// 活动赠送金额池仓储（t_courses_activity_user_discount / _user_discount_log / _used_log）——AC-06。
//
// 依据：unified/03-migration/academic-domain-design.md §3.2 #14~#19（赠送金额池 4 SP）/ §1.5（金额）
// / §1.7（scoping）。
//
// 覆盖 SP 映射：
//
//	user_discount_usable          → SumUsable（dump 3 参汇总口径：schoolid + campusid + userid；
//	                                campusid 条件**嵌在 schoolid 分支内**且恒为等值）
//	user_discount_use             → ListUsable(ASC) + IncUsed/IncUsedBatch + InsertDiscountLog(负值)
//	user_discount_refund          → ListUsable(DESC) + IncUsed(负 delta) + InsertDiscountLog(正值)
//	user_discount_refund_user_activity → ListUsable(DESC)（同活动池优先退回）
//	use_activity_recommend        → IncUsed + InsertUsedLog（老带新结算写负值）
//
// 金额口径（红线）：库里 discount_amount / discount_amount_used 是 decimal(12,2) **字符串列**，
// Go 侧一律转 money.Amount（int64 分）再运算；SQL 侧只用字符串字面量做加减（decimal 精确），
// **绝不**把金额转 float64（sqlite 的 SUM() 返回 REAL，会让分位失真——见 SumUsable 实现说明）。
package repository

