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

// 分账服务（Nested Set 树维护 + 上行分成 + 撤销 + 额度级联）——AC-09。
//
// 依据：unified/03-migration/academic-domain-design.md §3.3 #22~#25（分账 4 SP）
// / §1.7（全局无作用域表）/ §10.3（事务边界只在 Service）/ §11.1 拍板 11-12。
//
// 四个 SP 的 Go 化落点：
//
//	divide_into_add          → AddSubordinate（**服务端算左右值**，dump 2 参语义：只传上下级）
//	divide_into_log_add      → AddLog（上行链入账；**递归改迭代 BFS**，深度上限 100）
//	divide_into_log_delete   → DeleteLog（两分支：改绑 / 回滚删除，dump 2 参语义：studentid + orderid）
//	divide_into_update_quota → UpdateQuota（改额度 + 子树级联下降，子不得超父 → 3111）
//
// 事务纪律：所有写路径走 `repository.TxRunner.WithinTx`；事务内下游调用一律传
// `repository.WithTxContext(ctx, tx)` 注入的 ctx（读方法自动复用同一 tx，见仓储 db(ctx)）。
// 禁止在本服务内直接调用 `db.Transaction`（嵌套只允许经 TxRunner 透传）。
//
// 金额纪律：库里 quota / total_income / money 均为 decimal(12,2) 字符串列，
// 一律 `money.Parse` 转 money.Amount（int64 分）后运算，**零 float64**。
package service

import (
	"context"
	"errors"
	"strconv"
	"strings"

	"gorm.io/gorm"

	"yuansiwei/unified-backend/internal/academic/apperr"
	"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"
)

// MaxDivideDepth 是分账树的**结构上限**（根 layer=1；超限 → apperr.ErrDivideQuotaExceeded 3111）。
//
// 它的含义**不是**业务规则，而是"算法必须终止"的安全阀：AddSubordinate 要插链，
// 撤销/入账分支还要沿 parent 链做**上行 BFS**，一旦数据成环或链路极长，
// 递归会爆栈、BFS 会不终止。所以这个数字与"业务上最多几层"无关，
// **不要**用它表达业务规则（业务规则是下面的 MaxDivideBizDepth）。
//
// 依据：模型注释 layer「深度上限 100（超限 → 3111，防递归栈溢出）」+ dump 的层数保护。
// BFS 迭代在本上限内必然终止（即使数据成环也不会死循环）。
//
// ⚠ 与 MaxDivideBizDepth 是**两个不同概念，不要合并、也不要用其中一个替掉另一个**：
//   - MaxDivideDepth（本常量，100）= 结构上限，防不终止/爆栈，正常业务永远碰不到；
//   - MaxDivideBizDepth（100 之外的那个，3）= 业务上限，超管 → 校区主任 → 老师，第 4 层直接拒。
//
// 两者唯一的收敛点都是 AddSubordinate，但判定顺序固定为**先 3 后 100**
// （3 是更常见的失败，先判能给出更准确的错误语义）。
const MaxDivideDepth int32 = 100

