DEV-MERGE-LEGACY-BACKEND-2026/internal/academic/service/divide_tree_service.go

// 分账树查询服务（端点 38 分账树 / 端点 43 分账流水）——AC-13。
//
// 依据：unified/03-migration/academic-frontend-contract-v1.md
//   - §3.4 B 表端点 38：`tree:[{userId, realName, parentUserId|null, quota:金额,
//     cumulativeIncome:金额, children:[…]}]`；**`quota` = 每次分成金额（`DECIMAL(12,2)`），
//     不是 0~1 比率**（§1.5 B2，mock 曾错成比率）
//   - §3.4 C 表端点 43：`分页`；行 `{id, findUserId, studentId, orderNo, money, remark, createTime}`；
//     该端点**无 dump SP 对照** ⇒ 排序与窗口由 Go 定（Go 新增查询）
//   - 设计 §3.3 #22~#25（分账 4 SP，AC-09 已交付）/ §1.7「全局无作用域表·例外二」
//
// ---------------------------------------------------------------------------
// 为什么本服务要做「树不变式校验」而不是直接拼 JSON
// ---------------------------------------------------------------------------
//
// Nested Set 的 `left_val/right_val` 是**位移**维护的（插入 +2、删除 −2），
// 一旦某次位移漏了一行或错了 root 限定，树的形状就坏了，但**单看某一行数据完全正常**：
// 响应体照常能拼出来、前端照常能渲染一棵"看起来对"的树。这类损坏的症状是
// "分账金额算错/某层级消失"，排查成本极高。
//
// 因此本服务在拼树的同时**断言四条不变式**（任何一条不成立就不返回树，直接报数据损坏）：
//
//	I1 `left < right` 且所有 `left/right` 恰为 `1..2N` 的**无重复无空洞**排列；
//	I2 任意两节点区间**嵌套或相离**（不允许部分重叠）；
//	I3 父区间**严格包含**子区间；
//	I4 `layer = parent.layer + 1`（根 `layer = 1`，且根的 `parent_user_id` 为 NULL）。
//
// 这四条正是"测试绿但树坏了"唯一能抓住的东西，也是端点 38 用例的断言主体。
package service

