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

// 活动仓储（t_courses_activity / t_courses_activity_signed）——AC-06 活动报名主链路。
//
// 依据：unified/03-migration/academic-domain-design.md §3.2（活动 9 SP）/ §1.5（幂等语义演进）
// / §1.7（scoping 与两条例外）/ §10.3（事务边界只在 Service）。
//
// 覆盖 SP 映射：
//
//	signed_add        → UpsertSigned（DELETE+INSERT 幂等，对齐 dump）
//	signed_cancel     → UpdateSignedStatus + IncreaseNumberSign（服务层组合成状态机）
//	                    + CountSignedByUser(type4Only=false)（取消前置守卫）
//	sign 限一次(3106) → CountSignedByUser(type4Only=true)
//	退费回滚赠送金额   → ListDiscountLogsByStudentCourse（按**流水**定位，audit A11；旧 signed←pool←log
//	                    三表 join 的 ListSignedByStudentCourse 在 dump 中无依据，已删除）
//
// 作用域（关键设计，与 BaseRepo.Scoped 的差异必须读）：
//
//	t_courses_activity.campus_id = 0 的语义是「本机构所有**自营**校区」（DDL §2「7.」+ 设计 §11-2），
//	因此校园维度过滤**不能**用 `campus_id = ?`，否则全机构活动会被裁掉；
//	本仓储统一用 scopedCampusRows：`institution_id = ? AND campus_id IN (?, 0)`（超集语义）。
//	→ BaseRepo.CampusScoped 置 false（避免严格等值过滤），机构过滤仍由 scopedCampusRows 强制，
//	  安全红线（跨机构越权）不因这条例外而放松。
//
// 事务纪律：写方法一律接收 `tx *gorm.DB`（**仓储不开事务**）；读方法经 db(ctx) 取句柄，
// ctx 内已注入事务（WithTxContext）时自动复用同一 tx，保证事务内读一致。
package repository