// MaxDivideBizDepth 是分账层级的**业务规则**上限：最多 3 层（超管 → 校区主任 → 老师）。
// 超限一律 apperr.ErrDivideQuotaExceeded（3111），与其它三种 3111 语义共用错误码、靠 message 区分。
//
// 拍板日期 2026-11-10（业务确认为**硬规则**，不是建议）。
//
// 存量实测（2026-11-10）：三个库 `t_user_divide_into` 均为 `MAX(layer)=2`、`layer>3` **0 行**
// ⇒ 本规则与存量数据不矛盾，**无需存量豁免（grandfather）**，也不需要迁移/清洗。
// （写这句不是为了留证据，是让下一个人不必再查一遍、也不必再怀疑"这规则是不是忘了考虑存量"。）
//
// 出处（已按本机前端仓实读校正，不是转述）：
//
//	DEV-MERGE-LEGACY-PC-FRONTEND-2026/src/api/mock/routes/divide-into.ts:32
//	const MAX_DIVIDE_DEPTH = 3;
//	:107  if (parent.layer >= MAX_DIVIDE_DEPTH) return fail(3111, '分账层级超限（最多 3 层）');
//
// 判据等价：mock 的 `parent.layer >= 3` ⇔ 本服务的 `parent.Layer+1 > 3`（即 nextLayer > 3），
// 同一个边界、同一个 3111、同一个"第 4 层被拒"语义 —— 前后端不会出现"前端不让点、
// 后端却能建"或"后端拒了、前端以为能建"的错位。
// （注：mock 里那句注释「B-2 待业务拍板，暂保留 3」已过期，2026-11-10 已成硬规则。）
//
// 为什么必须落在后端而不是只靠前端常量：mock 里的常量只保证"界面上不让你点"。
// 真后端一旦没有这道校验，绕过前端（或第三方直接调 API）就能建出第 4 层，
// 而前端的树渲染与分成计算都按 3 层假设实现 ⇒ 联调时一切正常，上线后才发现数据坏。
//
// ⚠ 与 MaxDivideDepth（100，结构上限）**不是同一个概念，不要合并**，理由见上方注释。
const MaxDivideBizDepth int32 = 3

// remarkRebind 撤销改绑分支写入的备注文案（dump 原样："推广分成"）。
const remarkRebind = "推广分成"

// FirstChargedRecordReader 首次扣费上课记录只读端口（跨聚合依赖，本服务**只定义契约**）。
//
// 为什么用端口而不是直接 JOIN：`log_delete` 的改绑分支需要判断"学生是否已有首次扣费上课记录"，
// 该判定属于课次/打卡聚合（AC-05/AC-10 范围）。AC-09 不实现它，只声明只读契约 + 允许注入；
// 未注入时**所有撤销走回滚删除分支**（保守：不让分成悬空在多订单上）。
//
// 契约（**取数口径已写死，实现方不得自选**，dump `yuansiwei_finance.sql:763811`）：
//   - **4 个谓词缺一不可**：`student_id`（本人）、`cost > 0`（真扣费，排除免费/试听）、
//     `end_time IS NOT NULL`（已结课，未结课不算"首次扣费"）、`ORDER BY start_time ASC LIMIT 1`（最早）；
//   - **返回的是 `recordid` 列，不是 `record_student.id`**（dump 原文取 recordid；
//     取错列会让撤销时的 order_no 与明细侧对不上 → 改绑失效、分成悬空）；
//   - 只读，禁止写任何表；
//   - 返回 (recordID, found, err)：found=false 表示学生尚无扣费记录 → 走回滚删除分支；
//   - err 仅 DB 异常（infraerrors.ErrDBError），不得返回业务错误。
//
// 参考 SQL（口径以此为准）：
//
//	SELECT recordid FROM t_courses_record_student
//	 WHERE student_id = ? AND cost > 0 AND end_time IS NOT NULL
//	 ORDER BY start_time ASC LIMIT 1;
type FirstChargedRecordReader interface {
	// FirstChargedRecordID 取该学生"首次扣费上课记录"的 ID。
	//
	// 入参：ctx 请求上下文；studentID 报课学生（canonical_user_id ULID）。
	// 出参：recordID int64（上课记录 ID）；found bool；error。
	FirstChargedRecordID(ctx context.Context, studentID string) (recordID int64, found bool, err error)
}

// DivideService 分账服务（全局推广体系；越权防线在 Handler 角色白名单，本服务不做租户裁剪）。
type DivideService struct {
	// repo 分账树仓储（全局数据，不继承 BaseRepo）。
	repo *repository.DivideRepo
	// runner 事务运行器（顶层开事务，事务内透传）。
	runner *repository.TxRunner
	// firstCharged 首次扣费记录端口（可 nil：未注入时撤销一律走回滚删除）。
	firstCharged FirstChargedRecordReader
}

