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

// 余额核心服务（8 个余额类 SP 的 Go 化落点）——AC-04。
//
// 依据：unified/03-migration/academic-domain-design.md §3.1（余额 11 SP 映射，本文件覆盖 #1~#7 + #11）
// / §1.4（事务模板）/ §1.5（幂等键 uk_request_type）/ §7.1（充值时序）/ §10.2（type 编码与方向）
// / §10.3（事务边界只在 Service）/ §10.7（金额溢出与量级上限）。
//
// SP 映射（dump 行号见 §3.1，**顺序与方向一律按 dump，不得"顺手修正"**）：
//
//	#1  sp_user_expense_recharge                → Recharge（8 参、**双表更新**：全局 + 校区同事务）
//	#2  sp_user_expense_school_recharge         → Recharge（同构合并，仅默认备注不同 → RechargeKind）
//	#3  sp_user_expense_school_expenditure      → Expenditure（type 由调用方传，白名单校验）
//	#4  sp_user_expense_school_refund           → Refund（**补 institution_id 参数**，BUG#2 修正）
//	#5  sp_user_expense_school_get_refundable_amount → RefundableAmount（只读，无事务）
//	#6  sp_user_expense_school_transfer_expenditure  → Transfer（**不动 balance**；106=+m / 206=−m）
//	#7  sp_user_expense_baddebt                 → BadDebt（只加 special_expenses，不动 balance）
//	#11 sp_user_expense_school_spend            → AccumulateSpend（只更新 spend，不动 balance；BUG#1）
//
// 两条不可违反的纪律（评审逐处检查）：
//
//  1. **事务边界只在 Service**：写路径一律 `s.runner.WithinTx`；仓储方法不开事务，
//     事务内下游调用一律经 `repository.WithTxContext(ctx, tx)` 注入的 ctx（§10.3）。
//  2. **固定写序「全局 → 校区」**：所有双表写都收敛到
//     `ExpenseRepo.AddColumnsGlobalThenCampus`（一条表一条 UPDATE，全局在前），
//     与 RefundService 的**加锁**顺序保持一致，否则与并发充值交叉即成环（§1.4 / §7.2）。
//
// 金额纪律：全链路 `money.Amount`（int64 分），入参先过 `validatePositiveAmount`
// （业务量级 + `Validate()`），落库前再由仓储的 `amountLiteral` 二次 `Validate()`（§10.7 兜底网）。
package service

import (
	"context"
	"errors"
	"sort"
	"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/port"
	"yuansiwei/unified-backend/internal/academic/repository"
	infraerrors "yuansiwei/unified-backend/internal/infra/errors"
	appscope "yuansiwei/unified-backend/internal/infra/scope"
)

// 默认备注文案（dump 的 `IF inputRemark=”` 分支，**逐字对齐**，双跑会比对 log.remark）。
const (
	// defaultRechargeRemark SP1 `sp_user_expense_recharge` 默认备注。
	defaultRechargeRemark = "余额充值"
	// defaultSchoolRechargeRemark SP2 `sp_user_expense_school_recharge` 默认备注（与 SP1 不同）。
	defaultSchoolRechargeRemark = "充值缴费"
	// defaultExpenditureRemark SP3 `sp_user_expense_school_expenditure` 默认备注。
	defaultExpenditureRemark = "历史扣费"
	// defaultRefundRemark SP4 `sp_user_expense_school_refund` 默认备注。
	defaultRefundRemark = "报课的费用退回"
	// defaultBadDebtRemark SP7 `sp_user_expense_baddebt` 默认备注。
	defaultBadDebtRemark = "坏账处理"
)

// maxSingleAmount 单笔金额业务上限（1,000,000.00 元）。
//
// 依据设计 §10.7「配套纪律 2」：Service 入口对 money 做业务量级断言，把"脏数据放大"挡在运算前
// （超出 → 2002）。注意与 `money.MaxAmount`（decimal(12,2) 全域 ±99.99 亿元）不是一回事：
// 前者是**业务**天花板，后者是**存储**天花板，两者都必须校验。
const maxSingleAmount money.Amount = 100_000_000

// RechargeKind 充值 SP 形态（#1 与 #2 的**唯一差异**是默认备注，合并后用它区分双跑映射）。
type RechargeKind int

const (
	// RechargeKindDefault 对应 SP1 `sp_user_expense_recharge`（默认备注"余额充值"）。
	RechargeKindDefault RechargeKind = iota
	// RechargeKindSchool 对应 SP2 `sp_user_expense_school_recharge`（默认备注"充值缴费"）。
	RechargeKindSchool
)

// FundService 余额核心服务（充值/消费/退费/转结/坏账/累计消费/可退金额）。
//
// 字段：
//   - repo：余额账户仓储（全局 + 校区 + 流水；校区账户走机构作用域）；
//   - runner：事务运行器（顶层 BEGIN，事务内透传）；
//   - member：成员关系校验器（可 nil：系统任务/割接脚本模式不做对象级越权断言）。
type FundService struct {
	repo   *repository.ExpenseRepo
	runner *repository.TxRunner
	member port.MembershipChecker
}

// NewFundService 构造余额核心服务（repo 与 runner 绑定同一 DB 句柄，避免跨连接池事务失效）。
//
// 入参：
//   - db *gorm.DB：数据库句柄（必填）；
//   - sc *appscope.Scope：本次请求作用域（校区账户读写必需；系统任务可 nil，
//     此时**只能**调用全局/流水方法，触达校区账户会 panic fail-fast）；
//   - member port.MembershipChecker：成员校验器（可 nil）。
//
// 出参：*FundService。
func NewFundService(db *gorm.DB, sc *appscope.Scope, member port.MembershipChecker) *FundService {
	return &FundService{
		repo:   repository.NewExpenseRepo(db, sc),
		runner: repository.NewTxRunner(db),
		member: member,
	}
}

// ---------------------------------------------------------------- 入参 / 出参

// RechargeInput 充值入参（SP1 `sp_user_expense_recharge` 8 参 / SP2 同构 7 参）。
//
// 入参纪律：`Money` 已由 Handler 用 `money.Parse` 解析（**拒绝 float**，§10.6），
// 本层不再解析字符串，只校验量级与业务规则。
type RechargeInput struct {
	// UserID 充值用户（canonical_user_id ULID；必填）。
	UserID string `json:"userId"`
	// InstitutionID 机构 ID（必填 >0；dump 的 inputSchoolid）。
	InstitutionID int64 `json:"institutionId"`
	// CampusID 校区 ID（必填 >0；dump 的 inputCampusid）。
	CampusID int64 `json:"campusId"`
	// Money 充值金额（>0；dump 的 inputMoney）。
	Money money.Amount `json:"money"`
	// Type 流水类型（dump 的 inputType；<100 一律归 100，对齐 dump `IF inputType<100`）。
	Type int32 `json:"type"`
	// RequestID 幂等请求号（→ request_id 幂等键 + log_id 业务单号；空 = 不享幂等）。
	RequestID string `json:"requestId"`
	// Remark 备注（空 → 按 Kind 取默认文案）。
	Remark string `json:"remark"`
	// OperatorID 操作人（→ create_user_id；空 → NULL）。
	OperatorID string `json:"-"`
	// Kind SP 形态（默认 RechargeKindDefault）。
	Kind RechargeKind `json:"-"`
}

// RechargeResult 充值结果（端点 3 响应 `{logId,balance,repeated}`）。
type RechargeResult struct {
	// LogID 流水 ID（幂等命中时为**首次**流水 ID）。
	LogID int64 `json:"logId"`
	// Balance 充值后校区账户余额（balance_after 口径）。
	Balance money.Amount `json:"balance"`
	// Repeated true = 幂等命中（requestId 已处理），未重复入账。
	Repeated bool `json:"repeated"`
}