import (
	"context"
	"sort"
	"strings"
	"time"

	"gorm.io/gorm"

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

// RealNameResolver 用户姓名解析器（可选依赖；nil 时 `realName` 返回空串）。
//
// 为什么做成可选函数而不是硬编码查表：姓名住在 identity/org 域（`t_user.real_name`），
// academic 不持有该表的结构（设计 §1.3 跨域只读要经 port）。
// 生产装配由 AC-14 在 main 注入真实实现；未注入时字段留空——**不编造**姓名。
type RealNameResolver func(ctx context.Context, userIDs []string) (map[string]string, error)

// DivideTreeService 分账树 / 分账流水查询服务（只读，无事务）。
//
// 字段：
//   - repo 分账仓储（Nested Set 节点 + 流水）；
//   - names 姓名解析器（可 nil）；
//   - sc 请求作用域（可 nil：系统任务视角）。
type DivideTreeService struct {
	repo  *repository.DivideRepo
	names RealNameResolver
	sc    *appscope.Scope
	// db 数据库句柄（写路径编排用：`writer()` 现场装配 AC-09 的 `DivideService`）。
	db *gorm.DB
}

// NewDivideTreeService 构造分账查询服务。
//
// 入参：db *gorm.DB（必填）；sc *appscope.Scope（请求作用域）；names RealNameResolver（可 nil）。
// 出参：*DivideTreeService。
func NewDivideTreeService(db *gorm.DB, sc *appscope.Scope, names RealNameResolver) *DivideTreeService {
	return &DivideTreeService{repo: repository.NewDivideRepo(db), names: names, sc: sc, db: db}
}

// ---------------------------------------------------------------- 端点 38：分账树

// DivideTreeNode 分账树节点（契约 §3.4 B 表端点 38 逐字段对齐）。
//
// 量纲纪律（**mock 曾在此错一次**）：
//   - `Quota` = **金额**（元/次分成，`DECIMAL(12,2)`，两位小数字符串）；
//   - `CumulativeIncome` = **金额**（累计分成收入）。
//
// 两者都**不是** 0~1 的比率，也不得写成 number。
type DivideTreeNode struct {
	// UserID 节点用户（ULID）。
	UserID string `json:"userId"`
	// RealName 姓名（未注入姓名解析器时为空串——**不编造**）。
	RealName string `json:"realName"`
	// ParentUserID 上级用户（根为 null）。
	ParentUserID *string `json:"parentUserId"`
	// Quota 每次分成金额（元；`quota` 是金额不是比率）。
	Quota money.Amount `json:"quota"`
	// CumulativeIncome 累计分成收入（元）。
	CumulativeIncome money.Amount `json:"cumulativeIncome"`
	// Layer 层级（根=1；用于前端缩进与"层数上限 100"提示）。
	Layer int32 `json:"layer"`
	// Children 子节点（空 → `[]`，绝不 null）。
	Children []*DivideTreeNode `json:"children"`
}

// DivideTreeResult 分账树响应（**包一层 `tree`**，契约 §3.4 结构约定 2 的显式例外）。
type DivideTreeResult struct {
	// Tree 森林（多棵树时按根 user_id 升序；空 → `[]`）。
	Tree []*DivideTreeNode `json:"tree"`
	// NodeCount 节点总数（前端可做"共 N 人"提示，也便于对账）。
	NodeCount int `json:"nodeCount"`
	// RootCount 树的棵数（多根场景下前端分组渲染）。
	RootCount int `json:"rootCount"`
}

// GetTree 组装分账树并校验 Nested Set 不变式（端点 38）。
//
// 入参：ctx；rootUserID 可选（契约端点 38 的 `rootUserId?`：非空只取该棵树）。
// 出参：
//   - *DivideTreeResult：森林（按根 `user_id` 升序、子节点按 `left_val` 升序）；
//   - ErrInternal(5001) + 明确文案：**树不变式被破坏**（数据损坏，不能返回一棵"看起来对"的树）；
//   - ErrDBError(5002)：读库失败；金额字面量非法时同样 5002。
//
// 空表：返回 `{tree: [], nodeCount: 0, rootCount: 0}`（不是 nil、不是错误）。
func (s *DivideTreeService) GetTree(ctx context.Context, rootUserID string) (*DivideTreeResult, error) {
	rows, err := s.repo.ListAllNodes(ctx, strings.TrimSpace(rootUserID))
	if err != nil {
		return nil, err
	}
	if len(rows) == 0 {
		return &DivideTreeResult{Tree: []*DivideTreeNode{}, NodeCount: 0, RootCount: 0}, nil
	}
	if err := assertNestedSetInvariants(rows); err != nil {
		return nil, err
	}

	names := map[string]string{}
	if s.names != nil {
		ids := make([]string, 0, len(rows))
		for i := range rows {
			ids = append(ids, rows[i].UserID)
		}
		if resolved, nerr := s.names(ctx, ids); nerr == nil && resolved != nil {
			names = resolved
		}
		// 姓名解析失败**不阻断**树查询（姓名是展示位；树与金额才是数据）——
		// 这条与"金额/树结构任何异常都阻断"的不对称是有意的：前者是装饰、后者是对账依据。
	}

	nodes := make(map[string]*DivideTreeNode, len(rows))
	for i := range rows {
		quota, perr := money.Parse(rows[i].Quota)
		if perr != nil {
			return nil, infraerrors.WithCause(infraerrors.ErrDBError, perr)
		}
		income, perr := money.Parse(rows[i].TotalIncome)
		if perr != nil {
			return nil, infraerrors.WithCause(infraerrors.ErrDBError, perr)
		}
		nodes[rows[i].UserID] = &DivideTreeNode{
			UserID: rows[i].UserID, RealName: names[rows[i].UserID],
			ParentUserID: rows[i].ParentUserID, Quota: quota, CumulativeIncome: income,
			Layer: rows[i].Layer, Children: []*DivideTreeNode{},
		}
	}

	roots := make([]*DivideTreeNode, 0, 4)
	for i := range rows { // rows 已按 (root_user_id, left_val) 排序 ⇒ 子节点天然有序
		node := nodes[rows[i].UserID]
		if rows[i].ParentUserID == nil || strings.TrimSpace(*rows[i].ParentUserID) == "" {
			roots = append(roots, node)
			continue
		}
		parent, ok := nodes[*rows[i].ParentUserID]
		if !ok {
			// 父节点缺失 = 数据损坏（孤儿行）。dump 的 SP30 有"孤儿行跳过"先例（A16），
			// 但**查询树**不能静默丢行：丢行会让"分成总额少了某人"看起来像正常数据。
			return nil, infraerrors.WithCause(infraerrors.ErrInternal,
				errString("service: 分账树存在孤儿节点（parent_user_id 指向不存在的用户: "+
					*rows[i].ParentUserID+"）"))
		}
		parent.Children = append(parent.Children, node)
	}

	sort.Slice(roots, func(a, b int) bool { return roots[a].UserID < roots[b].UserID })
	return &DivideTreeResult{Tree: roots, NodeCount: len(rows), RootCount: len(roots)}, nil
}

// assertNestedSetInvariants 校验 Nested Set 四条不变式（I1~I4，见文件头）。
//
// 入参：rows 全部节点（**同一棵树内可比；多棵树按 root_user_id 分组后各自校验**）。
// 出参：nil 通过；ErrInternal(5001) + 具体违反项。
//
// 为什么不"自动修复"：位移错位无法从当前数据推断"原本该是多少"；
// 猜测式修复会把"确定性错误"变成"随机正确"。这里的职责是**让损坏可见**。
func assertNestedSetInvariants(rows []model.UserDivideInto) error {
	// 按 root 分组（root_user_id 为 NULL 时退化为自身为根）
	groups := map[string][]model.UserDivideInto{}
	order := make([]string, 0, 4)
	for i := range rows {
		root := rows[i].UserID
		if rows[i].RootUserID != nil && strings.TrimSpace(*rows[i].RootUserID) != "" {
			root = *rows[i].RootUserID
		}
		if _, ok := groups[root]; !ok {
			order = append(order, root)
		}
		groups[root] = append(groups[root], rows[i])
	}

	for _, root := range order {
		nodes := groups[root]
		// I1a：left < right
		seen := make(map[int32]string, len(nodes)*2)
		pairs := make([]struct{ left, right int32 }, 0, len(nodes))
		for i := range nodes {
			if nodes[i].LeftVal >= nodes[i].RightVal {
				return infraerrors.WithCause(infraerrors.ErrInternal,
					errString("service: 分账树不变式 I1 破（left >= right）: user="+nodes[i].UserID))
			}
			for _, v := range []int32{nodes[i].LeftVal, nodes[i].RightVal} {
				if v < 1 {
					return infraerrors.WithCause(infraerrors.ErrInternal,
						errString("service: 分账树不变式 I1 破（区间值 < 1）: user="+nodes[i].UserID))
				}
				if prev, dup := seen[v]; dup {
					return infraerrors.WithCause(infraerrors.ErrInternal,
						errString("service: 分账树不变式 I1 破（区间值重复 "+itoa32(v)+
							"：user="+prev+" 与 user="+nodes[i].UserID+"）"))
				}
				seen[v] = nodes[i].UserID
			}
			pairs = append(pairs, struct{ left, right int32 }{nodes[i].LeftVal, nodes[i].RightVal})
		}
		// I1b：恰为 1..2N 无空洞
		want := 2 * len(nodes)
		if len(seen) != want {
			return infraerrors.WithCause(infraerrors.ErrInternal,
				errString("service: 分账树不变式 I1 破（区间值数量 "+itoa32(int32(len(seen)))+
					" ≠ 2N="+itoa32(int32(want))+"）"))
		}
		for v := 1; v <= want; v++ {
			if _, ok := seen[int32(v)]; !ok {
				return infraerrors.WithCause(infraerrors.ErrInternal,
					errString("service: 分账树不变式 I1 破（区间值有空洞，缺 "+itoa32(int32(v))+"）"))
			}
		}
		// I2：任意两节点区间嵌套或相离（不允许部分重叠）
		for i := 0; i < len(pairs); i++ {
			for j := i + 1; j < len(pairs); j++ {
				a, b := pairs[i], pairs[j]
				nested := (a.left < b.left && b.right < a.right) || (b.left < a.left && a.right < b.right)
				disjoint := a.right < b.left || b.right < a.left
				if !nested && !disjoint {
					return infraerrors.WithCause(infraerrors.ErrInternal,
						errString("service: 分账树不变式 I2 破（区间部分重叠: ["+
							itoa32(a.left)+","+itoa32(a.right)+"] 与 ["+
							itoa32(b.left)+","+itoa32(b.right)+"]）"))
				}
			}
		}
	}

	// I3/I4：父区间严格包含子区间 + layer = parent.layer + 1
	byUser := make(map[string]model.UserDivideInto, len(rows))
	for i := range rows {
		byUser[rows[i].UserID] = rows[i]
	}
	for i := range rows {
		node := rows[i]
		if node.ParentUserID == nil || strings.TrimSpace(*node.ParentUserID) == "" {
			if node.Layer != 1 {
				return infraerrors.WithCause(infraerrors.ErrInternal,
					errString("service: 分账树不变式 I4 破（根节点 layer≠1）: user="+node.UserID))
			}
			continue
		}
		parent, ok := byUser[*node.ParentUserID]
		if !ok {
			return infraerrors.WithCause(infraerrors.ErrInternal,
				errString("service: 分账树不变式 I3/I4 破（父节点不存在）: user="+node.UserID))
		}
		if !(parent.LeftVal < node.LeftVal && node.RightVal < parent.RightVal) {
			return infraerrors.WithCause(infraerrors.ErrInternal,
				errString("service: 分账树不变式 I3 破（父区间未严格包含子区间）: user="+node.UserID))
		}
		if node.Layer != parent.Layer+1 {
			return infraerrors.WithCause(infraerrors.ErrInternal,
				errString("service: 分账树不变式 I4 破（layer≠parent.layer+1）: user="+node.UserID))
		}
	}
	return nil
}

// itoa32 最小 int32 → string 转换（避免为一个错误文案引入 strconv 依赖）。
//
// 入参：v 整数。出参：十进制字符串（负数带前导 '-'）。
func itoa32(v int32) string {
	if v == 0 {
		return "0"
	}
	negative := v < 0
	if negative {
		v = -v
	}
	buf := [12]byte{}
	pos := len(buf)
	for v > 0 {
		pos--
		buf[pos] = byte('0' + v%10)
		v /= 10
	}
	if negative {
		pos--
		buf[pos] = '-'
	}
	return string(buf[pos:])
}

// ---------------------------------------------------------------- 端点 43：分账流水

// DivideLogQuery 分账流水查询入参（端点 43）。
type DivideLogQuery struct {
	// FindUserID 分成获得者（空 = 不筛）。
	FindUserID string
	// StudentID 学生（空 = 不筛）。
	StudentID string
	// From 起始时间（含；零值 = 不筛）。
	From *time.Time
	// To 结束时间（**不含**；零值 = 不筛）。
	To *time.Time
	// Page / PageSize 分页（<=0 归一；>200 钳 200）。
	Page     int
	PageSize int
}

// DivideLogView 分账流水行（契约 §3.4 C 表端点 43 逐字段）。
type DivideLogView struct {
	// ID 流水 ID。
	ID int64 `json:"id"`
	// FindUserID 分成获得者（ULID）。
	FindUserID string `json:"findUserId"`
	// StudentID 学生（ULID）。
	StudentID string `json:"studentId"`
	// OrderNo 订单号（可空 → ""）。
	OrderNo string `json:"orderNo"`
	// Money 分成金额（元）。
	Money money.Amount `json:"money"`
	// Remark 备注。
	Remark string `json:"remark"`
	// CreateTime 业务时间（RFC3339）。
	CreateTime time.Time `json:"createTime"`
}

// ListLogs 分页查分账流水（端点 43）。
//
// 入参：ctx；q DivideLogQuery。
// 出参：([]DivideLogView, total, error)；`from > to` → 2001。
func (s *DivideTreeService) ListLogs(ctx context.Context, q DivideLogQuery) ([]DivideLogView, int64, error) {
	if q.From != nil && q.To != nil && q.From.After(*q.To) {
		return nil, 0, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("service: 分账流水的 from 不能晚于 to"))
	}
	page := repository.PageQuery{Page: q.Page, PageSize: q.PageSize}
	rows, total, err := s.repo.ListLogsFiltered(ctx, repository.DivideLogFilter{
		FindUserID: strings.TrimSpace(q.FindUserID),
		StudentID:  strings.TrimSpace(q.StudentID),
		From:       q.From, To: q.To,
	}, page)
	if err != nil {
		return nil, 0, err
	}
	views := make([]DivideLogView, 0, len(rows))
	for i := range rows {
		amount, perr := money.Parse(rows[i].Money)
		if perr != nil {
			return nil, 0, infraerrors.WithCause(infraerrors.ErrDBError, perr)
		}
		view := DivideLogView{
			// 表列 `user_id` → 契约响应字段 `findUserId`（名字听前端的，语义听 dump 的）
			ID: rows[i].ID, FindUserID: rows[i].UserID, StudentID: rows[i].StudentID,
			Money: amount, CreateTime: rows[i].CreateTime,
		}
		if rows[i].OrderNo != nil {
			view.OrderNo = *rows[i].OrderNo
		}
		if rows[i].Remark != nil {
			view.Remark = *rows[i].Remark
		}
		views = append(views, view)
	}
	return views, total, nil
}