// NewDivideService 构造分账服务（repo 与 runner 绑定同一 DB 句柄，避免跨连接池事务失效）。
//
// 入参：
//   - db *gorm.DB：数据库句柄（必填）。
//   - firstCharged FirstChargedRecordReader：首次扣费记录端口（可 nil）。
//
// 出参：*DivideService。
func NewDivideService(db *gorm.DB, firstCharged FirstChargedRecordReader) *DivideService {
	return &DivideService{
		repo:         repository.NewDivideRepo(db),
		runner:       repository.NewTxRunner(db),
		firstCharged: firstCharged,
	}
}

// AddSubordinate 把 subUserID 挂为 parentUserID 的下级（dump `divide_into_add` 2 参语义）。
//
// 入参：
//   - ctx 请求上下文；
//   - parentUserID 上级用户（ULID；必须已是树节点，否则 3001）；
//   - subUserID 下级用户（ULID；== parentUserID → 3140，禁止自环）。
//
// 出参：
//   - nil：成功（新建节点，或"已存在节点"分支改挂成功）；
//   - ErrNotFound(3001)：上级不存在或不在分账体系；
//   - ErrDivideQuotaExceeded(3111)：层级超限。**有两种语义，文案不同、判序不同**：
//     ① 业务上限：父 layer+1 > MaxDivideBizDepth(3) —— 超管→校区主任→老师，第 4 层直接拒；
//     ② 结构上限：父 layer+1 > MaxDivideDepth(100) —— 纯粹的数据结构自保，防止 BFS 不终止；
//   - ErrBusinessParam(3140)：入参非法。
//
// 层级判定严格按「先 ① 后 ②」：3 是业务规则的常规失败点（用户操作就会撞到），
// 100 是异常数据的兜底（正常业务撞不到）。顺序反了会把"业务上不让建"错报成"数据异常"。
//
// 左右值算法（Nested Set 插入最右子节点，**服务端计算**，调用方不传 left/right）：
//
//	① 父节点右值 R = parent.right_val（插入点）
//	② ShiftRight(R, +2)：right_val >= R 全体 +2 → 父节点及其**全部祖先**区间右移
//	③ ShiftLeft (R, +2)：left_val  >= R 全体 +2 → 位于插入点右侧的兄弟及其后代右移
//	④ 新节点 (left, right) = (R, R+1)，layer = parent.layer+1，root = 父的树根
//
// 不变式：①②③④ 必须在同一事务内完成（否则中间态树不可用）；完成后恒有 left < right。
//
// 已存在节点分支（audit D4，dump `yuansiwei_finance.sql:763695`）：
//
//	dump 的判断是 `if exists(select 1 from t_user_divide_into where userid = subid) then ... end if;`
//	分支体内**没有**任何改挂父链的动作 —— 即"已存在 = 完全 no-op（幂等成功，返回 nil）"。
//	本实现按 dump 对齐：不再改 parent/root/layer（改挂会凭空移动整棵子树且不重排左右值，
//	直接破坏嵌套集不变式）。
func (s *DivideService) AddSubordinate(ctx context.Context, parentUserID, subUserID string) error {
	parentUserID = strings.TrimSpace(parentUserID)
	subUserID = strings.TrimSpace(subUserID)
	if parentUserID == "" || subUserID == "" {
		return infraerrors.WithCause(apperr.ErrBusinessParam, errString("service: AddSubordinate 需要 parent/sub user id"))
	}
	if parentUserID == subUserID {
		return infraerrors.WithCause(apperr.ErrBusinessParam, errString("service: 下级不能是自身（禁止成环）"))
	}
	if err := s.assertReady(); err != nil {
		return err
	}

	return s.runner.WithinTx(ctx, func(tx *gorm.DB) error {
		txCtx := repository.WithTxContext(ctx, tx)

		parent, err := s.repo.GetByUserID(txCtx, parentUserID)
		if err != nil {
			return err // ErrNotFound(3001) 原样上抛：上级未加入分账体系
		}
		nextLayer := parent.Layer + 1
		// ① 业务规则（先判）：最多 3 层 —— 超管 → 校区主任 → 老师。拍板 2026-11-10。
		//    放前面是因为它才是**用户真会撞到**的那条；100 那条正常业务永远撞不到。
		//    文案与 ② 必须可区分：① 是产品限制（"你不能再往下建了"），
		//    ② 是数据结构自保（"链路长得不正常，可能是脏数据/成环"）。
		if nextLayer > MaxDivideBizDepth {
			return infraerrors.WithCause(apperr.ErrDivideQuotaExceeded,
				errString("service: 分账层级超业务上限（最多 "+strconv.Itoa(int(MaxDivideBizDepth))+
					" 层：超管→校区主任→老师），目标层级 "+strconv.Itoa(int(nextLayer))))
		}
		// ② 结构上限（纵深防御，保留不动）：防上行 BFS 不终止 / 递归爆栈。
		//    与 ① 不是同一个概念，见 MaxDivideDepth 的注释；删掉它会让脏数据把服务拖死。
		if nextLayer > MaxDivideDepth {
			return infraerrors.WithCause(apperr.ErrDivideQuotaExceeded,
				errString("service: 分账层级超结构上限 "+strconv.Itoa(int(MaxDivideDepth))+
					"，目标层级 "+strconv.Itoa(int(nextLayer))))
		}

		rootID := resolveRoot(parent)

		_, err = s.repo.GetByUserID(txCtx, subUserID)
		switch {
		case err == nil:
			// ── 已存在节点：完全 no-op（dump 763695 的分支体没有任何写动作）
			return nil
		case !errors.Is(err, infraerrors.ErrNotFound):
			return err
		}

		// ── 新建节点分支：嵌套集"插入最右子节点"
		insertAt := parent.RightVal
		// root 限定（audit V-02）：位移只作用于本树，否则会串改同库其它树的左右值区间
		if _, serr := s.repo.ShiftRight(txCtx, tx, rootID, insertAt, 2); serr != nil {
			return serr
		}
		if _, serr := s.repo.ShiftLeft(txCtx, tx, rootID, insertAt, 2); serr != nil {
			return serr
		}
		parentID := parentUserID
		node := &model.UserDivideInto{
			UserID: subUserID,
			// audit D6：新节点固定「一次付清(1)」，**不继承父**（dump 763714 的 INSERT 不写 type，
			// 落 DDL 默认值 1）。继承父会把"按课次"格式传染整条下级链 → 幂等维度(1 vs 2)跟着错。
			Type:             model.DivideTypeOneOff,
			Quota:            "0.00", // 新节点额度由后台 UpdateQuota 配置（默认 0，且不得超父）
			TotalIncome:      "0.00",
			TotalIncomePayed: "0.00",
			RootUserID:       &rootID,
			ParentUserID:     &parentID,
			LeftVal:          insertAt,
			RightVal:         insertAt + 1,
			Layer:            nextLayer,
		}
		if ierr := s.repo.InsertNode(txCtx, tx, node); ierr != nil {
			return ierr
		}
		return nil
	})
}