import (
	"context"
	"errors"
	"strings"

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

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

// UsedDelta 批量累加「已使用赠送金额」的单元素（id + 增量）。
//
// 字段：
//   - DiscountID int64：优惠账户 ID（t_courses_activity_user_discount.id；<=0 的条目被跳过）。
//   - Delta money.Amount：discount_amount_used 的增量（正=消费/占用，负=退回冲正；单位：分）。
type UsedDelta struct {
	// DiscountID 优惠账户 ID（DB 自增主键）。
	DiscountID int64
	// Delta 已使用金额增量（正=消费，负=退回；单位：分）。
	Delta money.Amount
}

// ActivityDiscountRepo 活动赠送金额池仓储。
//
// 表：
//   - t_courses_activity_user_discount（池：可用 = discount_amount − discount_amount_used）；
//   - t_courses_activity_user_discount_log（使用/退回流水，只增，负=消费/正=退回）；
//   - t_courses_activity_used_log（老带新获得/使用记录，结算写负值）。
//
// 作用域：三表均带 institution_id + campus_id（campus_id=0 = 机构所有自营校区）→ scopedCampusRows。
type ActivityDiscountRepo struct {
	*BaseRepo
}

// NewActivityDiscountRepo 构造赠送金额池仓储。
//
// 入参：db *gorm.DB / sc *appscope.Scope（语义同 NewActivityRepo）。
// 出参：*ActivityDiscountRepo（CampusScoped=false，校区维度走 IN (campus,0) 超集语义）。
func NewActivityDiscountRepo(db *gorm.DB, sc *appscope.Scope) *ActivityDiscountRepo {
	r := &ActivityDiscountRepo{BaseRepo: NewBaseRepo(db, sc)}
	r.CampusScoped = false
	return r
}

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

// ListUsable 列出用户可用赠送金额池（**活动维度**，dump `yuansiwei_finance.sql:763216`）。
//
// 入参：
//   - ctx 请求上下文；
//   - userID 学生（canonical_user_id ULID；空 → ErrBadParam）；
//   - activityID 活动 ID（**>0 时只取该活动的赠送池**，对齐 dump `WHERE userid=? AND activityid=?`；
//     **0 = 不限活动**，仅"汇总所有活动可用额"的场景使用——扣减路径必须传具体 activityID，
//     否则会把 A 活动的消费扣到 B 活动的池上）；
//   - order 游标方向（**顺序不可改**，源自 dump）：
//     OrderAsc  = user_discount_use 使用顺序（先入先出）；
//     OrderDesc = user_discount_refund 退回顺序（后入先退）。
//
// 出参：
//   - []model.CoursesActivityUserDiscount：可用行（`discount_amount > discount_amount_used`），
//     金额为字符串原文，调用方用 money.Parse 转 Amount；
//   - ErrBadParam / ErrDBError。
//
// 可用口径（dump user_discount_usable 一致）：仅累加 discount_amount > discount_amount_used 的行
// （负赠送/已用尽的行不参与），故本方法只返回正可用行。
func (r *ActivityDiscountRepo) ListUsable(ctx context.Context, userID string, activityID int64, order string) ([]model.CoursesActivityUserDiscount, error) {
	if strings.TrimSpace(userID) == "" {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: ListUsable 需要 user_id"))
	}
	if activityID < 0 {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: ListUsable activity_id 不得为负"))
	}
	dir, err := normalizeOrder(order)
	if err != nil {
		return nil, err
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	q := scopedCampusRows(db.Model(&model.CoursesActivityUserDiscount{}), r.Sc, "")
	q = q.Where("user_id = ?", userID).
		Where("discount_amount > discount_amount_used")
	if activityID > 0 {
		q = q.Where("activity_id = ?", activityID)
	}
	// dump 的 usable 无显式 ORDER BY；InnoDB 等值/主键扫描等价于主键升序，故 asc 口径与 dump 一致
	q = q.Order("id " + dir)
	var rows []model.CoursesActivityUserDiscount
	if err := q.Find(&rows).Error; err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return rows, nil
}

// SumUsable 汇总用户可用赠送金额（**对齐 dump `usable` 的 3 参口径**：机构 + 校区 + 用户）。
//
// 入参：
//   - ctx 请求上下文；
//   - userID 学生（ULID；空 → ErrBadParam）；
//   - institutionID 机构 ID（原 schoolid；**>0 = 机构+校区两个等值条件一起生效**；
//     **<=0 = 平台视角：一条作用域条件都不加**，此时 campusID 被忽略）；
//   - campusID 校区 ID（原 campusid；**仅在 institutionID>0 时生效**，且为**等值**——
//     `campusID=0` 命中"机构级池"（campus_id=0 的行），**不是**"不限校区"）；
//     不得为负（→ ErrBadParam）。
//
// 出参：
//   - money.Amount：可用额度合计（单位：分；无可用行为 0）；
//   - ErrBadParam / ErrDBError。
//
// 作用域（audit A7 二次修正，dump `yuansiwei_finance.sql:763181-763185` **逐字**）：
//
//	IF inputSchoolid>0 THEN
//	  SET selectCondition = CONCAT(" AND `schoolid`=",schoolid," AND `campusid`=",campusid);
//	ELSE
//	  SET selectCondition = '';
//	END IF;
//
//	→ 两条条件**都是等值**，且 campusid 条件**嵌套在 schoolid 分支内部**（不在外面）：
//	- `institutionID > 0` → `institution_id = ? AND campus_id = ?`（**恒一起写**；此分支内
//	  `campusID=0` 是"机构级池"这个**具体取值**，不是"不筛"——绝不能省略 campus 条件，
//	  否则会把全校区池一起加进来，可用额虚高）；
//	- `institutionID<=0` → `selectCondition = ''` → **一条作用域条件都不写**，
//	  传入的 `campusID` 一律**忽略**（dump 里 campusid 只出现在 school 分支内，
//	  不存在"只按校区筛"的路径）。
//	越权防线**不在本方法**：按裁定移到 Handler 角色白名单（平台视角只对 super_admin/academic 开放）。
//
// 实现说明（金额精度）：**不用 SQL SUM()**。sqlite 把 decimal 存 NUMERIC 时 SUM 返回 REAL，
// 会把分位带进浮点；MySQL 返回 DECIMAL(字符串) 虽精确，但两库行为不一致。
// 因此这里只让 DB 做过滤，**逐行在 Go 侧用 money.Amount（int64 分）累加**（用户池行数极小，
// 性能可忽略），换取"零浮点"的确定性。
func (r *ActivityDiscountRepo) SumUsable(ctx context.Context, userID string, institutionID, campusID int64) (money.Amount, error) {
	if strings.TrimSpace(userID) == "" {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: SumUsable 需要 user_id"))
	}
	if institutionID < 0 || campusID < 0 {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: SumUsable 机构/校区参数不得为负（0 的语义见方法注释：平台视角 / 机构级池）"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return 0, err
	}
	q := db.Model(&model.CoursesActivityUserDiscount{}).
		Where("user_id = ?", userID).
		Where("discount_amount > discount_amount_used")
	// dump 763181-763185：两条作用域条件**都是等值**，且 campus 条件**嵌套在 school 分支内**——
	// 故只在 institutionID>0 时把两个条件一起写（campusID=0 → 只命中 campus_id=0 的机构级池）；
	// institutionID<=0 → 不写任何作用域条件，campusID 被忽略。
	if institutionID > 0 {
		q = q.Where("institution_id = ? AND campus_id = ?", institutionID, campusID)
	}
	var rows []model.CoursesActivityUserDiscount
	if err := q.Find(&rows).Error; err != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	total := money.Amount(0)
	for i := range rows {
		totalAmount, perr := money.Parse(rows[i].DiscountAmount)
		if perr != nil {
			return 0, infraerrors.WithCause(infraerrors.ErrDBError, perr)
		}
		usedAmount, perr := money.Parse(rows[i].DiscountAmountUsed)
		if perr != nil {
			return 0, infraerrors.WithCause(infraerrors.ErrDBError, perr)
		}
		total = total.Add(totalAmount.Sub(usedAmount))
	}
	return total, nil
}

// ListDiscountLogsByStudentCourse 按报课记录取**赠送金额退回对象**（audit A11，dump `:763057`）。
//
// 入参：
//   - ctx 请求上下文；
//   - coursesStudentID 报课记录 ID（t_courses_student.id；<=0 → ErrBadParam）。
//
// 出参：
//   - []model.CoursesActivityUserDiscountLog：该报课记录产生的**负值流水**（消费行，`discount_amount_used < 0`），
//     按 id **降序**（最近使用优先，dump 退回路径固定顺序）；空结果返回非 nil 切片；
//   - ErrBadParam / ErrDBError。
//
// SQL（dump 763057 原文口径 + 多租户作用域 JOIN）：
//
//	SELECT dlog.* FROM t_courses_activity_user_discount_log dlog
//	  JOIN t_courses_activity_user_discount pool ON pool.id = dlog.activity_user_discount_id
//	 WHERE dlog.courses_student_id = ? AND dlog.discount_amount_used < 0
//	   AND pool.institution_id = ? AND pool.campus_id IN (?, 0)   -- 作用域（普通角色）
//	 ORDER BY dlog.id DESC
//
// 为什么只取负值行：退回时要按"当初扣了多少"逐笔等额回冲，正值行是退回动作本身（不能拿来回冲）；
// 排序固定 DESC（dump 无参数化方向）——**本方法不接受方向参数**，从根上消除 ORDER BY 注入面。
//
// 与旧 `ListSignedByStudentCourse` 的区别（audit A11）：那条路径（signed ← pool ← log 三表 join）
// **在 dump 中没有任何对应 SP 依据**，已删除；退回对象一律以本方法为准（流水是唯一事实来源）。
func (r *ActivityDiscountRepo) ListDiscountLogsByStudentCourse(ctx context.Context, coursesStudentID int64) ([]model.CoursesActivityUserDiscountLog, error) {
	if coursesStudentID <= 0 {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: ListDiscountLogsByStudentCourse 需要 courses_student_id"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	rows := make([]model.CoursesActivityUserDiscountLog, 0, 8)
	// 流水表**自身无作用域列**（DDL：id/discount/pool_id/courses_student_id/…，无 institution_id），
	// 故作用域从"流水 → 池"JOIN 取得（池有 institution_id + campus_id），语义与活动域一致（campus 超集）。
	q := db.Table("t_courses_activity_user_discount_log AS dlog").
		Select("dlog.*").
		Joins("JOIN t_courses_activity_user_discount AS pool ON pool.id = dlog.activity_user_discount_id").
		Where("dlog.courses_student_id = ?", coursesStudentID).
		Where("dlog.discount_amount_used < 0")
	q = scopedCampusRows(q, r.Sc, "pool")
	if err := q.Order("dlog.id DESC").Find(&rows).Error; err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	if rows == nil {
		rows = make([]model.CoursesActivityUserDiscountLog, 0)
	}
	return rows, nil
}

// IncUsed 累加优惠账户的「已使用赠送金额」（单账户原子增减）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - id 优惠账户 ID（<=0 → ErrBadParam）；
//   - delta 增量（正=消费，负=退回冲正；单位：分；0 → 空操作）。
//
// 出参：
//   - int64：受影响行数（0 = 账户不存在/不在作用域内）；
//   - ErrBadParam / ErrDBError。
//
// 红线：
//   - `discount_amount_used <= discount_amount` 的业务约束由 **Service** 在扣减前用可用额校验
//     （不足 → 3109），本方法**不做截断**——静默截断会破坏"池余额 = 流水累计"的对账恒等式；
//   - 与流水写入（InsertDiscountLog）必须同事务。
func (r *ActivityDiscountRepo) IncUsed(ctx context.Context, tx *gorm.DB, id int64, delta money.Amount) (int64, error) {
	if err := requireTx(tx, "IncUsed"); err != nil {
		return 0, err
	}
	if id <= 0 {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: IncUsed 需要 discount id"))
	}
	if delta.IsZero() {
		return 0, nil
	}
	if err := delta.Validate(); err != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, err)
	}
	q := scopedCampusRows(tx.Model(&model.CoursesActivityUserDiscount{}), r.Sc, "")
	res := q.Where("id = ?", id).
		UpdateColumn("discount_amount_used", gorm.Expr("discount_amount_used + ?", delta.String()))
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// IncUsedBatch 批量累加多个优惠账户的「已使用赠送金额」（**单语句 CASE WHEN**，禁止逐行 UPDATE）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - items 增量集合（同一 id 出现多次时**后者覆盖前者**；<=0 的 id 与零增量条目被忽略）。
//
// 出参：
//   - int64：受影响行数；
//   - ErrBadParam / ErrDBError（空集合 → 0, nil，不发 SQL）。
//
// 为什么必须单语句（性能/正确性双约束）：
//   - 一次跨多个池扣减若逐行 UPDATE，N 个账户 = N 次往返 + N 个独立执行计划；
//   - 单语句在事务内原子生效，减少锁持有时间（并发退费场景）。
//
// SQL：
//
//	UPDATE t_courses_activity_user_discount
//	   SET discount_amount_used = discount_amount_used + CASE id WHEN ? THEN ? ... ELSE 0 END
//	 WHERE id IN (...) [AND institution_id = ? AND campus_id IN (?,0)]
//
// 红线：金额以**字符串**字面量入场（decimal 精确），禁止 float。
func (r *ActivityDiscountRepo) IncUsedBatch(ctx context.Context, tx *gorm.DB, items []UsedDelta) (int64, error) {
	if err := requireTx(tx, "IncUsedBatch"); err != nil {
		return 0, err
	}
	// 归一：去重（后者覆盖）+ 过滤非法 id/零增量，保持入参顺序（CASE 分支顺序可预期，便于断言）
	order := make([]int64, 0, len(items))
	deltaByID := make(map[int64]money.Amount, len(items))
	for _, it := range items {
		if it.DiscountID <= 0 || it.Delta.IsZero() {
			continue
		}
		if err := it.Delta.Validate(); err != nil {
			return 0, infraerrors.WithCause(infraerrors.ErrBadParam, err)
		}
		if _, ok := deltaByID[it.DiscountID]; !ok {
			order = append(order, it.DiscountID)
		}
		deltaByID[it.DiscountID] = it.Delta
	}
	if len(order) == 0 {
		return 0, nil
	}

	var sqlText strings.Builder
	sqlText.WriteString("discount_amount_used + CASE id")
	caseArgs := make([]any, 0, len(order)*2)
	for _, id := range order {
		sqlText.WriteString(" WHEN ? THEN ?")
		caseArgs = append(caseArgs, id, deltaByID[id].String())
	}
	sqlText.WriteString(" ELSE 0 END")

	q := scopedCampusRows(tx.Model(&model.CoursesActivityUserDiscount{}), r.Sc, "")
	res := q.Where("id IN ?", order).UpdateColumn("discount_amount_used", gorm.Expr(sqlText.String(), caseArgs...))
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// InsertDiscountLog 写入赠送金额使用/退回流水（**只增**）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - row 流水行（ActivityUserDiscountID>0；DiscountAmountUsed 负=消费/正=退回）。
//
// 出参：nil 成功；ErrBadParam / ErrDBError。
//
// 红线：流水与池余额变动（IncUsed）必须同事务；流水禁止 UPDATE/DELETE（审计底线）。
func (r *ActivityDiscountRepo) InsertDiscountLog(ctx context.Context, tx *gorm.DB, row *model.CoursesActivityUserDiscountLog) error {
	if err := requireTx(tx, "InsertDiscountLog"); err != nil {
		return err
	}
	if row == nil {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: discount log 为 nil"))
	}
	if row.ActivityUserDiscountID <= 0 {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: discount log 缺少 activity_user_discount_id"))
	}
	if err := tx.WithContext(ctxOrBackground(ctx)).Create(row).Error; err != nil {
		return infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return nil
}

// ---------------------------------------------------------------- AC-07 原语

// ExistsUsedLog 判断用户在某活动上是否已有「老带新/充值赠送」记录（dump `signed_cancel` 762994 → **3108**）。
//
// SQL（dump 原文）：
//
//	SELECT (SELECT id FROM t_courses_activity_used_log WHERE activityid=? AND userid=?) INTO logid;
//	-- IF logid > 0 THEN LEAVE（不可取消）
//
// 语义：**判存在性**（不看金额正负、不看 order_no）——只要产生过消费/结算记录，
// 老带新报名就永久不可撤销（奖励已发出）。
//
// 入参：ctx / activityID（<=0 → ErrBadParam）/ userID（空 → ErrBadParam）。
// 出参：(是否存在, error)；ErrBadParam / ErrDBError。
func (r *ActivityDiscountRepo) ExistsUsedLog(ctx context.Context, activityID int64, userID string) (bool, error) {
	if activityID <= 0 || strings.TrimSpace(userID) == "" {
		return false, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: ExistsUsedLog 需要 activity_id>0 且 user_id"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return false, err
	}
	var count int64
	if err := db.Model(&model.CoursesActivityUsedLog{}).
		Where("activity_id = ? AND user_id = ?", activityID, userID).
		Count(&count).Error; err != nil {
		return false, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return count > 0, nil
}

// GetUsedLog 取用户在某活动上的老带新/赠送记录（幂等回读用）。
//
// 与 `ExistsUsedLog` 的区别：本方法返回**整行**（含 id / activity_money_used / recommend_user_id），
// 供幂等命中分支"从库回读"（§5.1 纪律 5：replay 不得复用首执行的中间变量）。
//
// 入参：ctx / activityID（<=0 → ErrBadParam）/ userID（空 → ErrBadParam）。
// 出参：(*model.CoursesActivityUsedLog, nil) 命中；(**nil**, nil) 无记录；ErrBadParam / ErrDBError。
func (r *ActivityDiscountRepo) GetUsedLog(
	ctx context.Context, activityID int64, userID string,
) (*model.CoursesActivityUsedLog, error) {
	if activityID <= 0 || strings.TrimSpace(userID) == "" {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: GetUsedLog 需要 activity_id>0 且 user_id"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	var out model.CoursesActivityUsedLog
	if err := db.Model(&model.CoursesActivityUsedLog{}).
		Where("activity_id = ? AND user_id = ?", activityID, userID).
		Order("id ASC").
		Take(&out).Error; err != nil {
		if errors.Is(err, gorm.ErrRecordNotFound) {
			return nil, nil
		}
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return &out, nil
}

// ListUsedLogsByOrder 取某报课单产生的**消费方向**（负值）活动金额流水（dump 762854 游标）。
//
// SQL（dump 原文）：
//
//	SELECT activityid,userid,activity_money_used FROM t_courses_activity_used_log
//	 WHERE orderid = ? AND activity_money_used < 0 ORDER BY id DESC;
//
// 入参：
//   - ctx 请求上下文；
//   - orderNo 报课单号（t_courses_student.id 的字符串形式；空 → ErrBadParam）；
//   - order 方向（OrderAsc/OrderDesc；**退回路径必须 DESC**，非法值 → 2002）。
//
// 出参：[]model.CoursesActivityUsedLog（空 → 非 nil 切片）；ErrBadParam / ErrDBError。
//
// 为什么只取负值行：正值行是**退回动作本身**（不能拿来回冲，否则同一笔可退两次）。
func (r *ActivityDiscountRepo) ListUsedLogsByOrder(
	ctx context.Context, orderNo string, order string,
) ([]model.CoursesActivityUsedLog, error) {
	if strings.TrimSpace(orderNo) == "" {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: ListUsedLogsByOrder 需要 order_no"))
	}
	dir, err := normalizeOrder(order)
	if err != nil {
		return nil, err
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	rows := make([]model.CoursesActivityUsedLog, 0, 8)
	q := db.Model(&model.CoursesActivityUsedLog{}).
		Where("order_no = ?", orderNo).
		Where("activity_money_used < 0").
		Order("id " + dir)
	if err := q.Find(&rows).Error; err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return rows, nil
}

// DiscountLogWithPool 最近一条赠送流水 + 其所属池行（dump `refund_user_activity` 游标的展开，763122）。
//
// 字段：
//   - PoolID 池行 ID（更新目标）；
//   - LogAmountUsed 流水金额原文（负=消费）；
//   - CoursesStudentID 该流水关联的报课记录（退回时原样带回）；
//   - DiscountAmount 池面额原文（type=3 代金券"一次全退"的取值来源）；
//   - DiscountAmountUsed 池已用原文。
type DiscountLogWithPool struct {
	// PoolID 优惠账户 ID。
	PoolID int64 `gorm:"column:pool_id"`
	// LogAmountUsed 流水金额（元字符串，负值）。
	LogAmountUsed string `gorm:"column:log_amount_used"`
	// CoursesStudentID 报课记录 ID（可为 NULL）。
	CoursesStudentID *int64 `gorm:"column:courses_student_id"`
	// DiscountAmount 池赠送面额（元字符串）。
	DiscountAmount string `gorm:"column:discount_amount"`
	// DiscountAmountUsed 池已使用（元字符串）。
	DiscountAmountUsed string `gorm:"column:discount_amount_used"`
}

// GetLastDiscountLogByUserActivity 取用户在**某活动**上最近一条消费流水（dump 763122 `LIMIT 0,1`）。
//
// SQL（dump 原文）：
//
//	SELECT t1.activity_user_discountid, t1.discount_amount_used, t1.courses_studentid,
//	       t2.discount_amount, t2.discount_amount_used
//	  FROM t_courses_activity_user_discount_log t1
//	  LEFT JOIN t_courses_activity_user_discount t2 ON t1.activity_user_discountid = t2.id
//	 WHERE t2.userid = ? AND t2.activityid = ? AND t1.discount_amount_used < 0
//	 ORDER BY t1.id DESC LIMIT 0,1;
//
// 语义：`refund_user_activity` **只处理最近一条**（dump 的 LIMIT 1）——多张券时不会一次退完。
//
// 入参：ctx / userID（空 → ErrBadParam）/ activityID（<=0 → ErrBadParam）。
// 出参：(*DiscountLogWithPool, nil) 命中；(**nil**, nil) 无消费流水（dump 游标空 → no-op）；
// ErrBadParam / ErrDBError。
func (r *ActivityDiscountRepo) GetLastDiscountLogByUserActivity(
	ctx context.Context, userID string, activityID int64,
) (*DiscountLogWithPool, error) {
	if strings.TrimSpace(userID) == "" || activityID <= 0 {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: GetLastDiscountLogByUserActivity 需要 user_id 且 activity_id>0"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	var out DiscountLogWithPool
	q := db.Table("t_courses_activity_user_discount_log AS dlog").
		Select("dlog.activity_user_discount_id AS pool_id, dlog.discount_amount_used AS log_amount_used, "+
			"dlog.courses_student_id, pool.discount_amount, pool.discount_amount_used").
		Joins("JOIN t_courses_activity_user_discount AS pool ON pool.id = dlog.activity_user_discount_id").
		Where("pool.user_id = ? AND pool.activity_id = ?", userID, activityID).
		Where("dlog.discount_amount_used < 0").
		Order("dlog.id DESC").
		Limit(1)
	if err := q.Take(&out).Error; err != nil {
		if errors.Is(err, gorm.ErrRecordNotFound) {
			return nil, nil // dump：游标无行 → 整个 SP no-op（不是错误）
		}
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return &out, nil
}

// ListUsableForUpdate 同 `ListUsable`，但对取出的池行加**行锁**（赠送金额扣减前必调）。
//
// 为什么需要独立方法而不是给 ListUsable 加锁：`ListUsable` 也被只读汇总路径使用（不该加锁）。
// 加锁语义：先 SELECT ... FOR UPDATE 固定候选行的已用额，再据可用额判定 3109，
// 避免"两笔并发使用同一张券 → used 超过 face"的超用（dump 无锁，属 Go 增强）。
//
// 入参：ctx / tx（**必传**）/ userID / activityID（**>0**，扣减必须单活动）/ order。
// 出参：[]model.CoursesActivityUserDiscount（可用行，id 方向由 order 决定）；ErrBadParam / ErrDBError。
func (r *ActivityDiscountRepo) ListUsableForUpdate(
	ctx context.Context, tx *gorm.DB, userID string, activityID int64, order string,
) ([]model.CoursesActivityUserDiscount, error) {
	if err := requireTx(tx, "ListUsableForUpdate"); err != nil {
		return nil, err
	}
	if strings.TrimSpace(userID) == "" || activityID <= 0 {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: ListUsableForUpdate 需要 user_id 且 activity_id>0"))
	}
	dir, err := normalizeOrder(order)
	if err != nil {
		return nil, err
	}
	rows := make([]model.CoursesActivityUserDiscount, 0, 8)
	q := scopedCampusRows(tx.WithContext(ctxOrBackground(ctx)).Model(&model.CoursesActivityUserDiscount{}), r.Sc, "")
	q = q.Where("user_id = ? AND activity_id = ?", userID, activityID).
		Where("discount_amount > discount_amount_used").
		Order("id " + dir).
		Clauses(clause.Locking{Strength: clause.LockingStrengthUpdate})
	if err := q.Find(&rows).Error; err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return rows, nil
}

// GetDiscountForUpdate 按主键取池行并加行锁（退回路径更新前必调）。
//
// 入参：ctx / tx（必传）/ id（<=0 → ErrBadParam）。
// 出参：*model.CoursesActivityUserDiscount；ErrNotFound / ErrBadParam / ErrDBError。
func (r *ActivityDiscountRepo) GetDiscountForUpdate(
	ctx context.Context, tx *gorm.DB, id int64,
) (*model.CoursesActivityUserDiscount, error) {
	if err := requireTx(tx, "GetDiscountForUpdate"); err != nil {
		return nil, err
	}
	if id <= 0 {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: GetDiscountForUpdate 需要 id>0"))
	}
	var out model.CoursesActivityUserDiscount
	q := scopedCampusRows(tx.WithContext(ctxOrBackground(ctx)).Model(&model.CoursesActivityUserDiscount{}), r.Sc, "")
	if err := q.Clauses(clause.Locking{Strength: clause.LockingStrengthUpdate}).
		Where("id = ?", id).Take(&out).Error; err != nil {
		return nil, wrapQueryErr(err, "GetDiscountForUpdate(t_courses_activity_user_discount)")
	}
	return &out, nil
}

// InsertUsedLog 写入老带新活动金额获得/使用记录（**只增**）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - row 记录行（ActivityID>0、UserID 非空；老带新结算写**负值** activity_money_used）。
//
// 出参：nil 成功；ErrBadParam / ErrDBError。
//
// 红线：符号方向固定（结算负值）；撤销报名前置校验按 (activity_id, user_id) 判存在（3108），
// 故本表写入必须与 signed 状态推进同事务。
func (r *ActivityDiscountRepo) InsertUsedLog(ctx context.Context, tx *gorm.DB, row *model.CoursesActivityUsedLog) error {
	if err := requireTx(tx, "InsertUsedLog"); err != nil {
		return err
	}
	if row == nil {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: used log 为 nil"))
	}
	if row.ActivityID <= 0 || strings.TrimSpace(row.UserID) == "" {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: used log 缺少 activity_id/user_id"))
	}
	if err := tx.WithContext(ctxOrBackground(ctx)).Create(row).Error; err != nil {
		return infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return nil
}