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）。
//
// 依据：模型注释 layer「深度上限 100（超限 → 3111，防递归栈溢出）」+ dump 的层数保护。
// BFS 迭代在本上限内必然终止（即使数据成环也不会死循环）。
const MaxDivideDepth int32 = 100

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

// FirstChargedRecordReader 首次扣费上课记录只读端口（跨聚合依赖，本服务**只定义契约**）。
//
// 为什么用端口而不是直接 JOIN：`log_delete` 的改绑分支需要判断"学生是否已有首次扣费上课记录"，
// 该判定属于课次/打卡聚合（AC-05/AC-10 范围）。AC-09 不实现它，只声明只读契约 + 允许注入；
// 未注入时**所有撤销走回滚删除分支**（保守：不让分成悬空在多订单上）。
//
// 契约：
//   - 只读，禁止写任何表；
//   - 返回 (recordID, found, err)：found=false 表示学生尚无扣费记录 → 走回滚删除分支；
//   - err 仅 DB 异常（infraerrors.ErrDBError），不得返回业务错误。
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 > 100）；
//   - ErrBusinessParam(3140)：入参非法。
//
// 左右值算法（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。
//
// 已存在节点分支（dump `if exists(select 1 from ... where userid = subid)`）：
//
//	dump 仅改 parent，**漏写 root_user_id**（留 NULL → 子树/级联查询失效）。
//	本实现按模型注释的修正要求显式写入父树根，且**不重排左右值**（与原 SP 一致，
//	区间重排会与迁移期数据冲突，登记为遗留项）。
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
		if nextLayer > MaxDivideDepth {
			return infraerrors.WithCause(apperr.ErrDivideQuotaExceeded,
				errString("service: 分账层级超上限 "+strconv.Itoa(int(MaxDivideDepth))))
		}

		rootID := resolveRoot(parent)

		existing, err := s.repo.GetByUserID(txCtx, subUserID)
		switch {
		case err == nil:
			// ── 已存在节点分支：只改挂父链（补齐 root，dump 缺陷修正）
			if existing.UserID == parentUserID {
				return infraerrors.WithCause(apperr.ErrBusinessParam, errString("service: 上下级相同"))
			}
			if _, uerr := s.repo.UpdateNodeParent(txCtx, tx, subUserID, parentUserID, rootID, nextLayer); uerr != nil {
				return uerr
			}
			return nil
		case !errors.Is(err, infraerrors.ErrNotFound):
			return err
		}

		// ── 新建节点分支：嵌套集"插入最右子节点"
		insertAt := parent.RightVal
		if _, serr := s.repo.ShiftRight(txCtx, tx, insertAt, 2); serr != nil {
			return serr
		}
		if _, serr := s.repo.ShiftLeft(txCtx, tx, insertAt, 2); serr != nil {
			return serr
		}
		parentID := parentUserID
		node := &model.UserDivideInto{
			UserID:           subUserID,
			Type:             parent.Type,
			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
	}
	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 异常）。
//
// 两分支（设计 §3.3 #23，**顺序不可颠倒**）：
//
//	① 改绑（保留分成）：学生已有首次扣费上课记录 first，且 first != orderID
//	   → 该组明细的 order_no 改为 first，备注写"推广分成"，total_income **不回滚**；
//	② 回滚删除：否则 → total_income -= money（冲正）并物理删除明细行。
//
// 说明：同一订单的分成会沿上行链生成多行（本人 + 各级上线），故按 (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 && firstID != orderID {
			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。
//
// 级联规则（"只降不升"）：
//
//	本节点 quota := 新值；
//	子树中 quota > 新值的节点 → 压到新值（低于新值的阶梯额度保持不变）。
//
// 事务：本节点更新与子树压制**同事务**（否则出现"父已降、子仍高于父"的越权窗口）。
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
			}
			// 上级不在树中（断链）→ 不做上限校验（不阻断后台修复数据）
		}

		if _, uerr := s.repo.UpdateNodeQuota(txCtx, tx, userID, quota); uerr != nil {
			return uerr
		}
		if _, cerr := s.repo.ClampSubtreeQuota(txCtx, tx, node.LeftVal, node.RightVal, 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) }