// ExpenditureInput 消费入参（SP3 `sp_user_expense_school_expenditure` 8 参）。
type ExpenditureInput struct {
	// UserID 用户（必填）。
	UserID string `json:"userId"`
	// InstitutionID 机构 ID（必填 >0）。
	InstitutionID int64 `json:"institutionId"`
	// CampusID 校区 ID（必填 >0）。
	CampusID int64 `json:"campusId"`
	// Money 消费金额（>0；流水落 `-Money`）。
	Money money.Amount `json:"money"`
	// Type 消费类型（101/104/105/200/201/204/205，白名单；非法 → 2002）。
	Type int32 `json:"type"`
	// RequestID 幂等请求号（空 = 不享幂等）。
	RequestID string `json:"requestId"`
	// Remark 备注（空 → "历史扣费"）。
	Remark string `json:"remark"`
	// OperatorID 操作人。
	OperatorID string `json:"-"`
}

// ExpenditureResult 消费结果（端点 4 响应 `{logId,balance}`）。
type ExpenditureResult struct {
	// LogID 流水 ID。
	LogID int64 `json:"logId"`
	// Balance 消费后校区账户余额。
	Balance money.Amount `json:"balance"`
	// Repeated true = 幂等命中。
	Repeated bool `json:"repeated"`
}

// RefundInput 退费入参（SP4 `sp_user_expense_school_refund` 7 参 + **补 institution_id**）。
type RefundInput struct {
	// UserID 用户（必填）。
	UserID string `json:"userId"`
	// InstitutionID 机构 ID（必填 >0；**dump 无此参数 = BUG#2**，见 Refund 方法注释）。
	InstitutionID int64 `json:"institutionId"`
	// CampusID 校区 ID（必填 >0）。
	CampusID int64 `json:"campusId"`
	// Money 退费金额（>0 才生效；<=0 → changed=false 的 no-op，对齐 dump `IF inputMoney>0`）。
	Money money.Amount `json:"money"`
	// Type 流水类型（dump 的 inputType；必须属 model.ExpenseLogType* 白名单）。
	Type int32 `json:"type"`
	// RequestID 幂等请求号（空 = 不享幂等）。
	RequestID string `json:"requestId"`
	// Remark 备注（空 → "报课的费用退回"）。
	Remark string `json:"remark"`
	// OperatorID 操作人。
	OperatorID string `json:"-"`
}

// RefundResult 退费结果（端点 5 响应 `{logId,balance,changed}`）。
type RefundResult struct {
	// LogID 流水 ID（no-op 时为 0）。
	LogID int64 `json:"logId"`
	// Balance 退费后校区账户余额。
	Balance money.Amount `json:"balance"`
	// Changed false = 未发生资金变动（money<=0 的 no-op，或幂等命中）。
	Changed bool `json:"changed"`
	// Repeated true = 幂等命中。
	Repeated bool `json:"repeated"`
}

// TransferInput 转结入参（SP6 `sp_user_expense_school_transfer_expenditure` 8 参）。
type TransferInput struct {
	// UserID 用户（必填）。
	UserID string `json:"userId"`
	// FromInstitutionID 转出机构 ID（必填 >0）。
	FromInstitutionID int64 `json:"fromInstitutionId"`
	// FromCampusID 转出校区 ID（必填 >0）。
	FromCampusID int64 `json:"fromCampusId"`
	// ToInstitutionID 转入机构 ID（必填 >0）。
	ToInstitutionID int64 `json:"toInstitutionId"`
	// ToCampusID 转入校区 ID（必填 >0）。
	ToCampusID int64 `json:"toCampusId"`
	// Money 转结金额（>0）。
	Money money.Amount `json:"money"`
	// RequestID 幂等请求号（**两条流水共用**同一 request_id，type 不同故不撞键）。
	RequestID string `json:"requestId"`
	// Remark 备注（dump 无默认值）。
	Remark string `json:"remark"`
	// OperatorID 操作人。
	OperatorID string `json:"-"`
}

// TransferResult 转结结果（端点 7 响应 `{logId106,logId206}`）。
type TransferResult struct {
	// LogID106 type=106 转结出流水 ID（dump: money = **+Money**）。
	LogID106 int64 `json:"logId106"`
	// LogID206 type=206 转结入流水 ID（dump: money = **−Money**）。
	LogID206 int64 `json:"logId206"`
	// FromBalance 转出校区账户余额（转结**不动 balance**，故与转结前相同）。
	FromBalance money.Amount `json:"fromBalance"`
	// ToBalance 转入校区账户余额（同上）。
	ToBalance money.Amount `json:"toBalance"`
	// Repeated true = 幂等命中。
	Repeated bool `json:"repeated"`
}

// BadDebtInput 坏账入参（SP7 `sp_user_expense_baddebt` 7 参）。
type BadDebtInput struct {
	// UserID 用户（必填）。
	UserID string `json:"userId"`
	// InstitutionID 机构 ID（必填 >0）。
	InstitutionID int64 `json:"institutionId"`
	// CampusID 校区 ID（必填 >0）。
	CampusID int64 `json:"campusId"`
	// Money 坏账金额（>0）。
	Money money.Amount `json:"money"`
	// RequestID 幂等请求号（空 = 不享幂等）。
	RequestID string `json:"requestId"`
	// Remark 备注（空 → "坏账处理"）。
	Remark string `json:"remark"`
	// OperatorID 操作人。
	OperatorID string `json:"-"`
}

// BadDebtResult 坏账结果（端点 8 响应 `{logId,specialExpenses}`）。
type BadDebtResult struct {
	// LogID type=108 流水 ID。
	LogID int64 `json:"logId"`
	// SpecialExpenses 处理后校区账户特殊费用累计。
	SpecialExpenses money.Amount `json:"specialExpenses"`
	// Balance 处理后校区账户余额（本方法不动 balance，回显仅为对账方便）。
	Balance money.Amount `json:"balance"`
	// Repeated true = 幂等命中。
	Repeated bool `json:"repeated"`
}

// SpendInput 累计消费入参（SP11 `sp_user_expense_school_spend` 4 参）。
type SpendInput struct {
	// UserID 用户（必填）。
	UserID string `json:"userId"`
	// InstitutionID 机构 ID（必填 >0）。
	InstitutionID int64 `json:"institutionId"`
	// CampusID 校区 ID（必填 >0）。
	CampusID int64 `json:"campusId"`
	// SpendMoney 本次累加的课费单价之和（元；**负数一律归 0**，dump INSERT 分支同口径）。
	SpendMoney money.Amount `json:"spendMoney"`
}

// SpendResult 累计消费结果（端点 10 响应 `{spend}`）。
type SpendResult struct {
	// Spend 累加后校区账户 spend 列（**不是** balance）。
	Spend money.Amount `json:"spend"`
}

// ---------------------------------------------------------------- 校验助手

