feat(员工代收款): 新增员工代收款账单闭环

- 新增 6 张表与成对迁移 000212，扩展企业微信审批场景业务类型白名单
- 后台线下套餐订单与两条代理线下充值入账路径在来源成功事务内建账，来源唯一键幂等
- 核销申请、审批尝试记录、账单分摊预占与驳回重提，审批业务类型 employee_collection_approval
- 企业微信终态消费幂等：通过转已核销、驳回释放预占、通过后撤销不回滚并转异常终态
- 退款成功事务内按 bill_id+refund_id 幂等冲销账单或仅写退款关联提示
- 线下收款方式字典、账单查询/统计/关闭、申请查询与代办权限，均写入事务内审计

OpenSpec Change: add-employee-collection-bills

internal/domain/employeecollection/allocation.go

@@ -0,0 +1,58 @@
+package employeecollection
+
+import (
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// AllocationCandidate 是一笔待校验的核销申请账单分摊候选。
+type AllocationCandidate struct {
+	// BillID 表示目标账单ID。
+	BillID uint
+	// BillStatus 表示目标账单当前持久化状态。
+	BillStatus int
+	// Amount 表示本次分摊金额（分）。
+	Amount int64
+	// Available 表示目标账单当前可核销余额（分），已扣除已通过分摊与其他审批中预占。
+	Available int64
+}
+
+// ValidateAllocations 校验核销申请的账单分摊集合。
+// 规则：付款金额为正、分摊数量在允许区间、账单不重复、账单已关闭时拒绝、
+// 单笔分摊为正且不超过该账单可核销余额、分摊总额不超过本次付款金额。
+func ValidateAllocations(paidAmount int64, candidates []AllocationCandidate) error {
+	if paidAmount <= 0 {
+		return errors.New(errors.CodeInvalidParam, "付款金额必须大于零")
+	}
+	if len(candidates) == 0 {
+		return errors.New(errors.CodeInvalidParam, "核销申请至少需要一个账单分摊")
+	}
+	if len(candidates) > constants.EmployeeCollectionAllocationMaxCount {
+		return errors.New(errors.CodeInvalidParam, "核销申请账单分摊数量超出限制")
+	}
+	seen := make(map[uint]struct{}, len(candidates))
+	var total int64
+	for _, candidate := range candidates {
+		if candidate.BillID == 0 {
+			return errors.New(errors.CodeInvalidParam, "账单分摊缺少目标账单")
+		}
+		if _, exists := seen[candidate.BillID]; exists {
+			return errors.New(errors.CodeInvalidParam, "同一账单不能重复分摊")
+		}
+		seen[candidate.BillID] = struct{}{}
+		if candidate.BillStatus == constants.EmployeeCollectionBillStatusClosed {
+			return errors.New(errors.CodeEmployeeCollectionBillClosed)
+		}
+		if candidate.Amount <= 0 {
+			return errors.New(errors.CodeEmployeeCollectionAllocationAmountInvalid)
+		}
+		if candidate.Amount > candidate.Available {
+			return errors.New(errors.CodeEmployeeCollectionAllocationExceeded)
+		}
+		total += candidate.Amount
+	}
+	if total > paidAmount {
+		return errors.New(errors.CodeEmployeeCollectionPaidAmountExceeded)
+	}
+	return nil
+}

internal/domain/employeecollection/application.go

@@ -0,0 +1,110 @@
+package employeecollection
+
+import (
+	"strings"
+	"time"
+	"unicode/utf8"
+
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// ApplicationInput 是核销申请提交的领域输入；账单分摊由 ValidateAllocations 单独校验。
+type ApplicationInput struct {
+	// PaidAmount 表示人工确认的付款金额（分）。
+	PaidAmount int64
+	// PayerName 表示付款方名称。
+	PayerName string
+	// PaidAt 表示付款时间。
+	PaidAt time.Time
+	// ExternalTransactionNo 表示人工确认的外部交易流水号。
+	ExternalTransactionNo string
+	// Remark 表示申请备注。
+	Remark string
+	// ActingReason 表示代办原因，仅代办提交时必填。
+	ActingReason string
+	// PaymentVoucherKeys 表示支付凭证对象存储键列表。
+	PaymentVoucherKeys []string
+}
+
+// NormalizedApplicationInput 是通过校验并去空格后的核销申请事实。
+type NormalizedApplicationInput struct {
+	PaidAmount            int64
+	PayerName             string
+	PaidAt                time.Time
+	ExternalTransactionNo string
+	Remark                string
+	ActingReason          string
+	PaymentVoucherKeys    []string
+}
+
+// NormalizeApplicationInput 校验并规范化核销申请输入。
+// acting 表示本次是否由超级管理员为他人代办：代办必须填写原因，本人办理不得填写原因。
+func NormalizeApplicationInput(input ApplicationInput, acting bool) (NormalizedApplicationInput, error) {
+	if input.PaidAmount <= 0 {
+		return NormalizedApplicationInput{}, errors.New(errors.CodeInvalidParam, "付款金额必须大于零")
+	}
+	if input.PaidAt.IsZero() {
+		return NormalizedApplicationInput{}, errors.New(errors.CodeInvalidParam, "付款时间必填")
+	}
+	payerName := strings.TrimSpace(input.PayerName)
+	if payerName == "" {
+		return NormalizedApplicationInput{}, errors.New(errors.CodeInvalidParam, "付款方名称必填")
+	}
+	if utf8.RuneCountInString(payerName) > constants.EmployeeCollectionPayerNameMaxLength {
+		return NormalizedApplicationInput{}, errors.New(errors.CodeInvalidParam, "付款方名称长度超出限制")
+	}
+	externalTransactionNo := strings.TrimSpace(input.ExternalTransactionNo)
+	if externalTransactionNo == "" {
+		return NormalizedApplicationInput{}, errors.New(errors.CodeInvalidParam, "外部交易流水号必填")
+	}
+	if utf8.RuneCountInString(externalTransactionNo) > constants.EmployeeCollectionExternalTransactionNoMaxLength {
+		return NormalizedApplicationInput{}, errors.New(errors.CodeInvalidParam, "外部交易流水号长度超出限制")
+	}
+	remark := strings.TrimSpace(input.Remark)
+	if utf8.RuneCountInString(remark) > constants.EmployeeCollectionRemarkMaxLength {
+		return NormalizedApplicationInput{}, errors.New(errors.CodeInvalidParam, "核销申请备注长度超出限制")
+	}
+	actingReason := strings.TrimSpace(input.ActingReason)
+	if utf8.RuneCountInString(actingReason) > constants.EmployeeCollectionRemarkMaxLength {
+		return NormalizedApplicationInput{}, errors.New(errors.CodeInvalidParam, "代办原因长度超出限制")
+	}
+	if acting && actingReason == "" {
+		return NormalizedApplicationInput{}, errors.New(errors.CodeInvalidParam, "超级管理员代办核销申请必须填写代办原因")
+	}
+	if !acting && actingReason != "" {
+		return NormalizedApplicationInput{}, errors.New(errors.CodeInvalidParam, "本人办理核销申请不能填写代办原因")
+	}
+	vouchers, err := NormalizePaymentVouchers(input.PaymentVoucherKeys)
+	if err != nil {
+		return NormalizedApplicationInput{}, err
+	}
+	return NormalizedApplicationInput{
+		PaidAmount: input.PaidAmount, PayerName: payerName,
+		PaidAt: input.PaidAt.UTC(), ExternalTransactionNo: externalTransactionNo,
+		Remark: remark, ActingReason: actingReason, PaymentVoucherKeys: vouchers,
+	}, nil
+}
+
+// ValidateApplicationResubmit 校验申请当前状态允许修改并重提。
+// 只有企业微信最终驳回的申请可以修改重提；已通过、审批中与异常终态一律拒绝。
+func ValidateApplicationResubmit(status int) error {
+	if status == constants.EmployeeCollectionApplicationStatusRejected {
+		return nil
+	}
+	return errors.New(errors.CodeEmployeeCollectionApplicationStatusInvalid)
+}
+
+// MaskExternalTransactionNo 生成外部交易流水号的脱敏展示，用于审计与日志，不保留完整流水。
+// 长度不超过 8 时整体掩码，否则保留首尾各 4 位。
+func MaskExternalTransactionNo(value string) string {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return ""
+	}
+	runes := []rune(trimmed)
+	if len(runes) <= 8 {
+		return "****"
+	}
+	return string(runes[:4]) + "****" + string(runes[len(runes)-4:])
+}

internal/domain/employeecollection/approval_opinion.go

@@ -0,0 +1,51 @@
+package employeecollection
+
+import (
+	"strings"
+
+	"github.com/bytedance/sonic"
+)
+
+// ExtractApprovalOpinion 从通用审批实例的终态决策快照中提取审批意见文本。
+// 快照来自渠道审批详情（`info` 对象），审批意见位于 `comments[].comment_content`；
+// 兼容 `content` 与 `text` 两种等价键。取最后一条非空意见作为最终审批意见。
+// 无法解析或没有意见时返回空字符串：意见缺失不影响申请与账单事实。
+func ExtractApprovalOpinion(snapshot []byte) string {
+	if len(snapshot) == 0 {
+		return ""
+	}
+	var payload map[string]any
+	if err := sonic.Unmarshal(snapshot, &payload); err != nil {
+		return ""
+	}
+	opinion := ""
+	if raw, ok := payload["comments"].([]any); ok {
+		for _, item := range raw {
+			comment, ok := item.(map[string]any)
+			if !ok {
+				continue
+			}
+			if content := commentText(comment); content != "" {
+				opinion = content
+			}
+		}
+	}
+	if opinion != "" {
+		return opinion
+	}
+	return commentText(payload)
+}
+
+// commentText 按优先顺序读取审批意见文本。
+func commentText(container map[string]any) string {
+	for _, key := range []string{"comment_content", "content", "text"} {
+		value, ok := container[key].(string)
+		if !ok {
+			continue
+		}
+		if trimmed := strings.TrimSpace(value); trimmed != "" {
+			return trimmed
+		}
+	}
+	return ""
+}

internal/domain/employeecollection/bill.go

@@ -0,0 +1,173 @@
+// Package employeecollection 收口员工代收款账单的金额、状态与预占不变量。
+// 只依赖标准库、领域常量和稳定错误，不依赖传输、持久化或外部 SDK。
+package employeecollection
+
+import (
+	"strings"
+	"unicode/utf8"
+
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// BillAmounts 描述一张员工代收款账单的应收、已核销、审批中预占与关闭事实。
+type BillAmounts struct {
+	// Receivable 表示应收金额（分），来源成功事务判定后不允许为负。
+	Receivable int64
+	// Received 表示企业微信最终通过后累计的已核销金额（分）。
+	Received int64
+	// Reserved 表示审批中分摊预占的金额（分）。
+	Reserved int64
+	// Closed 表示账单是否已关闭；已关闭账单的可核销余额为 0。
+	Closed bool
+}
+
+// NewBillAmounts 依据来源应收金额构造初始账单金额事实。
+// 应收金额必须大于零，避免零元账单立即成为已核销。
+func NewBillAmounts(receivable int64) (BillAmounts, error) {
+	amounts := BillAmounts{Receivable: receivable}
+	if err := amounts.Validate(); err != nil {
+		return BillAmounts{}, err
+	}
+	return amounts, nil
+}
+
+// Validate 校验账单金额不变量：应收为正，已核销与预占非负且合计不超过应收。
+func (a BillAmounts) Validate() error {
+	if a.Receivable <= 0 {
+		return errors.New(errors.CodeInvalidParam, "账单应收金额必须大于零")
+	}
+	if a.Received < 0 || a.Reserved < 0 {
+		return errors.New(errors.CodeInvalidParam, "账单已核销与预占金额不能为负")
+	}
+	if a.Received+a.Reserved > a.Receivable {
+		return errors.New(errors.CodeInvalidParam, "账单已核销与预占金额合计不能超过应收金额")
+	}
+	return nil
+}
+
+// Available 返回账单当前可被新分摊占用的金额；已关闭账单始终返回 0。
+func (a BillAmounts) Available() int64 {
+	if a.Closed {
+		return 0
+	}
+	available := a.Receivable - a.Received - a.Reserved
+	if available < 0 {
+		return 0
+	}
+	return available
+}
+
+// DerivedStatus 依据金额推导未关闭账单的核销状态。
+// 调用方必须自行区分已关闭账单，关闭状态不可由金额推导。
+func (a BillAmounts) DerivedStatus() int {
+	switch {
+	case a.Received <= 0:
+		return constants.EmployeeCollectionBillStatusPending
+	case a.Received >= a.Receivable:
+		return constants.EmployeeCollectionBillStatusSettled
+	default:
+		return constants.EmployeeCollectionBillStatusPartial
+	}
+}
+
+// Reserve 在审批中预占指定金额，返回预占后的新金额事实。
+// 分摊金额必须大于零且不超过当前可核销余额。
+func (a BillAmounts) Reserve(amount int64) (BillAmounts, error) {
+	if amount <= 0 {
+		return BillAmounts{}, errors.New(errors.CodeEmployeeCollectionAllocationAmountInvalid)
+	}
+	if err := a.ensureSettleable(); err != nil {
+		return BillAmounts{}, err
+	}
+	if amount > a.Available() {
+		return BillAmounts{}, errors.New(errors.CodeEmployeeCollectionAllocationExceeded)
+	}
+	a.Reserved += amount
+	return a, nil
+}
+
+// Release 释放指定金额的审批中预占，返回释放后的新金额事实。
+func (a BillAmounts) Release(amount int64) (BillAmounts, error) {
+	if amount <= 0 {
+		return BillAmounts{}, errors.New(errors.CodeEmployeeCollectionAllocationAmountInvalid)
+	}
+	if amount > a.Reserved {
+		return BillAmounts{}, errors.New(errors.CodeInternalError, "释放的预占金额超过账单当前预占")
+	}
+	a.Reserved -= amount
+	return a, nil
+}
+
+// Approve 将指定金额从审批中预占转入已核销，返回通过后的新金额事实。
+func (a BillAmounts) Approve(amount int64) (BillAmounts, error) {
+	if amount <= 0 {
+		return BillAmounts{}, errors.New(errors.CodeEmployeeCollectionAllocationAmountInvalid)
+	}
+	if amount > a.Reserved {
+		return BillAmounts{}, errors.New(errors.CodeInternalError, "通过的分摊金额超过账单当前预占")
+	}
+	a.Reserved -= amount
+	a.Received += amount
+	return a, nil
+}
+
+// ReduceReceivable 按来源订单退款金额冲减应收，仅在账单不存在任何已通过或审批中分摊时允许。
+func (a BillAmounts) ReduceReceivable(amount int64) (BillAmounts, error) {
+	if amount <= 0 {
+		return BillAmounts{}, errors.New(errors.CodeInvalidParam, "冲减金额必须大于零")
+	}
+	if a.Received > 0 || a.Reserved > 0 {
+		return BillAmounts{}, errors.New(errors.CodeEmployeeCollectionBillNotSettleable, "账单存在分摊，不能冲减应收")
+	}
+	if amount >= a.Receivable {
+		return BillAmounts{}, errors.New(errors.CodeInvalidParam, "冲减金额必须小于账单应收金额")
+	}
+	a.Receivable -= amount
+	return a, nil
+}
+
+// ensureSettleable 校验账单允许产生新的审批中分摊。
+func (a BillAmounts) ensureSettleable() error {
+	if a.Closed {
+		return errors.New(errors.CodeEmployeeCollectionBillClosed)
+	}
+	if a.DerivedStatus() == constants.EmployeeCollectionBillStatusSettled {
+		return errors.New(errors.CodeEmployeeCollectionBillNotSettleable)
+	}
+	return nil
+}
+
+// BillCloseInput 描述关闭一张账单前的事实。
+type BillCloseInput struct {
+	// Status 表示账单当前持久化状态。
+	Status int
+	// PendingAllocations 表示账单上仍处于审批中（预占）的分摊数量。
+	PendingAllocations int64
+	// Reason 表示关闭原因，必填。
+	Reason string
+}
+
+// ValidateBillClose 校验关闭账单的前置条件。
+// 已关闭账单返回账单已关闭，已核销账单不允许关闭，存在审批中分摊时拒绝关闭，关闭原因必填。
+func ValidateBillClose(input BillCloseInput) error {
+	if input.Status == constants.EmployeeCollectionBillStatusClosed {
+		return errors.New(errors.CodeEmployeeCollectionBillClosed)
+	}
+	if input.Status == constants.EmployeeCollectionBillStatusSettled {
+		return errors.New(errors.CodeEmployeeCollectionBillNotSettleable, "已核销账单没有未核销余额，不能关闭")
+	}
+	if input.Status != constants.EmployeeCollectionBillStatusPending &&
+		input.Status != constants.EmployeeCollectionBillStatusPartial {
+		return errors.New(errors.CodeConflict, "账单当前状态不允许关闭")
+	}
+	if input.PendingAllocations > 0 {
+		return errors.New(errors.CodeEmployeeCollectionApplicationPending)
+	}
+	if trimmed := strings.TrimSpace(input.Reason); trimmed == "" {
+		return errors.New(errors.CodeInvalidParam, "关闭原因必填")
+	} else if utf8.RuneCountInString(trimmed) > constants.EmployeeCollectionRemarkMaxLength {
+		return errors.New(errors.CodeInvalidParam, "关闭原因长度超出限制")
+	}
+	return nil
+}

internal/domain/employeecollection/order_bill.go

@@ -0,0 +1,56 @@
+package employeecollection
+
+import (
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+)
+
+// OrderBillSubject 是判定后台线下套餐订单是否建账所需的来源事实。
+// 四个条件必须同时成立，判定只由 ShouldCreateBillForOrder 一处实现。
+type OrderBillSubject struct {
+	// PaymentMethod 表示订单支付方式快照。
+	PaymentMethod string
+	// OperatorAccountType 表示实际操作账号类型快照。
+	OperatorAccountType string
+	// ActualPaidAmount 表示订单实际支付金额（分），空表示来源未产生实收金额。
+	ActualPaidAmount *int64
+	// HasGiftPackage 表示订单是否包含赠送套餐。
+	HasGiftPackage bool
+}
+
+// OrderBillSubjectFromOrder 从已冻结的订单事实提取建账判据输入。
+// 建账与创建时付款凭证放宽必须使用同一份输入，避免出现两套口径。
+func OrderBillSubjectFromOrder(order *model.Order, hasGiftPackage bool) OrderBillSubject {
+	if order == nil {
+		return OrderBillSubject{}
+	}
+	return OrderBillSubject{
+		PaymentMethod:       order.PaymentMethod,
+		OperatorAccountType: order.OperatorAccountType,
+		ActualPaidAmount:    order.ActualPaidAmount,
+		HasGiftPackage:      hasGiftPackage,
+	}
+}
+
+// ShouldCreateBillForOrder 判定后台线下套餐订单是否触发员工代收款建账。
+// 判据：支付方式为线下、实际操作账号为平台账号、订单不含赠送套餐、实收金额大于零。
+func ShouldCreateBillForOrder(subject OrderBillSubject) bool {
+	return subject.PaymentMethod == model.PaymentMethodOffline &&
+		subject.OperatorAccountType == model.OperatorAccountTypePlatform &&
+		!subject.HasGiftPackage &&
+		subject.ActualPaidAmount != nil && *subject.ActualPaidAmount > 0
+}
+
+// RechargeBillSubject 是判定代理线下充值入账是否建账所需的来源事实。
+type RechargeBillSubject struct {
+	// PaymentMethod 表示充值记录支付方式。
+	PaymentMethod string
+	// Amount 表示充值记录金额（分）。
+	Amount int64
+}
+
+// ShouldCreateBillForRecharge 判定代理线下充值入账是否触发员工代收款建账。
+// 判据：支付方式为线下且入账金额大于零；零金额无法形成正的应收金额。
+func ShouldCreateBillForRecharge(subject RechargeBillSubject) bool {
+	return subject.PaymentMethod == constants.RechargeMethodOffline && subject.Amount > 0
+}

internal/domain/employeecollection/payment_method.go

@@ -0,0 +1,69 @@
+package employeecollection
+
+import (
+	"strings"
+	"unicode"
+
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// PaymentMethodInput 是线下收款方式字典写入的领域输入。
+type PaymentMethodInput struct {
+	// Code 表示稳定编码，创建后仅可在未被引用时修改。
+	Code string
+	// Name 表示收款方式名称。
+	Name string
+	// SortOrder 表示排序值，必须非负。
+	SortOrder int64
+	// Status 表示启停状态，取值见 constants.EmployeeCollectionPaymentMethodStatus*。
+	Status int
+	// Remark 表示备注。
+	Remark string
+}
+
+// NormalizedPaymentMethodInput 是通过校验并去空格后的字典写入事实。
+type NormalizedPaymentMethodInput struct {
+	Code      string
+	Name      string
+	SortOrder int64
+	Status    int
+	Remark    string
+}
+
+// NormalizePaymentMethodInput 校验并规范化线下收款方式字典写入输入。
+// 规则：编码 1 至 64 字符且不含空白或控制字符、名称 1 至 100 字符、
+// 排序值非负、状态仅允许启用或停用、备注不超过 500 字符。
+func NormalizePaymentMethodInput(input PaymentMethodInput) (NormalizedPaymentMethodInput, error) {
+	code := strings.TrimSpace(input.Code)
+	if code == "" {
+		return NormalizedPaymentMethodInput{}, errors.New(errors.CodeInvalidParam, "收款方式编码必填")
+	}
+	if len([]rune(code)) > constants.EmployeeCollectionCodeMaxLength {
+		return NormalizedPaymentMethodInput{}, errors.New(errors.CodeInvalidParam, "收款方式编码长度超出限制")
+	}
+	if strings.IndexFunc(code, func(r rune) bool { return unicode.IsSpace(r) || unicode.IsControl(r) }) >= 0 {
+		return NormalizedPaymentMethodInput{}, errors.New(errors.CodeInvalidParam, "收款方式编码不能包含空白或控制字符")
+	}
+	name := strings.TrimSpace(input.Name)
+	if name == "" {
+		return NormalizedPaymentMethodInput{}, errors.New(errors.CodeInvalidParam, "收款方式名称必填")
+	}
+	if len([]rune(name)) > constants.EmployeeCollectionNameMaxLength {
+		return NormalizedPaymentMethodInput{}, errors.New(errors.CodeInvalidParam, "收款方式名称长度超出限制")
+	}
+	if input.SortOrder < 0 {
+		return NormalizedPaymentMethodInput{}, errors.New(errors.CodeInvalidParam, "收款方式排序值不能为负")
+	}
+	if input.Status != constants.EmployeeCollectionPaymentMethodStatusDisabled &&
+		input.Status != constants.EmployeeCollectionPaymentMethodStatusEnabled {
+		return NormalizedPaymentMethodInput{}, errors.New(errors.CodeInvalidParam, "收款方式状态仅支持停用或启用")
+	}
+	remark := strings.TrimSpace(input.Remark)
+	if len([]rune(remark)) > constants.EmployeeCollectionRemarkMaxLength {
+		return NormalizedPaymentMethodInput{}, errors.New(errors.CodeInvalidParam, "收款方式备注长度超出限制")
+	}
+	return NormalizedPaymentMethodInput{
+		Code: code, Name: name, SortOrder: input.SortOrder, Status: input.Status, Remark: remark,
+	}, nil
+}

internal/domain/employeecollection/refund_offset.go

@@ -0,0 +1,37 @@
+package employeecollection
+
+import (
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// RefundOffsetDecision 是来源订单退款成功对账单的处理判定结果。
+type RefundOffsetDecision struct {
+	// Outcome 取值见 constants.EmployeeCollectionRefundOutcome*。
+	Outcome string
+	// ReducedAmount 是本次实际冲减的应收金额（分），仅 reduced 时大于零。
+	ReducedAmount int64
+}
+
+// DecideRefundOffset 判定来源订单本次退款成功金额对账单的处理方式。
+// 判定顺序：已关闭账单与存在已通过或审批中分摊的账单只写退款关联提示，
+// 其余按退款成功金额与账单应收比较，等于或超过应收时关闭账单，小于应收时按退款金额冲减。
+// 已通过分摊体现为 received_amount > 0，审批中分摊体现为 reserved_amount > 0；
+// 这两个金额只由本能力的条件更新维护，因此与「存在已通过或审批中分摊」等价。
+func DecideRefundOffset(bill BillAmounts, refundAmount int64) (RefundOffsetDecision, error) {
+	if refundAmount <= 0 {
+		return RefundOffsetDecision{}, errors.New(errors.CodeInvalidParam, "退款成功金额必须大于零")
+	}
+	if err := bill.Validate(); err != nil {
+		return RefundOffsetDecision{}, err
+	}
+	if bill.Closed || bill.Received > 0 || bill.Reserved > 0 {
+		return RefundOffsetDecision{Outcome: constants.EmployeeCollectionRefundOutcomeHintOnly}, nil
+	}
+	if refundAmount >= bill.Receivable {
+		return RefundOffsetDecision{Outcome: constants.EmployeeCollectionRefundOutcomeClosedFull}, nil
+	}
+	return RefundOffsetDecision{
+		Outcome: constants.EmployeeCollectionRefundOutcomeReduced, ReducedAmount: refundAmount,
+	}, nil
+}

internal/domain/employeecollection/source.go

@@ -0,0 +1,14 @@
+package employeecollection
+
+import "strconv"
+
+// OrderSourceKey 返回后台线下套餐订单来源的账单唯一键。
+// 该键是 tb_employee_collection_bill.source_key 的持久化契约，同一来源至多一张账单。
+func OrderSourceKey(orderID uint) string {
+	return "order:" + strconv.FormatUint(uint64(orderID), 10)
+}
+
+// RechargeSourceKey 返回代理线下充值来源的账单唯一键。
+func RechargeSourceKey(rechargeID uint) string {
+	return "recharge:" + strconv.FormatUint(uint64(rechargeID), 10)
+}

internal/domain/employeecollection/voucher.go

@@ -0,0 +1,35 @@
+package employeecollection
+
+import (
+	"strings"
+
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// NormalizePaymentVouchers 校验并规范化支付凭证对象键列表。
+// 规则：数量必须在 1 至 5 个之间、每个键去空格后非空且不超过长度上限、不允许重复。
+// 只接受对象存储键引用，不接受内联内容，避免敏感付款材料进入业务事实。
+func NormalizePaymentVouchers(keys []string) ([]string, error) {
+	if len(keys) < constants.EmployeeCollectionVoucherMinCount ||
+		len(keys) > constants.EmployeeCollectionVoucherMaxCount {
+		return nil, errors.New(errors.CodeEmployeeCollectionVoucherInvalid)
+	}
+	normalized := make([]string, 0, len(keys))
+	seen := make(map[string]struct{}, len(keys))
+	for _, key := range keys {
+		trimmed := strings.TrimSpace(key)
+		if trimmed == "" {
+			return nil, errors.New(errors.CodeEmployeeCollectionVoucherInvalid)
+		}
+		if len([]rune(trimmed)) > constants.EmployeeCollectionVoucherKeyMaxLength {
+			return nil, errors.New(errors.CodeEmployeeCollectionVoucherInvalid)
+		}
+		if _, exists := seen[trimmed]; exists {
+			return nil, errors.New(errors.CodeEmployeeCollectionVoucherInvalid)
+		}
+		seen[trimmed] = struct{}{}
+		normalized = append(normalized, trimmed)
+	}
+	return normalized, nil
+}