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"
	"time"

	"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 root_user_id = ? AND right_val >= threshold`。
//
// 入参：
//   - ctx 请求上下文；
//   - tx 事务句柄（**必传**）；
//   - rootUserID **所属树根**（ULID；**必填**，见下方红线）；
//   - threshold int32：扩张阈值（新节点插入点 = 父节点右值；父与全部祖先的 right 均 >= 它，一次覆盖）；
//   - delta int32：增量（插入子节点固定 +2；撤销固定 -2）。
//
// 出参：int64 受影响行数；ErrBadParam / ErrDBError。
//
// 红线（audit V-02，dump `yuansiwei_finance.sql:763707-763708`）：
//
//	dump 原文的位移语句带 `WHERE root_userid = rootUserid AND left_val >= parentRight`。
//	**漏掉 root 限定的后果**：多棵树共用一张表（各自 root 的左右值区间可能重叠/相邻），
//	同输入会产出不同的 left/right → 双跑快照 diff 必然不一致，且会污染别的树的区间。
//	（同一 dump 的另一处 left 位移同理，行号 763708。）
//
// 与 ShiftLeft **必须同一事务、同一 rootUserID 与 threshold**（两步各自只动一列，
// 合成标准嵌套集插入算法；拆事务会让树在中间态不可用）。
func (r *DivideRepo) ShiftRight(ctx context.Context, tx *gorm.DB, rootUserID string, threshold int32, delta int32) (int64, error) {
	return r.shift(ctx, tx, "right_val", rootUserID, threshold, delta)
}

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

// shift 左右值扩张的公共实现（列名由内部常量传入，**不接受外部字符串**，防注入）。
//
// 入参：col 列名（"left_val"/"right_val"）；rootUserID 树根（必填）；
// threshold/delta 语义见 ShiftRight。
// 出参：int64 受影响行数；ErrBadParam / ErrDBError。
func (r *DivideRepo) shift(ctx context.Context, tx *gorm.DB, col, rootUserID 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 strings.TrimSpace(rootUserID) == "" {
		// root 限定不可省：漏了会串改其它树的区间（audit V-02）
		return 0, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("repository: shift 需要 root_user_id（多树隔离，dump 763707）"))
	}
	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("root_user_id = ?", strings.TrimSpace(rootUserID)).
		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 改挂节点父链（只改父/根/层级，**不重排左右值**）。
//
// ⚠ **当前无业务调用方**（audit D4：dump `:763695` 的 "subid 已存在" 分支是**完全 no-op**，
// 分支体内没有任何写动作）。本方法因此**不属于 dump 流程**，仅保留给后台数据修复；
// 若将来要用于业务链路，必须先评审——它不重排左右值，改挂自带子树的节点会产生区间交叠。
//
// 入参：
//   - 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）；
//   - divideType 分成类型过滤（model.DivideTypeOneOff/PerLesson；**0 = 不筛**，仅 admin 全量场景）；
//   - quota 上限（单位：分；负 → ErrBadParam）。
//
// 出参：int64 受影响行数；ErrBadParam / ErrDBError。
//
// SQL（audit A6 / dump `yuansiwei_finance.sql:763872-763873` 原文条件，**缺一不可**）：
//
//	UPDATE t_user_divide_into SET quota=updateQuota
//	 WHERE left_val>uLeft AND right_val<uRight AND quota>updateQuota AND type=uType;
//
// 语义（"子不得超父"）：只降不升——低于上限的节点保持原额度（分别配置的阶梯额度不被抹平）。
// 红线：`type` 过滤不可省 —— 否则一次付清(1)与按课次(2)两条线的额度会被跨类型抹平（漏实现 = 缺陷）。
func (r *DivideRepo) ClampSubtreeQuota(ctx context.Context, tx *gorm.DB, leftVal, rightVal int32, divideType int8, 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 divideType != 0 && divideType != model.DivideTypeOneOff && divideType != model.DivideTypePerLesson {
		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: 分成额度不能为负"))
	}
	q := tx.WithContext(ctxOrBackground(ctx)).Model(&model.UserDivideInto{}).
		Where("left_val > ? AND right_val < ?", leftVal, rightVal).
		Where("quota > ?", quota.String())
	if divideType != 0 {
		q = q.Where("type = ?", divideType)
	}
	res := q.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"))
	}
	// create_time 重置为 DB 当前时间（dump 改绑分支：`create_time=now()`，让改绑后的明细排到最新）
	fields := map[string]any{"order_no": orderNo, "create_time": gorm.Expr("CURRENT_TIMESTAMP")}
	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) }