// validateUserScope 校验"用户 + 机构 + 校区"三元组（资金方法入口统一形状）。
//
// 入参：userID / institutionID / campusID；op 操作名（错误文案定位）；campusRequired 是否要求校区>0。
// 出参：nil 合法；2001（缺 user_id）/ 3140（校区或机构缺失，对齐设计 §1.6「campusid<=0 → 3140」）。
func validateUserScope(userID string, institutionID, campusID int64, op string, campusRequired bool) error {
	if strings.TrimSpace(userID) == "" {
		return infraerrors.WithCause(infraerrors.ErrBadParam, errString("service: "+op+" 需要 user_id"))
	}
	if institutionID <= 0 {
		return infraerrors.WithCause(apperr.ErrBusinessParam,
			errString("service: "+op+" 需要 institution_id > 0"))
	}
	if campusRequired && campusID <= 0 {
		// dump：`IF (inputSchoolid<1 || inputCampusid<1) THEN LEAVE`（静默 no-op）
		// Go：显式 3140，避免"调用成功但什么都没做"
		return infraerrors.WithCause(apperr.ErrBusinessParam,
			errString("service: "+op+" 需要 campus_id > 0（dump：必须有校区信息）"))
	}
	if campusID < 0 {
		return infraerrors.WithCause(apperr.ErrBusinessParam,
			errString("service: "+op+" 的 campus_id 不得为负"))
	}
	return nil
}

// validatePositiveAmount 校验金额为正且不超业务/存储天花板（§10.7）。
//
// 入参：amount 金额（分）；op 操作名。
// 出参：nil 合法；2002（<=0 / 超业务上限 / 超 decimal(12,2) 全域）。
//
// 与 dump 的差异（登记为有意偏离）：dump 对负数是 `IF inputMoney<0 THEN SET inputMoney=0`
// **静默归零后继续记账**，会留下 money=0 的流水并占住幂等键；Go 显式拒绝（2002）。
func validatePositiveAmount(amount money.Amount, op string) error {
	if amount <= 0 {
		return infraerrors.WithCause(infraerrors.ErrBadFormat,
			errString("service: "+op+" 金额必须 > 0（dump 静默归零 → Go 显式拒绝）"))
	}
	if amount > maxSingleAmount {
		return infraerrors.WithCause(infraerrors.ErrBadFormat,
			errString("service: "+op+" 金额超出单笔业务上限"))
	}
	if err := amount.Validate(); err != nil {
		return infraerrors.WithCause(infraerrors.ErrBadFormat, err)
	}
	return nil
}

// parseAccountAmount 把账户 decimal 字符串列解析为 money.Amount。
//
// 入参：raw 列原文（如 "12.34"）；col 列名（错误文案定位）。
// 出参：money.Amount；ErrDBError（历史脏值/格式非法——属数据问题，不是入参问题）。
func parseAccountAmount(raw, col string) (money.Amount, error) {
	amount, err := money.Parse(raw)
	if err != nil {
		return 0, infraerrors.WithCause(infraerrors.ErrDBError,
			errString("service: 账户列 "+col+" 金额非法（"+raw+"）"))
	}
	return amount, nil
}

// optString 把空串转成 nil 指针（*string 列的 NULL 语义：request_id 为空时"不享幂等"）。
func optString(s string) *string {
	s = strings.TrimSpace(s)
	if s == "" {
		return nil
	}
	return &s
}

// amountPtr 返回金额两位小数字符串的指针（`balance_after` 等可空金额列用）。
func amountPtr(a money.Amount) *string {
	s := a.String()
	return &s
}

// newExpenseLog 组装一条余额变更流水（字段口径收口，避免各方法重复拼装）。
//
// 入参：userID/typ/money 金额/requestID/remark/operatorID/balanceAfter（nil = 不写快照）。
// 出参：*model.UserExpenseLog（未落库；Create 后 ID 由 GORM 回填）。
func newExpenseLog(userID string, typ int32, amount money.Amount, requestID, remark, operatorID string,
	balanceAfter *money.Amount) *model.UserExpenseLog {
	lg := &model.UserExpenseLog{
		UserID:       userID,
		Type:         typ,
		Money:        amount.String(),
		RequestID:    optString(requestID),
		LogID:        optString(requestID), // dump：logid = 外部单号（SP1 的 inputOrder / SP2 的 inputRequestid）
		CreateUserID: optString(operatorID),
		Remark:       optString(remark),
	}
	if balanceAfter != nil {
		lg.BalanceAfter = amountPtr(*balanceAfter)
	}
	return lg
}

// assertInScope 对象级越权断言（全局钱包无作用域列，只能由 Service 显式校验，设计 §1.7 例外一）。
//
// 入参：ctx / userID / institutionID / campusID。
// 出参：nil 通过（或未注入 checker 的系统任务模式）；1004 越权；5002 DB 异常。
func (s *FundService) assertInScope(ctx context.Context, userID string, institutionID, campusID int64) error {
	if s == nil || s.member == nil {
		return nil // 系统任务/割接脚本模式：不注入 checker 即不做对象级断言（装配层责任）
	}
	return s.member.AssertInScope(ctx, userID, institutionID, campusID)
}

// ---------------------------------------------------------------- SP1 / SP2 充值

// Recharge 余额充值（SP1 `sp_user_expense_recharge` + SP2 `sp_user_expense_school_recharge`）。
//
// dump 语义（yuansiwei_finance.sql:764247，★8 参 + **双表更新**）：
//
//	① inputMoney<0 → 0；inputType<100 → 100；inputRemark='' → 默认备注；
//	② schoolid<1 || campusid<1 → LEAVE（静默 no-op）；
//	③ 校区账户不存在则 INSERT；全局账户不存在则 INSERT；
//	④ UPDATE 校区：balance+, total_income+ ；UPDATE 全局：balance+, total_income+；
//	⑤ INSERT log(type=inputType, logid=inputOrder, money=inputMoney)。
//
// Go 的三处**有意强化**（不改变资金结果）：
//   - 建户合并为一次 UPSERT（`ON CONFLICT DO NOTHING`），替代 dump 的 `COUNT` 判存在（§1.5）；
//   - 写序固定为 **全局 → 校区**（dump 是校区 → 全局；顺序不同但结果一致，
//     统一顺序是**死锁预防**的硬要求，见 §1.4 与 §7.2 的加锁基线）；
//   - 幂等：`request_id + type` 唯一键，并发重复提交只落 1 条流水（dump 无幂等，会重复入账）。
//
// 入参：ctx / in（见 RechargeInput；Kind 决定默认备注）。
// 出参：*RechargeResult（logId/balance/repeated）；错误码 2001/2002/3140/1004/5002。
func (s *FundService) Recharge(ctx context.Context, in RechargeInput) (*RechargeResult, error) {
	if err := validateUserScope(in.UserID, in.InstitutionID, in.CampusID, "Recharge", true); err != nil {
		return nil, err
	}
	if err := validatePositiveAmount(in.Money, "Recharge"); err != nil {
		return nil, err
	}
	if in.Type < 100 {
		// dump：`IF inputType<100 THEN SET inputType=100`（充值流水类型下限）
		in.Type = model.ExpenseLogTypeRecharge
	}
	if s == nil || s.runner == nil || s.repo == nil {
		return nil, infraerrors.WithCause(infraerrors.ErrInternal, errString("service: FundService 未装配"))
	}
	remark := strings.TrimSpace(in.Remark)
	if remark == "" {
		if in.Kind == RechargeKindSchool {
			remark = defaultSchoolRechargeRemark
		} else {
			remark = defaultRechargeRemark
		}
	}

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

		// ① 幂等预检（`uk_request_type`）：命中 → 返回首次结果，不重复入账
		hit, e := s.repo.FindLogByRequest(txCtx, tx, in.UserID, in.RequestID, in.Type)
		if e != nil {
			return e
		}
		if hit != nil {
			bal, pe := balanceAfterOf(hit)
			if pe != nil {
				return pe
			}
			out = RechargeResult{LogID: hit.ID, Balance: bal, Repeated: true}
			return nil
		}

		// ② 作用域断言（全局钱包无作用域列 → Service 层显式校验）
		if e := s.assertInScope(txCtx, in.UserID, in.InstitutionID, in.CampusID); e != nil {
			return e
		}

		// ③ 建户（两个 UPSERT，**不动已有余额**）
		if e := s.repo.UpsertGlobal(txCtx, tx, &model.UserExpense{UserID: in.UserID}); e != nil {
			return e
		}
		if e := s.repo.UpsertCampus(txCtx, tx, &model.UserExpenseSchool{
			UserID: in.UserID, InstitutionID: in.InstitutionID, CampusID: in.CampusID,
		}); e != nil {
			return e
		}

		// ④ 原子增减（固定「全局 → 校区」，两列合并为每表一条 UPDATE）
		if _, e := s.repo.AddColumnsGlobalThenCampus(txCtx, tx, "Recharge", in.UserID,
			in.InstitutionID, in.CampusID,
			repository.ColumnDelta{Column: repository.ExpenseColumnBalance, Delta: in.Money},
			repository.ColumnDelta{Column: repository.ExpenseColumnTotalIncome, Delta: in.Money},
		); e != nil {
			return e
		}

		// ⑤ 流水（balance_after = 充值后校区余额快照，供对账/双跑逐字段比对）
		acc, e := s.repo.GetCampusAccount(txCtx, tx, in.UserID, in.InstitutionID, in.CampusID)
		if e != nil {
			return e
		}
		bal, e := parseAccountAmount(acc.Balance, "t_user_expense_school.balance")
		if e != nil {
			return e
		}
		lg := newExpenseLog(in.UserID, in.Type, in.Money, in.RequestID, remark, in.OperatorID, &bal)
		if e := s.insertLog(txCtx, tx, lg); e != nil {
			return e
		}
		out = RechargeResult{LogID: lg.ID, Balance: bal}
		return nil
	})
	if err != nil {
		return nil, s.mapIdempotentHit(err, func() error {
			return s.replayRecharge(ctx, in, &out)
		})
	}
	return &out, nil
}