// ---------------------------------------------------------------- 端点 39 / 40：加入下线 / 改额度

// AddMemberResult 加入下线结果（端点 39 响应 `{ancestorIds:[]}`）。
type AddMemberResult struct {
	// AncestorIDs 新节点的祖先链（由外向内；**不含自身**）。
	AncestorIDs []string `json:"ancestorIds"`
}

// AddMember 加入下线（端点 39 `POST /admin/divide-into/members`）。
//
// 入参：ctx；parentUserID 上级（ULID）；subUserID 下线（ULID）。
// 出参：*AddMemberResult（祖先链）；错误码 2001/3111（深度超 100）/5002。
//
// 编排说明：写动作复用 **AC-09 已交付的 `DivideService.AddSubordinate`**（本服务不重写位移逻辑）；
// 随后读一次新节点的祖先链返回给前端（dump `divide_into_add` 末尾的 `SELECT userid` 就是它）。
// ⚠ 新节点 `quota` 默认 **0.00**（D6/DDL 默认）⇒ 建完必须调端点 40 设额度，否则该链
// **一分钱都不分成且不报错**（静默不入账，契约 §2.3 已提示前端引导用户设额度）。
func (s *DivideTreeService) AddMember(ctx context.Context, parentUserID, subUserID string) (*AddMemberResult, error) {
	if strings.TrimSpace(parentUserID) == "" || strings.TrimSpace(subUserID) == "" {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam,
			errString("service: AddMember 需要 parentUserId 与 subUserId"))
	}
	if err := s.writer().AddSubordinate(ctx, parentUserID, subUserID); err != nil {
		return nil, err
	}
	node, err := s.repo.GetByUserID(ctx, subUserID)
	if err != nil {
		return nil, err
	}
	root := subUserID
	if node.RootUserID != nil && strings.TrimSpace(*node.RootUserID) != "" {
		root = *node.RootUserID
	}
	ids, err := s.repo.ListAncestorIDs(ctx, node.LeftVal, node.RightVal, root)
	if err != nil {
		return nil, err
	}
	if ids == nil {
		ids = []string{}
	}
	return &AddMemberResult{AncestorIDs: ids}, nil
}