// ---------------------------------------------------------------- AC-13 查询原语（端点 38 / 43）

// ListAllNodes 取全部分账节点（Nested Set，按 `root_user_id, left_val` 排序）。
//
// 入参：ctx。
// 出参：
//   - []model.UserDivideInto：稳定顺序（同 root 内按 left 升序 ⇒ 天然是树的先序）；
//   - ErrDBError。
//
// 作用域：`t_user_divide_into` **无** institution_id / campus_id（全局推广体系，设计 §1.7 例外一），
// 故不叠 Scoped；可见性由端点角色白名单（super_admin/finance/market）控制，见 handler 注释。
//
// 为什么不在此拼树：拼树 + 树不变式校验属业务规则（layer = parent.layer+1、
// 区间嵌套或相离），放 Service 才能单测（`service.divide_tree.go`）。
func (r *DivideRepo) ListAllNodes(ctx context.Context, rootUserID string) ([]model.UserDivideInto, error) {
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	q := db.Model(&model.UserDivideInto{})
	if strings.TrimSpace(rootUserID) != "" {
		// 端点 38 的 `rootUserId?`：只取某一棵树（多树共存时前端按需拉取，避免全量森林）
		q = q.Where("root_user_id = ?", strings.TrimSpace(rootUserID))
	}
	rows := make([]model.UserDivideInto, 0, 64)
	if qErr := q.Order("root_user_id ASC").Order("left_val ASC").Find(&rows).Error; qErr != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, qErr)
	}
	return rows, nil
}

// ListAncestorIDs 取某节点的**祖先链**（端点 39 的 `{ancestorIds:[]}`，设计 §3.3 #21 末尾原语）。
//
// 入参：ctx；userID 新加入的下线；leftVal/rightVal/rootUserID 其 Nested Set 区间与树根。
// 出参：[]string 祖先 user_id（**不含自身**；由内向外或由外向内按 `left_val ASC` = 由外向内）；
//
//	ErrDBError。
//
// dump 原文：`SELECT userid ... WHERE left<userLeft AND right>userRight AND root_userid=root`
// ⇒ 天然含"区间包含该节点"的所有祖先；**root 限定不可省**（D5：跨树区间数值可能重叠，
// 缺 root 会把别的树的节点算成本节点祖先）。
func (r *DivideRepo) ListAncestorIDs(
	ctx context.Context, leftVal, rightVal int32, rootUserID string,
) ([]string, error) {
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	ids := make([]string, 0, 8)
	q := db.Model(&model.UserDivideInto{}).
		Where("left_val < ? AND right_val > ?", leftVal, rightVal)
	if strings.TrimSpace(rootUserID) != "" {
		q = q.Where("root_user_id = ?", strings.TrimSpace(rootUserID))
	}
	if qErr := q.Order("left_val ASC").Pluck("user_id", &ids).Error; qErr != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, qErr)
	}
	return ids, nil
}

