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（服务层组合成状态机）
//	sign 限一次(3106) → CountSignedByUser(type4Only=true)
//	退费回滚赠送金额   → ListSignedByStudentCourse（按报课记录定位报名行）
//
// 作用域（关键设计，与 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"
	"time"

	"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)
	}
	// ② 插入新行（状态机全字段重置；审计时间兜底，见 ensureCreateTime）
	ensureCreateTime(&signed.CreateTime)
	if err := tx.WithContext(ctxOrBackground(ctx)).Create(signed).Error; err != nil {
		return infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return nil
}

// CountSignedByUser 统计用户有效报名数（**type=4 跨活动去重判定**，3106 老带新限一次）。
//
// 入参：
//   - ctx 请求上下文；
//   - userID 报名用户（canonical_user_id ULID；空 → ErrBadParam）；
//   - type4Only true=只统计老带新（t_courses_activity.type=4）活动；false=统计全部活动类型。
//
// 出参：
//   - int64：有效报名记录数（**status != 0**，已取消/过期行不计）；
//   - ErrBadParam / ErrDBError。
//
// SQL 口径（对齐 dump，表名/列名限定防 JOIN ambiguous）：
//
//	SELECT count(*) FROM t_courses_activity_signed signed
//	  JOIN t_courses_activity activity ON activity.id = signed.activity_id
//	 WHERE signed.user_id = ? AND signed.status <> 0 AND activity.type = 4
//	   AND signed.institution_id = ? AND signed.campus_id IN (?, 0)   -- 作用域
//
// 去重语义：跨活动去重由 UK(user_id, activity_id) 保证（一活动一行），故 COUNT(*) 即
// "该用户参加过多少个 type=4 活动"；>0 即可返回 3106（设计 §3.2 signed_add）。
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).
		Where("signed.status <> ?", model.ActivitySignedCancelled)
	if type4Only {
		q = q.Joins("JOIN t_courses_activity AS activity ON activity.id = signed.activity_id").
			Where("activity.type = ?", model.ActivityTypeRecommend)
	}
	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
}

// ListSignedByStudentCourse 按报课记录回溯报名行（退费/撤销时定位需要回滚的 signed）。
//
// 发现路径（dump 的退费回滚链）：报课记录 id → 赠送金额使用流水 log.courses_student_id
// → 赠送金额池 pool.id → (pool.activity_id, pool.user_id) → signed（同活动同用户）。
//
// 入参：
//   - ctx 请求上下文；
//   - stuCourseID 报课记录 ID（t_courses_student.id；<=0 → ErrBadParam）；
//   - order 游标方向（OrderAsc/OrderDesc，**顺序写死不可改**）：
//     OrderAsc = 按使用先后（先用的活动先处理，dump 消费路径）；
//     OrderDesc = 按最近使用优先（dump 退回路径）。
//
// 出参：
//   - []model.CoursesActivitySigned：去重后的报名行（同一活动多笔流水只返回一行）；
//   - ErrBadParam / ErrDBError。
//
// 事务：只读（ctx 内注入 tx 时自动复用）。
func (r *ActivityRepo) ListSignedByStudentCourse(ctx context.Context, stuCourseID int64, order string) ([]model.CoursesActivitySigned, error) {
	if stuCourseID <= 0 {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: ListSignedByStudentCourse 需要 courses_student_id"))
	}
	dir, err := normalizeOrder(order)
	if err != nil {
		return nil, err
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	q := db.Table("t_courses_activity_signed AS signed").
		Distinct("signed.*").
		Joins("JOIN t_courses_activity_user_discount AS pool ON pool.activity_id = signed.activity_id AND pool.user_id = signed.user_id").
		Joins("JOIN t_courses_activity_user_discount_log AS dlog ON dlog.activity_user_discount_id = pool.id").
		Where("dlog.courses_student_id = ?", stuCourseID).
		Where("signed.status <> ?", model.ActivitySignedCancelled)
	q = scopedCampusRows(q, r.Sc, "signed")
	// 游标方向来自白名单常量（dump 固定顺序），禁止调用方拼 SQL
	q = q.Order("signed.id " + dir)
	var rows []model.CoursesActivitySigned
	if err := q.Find(&rows).Error; err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return rows, 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()
}

// ensureCreateTime 审计时间兜底（零值 → 当前时间）。
//
// 为什么需要（实测缺陷）：AC-01 的活动域 model 用的是 `CreateTime` 字段名（非 GORM 约定的
// `CreatedAt`），且 tag 只有 `not null` 没有 `default:CURRENT_TIMESTAMP(3)`；
// 实测 GORM 会把 time.Time 零值**显式**写进 INSERT（得到 0001-01-01），DB 默认值根本兜不住。
// 审计时间是对账依据（红线），故在仓储写入前统一兜底，避免调用方漏填造成时间列被写坏。
//
// 入参：dst *time.Time——待写入行的 create_time 字段地址（nil 时忽略）。
func ensureCreateTime(dst *time.Time) {
	if dst != nil && dst.IsZero() {
		*dst = time.Now()
	}
}