// SetQuotaResult 改额度结果（端点 40 响应 `{affectedUserIds:[]}`）。
type SetQuotaResult struct {
	// AffectedUserIDs 受影响用户（**含自身**；dump 末尾 `LEFT>=uLeft AND RIGHT<=uRight AND quota>=newQuota`）。
	AffectedUserIDs []string `json:"affectedUserIds"`
}

// SetQuota 改分成额度（端点 40 `PUT /admin/divide-into/members/:userId/quota`）。
//
// 入参：ctx；userID 节点；quota 新额度（**金额**，`DECIMAL(12,2)` —— 不是 0~1 比率）。
// 出参：*SetQuotaResult；错误码 2001/2002（quota 非法）/3111（**子额度 > 父额度**，见下）/3001/5002。
//
// 3111 的判据（**必须精确，mock 曾把 quota 当比率而写错**）：
// **「新额度 > 父节点额度」** 才 3111 —— 不是 `quota > 1`、也不是比率越界。
// 该判据由 AC-09 的 `DivideService.UpdateQuota` 实现（dump 无此校验，属 D9 有意增强），
// 本方法**只编排、不重复实现**：先写（含子树级联下降），再读一次受影响列表。
func (s *DivideTreeService) SetQuota(ctx context.Context, userID string, quota money.Amount) (*SetQuotaResult, error) {
	if strings.TrimSpace(userID) == "" {
		return nil, infraerrors.WithCause(infraerrors.ErrBadParam, errString("service: SetQuota 需要 userId"))
	}
	if err := quota.Validate(); err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrBadFormat, err)
	}
	if quota.IsNegative() {
		return nil, infraerrors.WithCause(infraerrors.ErrBadFormat,
			errString("service: 分成额度不能为负（quota 是金额，不是比率）"))
	}
	if err := s.writer().UpdateQuota(ctx, userID, quota); err != nil {
		return nil, err
	}
	node, err := s.repo.GetByUserID(ctx, userID)
	if err != nil {
		return nil, err
	}
	ids, err := s.repo.ListSubtreeUserIDsWithQuotaAtLeast(ctx, node.LeftVal, node.RightVal, quota)
	if err != nil {
		return nil, err
	}
	if ids == nil {
		ids = []string{}
	}
	return &SetQuotaResult{AffectedUserIDs: ids}, nil
}