// AddLog 上行分成入账（dump `divide_into_log_add`；**递归改迭代 BFS**）。
//
// 入参：
//   - ctx 请求上下文；
//   - findUserID 起始用户（ULID；通常是直接推荐人）；
//   - stuID 报课学生（ULID；幂等键组成列）；
//   - recordID 上课记录 ID（int64；写入 order_no 作为 type=2 的幂等键，dump 传 orderid 语义）；
//   - remark 备注（可空；空则落 NULL）。
//
// 出参：
//   - nil：成功（含"起始用户不是树节点 → 不入账"的空操作、以及幂等命中）；
//   - ErrDivideQuotaExceeded(3111)：上行层数超 100（数据成环/异常链）；
//   - ErrBusinessParam / ErrDBError；
//   - 若节点 quota 金额被写坏（非十进制）→ ErrDBError（数据异常，不静默归零）。
//
// 上行链语义（**逐字对齐 dump `yuansiwei_finance.sql:763744`**）：
//
//	DECLARE cur CURSOR FOR SELECT userid,type,parent_userid,quota FROM t_user_divide_into
//	 WHERE userid = (SELECT parent_userid FROM t_user_divide_into WHERE userid = findUserid);
//
// 起点 = **findUserid 的上级**（本人不参与分成，本人只是"被推荐人"），随后逐级上溯 parent_user_id，
// 每级生成一条明细（money = 该级节点的 quota 快照）并累加该节点 total_income，到根（parent 为 NULL）终止。
// findUserid 是根（其 parent_user_id 为 NULL）或本身不是树节点 → 子查询为 NULL → **无明细且不报错**
// （静默不入账，与 dump 的子查询语义一致）。
//
// 幂等（两级，设计 §3.3 #22，**同事务内逐级判定**）：
//   - 节点 type=1（一次付清）：同 (user, student) 只生成一条 → 后续不同 recordID 也不重复入账；
//   - 节点 type=2（按课次）  ：同 (user, student, order_no) 只生成一条。
//
// 为什么用迭代：链深可达 100，递归在极端脏数据下会栈溢出；迭代 + 显式层数计数可兜底成环。
func (s *DivideService) AddLog(ctx context.Context, findUserID, stuID string, recordID int64, remark string) error {
	findUserID = strings.TrimSpace(findUserID)
	stuID = strings.TrimSpace(stuID)
	if findUserID == "" || stuID == "" {
		return infraerrors.WithCause(apperr.ErrBusinessParam, errString("service: AddLog 需要 findUserID/stuID"))
	}
	if recordID <= 0 {
		return infraerrors.WithCause(apperr.ErrBusinessParam, errString("service: AddLog 需要 recordID > 0"))
	}
	if err := s.assertReady(); err != nil {
		return err
	}
	orderNo := strconv.FormatInt(recordID, 10)

	return s.runner.WithinTx(ctx, func(tx *gorm.DB) error {
		txCtx := repository.WithTxContext(ctx, tx)

		// ① 定位 findUserid 的**上级**（dump 子查询口径）：本人不参与分成
		self, err := s.repo.GetByUserID(txCtx, findUserID)
		if errors.Is(err, infraerrors.ErrNotFound) {
			// 红线（模型注释）：必须是分账树节点才入账；非节点 → 静默不入账（不是错误）
			return nil
		}
		if err != nil {
			return err
		}
		if self.ParentUserID == nil || strings.TrimSpace(*self.ParentUserID) == "" {
			// findUserid 是根：dump 子查询返回 NULL → 无明细（幂等空操作）
			return nil
		}
		startID := strings.TrimSpace(*self.ParentUserID)
		if startID == self.UserID {
			return infraerrors.WithCause(apperr.ErrDivideQuotaExceeded,
				errString("service: 分账树自环（parent 指向自身）"))
		}

		cur, err := s.repo.GetByUserID(txCtx, startID)
		if errors.Is(err, infraerrors.ErrNotFound) {
			return nil // 断链（上级已不在树中）：无明细（与 dump 子查询 NULL 同效）
		}
		if err != nil {
			return err
		}

		for depth := int32(0); cur != nil; depth++ {
			if depth >= MaxDivideDepth {
				return infraerrors.WithCause(apperr.ErrDivideQuotaExceeded,
					errString("service: 上行分成层级超上限（疑似成环） "+strconv.Itoa(int(MaxDivideDepth))))
			}
			if err := s.appendShare(txCtx, tx, cur, stuID, orderNo, remark); err != nil {
				return err
			}
			if cur.ParentUserID == nil || strings.TrimSpace(*cur.ParentUserID) == "" {
				break // 到根
			}
			parentID := strings.TrimSpace(*cur.ParentUserID)
			if parentID == cur.UserID {
				return infraerrors.WithCause(apperr.ErrDivideQuotaExceeded,
					errString("service: 分账树自环（parent 指向自身）"))
			}
			next, perr := s.repo.GetByUserID(txCtx, parentID)
			if errors.Is(perr, infraerrors.ErrNotFound) {
				break // 断链（上级已不在树中）：终止上行，已入账部分保留
			}
			if perr != nil {
				return perr
			}
			cur = next
		}
		return nil
	})
}