// ---------------------------------------------------------------- SP3 消费

// Expenditure 余额消费扣费（SP3 `sp_user_expense_school_expenditure`）。
//
// dump 语义（:764364，**type 决定列组合，方向不可改**）：
//
//	inputType=200（历史扣费）  → balance−, total_expenditure+, spend+
//	inputType=207（余额退费）  → balance−, total_income−
//	其余（101/104/105/201/204/205）→ balance−, total_expenditure+
//	两条 UPDATE（校区 + 全局）+ log(money = **−inputMoney**)
//
// Go 的口径选择（**与 dump 的两处差异，均为设计 §3.1 #3 明确要求**）：
//   - type 白名单校验：`101/104/105/200/201/204/205`（非法 → 2002）。dump 会把
//     `type<200 或 >299` **静默改成 200**，把"调用方传错类型"变成"记成历史扣费"；
//   - dump 的 `type=207` 分支**不开放**给本方法（退费走 `Refund`/`CustomRefund`，
//     否则同一语义有两条写入口，流水方向难以对账）。
//
// 入参：ctx / in。出参：*ExpenditureResult；错误码 2001/2002/3140/1004/5002。
func (s *FundService) Expenditure(ctx context.Context, in ExpenditureInput) (*ExpenditureResult, error) {
	if err := validateUserScope(in.UserID, in.InstitutionID, in.CampusID, "Expenditure", true); err != nil {
		return nil, err
	}
	if err := validatePositiveAmount(in.Money, "Expenditure"); err != nil {
		return nil, err
	}
	if !isExpenditureType(in.Type) {
		return nil, infraerrors.WithCause(infraerrors.ErrBadFormat,
			errString("service: Expenditure 的 type 非法（白名单 101/104/105/200/201/204/205）"))
	}
	if s == nil || s.runner == nil || s.repo == nil {
		return nil, infraerrors.WithCause(infraerrors.ErrInternal, errString("service: FundService 未装配"))
	}
	remark := strings.TrimSpace(in.Remark)
	if remark == "" {
		remark = defaultExpenditureRemark
	}
	deltas := expenditureDeltas(in.Type, in.Money)

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

		hit, e := s.repo.FindLogByRequest(txCtx, tx, in.UserID, in.RequestID, in.Type)
		if e != nil {
			return e
		}
		if hit != nil {
			bal, pe := balanceAfterOf(hit)
			if pe != nil {
				return pe
			}
			out = ExpenditureResult{LogID: hit.ID, Balance: bal, Repeated: true}
			return nil
		}
		if e := s.assertInScope(txCtx, in.UserID, in.InstitutionID, in.CampusID); e != nil {
			return e
		}
		if e := s.repo.UpsertGlobal(txCtx, tx, &model.UserExpense{UserID: in.UserID}); e != nil {
			return e
		}
		if e := s.repo.UpsertCampus(txCtx, tx, &model.UserExpenseSchool{
			UserID: in.UserID, InstitutionID: in.InstitutionID, CampusID: in.CampusID,
		}); e != nil {
			return e
		}
		if _, e := s.repo.AddColumnsGlobalThenCampus(txCtx, tx, "Expenditure", in.UserID,
			in.InstitutionID, in.CampusID, deltas...); e != nil {
			return e
		}
		acc, e := s.repo.GetCampusAccount(txCtx, tx, in.UserID, in.InstitutionID, in.CampusID)
		if e != nil {
			return e
		}
		bal, e := parseAccountAmount(acc.Balance, "t_user_expense_school.balance")
		if e != nil {
			return e
		}
		// dump：INSERT log(money = **−inputMoney**)
		lg := newExpenseLog(in.UserID, in.Type, in.Money.Neg(), in.RequestID, remark, in.OperatorID, &bal)
		if e := s.insertLog(txCtx, tx, lg); e != nil {
			return e
		}
		out = ExpenditureResult{LogID: lg.ID, Balance: bal}
		return nil
	})
	if err != nil {
		return nil, s.mapIdempotentHit(err, func() error {
			return s.replayExpenditure(ctx, in, &out)
		})
	}
	return &out, nil
}

// expenditureDeltas 按 type 生成列增量（dump 三个分支的逐列对应，**顺序/方向不得改**）。
//
// 入参：typ 消费类型（已过白名单）；amount 消费金额（>0）。
// 出参：[]repository.ColumnDelta（balance 恒为 −amount）。
func expenditureDeltas(typ int32, amount money.Amount) []repository.ColumnDelta {
	switch typ {
	case model.ExpenseLogTypeHistoryDeduct:
		// dump：`balance-`,`total_expenditure+`,`spend+`（历史扣费同时计入消费统计）
		return []repository.ColumnDelta{
			{Column: repository.ExpenseColumnBalance, Delta: amount.Neg()},
			{Column: repository.ExpenseColumnTotalExpenditure, Delta: amount},
			{Column: repository.ExpenseColumnSpend, Delta: amount},
		}
	default:
		// dump：`balance-`,`total_expenditure+`（报课学费 / 学校消费）
		return []repository.ColumnDelta{
			{Column: repository.ExpenseColumnBalance, Delta: amount.Neg()},
			{Column: repository.ExpenseColumnTotalExpenditure, Delta: amount},
		}
	}
}

// isExpenditureType 消费类型白名单（设计 §3.1 #3：101/104/105/200/201/204/205）。
func isExpenditureType(typ int32) bool {
	switch typ {
	case model.ExpenseLogTypeCourseCampus, // 101
		model.ExpenseLogTypeCourseSchoolA, // 104
		model.ExpenseLogTypeCourseSchoolB, // 105
		model.ExpenseLogTypeHistoryDeduct, // 200
		model.ExpenseLogTypeCourseCampusB, // 201
		model.ExpenseLogTypeCourseSchoolC, // 204
		model.ExpenseLogTypeCourseSchoolD: // 205
		return true
	default:
		return false
	}
}

