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

// 分账树仓储（t_user_divide_into / t_user_divide_into_log）——AC-09。
//
// 依据：unified/03-migration/academic-domain-design.md §3.3 #22~#25（分账 4 SP）
// / §1.7「全局无作用域表·例外二」/ §11.1 拍板 11-12。
//
// **本仓储不继承 BaseRepo**（设计 §11.1 拍板：全局推广体系无 institution_id/campus_id）：
//   - 两表无租户列，`Scoped` 无从下手（叠 institution_id 会 Unknown column）；
//   - 越权防线改为 **Handler 角色白名单（super_admin/academic）+ Service 显式数据范围参数**，
//     本文件的数据访问方法因此**不接受**作用域参数，评审时必须显式标注"平台级/全局数据"；
//   - 禁止把本仓储用于任何机构/校区维度的报表裁剪（需要裁剪时按 user_id 精确取数）。
//
// 表语义（Nested Set）：
//
//	t_user_divide_into     一人一节点（PK user_id）；root_user_id 标记所属树；
//	                       left_val/right_val 为嵌套集区间（恒有 left < right）；layer 根=1。
//	t_user_divide_into_log 分成明细（只增；type=1 同 user+student / type=2 同 user+student+order 幂等）。
//
// 事务纪律：写方法一律接收 `tx *gorm.DB`（仓储不开事务，事务边界在 DivideService）。
package repository