// appendShare 为单个节点生成分成明细并累加 total_income（AddLog 的迭代体）。
//
// 入参：txCtx（含 tx 的 ctx）；tx；node 当前节点；stuID 学生；orderNo 订单号；remark 备注。
// 出参：nil 成功/幂等命中；ErrDBError。
//
// 幂等判定经 repository.FindLog（两级键口径唯一入口），命中即跳过（**不返回错误**，
// 对外语义是"重复请求幂等成功"，与设计 §10.1 的 3114 仅内部日志口径一致）。
func (s *DivideService) appendShare(txCtx context.Context, tx *gorm.DB, node *model.UserDivideInto, stuID, orderNo, remark string) error {
	if node == nil {
		return nil
	}
	_, err := s.repo.FindLog(txCtx, node.UserID, stuID, node.Type, orderNo)
	switch {
	case err == nil:
		return nil // 幂等命中：该 (user, student[, order]) 已有分成
	case !errors.Is(err, infraerrors.ErrNotFound):
		return err
	}

	amount, perr := parseAmount(node.Quota)
	if perr != nil {
		return perr
	}
	// audit D2（dump 763760）：额度 <= 0 的节点**不生成明细**（也不累加 total_income）。
	// 否则会给 0 元分成写一条"流水"，把"明细条数 = 实际发钱次数"这个对账恒等式打破。
	if !amount.GreaterThan(0) {
		return nil
	}
	row := &model.UserDivideIntoLog{
		Type:      node.Type,
		UserID:    node.UserID,
		StudentID: stuID,
		OrderNo:   stringPtr(orderNo),
		Money:     amount.String(),
		Remark:    optionalString(remark),
	}
	if ierr := s.repo.InsertLog(txCtx, tx, row); ierr != nil {
		return ierr
	}
	if _, ierr := s.repo.IncTotalIncome(txCtx, tx, node.UserID, amount); ierr != nil {
		return ierr
	}
	return nil
}