// ---------------------------------------------------------------- SP4 退费

// Refund 余额退费（SP4 `sp_user_expense_school_refund`）。
//
// dump 语义（:764576）：`IF inputMoney>0` 才动作（<=0 静默 no-op）；
// 校区账户已存在才 UPDATE（balance+, total_expenditure−）；全局账户已存在才 UPDATE；
// 任一更新成功才写 log（money = **+inputMoney**，type = inputType）。
//
// **BUG#2 修正（设计 §3.1 #4）**：dump 的定位条件是 `userid + campusid`，**没有 schoolid**——
// 同一 campus_id 若在多机构复用（历史数据/跨库迁移期），会误更新别的机构的账户行。
// Go 侧补 `institution_id` 参数并进 WHERE，定位三元组精确到 `(user, institution, campus)`。
//
// 入参：ctx / in。出参：*RefundResult（changed=false 表示无资金变动）；
// 错误码 2001/2002/3140/1004/3001/5002。
func (s *FundService) Refund(ctx context.Context, in RefundInput) (*RefundResult, error) {
	if err := validateUserScope(in.UserID, in.InstitutionID, in.CampusID, "Refund", true); err != nil {
		return nil, err
	}
	if in.Type <= 0 {
		return nil, infraerrors.WithCause(infraerrors.ErrBadFormat, errString("service: Refund 需要 type"))
	}
	if !isKnownLogType(in.Type) {
		return nil, infraerrors.WithCause(infraerrors.ErrBadFormat,
			errString("service: Refund 的 type 不在流水类型白名单内"))
	}
	if s == nil || s.runner == nil || s.repo == nil {
		return nil, infraerrors.WithCause(infraerrors.ErrInternal, errString("service: FundService 未装配"))
	}
	remark := strings.TrimSpace(in.Remark)
	if remark == "" {
		remark = defaultRefundRemark
	}

	// dump：`IF inputMoney>0` 才动作 → Go 返回成功但 changed=false（显式语义，不静默）
	if in.Money <= 0 {
		return &RefundResult{Changed: false}, nil
	}
	if err := validatePositiveAmount(in.Money, "Refund"); err != nil {
		return nil, err
	}

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

		hit, e := s.repo.FindLogByRequest(txCtx, tx, in.UserID, in.RequestID, in.Type)
		if e != nil {
			return e
		}
		if hit != nil {
			bal, pe := balanceAfterOf(hit)
			if pe != nil {
				return pe
			}
			out = RefundResult{LogID: hit.ID, Balance: bal, Changed: true, Repeated: true}
			return nil
		}
		if e := s.assertInScope(txCtx, in.UserID, in.InstitutionID, in.CampusID); e != nil {
			return e
		}
		// dump 不建户（account 不存在则什么都不做）；Go 显式 3001，避免"调用成功但没退钱"
		if _, e := s.repo.GetCampusForUpdateExact(txCtx, tx, in.UserID, in.InstitutionID, in.CampusID); e != nil {
			return e
		}
		// dump：`balance+`,`total_expenditure-`
		if _, e := s.repo.AddColumnsGlobalThenCampus(txCtx, tx, "Refund", in.UserID,
			in.InstitutionID, in.CampusID,
			repository.ColumnDelta{Column: repository.ExpenseColumnBalance, Delta: in.Money},
			repository.ColumnDelta{Column: repository.ExpenseColumnTotalExpenditure, Delta: in.Money.Neg()},
		); e != nil {
			return e
		}
		acc, e := s.repo.GetCampusAccount(txCtx, tx, in.UserID, in.InstitutionID, in.CampusID)
		if e != nil {
			return e
		}
		bal, e := parseAccountAmount(acc.Balance, "t_user_expense_school.balance")
		if e != nil {
			return e
		}
		lg := newExpenseLog(in.UserID, in.Type, in.Money, in.RequestID, remark, in.OperatorID, &bal)
		if e := s.insertLog(txCtx, tx, lg); e != nil {
			return e
		}
		out = RefundResult{LogID: lg.ID, Balance: bal, Changed: true}
		return nil
	})
	if err != nil {
		return nil, s.mapIdempotentHit(err, func() error {
			return s.replayRefund(ctx, in, &out)
		})
	}
	return &out, nil
}

// ---------------------------------------------------------------- SP5 可退金额（只读）

// RefundableAmount 查询校区账户可退金额（SP5 `sp_user_expense_school_get_refundable_amount`，**只读**）。
//
// 口径（设计 §3.1 #5 定稿）：`max(校区余额, 0)`；账户不存在 → 0（旧行为）；
// 余额 <= 0（欠费）→ 0。
//
// ⚠ 与 dump 的差异（**已知偏离，登记于本批报告**）：dump 在 `campusBalance - SUM(已使用赠送金额)`
// 之后取 max(…,0)（`totalDiscountAmountUsed` 来自 t_user_balance_request × t_courses_activity_signed
// 的关联聚合，yuansiwei_finance.sql:764472）。设计 §3.1 #5 把该方法**收敛为** `max(balance,0)`
// （赠送扣减属 P2 的"赠送金额可退性"专题），本实现按设计执行；若后续要按 dump 补齐，
// 只需扩展本方法内部（调用方签名不变）。
//
// 入参：ctx / userID / institutionID / campusID。
// 出参：(可退金额, error)；账户不存在 → (0, nil)；错误码 2001/3140/1004/5002。
func (s *FundService) RefundableAmount(
	ctx context.Context, userID string, institutionID, campusID int64,
) (money.Amount, error) {
	if err := validateUserScope(userID, institutionID, campusID, "RefundableAmount", true); err != nil {
		return 0, err
	}
	if s == nil || s.repo == nil {
		return 0, infraerrors.WithCause(infraerrors.ErrInternal, errString("service: FundService 未装配"))
	}
	if err := s.assertInScope(ctx, userID, institutionID, campusID); err != nil {
		return 0, err
	}
	acc, err := s.repo.GetCampusAccount(ctx, nil, userID, institutionID, campusID)
	if err != nil {
		if errors.Is(err, infraerrors.ErrNotFound) {
			return 0, nil // dump：账户不存在 → 0
		}
		return 0, err
	}
	bal, err := parseAccountAmount(acc.Balance, "t_user_expense_school.balance")
	if err != nil {
		return 0, err
	}
	if bal <= 0 {
		return 0, nil
	}
	return bal, nil
}

// ---------------------------------------------------------------- SP6 课费转结