// ListSubtreeUserIDsWithQuotaAtLeast 取子树内 `quota >= 阈值` 的 user_id（端点 40 的 `{affectedUserIds:[]}`）。
//
// 入参：ctx；leftVal/rightVal 子树区间（含自身）；quota 新额度（调用方已转为分）。
// 出参：[]string 受影响 user_id（`left_val ASC` 由外向内）；ErrDBError。
//
// dump 原文：`SELECT userid ... WHERE left>=uLeft AND right<=uRight AND quota>=newQuota`（含自身）。
// 该查询在 `update_quota` **末尾**执行 ⇒ 本方法应在 UpdateQuota 之后调用（读已提交状态）。
func (r *DivideRepo) ListSubtreeUserIDsWithQuotaAtLeast(
	ctx context.Context, leftVal, rightVal int32, quota money.Amount,
) ([]string, error) {
	db, err := r.db(ctx)
	if err != nil {
		return nil, err
	}
	ids := make([]string, 0, 8)
	if qErr := db.Model(&model.UserDivideInto{}).
		Where("left_val >= ? AND right_val <= ? AND quota >= ?", leftVal, rightVal, quota.String()).
		Order("left_val ASC").Pluck("user_id", &ids).Error; qErr != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrDBError, qErr)
	}
	return ids, nil
}

// DivideLogFilter 分账流水筛选（端点 43）。
//
// 字段语义（nil/空 = 不筛）：
//   - FindUserID 分成获得者（**表列是 `user_id`**；契约响应字段名才叫 `findUserId`）；StudentID 学生；
//   - From/To：`create_time >= from AND create_time < to`（**右开**，与契约 §1.3 一致）。
type DivideLogFilter struct {
	// FindUserID 分成获得者（ULID；空 = 不筛）。
	FindUserID string
	// StudentID 学生（ULID；空 = 不筛）。
	StudentID string
	// From 起始时间（含；nil = 不筛）。
	From *time.Time
	// To 结束时间（**不含**；nil = 不筛）。
	To *time.Time
}

// ListLogsFiltered 分页查分账流水（端点 43，带用户/学生/时间窗筛选，附总条数）。
//
// 入参：ctx；f DivideLogFilter；page PageQuery（内部钳制 pageSize ∈ [1,200]）。
// 出参：
//   - []model.UserDivideIntoLog：`create_time DESC, id DESC`；空结果非 nil 切片；
//   - int64：同条件总条数（**与列表逐字同 WHERE**，同快照）；
//   - ErrDBError。
//
// ⚠ 该端点**无 dump SP 对照**（dump 只有 add/delete/update_quota 三个 SP）⇒ 排序与窗口由 Go 定，
// 已登记为「Go 新增查询」（契约 v1.4 端点 43 注）。
func (r *DivideRepo) ListLogsFiltered(
	ctx context.Context, f DivideLogFilter, page PageQuery,
) ([]model.UserDivideIntoLog, int64, error) {
	db, err := r.db(ctx)
	if err != nil {
		return nil, 0, err
	}
	base := db.Model(&model.UserDivideIntoLog{})
	if f.FindUserID != "" {
		base = base.Where("user_id = ?", f.FindUserID)
	}
	if f.StudentID != "" {
		base = base.Where("student_id = ?", f.StudentID)
	}
	if f.From != nil {
		base = base.Where("create_time >= ?", *f.From)
	}
	if f.To != nil {
		base = base.Where("create_time < ?", *f.To)
	}
	var total int64
	if cErr := base.Count(&total).Error; cErr != nil {
		return nil, 0, infraerrors.WithCause(infraerrors.ErrDBError, cErr)
	}
	pageSize := page.Limit()
	rows := make([]model.UserDivideIntoLog, 0, pageSize)
	if qErr := base.Order("create_time DESC").Order("id DESC").
		Limit(pageSize).Offset(page.Offset()).Find(&rows).Error; qErr != nil {
		return nil, 0, infraerrors.WithCause(infraerrors.ErrDBError, qErr)
	}
	if rows == nil {
		rows = make([]model.UserDivideIntoLog, 0)
	}
	return rows, total, nil
}