// writer 取写路径服务（AC-09 已交付的 `DivideService`；本服务只编排、不重写位移/级联逻辑）。
func (s *DivideTreeService) writer() *DivideService {
	// firstCharged 传 nil：端点 39/40 不触碰"首扣记录"判据（那是端点 42 撤销路径的依赖），
	// 只有调用 `RevokeLog` 才需要它 —— 本服务不调，故 nil 安全（若将来调用会得到显式错误而非 panic）。
	return NewDivideService(s.db, nil)
}

// AddLog 记分账流水（端点 41）——**转调 AC-09 的 `DivideService.AddLog`**，不重复实现上行链。
//
// 入参：ctx；findUserID 起点（**本人不拿分成，从 parent 起上行**）；stuID 学生；orderNo 订单/上课记录号；remark 备注。
// 出参：2001/2002/3111/3001/5002（由 AC-09 实现给出）。
//
// ⚠ 排查顺序（设计 §3.3 #21 连锁陷阱，三条成因**有且只有三条**）：
//
//	① 节点 `quota=0`（新建默认值，最常见）；② `findUserID` 本身是根（无父 → 正确空结果）；
//	③ `findUserID` 不是树节点（未入体系 → 静默不入账，也是正确行为）。
func (s *DivideTreeService) AddLog(ctx context.Context, findUserID, stuID string, orderNo int64, remark string) error {
	return s.writer().AddLog(ctx, findUserID, stuID, orderNo, remark)
}