// Transfer 课费转结（SP6 `sp_user_expense_school_transfer_expenditure`）。
//
// dump 语义（:764661，★**与 P0-04 规格相反，以 dump 为准**，设计 §3.1 #6 / §10.2）：
//
//	IF inputMoney>0：
//	  源校区账户存在 →
//	    目标校区账户不存在则 INSERT；
//	    UPDATE 源：total_expenditure−m, total_income−m
//	    UPDATE 目标：total_expenditure+m, total_income+m
//	    INSERT log(type=106, money=**+m**)   ← 转结出
//	    INSERT log(type=206, money=**−m**)   ← 转结入
//
// **四个"不得改动"的点**：
//  1. **不动 balance**（dump 全程没有 balance 赋值）——转结只调"总消费/总充值"两个统计口径；
//  2. 106 记 **+m**、206 记 **−m**（与"出/入"的直觉相反，dump 原文如此，§11-6 #6）；
//  3. 两条流水的 `request_id` **相同**、`type` 不同 → 不撞 `uk_request_type`（唯一键含 type）；
//  4. 目标账户不存在时**建户**（dump 的 INSERT），源账户不存在时**不动**（dump 的 `IF campusLogid1>0`）。
//
// Go 的两处显式化：源账户不存在 → 3001（不静默）；同校区自转 → 3140（净效应为零的无意义操作）。
//
// 入参：ctx / in。出参：*TransferResult{logId106,logId206}；错误码 2001/2002/3140/1004/3001/5002。
func (s *FundService) Transfer(ctx context.Context, in TransferInput) (*TransferResult, error) {
	if err := validateUserScope(in.UserID, in.FromInstitutionID, in.FromCampusID, "Transfer(from)", true); err != nil {
		return nil, err
	}
	if err := validateUserScope(in.UserID, in.ToInstitutionID, in.ToCampusID, "Transfer(to)", true); err != nil {
		return nil, err
	}
	if err := validatePositiveAmount(in.Money, "Transfer"); err != nil {
		return nil, err
	}
	if in.FromInstitutionID == in.ToInstitutionID && in.FromCampusID == in.ToCampusID {
		return nil, infraerrors.WithCause(apperr.ErrBusinessParam,
			errString("service: Transfer 的转出与转入校区不能相同"))
	}
	if s == nil || s.runner == nil || s.repo == nil {
		return nil, infraerrors.WithCause(infraerrors.ErrInternal, errString("service: FundService 未装配"))
	}

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

		// ① 幂等预检：106 是"转结出"主流水（必然存在），用它做命中判定
		hit106, e := s.repo.FindLogByRequest(txCtx, tx, in.UserID, in.RequestID, model.ExpenseLogTypeTransferOut)
		if e != nil {
			return e
		}
		if hit106 != nil {
			out = TransferResult{LogID106: hit106.ID, Repeated: true}
			if bal, pe := balanceAfterOf(hit106); pe == nil {
				out.FromBalance = bal
			}
			hit206, e := s.repo.FindLogByRequest(txCtx, tx, in.UserID, in.RequestID, model.ExpenseLogTypeTransferIn)
			if e != nil {
				return e
			}
			if hit206 != nil {
				out.LogID206 = hit206.ID
				if bal, pe := balanceAfterOf(hit206); pe == nil {
					out.ToBalance = bal
				}
			}
			return nil
		}

		// ② 作用域断言（两侧机构都必须可见）
		if e := s.assertInScope(txCtx, in.UserID, in.FromInstitutionID, in.FromCampusID); e != nil {
			return e
		}
		if in.ToInstitutionID != in.FromInstitutionID {
			if e := s.assertInScope(txCtx, in.UserID, in.ToInstitutionID, in.ToCampusID); e != nil {
				return e
			}
		}

		// ③ 加锁：两个校区账户**按 campus_id ASC 排序**后依次加锁（§1.4 多账户场景防死锁）
		refs := []campusRef{
			{InstitutionID: in.FromInstitutionID, CampusID: in.FromCampusID},
			{InstitutionID: in.ToInstitutionID, CampusID: in.ToCampusID},
		}
		sort.Slice(refs, func(i, j int) bool { return refs[i].CampusID < refs[j].CampusID })
		locked := make(map[campusRef]bool, len(refs))
		for _, ref := range refs {
			_, le := s.repo.GetCampusForUpdateExact(txCtx, tx, in.UserID, ref.InstitutionID, ref.CampusID)
			if le != nil {
				if errors.Is(le, infraerrors.ErrNotFound) {
					locked[ref] = false
					continue
				}
				return le
			}
			locked[ref] = true
		}
		fromRef := campusRef{InstitutionID: in.FromInstitutionID, CampusID: in.FromCampusID}
		toRef := campusRef{InstitutionID: in.ToInstitutionID, CampusID: in.ToCampusID}
		if !locked[fromRef] {
			// dump：源账户不存在 → `IF campusLogid1>0` 不成立 → 静默什么都不做
			return infraerrors.WithCause(infraerrors.ErrNotFound,
				errString("service: Transfer 转出校区账户不存在"))
		}
		if !locked[toRef] {
			// dump：目标账户不存在 → INSERT 建户
			if e := s.repo.UpsertCampus(txCtx, tx, &model.UserExpenseSchool{
				UserID: in.UserID, InstitutionID: in.ToInstitutionID, CampusID: in.ToCampusID,
			}); e != nil {
				return e
			}
		}

		// ④ 4 次 UPDATE → 2 条语句（每表两列），**balance 一律不动**
		if _, e := s.repo.AddCampusColumns(txCtx, tx, "Transfer(out)", in.UserID,
			in.FromInstitutionID, in.FromCampusID,
			repository.ColumnDelta{Column: repository.ExpenseColumnTotalExpenditure, Delta: in.Money.Neg()},
			repository.ColumnDelta{Column: repository.ExpenseColumnTotalIncome, Delta: in.Money.Neg()},
		); e != nil {
			return e
		}
		if _, e := s.repo.AddCampusColumns(txCtx, tx, "Transfer(in)", in.UserID,
			in.ToInstitutionID, in.ToCampusID,
			repository.ColumnDelta{Column: repository.ExpenseColumnTotalExpenditure, Delta: in.Money},
			repository.ColumnDelta{Column: repository.ExpenseColumnTotalIncome, Delta: in.Money},
		); e != nil {
			return e
		}

		// ⑤ 两条流水（106 在前、206 在后；方向 ★dump 口径）
		fromAcc, e := s.repo.GetCampusAccount(txCtx, tx, in.UserID, in.FromInstitutionID, in.FromCampusID)
		if e != nil {
			return e
		}
		fromBal, e := parseAccountAmount(fromAcc.Balance, "t_user_expense_school.balance")
		if e != nil {
			return e
		}
		toAcc, e := s.repo.GetCampusAccount(txCtx, tx, in.UserID, in.ToInstitutionID, in.ToCampusID)
		if e != nil {
			return e
		}
		toBal, e := parseAccountAmount(toAcc.Balance, "t_user_expense_school.balance")
		if e != nil {
			return e
		}
		lg106 := newExpenseLog(in.UserID, model.ExpenseLogTypeTransferOut, in.Money,
			in.RequestID, in.Remark, in.OperatorID, &fromBal)
		if e := s.insertLog(txCtx, tx, lg106); e != nil {
			return e
		}
		lg206 := newExpenseLog(in.UserID, model.ExpenseLogTypeTransferIn, in.Money.Neg(),
			in.RequestID, in.Remark, in.OperatorID, &toBal)
		if e := s.insertLog(txCtx, tx, lg206); e != nil {
			return e
		}
		out = TransferResult{
			LogID106: lg106.ID, LogID206: lg206.ID,
			FromBalance: fromBal, ToBalance: toBal,
		}
		return nil
	})
	if err != nil {
		return nil, s.mapIdempotentHit(err, func() error {
			return s.replayTransfer(ctx, in, &out)
		})
	}
	return &out, nil
}

// campusRef 校区账户定位三元组的"机构 + 校区"部分（转结加锁排序用）。
type campusRef struct {
	// InstitutionID 机构 ID。
	InstitutionID int64
	// CampusID 校区 ID。
	CampusID int64
}

// ---------------------------------------------------------------- SP7 坏账