import (
	"context"
	"errors"
	"strings"

	"gorm.io/gorm"

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

// DivideRepo 分账树仓储（全局数据，**不继承 BaseRepo**，见文件头）。
type DivideRepo struct {
	// DB 数据库句柄（连接池由 infra/db 统一建立；nil 时任何查询返回 ErrInternal）。
	DB *gorm.DB
}

// NewDivideRepo 构造分账树仓储。
//
// 入参：db *gorm.DB——连接池句柄（必填）。
// 出参：*DivideRepo。
func NewDivideRepo(db *gorm.DB) *DivideRepo { return &DivideRepo{DB: db} }

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

// GetByUserID 取分账树节点（主键 user_id）。
//
// 入参：ctx 请求上下文；userID 节点用户（ULID；空 → ErrBadParam）。
// 出参：
//   - *model.UserDivideInto：节点（left_val/right_val/layer/quota 原样返回，金额为字符串）；
//   - ErrNotFound（3001）：该用户尚未进入分账体系（**不是**错误路径，调用方按业务分支处理）；
//   - ErrBadParam / ErrDBError。
func (r *DivideRepo) GetByUserID(ctx context.Context, userID string) (*model.UserDivideInto, error) {
	if strings.TrimSpace(userID) == "" {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: GetByUserID 需要 user_id"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	var out model.UserDivideInto
	if err := db.Where("user_id = ?", userID).First(&out).Error; err != nil {
		return nil, wrapQueryErr(err, "GetByUserID(t_user_divide_into)")
	}
	return &out, nil
}

// GetSubtree 取节点子树（严格位于 (leftVal, rightVal) 区间内的后代）。
//
// 入参：
//   - ctx 请求上下文；
//   - leftVal/rightVal int32：父节点的左右值（Nested Set 区间；rightVal <= leftVal → ErrBadParam）；
//   - divideType int8：分成类型过滤（model.DivideTypeOneOff / DivideTypePerLesson；0 = 不筛类型）。
//
// 出参：
//   - []model.UserDivideInto：后代节点，按 left_val 升序（= 树的深度优先前序，便于逐层遍历）；
//   - ErrBadParam / ErrDBError。
//
// 用途：额度级联下降（update_quota）/ 子树统计。**不含**父节点自身。
func (r *DivideRepo) GetSubtree(ctx context.Context, leftVal, rightVal int32, divideType int8) ([]model.UserDivideInto, error) {
	if leftVal < 0 || rightVal <= leftVal {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: GetSubtree 左右值区间非法"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	q := db.Model(&model.UserDivideInto{}).
		Where("left_val > ? AND right_val < ?", leftVal, rightVal)
	if divideType > 0 {
		q = q.Where("type = ?", divideType)
	}
	var rows []model.UserDivideInto
	if err := q.Order("left_val asc").Find(&rows).Error; err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return rows, nil
}

// ShiftRight 右值扩张：`right_val = right_val + delta WHERE right_val >= threshold`。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - threshold int32：扩张阈值（新节点插入点 = 父节点右值；**父与全部祖先**的 right 均 >= 它，一次覆盖）；
//   - delta int32：增量（插入子节点固定 +2；撤销固定 -2）。
//
// 出参：int64 受影响行数；ErrBadParam / ErrDBError。
//
// 红线：与 ShiftLeft **必须同一事务、同一 threshold**（两步各自只动一列，合成标准嵌套集插入算法；
// 拆事务会让树在中间态不可用）。
func (r *DivideRepo) ShiftRight(ctx context.Context, tx *gorm.DB, threshold int32, delta int32) (int64, error) {
	return r.shift(ctx, tx, "right_val", threshold, delta)
}

// ShiftLeft 左值扩张：`left_val = left_val + delta WHERE left_val >= threshold`。
//
// 入参：语义同 ShiftRight（只作用于 left_val 列——即"位于插入点右侧的兄弟及其后代"）。
// 出参：int64 受影响行数；ErrBadParam / ErrDBError。
func (r *DivideRepo) ShiftLeft(ctx context.Context, tx *gorm.DB, threshold int32, delta int32) (int64, error) {
	return r.shift(ctx, tx, "left_val", threshold, delta)
}

// shift 左右值扩张的公共实现（列名由内部常量传入，**不接受外部字符串**，防注入）。
//
// 入参：col 列名（"left_val"/"right_val"）；threshold/delta 语义见 ShiftRight。
// 出参：int64 受影响行数；ErrBadParam / ErrDBError。
func (r *DivideRepo) shift(ctx context.Context, tx *gorm.DB, col string, threshold int32, delta int32) (int64, error) {
	if err := requireTx(tx, "shift("+col+")"); err != nil {
		return 0, err
	}
	if col != "left_val" && col != "right_val" {
		return 0, infraerrors.WithCause(infraerrors.ErrInternal, errString("repository: shift 列名非法"))
	}
	if threshold < 0 {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: shift 阈值不能为负"))
	}
	if delta == 0 {
		return 0, nil
	}
	res := tx.WithContext(ctxOrBackground(ctx)).Model(&model.UserDivideInto{}).
		Where(col+" >= ?", threshold).
		UpdateColumn(col, gorm.Expr(col+" + ?", delta))
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// InsertNode 插入分账树节点（新节点左右值由 Service 用嵌套集算法算出）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - node 节点（UserID 非空；必须满足 LeftVal < RightVal，否则 ErrBadParam）。
//
// 出参：nil 成功；ErrBadParam / ErrDBError。
//
// 红线：与 ShiftRight/ShiftLeft **必须同事务**；已存在同 user_id 节点 → 唯一键冲突（ErrDBError，
// 调用方按"已存在分支"重入，不得重试插入）。
func (r *DivideRepo) InsertNode(ctx context.Context, tx *gorm.DB, node *model.UserDivideInto) error {
	if err := requireTx(tx, "InsertNode"); err != nil {
		return err
	}
	if node == nil || strings.TrimSpace(node.UserID) == "" {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: InsertNode 需要 user_id"))
	}
	if node.LeftVal >= node.RightVal {
		return infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: InsertNode 违反 Nested Set 不变式 left_val < right_val"))
	}
	if err := tx.WithContext(ctxOrBackground(ctx)).Create(node).Error; err != nil {
		return infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return nil
}

// InsertLog 写入分成明细（**只增**）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - log 明细（Type∈{1,2}、UserID/StudentID 非空、Money 为元字符串）。
//
// 出参：nil 成功；ErrBadParam / ErrDBError。
//
// 红线：与节点 total_income 累加（IncTotalIncome）必须同事务（否则"明细有、收入没加"）。
func (r *DivideRepo) InsertLog(ctx context.Context, tx *gorm.DB, log *model.UserDivideIntoLog) error {
	if err := requireTx(tx, "InsertLog"); err != nil {
		return err
	}
	if log == nil || strings.TrimSpace(log.UserID) == "" || strings.TrimSpace(log.StudentID) == "" {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: InsertLog 需要 user_id/student_id"))
	}
	if log.Type != model.DivideTypeOneOff && log.Type != model.DivideTypePerLesson {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: InsertLog 分成类型非法"))
	}
	if err := tx.WithContext(ctxOrBackground(ctx)).Create(log).Error; err != nil {
		return infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return nil
}

// DeleteLog 物理删除分成明细（撤销分支二：回滚 total_income 后删行）。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - id 明细 ID（<=0 → ErrBadParam）。
//
// 出参：nil 成功/行不存在（幂等）；ErrBadParam / ErrDBError。
//
// 红线（设计 §3.3 #23）：旧语义允许物理删除本表行（与"流水只增"纪律的唯一例外），
// 但必须与 total_income 回滚同事务；删除前须判定"是否已有首次扣费上课记录"（改绑分支优先）。
func (r *DivideRepo) DeleteLog(ctx context.Context, tx *gorm.DB, id int64) error {
	if err := requireTx(tx, "DeleteLog"); err != nil {
		return err
	}
	if id <= 0 {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: DeleteLog 需要 id"))
	}
	if err := tx.WithContext(ctxOrBackground(ctx)).Where("id = ?", id).
		Delete(&model.UserDivideIntoLog{}).Error; err != nil {
		return infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return nil
}

// FindLog 按**幂等键**查分成明细（两级幂等判定唯一入口）。
//
// 入参：
//   - ctx 请求上下文；
//   - userID 获得分成的用户（ULID）；studentID 报课学生（ULID）；divideType 分成类型；
//   - orderNo 订单号（type=2 的上课记录 id 字符串；**type=1 时忽略**——一次付清不区分订单）。
//
// 出参：
//   - *model.UserDivideIntoLog：命中行；
//   - ErrNotFound：未命中（调用方据此判定"未生成"，非异常）；
//   - ErrBadParam / ErrDBError。
//
// 幂等键（dump divide_into_log_add 口径，**不可改**）：
//   - type=1（一次付清）：(user_id, student_id, type)；
//   - type=2（按课次）  ：(user_id, student_id, type, order_no)。
func (r *DivideRepo) FindLog(ctx context.Context, userID, studentID string, divideType int8, orderNo string) (*model.UserDivideIntoLog, error) {
	if strings.TrimSpace(userID) == "" || strings.TrimSpace(studentID) == "" {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: FindLog 需要 user_id/student_id"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	q := db.Model(&model.UserDivideIntoLog{}).
		Where("user_id = ? AND student_id = ? AND type = ?", userID, studentID, divideType)
	if divideType == model.DivideTypePerLesson {
		q = q.Where("order_no = ?", strings.TrimSpace(orderNo))
	}
	var out model.UserDivideIntoLog
	if err := q.Order("id asc").First(&out).Error; err != nil {
		return nil, wrapQueryErr(err, "FindLog(t_user_divide_into_log)")
	}
	return &out, nil
}

// ListLogsByStudentOrder 取某「学生 + 订单」产生的**全部**分成明细（撤销的两参入口）。
//
// 入参：ctx 请求上下文；studentID 报课学生（ULID）；orderNo 订单号（上课记录 id 字符串）。
// 出参：
//   - []model.UserDivideIntoLog：按 id 升序（生成先后；空切片表示无记录，幂等空操作）；
//   - ErrBadParam / ErrDBError。
//
// 语义（dump `divide_into_log_delete(studentid, orderid)` 两参）：同一订单的分成会沿上行链
// 生成多行（本人 + 各级上线），撤销时必须**整组处理**，故按 (student_id, order_no) 取全量，
// 而非只取一行。
func (r *DivideRepo) ListLogsByStudentOrder(ctx context.Context, studentID, orderNo string) ([]model.UserDivideIntoLog, error) {
	if strings.TrimSpace(studentID) == "" || strings.TrimSpace(orderNo) == "" {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: ListLogsByStudentOrder 需要 student_id/order_no"))
	}
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	var rows []model.UserDivideIntoLog
	if err := db.Model(&model.UserDivideIntoLog{}).
		Where("student_id = ? AND order_no = ?", studentID, orderNo).
		Order("id asc").
		Find(&rows).Error; err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return rows, nil
}

// UpdateNodeParent 改挂节点父链（`subid 已存在`分支：只改父/根/层级，**不重排左右值**）。
//
// 入参：
//   - ctx 请求上下文；tx 事务句柄（**必传**）；
//   - userID 被改挂节点；parentUserID 新上级；rootUserID 所属树根；layer 新层级（根=1）。
//
// 出参：int64 受影响行数；ErrBadParam / ErrDBError。
//
// 红线（修正 dump 缺陷，模型注释 §UserDivideInto.root_user_id 已标注）：
// 旧 SP 在该分支**漏写 root_user_id**（留 NULL，导致子树查询/级联失效）；本方法强制显式写根。
// 遗留：不重排左右值（与原 SP 一致）——若被改挂节点自带子树，区间可能出现交叠，
// 已在交付说明中登记为遗留项（AC-09 范围内不引入区间重排，避免与迁移期数据冲突）。
func (r *DivideRepo) UpdateNodeParent(ctx context.Context, tx *gorm.DB, userID, parentUserID, rootUserID string, layer int32) (int64, error) {
	if err := requireTx(tx, "UpdateNodeParent"); err != nil {
		return 0, err
	}
	if strings.TrimSpace(userID) == "" || strings.TrimSpace(parentUserID) == "" || strings.TrimSpace(rootUserID) == "" {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: UpdateNodeParent 需要 user/parent/root"))
	}
	if layer < 1 {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: UpdateNodeParent layer 必须 >= 1"))
	}
	res := tx.WithContext(ctxOrBackground(ctx)).Model(&model.UserDivideInto{}).
		Where("user_id = ?", userID).
		Updates(map[string]any{
			"parent_user_id": parentUserID,
			"root_user_id":   rootUserID,
			"layer":          layer,
		})
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// UpdateNodeQuota 更新节点分成额度（不触碰左右值/收入）。
//
// 入参：ctx；tx（**必传**）；userID 节点；quota 新额度（单位：分；负 → ErrBadParam）。
// 出参：int64 受影响行数；ErrBadParam / ErrDBError。
//
// 红线：**必须**与 ClampSubtreeQuota 同事务（否则出现"父降了、子仍高于父"的越权额度窗口）。
func (r *DivideRepo) UpdateNodeQuota(ctx context.Context, tx *gorm.DB, userID string, quota money.Amount) (int64, error) {
	if err := requireTx(tx, "UpdateNodeQuota"); err != nil {
		return 0, err
	}
	if strings.TrimSpace(userID) == "" {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: UpdateNodeQuota 需要 user_id"))
	}
	if err := quota.Validate(); err != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, err)
	}
	if quota.IsNegative() {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: 分成额度不能为负"))
	}
	res := tx.WithContext(ctxOrBackground(ctx)).Model(&model.UserDivideInto{}).
		Where("user_id = ?", userID).
		UpdateColumn("quota", quota.String())
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// ClampSubtreeQuota 额度级联下降：把子树内**超过**上限的节点统一压到上限。
//
// 入参：
//   - ctx；tx（**必传**）；
//   - leftVal/rightVal int32 父节点区间（rightVal <= leftVal → ErrBadParam）；
//   - quota 上限（单位：分；负 → ErrBadParam）。
//
// 出参：int64 受影响行数；ErrBadParam / ErrDBError。
//
// SQL：`UPDATE ... SET quota = ? WHERE left_val > ? AND right_val < ? AND quota > ?`
// 语义（"子不得超父"）：只降不升——低于上限的节点保持原额度（分别配置的阶梯额度不被抹平）。
func (r *DivideRepo) ClampSubtreeQuota(ctx context.Context, tx *gorm.DB, leftVal, rightVal int32, quota money.Amount) (int64, error) {
	if err := requireTx(tx, "ClampSubtreeQuota"); err != nil {
		return 0, err
	}
	if leftVal < 0 || rightVal <= leftVal {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: ClampSubtreeQuota 左右值区间非法"))
	}
	if err := quota.Validate(); err != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, err)
	}
	if quota.IsNegative() {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: 分成额度不能为负"))
	}
	res := tx.WithContext(ctxOrBackground(ctx)).Model(&model.UserDivideInto{}).
		Where("left_val > ? AND right_val < ?", leftVal, rightVal).
		Where("quota > ?", quota.String()).
		UpdateColumn("quota", quota.String())
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// IncTotalIncome 累加节点分成总收入（上行分成 +，撤销回滚 −）。
//
// 入参：ctx；tx（**必传**）；userID 节点；delta 增量（单位：分；0 → 空操作）。
// 出参：int64 受影响行数；ErrBadParam / ErrDBError。
//
// 红线：与 InsertLog/DeleteLog 同事务；金额字符串入场（decimal 精确，零 float64）。
func (r *DivideRepo) IncTotalIncome(ctx context.Context, tx *gorm.DB, userID string, delta money.Amount) (int64, error) {
	if err := requireTx(tx, "IncTotalIncome"); err != nil {
		return 0, err
	}
	if strings.TrimSpace(userID) == "" {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: IncTotalIncome 需要 user_id"))
	}
	if delta.IsZero() {
		return 0, nil
	}
	if err := delta.Validate(); err != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, err)
	}
	res := tx.WithContext(ctxOrBackground(ctx)).Model(&model.UserDivideInto{}).
		Where("user_id = ?", userID).
		UpdateColumn("total_income", gorm.Expr("total_income + ?", delta.String()))
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// UpdateLogOrderNo 改绑分成明细的订单号（撤销分支一：保留分成，改指首次扣费上课记录）。
//
// 入参：ctx；tx（**必传**）；id 明细 ID；orderNo 新订单号（上课记录 id 字符串）；remark 备注（可空）。
// 出参：int64 受影响行数；ErrBadParam / ErrDBError。
//
// 红线（dump 口径）：改绑**不改 money**、**不回滚 total_income**（分成保留）；
// order_no 是 type=2 的幂等键组成列，改绑即改幂等语义 → 必须写审计备注（默认"推广分成"）。
func (r *DivideRepo) UpdateLogOrderNo(ctx context.Context, tx *gorm.DB, id int64, orderNo, remark string) (int64, error) {
	if err := requireTx(tx, "UpdateLogOrderNo"); err != nil {
		return 0, err
	}
	if id <= 0 || strings.TrimSpace(orderNo) == "" {
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam, errString("repository: UpdateLogOrderNo 需要 id/order_no"))
	}
	fields := map[string]any{"order_no": orderNo}
	if strings.TrimSpace(remark) != "" {
		fields["remark"] = remark
	}
	res := tx.WithContext(ctxOrBackground(ctx)).Model(&model.UserDivideIntoLog{}).
		Where("id = ?", id).
		Updates(fields)
	if res.Error != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, res.Error)
	}
	return res.RowsAffected, nil
}

// IsNotFound 判断错误是否为仓储 ErrNotFound（供 Service 分支判断，避免各处抄 errors.Is）。
//
// 入参：err error（可 nil）。出参：true 表示"记录不存在"。
func IsNotFound(err error) bool { return err != nil && errors.Is(err, infraerrors.ErrNotFound) }