DEV-MERGE-LEGACY-BACKEND-2026/internal/academic/repository/balance_request_repo.go

// 余额变更工单仓储（t_user_balance_request）——AC-03 资金工单（充值/退费/坏账/取消活动/转结）。
//
// 依据：unified/03-migration/academic-domain-design.md §2「4. t_user_balance_request」/ §3（审批驱动）
// / §10.3（事务边界只在 Service）。
//
// 工单是**资金变动唯一入口**：`approved` 由 0（未处理）→ 终态的审批动作才触发余额变动；
// 因此本仓储的三个写方法都是"资金事务的参与者"，一律接收调用方 tx（本文件不开事务）。
//
// 并发防线：
//   - `UpdateApproved` 是 **CAS**（`WHERE approved = 0`）——重复审批/双人同时点通过时，
//     第二次 affected=0，Service 据此返回幂等结果而不是重复入账；
//   - `GetForUpdate` 提供 `SELECT ... FOR UPDATE` 加锁读（审批前读旧值/校验金额用）。
//
// 作用域：表带 institution_id + campus_id（作用域列）→ 继承 BaseRepo，普通角色强制本机构。
package repository

import (
	"context"
	"strings"
	"time"

	"gorm.io/gorm"
	"gorm.io/gorm/clause"

	"yuansiwei/unified-backend/internal/academic/model"
	infraerrors "yuansiwei/unified-backend/internal/infra/errors"
	appscope "yuansiwei/unified-backend/internal/infra/scope"
)

// ErrDuplicateBizNo 工单业务单号重复哨兵（撞 uk_biz_no）——属幂等命中，不是 5002。
//
// 判定方式：`stderrors.Is(err, repository.ErrDuplicateBizNo)`。
var ErrDuplicateBizNo = infraerrors.New(infraerrors.CodeUnique, "重复的业务单号（biz_no 已存在）")

// BalanceRequestRepo 余额变更工单仓储（多租户表，继承 BaseRepo 强制机构作用域）。
type BalanceRequestRepo struct {
	*BaseRepo
}

// NewBalanceRequestRepo 构造工单仓储。
//
// 入参：db *gorm.DB（连接池句柄）/ sc *appscope.Scope（请求作用域；系统任务可 nil，一查询即 panic）。
// 出参：*BalanceRequestRepo（CampusScoped=true：表带 campus_id）。
func NewBalanceRequestRepo(db *gorm.DB, sc *appscope.Scope) *BalanceRequestRepo {
	r := &BalanceRequestRepo{BaseRepo: NewBaseRepo(db, sc)}
	r.CampusScoped = true
	return r
}

// db 取查询句柄（ctx 内含 tx 时复用同一事务）。
func (r *BalanceRequestRepo) db(ctx context.Context) (*gorm.DB, error) {
	if r == nil || r.DB == nil {
		return nil, infraerrors.WithCause(infraerrors.ErrInternal, errString("repository: BalanceRequestRepo.DB 为 nil"))
	}
	if tx := TxFromContext(ctx); tx != nil {
		return tx, nil
	}
	if ctx == nil {
		return r.DB, nil
	}
	return r.DB.WithContext(ctx), nil
}

// GetForUpdate 按主键取工单并加行锁（审批前读旧值）。
//
// 入参：ctx 请求上下文；tx 事务句柄（**必传**）；id 工单 ID（<=0 → ErrBadParam）。
// 出参：*model.UserBalanceRequest + ErrNotFound（不存在或跨机构）/ ErrBadParam / ErrDBError。
//
// SQL：`SELECT * FROM t_user_balance_request WHERE id=? [AND institution_id=?] LIMIT 1 FOR UPDATE`。
func (r *BalanceRequestRepo) GetForUpdate(ctx context.Context, tx *gorm.DB, id int64) (*model.UserBalanceRequest, error) {
	if err := requireTx(tx, "GetForUpdate(t_user_balance_request)"); err != nil {
		return nil, err
	}
	if id <= 0 {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: balance request id 必须 > 0"))
	}
	var out model.UserBalanceRequest
	q := r.Scoped(tx.WithContext(ctxOrBackground(ctx)))
	err := q.Clauses(clause.Locking{Strength: clause.LockingStrengthUpdate}).
		Where("id = ?", id).Take(&out).Error
	if err != nil {
		return nil, wrapQueryErr(err, "GetForUpdate(t_user_balance_request)")
	}
	return &out, nil
}