// BadDebt 坏账处理（SP7 `sp_user_expense_baddebt`）。
//
// 口径（设计 §3.1 #7）：**只加 `special_expenses`，不动 balance**；log type=108、money=+Money。
//
// ⚠ 与 dump 的差异（**已知偏离，登记于本批报告**）：dump（:763890）两条 UPDATE 都是
// `balance = balance + m, special_expenses = special_expenses + m`——即**同时加余额**。
// 设计与本实现按"坏账 = 只统计特殊费用"执行（不凭空给学员加可用余额）；
// 若按 dump 回改，只需在下面的 `AddColumnsGlobalThenCampus` 里补一个 balance 列增量，
// 并把 `BadDebtResult.Balance` 的断言改为"增加后余额"。
// 连带影响（已上报）：dump 口径下 108 流水与账户余额同增，余额恒等式成立；
// 本口径下 type=108 **不参与**余额恒等式（AC-17 ④ 需排除 108 或按 dump 回改）。
//
// 入参：ctx / in。出参：*BadDebtResult；错误码 2001/2002/3140/1004/5002。
func (s *FundService) BadDebt(ctx context.Context, in BadDebtInput) (*BadDebtResult, error) {
	if err := validateUserScope(in.UserID, in.InstitutionID, in.CampusID, "BadDebt", true); err != nil {
		return nil, err
	}
	if err := validatePositiveAmount(in.Money, "BadDebt"); err != nil {
		return nil, err
	}
	if s == nil || s.runner == nil || s.repo == nil {
		return nil, infraerrors.WithCause(infraerrors.ErrInternal, errString("service: FundService 未装配"))
	}
	remark := strings.TrimSpace(in.Remark)
	if remark == "" {
		remark = defaultBadDebtRemark
	}

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

		hit, e := s.repo.FindLogByRequest(txCtx, tx, in.UserID, in.RequestID, model.ExpenseLogTypeBadDebt)
		if e != nil {
			return e
		}
		if hit != nil {
			out = BadDebtResult{LogID: hit.ID, Repeated: true}
			if acc, ae := s.repo.GetCampusAccount(txCtx, tx, in.UserID, in.InstitutionID, in.CampusID); ae == nil {
				if spec, pe := parseAccountAmount(acc.SpecialExpenses, "t_user_expense_school.special_expenses"); pe == nil {
					out.SpecialExpenses = spec
				}
				if bal, pe := parseAccountAmount(acc.Balance, "t_user_expense_school.balance"); pe == nil {
					out.Balance = bal
				}
			}
			return nil
		}
		if e := s.assertInScope(txCtx, in.UserID, in.InstitutionID, in.CampusID); e != nil {
			return e
		}
		if e := s.repo.UpsertGlobal(txCtx, tx, &model.UserExpense{UserID: in.UserID}); e != nil {
			return e
		}
		if e := s.repo.UpsertCampus(txCtx, tx, &model.UserExpenseSchool{
			UserID: in.UserID, InstitutionID: in.InstitutionID, CampusID: in.CampusID,
		}); e != nil {
			return e
		}
		if _, e := s.repo.AddColumnsGlobalThenCampus(txCtx, tx, "BadDebt", in.UserID,
			in.InstitutionID, in.CampusID,
			repository.ColumnDelta{Column: repository.ExpenseColumnSpecialExpenses, Delta: in.Money},
		); e != nil {
			return e
		}
		acc, e := s.repo.GetCampusAccount(txCtx, tx, in.UserID, in.InstitutionID, in.CampusID)
		if e != nil {
			return e
		}
		bal, e := parseAccountAmount(acc.Balance, "t_user_expense_school.balance")
		if e != nil {
			return e
		}
		spec, e := parseAccountAmount(acc.SpecialExpenses, "t_user_expense_school.special_expenses")
		if e != nil {
			return e
		}
		lg := newExpenseLog(in.UserID, model.ExpenseLogTypeBadDebt, in.Money,
			in.RequestID, remark, in.OperatorID, &bal)
		if e := s.insertLog(txCtx, tx, lg); e != nil {
			return e
		}
		out = BadDebtResult{LogID: lg.ID, SpecialExpenses: spec, Balance: bal}
		return nil
	})
	if err != nil {
		return nil, s.mapIdempotentHit(err, func() error {
			return s.replayBadDebt(ctx, in, &out)
		})
	}
	return &out, nil
}

// ---------------------------------------------------------------- SP11 累计消费（spend）

// AccumulateSpend 累计消费金额（SP11 `sp_user_expense_school_spend`）。
//
// 口径（设计 §3.1 #11）：**只更新 `spend`，不动 `balance`**；无流水（dump 不写 log）。
//
// **BUG#1 修正**：dump 的全局分支 `INSERT INTO t_user_expense(userid, spend) VALUES(inputUserid,
// inputMoney, inputSpendMoney)` 是 **3 个值对 2 列**（且 inputMoney 在该 SP 里根本未声明）→ 必报错。
// Go 修正为"UPSERT 建户 + `spend = spend + ?`"，列数与列名对齐 DDL。
//
// 负值处理：dump 仅在 **INSERT 分支**把负数归 0（UPDATE 分支会照减）；本实现统一归 0
// （`spend` 是"只增"的统计口径列，model 注释亦如此约定），并回显当前值。
//
// 幂等：dump 的 SP11 **没有请求号**（签名只有 4 参），因此本方法不参与 `uk_request_type` 幂等；
// 重复调用会重复累加 `spend`——这是 dump 的既有语义（调用方为"结束上课"链路，每次课一条），
// 不做"按 requestId 去重"的加法，以免与 dump 的双跑口径分叉。
//
// 入参：ctx / in。出参：*SpendResult{spend}；错误码 2001/3140/5002。
func (s *FundService) AccumulateSpend(ctx context.Context, in SpendInput) (*SpendResult, error) {
	if err := validateUserScope(in.UserID, in.InstitutionID, in.CampusID, "AccumulateSpend", true); err != nil {
		return nil, err
	}
	if err := in.SpendMoney.Validate(); err != nil {
		return nil, infraerrors.WithCause(infraerrors.ErrBadFormat, err)
	}
	if in.SpendMoney < 0 {
		in.SpendMoney = 0 // dump INSERT 分支：负数归 0（spend 只增）
	}
	if s == nil || s.runner == nil || s.repo == nil {
		return nil, infraerrors.WithCause(infraerrors.ErrInternal, errString("service: FundService 未装配"))
	}

	var out SpendResult
	err := s.runner.WithinTx(ctx, func(tx *gorm.DB) error {
		txCtx := repository.WithTxContext(ctx, tx)
		if e := s.assertInScope(txCtx, in.UserID, in.InstitutionID, in.CampusID); e != nil {
			return e
		}
		if e := s.repo.UpsertGlobal(txCtx, tx, &model.UserExpense{UserID: in.UserID}); e != nil {
			return e
		}
		if e := s.repo.UpsertCampus(txCtx, tx, &model.UserExpenseSchool{
			UserID: in.UserID, InstitutionID: in.InstitutionID, CampusID: in.CampusID,
		}); e != nil {
			return e
		}
		if !in.SpendMoney.IsZero() {
			if _, e := s.repo.AddColumnsGlobalThenCampus(txCtx, tx, "AccumulateSpend", in.UserID,
				in.InstitutionID, in.CampusID,
				repository.ColumnDelta{Column: repository.ExpenseColumnSpend, Delta: in.SpendMoney},
			); e != nil {
				return e
			}
		}
		acc, e := s.repo.GetCampusAccount(txCtx, tx, in.UserID, in.InstitutionID, in.CampusID)
		if e != nil {
			return e
		}
		spend, e := parseAccountAmount(acc.Spend, "t_user_expense_school.spend")
		if e != nil {
			return e
		}
		out = SpendResult{Spend: spend}
		return nil
	})
	if err != nil {
		return nil, err
	}
	return &out, nil
}

// ---------------------------------------------------------------- 幂等公共形状