import (
	"context"
	"errors"
	"fmt"
	"strings"

	"gorm.io/gorm"

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

// 游标方向常量（源自 dump 的固定排序，调用方只能二选一，禁止拼接其它 SQL 片段）。
//
// 语义（dump 口径，**顺序不可改**）：
//   - OrderAsc ：按 id 升序——"消费/使用"路径（先入先出，旧 SP 游标）；
//   - OrderDesc：按 id 降序——"退回/回滚"路径（后入先退，旧 SP 游标）。
//
// 安全红线：方向值来自本白名单，绝不接受调用方透传的原始字符串（防 ORDER BY 注入）。
const (
	// OrderAsc 升序（使用路径）。
	OrderAsc = "asc"
	// OrderDesc 降序（退回路径）。
	OrderDesc = "desc"
)

// normalizeOrder 校验并归一排序方向（白名单；空串按 OrderAsc 处理）。
//
// 入参：order string——调用方传入的方向（大小写/空白不敏感）。
// 出参：归一后的 "asc"/"desc"；非法值 → infraerrors.ErrBadParam（2002）。
func normalizeOrder(order string) (string, error) {
	switch strings.ToLower(strings.TrimSpace(order)) {
	case "", OrderAsc:
		return OrderAsc, nil
	case OrderDesc:
		return OrderDesc, nil
	default:
		return "", infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: 非法排序方向 "+order))
	}
}

// scopedCampusRows 追加作用域过滤（机构强制 + 校区"含全机构池"超集）。
//
// 入参：
//   - db *gorm.DB：基础查询（nil → 返回 nil）。
//   - sc *appscope.Scope：请求作用域（nil → panic fail-fast，与 BaseRepo.Scoped 同口径）。
//   - alias string：表别名前缀（如 "signed."）；JOIN 场景必须限定，否则 ambiguous column。
//
// 出参：*gorm.DB——追加过滤后的链式查询。
//
// 过滤规则：
//  1. sc.SuperAdmin=true → 不加任何过滤（平台超管跨机构视角）；
//  2. 否则强制 `alias.institution_id = sc.InstitutionID`（安全红线，不可绕过）；
//  3. 仅当 sc.CampusID > 0 时追加 `alias.campus_id IN (sc.CampusID, 0)`——
//     0=机构所有自营校区，属该校区可见范围（设计 §11-2）。
func scopedCampusRows(db *gorm.DB, sc *appscope.Scope, alias string) *gorm.DB {
	if db == nil {
		return nil
	}
	if sc == nil {
		panic(errNoScope.Error())
	}
	if sc.SuperAdmin {
		return db
	}
	col := func(name string) string {
		if alias == "" {
			return name
		}
		return alias + "." + name
	}
	db = db.Where(col("institution_id")+" = ?", sc.InstitutionID)
	if sc.CampusID > 0 {
		// campus_id=0 = 机构所有自营校区（超集语义，不能用等值）
		db = db.Where(col("campus_id")+" IN ?", []int64{sc.CampusID, 0})
	}
	return db
}

// requireTx 校验写方法必须携带事务句柄（仓储不开事务，设计 §10.3）。
//
// 入参：tx *gorm.DB（可 nil）。出参：nil 合法；ErrInternal 表示调用方漏传事务。
func requireTx(tx *gorm.DB, op string) error {
	if tx == nil {
		return infraerrors.WithCause(infraerrors.ErrInternal, errString("repository: "+op+" 必须传入 tx（禁止脱离事务写资金/状态）"))
	}
	return nil
}

// ActivityRepo 活动方案 + 报名仓储。
//
// 表：t_courses_activity（活动方案）/ t_courses_activity_signed（报名·UK(user_id, activity_id)）。
// 作用域：两表均带 institution_id + campus_id（冗余作用域列）→ 统一走 scopedCampusRows。
type ActivityRepo struct {
	*BaseRepo
}

// NewActivityRepo 构造活动仓储。
//
// 入参：db *gorm.DB（连接池句柄）/ sc *appscope.Scope（请求作用域；系统任务可 nil，一查询即 panic）。
// 出参：*ActivityRepo。
//
// 说明：CampusScoped 置 false —— 校区维度由 scopedCampusRows 以 `IN (campus,0)` 超集语义处理
// （见文件头「作用域」段），机构过滤不受影响。
func NewActivityRepo(db *gorm.DB, sc *appscope.Scope) *ActivityRepo {
	r := &ActivityRepo{BaseRepo: NewBaseRepo(db, sc)}
	r.CampusScoped = false
	return r
}

// db 取查询句柄（ctx 内含 tx 时复用同一事务，保证事务内读一致）。
//
// 入参：ctx context.Context（可 nil）。出参：(*gorm.DB, error)；未装配 DB → ErrInternal。
func (r *ActivityRepo) db(ctx context.Context) (*gorm.DB, error) {
	if r == nil || r.DB == nil {
		return nil, infraerrors.WithCause(infraerrors.ErrInternal, errString("repository: ActivityRepo.DB 为 nil"))
	}
	if tx := TxFromContext(ctx); tx != nil {
		return tx, nil
	}
	if ctx == nil {
		return r.DB, nil
	}
	return r.DB.WithContext(ctx), nil
}

// GetByID 按主键取单个活动（**作用域强制**：跨机构活动一律 ErrNotFound，不泄露存在性）。
//
// 入参：
//   - ctx 请求上下文（取消/超时传播）；
//   - id 活动 ID（<=0 → ErrBadParam，避免全表扫描）。
//
// 出参：
//   - *model.CoursesActivity：命中行（含 money 字符串原文，金额换算由 Service 用 money.Amount）；
//   - ErrNotFound（3001）：不存在或不在作用域内；
//   - ErrDBError（5002）：SQL/驱动异常（不返回 gorm 原错）。
func (r *ActivityRepo) GetByID(ctx context.Context, id int64) (*model.CoursesActivity, error) {
	if id <= 0 {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: activity id 必须 > 0"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	var out model.CoursesActivity
	q := scopedCampusRows(db.Model(&model.CoursesActivity{}), r.Sc, "")
	if err := q.Where("id = ?", id).First(&out).Error; err != nil {
		return nil, wrapQueryErr(err, "GetByID(t_courses_activity)")
	}
	return &out, nil
}

// GetByIDs 批量取活动（**防 N+1**：一次 IN 查询，返回 map 供调用方 O(1) 索引）。
//
// 入参：
//   - ctx 请求上下文；
//   - ids 活动 ID 集合（空/全非法 → 返回空 map 且**不发 SQL**）。
//
// 出参：
//   - map[int64]*model.CoursesActivity：命中行索引（**缺失的 id 不在 map 中**，调用方按需判缺失，
//     语义上等价"不在作用域内或不存在"，禁止据此区分存在性）；
//   - ErrDBError（5002）。
//
// 实现说明：入参先去重 + 剔除 <=0（防无意义扫描）；结果不保证顺序（map 语义）。
func (r *ActivityRepo) GetByIDs(ctx context.Context, ids []int64) (map[int64]*model.CoursesActivity, error) {
	out := make(map[int64]*model.CoursesActivity, len(ids))
	clean := make([]int64, 0, len(ids))
	seen := make(map[int64]struct{}, len(ids))
	for _, id := range ids {
		if id <= 0 {
			continue
		}
		if _, ok := seen[id]; ok {
			continue
		}
		seen[id] = struct{}{}
		clean = append(clean, id)
	}
	if len(clean) == 0 {
		return out, nil
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	var rows []model.CoursesActivity
	q := scopedCampusRows(db.Model(&model.CoursesActivity{}), r.Sc, "")
	if err := q.Where("id IN ?", clean).Find(&rows).Error; err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	for i := range rows {
		out[rows[i].ID] = &rows[i]
	}
	return out, nil
}

// UpsertSigned 报名落库（**DELETE+INSERT 幂等**，对齐 dump `signed_add`）。
//
// 依据：dump 的 signed_add 先 `DELETE FROM t_courses_activity_signed WHERE userid=? AND activityid=?`
// 再 INSERT——同一 (user, activity) 只留一条，连历史 status=0 的旧行一并清掉（设计 §1.5）。
// 目标态 UK(user_id, activity_id) 兜底；此处保留 DELETE+INSERT 语义（而非 OnConflict 覆盖），
// 因为状态机要求"重新报名 = 全字段重置"（activity_money/recharge_amount/审核字段清零）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**，nil → ErrInternal）；
//   - signed 报名行（ActivityID>0、UserID 非空；institution_id 为 0 时用请求作用域补齐）。
//
// 出参：nil 成功；ErrBadParam（参数非法）/ ErrDBError（SQL 异常，事务由调用方回滚）。
//
// 事务/一致性（红线）：
//   - DELETE **不叠作用域**：UK(user_id, activity_id) 全局唯一，若历史迁移行的作用域列脏，
//     叠作用域会漏删 → INSERT 撞 UK 直接失败；activity_id 的归属已由调用方 GetByID 作用域校验；
//   - campus_id **不由本方法补齐**：它必须是活动上的 campus_id 快照（0 有"全自营校区"语义，
//     用请求作用域值覆盖会篡改语义）→ 由 Service 从活动行复制后传入；
//   - 报名人数增减（IncreaseNumberSign）由 Service 在同一事务内配套调用。
func (r *ActivityRepo) UpsertSigned(ctx context.Context, tx *gorm.DB, signed *model.CoursesActivitySigned) error {
	if err := requireTx(tx, "UpsertSigned"); err != nil {
		return err
	}
	if signed == nil {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: signed 为 nil"))
	}
	if signed.ActivityID <= 0 || strings.TrimSpace(signed.UserID) == "" {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: signed 缺少 activity_id/user_id"))
	}
	if signed.InstitutionID == 0 {
		inst, _ := r.GetScopedID()
		signed.InstitutionID = inst
	}
	// ① 幂等清旧行（dump：DELETE WHERE userid AND activityid）
	if err := tx.Where("user_id = ? AND activity_id = ?", signed.UserID, signed.ActivityID).
		Delete(&model.CoursesActivitySigned{}).Error; err != nil {
		return infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	// ② 插入新行（状态机全字段重置）
	if err := tx.WithContext(ctxOrBackground(ctx)).Create(signed).Error; err != nil {
		return infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return nil
}

// CountSignedByUser 统计用户报名数（**type=4 老带新限一次判定** / 取消报名的守卫条件）。
//
// 入参：
//   - ctx 请求上下文；
//   - userID 报名用户（canonical_user_id ULID；空 → ErrBadParam）；
//   - type4Only 判定口径（**两分支语义不同，禁止合并**）：
//     true  = 老带新限一次（3106）：只统计老带新活动（activity.type=4）**且活动未停用**（activity.status<>0），
//     **不过滤报名行状态**——取消过的报名也算"参加过"；
//     false = 取消报名前置守卫（signed_cancel）：统计该用户**当前有效**报名（signed.status<>0），
//     不限活动类型、不看活动状态。
//
// 出参：
//   - int64：命中条数（>0 即命中对应业务规则）；
//   - ErrBadParam / ErrDBError。
//
// SQL 口径（**逐字对齐 dump**，两分支条件集**互不重叠**）：
//
//	type4Only=true（dump `yuansiwei_finance.sql:762947`，老带新限一次）：
//	  SELECT COUNT(1) FROM t_courses_activity_signed t1
//	    INNER JOIN t_courses_activity t2 ON t1.activityid=t2.id AND t2.type=4
//	   WHERE t1.userid=? AND t2.status != 0          -- ← 只筛**活动** t2.status
//	  （**本分支没有 `t1.status` 条件**——报名行状态一律不参与过滤，
//	    取消过也算"参加过"，以此堵住"取消报名后重报再领老带新奖励"的重复发钱口子）
//
//	type4Only=false（signed_cancel 第一道守卫）：
//	  SELECT count(*) FROM t_courses_activity_signed
//	   WHERE user_id=? AND status <> 0                -- ← 这里筛的是**报名行** signed.status
//	  （本分支不看活动表、不看活动类型/状态）
//
// 两个分支唯一共用的条件是 `user_id = ?`；因此**禁止**把 `signed.status <> 0` 提到分支外
// （提到外面会让 type4 分支重新筛报名状态，退回 P0-1 的重复发钱缺陷）。
//
// 去重语义：跨活动去重由 UK(user_id, activity_id) 保证（一活动一行）。
func (r *ActivityRepo) CountSignedByUser(ctx context.Context, userID string, type4Only bool) (int64, error) {
	if strings.TrimSpace(userID) == "" {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: CountSignedByUser 需要 user_id"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return 0, err
	}
	q := db.Table("t_courses_activity_signed AS signed").
		Where("signed.user_id = ?", userID)
	if type4Only {
		// dump 口径：判**活动** status（停用=0 的活动不计），报名行状态不参与过滤
		q = q.Joins("JOIN t_courses_activity AS activity ON activity.id = signed.activity_id").
			Where("activity.type = ?", model.ActivityTypeRecommend).
			Where("activity.status <> ?", model.ActivityStatusDisabled)
	} else {
		// signed_cancel 守卫：只看报名行是否有效
		q = q.Where("signed.status <> ?", model.ActivitySignedCancelled)
	}
	q = scopedCampusRows(q, r.Sc, "signed")
	var count int64
	if err := q.Count(&count).Error; err != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return count, nil
}

// UpdateSignedStatus 更新报名状态（状态机推进 / 取消报名）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - userID 报名用户（ULID）；activityID 活动 ID；status 目标状态（model.ActivitySigned*）。
//
// 出参：
//   - int64：受影响行数（0 = 该 (user, activity) 不存在或不在作用域内，Service 据此返回 3001）；
//   - ErrBadParam / ErrDBError。
//
// 说明：状态机的**合法性判定**在 Service（如 2→1 仅取消路径、已审核不可取消 3107），
// 仓储只做「条件更新」，不解释状态流转规则（避免业务规则沉淀到数据层）。
func (r *ActivityRepo) UpdateSignedStatus(ctx context.Context, tx *gorm.DB, userID string, activityID int64, status int32) (int64, error) {
	if err := requireTx(tx, "UpdateSignedStatus"); err != nil {
		return 0, err
	}
	if strings.TrimSpace(userID) == "" || activityID <= 0 {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: UpdateSignedStatus 需要 user_id/activity_id"))
	}
	q := scopedCampusRows(tx.Model(&model.CoursesActivitySigned{}), r.Sc, "")
	res := q.Where("user_id = ? AND activity_id = ?", userID, activityID).
		UpdateColumn("status", status)
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// IncreaseNumberSign 报名人数原子增减（**下限 0**，防取消竞态把人数减成负数）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - activityID 活动 ID（<=0 → ErrBadParam）；delta 增量（报名 +1 / 取消 -1；0 → 空操作）。
//
// 出参：
//   - int64：受影响行数（0 = 活动不存在/不在作用域内）；
//   - ErrBadParam / ErrDBError。
//
// SQL（跨库可移植的下限保护，不用 GREATEST/MAX 以免方言差异）：
//
//	UPDATE t_courses_activity
//	   SET number_sign = CASE WHEN number_sign + <delta> < 0 THEN 0 ELSE number_sign + <delta> END
//	 WHERE id = ? [AND institution_id = ? AND campus_id IN (?,0)]
//
// 红线：与 UpsertSigned/UpdateSignedStatus **必须同事务**（否则出现"报名行在、人数没加"的脏读）。
func (r *ActivityRepo) IncreaseNumberSign(ctx context.Context, tx *gorm.DB, activityID int64, delta int32) (int64, error) {
	if err := requireTx(tx, "IncreaseNumberSign"); err != nil {
		return 0, err
	}
	if activityID <= 0 {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: IncreaseNumberSign 需要 activity_id"))
	}
	if delta == 0 {
		return 0, nil
	}
	expr := gorm.Expr("CASE WHEN number_sign + ? < 0 THEN 0 ELSE number_sign + ? END", delta, delta)
	q := scopedCampusRows(tx.Model(&model.CoursesActivity{}), r.Sc, "")
	res := q.Where("id = ?", activityID).UpdateColumn("number_sign", expr)
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// CancelSigned 取消报名并**归零赠送/活动金额**（dump `yuansiwei_finance.sql:763028`）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**：与报名人数增减、赠送池回滚同事务）；
//   - userID 报名用户（ULID；空 → ErrBadParam）；activityID 活动 ID（<=0 → ErrBadParam）。
//
// 出参：
//   - int64：受影响行数（0 = 该 (user, activity) 不存在或不在作用域内 → Service 返回 3001）；
//   - ErrBadParam / ErrDBError。
//
// SQL（dump 原文：一条 UPDATE 同置三列，**不可拆成多次更新**）：
//
//	UPDATE t_courses_activity_signed
//	   SET status = 0, activity_money = 0, activity_money_used = 0
//	 WHERE user_id = ? AND activity_id = ? [AND institution_id = ? AND campus_id IN (?,0)]
//
// 红线：
//   - 三列**必须同一条语句归零**——分步更新会在中间态出现"已取消但金额仍在"，被对账/双跑读到；
//   - 审核推进（status 单向推进、不动金额）仍走 `UpdateSignedStatus`，两者用途不可混；
//   - 归零是"取消"语义的一部分（dump 明确 SET 0），金额不会回补到别处，故调用方必须已做业务校验
//     （如老带新已发奖励 → 3108 不可撤销，判定在 Service）。
func (r *ActivityRepo) CancelSigned(ctx context.Context, tx *gorm.DB, userID string, activityID int64) (int64, error) {
	if err := requireTx(tx, "CancelSigned"); err != nil {
		return 0, err
	}
	if strings.TrimSpace(userID) == "" || activityID <= 0 {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: CancelSigned 需要 user_id/activity_id"))
	}
	q := scopedCampusRows(tx.WithContext(ctxOrBackground(ctx)).Model(&model.CoursesActivitySigned{}), r.Sc, "")
	res := q.Where("user_id = ? AND activity_id = ?", userID, activityID).
		UpdateColumns(map[string]any{
			"status":              model.ActivitySignedCancelled,
			"activity_money":      "0.00",
			"activity_money_used": "0.00",
		})
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// ListExpirableSignedActivityIDs 列出「退费/清零需要失效」的充值活动 ID（SP9/SP10 同源口径）。
//
// 依据：dump `sp_user_expense_custom_refund`（yuansiwei_finance.sql:764062）与
// `sp_user_expense_school_cleared_balance`（:764338）**逐字相同**的两段临时表填充 SQL，
// 只差最后一行的校区过滤——这正是"自营 / 加盟"分流的唯一区别（设计 §7.2 ④ / §11-2）。
//
// dump 原文（自营分支，`IF(campusSelfSupport)`）：
//
//	SELECT t1.activityid FROM t_courses_activity_signed AS t1
//	  LEFT JOIN t_courses_activity AS t2 ON t1.activityid = t2.id
//	 WHERE t1.userid = ?          -- 报名用户
//	   AND t2.type = 2            -- **只失效充值赠送活动**（代金券/老带新不动）
//	   AND t1.status != 4         -- 已过期的不重复处理
//	   AND t2.schoolid = ?        -- 机构（旧口径 schoolid → institution_id）
//	   AND t2.campusid IN (?, 0)  -- 自营：本校区 + 全机构池（campus_id=0）
//	-- 加盟分支：AND t2.campusid = ?   （不含 0=全机构池）
//
// 入参：
//   - ctx 请求上下文（可携带事务，实现内部经 db(ctx) 复用同一 tx）；
//   - userID 报名用户（ULID；空 → ErrBadParam）；
//   - institutionID 机构 ID（**必填 >0**；与 scope 机构不一致 → ErrUnscoped(1004)）；
//   - campusID 校区 ID（**必填 >0**；dump 的 `campusid<=0` 无意义）；
//   - selfSupport true=自营（`IN (campus,0)`）/ false=加盟（`= campus`）。
//
// 出参：
//   - []int64：活动 ID（**去重 + 升序**，空 → 长度 0 的非 nil 切片）；
//   - ErrBadParam / ErrUnscoped / ErrDBError。
//
// 红线：
//   - **不得**把 `t2.campusid` 的过滤写成 signed 上的 `campus_id`：活动 `campus_id=0`
//     的语义是"机构所有自营校区"，用 signed 的冗余列会漏掉这一类活动；
//   - 机构过滤必须落在 `activity.institution_id`（dump 的 `t2.schoolid`），不可省略。
func (r *ActivityRepo) ListExpirableSignedActivityIDs(
	ctx context.Context, userID string, institutionID, campusID int64, selfSupport bool,
) ([]int64, error) {
	if strings.TrimSpace(userID) == "" {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: ListExpirableSignedActivityIDs 需要 user_id"))
	}
	if institutionID <= 0 || campusID <= 0 {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: ListExpirableSignedActivityIDs 需要 institution_id>0 且 campus_id>0"))
	}
	// 机构越权防线（dump 无此校验；目标态多租户红线，与 scopedCampusRows 同口径）
	if r == nil || r.Sc == nil {
		panic(errNoScope.Error())
	}
	if !r.Sc.SuperAdmin && r.Sc.InstitutionID != institutionID {
		return nil, infraerrors.WithCause(infraerrors.ErrUnscoped,
			errString("repository: 活动失效的机构与请求作用域不一致"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	q := db.Table("t_courses_activity_signed AS signed").
		Joins("JOIN t_courses_activity AS activity ON activity.id = signed.activity_id").
		Where("signed.user_id = ?", userID).
		Where("activity.type = ?", model.ActivityTypeRecharge).
		Where("signed.status <> ?", model.ActivitySignedExpired).
		Where("activity.institution_id = ?", institutionID)
	if selfSupport {
		// 自营：本校区 + 全机构池（campus_id=0）
		q = q.Where("activity.campus_id IN ?", []int64{campusID, 0})
	} else {
		// 加盟：只能动本校区自己的活动（不含 0=全机构池）
		q = q.Where("activity.campus_id = ?", campusID)
	}
	ids := make([]int64, 0, 8)
	if err := q.Distinct().Order("signed.activity_id ASC").Pluck("signed.activity_id", &ids).Error; err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	if ids == nil {
		ids = make([]int64, 0)
	}
	return ids, nil
}

// SetSignedStatusByActivityIDs 批量置报名状态（活动失效 status=4 / 取消充值活动 status=0）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**：与资金增减同事务，否则出现"钱退了、活动还能用"）；
//   - userID 报名用户（ULID；空 → ErrBadParam）；
//   - activityIDs 活动 ID 集合（空 → no-op 返回 0，不发 SQL）；
//   - status 目标状态（model.ActivitySigned*）。
//
// 出参：(受影响行数, error)；ErrBadParam / ErrInternal / ErrDBError。
//
// SQL（dump 原文，**不带 status 过滤、不带作用域过滤**）：
//
//	UPDATE t_courses_activity_signed SET status = ? WHERE user_id = ? AND activity_id IN (...)
//
// 为什么不带作用域过滤：候选集合已由 `ListExpirableSignedActivityIDs` 按
// `activity.institution_id + activity.campus_id` 精确筛出（比 signed 的冗余列更准），
// 再叠一层 signed 的 campus_id 等值会把 `campus_id=0` 的活动报名行漏掉。
// 机构越权风险为 0：入参 activityIDs 只能来自上面的受控查询。
func (r *ActivityRepo) SetSignedStatusByActivityIDs(
	ctx context.Context, tx *gorm.DB, userID string, activityIDs []int64, status int32,
) (int64, error) {
	if err := requireTx(tx, "SetSignedStatusByActivityIDs"); err != nil {
		return 0, err
	}
	if strings.TrimSpace(userID) == "" {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: SetSignedStatusByActivityIDs 需要 user_id"))
	}
	clean := make([]int64, 0, len(activityIDs))
	for _, id := range activityIDs {
		if id > 0 {
			clean = append(clean, id)
		}
	}
	if len(clean) == 0 {
		return 0, nil
	}
	res := tx.WithContext(ctxOrBackground(ctx)).Model(&model.CoursesActivitySigned{}).
		Where("user_id = ? AND activity_id IN ?", userID, clean).
		UpdateColumn("status", status)
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// wrapQueryErr 把查询错误归一为 academic 错误契约（不存在 → ErrNotFound，其余 → ErrDBError）。
//
// 入参：err 原生错误；op 操作名（仅用于日志关联，不进入响应体）。
// 出参：*infraerrors.AppError（ErrNotFound / ErrDBError）。
func wrapQueryErr(err error, op string) error {
	if err == nil {
		return nil
	}
	if errors.Is(err, gorm.ErrRecordNotFound) {
		return infraerrors.WithCause(infraerrors.ErrNotFound, err)
	}
	return infraerrors.WithCause(infraerrors.ErrDBError, fmt.Errorf("%s: %w", op, err))
}

// ctxOrBackground 保证传给 gorm 的 ctx 非 nil（gorm.WithContext(nil) 会 panic）。
func ctxOrBackground(ctx context.Context) context.Context {
	if ctx != nil {
		return ctx
	}
	return context.Background()
}