// Insert 创建工单（幂等键 biz_no）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - row 工单行（BizNo 非空、Type != 0、UserID 非空；InstitutionID=0 时用作用域补齐）。
//
// 出参：
//   - nil 成功；
//   - ErrDuplicateBizNo（biz_no 已存在 → 幂等命中）；
//   - ErrBadParam / ErrUnscoped / ErrDBError。
//
// 红线：`approved` 一律由 DB 默认 0（未处理）落库，**禁止**创建即通过（资金变动必须走审批链）。
func (r *BalanceRequestRepo) Insert(ctx context.Context, tx *gorm.DB, row *model.UserBalanceRequest) error {
	if err := requireTx(tx, "Insert(t_user_balance_request)"); err != nil {
		return err
	}
	if row == nil {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: balance request 为 nil"))
	}
	if strings.TrimSpace(row.BizNo) == "" || strings.TrimSpace(row.UserID) == "" || row.Type == 0 {
		return infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: balance request 需要 biz_no/user_id/type"))
	}
	if row.InstitutionID == 0 {
		inst, campus := r.GetScopedID()
		if inst <= 0 {
			return infraerrors.WithCause(infraerrors.ErrUnscoped,
				errString("repository: balance request 缺少 institution_id 且作用域无机构"))
		}
		row.InstitutionID = inst
		row.CampusID = campus
	}
	if err := normalizeExpenseAmounts(&row.Money); err != nil {
		return err
	}
	// approved 由调用方显式置 0（零值即未处理），此处不做覆盖以便"迁移搬入历史终态工单"
	err := tx.WithContext(ctxOrBackground(ctx)).Create(row).Error
	if err != nil {
		if IsDupKey(err) {
			return infraerrors.WithCause(ErrDuplicateBizNo, err)
		}
		return infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return nil
}

// UpdateApproved 审批状态 CAS 推进（`WHERE approved = 0`，0→终态唯一入口）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**：资金变动 + 工单回写必须同事务）；
//   - id 工单 ID（<=0 → ErrBadParam）；
//   - to 目标状态（model.BalanceRequestApproved*：-2 取消 / -1 不通过 / 1 已通过）；
//   - responseUserID 审批人（ULID；nil = 系统自动审批，落 NULL）；
//   - responseTime 审批时间（nil = 不写，由调用方决定；资金口径要求非 nil 见 Service 校验）。
//
// 出参：
//   - int64：受影响行数（**1=本次抢到审批权**；0=已被处理过/不存在/跨机构 → Service 做幂等返回）；
//   - ErrBadParam / ErrDBError。
//
// SQL（单语句 CAS）：`UPDATE t_user_balance_request SET approved=?, response_user_id=?, response_time=?
// WHERE id=? AND approved=0 [AND institution_id=?]`。
//
// 红线：CAS 的 `approved = 0` 条件**不可省**（否则双人同时点"通过"会重复入账）；
// 金额/类型**不允许**在本方法内变更（改金额须新建工单）。
func (r *BalanceRequestRepo) UpdateApproved(ctx context.Context, tx *gorm.DB, id int64, to int8,
	responseUserID *string, responseTime *time.Time) (int64, error) {
	if err := requireTx(tx, "UpdateApproved"); err != nil {
		return 0, err
	}
	if id <= 0 {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: UpdateApproved 需要 id"))
	}
	switch to {
	case model.BalanceRequestApprovedCancelled, model.BalanceRequestApprovedRejected,
		model.BalanceRequestApprovedPassed:
	default:
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: UpdateApproved 目标状态非法（只允许 -2/-1/1）"))
	}
	updates := map[string]any{
		"approved":         to,
		"response_user_id": responseUserID, // nil → 写 NULL
	}
	if responseTime != nil {
		updates["response_time"] = *responseTime
	}
	q := r.Scoped(tx.WithContext(ctxOrBackground(ctx)).Model(&model.UserBalanceRequest{}))
	res := q.Where("id = ? AND approved = ?", id, model.BalanceRequestApprovedPending).
		Updates(updates)
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// ListByUser 分页列出某用户的工单（按 id 倒序，最新在前）。
//
// 入参：
//   - ctx 请求上下文；
//   - userID 用户（ULID；空 → ErrBadParam）；
//   - page 分页（PageQuery；内部 ClampPage：pageSize ∈ [1,200]）。
//
// 出参：
//   - []model.UserBalanceRequest：**空结果返回长度 0 的非 nil 切片**；
//   - ErrBadParam / ErrDBError。
//
// 作用域：经 Scoped（普通角色只见本机构工单；超管全量）。
func (r *BalanceRequestRepo) ListByUser(ctx context.Context, userID string, page PageQuery) ([]model.UserBalanceRequest, error) {
	if strings.TrimSpace(userID) == "" {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: ListByUser 需要 user_id"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	pageSize := page.Limit()
	rows := make([]model.UserBalanceRequest, 0, pageSize)
	q := r.Scoped(db.Model(&model.UserBalanceRequest{}))
	err = q.Where("user_id = ?", userID).
		Order("id DESC").Limit(pageSize).Offset(page.Offset()).
		Find(&rows).Error
	if err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	if rows == nil {
		rows = make([]model.UserBalanceRequest, 0)
	}
	return rows, nil
}