// DeleteLog 撤销某「学生 + 订单」产生的全部分成（dump `divide_into_log_delete` 2 参语义）。
//
// 入参：
//   - ctx 请求上下文；
//   - stuID 报课学生（ULID）；
//   - orderID 订单/上课记录 ID（int64；dump 传 orderid）。
//
// 出参：
//   - nil：成功（含"无对应明细"的幂等空操作）；
//   - ErrBusinessParam / ErrDBError（含端口返回的 DB 异常）。
//
// 两分支（audit D11 按 dump 定稿，**顺序不可颠倒**）：
//
//	① 改绑（保留分成）：**只要**学生存在首次扣费上课记录 first
//	   → 该组明细的 order_no 一律改为 first、create_time 重置为 now()、备注写"推广分成"，
//	   total_income **不回滚**；
//	② 回滚删除：**仅**在无 first 记录时 → total_income -= money（冲正）并物理删除明细行。
//
// 关键改动（D11）：去掉旧实现里的 `first != orderID` 条件 —— dump 762547 的改绑分支不做这个比较，
// 撤的正是"当前这单"，而它自己就是首扣记录；带条件会把它判成"无可改绑"→ 误走回滚删除，
// 把真实产生的分成整组冲掉（少发钱）。
//
// 说明：同一订单的分成会沿上行链生成多行（本人 + 各级上线），故按 (student, order) 取全量
// 逐行处理，而不是只处理一行（否则上级分成会悬空）。
func (s *DivideService) DeleteLog(ctx context.Context, stuID string, orderID int64) error {
	stuID = strings.TrimSpace(stuID)
	if stuID == "" || orderID <= 0 {
		return infraerrors.WithCause(apperr.ErrBusinessParam, errString("service: DeleteLog 需要 stuID/orderID"))
	}
	if err := s.assertReady(); err != nil {
		return err
	}
	orderNo := strconv.FormatInt(orderID, 10)

	return s.runner.WithinTx(ctx, func(tx *gorm.DB) error {
		txCtx := repository.WithTxContext(ctx, tx)

		rows, err := s.repo.ListLogsByStudentOrder(txCtx, stuID, orderNo)
		if err != nil {
			return err
		}
		if len(rows) == 0 {
			return nil // 已撤销/从未生成：幂等空操作
		}

		// 首次扣费记录（端口未注入 → 一律走回滚删除分支）
		var firstID int64
		var hasFirst bool
		if s.firstCharged != nil {
			firstID, hasFirst, err = s.firstCharged.FirstChargedRecordID(txCtx, stuID)
			if err != nil {
				return err
			}
		}
		rebindTo := ""
		if hasFirst && firstID > 0 {
			// D11：有首扣记录就改绑，**不与当前 orderID 比较**（dump 762547）
			rebindTo = strconv.FormatInt(firstID, 10)
		}

		for i := range rows {
			row := &rows[i]
			if rebindTo != "" {
				// ① 改绑分支：保留分成，仅改幂等键指向首次扣费订单
				if _, uerr := s.repo.UpdateLogOrderNo(txCtx, tx, row.ID, rebindTo, remarkRebind); uerr != nil {
					return uerr
				}
				continue
			}
			// ② 回滚删除分支：冲正 total_income 后物理删除
			amount, perr := parseAmount(row.Money)
			if perr != nil {
				return perr
			}
			if _, ierr := s.repo.IncTotalIncome(txCtx, tx, row.UserID, amount.Neg()); ierr != nil {
				return ierr
			}
			if derr := s.repo.DeleteLog(txCtx, tx, row.ID); derr != nil {
				return derr
			}
		}
		return nil
	})
}