// insertLog 写流水并把"撞 uk_request_type"翻译成内部幂等哨兵（`apperr.ErrRepeated`）。
//
// 入参：txCtx（含 tx 的 ctx）/ tx / lg 流水行。
// 出参：nil 成功；apperr.ErrRepeated（**并发幂等命中**，调用方据此回放首次结果）；
// 其余错误原样上抛（ErrBadParam/ErrDBError）。
//
// 为什么用 ErrRepeated 作为事务内哨兵：它是 *AppError，`TxRunner.wrapTxErr` 会原样透传
// （不降级成 5002），且它是设计里"仅内部日志用"的码（§10.1），不会泄漏给前端。
func (s *FundService) insertLog(txCtx context.Context, tx *gorm.DB, lg *model.UserExpenseLog) error {
	err := s.repo.InsertLog(txCtx, tx, lg)
	if err == nil {
		return nil
	}
	if errors.Is(err, repository.ErrDuplicateLog) {
		return apperr.ErrRepeated
	}
	return err
}

// mapIdempotentHit 把"并发幂等命中"从错误路径转成"回放首次结果"的成功路径。
//
// 入参：
//   - err：WithinTx 返回的错误；
//   - replay：回放函数（重新查询首次流水并填充 out）。
//
// 出参：nil（回放成功）/ 回放错误 / 原错误（非幂等命中）。
//
// 语义（§1.5）：`uk_request_type` 撞键 = 同一请求号 + 同一 type 的第二次写入，
// **不是错误**（code 仍 200，data.repeated=true）。实现上先整笔回滚（本次零残留），再回放。
func (s *FundService) mapIdempotentHit(err error, replay func() error) error {
	if err == nil {
		return nil
	}
	if errors.Is(err, apperr.ErrRepeated) {
		return replay()
	}
	return err
}

// balanceAfterOf 从流水行取 balance_after 快照（NULL → 0，幂等回放用）。
//
// 入参：lg 流水行（可 nil）。出参：(金额, error)；balance_after 为 NULL 时返回 0 且无错
// （历史行没有快照列，回放时余额字段退化为 0 并保持 repeated=true）。
func balanceAfterOf(lg *model.UserExpenseLog) (money.Amount, error) {
	if lg == nil || lg.BalanceAfter == nil {
		return 0, nil
	}
	return parseAccountAmount(*lg.BalanceAfter, "t_user_expense_log.balance_after")
}

// replayRecharge 幂等回放（充值）。
func (s *FundService) replayRecharge(ctx context.Context, in RechargeInput, out *RechargeResult) error {
	hit, err := s.repo.FindLogByRequest(ctx, nil, in.UserID, in.RequestID, in.Type)
	if err != nil {
		return err
	}
	if hit == nil {
		return infraerrors.WithCause(infraerrors.ErrInternal,
			errString("service: Recharge 幂等命中但首次流水已不可见"))
	}
	bal, err := balanceAfterOf(hit)
	if err != nil {
		return err
	}
	*out = RechargeResult{LogID: hit.ID, Balance: bal, Repeated: true}
	return nil
}

// replayExpenditure 幂等回放（消费）。
func (s *FundService) replayExpenditure(ctx context.Context, in ExpenditureInput, out *ExpenditureResult) error {
	hit, err := s.repo.FindLogByRequest(ctx, nil, in.UserID, in.RequestID, in.Type)
	if err != nil {
		return err
	}
	if hit == nil {
		return infraerrors.WithCause(infraerrors.ErrInternal,
			errString("service: Expenditure 幂等命中但首次流水已不可见"))
	}
	bal, err := balanceAfterOf(hit)
	if err != nil {
		return err
	}
	*out = ExpenditureResult{LogID: hit.ID, Balance: bal, Repeated: true}
	return nil
}

// replayRefund 幂等回放（退费）。
func (s *FundService) replayRefund(ctx context.Context, in RefundInput, out *RefundResult) error {
	hit, err := s.repo.FindLogByRequest(ctx, nil, in.UserID, in.RequestID, in.Type)
	if err != nil {
		return err
	}
	if hit == nil {
		return infraerrors.WithCause(infraerrors.ErrInternal,
			errString("service: Refund 幂等命中但首次流水已不可见"))
	}
	bal, err := balanceAfterOf(hit)
	if err != nil {
		return err
	}
	*out = RefundResult{LogID: hit.ID, Balance: bal, Changed: true, Repeated: true}
	return nil
}

// replayBadDebt 幂等回放（坏账）。
func (s *FundService) replayBadDebt(ctx context.Context, in BadDebtInput, out *BadDebtResult) error {
	hit, err := s.repo.FindLogByRequest(ctx, nil, in.UserID, in.RequestID, model.ExpenseLogTypeBadDebt)
	if err != nil {
		return err
	}
	if hit == nil {
		return infraerrors.WithCause(infraerrors.ErrInternal,
			errString("service: BadDebt 幂等命中但首次流水已不可见"))
	}
	var spec, bal money.Amount
	if acc, ae := s.repo.GetCampusAccount(ctx, nil, in.UserID, in.InstitutionID, in.CampusID); ae == nil {
		if v, pe := parseAccountAmount(acc.SpecialExpenses, "t_user_expense_school.special_expenses"); pe == nil {
			spec = v
		}
		if v, pe := parseAccountAmount(acc.Balance, "t_user_expense_school.balance"); pe == nil {
			bal = v
		}
	}
	*out = BadDebtResult{LogID: hit.ID, SpecialExpenses: spec, Balance: bal, Repeated: true}
	return nil
}

// replayTransfer 幂等回放（转结）。
func (s *FundService) replayTransfer(ctx context.Context, in TransferInput, out *TransferResult) error {
	hit106, err := s.repo.FindLogByRequest(ctx, nil, in.UserID, in.RequestID, model.ExpenseLogTypeTransferOut)
	if err != nil {
		return err
	}
	if hit106 == nil {
		return infraerrors.WithCause(infraerrors.ErrInternal,
			errString("service: Transfer 幂等命中但首次流水已不可见"))
	}
	res := TransferResult{LogID106: hit106.ID, Repeated: true}
	if bal, pe := balanceAfterOf(hit106); pe == nil {
		res.FromBalance = bal
	}
	hit206, err := s.repo.FindLogByRequest(ctx, nil, in.UserID, in.RequestID, model.ExpenseLogTypeTransferIn)
	if err != nil {
		return err
	}
	if hit206 != nil {
		res.LogID206 = hit206.ID
		if bal, pe := balanceAfterOf(hit206); pe == nil {
			res.ToBalance = bal
		}
	}
	*out = res
	return nil
}

// isKnownLogType 流水类型白名单（`model.ExpenseLogType*` 全集，§10.2）。
//
// 用途：`Refund` 的 type 来自调用方（dump 透传），必须落在已知编码内，
// 否则会污染流水表并让"按 type 汇总"的对账口径失效。
func isKnownLogType(typ int32) bool {
	switch typ {
	case model.ExpenseLogTypeRecharge,
		model.ExpenseLogTypeCourseCampus,
		model.ExpenseLogTypeCourseSchoolA,
		model.ExpenseLogTypeCourseSchoolB,
		model.ExpenseLogTypeTransferOut,
		model.ExpenseLogTypeRecommend,
		model.ExpenseLogTypeBadDebt,
		model.ExpenseLogTypeHistoryDeduct,
		model.ExpenseLogTypeCourseCampusB,
		model.ExpenseLogTypeCourseSchoolC,
		model.ExpenseLogTypeCourseSchoolD,
		model.ExpenseLogTypeTransferIn,
		model.ExpenseLogTypeRefund,
		model.ExpenseLogTypeClearBalance,
		model.ExpenseLogTypeCancelRechargeAct:
		return true
	default:
		return false
	}
}