// RevokeLog 撤销分账流水（端点 42）——**转调 AC-09 的 `DivideService.DeleteLog`**。
//
// D11 已拍板（按 dump）：存在「首扣记录」即**改绑保留**（`total_income` 不回滚），
// 仅无首扣记录时才回滚并物理删除。该判据依赖 `FirstChargedRecordReader`，
// 故本方法的 writer 必须注入真实 reader（见 `writerWithFirstCharged`）。
func (s *DivideTreeService) RevokeLog(ctx context.Context, stuID string, orderNo int64) error {
	return s.writerWithFirstCharged().DeleteLog(ctx, stuID, orderNo)
}

// writerWithFirstCharged 取注入首扣读取器的写服务（撤销路径**必须**有它，否则无法判"是否首扣"）。
//
// 说明：`port.NewOrgFirstChargedReader(db)` 是 AC-11 交付的真实实现（读 `t_courses_record_student`）；
// 若装配失败/表缺失，`DeleteLog` 会返回显式错误而不是静默按"无首扣"处理（防误回滚分成）。
func (s *DivideTreeService) writerWithFirstCharged() *DivideService {
	var reader FirstChargedRecordReader
	if s.db != nil {
		// AC-11 交付的真实实现（`repository.RecordRepo.FirstChargedRecordID`，四个谓词逐字对齐 dump 763811）。
		// 作用域传 nil：撤销路径按 `student_id` 精确取数（该实现内部不依赖 scoping），
		// 越权由端点角色白名单 + `mustScope` 保证（分账是全局域，见 handler 文件头）。
		reader = repository.NewRecordRepo(s.db, nil)
	}
	return NewDivideService(s.db, reader)
}