// UpdateQuota 修改节点分成额度并级联下降子树（dump `divide_into_update_quota`）。
//
// 入参：
//   - ctx 请求上下文；
//   - userID 节点用户（ULID；必须是树节点，否则 3001）；
//   - quota 新额度（单位：分；负值/越界 → 3140）。
//
// 出参：
//   - nil：成功（含"子树内无超标节点"的空更新）；
//   - ErrNotFound(3001)：节点不存在；
//   - ErrDivideQuotaExceeded(3111)：新额度**超过上级**额度（子不得超父）；
//   - ErrBusinessParam / ErrDBError。
//
// 级联规则（audit A6，dump `yuansiwei_finance.sql:763870-763874` **两个前置条件**）：
//
//	UPDATE ... SET quota=updateQuota WHERE userid=findUserid;          -- 本节点先落新值
//	IF (uQuota > 0) THEN                                               -- ① 节点**原** quota>0 才级联
//	  UPDATE ... WHERE left_val>uLeft AND right_val<uRight
//	              AND quota>updateQuota AND type=uType;               -- ② 只压**同分成类型**的子节点
//	END IF;
//
// 即：① 原 quota=0 的节点不级联（尚未配置额度的节点不该"顺手"压低子树）；
//
//	② 级联只在同一分成类型内传播（一次付清/按课次两条线的额度互不影响）。
//
// 事务：本节点更新与子树压制**同事务**（否则出现"父已降、子仍高于父"的越权窗口）。
func (s *DivideService) UpdateQuota(ctx context.Context, userID string, quota money.Amount) error {
	userID = strings.TrimSpace(userID)
	if userID == "" {
		return infraerrors.WithCause(apperr.ErrBusinessParam, errString("service: UpdateQuota 需要 userID"))
	}
	if quota.IsNegative() {
		return infraerrors.WithCause(apperr.ErrBusinessParam, errString("service: 分成额度不能为负"))
	}
	if verr := quota.Validate(); verr != nil {
		return infraerrors.WithCause(apperr.ErrBusinessParam, verr)
	}
	if err := s.assertReady(); err != nil {
		return err
	}

	return s.runner.WithinTx(ctx, func(tx *gorm.DB) error {
		txCtx := repository.WithTxContext(ctx, tx)

		node, err := s.repo.GetByUserID(txCtx, userID)
		if err != nil {
			return err // ErrNotFound(3001) 原样上抛
		}

		// 上限校验：子不得超父（父额度是硬上限，超限 → 3111）
		if node.ParentUserID != nil && strings.TrimSpace(*node.ParentUserID) != "" {
			parent, perr := s.repo.GetByUserID(txCtx, strings.TrimSpace(*node.ParentUserID))
			if perr == nil {
				parentQuota, aerr := parseAmount(parent.Quota)
				if aerr != nil {
					return aerr
				}
				if quota.GreaterThan(parentQuota) {
					return infraerrors.WithCause(apperr.ErrDivideQuotaExceeded,
						errString("service: 分成额度不得超过上级（"+quota.String()+" > "+parentQuota.String()+"）"))
				}
			} else if !errors.Is(perr, infraerrors.ErrNotFound) {
				return perr
			}
			// 上级不在树中（断链）→ 不做上限校验（不阻断后台修复数据）
		}

		// A6 前置①：取**原** quota（必须在更新本节点之前读，否则拿到的已是新值）
		origQuota, aerr := parseAmount(node.Quota)
		if aerr != nil {
			return aerr
		}
		if _, uerr := s.repo.UpdateNodeQuota(txCtx, tx, userID, quota); uerr != nil {
			return uerr
		}
		if !origQuota.GreaterThan(0) {
			// 原额度为 0 → dump 不级联（只落本节点新值）
			return nil
		}
		// A6 前置②：只压同一分成类型的子节点
		if _, cerr := s.repo.ClampSubtreeQuota(txCtx, tx, node.LeftVal, node.RightVal, node.Type, quota); cerr != nil {
			return cerr
		}
		return nil
	})
}

// assertReady 装配期自检（repo/runner 未构造 → ErrInternal，避免 nil 解引用）。
func (s *DivideService) assertReady() error {
	if s == nil || s.repo == nil || s.runner == nil {
		return infraerrors.WithCause(infraerrors.ErrInternal, errString("service: DivideService 未装配 repo/runner"))
	}
	return nil
}

// resolveRoot 解析节点的所属树根（自身为根时返回自身 user_id）。
//
// 入参：node 分账节点（可 nil）。出参：根 user_id 字符串。
//
// 修正点（模型注释 ★）：旧 SP 在"subid 已存在"分支可能留下 root_user_id = NULL，
// 因此这里必须容忍 nil/空串并回退到节点自身，再回退到 parent（由调用方兜底）。
func resolveRoot(node *model.UserDivideInto) string {
	if node == nil {
		return ""
	}
	if node.RootUserID != nil && strings.TrimSpace(*node.RootUserID) != "" {
		return strings.TrimSpace(*node.RootUserID)
	}
	return node.UserID
}

// parseAmount 把库里的 decimal(12,2) 字符串转 money.Amount（空串视为 0.00，容错迁移期脏值）。
//
// 入参：s 十进制"元"字符串。出参：money.Amount；解析失败 → ErrDBError（数据异常不静默归零）。
func parseAmount(s string) (money.Amount, error) {
	trimmed := strings.TrimSpace(s)
	if trimmed == "" {
		return 0, nil
	}
	amount, err := money.Parse(trimmed)
	if err != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError, err)
	}
	return amount, nil
}

// stringPtr 返回字符串指针（空串返回 nil，便于落 NULL）。
func stringPtr(s string) *string {
	trimmed := strings.TrimSpace(s)
	if trimmed == "" {
		return nil
	}
	return &trimmed
}

// optionalString 空串返回 nil 的指针构造（备注列语义：空 → NULL）。
func optionalString(s string) *string { return stringPtr(s) }

// errString 实现 error 的最小字符串类型（本包不引入额外依赖，语义同 repository.errString）。
type errString string

// Error 实现 error 接口。
func (e errString) Error() string { return string(e) }