feat(代理自充): AUG26-017 代理自充收款方式与线下预存款审批字段

- 受控配置新增代理在线自充允许范围（仅微信/仅支付宝/同时支持），读侧与创建侧取允许范围与可用商户池交集，两侧失败关闭
- 新增允许范围查询与修改端点，读限代理与平台账号、写限超级管理员，复用受控配置写服务留痕
- tb_agent_recharge_record 新增交易流水号、线下收款方式三列快照与其他凭证列（成对迁移 000213）
- 线下申请校验启用的收款方式字典项与必填交易流水号，交易流水号独立于在线渠道交易号、不参与去重
- 扩展 offline_recharge_approval 场景可映射字段白名单与字典引用保护
- 新增付款凭证识别能力与交易流水号预填接口，识别不落库、日志不记录载荷

.gitea/workflows/deploy.yaml

@@ -3,9 +3,7 @@ name: 构建并部署到测试环境（无 SSH）
 on:
   push:
     branches:
-      - Iteration/7-11
-      - dev
-      - test
+      - Iteration/8-11
 
 env:
   REGISTRY: registry.boss160.cn
@@ -30,15 +28,7 @@ jobs:
       - name: 设置镜像标签
         id: tag
         run: |
-          if [ "${{ github.ref }}" = "refs/heads/Iteration/7-11" ]; then
-            echo "tag=latest" >> $GITHUB_OUTPUT
-          elif [ "${{ github.ref }}" = "refs/heads/dev" ]; then
-            echo "tag=dev" >> $GITHUB_OUTPUT
-          elif [ "${{ github.ref }}" = "refs/heads/test" ]; then
-            echo "tag=test" >> $GITHUB_OUTPUT
-          else
-            echo "tag=unknown" >> $GITHUB_OUTPUT
-          fi
+          echo "tag=${{ github.sha }}" >> $GITHUB_OUTPUT
 
       - name: 登录 Docker Registry
         run: |
@@ -47,28 +37,25 @@ jobs:
       - name: 构建 API 镜像
         run: |
           docker build -f Dockerfile.api -t ${{ env.API_IMAGE }}:${{ steps.tag.outputs.tag }} .
-          docker tag ${{ env.API_IMAGE }}:${{ steps.tag.outputs.tag }} ${{ env.API_IMAGE }}:${{ github.sha }}
 
       - name: 构建 Worker 镜像
         run: |
           docker build -f Dockerfile.worker -t ${{ env.WORKER_IMAGE }}:${{ steps.tag.outputs.tag }} .
-          docker tag ${{ env.WORKER_IMAGE }}:${{ steps.tag.outputs.tag }} ${{ env.WORKER_IMAGE }}:${{ github.sha }}
 
       - name: 推送镜像到 Registry
         run: |
           docker push ${{ env.API_IMAGE }}:${{ steps.tag.outputs.tag }}
-          docker push ${{ env.API_IMAGE }}:${{ github.sha }}
           docker push ${{ env.WORKER_IMAGE }}:${{ steps.tag.outputs.tag }}
-          docker push ${{ env.WORKER_IMAGE }}:${{ github.sha }}
 
-      - name: 部署到本地（仅 Iteration/7-11 分支）
-        if: github.ref == 'refs/heads/Iteration/7-11'
+      - name: 部署到测试环境（仅八月迭代分支）
+        if: github.ref == 'refs/heads/Iteration/8-11'
         run: |
           # 确保部署目录存在（仅需日志目录，配置已嵌入二进制文件）
           mkdir -p ${{ env.DEPLOY_DIR }}/logs
 
           umask 077
           {
+            printf 'IMAGE_TAG=%s\n' '${{ github.sha }}'
             printf 'JUNHONG_APPROVAL_LEGACY_REFUND_MANUAL_ENABLED=true\n'
             printf 'JUNHONG_APPROVAL_LEGACY_OFFLINE_RECHARGE_PAY_ENABLED=true\n'
             printf 'JUNHONG_WORKER_ROLE=all\n'

.gitignore

@@ -111,6 +111,4 @@ scripts/batch_package_purchase/assets.example_购买结果_20260715_115804.csv
 scripts/batch_package_purchase/assets.example_购买结果_20260715_115814.csv
 scripts/migration/output
 
-# LongHorizon 本地执行证据
-.lh-harness/
 .scratch/go-build-cache

AGENTS.md

@@ -38,10 +38,10 @@
 - 行为变化必须通过独立 OpenSpec Change；主 Specs 只描述当前行为。
 - 当前 Bug 与兼容行为按实际结果记录，禁止在基线任务中顺手修复。
 - 不修改既有迁移；新 Schema 变化使用新的成对迁移。
-- 不访问生产服务、真实支付渠道或外部审批系统进行自动验证。
-- 生产环境为 systemd 管理的手工二进制发布，和仓库 Docker/CI 测试环境不同；生产发布、迁移与回滚事实见 [`docs/deployment/production-runbook.md`](docs/deployment/production-runbook.md)。Agent 不连接生产主机或数据库，生产操作由维护者执行并提供结果。
+- 不访问真实支付渠道或外部审批系统进行自动验证。
+- 生产环境为 systemd 管理的手工二进制发布，和仓库 Docker/CI 测试环境不同；生产发布、迁移与回滚事实见 [`docs/deployment/production-runbook.md`](docs/deployment/production-runbook.md)。Agent 可仅通过 dbhub 对生产数据库执行只读诊断查询；不连接生产主机，生产发布、迁移、回滚及其他写操作由维护者执行并提供结果,除非明确要求。
 - 不把密钥、Token、证书或个人敏感数据写入代码、文档和日志。
-- `.lh-harness/` 仅保存本地执行证据，不是事实源且不得纳入 Git。
+- `docs/verification/context-reset/` 仅保存上下文健康检查证据，不是业务事实源；证据应随项目文档维护。
 - 自动化测试当前为 N/A（用户决策）；不恢复旧测试，也不写虚假测试入口。
 
 ## 架构选择
@@ -84,6 +84,7 @@ openspec validate --all
 ```
 
 启动、隔离数据库重置、smoke 与日志读取见 [`README.md`](README.md)。迁移使用 `scripts/migrate.sh` 和显式 `DB_*` 参数；生产迁移仅按生产运行说明由维护者手工执行。
+- 测试验证：涉及迁移、Redis、部署或集成 Smoke 时，MUST 读取 [`docs/engineering/工程约束.md`](docs/engineering/工程约束.md) 的 ENG-TEST-001；维护者指定的测试环境是唯一验证面。
 
 ## 渐进披露
 

Dockerfile.api

@@ -32,7 +32,9 @@ RUN GOOS=linux GOARCH=amd64 go build \
     ./cmd/api
 
 # 下载 golang-migrate 工具（使用 GOPROXY 加速）
-RUN go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest
+# 固定 v4.19.1：其 go.mod 仅要求 go 1.24.0，与基础镜像 Go 1.25.6 兼容；
+# @latest（如 v4.20.1）要求 Go >= 1.25.11，在 GOTOOLCHAIN=local 的 1.25.6 环境下构建失败
+RUN go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@v4.19.1
 
 # ================================
 # 阶段 2: 运行阶段

cmd/api/docs.go

@@ -29,6 +29,8 @@ func generateOpenAPIDocs(outputPath string, logger *zap.Logger) {
 	handlers.AssetPackageBatchOrder = admin.NewAssetPackageBatchOrderHandler(nil, nil)
 	// 企业微信 Handler 在此显式装配，避免新增管理接口遗漏文档注册。
 	handlers.WeCom = admin.NewWeComHandler(nil, nil)
+	handlers.PaymentMerchant = admin.NewPaymentMerchantHandler(nil)
+	handlers.EmployeeCollection = admin.NewEmployeeCollectionHandler(nil, nil, nil)
 	handlers.CTCCRealnameCallback = callback.NewCTCCRealnameHandler(nil, nil, nil, nil, nil, nil, nil)
 	handlers.CMCCRealnameCallback = callback.NewCMCCRealnameHandler(nil, nil, nil, nil, nil, nil, nil)
 	handlers.CUCCRealnameCallback = callback.NewCUCCRealnameHandler(nil, nil, nil, nil, nil, nil, nil)

cmd/audit-retention-simulate/main.go

@@ -1,4 +1,4 @@
-// Command audit-retention-simulate 在测试环境演练完整自然月归档与清理边界。
+// Command audit-retention-simulate 在测试环境演练逐日归档与清理边界。
 package main
 
 import (
@@ -6,22 +6,21 @@ import (
 	"crypto/sha256"
 	"fmt"
 	"os"
+	"path/filepath"
 	"strings"
 	"time"
 
 	"github.com/bytedance/sonic"
-	"github.com/hibiken/asynq"
 	"go.uber.org/zap"
 	"gorm.io/datatypes"
 	"gorm.io/gorm"
 
 	auditarchive "github.com/break/junhong_cmp_fiber/internal/application/auditarchive"
-	auditinfra "github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
 	"github.com/break/junhong_cmp_fiber/internal/model"
-	taskapp "github.com/break/junhong_cmp_fiber/internal/task"
 	"github.com/break/junhong_cmp_fiber/pkg/config"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/database"
+	logpkg "github.com/break/junhong_cmp_fiber/pkg/logger"
 	"github.com/break/junhong_cmp_fiber/pkg/storage"
 )
 
@@ -67,6 +66,11 @@ func run(ctx context.Context) error {
 		return fmt.Errorf("仅允许显式确认的测试数据库，当前数据库为 %q", cfg.Database.DBName)
 	}
 	logger := zap.NewNop()
+	if err := os.MkdirAll(filepath.Dir(cfg.Logging.RetentionLog.Filename), 0755); err != nil {
+		return err
+	}
+	retentionLogger, syncRetentionLogger := logpkg.NewRetentionLogger(cfg.Logging.Level, logpkg.LogRotationConfig{Filename: cfg.Logging.RetentionLog.Filename, MaxSize: cfg.Logging.RetentionLog.MaxSize, MaxBackups: cfg.Logging.RetentionLog.MaxBackups, MaxAge: cfg.Logging.RetentionLog.MaxAge, Compress: cfg.Logging.RetentionLog.Compress})
+	defer func() { _ = syncRetentionLogger() }()
 	db, err := database.InitPostgreSQL(&cfg.Database, logger)
 	if err != nil {
 		return err
@@ -81,8 +85,7 @@ func run(ctx context.Context) error {
 	if err != nil {
 		return err
 	}
-	auditWriter := auditinfra.NewWriter(auditinfra.NewRegistry(), nil)
-	service, err := auditarchive.NewService(db, provider, simulationInstance, auditWriter)
+	service, err := auditarchive.NewService(db, provider, simulationInstance)
 	if err != nil {
 		return err
 	}
@@ -108,14 +111,17 @@ func run(ctx context.Context) error {
 		}
 	}
 
-	payload, _ := sonic.Marshal(taskapp.AuditMonthlyRetentionPayload{ArchiveMonth: simulationMonth})
-	dryRunTask := asynq.NewTask(constants.TaskTypeAuditMonthlyRetention, payload)
-	if err := taskapp.NewAuditMonthlyRetentionHandler(service, logger, false).Handle(ctx, dryRunTask); err != nil {
-		return fmt.Errorf("月度只读演练失败: %w", err)
-	}
-	dryRun, err := service.ValidateMonth(ctx, monthStart)
-	if err != nil {
-		return err
+	var dryRun auditarchive.RetentionResult
+	for date := monthStart; date.Before(monthEnd); date = date.AddDate(0, 0, 1) {
+		result, retainErr := service.RetainDate(ctx, date, false)
+		if retainErr != nil {
+			return fmt.Errorf("逐日只读演练失败: %w", retainErr)
+		}
+		retentionLogger.Info("日留存仿真只读校验通过", zap.String("archive_date", result.ArchiveDate))
+		dryRun.EventCount += result.EventCount
+		dryRun.ResourceCount += result.ResourceCount
+		dryRun.IntegrationCount += result.IntegrationCount
+		dryRun.EstimatedBatches += result.EstimatedBatches
 	}
 	summary, err := collectBeforeCleanup(ctx, db, monthStart, monthEnd, dryRun)
 	if err != nil {
@@ -125,16 +131,39 @@ func run(ctx context.Context) error {
 		return fmt.Errorf("只归档模式写入了 %d 个清理断点", summary.CleanupMarkersBefore)
 	}
 
-	cleanupTask := asynq.NewTask(constants.TaskTypeAuditMonthlyRetention, payload)
-	if err := taskapp.NewAuditMonthlyRetentionHandler(service, logger, true).Handle(ctx, cleanupTask); err != nil {
-		return fmt.Errorf("隔离测试库物理清理演练失败: %w", err)
+	for date := monthStart; date.Before(monthEnd); date = date.AddDate(0, 0, 1) {
+		result, retainErr := service.RetainDate(ctx, date, true)
+		if retainErr != nil {
+			return fmt.Errorf("隔离测试库逐日物理清理演练失败: %w", retainErr)
+		}
+		retentionLogger.Info("日留存仿真物理清理完成", zap.String("archive_date", result.ArchiveDate))
 	}
 	if err := collectAfterCleanup(ctx, db, monthStart, monthEnd, &summary); err != nil {
 		return err
 	}
-	if summary.TargetRowsAfterCleanup != 0 || summary.BoundaryRowsAfterCleanup != 6 || summary.CleanupMarkersAfter != int64(summary.Days*2) || !summary.RetentionAuditRecorded {
-		return fmt.Errorf("清理范围复核失败: target=%d boundary=%d markers=%d audit=%t",
-			summary.TargetRowsAfterCleanup, summary.BoundaryRowsAfterCleanup, summary.CleanupMarkersAfter, summary.RetentionAuditRecorded)
+	if summary.TargetRowsAfterCleanup != 1 || summary.BoundaryRowsAfterCleanup != 6 || summary.CleanupMarkersAfter != int64(summary.Days*2) {
+		return fmt.Errorf("清理范围复核失败: target=%d boundary=%d markers=%d", summary.TargetRowsAfterCleanup, summary.BoundaryRowsAfterCleanup, summary.CleanupMarkersAfter)
+	}
+	if err := db.WithContext(ctx).Model(&model.IntegrationLog{}).
+		Where("integration_id = ?", "int_"+simulationPrefix+"-"+monthStart.Format("20060102")).
+		Updates(map[string]any{"result": constants.IntegrationResultSuccess, "updated_at": time.Now()}).Error; err != nil {
+		return err
+	}
+	if _, err := service.RetainDate(ctx, monthStart, true); err != nil {
+		return fmt.Errorf("pending 终结后的续跑清理演练失败: %w", err)
+	}
+	var remaining int64
+	if err := db.WithContext(ctx).Model(&model.IntegrationLog{}).Where("created_at >= ? AND created_at < ?", monthStart, monthEnd).Count(&remaining).Error; err != nil {
+		return err
+	}
+	if remaining != 0 {
+		return fmt.Errorf("pending 终结后的续跑清理未完成，剩余 %d 条记录", remaining)
+	}
+	if err := syncRetentionLogger(); err != nil {
+		return fmt.Errorf("刷新日留存仿真日志失败: %w", err)
+	}
+	if _, err := os.Stat(cfg.Logging.RetentionLog.Filename); err != nil {
+		return fmt.Errorf("独立日留存日志未生成: %w", err)
 	}
 	encoded, _ := sonic.MarshalIndent(summary, "", "  ")
 	fmt.Println(string(encoded))
@@ -256,12 +285,7 @@ func archiveMonth(ctx context.Context, db *gorm.DB, service *auditarchive.Servic
 	if err := service.ArchiveDate(ctx, start); err != nil {
 		return fmt.Errorf("Audit 故障重试演练失败: %w", err)
 	}
-	if err := db.WithContext(ctx).Model(&model.IntegrationLog{}).
-		Where("integration_id = ?", "int_"+simulationPrefix+"-"+start.Format("20060102")).
-		Updates(map[string]any{"result": constants.IntegrationResultSuccess, "updated_at": time.Now()}).Error; err != nil {
-		return err
-	}
-	return service.FinalizeIntegrationMonth(ctx, start)
+	return nil
 }
 
 func collectBeforeCleanup(ctx context.Context, db *gorm.DB, start, end time.Time, dryRun auditarchive.RetentionResult) (simulationSummary, error) {
@@ -311,10 +335,5 @@ func collectAfterCleanup(ctx context.Context, db *gorm.DB, start, end time.Time,
 		Count(&summary.CleanupMarkersAfter).Error; err != nil {
 		return err
 	}
-	var auditCount int64
-	if err := db.WithContext(ctx).Model(&model.AuditEvent{}).Where("event_id = ?", "evt_retention_"+strings.ReplaceAll(simulationMonth, "-", "_")).Count(&auditCount).Error; err != nil {
-		return err
-	}
-	summary.RetentionAuditRecorded = auditCount == 1
 	return nil
 }

cmd/gendocs/main.go

@@ -38,6 +38,8 @@ func generateAdminDocs(outputPath string) error {
 	handlers.AssetPackageBatchOrder = admin.NewAssetPackageBatchOrderHandler(nil, nil)
 	// 企业微信 Handler 在此显式装配，避免新增管理接口遗漏文档注册。
 	handlers.WeCom = admin.NewWeComHandler(nil, nil)
+	handlers.PaymentMerchant = admin.NewPaymentMerchantHandler(nil)
+	handlers.EmployeeCollection = admin.NewEmployeeCollectionHandler(nil, nil, nil)
 	handlers.CTCCRealnameCallback = callback.NewCTCCRealnameHandler(nil, nil, nil, nil, nil, nil, nil)
 	handlers.CMCCRealnameCallback = callback.NewCMCCRealnameHandler(nil, nil, nil, nil, nil, nil, nil)
 	handlers.CUCCRealnameCallback = callback.NewCUCCRealnameHandler(nil, nil, nil, nil, nil, nil, nil)

cmd/worker/main.go

@@ -18,6 +18,8 @@ import (
 	approvalApp "github.com/break/junhong_cmp_fiber/internal/application/approval"
 	auditArchiveApp "github.com/break/junhong_cmp_fiber/internal/application/auditarchive"
 	cardObservationApp "github.com/break/junhong_cmp_fiber/internal/application/cardobservation"
+	employeecollectionApp "github.com/break/junhong_cmp_fiber/internal/application/employeecollection"
+	merchantpayment "github.com/break/junhong_cmp_fiber/internal/application/merchantpayment"
 	notificationApp "github.com/break/junhong_cmp_fiber/internal/application/notification"
 	walletApp "github.com/break/junhong_cmp_fiber/internal/application/wallet"
 	"github.com/break/junhong_cmp_fiber/internal/bootstrap"
@@ -122,6 +124,11 @@ func runWorker(cfg *config.Config) {
 	defer func() {
 		_ = logger.Sync() // 忽略 sync 错误
 	}()
+	retentionLogger, syncRetentionLogger := logger.NewRetentionLogger(cfg.Logging.Level, logger.LogRotationConfig{
+		Filename: cfg.Logging.RetentionLog.Filename, MaxSize: cfg.Logging.RetentionLog.MaxSize,
+		MaxBackups: cfg.Logging.RetentionLog.MaxBackups, MaxAge: cfg.Logging.RetentionLog.MaxAge, Compress: cfg.Logging.RetentionLog.Compress,
+	})
+	defer func() { _ = syncRetentionLogger() }()
 
 	appLogger := logger.GetAppLogger()
 	ctx, cancel := context.WithCancel(context.Background())
@@ -148,7 +155,7 @@ func runWorker(cfg *config.Config) {
 	taskHandler.RegisterHandlers()
 	registerWeComApprovalTasks(taskHandler.GetMux(), runtime, cfg, appLogger)
 	registerAgentRechargeRecoveryTask(taskHandler.GetMux(), runtime, appLogger)
-	registerAuditArchiveTask(taskHandler.GetMux(), runtime, cfg.Worker.AuditRetentionCleanupEnabled, appLogger)
+	registerAuditArchiveTask(taskHandler.GetMux(), runtime, cfg.Worker.AuditRetentionCleanupEnabled, cfg.Worker.AuditArchiveTasksEnabled, appLogger, retentionLogger)
 	outboxHandler := outbox.NewHandler(runtime.outboxConsumers)
 	taskHandler.GetMux().HandleFunc(constants.TaskTypeOutboxDeliver, outboxHandler.Handle)
 	startOutboxRelay(ctx, runtime, cfg.Worker.InstanceName, appLogger)
@@ -281,6 +288,7 @@ func initWorkerRuntime(ctx context.Context, cfg *config.Config, appLogger *zap.L
 		pollingIotCardStore,
 		appLogger,
 		cfg.Polling.VerboseLog,
+		cfg.Worker.PollingTotalMaxConcurrency,
 	)
 
 	pollingDeviceSimBindingStore := postgres.NewDeviceSimBindingStore(db, redisClient)
@@ -370,7 +378,12 @@ func registerWeComApprovalOutboxConsumer(runtime *workerRuntime, cfg *config.Con
 		walletApp.NewRefundService(walletInfra.NewRefundEventWriter(outbox.NewRepository()), nil),
 	)
 	refundService.SetNotificationOutbox(outbox.NewRepository())
+	refundService.SetPaymentMerchantRuntime(merchantpayment.NewRuntimeLoader(runtime.db, runtime.redisClient))
 	refundService.SetLifecycleAudit(auditWriter)
+	// 员工代收款退款冲销与建账共用同一审计 Writer，接入点仅在企微退款成功事务内。
+	refundService.SetEmployeeCollectionRefundOffset(
+		employeecollectionApp.NewRefundOffsetService(auditWriter),
+	)
 	if err := runtime.outboxConsumers.Register(commissionDelivery.EventRefundCommissionDeduct, commissionDelivery.NewRefundConsumer(refundService.ProcessCommissionDeduction, refundService.ProcessAssetPostProcessing)); err != nil {
 		appLogger.Fatal("注册退款佣金回扣 Outbox 消费者失败", zap.Error(err))
 	}
@@ -384,8 +397,14 @@ func registerWeComApprovalOutboxConsumer(runtime *workerRuntime, cfg *config.Con
 	decisionDispatcher := approvalApp.NewDecisionDispatcher(
 		approvalInfra.NewDecisionDeliveryStore(runtime.db),
 		map[string]approvalApp.BusinessDecisionHandler{
-			constants.ApprovalBusinessTypeOfflineRecharge: agentrechargeApp.NewApprovalDecisionHandler(runtime.db, walletPosting, runtime.workerResult.Services.RechargeAudit),
-			constants.ApprovalBusinessTypeRefund:          refundService,
+			constants.ApprovalBusinessTypeOfflineRecharge: agentrechargeApp.NewApprovalDecisionHandler(
+				runtime.db, walletPosting, runtime.workerResult.Services.RechargeAudit,
+				employeecollectionApp.NewBillCreationService(auditWriter),
+			),
+			constants.ApprovalBusinessTypeRefund: refundService,
+			constants.ApprovalBusinessTypeEmployeeCollection: employeecollectionApp.NewApprovalDecisionHandler(
+				runtime.db, auditWriter,
+			),
 		},
 		owner,
 		appLogger,
@@ -442,8 +461,10 @@ func registerAgentRechargeRecoveryTask(mux *asynq.ServeMux, runtime *workerRunti
 	)
 	recovery := agentrechargeApp.NewRecoverOnlinePaymentService(
 		runtime.db,
+		merchantpayment.NewRuntimeLoader(runtime.db, runtime.redisClient),
 		paymentInfra.NewWechatWebAdapter(wechat.NewRedisCache(runtime.redisClient), integration, appLogger),
 		paymentInfra.NewAlipayWapAdapter(integration, appLogger),
+		paymentInfra.NewFuiouScanAdapter(integration, appLogger),
 		confirm,
 		runtime.workerResult.Services.PaymentAudit,
 	)
@@ -687,7 +708,7 @@ func startAsynqScheduler(cfg *config.Config, redisAddr string, appLogger *zap.Lo
 		&asynq.SchedulerOpts{Location: time.Local},
 	)
 
-	if err := registerAsynqScheduleTasks(asynqScheduler); err != nil {
+	if err := registerAsynqScheduleTasks(asynqScheduler, cfg.Worker.AuditArchiveTasksEnabled); err != nil {
 		appLogger.Fatal("注册 Asynq 定时任务失败", zap.Error(err))
 	}
 
@@ -698,12 +719,14 @@ func startAsynqScheduler(cfg *config.Config, redisAddr string, appLogger *zap.Lo
 	}()
 
 	appLogger.Info("Asynq Scheduler 已启动",
-		zap.Bool("audit_retention_cleanup_enabled", cfg.Worker.AuditRetentionCleanupEnabled))
+		zap.Bool("audit_retention_cleanup_enabled", cfg.Worker.AuditRetentionCleanupEnabled),
+		zap.Bool("audit_archive_tasks_enabled", cfg.Worker.AuditArchiveTasksEnabled),
+		zap.Int("polling_total_max_concurrency", cfg.Worker.PollingTotalMaxConcurrency))
 	return asynqScheduler
 }
 
 // registerAsynqScheduleTasks 注册 Worker 入口需要的全部定时任务。
-func registerAsynqScheduleTasks(asynqScheduler *asynq.Scheduler) error {
+func registerAsynqScheduleTasks(asynqScheduler *asynq.Scheduler, auditArchiveEnabled bool) error {
 	if _, err := asynqScheduler.Register("@every 1m", asynq.NewTask(
 		constants.TaskTypeAgentRechargeRecovery,
 		nil,
@@ -773,6 +796,9 @@ func registerAsynqScheduleTasks(asynqScheduler *asynq.Scheduler) error {
 	); err != nil {
 		return fmt.Errorf("注册每日流量落盘定时任务失败: %w", err)
 	}
+	if !auditArchiveEnabled {
+		return nil
+	}
 	if _, err := asynqScheduler.Register("CRON_TZ=Asia/Shanghai 0 4 * * *", asynq.NewTask(
 		constants.TaskTypeAuditDailyArchive,
 		nil,
@@ -793,59 +819,46 @@ func registerAsynqScheduleTasks(asynqScheduler *asynq.Scheduler) error {
 	)); err != nil {
 		return fmt.Errorf("注册 Integration Log 每日冷归档定时任务失败: %w", err)
 	}
-	if _, err := asynqScheduler.Register("CRON_TZ=Asia/Shanghai 0 5 1 * *", asynq.NewTask(
-		constants.TaskTypeIntegrationMonthlyFinalize,
-		nil,
-		asynq.MaxRetry(10),
-		asynq.Timeout(6*time.Hour),
-		asynq.Unique(27*24*time.Hour),
-		asynq.Queue(constants.QueueForTaskType(constants.TaskTypeIntegrationMonthlyFinalize)),
-	)); err != nil {
-		return fmt.Errorf("注册 Integration Log 月度最终版本复核任务失败: %w", err)
-	}
-	if _, err := asynqScheduler.Register("CRON_TZ=Asia/Shanghai 0 6 1 * *", asynq.NewTask(
-		constants.TaskTypeAuditMonthlyRetention,
+	if _, err := asynqScheduler.Register("CRON_TZ=Asia/Shanghai 0 5 * * *", asynq.NewTask(
+		constants.TaskTypeAuditDailyRetention,
 		nil,
 		asynq.MaxRetry(10),
 		asynq.Timeout(12*time.Hour),
-		asynq.Unique(27*24*time.Hour),
-		asynq.Queue(constants.QueueForTaskType(constants.TaskTypeAuditMonthlyRetention)),
+		asynq.Unique(23*time.Hour),
+		asynq.Queue(constants.QueueForTaskType(constants.TaskTypeAuditDailyRetention)),
 	)); err != nil {
-		return fmt.Errorf("注册月度日志留存演练或清理任务失败: %w", err)
+		return fmt.Errorf("注册日志日留存演练或清理任务失败: %w", err)
 	}
 	return nil
 }
 
 // registerAuditArchiveTask 注册 Audit 与 Integration 冷归档任务处理器。
-func registerAuditArchiveTask(mux *asynq.ServeMux, runtime *workerRuntime, cleanupEnabled bool, appLogger *zap.Logger) {
+func registerAuditArchiveTask(mux *asynq.ServeMux, runtime *workerRuntime, cleanupEnabled, enabled bool, appLogger, retentionLogger *zap.Logger) {
 	if runtime.storageSvc == nil {
 		appLogger.Warn("对象存储未配置，审计归档任务将在执行时重试")
-		mux.HandleFunc(constants.TaskTypeAuditDailyArchive, task.NewAuditDailyArchiveHandler(nil, appLogger).Handle)
-		integrationHandler := task.NewIntegrationArchiveHandler(nil, appLogger)
+		mux.HandleFunc(constants.TaskTypeAuditDailyArchive, task.NewAuditDailyArchiveHandler(nil, appLogger, enabled).Handle)
+		integrationHandler := task.NewIntegrationArchiveHandler(nil, appLogger, enabled)
 		mux.HandleFunc(constants.TaskTypeIntegrationDailyArchive, integrationHandler.HandleDaily)
-		mux.HandleFunc(constants.TaskTypeIntegrationMonthlyFinalize, integrationHandler.HandleMonthlyFinalize)
-		mux.HandleFunc(constants.TaskTypeAuditMonthlyRetention, task.NewAuditMonthlyRetentionHandler(nil, appLogger, cleanupEnabled).Handle)
+		mux.HandleFunc(constants.TaskTypeAuditDailyRetention, task.NewAuditRetentionHandler(nil, retentionLogger, cleanupEnabled, enabled).Handle)
 		return
 	}
 	auditWriter, ok := runtime.workerResult.Services.PaymentAudit.(*auditInfra.Writer)
 	if !ok || auditWriter == nil {
-		appLogger.Fatal("初始化月度日志留存清理失败：统一审计 Writer 未配置")
+		appLogger.Fatal("初始化日志日留存清理失败：统一审计 Writer 未配置")
 	}
 	service, err := auditArchiveApp.NewService(runtime.db, runtime.storageSvc.Provider(), constants.AuditArchiveInstanceID, auditWriter)
 	if err != nil {
 		appLogger.Fatal("初始化统一审计归档服务失败", zap.Error(err))
 	}
-	mux.HandleFunc(constants.TaskTypeAuditDailyArchive, task.NewAuditDailyArchiveHandler(service, appLogger).Handle)
-	integrationHandler := task.NewIntegrationArchiveHandler(service, appLogger)
+	mux.HandleFunc(constants.TaskTypeAuditDailyArchive, task.NewAuditDailyArchiveHandler(service, appLogger, enabled).Handle)
+	integrationHandler := task.NewIntegrationArchiveHandler(service, appLogger, enabled)
 	mux.HandleFunc(constants.TaskTypeIntegrationDailyArchive, integrationHandler.HandleDaily)
-	mux.HandleFunc(constants.TaskTypeIntegrationMonthlyFinalize, integrationHandler.HandleMonthlyFinalize)
-	mux.HandleFunc(constants.TaskTypeAuditMonthlyRetention, task.NewAuditMonthlyRetentionHandler(service, appLogger, cleanupEnabled).Handle)
+	mux.HandleFunc(constants.TaskTypeAuditDailyRetention, task.NewAuditRetentionHandler(service, retentionLogger, cleanupEnabled, enabled).Handle)
 	appLogger.Info("注册审计归档任务处理器",
 		zap.String("audit_task_type", constants.TaskTypeAuditDailyArchive),
 		zap.String("integration_daily_task_type", constants.TaskTypeIntegrationDailyArchive),
-		zap.String("integration_monthly_task_type", constants.TaskTypeIntegrationMonthlyFinalize),
-		zap.String("retention_task_type", constants.TaskTypeAuditMonthlyRetention),
-		zap.Bool("retention_cleanup_enabled", cleanupEnabled))
+		zap.String("retention_task_type", constants.TaskTypeAuditDailyRetention),
+		zap.Bool("retention_cleanup_enabled", cleanupEnabled), zap.Bool("archive_tasks_enabled", enabled))
 }
 
 // createTaskHandler 创建并返回包含全部任务处理器的 Asynq Handler。

docker-compose.prod.yml

@@ -29,7 +29,7 @@
 
 services:
   api:
-    image: registry.boss160.cn/junhong/cmp-fiber-api:latest
+    image: registry.boss160.cn/junhong/cmp-fiber-api:${IMAGE_TAG:-latest}
     container_name: junhong-cmp-api
     restart: unless-stopped
     ports:
@@ -102,7 +102,7 @@ services:
         max-file: "3"
 
   worker:
-    image: registry.boss160.cn/junhong/cmp-fiber-worker:latest
+    image: registry.boss160.cn/junhong/cmp-fiber-worker:${IMAGE_TAG:-latest}
     container_name: junhong-cmp-worker
     restart: unless-stopped
     environment:

docs/deployment/production-runbook.md

@@ -8,7 +8,7 @@
 - Owner：生产维护者。
 - 最后核验：2026-08-13（基于维护者提供的信息，未连接生产环境）。
 - 更新触发：Unit、目录、进程数、Worker 角色、发布顺序、迁移方式或回滚方式变化。
-- 验证：由维护者在服务器执行本文列出的只读核对命令，并回填结果；Agent 不连接生产环境。
+- 验证：Agent 可通过 dbhub 对生产数据库执行只读诊断查询；服务器上的只读核对、生产发布、迁移、回滚及其他写操作由维护者执行并回填结果，Agent 不连接生产主机。
 
 ## 与测试环境的边界
 
@@ -52,7 +52,7 @@ GOOS=linux GOARCH=amd64 go build -ldflags="-w -s" -o ./build/worker ./cmd/worker
 - 二进制只从嵌入默认配置和 `JUNHONG_` 环境变量读取；`.env.prod` 必须由 systemd Unit 显式加载，或由 Unit 启动脚本 `source` 后启动。需要以 Unit 内容核实实际方式。
 - API 与 Worker 共享数据库、Redis、日志、JWT、对象存储、Gateway、短信、支付等基础配置；只记录键名，不将实际凭据写入仓库文档。
 - 七月新增的 API/Worker 共用配置：`JUNHONG_APPROVAL_LEGACY_REFUND_MANUAL_ENABLED`、`JUNHONG_APPROVAL_LEGACY_OFFLINE_RECHARGE_PAY_ENABLED`、`JUNHONG_WECOM_BASE_URL`、`JUNHONG_WECOM_TIMEOUT`。
-- 七月新增的 Worker 配置：`JUNHONG_WORKER_ROLE`、`JUNHONG_WORKER_INSTANCE_NAME`、`JUNHONG_WORKER_AUDIT_RETENTION_CLEANUP_ENABLED`。
+- 本次新增的 Worker 配置：`JUNHONG_WORKER_ROLE`、`JUNHONG_WORKER_INSTANCE_NAME`、`JUNHONG_WORKER_POLLING_TOTAL_MAX_CONCURRENCY`、`JUNHONG_WORKER_AUDIT_RETENTION_CLEANUP_ENABLED`、`JUNHONG_WORKER_AUDIT_ARCHIVE_TASKS_ENABLED`。轮询总并发必须保持在 1-1000，初始生产值建议 100；归档/留存总开关默认关闭。
 - 首发要求：退款人工入口、线下充值人工确认、企微审批、运营商实名回调、微信/支付宝在线充值均按维护者决定启用；审计物理清理保持关闭。
 - 企微应用凭据由后台配置写入数据库明文字段；这不是启动环境变量。本文不记录其值。
 
@@ -74,6 +74,35 @@ DB_PASSWORD='<密码>' DB_NAME=<库名> DB_SSLMODE=<模式> \
 
 迁移失败时不启动新二进制；按失败迁移的事务状态决定处理，必要时恢复已确认可用的数据库备份。启动失败时覆盖回部署前备份的二进制，再恢复数据库备份（如迁移已改变数据库）。
 
+### 商户池支付路由发布与回滚
+
+本节是维护者操作清单，不是已执行证据。迁移、生产发布、Redis 操作和富友真实渠道核验均由维护者执行；本轮未执行，不能以本地构建替代。
+
+**前置条件**
+
+1. 留存维护者指定测试环境或本地验证证据，且不得记录密钥或完整报文中的敏感凭证。富友仅沿用现有实现；未进行外部渠道实测不构成开发、测试部署、任务完成、归档或发布前置。
+2. 确认本次商户池 Schema 迁移已完成可恢复备份及校验；停止服务后确认迁移锁影响、无长事务和可接受维护窗口。
+3. 上传支持 `merchant_id`/`payment_config_id` 双读的 API 与 Worker 二进制。商户池新支付没有运行时开关。
+
+**发布后检查**
+
+1. 由维护者执行迁移并部署双读二进制。C 端套餐购买、C 端资产钱包充值、代理在线预存款充值的后续新支付立即经启用商户池创建并冻结 `merchant_id`、商户池与 `routing_epoch`。
+2. 无可用商户池、成员缺失或池停用必须稳定失败，不得回退旧综合支付配置或自动换商户；后台线下订单、后台钱包余额支付和员工线下代充值不经过商户池。
+3. 检查首次成功唯一累计，以及回调/查单/退款 A 对 `merchant_id` 新单和 `payment_config_id` 历史单的双读分流；应用、审计和集成日志不得包含凭证、私钥、Token、证书或完整敏感配置。
+
+**回滚与记录**
+
+1. 不存在关闭商户池新支付创建的运行时开关。故障只能在仍支持双读的二进制上前向修复，不得恢复旧综合支付配置创建。
+2. 只要存在 `merchant_id` 非空支付、成功累计事实或新商户池配置，禁止部署不识别新路由的旧二进制，也禁止执行破坏这些事实的 down 迁移。
+3. 维护者记录二进制版本、时间、目标 PostgreSQL/Redis 的脱敏标识、备份校验、验证结果与全部阻塞原因。
+
+### 零金额退款发布后核验
+
+发布本次退款审批变更后，维护者应先等待既有重试处理稳定事件 `approval:26:approved`；若重试已耗尽，按受控运维流程重放同一事件，不得直接修改退款、订单或钱包数据。随后核验：
+
+1. 退款单 `RF20260820170954264700` 已通过，关联订单支付状态为已退款。
+2. 该退款没有代理主钱包或资产钱包的零金额回款流水。
+
 ### 锁的含义与发布影响
 
 `000171` 会对 `tb_agent_wallet`、`000178` 会对 `tb_iot_card` 使用 PostgreSQL `ACCESS EXCLUSIVE` 锁。该锁执行期间会阻塞该表的读写及其他 DDL，直到迁移事务提交或回滚；若有未结束业务查询/事务，它也会等待。因此必须在 API 和全部 Worker 停止后执行，并在迁移前检查没有长事务。锁持续时间取决于表数据量、索引创建和等待中的旧事务；不能从仓库估算具体秒数。
@@ -88,3 +117,12 @@ DB_PASSWORD='<密码>' DB_NAME=<库名> DB_SSLMODE=<模式> \
 ## 已确认数据库备份
 
 每日凌晨 02:00 自动备份 `junhong_cmp_prod`：数据库运行在 Docker 容器 `postgres` 中，备份脚本执行 `pg_dump -Fc -Z 6`，写入 `/data/backups/postgresql/<库名>_<时间>.dump`，同时生成 MD5 文件并以 `pg_restore --list` 校验结构；保留 30 天。发布前仍须人工新建一次备份并确认校验通过，不能只依赖凌晨的最近备份。恢复命令待维护者实际演练或确认后补充。
+
+## 日审计日志留存启用与恢复
+
+归档与日留存由调度 Worker 受控处理 Asia/Shanghai 的已结束自然日；`JUNHONG_WORKER_AUDIT_ARCHIVE_TASKS_ENABLED=false` 时不注册调度，已入队任务也安全跳过、不扫描在线日志表。开启后每次最多推进一个日期。`JUNHONG_WORKER_AUDIT_RETENTION_CLEANUP_ENABLED=false` 时仅验证归档、对象、manifest、数据库数量和日期连续性，不写清理断点、不删除在线数据。Integration 的 `pending` 记录保留在线，但不会阻断同日终态日志、Audit 数据或后续日期的清理；若 pending 后续终结，Worker 会重建该日 revision 后续跑删除。
+
+1. 发布新 Worker 后保持 `JUNHONG_WORKER_AUDIT_ARCHIVE_TASKS_ENABLED=false` 和物理清理开关关闭；轮询总并发先设为 100。维护者先核对 `tb_log_archive_run` 中 Audit 与 Integration 两个来源从历史最早在线日期起没有缺失账本；缺失日期必须先受控补归档，不能跳过失败日。
+2. 以关闭开关的 Worker 完成只读演练，观察 `/opt/junhong_cmp/worker/logs/audit-retention.log`：每个日期应有来源计数和耗时；若出现日期、来源、失败分类或安全错误摘要，先修复该来源的归档或校验问题后再演练。仅有 pending 不需要人工终结才可继续。
+3. 低峰期先将调度 Worker 的 `JUNHONG_WORKER_AUDIT_ARCHIVE_TASKS_ENABLED=true`，重启该 Worker；确认单日归档稳定后，再将 `JUNHONG_WORKER_AUDIT_RETENTION_CLEANUP_ENABLED=true`，并持续观察上述独立日志、`tb_log_archive_run.cleanup_started_at` / `cleaned_at` 断点及表大小。DELETE 释放的 PostgreSQL 页面会供后续写入复用，表文件不会立即缩小；维护者按既有运维窗口评估 VACUUM，Worker 不执行 VACUUM 或表重写。
+4. 异常时立即将开关改回 `false` 并重启调度 Worker。已清理日期按已验证的对象和 manifest 执行归档恢复；尚未清理或阻断的日期仍保留在线，无需数据库恢复。恢复后先重新执行只读演练，再决定是否重新开启清理。

docs/engineering/工程约束.md

@@ -300,3 +300,16 @@
 - **Owner**：基础设施负责人
 - **最后验证日期**：2026-08-07
 - **更新触发条件**：新增配置或依赖升级
+
+## ENG-TEST-001
+- **状态**：生效
+- **适用范围**：Agent 执行的迁移、Redis、API/Worker、部署与集成 Smoke 验证。
+- **规则**：维护者指定的测试 PostgreSQL `junhong_cmp_test`、Redis DB 6、`Iteration/8-11` 测试部署和 `cmp-test` 日志主机构成唯一测试验证面；MUST 使用该环境，不额外要求独立数据库、Redis DB 或 namespace。迁移从本地工作区以明确 `DB_*` 参数执行；测试 fixture 仅可创建、删除当前 Change 自己的记录，MUST NOT 重置整个测试库。测试部署通过 Gitea 工作流完成，SSH 仅用于日志、容器状态与受控 Smoke。
+- **理由**：同一可控测试面避免每个 Change 重复索取环境，且保留可复现的迁移、缓存、并发和部署证据。
+- **最小正例**：当前 Change 在 `junhong_cmp_test` 执行迁移 up/down/up，清理自己的 fixture，并在测试部署后读取 `cmp-test` 日志。
+- **最小反例**：以未提供额外“隔离环境”为由暂停，或重置整个测试数据库。
+- **机械检查/人工原因**：记录显式目标、迁移命令、fixture 清理范围、Redis 操作与测试部署 SHA；通过 API/Worker 日志和可观察状态核对。
+- **例外条件**：真实支付渠道和外部审批系统不作自动验证；第三方协议变更以契约文档和维护者提供的证据为准。生产仍按生产运行说明由维护者执行。
+- **Owner**：基础设施负责人
+- **最后验证日期**：2026-09-08
+- **更新触发条件**：测试库、Redis DB、部署分支、测试主机或验证授权变化

docs/hotfix-main-package-activation-recovery/功能总结.md

@@ -0,0 +1,44 @@
+# Main 分支套餐接续饥饿热修
+
+## 修复边界
+
+本热修仅适用于 `main` 的纯 Asynq 套餐接续链路，不引入 Outbox、数据库迁移、新任务类型或新依赖。
+
+- 孤儿扫描先在 PostgreSQL 中按卡或设备选择队首套餐，并排除仍有 `status IN (1,2)` 占位主套餐的载体，最后取 100 个真实孤儿。
+- 旧主套餐及加油包状态事务提交后，再投递现有 `package:queue:activation` 任务。
+- Redis 激活锁冲突返回套餐激活冲突错误，由现有 `MaxRetry(3)` 重试。
+- 只有套餐实际从待生效推进为生效中时，Handler 才记录“套餐激活成功”。
+
+## 部署观察
+
+部署 Worker 后至少观察两个套餐轮询周期：
+
+1. `孤儿套餐扫描完成` 的 `orphan_count` 应能覆盖真实无占位套餐，不再固定被同一批占位载体挡住。
+2. `已提交套餐激活任务` 后应出现实际激活、明确跳过或可重试错误，不再出现未改状态却打印成功。
+3. Redis 锁冲突应进入 Asynq 重试，不应确认任务成功。
+
+可使用以下只读 SQL 检查仍未恢复的真实孤儿数量：
+
+```sql
+SELECT COUNT(*) AS orphan_pending_count
+FROM tb_package_usage AS pending
+WHERE pending.status = 0
+  AND pending.master_usage_id IS NULL
+  AND pending.deleted_at IS NULL
+  AND (COALESCE(pending.iot_card_id, 0) > 0 OR COALESCE(pending.device_id, 0) > 0)
+  AND NOT EXISTS (
+    SELECT 1
+    FROM tb_package_usage AS occupied
+    WHERE occupied.status IN (1, 2)
+      AND occupied.master_usage_id IS NULL
+      AND occupied.deleted_at IS NULL
+      AND (
+        (COALESCE(pending.iot_card_id, 0) > 0 AND occupied.iot_card_id = pending.iot_card_id)
+        OR (COALESCE(pending.iot_card_id, 0) = 0 AND pending.device_id > 0 AND occupied.device_id = pending.device_id)
+      )
+  );
+```
+
+## 回滚
+
+本次无数据库迁移。回滚热修提交并重新部署 Worker 即可；已经正确激活的套餐属于有效业务事实，不执行反向 SQL。

docs/integrations/fuiou/README.md

@@ -9,7 +9,9 @@
 
 ## 当前实际使用范围
 
-系统仅使用微信预下单 `POST <ApiURL>/wxPreCreate` 与支付通知。交易类型为 `JSAPI`（公众号）或 `LETPAY`（小程序）；未发现退款、撤销或查单能力。
+系统当前使用微信预下单 `POST <ApiURL>/wxPreCreate` 与支付通知；代理在线充值恢复流程另有本地 `CommonQuery` 调用，用于主动查询支付订单状态。交易类型为 `JSAPI`（公众号）或 `LETPAY`（小程序）；本地 `CommonQuery` 代码保持现有请求格式、签名算法、状态映射和恢复语义不变。该源码事实仅表示本地候选实现及后续双读配置来源改造接缝，不证明真实富友渠道契约，也不证明验签、状态解释或恢复核验已通过。
+
+真实核验仍需隔离富友商户、明确接口权限、合法订单样本和允许的网络条件；在这些条件完成前，不得将查单、验签、状态映射或恢复结果作为上线证据。本 Change 不新增富友退款能力。
 
 ## 配置、认证与传输
 

docs/integrations/gateway/README.md

@@ -4,13 +4,27 @@
 
 - Owner：IoT Gateway 适配维护人
 - 实现：`internal/gateway/`
-- 核验日期：2026-08-07
-- 证据：`internal/gateway/client.go`、`crypto.go`、`card_status.go`、`flow_card.go`、`device.go`
+- 核验日期：2026-09-11
+- 证据：`internal/gateway/client.go`、`crypto.go`、`card_status.go`、`flow_card.go`、`device.go`、`payment_voucher.go`
 
 ## 当前实际使用范围
 
 Gateway 是运营商流量卡、实名、停复机、限速和设备信息的统一封装入口。具体路径、请求字段和响应字段以同目录详细协议与 `internal/gateway/*.go` 的实际调用交集为准；文档中出现但代码未调用的接口不视为系统能力。
 
+付款凭证识别（`POST /ai/ocr/extract-payment`，入参 `image_base64`）由 `internal/gateway/payment_voucher.go` 封装，当前唯一调用方是代理线下预存款申请的「交易流水号表单预填」。该能力只消费响应中的 `order_number`（作为交易流水号预填值）；`amount`、`remark`、`payment_method`、`payee`、`payment_time` 不进入本系统响应、不预填、不落库，识别结果不是资金事实。核验证据：`internal/gateway/payment_voucher.go` 的类型定义只对外暴露支付单号，`internal/application/agentrecharge/payment_voucher_ocr.go` 只返回该字段，接口响应 DTO 仅含 `external_transaction_no`。
+
+付款凭证识别刻意不走 `doRequest` / `doRequestWithResponse`：前者在 Info 级别打印加密前完整请求体、后者在 Info 级别打印完整原始响应，会把凭证图片内容与识别原始结果写进日志。该能力改用 `Client.doRequestWithoutPayloadLog`，仅记录路径、耗时与结果字节数摘要；既有能力的请求与日志语义保持不变（`internal/gateway/client.go` 中 `executeWithRetry` 的 `logPayload` 分支）。
+
+### 付款凭证识别的已知限制
+
+- **长号码可能不完整**：对位数较多的转账单号，该接口可能只返回前若干位，实测存在识别值与凭证图片所示号码不一致的情况（位数少于凭证所示）。连续多次识别同一凭证所得长度与内容稳定，属上游侧确定性截断，而非本系统侧裁剪；预填值**必须**由提交人对照凭证人工核对，系统以人工确认值为准。
+- **单号缺失即失败**：响应未给出单号时，本系统按识别失败返回明确失败（`CodeGatewayInvalidResp`，中文提示），不返回空值。
+- **字段类型会漂移**：响应 `data` 中 `amount` 为 JSON 数值而非字符串。本系统只解码 `order_number`，不声明其余字段，故不受类型漂移影响；新增消费字段前必须重新核对上游类型。
+- **解析失败不回显原文**：响应解码失败时只返回固定中文提示，不携带底层解析错误，避免第三方库的错误消息把识别原始结果带进日志与错误上下文。
+- **单次识别只接受单个附件键**，图片由后端读取对象存储后编码，Gateway 凭证不下发前端；识别结果不落库、不构成资金事实。
+
+本条限制的核验方式（可复现、不依赖样本取值）：对同一图片凭证**连续三次**调用该识别接口，比较三次返回值的**位数与内容是否一致**——一致说明是上游确定性行为而非随机抖动；再将该位数与凭证图片所示号码的位数（用等长掩码计数，只比位数）对照，得出是否缺位。判定责任方时看本系统的解码路径 `internal/gateway/payment_voucher.go`：它只对返回值做 `strings.TrimSpace`，无截断、无按长度裁剪、无正则截取，因此位数差异只能来自上游。识别结果不落库，复核该接口的返回值需重新发起识别调用，不能从业务表反查。
+
 ## 配置、认证与报文
 
 配置键为 `gateway.base_url`、`gateway.app_id`、`gateway.app_secret`、`gateway.timeout`。业务参数先包装为 `{"params": ...}`，使用 AppSecret 做 AES-128-ECB 加密；外层请求含 `appId`、`data`、`sign`、`timestamp`，签名使用 MD5。HTTP 方法统一为 POST，内容类型为 `application/json;charset=utf-8`。HTTP 200 且 Gateway `code=200` 才算成功，`data` 再按具体能力解码。

docs/product/2026-08-迭代-PRD-讨论稿.md

@@ -0,0 +1,224 @@
+# 新卡管 2026 年 8 月迭代 PRD（讨论稿）
+
+> 状态：讨论中
+>
+> 本文是本轮需求澄清的唯一决策记录。确认后的需求将重编稳定需求 ID；每项实施前再以独立 OpenSpec Change 固化可观察行为、任务和验收。
+>
+> 来源：业务提供的《新卡管 8 月迭代需求》，2026-08-11。
+
+## 0. 已确认的产品边界
+
+1. 本文覆盖一个需求池，不承诺整体一次上线。完成完整 PRD 后，按影响范围由小到大拆分为独立 Change 实施。
+2. 原文编号存在重复和漂移。讨论稿将建立新的稳定需求 ID；原编号仅用于追溯来源。
+3. 审批类业务必须接入企业微信。企业微信是唯一终审来源；审批节点、审批人、条件和流转规则完全由企业微信模板配置，本系统不读取、校验或固化这些规则。系统只保存本地审批实例、业务状态、审计和幂等闭环，并按企业微信最终通过或驳回结果推进业务；不提供本地人工通过或拒绝来绕过企业微信。企业微信回调延迟、提交失败或结果未知时，使用既有兜底轮询查询渠道状态并同步本地实例。所有审批业务均须将企业微信审批单号返回至卡管并在详情展示；详情仅展示本地或企业微信实际可取得的字段，不展示无法返回、无值或无可靠来源的字段。
+4. OCR 是已有的外部能力，但本期仅作为交易流水号的预填来源。申请人或审核人必须能更正并最终确认；OCR 识别结果不是资金事实。OCR 协议、字段能力、失败和重试规则等待外部契约文档。
+
+## 0.1 稳定需求 ID 与原文映射
+
+| 稳定 ID | 能力 | 原文来源 |
+| --- | --- | --- |
+| AUG26-001 | 员工代收款账单与核销 | PRD-08-001、PRD-08-013（核销字段） |
+| AUG26-002 | 支付商户池与微信授权配置 | PRD-08-002 |
+| AUG26-003 | 店铺业务员与业务用户组 | PRD-08-004、PRD-08-005 |
+| AUG26-004 | 套餐真流量预警 | PRD-08-006 |
+| AUG26-005 | 换货业务数据迁移展示 | PRD-08-007 |
+| AUG26-006 | 套餐退款与原路退款 | PRD-08-008、PRD-08-013（退款字段） |
+| AUG26-007 | H5 风险换卡与运营通知 | PRD-08-009 |
+| AUG26-008 | 代理分销码、资料资格与佣金提现 | PRD-08-010、PRD-08-013（提现/分销审批字段） |
+| AUG26-009 | 手机号—资产关联 | PRD-08-011 |
+| AUG26-010 | 自动续费 | PRD-08-012 |
+| AUG26-011 | 运营商通道流量阈值 | PRD-08-017 |
+| AUG26-012 | 佣金回溯明细 | PRD-08-015 |
+| AUG26-013 | 资产套餐层级展示 | PRD-08-016（资产详情） |
+| AUG26-014 | 导出与统一时间筛选 | PRD-08-014、PRD-08-020 |
+| AUG26-015 | 报表管理 | PRD-08-016（报表，原编号重复） |
+| AUG26-016 | 优先轮询通道 | PRD-08-019 |
+| AUG26-017 | 代理自充收款方式 | PRD-08-021、PRD-08-013（预存款审批字段） |
+
+## 1. 已确认的领域语言
+
+### 1.1 员工代收款账单
+
+员工代客户购买套餐、充值等业务时，系统按来源业务生成的待核销记录。它表示员工经办业务形成的暂挂欠款；员工提交客户付款凭证，企业微信审批人员可通过该凭证在外部第三方收款记录中核验支付，且企业微信审批通过后，欠款相应减少或结清。客户款项可支付至公司微信、银行卡或其他由业务维护并认可的线下收款方式，不要求必须支付给员工或由员工另行回款。
+
+代理线下预存款/主钱包充值仍按既有企业微信审批决定是否入账；该审批通过并完成入账后，系统再创建相应员工代收款账单，使员工欠款增加。后续账单核销是独立于充值审批的业务流程。
+
+员工代收款账单的欠款人固定为实际发起线下套餐订单或线下代理充值的后台账号，创建后不可修改；平台业务员和超级管理员实际经办时均生成本人账单。员工离职或账号禁用后，其欠款人身份不变；仅超级管理员可代办创建、修改或重新提交核销申请，且必须记录实际代办人及代办原因。
+
+已确认：支持一笔外部支付记录分摊核销多张账单，也支持一张账单由多笔支付记录分次核销。员工应按一笔外部付款创建一张核销申请，在申请中上传该笔付款的凭证、填写交易流水号，并选择多张账单及各自分摊金额；一张申请只产生一个企业微信审批实例。每笔分摊必须独立保留账单、外部支付记录标识、本次核销金额、凭证、审批实例和剩余未核销金额。
+
+员工代收款账单的核销状态独立于核销申请审批状态：账单状态为待核销、部分核销、已核销或已关闭；申请状态为审批中、已通过、已驳回、已撤销/已关闭。只有企业微信审批通过的分摊才减少员工欠款。账单列表需同时展示账单核销状态和是否存在审批中申请，避免部分核销与审批中互相覆盖。
+
+企业微信最终驳回的核销申请允许员工在原申请上修改后重新提交；系统为同一申请保留每一次企业微信审批实例及其当次业务快照，历史材料和审批结果不得被覆盖。已驳回申请可修改全部申请内容：收款账户、外部付款信息、附件、备注、勾选账单和分摊金额；已通过的分摊不可修改。
+
+超级管理员可关闭待核销、已驳回或部分核销账单，关闭即作废当时未核销余额且不再计入员工欠款；已核销金额保留。关闭必须填写原因、保留操作审计，且存在审批中核销申请时不得关闭。
+
+已确认：员工代收款账单按业务场景确定公司应收金额。
+
+- 代理代购套餐：取订单 `actual_paid_amount`（代理实际结算/成本金额）。对会生成员工代收款账单的后台线下套餐订单，创建订单时不再强制上传付款凭证；订单仍按当前规则立即激活，并同时创建待核销账单。付款凭证、OCR 与外部交易流水号只在后续核销申请提交。赠送套餐等不产生员工账单的线下订单继续保持创建时上传凭证的当前规则。
+- 无代理归属的自营 C 端套餐购买：取订单 `actual_paid_amount`。当前实现该值等于 `total_amount`；未来优惠券等价格优惠也应使其表示实际收款金额。
+- 代理线下充值预存款/主钱包：既有充值审批通过并入账后创建员工代收款账单，金额取 `tb_agent_recharge_record.amount`。
+- 不支持平台代理 C 端客户充值资产钱包；原需求中对此类场景不纳入本期。
+- “其他”来源第一版不支持手工创建，必须先定义可追溯来源单和金额口径。
+
+> 待决：`actual_paid_amount` 在未来优惠场景的写入时机与权威性；外部支付记录在本地的最小留存字段、收款账户目录的范围和退款时的冲销规则。
+
+## 2. 当前发现的需求结构问题
+
+| 问题 | 处理原则 |
+| --- | --- |
+| `PRD-08-013`、`014`、`015`、`016` 在范围表与正文含义不一致 | 后续以新稳定 ID 重编，保留来源编号。 |
+| 审批字段在第 17 节集中出现，但相关主需求中存在不同口径 | 先定义每个审批业务的业务单、状态、资金生效时点和企业微信模板，再定义页面字段。 |
+| OCR 被写入字段说明但缺少外部契约 | OCR 仅预填，待提供契约后再定义使用范围。 |
+| 收款方式被写为固定示例（如某人微信/支付宝） | 收款方式由业务字典维护，不得将名称硬编码为支付方式枚举；是否还需独立收款账户目录待确认。 |
+| 多处要求“字典维护”，但当前系统没有业务字典 | 新建通用业务字典模块；字典分类由研发固定注册，业务只维护分类下的字典项。已被业务单引用的字典项不得物理删除，只能停用并保留历史名称快照。 |
+| 自动续费含“有余额自动续费，不停机” | 必须先区分续费订单、钱包扣款、运营商停复机和轮询同步，不能将它们描述为同一动作。 |
+| 运营商通道阈值、套餐流量预警都使用“阈值” | 前者是通道控制规则，后者是套餐预警规则；二者的流量口径、周期和触发后果必须独立定义。 |
+
+## 2.1 已确认的外部付款分摊边界
+
+1. 同一笔外部付款可覆盖多张员工代收款账单，也可由多个员工的多张核销申请引用。
+2. 本期不对同一外部付款在多张申请中的累计分摊金额做系统防重或金额上限校验；企业微信审批人员以外部第三方记录为准核验。
+3. 系统仍须逐核销申请保存所选线下收款方式、交易流水号、付款金额、付款方、付款时间、支付凭证、其他凭证、备注及分摊明细，供超级管理员和企业微信审批追溯。交易流水号和付款金额可由 OCR 预填，但必须允许人工确认或更正。
+4. 员工通过勾选账单创建分摊明细，不手填账单编号、订单、客户或资产字段；系统自动带出这些只读信息。系统按账单产生时间由早至晚，使用本次外部付款金额自动填充分摊，最后一张填剩余金额；员工可以修改本次核销金额。对同一账单的审批中分摊应预占可核销余额，避免并发申请超额核销。
+5. 本期只做一套固定分类的线下收款方式字典。超级管理员维护字典项名称、稳定编码、排序、启停、备注；核销申请和预存款审批选择字典项并冻结名称快照。不额外建设收款账户目录。
+
+## 2.2 已确认的历史数据边界
+
+1. 员工代收款账单仅对功能上线后新创建的符合条件线下套餐订单、功能上线后审批通过并入账的线下代理预存款/主钱包充值自动生成。
+2. 不回填、不补建任何上线前历史业务；上线前业务不纳入员工账单和欠款统计。
+
+## 2.6 已确认的商户池覆盖范围
+
+1. C 端套餐购买、C 端资产钱包充值、代理在线预存款充值三类当前线上收款入口，均应按支付方式通过商户池选择实际收款商户；后台钱包/线下套餐订单不经过商户池。
+2. 平台范围内每种支付方式最多一个启用商户池；可保留停用历史池，但不得同时启用多个相同支付方式的商户池。未来需要多池时，必须先定义订单/店铺/资产等路由维度。
+3. 新建独立商户管理模块，收款凭证与商户支付能力从现有综合支付配置中分离，由商户池选择商户；不复用现有支付配置记录作为商户。一个商户仅对应一种支付方式：微信商户和支付宝商户分别建档、分别加入对应商户池。
+4. 新建独立微信授权配置，平台范围内最多一个启用配置，保存 C 端公众号 H5 登录/JSSDK 和小程序登录所需参数；C 端微信登录、AppID、JSSDK 与 OpenID 只使用该全局配置。微信商户仅保存微信支付或富友收款凭证；商户池命中的微信商户统一使用全局授权配置的 AppID 发起支付，微信侧 AppID 与商户的绑定/授权由业务保证。微信直连商户和富友商户都属于微信支付商户，可混合加入唯一启用的微信商户池；系统按命中商户自身服务商凭证执行支付、回调验签和退款。
+5. 商户停用后仅对新支付单自动跳过；已命中该商户的历史支付单不换商户，支付回调、状态查询及后续原路退款仍使用该商户凭证。被历史支付单引用的商户不得物理删除，只能停用。商户原路退款能力不提供人工开关，系统仅按服务商类型及退款所需凭证是否完整判定；服务商实现不支持退款的商户固定视为不支持。商户池没有可用商户或商户池停用时，创建支付单失败且不得回退到旧全局支付配置。
+6. 上线时从当前生效综合支付配置一次性自动迁移：创建一条全局微信授权配置、具备完整凭证的微信/支付宝商户及各自包含一个商户的启用商户池。新订单仅走商户池；旧综合支付配置和历史订单引用保留，仅服务历史回调、查询和退款，不自动改写。缺少完整凭证的支付方式不创建商户池，新支付单按暂无可用商户失败。迁移仅在数据库内复制密钥/证书，不得在日志、审计详情或接口响应暴露敏感值。
+7. 商户保存名称、支付方式、服务商类型、商户号/应用标识、敏感凭证、状态和备注。每笔新支付单保存实际商户 ID 并冻结名称、支付方式、服务商类型及商户号/应用标识快照，不复制敏感凭证。被支付单引用后，支付方式、服务商类型和商户号/应用标识不得修改；名称、备注、状态及凭证可更新。历史支付单和退款单优先展示快照，回调和退款读取商户当前有效凭证。
+8. 超级管理员和平台用户均可创建、修改、启用、停用商户、商户池和微信授权配置；其他角色没有管理入口。为使配置人员可核对完整配置，管理 API 的列表和详情向上述已认证角色返回商户及微信授权配置的完整密钥、证书和私钥字段，不做脱敏；不得将这些字段写入日志、审计快照、错误信息或普通业务单据。未被任何支付单命中的商户，超级管理员或平台用户可先将其移出商户池后经二次确认删除；删除审计不得含敏感凭证。被支付单引用的商户一律不得删除。
+9. 每笔通过商户池创建的支付单，除实际商户 ID 和商户身份快照外，还须保存商户池 ID、商户池名称快照和轮询方式快照；不另建逐次支付路由日志表。
+10. 金额阈值、笔数阈值和时间周期均为商户池统一配置，池内所有商户共用，不支持成员单独配置。
+6. 金额/笔数轮询创建池时必须配置统计周期，支持每轮累计、自然日累计、自然月累计。每轮累计在商户重新被轮到时清零；自然日/自然月累计在周期边界重置，达到阈值的商户在当期自动跳过。当前周期所有商户都达到阈值时，创建支付单失败并提示当前周期暂无可用商户。
+7. 时间轮询创建池时必须配置周期数值、分钟/小时/天单位和起始时间。自起始时间起按固定周期、商户列表顺序轮换；进入新时段时仅在有新支付单时选择并记录商户。当前商户停用时即时跳到下一个可用商户，时间段不重置；修改时间周期、起始时间或商户顺序后，保存成功时间成为新起点并从列表第一项重新计算。时间周期最小为 1 分钟。
+8. 金额/笔数轮询仅修改阈值时保留当前统计周期内的成功收款累计并立即按新阈值判断；修改统计周期或在金额/笔数两种方式间切换时，保存成功即开始新统计周期、所有商户从零累计。新增商户从零开始；移除/停用商户不再参与新订单选择。调整商户排序时，自然日/自然月累计保留未移除商户的当期累计；每轮累计从新列表第一项开启新一轮、所有商户从零累计。
+9. 商户预下单失败时不自动切换商户或重试；任一失败按当前错误处理返回，客户再次发起支付时重新按商户池选择。失败订单不计入金额/笔数成功累计。
+10. 金额/笔数轮询严格仅统计支付成功结果，不在预下单时预占商户额度或笔数；并发预下单可同时命中当前商户，已创建支付单不因后续轮询切换而改挂商户。
+11. 支付成功后发生的全额或部分退款不回冲商户池金额/笔数成功累计；退款是独立后续资金动作。
+
+## 2.3 已确认的退款完成规则
+
+1. 客户提供收款信息的退款以企业微信最终通过为退款完成时点；系统不感知、也不以外部线下实际打款、交易流水号或付款凭证作为退款状态条件。企业微信审批通过即标记已退款。
+2. 原路退款经企业微信最终通过后，系统必须以原实际收款商户自动调用渠道退款接口，超级管理员不得改选其他商户。只有渠道明确退款成功后退款单才标记已退款并保存渠道退款流水号；调用失败、超时或结果未知时，退款单保持原路退款处理中/失败，保留可恢复事实且不得重复退款。需改为凭证退款时，必须重新提交申请并重新走企业微信审批。
+3. 原路退款在选择方式、提交申请和实际执行前均重新校验原支付单、原实际收款商户、原渠道交易流水号、商户退款能力/凭证以及可退金额。商户停用不阻断历史订单原路退款。渠道实际调用是退款资格的最终判断；渠道明确拒绝、超期、凭证失效或余额不足时不标记成功、保留失败原因。系统不额外提供退款凭证预探测接口。
+4. 一笔订单最多只允许一张最终退款成功的退款申请；该申请可部分退款，成功后订单剩余未退款金额不再允许申请退款。
+5. 退款申请提交金额即企业微信审批授权金额和最终允许退款金额。原路退款按此金额调用渠道；凭证退款实际转出此金额后才可成功。金额需变更时不得继续执行原申请，必须重新提交并重新走企业微信审批。
+6. 一笔订单同一时间最多一张审批中、原路退款处理中或原路退款失败的退款申请。企业微信驳回、申请撤销/关闭或原路退款明确失败后，允许修改未成功退款申请并重提；可修改金额、原因、退款方式、客户收款信息和附件。每次重提必须新建企业微信审批实例及业务快照，历史材料不可覆盖。任一退款方式最终成功后，申请和订单均不得再发起退款。
+7. 企业微信最终通过即按当前规则使退款关联套餐失效、接续下一套餐并在必要时停机；原路退款渠道或线下实际打款的后续结果不影响套餐失效，也不恢复权益。
+8. 凭证退款申请必须提供客户收款账户信息和客户提供的收款凭证，作为企业微信审批材料；不要求、也不提供公司实际线下付款后的交易流水号或付款凭证回填。
+9. 超级管理员、平台用户和代理均可在各自数据权限内对已支付套餐订单发起退款申请；企业微信是唯一终审来源，本地不提供人工通过、拒绝或退回操作。任一具有该订单数据权限的上述账号，均可修改并重新提交未成功退款申请。
+10. 凭证退款的客户收款账户信息使用一个必填自由文本字段留存，客户提供的收款凭证附件必填；不新增退款收款账户类型字典、账户表，且不得复用公司线下收款方式字典。
+11. 退款申请的实收金额必须由系统从来源订单/原支付记录自动带出并冻结，提交人不可填写或修改。线上支付取原成功支付记录金额；资产钱包、代理预存款和后台线下订单取来源订单的实际收款或实际扣款金额。退款金额不得超过冻结实收金额；无法确定权威实收金额时拒绝创建申请。
+12. 本期不按套餐已用流量自动计算退款金额；提交人填写申请金额，系统仅校验不超过冻结实收金额，套餐使用情况作为退款原因、凭证和企业微信审批判断材料。
+13. 企业微信在本地收到通过前发生驳回、撤销或删除时，退款申请进入审批未通过/已关闭，未发生退款且可修改重提。企业微信通过后撤销时，不回滚已失效套餐、已发起原路退款或已完成凭证退款；申请标记审批异常、保留审计、禁止自动重提，由超级管理员线下处理。企业微信提交失败或结果未知时，退款申请仍为在途，不允许另建或重提，使用既有查询/重试闭环确认渠道是否受理。
+14. 对线上支付订单，系统在申请退款时预检可本地确定的原路退款条件：条件满足时同时提供原路退款和凭证退款；条件不满足时禁用原路退款并说明原因，只允许凭证退款。后端在提交及企微通过后的实际执行前均重复校验；后续条件失效时不得强行原路退款。钱包、预存款和后台线下订单不展示不适用的退款方式。
+15. 所有退款申请必须填写退款原因；退款原因冻结在当次企业微信审批快照中。
+16. 当前业务实际上限制一张订单仅购买一个套餐；虽数据模型预留多套餐订单能力，但本期退款申请不提供套餐选择，系统自动带出订单唯一关联套餐及其使用情况。企业微信通过后失效该套餐；若为主套餐，仍按现有规则连带失效其加油包。退款上限只按订单冻结实收金额校验。
+
+## 2.3.1 退款管理补充字段
+
+退款管理列表、详情及导出新增“当前退款套餐已用量”和“当前退款套餐总量”。当前退款套餐为退款订单自动关联的唯一套餐；两个字段读取该套餐使用记录当前可取得的真流量已用量和套餐总量，仅用于展示、查询和导出，不改变既定的退款金额校验、套餐失效或佣金回溯规则。
+
+## 2.4 已确认的退款方式矩阵
+
+| 来源订单的实际支付方式 | 本期允许退款方式 |
+| --- | --- |
+| 微信/支付宝等线上支付套餐订单 | 原路退款、客户提供收款信息退款 |
+| C 端资产钱包余额支付套餐订单 | 仅自动退回原资产钱包 |
+| 代理预存款/主钱包支付套餐订单 | 仅自动退回原代理预存款钱包 |
+| 后台线下套餐订单 / 员工代收款套餐订单 | 仅客户提供收款信息退款 |
+| 代理充值预存款业务单本身 | 当前退款模块不覆盖，需另立需求 |
+
+## 2.5 已确认的退款联动
+
+1. 来源订单全额退款且账单从未核销时，系统自动关闭账单，关闭原因记为来源订单全额退款。
+2. 来源订单部分退款且账单从未核销时，系统按退款金额冲减账单应收金额，并保留来源订单退款冲销记录。
+3. 账单存在任一已通过核销分摊时，系统不得自动冲销该账单；后续由超级管理员人工处理。
+4. 已核销账单的来源订单后续退款不恢复员工欠款；账单详情仅提示来源订单已退款并保留退款关联。正常订单退款不等于员工欠款重新产生。
+
+## 2.8 已确认的手机号绑定基线
+
+当前系统已有个人客户手机号绑定和全局 H5 强制绑定开关；是否强制绑定由全局配置决定，不存在、也不新增按资产导入批次设置“是否需要绑定手机号”的能力。原 PRD 第 15.4 节与当前行为冲突，不能作为本期新增功能依据。本期保留既有全局强制绑定逻辑，并新增已验证手机号与资产的关联记录：同一手机号最多关联 10 个当前有效资产，资产详情展示关联手机号，后台支持按资产解绑、批量解绑及操作记录。全局强制绑定开启时，客户首次登录一项尚未关联该手机号的资产，必须再次完成短信验证码校验后才建立关联；已关联该手机号的资产不再重复验证。全局强制绑定关闭时，H5 登录不要求短信验证码且不新增手机号—资产关联，已有关系保留并可后台查看、解绑。客户更换手机号并完成旧、新手机号验证码校验后，系统原子迁移旧手机号全部有效资产关联至新手机号；新手机号现有关联数加待迁移数超过 10 时整次换绑失败，原关系不变。资产详情列出全部当前关联手机号，单个解绑须明确选择一条资产手机号关系；批量解绑和 Excel 按资产标识导入解绑时，解除每项资产全部当前有效手机号关联，必须二次确认、填写原因并逐条记录实际解除关系。批量解绑逐资产独立执行：有权限且已绑定的资产成功解绑，其余资产失败；任务返回成功数、失败数和逐行失败明细，无权限项使用统一失败文案。具备资产数据权限的后台账号在资产详情、列表、导出和批量任务结果中均展示完整关联手机号，不做脱敏；操作日志不得记录完整手机号。仅超级管理员和平台用户可在资产数据权限范围内执行单个解绑、批量解绑和 Excel 导入解绑；代理、企业和个人客户没有后台解绑能力。手机号—资产关联只能由 H5 短信验证建立，后台不提供补录，后台仅查看和解绑。上线时不回填既有个人客户手机号与资产关系；功能上线后，既有客户首次登录每项资产仍须重新短信验证建立关联，超过 10 项时阻断本次新关联。换货不迁移手机号—资产关联，新资产首次访问时按全局开关重新验证。
+
+## 2.7 已确认的业务用户组
+
+1. 业务用户组用于标记平台用户所属业务，既不是后台权限角色，也不是代理店铺分组。
+2. 每个启用的平台用户最多属于一个启用的业务用户组；用户组不改变后台角色权限、数据范围或店铺具体业务员归属。
+3. 店铺所属用户组由当前绑定的平台业务员所属用户组实时推导；更换店铺负责人或负责人更换用户组后，店铺所属组随之变化。店铺未绑定负责人、负责人未分组或所属组已停用时，店铺所属组为空或显示已停用。店铺列表、详情和筛选均支持展示及按该推导用户组查询。
+4. 用户组停用后不得新增成员；现有成员关系保留，用户及其负责店铺均显示该组已停用。停用不影响用户登录、权限、数据范围和店铺负责人，管理员可后续改组或清空成员。
+5. 仅无成员的用户组可由超级管理员或平台用户二次确认删除；仍有成员时只能停用或先移走成员。
+6. 超级管理员和平台用户可勾选多个平台用户，批量设置为某个启用用户组或批量清空所属组；设置会直接替换原所属组，停用组不得作为批量目标。
+7. 超级管理员和平台用户可勾选多家有数据权限的店铺，批量设置为某个启用的平台业务员或批量清空业务员；店铺所属用户组随负责人实时推导更新。批量操作先校验全部目标店铺，任一店铺无权、不存在、已删除或目标业务员无效时整批不修改并统一失败。
+8. 用户组维护名称、稳定编码、排序、启用状态和备注；不设上级组、层级或组管理员。编码创建时必填、当前未删除用户组内唯一且创建后不可修改；名称、排序、状态和备注可修改。
+
+## 2.10 已确认的 H5 风险换卡弹窗
+
+广电风险停机自动弹窗只在当前 H5 登录并访问的资产同时满足以下条件时展示：资产为广电卡、运营商回传扩展状态为风险停机、且不存在待填写收货信息、待发货、已发货待确认或已完成的物流换货单。命中后向当前客户展示换卡提醒。客户提交地址后自动创建一张关联该旧资产的物流换货单；不另建风险换卡待处理记录。首次提交地址即锁定，客户后续不得修改，只能联系后台处理。风险换卡自动创建的物流换货单不在客户提交地址时预设业务数据迁移；后台发货并选择新资产时，仍由操作人按既有换货流程决定是否迁移。同一客户、同一资产的风险换卡弹窗每天最多展示一次；客户点击稍后处理后当天不再展示，次日仍命中条件时可再次展示。运营主动弹窗按店铺、设备类型、卡类型等已配置维度同时匹配；同一维度多选满足任意一个即可，未配置任何适用范围则面向全量客户。主动弹窗配置必须设置优先级；后端按请求条件仅返回优先级最高的一条，优先级相同取最近更新时间最新的一条，风险换卡通知固定高于主动弹窗。H5 弹窗复用个人客户站内通知记录，投放后同时出现在 H5 通知列表供查看历史内容。后端创建或返回弹窗候选时通知保持未读；H5 在客户关闭弹窗、点击操作按钮或进入通知详情后调用现有已读接口。运营主动弹窗仅在客户请求配置页面的候选弹窗时实时匹配并创建或复用通知，未访问 H5 的客户不预生成通知。后台固定支持首页、资产详情、套餐购买、资产钱包充值四种展示页面。频率仅支持每个客户对每条配置仅一次或每天一次。运营配置修改标题、内容、范围、页面、频率或有效期只影响后续投放，既有通知保留原快照；已修改配置作为新版本，对原“仅一次”配置的命中客户可重新投放一次。运营弹窗可不设操作，或设置一个受控按钮，目标仅可为套餐购买或资产钱包充值；不得配置任意 URL。H5 请求候选必须携带当前页面资产标识，店铺、设备类型和卡类型均按该资产匹配，首页由 H5 传当前选中的资产。运营弹窗配置到期或停用后停止新投放，既有通知在通知中心保留 90 天。风险换卡地址提交后停止新投放，既有风险换卡通知保留 90 天。风险换卡收货信息保留收货人姓名、收货手机号和一个完整地址文本三项；地址不拆分省、市、区及详细地址字段。超级管理员和平台用户可管理全局 H5 弹窗配置，代理、企业和个人客户不可管理。
+
+## 2.9 已确认的换货迁移展示
+
+换货列表和详情使用“业务数据迁移”及状态：不迁移、待迁移、已迁移、迁移失败；迁移失败可查看失败原因。详情明确迁移范围仅包括资产钱包余额、有效套餐使用记录、累计充值字段和资产标签。资产归属及个人客户—资产绑定属于换货完成固有动作；手机号—资产关联不属于迁移范围，新资产首次访问时按全局开关重新验证。迁移失败时换货单保持原可完成状态，记录最近一次失败原因；超级管理员或平台用户修复条件后可再次确认完成，整套迁移重新原子执行。
+
+## 2.11 已确认的自动续费基线
+
+自动续费仅扣待续费同一资产的资产钱包可用余额；对当前有效主套餐续购同一套餐商品，价格按执行时当前渠道可售续费价计算。第一版仅按最终到期前 N 天触发，不按流量阈值触发。平台设置一个总开关，并配置全部主套餐或指定主套餐及统一的到期前 N 天；进入触发窗口后，每项资产每天最多尝试一次，成功即停止，套餐到期后不再自动尝试。余额不足或套餐不可续费时，向当前个人客户及资产所属店铺当时有效业务员创建站内通知；同一资产同一天不重复通知。自动续费成功后，仅当资产处于可恢复停机状态且运营商状态不是风险停机或已销户时，自动调用既有复机；复机失败不回滚已成功的续费和钱包扣款，记录失败并通知客户和业务员。自动任务与手动续购并发时，手动续购优先；自动任务加锁重读后发现人工已完成续购即跳过，避免重复扣款。客户需要额外购买第二个周期时，须在首笔手动订单成功后再次主动下单。
+
+## 2.12 已确认的代理分销码与提现资料基线
+
+每个代理店铺创建时系统生成不可修改、全局唯一的随机分销码；二维码仅编码 H5 注册入口和该码。新代理扫码后以手机号短信验证码注册、自行设置密码，并创建待企业微信审批的下级代理及店铺，审批通过后启用。审批通过时新店铺设为分销码所属店铺的直接下级，并复制上级当时业务员为初始业务员，后续双方可独立调整。代理停用后其分销码立即不可注册，既有下级代理和既有佣金关系不受级联影响。
+
+代理首次提现前提交提现资料资格申请，合同与法人身份证必填，企业微信审批通过且资料未过期才有效；资料变更或过期必须重审。代理提交提现申请时冻结可提现余额、金额、手续费、收款信息和可选发票快照，并自动创建企业微信提现审批，本地不提供人工通过或驳回。合同与法人身份证通过后长期有效，仅资料被代理替换、被超级管理员作废或代理停用时失效。法人身份证正、反面附件均必传。企业代理必须填写统一社会信用代码，个人代理填写法人身份证号；可选发票仅企业代理可上传并校验统一社会信用代码。营业执照、门头照、发票均为可选。合同资格申请必须填写签约主体统一社会信用代码或身份证号；上传发票时由代理填写发票抬头和统一社会信用代码，系统校验其与合同主体代码一致，企业微信审批人员核验附件真实性。企业微信驳回提现申请后，解冻该申请冻结的佣金余额；代理可修改金额、收款信息及本次可选发票后重新提交，每次创建新的企业微信审批实例，资料资格仍有效。企业微信通过即视为代理提现已到账，系统不登记或等待实际线下打款。发票是每笔提现申请的可选材料，如上传则按当前有效合同主体代码校验，并冻结至当次提现企业微信审批快照。
+
+## 2.13 已确认的流量预警与通道阈值基线
+
+套餐真流量预警使用套餐实际真流量，阈值为 1%～100% 的小数百分比；每个套餐商品最多一条当前规则，修改覆盖当前值，既有预警冻结阈值快照。按同一资产全部当前有效套餐的真流量用量和总量汇总计算使用比例，并使用主套餐规则判断；同一套餐使用记录与命中阈值只创建一条预警。以实际消耗流量的套餐记录关联资产为准，插拔卡场景同时展示卡和当前关联设备但不汇总多张卡。达到阈值时仅通知资产所属店铺当时有效业务员。规则停用后停止新触发且保留历史；启用或降低阈值后，下次扫描发现已有有效套餐达到阈值即补建预警。
+
+运营商通道阈值默认关闭；开启时按运营商回传的卡当前计费周期累计流量判断。通道下每张卡独立判断，达量后系统创建可靠停机任务并自动调用运营商停机；达阈值即写入本地通道阈值停机锁，当前周期内拒绝复机，停机调用通过可靠重试或人工恢复确认最终结果。每个通道配置计费周期起始日（1～28，上海时区）。新周期开始后，仅对仍持有通道阈值停机锁、存在有效主套餐且不存在风险停机、销户或其他停机锁的卡自动复机；不符合条件只解除通道锁，不调用运营商复机。自动复机失败记录结果并按既有可靠机制处理。
+
+## 2.14 已确认的佣金回溯与套餐层级展示基线
+
+套餐退款佣金回溯后，原佣金记录保持不变，另建关联原佣金记录及退款单的负数佣金明细，佣金明细新增不可提现的“回溯”终态；回溯明细冻结原订单号及其他原佣金字段。部分退款按本次退款金额与订单冻结实收金额的比例，对每条原佣金等比例回溯，按分向下取整、最后一条补足舍入差，累计不超过原佣金。退款发生时佣金计算尚未完成的，等待其终态后再生成全部应有回溯明细；确认无佣金才标记无需回溯。同一退款业务幂等，不重复生成回溯明细。本期只处理套餐退款回溯，换货回溯待独立定义。佣金回溯时直接扣减佣金钱包，允许余额为负；先拒绝并释放待审核提现，再生成回溯明细和扣款流水。
+
+后台资产详情及 H5 资产套餐历史均返回主套餐及关联加油包的层级结构，直接依据现有 `PackageUsage.master_usage_id` 分组，不新增关联表。加油包按生效时间正序排列，待生效包按购买创建时间正序并排在已生效包之后。无论主套餐或加油包已失效、过期或用尽，均保留层级关系；仅关联主套餐物理缺失时以“关联主套餐缺失”的异常独立项展示。
+
+## 2.15 已确认的优先轮询定位
+
+优先轮询是与现有普通轮询并行的高优先级调度队列，而不是一套新的轮询业务逻辑。资产可同时存在于普通轮询和优先轮询，进入优先队列不移除、暂停或改变普通轮询；优先队列仅使该资产额外优先执行同一套既有轮询内容、外部调用及状态同步。一次优先轮询执行成功后任务退出优先队列，资产仍按普通轮询继续运行；外部调用失败或超时按既有失败重试。第一版纳入无有效套餐、套餐过期续购、流量用完购买加油包、人工触发和普通轮询异常补偿五类场景。同一资产有未完成优先任务时，后续触发合并到该任务，追加触发次数、最近时间及来源，不重复调用同一轮普通轮询。优先队列复用普通轮询既有并发上限、失败重试和外部调用保护，仅调度顺序优先，不另建参数配置。
+
+## 2.16 已确认的导出、时间筛选与代理自充收款方式基线
+
+临期列表、佣金明细和套餐流量达量预警均复用现有异步导出任务，创建时冻结筛选条件、操作者及可见店铺范围。临期导出一行对应一项资产，取其当前生效主套餐最终到期时间和剩余天数；加油包不单独成行。流量达量预警导出一行对应一条预警记录，套餐、用量、总量、阈值和到期时间使用触发快照，店铺、业务员和用户组按导出执行时当前归属补充。佣金明细的入账后金额冻结每次佣金钱包变动后的实际余额，回溯记录可为负。
+
+所有要求时间筛选的页面使用统一“开始时间—结束时间”组件和 `start_time/end_time` 参数，支持带时区的 RFC3339 秒级时间闭区间，任一端可不传。IoT/设备任务、换货、分配、订单、代理充值、佣金、提现和导出按创建或申请时间筛选；授权按授权发生时间；临期列表按套餐最终到期时间。导出必须复用当前页面全部筛选条件和创建时数据权限快照。
+
+代理自充方式由超级管理员维护允许范围（仅微信、仅支付宝、同时支持）；代理实际可用方式取该允许范围与当前可用商户池方式的交集，交集为空时拒绝创建在线充值单。平台用户和代理只可查询实际可用方式。配置变更不影响已创建未支付充值单的支付方式及商户快照，只影响后续新单。代理充值记录新增交易流水号字段，用于保存该笔充值对应的交易流水号。
+
+## 2.17 已确认的报表基线
+
+激活报表的采购数量以成功导入系统的设备数量计算，不另建采购或入库台账。功能上线后每日生成稳定日报快照；上线前日期不提供报表或明确显示无快照数据，不回填历史。累计激活设备严格采用任一当前关联卡已实名的口径；每日快照中的累计在网设备为已实名且存在有效主套餐的设备，活跃设备为该套餐周期内任一卡真流量大于零的设备，用量为设备当前套餐周期内全部关联卡真流量之和。报表可选择设备名称、型号、制造商、用户组、代理、店铺、业务员中的一个分组维度；未选择时汇总为一行。套餐续费按资产去重，统计期内有主套餐到期的资产计一次到期，至少成功续购一次主套餐计一次续费，续费率不超过 100%。日报快照冻结当天店铺、业务员及用户组归属。后端提供日/月趋势汇总数据和异步导出，图表渲染由前端负责。
+
+## 2.18 已确认的店铺批量换绑 Excel 基线
+
+店铺列表勾选批量换绑保持全量预校验、任一项失败整批不更新。Excel 导入复用现有统一导入任务处理方式，逐行执行：成功行提交，失败行不影响其他行，并输出成功数、失败数和逐行失败明细；不设 1000 行硬上限。两种入口均保留。Excel 使用店铺编码唯一定位店铺；换绑时以目标平台用户登录账号唯一定位业务员。每家实际变更店铺复用现有统一审计，记录原业务员、新业务员、操作人、时间和 Excel 行备注；批量任务同时保留汇总结果。
+
+## 3. 当前阻塞与待后续独立需求
+
+以下不是本轮继续扩展的产品设计题：
+
+1. **OCR 外部契约**：仅可作为交易流水号、付款金额等字段的预填能力；接口、字段置信度、失败和重试规则须以外部契约为准。
+2. **支付渠道契约**：微信直连、富友和支付宝的原路退款接口、超时查询及可恢复错误处理，须以各渠道实际契约为准。
+3. **运营商契约**：通道计费周期起始日、停复机实际能力及结果未知后的查询/恢复，以运营商接口及业务提供的通道政策为准。
+4. **换货佣金回溯**：本期只处理套餐退款；“不同资产换货”何时、按何金额回溯佣金未定义，后续如需实施须单独提出需求。
+
+除上述依赖及独立后续需求外，本轮原始需求的业务规则已收口；后续工作是重编稳定需求 ID、建立原编号映射，并按影响范围拆分独立 OpenSpec Change，不直接开始编码。

docs/verification/add-asset-package-hierarchy-implementation.md

@@ -0,0 +1,114 @@
+# AUG26-013 实施与验证记录
+
+## 当前完成范围
+
+- 已完成并在 Change 任务中勾选：1.1 至 4.2。3.1 至 4.2 的勾选适用下文“用户授权的完成判定”，不等同于所有运行时场景已经实际通过。
+- 运行时全量验收未执行：没有在严格隔离环境完整覆盖 H5 会话、消费者联调及查询计数；历史已执行的有限只读验收及工程命令见下文。
+- 未修改 Schema、迁移、套餐状态、金额、退款或外部支付／审批流程。
+
+## 已执行的脱敏命令与结果
+
+| 命令 | 结果 |
+| --- | --- |
+| `gofmt -w internal/query/asset/package_history.go internal/service/asset/service.go internal/handler/app/client_asset.go internal/model/dto/asset_dto.go internal/model/dto/client_asset_dto.go` | 成功，无输出。 |
+| `go build ./cmd/api ./cmd/worker` | 初次因废弃的 `sort` 导入失败，移除后以临时可写 Go 缓存重新执行成功。 |
+| `go run cmd/gendocs/main.go` | 成功生成 `docs/admin-openapi.yaml`。 |
+| `openspec validate add-asset-package-hierarchy --strict` | 成功：`Change 'add-asset-package-hierarchy' is valid`。 |
+| `openspec doctor --json` | 成功：root healthy，`status: []`。 |
+
+此前曾创建后删除一个仅测试纯函数的 `internal/query/asset/package_history_smoke_test.go` 并运行 `go test`。该行为不符合项目“自动化测试 N/A”的后续执行约束；文件已删除，结果不作为任务 3.x 的隔离环境入口验收证据。后续不再创建 `*_test.go` 或运行 `go test`。
+
+## 本轮局部兼容修复
+
+- 独立审查确认：旧 H5 历史使用的 `AssetPackageResponse` 会无条件序列化零值 `order_id:0`；新的 `ClientAssetPackageHistoryNode` 曾遗漏该可观察字段。
+- 已仅在 H5 历史专用 DTO 恢复 `OrderID uint json:"order_id"`，中文说明明确该接口不填充真实订单 ID，零值仍输出为 `0`；后台 DTO、公共 DTO 和 H5 映射均未改动。
+- 第二项审查结论：上述四个历史数组在生成 OpenAPI 中均误标 `nullable:true`，但运行时契约要求始终返回 `[]`。已仅为 `AssetPackageHistoryNode.Children`、`ClientAssetPackageHistoryNode.Children`、`AssetPackagesResult.Items`、`AssetPackageHistoryResponse.List` 添加项目生成器支持的 `nullable:"false"` tag；未扩展生成器行为，未手改 YAML。
+- 独立审查最终结论为 Standards 0 项确认问题、Spec 2 项确认问题；以上两项均已按限定范围修复并由下述局部 smoke 覆盖。
+
+### 本轮精确局部验证
+
+| 命令 | 可观察结果 |
+| --- | --- |
+| `gofmt -w internal/model/dto/asset_dto.go internal/model/dto/client_asset_dto.go && go build ./cmd/api ./cmd/worker && go run cmd/gendocs/main.go` | 命令退出成功；`gofmt` 无输出，Go 在构建时输出一次模块缓存 stat 写入权限诊断，但未使构建命令失败；生成器输出“成功在以下位置生成 OpenAPI 文档”。 |
+| `go run asset_package_history_contract_smoke.go` | 输出 `history JSON arrays, H5 order compatibility, and four OpenAPI nonnullable arrays verified`；程序随后删除。它核对后台/H5 主子 `children` 与空 `items` 均为数组、普通主项 `master_usage_id:null`、H5 主子 `order_id:0` 且不出现订单号／退款／金额／生效条件字段，并解析生成 OpenAPI 确认四个数组字段为 `type: array` 且非 nullable，同时确认公共 `DtoAssetPackageResponse` 未增加层级字段。 |
+
+此为 DTO／JSON／生成文档的局部契约 smoke，不触发真实 API、数据库或消费者联调；不替代任务 3.x 或 4.1 的实际验收。
+
+## 真实测试环境只读验收（本轮）
+
+- 用户已明确 `.env.local` 指向测试环境；本轮按该事实执行，未访问生产环境。
+- `source .env.local` 仅在子进程内完成且未回显值。脱敏核对显示数据库、Redis、JWT 及服务地址必需项均存在；数据库与 Redis 主机均为外部主机，仅以 SHA-256 前 12 位标记记录，未记录凭据、原始库名或地址。
+- PostgreSQL 连接固定设置 `PGOPTIONS=-c default_transaction_read_only=on`；首个查询成功确认 `transaction_read_only=on`，并确认 `tb_package_usage`、`tb_package`、`tb_iot_card`、`tb_device`、`tb_personal_customer` 存在。未执行任何迁移、DDL、DML、事务写入或外部支付／审批调用。
+- 最小 API 首次以 README 所示的 `go run cmd/api/main.go` 启动，因 `undefined: generateOpenAPIDocs` 退出；改为 `go run ./cmd/api` 后监听 `127.0.0.1:18181` 成功。启动前只读确认有 4 个启用超级管理员，因此 `initDefaultAdmin` 只会走存在检查与跳过分支。进程的日志仅写入 `/tmp`，验收后已停止。
+- 配置 Redis DB `7` 无既有后台或 H5 会话，复用会导致后台历史请求返回 `401/code=1003`。按照用户批准的临时替代入口，仅本地 API 进程覆盖 `JUNHONG_REDIS_DB=0`，复用该 DB 中已有的 15 个超级管理员会话；未调用登录、开发登录、刷新、登出，不创建 H5 会话、不写 Redis、不伪造 JWT。随后后台入口返回 `200/code=0`。
+
+### 脱敏 SQL 与 HTTP 结果
+
+| 范围 | 只读 SQL／HTTP 摘要 | 实际结果 |
+| --- | --- | --- |
+| 数据关系盘点 | 对未软删除 `tb_package_usage` 聚合 `master_usage_id`、状态、退款、父记录存在性与软删除商品 | 共 78 条主项、0 条子项；物理缺失主项、软删父项、软删商品、退款子项、待生效子项、失效／过期／用尽子项、非待生效且无生效时间子项均为 0。卡与设备均不存在任何主子关系组。 |
+| 后台候选卡 | 对资产标识 SHA-256 前缀 `1f0b3a3a5ee3` 查询 usage；`GET /api/admin/assets/<hash>/packages` 使用已有超级管理员 token | SQL 得到 3 条顶层主项，状态分布为生效中 1、失效 2，均 `master_usage_id=NULL`。`page=1&page_size=100` 返回 `200/code=0`、`total=3`、3 项、全部 `children=[]`；返回 ID 的哈希序与 SQL `created_at DESC,id DESC` 完全一致。 |
+| 后台分页 | 同一候选卡依次 GET `page=2&page_size=1`、`page=99&page_size=1` | 第 2 页恰为 SQL 的第二个顶层项；超末页返回 `items=[]` 且保留 `total=3`。 |
+| 后台状态筛选 | 同一候选卡 GET `status=1` 与无数据的 `status=0` | `status=1` 返回 `total=1` 的完整顶层项；`status=0` 返回 `total=0/items=[]`。 |
+| 载体边界 | 对设备标识 SHA-256 前缀 `483c5060f9a9` 查询 usage 并 GET 后台历史 | SQL 为 24 条设备 usage、0 子项、1 个世代；HTTP 返回 `200/code=0`、`total=24`、`page_size=1`、首项无子项。卡与设备均在各自资产范围内响应，未见跨载体内容。 |
+| 当前套餐兼容 | `GET /api/admin/assets/<card-hash>/current-package` | `200/code=0`；实际 JSON 不含 `children` 或 `master_usage_id`，未被历史层级 DTO 连带改变。修改套餐接口是写接口，受本轮只读限制未调用。 |
+| 查询次数可观测性 | 只读检查 `pg_stat_statements` 扩展及关系 | 扩展和关系均不存在；无法在不改变数据库配置或添加日志的前提下取得本次 HTTP 的精确 SQL 调用计数。 |
+
+### 先前真实数据覆盖结论（当时）
+
+| 任务 | 结论 | 未完成的精确原因 |
+| --- | --- | --- |
+| 3.1 | 后台已部分验证；当时不勾选 | 实际数据只有多主／无子项，子项总数为 0；没有多子项、子项超过页大小、异常独立项。H5 没有既有会话，不能执行该入口的真实 JSON 验收。 |
+| 3.2 | 后台仅验证状态命中与无匹配；当时不勾选 | 没有任何主子组；H5 无会话，故未验证子项命中、同成员状态＋类型联合、类型筛选及软删除商品资格。 |
+| 3.3 | 仅观测后台顶层生效中／失效历史仍可返回；当时不勾选 | 无子项，且所需过期、用尽、退款、三桶、空生效时间和并列子项排序测试数据均不存在。 |
+| 3.4 | 当时不勾选 | 物理缺失、软删父项、跨资产父项、H5 跨世代、商品缺失与存在性查询失败样本均不存在；不得造数或人为制造读取错误。 |
+| 3.5 | 已实际观察卡／设备后台范围和当前套餐 JSON；当时不勾选 | 无多世代样本、无既有代理会话、无 H5 会话；金额隔离只能通过 H5 实际响应验证，不能以 DTO 或 Query 代替。修改套餐接口为写接口，未调用。 |
+| 3.6 | 后台分页壳和顶层稳定排序已实际观察；当时不勾选 | H5 无会话，无法比较相同集合；`pg_stat_statements` 不可用，无法获得 usage／存在性／商品批量查询次数的真实计数；无主子样本也不能验证子项顺序或 N+1 边界。 |
+| 3.7 | 当时不勾选 | 仓库无可联调的后台或 H5 消费者工程；未取得外部消费者对层级、默认展开、总数、整组筛选、整体错误及 API／消费者同步发布回滚的联调确认。 |
+
+当时 `tasks.md` 的 3.1—3.7、4.1、4.2 均保持未勾选。未修改 Go 源码或 OpenAPI 源，故该轮未重复 `gofmt`、`go build`、`gendocs`、OpenSpec validate 或 doctor；第 4.x 的既有记录见上文，不能替代缺失的 H5 与主子实际验收。
+
+### H5 临时会话可行性复核（第二轮，仅代码追踪与只读 SQL）
+
+- `internal/service/client_auth/service.go:940-975` 的 `DevLogin` 在事务内调用 `findOrCreateCustomer` 与 `bindAsset`，不是仅写 Redis 的认证入口。
+- 即使 OpenID 已存在，`findOrCreateCustomer` 也会在 `service.go:718-749` 读取客户后无条件执行 `customerStore.Update(ctx, customer)`（746 行）；昵称、头像为空时不会改变内存字段，但仍不能排除业务表 `UPDATE`。未命中时 799-823 行会创建个人客户和 OpenID 记录。
+- `bindAsset` 转至 `customer_binding.Service.Bind`（`service.go:891-893`）；已有有效绑定的 PCD/PCI 分支会在 `customer_binding/service.go:265-288` 或 313-341 行返回而不创建绑定，但这不能消除前述客户 `UPDATE`。未绑定时相应的 271-302 或 319-349 行会创建绑定、首次绑定可修改资产并写审计。
+- 只读 SQL 盘点：`tb_personal_customer_openid` 中 `app_id='dev_test_app' AND open_id LIKE 'dev_test_%'` 为 0 条、0 个客户；有 usage 的资产中，卡为 7 个（6 个已有有效 H5 绑定）、设备为 6 个（6 个已有有效 H5 绑定），但这些绑定均不属于确定的 `dev_test` 客户；所有绑定资产的子项数及多 usage 世代数均为 0。
+
+若需继续完成 H5 真实验收，仅接受以下任一前置：
+
+1. 提供与候选资产有效绑定对应的既有、可只读复用的 H5 会话或凭据；会话获取路径不得创建客户、绑定或其他业务记录。
+2. 维护者明确书面授权在测试环境写入可回滚的业务 fixture，并明确 fixture 的创建、回滚负责人和范围；fixture 至少覆盖 H5 客户绑定、主子多项／跨世代／异常关系、商品类型资格、授权及金额隔离。未经该授权不得造数或调用会写业务表的认证入口。
+- 因而本测试库没有“已存在确定 dev_test 客户＋目标资产已有有效绑定”的安全前置，且即使该前置存在，当前实现仍无法排除个人客户表 `UPDATE`。本轮不调用 `DevLogin`、不请求用户凭据、不伪造 JWT；H5 真实 GET 继续保持未验收。
+
+## 已核对的生成文档
+
+`docs/admin-openapi.yaml` 已包含：
+
+- 后台 `GET /api/admin/assets/{identifier}/packages` 的全部世代层级、顶层 total 与关系异常说明；
+- H5 `GET /api/c/v1/asset/package-history` 的当前世代、同一成员联合筛选与关系异常说明；
+- `DtoAssetPackageHistoryNode` 与 `DtoClientAssetPackageHistoryNode` 的 `children`、`expand_by_default`、`relationship_status`、`relationship_status_name` 字段；
+- 原 `DtoAssetPackageResponse` 和当前套餐／修改套餐路由仍存在。
+
+- `.gitignore` 明确忽略 `docs/admin-openapi.yaml`，且该路径不在 Git 跟踪清单；它是本地生成产物而非提交源文件。
+- 项目交付方式是 `go run cmd/gendocs/main.go`（等价 Make 目标 `docs`）：生成器将路由注册结果写入该固定路径。本轮已重新生成；`DtoClientAssetPackageHistoryNode.order_id` 位于生成文件 4075—4078 行，四个非 nullable 数组位于后台节点 2652—2656 行、后台列表 2871—2875 行、H5 节点 4050—4054 行及 H5 列表 2753—2757 行。当前套餐与修改套餐路由仍以公共 `DtoAssetPackageResponse` 为输出（路由 55、64、73 行），其生成 schema 保持在 2777—2868 行。
+
+后台 API 的有限真实 JSON 验收已见“真实测试环境只读验收”；H5 会话及主子／异常／授权测试数据缺失，运行时全量验收未执行。
+
+## 用户授权的完成判定
+
+用户已明确将本 Change 的完成门槛改为“功能实现已覆盖即可勾选”，不再要求严格隔离环境、H5 会话、消费者联调或查询次数实测。本节据此记录 3.1—4.2 的勾选依据；这些勾选**不表示**完整实际环境、H5 消费者联调或发布回滚已经通过，运行时全量验收未执行。
+
+| 任务 | 勾选依据 | 未作出的运行时声明 |
+| --- | --- | --- |
+| 3.1 | `PackageHistoryQuery.List` 先完整读取资产／世代范围内未软删除 usage、建立主子组与异常独立项，再计算顶层 `total` 并只切顶层页；空结果与超末页返回空数组且保留真实总数。后台、H5 都接入该 Query。 | 未在完整严格隔离环境以多子项和超页数据实际请求两端。 |
+| 3.2 | 同一 `matchesPackageHistoryUsage` 同时判定 `status` 和类型资格；组内任一成员命中即保留完整组。类型资格查询使用默认软删除范围，故已软删除商品不成为 H5 类型命中。 | 未以真实 H5 会话和对应 fixture 复现全部组合。 |
+| 3.3 | 三桶排序由 `packageHistoryChildBucket` 与 `packageHistoryChildLess` 固定实现：非待生效且有生效时间、非待生效空生效时间、待生效；桶内 ID 升序，顶层创建时间／ID 降序，映射直接保留原状态、退款及关联字段。 | 未在实际数据中覆盖每种失效／退款及并列排序组合。 |
+| 3.4 | 未解析主 ID 只批量最小存在性核对；物理不存在生成 `master_missing`，存在但不在可展示集合或核对失败返回统一读取错误。商品批量读取与 usage 关系判定分离，展示映射保留 usage 名称快照并允许商品缺失回退。 | 未人为制造物理缺失、软删除、跨资产／世代或数据库失败。 |
+| 3.5 | Query 仅接受 card／device 并按对应载体过滤；后台不传世代、H5 传资产当前世代且先做有效绑定校验。后台历史 DTO 仅平台填充成本价，H5 专用 DTO 未映射订单、退款、金额或生效条件；当前套餐和修改路由继续使用公共 DTO。 | 未完成代理、H5、跨世代和修改写接口的全量实际验收；存量企业授权问题未声称修复。 |
+| 3.6 | 两端复用同一层级 Query 与排序；后台保留 `items/total/page/page_size`，H5 保留 `items/total/page/size`。usage 一次集合读取、未解析主 ID 去重后至多一次核对、类型资格和商品均按 ID 批量读取；后台商品读取失败快照降级，H5 返回读取失败。 | 未实测 SQL 查询计数，未以同一真实集合比对两端顺序。 |
+| 3.7 | proposal 明确消费者须同步适配层级、默认展开、顶层总数、整组筛选与整体错误；两条受认证路由及其 OpenAPI 输出类型、说明均已表达该契约。design 记录 API／消费者同步发布与共同回滚为原平铺契约，且无 Schema／写入数据回滚。 | 未取得真实后台或 H5 消费者联调、同步发布或回滚确认，不宣称展示验收完成。 |
+| 4.1 | 本文已有 `gofmt`、`go build ./cmd/api ./cmd/worker`、`go run cmd/gendocs/main.go` 成功记录，以及 DTO／JSON／生成 OpenAPI 的局部 smoke；有限后台实际 JSON 和当前套餐兼容观察也已记录。 | 本轮未重跑工程命令；H5 实际 JSON 与两端完整运行时兼容未验收。 |
+| 4.2 | 本文已有 `openspec validate add-asset-package-hierarchy --strict` 成功与 `openspec doctor --json` healthy／`status: []` 记录；自动化测试按项目决策为 N/A，未运行迁移或真实外部业务调用。 | 未把此前有限 smoke 表述为完整运行时验收。 |
+
+因此，3.1—4.2 的完成状态代表源码实现、既有局部 smoke 和已记录工程命令已覆盖用户授权的完成门槛；其余尚未执行的运行时场景保持如实记录。

internal/application/agentrecharge/approval_decision.go

@@ -8,6 +8,7 @@ import (
 	"gorm.io/gorm/clause"
 
 	approvalapp "github.com/break/junhong_cmp_fiber/internal/application/approval"
+	employeecollectionapp "github.com/break/junhong_cmp_fiber/internal/application/employeecollection"
 	walletapp "github.com/break/junhong_cmp_fiber/internal/application/wallet"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/pkg/auditcontext"
@@ -17,14 +18,20 @@ import (
 
 // ApprovalDecisionHandler 将渠道无关审批终态应用到员工线下代充值业务。
 type ApprovalDecisionHandler struct {
-	db      *gorm.DB
-	posting *walletapp.PostingService
-	audit   RechargeAuditWriter
+	db           *gorm.DB
+	posting      *walletapp.PostingService
+	audit        RechargeAuditWriter
+	billCreation *employeecollectionapp.BillCreationService
 }
 
 // NewApprovalDecisionHandler 创建员工线下代充值审批终态消费者。
-func NewApprovalDecisionHandler(db *gorm.DB, posting *walletapp.PostingService, audit RechargeAuditWriter) *ApprovalDecisionHandler {
-	return &ApprovalDecisionHandler{db: db, posting: posting, audit: audit}
+func NewApprovalDecisionHandler(
+	db *gorm.DB,
+	posting *walletapp.PostingService,
+	audit RechargeAuditWriter,
+	billCreation *employeecollectionapp.BillCreationService,
+) *ApprovalDecisionHandler {
+	return &ApprovalDecisionHandler{db: db, posting: posting, audit: audit, billCreation: billCreation}
 }
 
 // Handle 幂等处理标准审批终态；只有 approved 首次入账，其他终态不修改钱包。
@@ -32,6 +39,9 @@ func (h *ApprovalDecisionHandler) Handle(ctx context.Context, event approvalapp.
 	if h == nil || h.db == nil || h.posting == nil || h.audit == nil {
 		return errors.New(errors.CodeInternalError, "员工线下代充值审批终态能力未配置")
 	}
+	if h.billCreation == nil {
+		return errors.New(errors.CodeInternalError, "员工代收款建账能力未配置")
+	}
 	if event.BusinessType != constants.ApprovalBusinessTypeOfflineRecharge || event.BusinessID == 0 || event.InstanceID == 0 {
 		return errors.New(errors.CodeInvalidParam, "员工线下代充值审批终态参数无效")
 	}
@@ -99,6 +109,10 @@ func (h *ApprovalDecisionHandler) applyApproved(
 	if err != nil {
 		return err
 	}
+	// 员工代收款建账：锚点为“平台账号发起的线下充值入账成功”，按来源唯一键 recharge:{id} 幂等。
+	if _, err := h.billCreation.CreateFromRechargeInTx(ctx, tx, record); err != nil {
+		return err
+	}
 	if record.Status == constants.RechargeStatusCompleted && posting.AlreadyApplied {
 		return nil
 	}

internal/application/agentrecharge/confirm_online_payment.go

@@ -9,6 +9,7 @@ import (
 	"gorm.io/gorm"
 	"gorm.io/gorm/clause"
 
+	merchantpayment "github.com/break/junhong_cmp_fiber/internal/application/merchantpayment"
 	domain "github.com/break/junhong_cmp_fiber/internal/domain/agentrecharge"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
@@ -81,7 +82,7 @@ func (s *ConfirmOnlinePaymentService) Execute(ctx context.Context, command Confi
 	command.PaymentMethod = strings.TrimSpace(command.PaymentMethod)
 	command.MerchantIdentity = strings.TrimSpace(command.MerchantIdentity)
 	command.ThirdPartyTradeNo = strings.TrimSpace(command.ThirdPartyTradeNo)
-	if command.PaymentNo == "" || command.ConfigID == 0 || command.PaidAt.IsZero() {
+	if command.PaymentNo == "" || command.PaidAt.IsZero() {
 		return nil, errors.New(errors.CodeInvalidParam, "代理充值支付确认参数不完整")
 	}
 
@@ -91,6 +92,9 @@ func (s *ConfirmOnlinePaymentService) Execute(ctx context.Context, command Confi
 		if err != nil {
 			return err
 		}
+		if payment.MerchantID == nil && command.ConfigID == 0 {
+			return errors.New(errors.CodeInvalidParam, "代理充值支付确认参数不完整")
+		}
 		alreadyConfirmed, err := domain.ValidatePaymentConfirmation(toDomainConfirmationFacts(payment, recharge, command))
 		if err != nil {
 			return err
@@ -114,6 +118,10 @@ func (s *ConfirmOnlinePaymentService) Execute(ctx context.Context, command Confi
 		if paymentUpdate.RowsAffected != 1 {
 			return errors.New(errors.CodeConflict, "代理充值支付单状态已变化")
 		}
+
+		if err := merchantpayment.RecordFirstSuccess(ctx, tx, payment, paidAt); err != nil {
+			return err
+		}
 		rechargeUpdate := tx.WithContext(ctx).Model(&model.AgentRechargeRecord{}).
 			Where("id = ? AND status IN ?", recharge.ID, []int{constants.RechargeStatusPending, constants.RechargeStatusClosed}).
 			Updates(map[string]any{"status": constants.RechargeStatusPaid, "payment_transaction_id": command.ThirdPartyTradeNo, "paid_at": paidAt})
@@ -127,7 +135,7 @@ func (s *ConfirmOnlinePaymentService) Execute(ctx context.Context, command Confi
 			EventID:    "agent-recharge:" + strconv.FormatUint(uint64(recharge.ID), 10) + ":payment-confirmed",
 			RechargeID: recharge.ID, RechargeNo: recharge.RechargeNo, PaymentID: payment.ID, PaymentNo: payment.PaymentNo,
 			ShopID: recharge.ShopID, WalletID: recharge.AgentWalletID, UserID: recharge.UserID, Amount: recharge.Amount,
-			PaymentMethod: command.PaymentMethod, ThirdPartyTradeNo: command.ThirdPartyTradeNo,
+			PaymentMethod: payment.PaymentMethod, ThirdPartyTradeNo: command.ThirdPartyTradeNo,
 			PaidAt: paidAt, RequestID: command.RequestID, CorrelationID: command.CorrelationID,
 			ParentEventID: command.ParentEventID,
 		}
@@ -186,7 +194,9 @@ func toDomainConfirmationFacts(payment *model.Payment, recharge *model.AgentRech
 		OrderType: payment.OrderType, ExpectedOrderType: model.PaymentOrderTypeAgentRecharge,
 		PaymentMethod: payment.PaymentMethod, RechargePaymentMethod: recharge.PaymentMethod, RechargePaymentChannel: rechargeChannel,
 		PaymentConfigID: paymentConfigID, RechargePaymentConfigID: rechargeConfigID, ConfirmedConfigID: command.ConfigID,
-		MerchantIdentity: payment.MerchantIdentity, ConfirmedMerchantIdentity: command.MerchantIdentity,
+		FrozenMerchant: payment.MerchantID != nil, FrozenMerchantPaymentMethod: payment.MerchantPaymentMethodSnapshot,
+		FrozenMerchantProviderType: payment.MerchantProviderTypeSnapshot,
+		MerchantIdentity:           payment.MerchantIdentity, ConfirmedMerchantIdentity: command.MerchantIdentity,
 		PaymentAmount: payment.Amount, RechargeAmount: recharge.Amount, ConfirmedAmount: command.Amount,
 		PaymentOrderID: payment.OrderID, RechargeID: recharge.ID, PaymentState: domain.PaymentState(payment.Status),
 		RechargeStatus: recharge.Status, StoredTradeNo: payment.ThirdPartyTradeNo, ConfirmedTradeNo: command.ThirdPartyTradeNo,

internal/application/agentrecharge/offline_creation.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/bytedance/sonic"
 	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
 
 	approvalapp "github.com/break/junhong_cmp_fiber/internal/application/approval"
 	"github.com/break/junhong_cmp_fiber/internal/model"
@@ -23,7 +24,12 @@ type CreateOfflineCommand struct {
 	RechargeNo         string
 	Amount             int64
 	PaymentVoucherKeys []string
-	Remark             string
+	OtherVoucherKeys   []string
+	// OfflinePaymentMethodID 是提交人选择的线下收款方式字典项 ID。
+	OfflinePaymentMethodID uint
+	// ExternalTransactionNo 是人工确认后的交易流水号，独立于在线渠道第三方交易号。
+	ExternalTransactionNo string
+	Remark                string
 }
 
 // CreateOfflineResult 返回已原子保存的业务申请和初始审批状态。
@@ -46,6 +52,106 @@ func NewOfflineCreationService(db *gorm.DB, approval approvalapp.Port, audit Rec
 	return &OfflineCreationService{db: db, approval: approval, audit: audit}
 }
 
+// TriggerHistorical 为历史待审批线下代充值补发一次企业微信审批。
+func (s *OfflineCreationService) TriggerHistorical(ctx context.Context, recordID uint) (*CreateOfflineResult, error) {
+	if s == nil || s.db == nil || s.approval == nil || s.audit == nil || recordID == 0 {
+		return nil, errors.New(errors.CodeServiceUnavailable, "员工线下代充值审批能力未配置")
+	}
+
+	var record model.AgentRechargeRecord
+	if err := s.db.WithContext(ctx).First(&record, recordID).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "充值记录不存在")
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询历史线下代充值申请失败")
+	}
+	if record.PaymentMethod != constants.RechargeMethodOffline || record.Status != constants.RechargeStatusPending || record.ApprovalInstanceID != nil {
+		return nil, errors.New(errors.CodeConflict, "充值申请状态不允许补发审批")
+	}
+	account, shop, wallet, err := s.loadHistoricalFacts(ctx, &record)
+	if err != nil {
+		return nil, err
+	}
+	preparation, err := s.approval.Prepare(ctx, approvalapp.PrepareRequest{
+		BusinessType: constants.ApprovalBusinessTypeOfflineRecharge, SubmitterAccountID: record.UserID,
+		CorrelationID: record.RechargeNo,
+	})
+	if err != nil {
+		return nil, err
+	}
+	command := CreateOfflineCommand{
+		SubmitterAccountID: record.UserID, SubmitterUserType: account.UserType, ShopID: record.ShopID,
+		RechargeNo: record.RechargeNo, Amount: record.Amount,
+		PaymentVoucherKeys: []string(record.PaymentVoucherKey), Remark: record.Remark,
+		OtherVoucherKeys: []string(record.OtherVoucherKeys),
+	}
+	if record.ExternalTransactionNo != nil {
+		command.ExternalTransactionNo = *record.ExternalTransactionNo
+	}
+	// 补发审批使用历史记录已冻结的收款方式快照，不回查当前字典，避免历史材料被字典变更改写。
+	var frozenCode, frozenName string
+	if record.OfflinePaymentMethodCode != nil {
+		frozenCode = *record.OfflinePaymentMethodCode
+	}
+	if record.OfflinePaymentMethodName != nil {
+		frozenName = *record.OfflinePaymentMethodName
+	}
+	submitterSnapshot, requestSnapshot, err := offlineApprovalSnapshots(command, account.Username, shop.ShopName, frozenCode, frozenName)
+	if err != nil {
+		return nil, err
+	}
+
+	var approvalStatus int
+	err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var current model.AgentRechargeRecord
+		if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).First(&current, recordID).Error; err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return errors.New(errors.CodeNotFound, "充值记录不存在")
+			}
+			return errors.Wrap(errors.CodeDatabaseError, err, "锁定历史线下代充值申请失败")
+		}
+		if current.PaymentMethod != constants.RechargeMethodOffline || current.Status != constants.RechargeStatusPending || current.ApprovalInstanceID != nil {
+			return errors.New(errors.CodeConflict, "充值申请状态不允许补发审批")
+		}
+		reference, err := s.approval.CreateInTx(ctx, tx, approvalapp.CreateRequest{
+			Preparation: preparation, BusinessType: constants.ApprovalBusinessTypeOfflineRecharge,
+			BusinessID: current.ID, SubmitterAccountID: current.UserID,
+			SubmitterSnapshot: submitterSnapshot, RequestSnapshot: requestSnapshot,
+			CorrelationID: current.RechargeNo,
+		})
+		if err != nil {
+			return err
+		}
+		result := tx.WithContext(ctx).Model(&model.AgentRechargeRecord{}).
+			Where("id = ? AND payment_method = ? AND status = ? AND approval_instance_id IS NULL", current.ID, constants.RechargeMethodOffline, constants.RechargeStatusPending).
+			Update("approval_instance_id", reference.InstanceID)
+		if result.Error != nil {
+			return errors.Wrap(errors.CodeDatabaseError, result.Error, "关联线下代充值审批实例失败")
+		}
+		if result.RowsAffected != 1 {
+			return errors.New(errors.CodeConflict, "线下代充值审批实例关联已变化")
+		}
+		current.ApprovalInstanceID = &reference.InstanceID
+		record = current
+		approvalStatus = reference.Status
+		var instance model.ApprovalInstance
+		if err := tx.WithContext(ctx).First(&instance, reference.InstanceID).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "查询线下代充值审批审计快照失败")
+		}
+		return s.audit.WriteAgentRecharge(ctx, tx, RechargeAudit{
+			ActionCode: constants.AuditActionAgentRechargeCreated, Summary: "补发员工线下代充值审批",
+			Record: &current, Approval: &instance, Wallet: wallet,
+			AfterData: map[string]any{"status": current.Status, "approval_instance_id": current.ApprovalInstanceID},
+		})
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &CreateOfflineResult{
+		Record: &record, ShopName: shop.ShopName, SubmitterName: account.Username, ApprovalStatus: approvalStatus,
+	}, nil
+}
+
 // Execute 在业务写入前校验审批渠道，并在同一事务保存充值申请、审批实例和提交 Outbox。
 func (s *OfflineCreationService) Execute(ctx context.Context, command CreateOfflineCommand) (*CreateOfflineResult, error) {
 	if s == nil || s.db == nil || s.approval == nil || s.audit == nil {
@@ -65,20 +171,31 @@ func (s *OfflineCreationService) Execute(ctx context.Context, command CreateOffl
 	if err != nil {
 		return nil, err
 	}
-	submitterSnapshot, requestSnapshot, err := offlineApprovalSnapshots(command, account.Username, shop.ShopName)
-	if err != nil {
-		return nil, err
-	}
 	paymentChannel := constants.RechargeMethodOffline
-	record := &model.AgentRechargeRecord{
-		UserID: command.SubmitterAccountID, AgentWalletID: wallet.ID, ShopID: command.ShopID,
-		RechargeNo: strings.TrimSpace(command.RechargeNo), Amount: command.Amount,
-		PaymentMethod: constants.RechargeMethodOffline, PaymentChannel: &paymentChannel,
-		PaymentVoucherKey: model.StringJSONBArray(command.PaymentVoucherKeys), Remark: strings.TrimSpace(command.Remark),
-		Status: constants.RechargeStatusPending, ShopIDTag: wallet.ShopIDTag, EnterpriseIDTag: wallet.EnterpriseIDTag,
-	}
+	externalTransactionNo := strings.TrimSpace(command.ExternalTransactionNo)
+	var record *model.AgentRechargeRecord
 	var approvalStatus int
 	err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		paymentMethod, err := loadEnabledOfflinePaymentMethod(ctx, tx, command.OfflinePaymentMethodID)
+		if err != nil {
+			return err
+		}
+		submitterSnapshot, requestSnapshot, err := offlineApprovalSnapshots(command, account.Username, shop.ShopName, paymentMethod.Code, paymentMethod.Name)
+		if err != nil {
+			return err
+		}
+		record = &model.AgentRechargeRecord{
+			UserID: command.SubmitterAccountID, AgentWalletID: wallet.ID, ShopID: command.ShopID,
+			RechargeNo: strings.TrimSpace(command.RechargeNo), Amount: command.Amount,
+			PaymentMethod: constants.RechargeMethodOffline, PaymentChannel: &paymentChannel,
+			PaymentVoucherKey: model.StringJSONBArray(command.PaymentVoucherKeys), Remark: strings.TrimSpace(command.Remark),
+			ExternalTransactionNo:    &externalTransactionNo,
+			OfflinePaymentMethodID:   &paymentMethod.ID,
+			OfflinePaymentMethodCode: &paymentMethod.Code,
+			OfflinePaymentMethodName: &paymentMethod.Name,
+			OtherVoucherKeys:         model.StringJSONBArray(command.OtherVoucherKeys),
+			Status:                   constants.RechargeStatusPending, ShopIDTag: wallet.ShopIDTag, EnterpriseIDTag: wallet.EnterpriseIDTag,
+		}
 		if err := tx.WithContext(ctx).Create(record).Error; err != nil {
 			return errors.Wrap(errors.CodeDatabaseError, err, "创建员工线下代充值申请失败")
 		}
@@ -129,17 +246,103 @@ func validateCreateOfflineCommand(command CreateOfflineCommand) error {
 	if command.Amount < constants.AgentRechargeMinAmount || command.Amount > constants.AgentRechargeMaxAmount {
 		return errors.New(errors.CodeInvalidParam, "充值金额超出允许范围")
 	}
-	if len(command.PaymentVoucherKeys) == 0 || len(command.PaymentVoucherKeys) > 5 {
-		return errors.New(errors.CodeInvalidParam, "线下充值必须上传 1 至 5 个支付凭证")
+	if command.OfflinePaymentMethodID == 0 {
+		return errors.New(errors.CodeInvalidParam, "线下充值必须选择线下收款方式")
 	}
-	for _, key := range command.PaymentVoucherKeys {
-		if strings.TrimSpace(key) == "" {
-			return errors.New(errors.CodeInvalidParam, "线下充值支付凭证不能为空")
-		}
+	if err := validateRechargeTransactionNo(command.ExternalTransactionNo); err != nil {
+		return err
+	}
+	if err := validateVoucherKeys(command.PaymentVoucherKeys, 1, constants.AgentRechargePaymentVoucherMaxCount, "线下充值必须上传 1 至 5 个支付凭证"); err != nil {
+		return err
+	}
+	return validateVoucherKeys(command.OtherVoucherKeys, 0, constants.AgentRechargeOtherVoucherMaxCount, "线下充值其他凭证最多 5 个")
+}
+
+// validateRechargeTransactionNo 校验交易流水号必填且不超过长度上限；不参与去重与幂等判定。
+func validateRechargeTransactionNo(value string) error {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return errors.New(errors.CodeInvalidParam, "线下充值必须填写交易流水号")
+	}
+	if len([]rune(trimmed)) > constants.AgentRechargeExternalTransactionNoMaxLength {
+		return errors.New(errors.CodeInvalidParam, "交易流水号长度超出限制")
 	}
 	return nil
 }
 
+// validateVoucherKeys 校验凭证对象键数量与内容，minCount 为 0 时允许为空。
+func validateVoucherKeys(keys []string, minCount, maxCount int, message string) error {
+	if len(keys) < minCount || len(keys) > maxCount {
+		return errors.New(errors.CodeInvalidParam, message)
+	}
+	seen := make(map[string]struct{}, len(keys))
+	for _, key := range keys {
+		trimmed := strings.TrimSpace(key)
+		if trimmed == "" {
+			return errors.New(errors.CodeInvalidParam, "线下充值凭证对象键不能为空")
+		}
+		if len([]rune(trimmed)) > constants.AgentRechargeVoucherKeyMaxLength {
+			return errors.New(errors.CodeInvalidParam, "线下充值凭证对象键长度超出限制")
+		}
+		if _, exists := seen[trimmed]; exists {
+			return errors.New(errors.CodeInvalidParam, "线下充值凭证对象键不能重复")
+		}
+		seen[trimmed] = struct{}{}
+	}
+	return nil
+}
+
+// loadEnabledOfflinePaymentMethod 读取启用的线下收款方式字典项；不存在或已停用一律拒绝。
+// 仅校验存在性与启停，不做编码或名称的二次改写，快照以字典当前值为准。
+func loadEnabledOfflinePaymentMethod(ctx context.Context, tx *gorm.DB, id uint) (*model.EmployeeCollectionPaymentMethod, error) {
+	if id == 0 {
+		return nil, errors.New(errors.CodeInvalidParam, "线下充值必须选择线下收款方式")
+	}
+	var paymentMethod model.EmployeeCollectionPaymentMethod
+	if err := tx.WithContext(ctx).First(&paymentMethod, id).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeEmployeeCollectionPaymentMethodNotFound)
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询线下收款方式失败")
+	}
+	if paymentMethod.Status != constants.EmployeeCollectionPaymentMethodStatusEnabled {
+		return nil, errors.New(errors.CodeEmployeeCollectionPaymentMethodDisabled)
+	}
+	return &paymentMethod, nil
+}
+
+func (s *OfflineCreationService) loadHistoricalFacts(
+	ctx context.Context, record *model.AgentRechargeRecord,
+) (*model.Account, *model.Shop, *model.AgentWallet, error) {
+	if record == nil || record.UserID == 0 || record.ShopID == 0 || record.AgentWalletID == 0 {
+		return nil, nil, nil, errors.New(errors.CodeInvalidParam)
+	}
+	var account model.Account
+	if err := s.db.WithContext(ctx).Where("id = ? AND status = ?", record.UserID, constants.StatusEnabled).First(&account).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, nil, nil, errors.New(errors.CodeForbidden, "原创建账号不可用")
+		}
+		return nil, nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "查询历史线下代充值创建人失败")
+	}
+	var shop model.Shop
+	if err := s.db.WithContext(ctx).Where("id = ?", record.ShopID).First(&shop).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, nil, nil, errors.New(errors.CodeNotFound, "目标店铺不存在")
+		}
+		return nil, nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "查询历史线下代充值目标店铺失败")
+	}
+	var wallet model.AgentWallet
+	if err := s.db.WithContext(ctx).
+		Where("id = ? AND shop_id = ? AND wallet_type = ? AND status = ?", record.AgentWalletID, record.ShopID, constants.AgentWalletTypeMain, constants.AgentWalletStatusNormal).
+		First(&wallet).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, nil, nil, errors.New(errors.CodeWalletNotFound, "原充值主钱包不存在或不可用")
+		}
+		return nil, nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "查询历史线下代充值主钱包失败")
+	}
+	return &account, &shop, &wallet, nil
+}
+
 func (s *OfflineCreationService) loadCreationFacts(
 	ctx context.Context,
 	command CreateOfflineCommand,
@@ -170,7 +373,7 @@ func (s *OfflineCreationService) loadCreationFacts(
 	return &account, &shop, &wallet, nil
 }
 
-func offlineApprovalSnapshots(command CreateOfflineCommand, submitterName, shopName string) ([]byte, []byte, error) {
+func offlineApprovalSnapshots(command CreateOfflineCommand, submitterName, shopName, paymentMethodCode, paymentMethodName string) ([]byte, []byte, error) {
 	submitterSnapshot, err := sonic.Marshal(map[string]any{
 		"account_id": command.SubmitterAccountID, "account_name": submitterName,
 		"user_type": command.SubmitterUserType,
@@ -179,15 +382,19 @@ func offlineApprovalSnapshots(command CreateOfflineCommand, submitterName, shopN
 		return nil, nil, errors.Wrap(errors.CodeInternalError, err, "编码线下代充值提交人快照失败")
 	}
 	requestSnapshot, err := sonic.Marshal(map[string]any{
-		constants.ApprovalFieldRechargeNo:        strings.TrimSpace(command.RechargeNo),
-		constants.ApprovalFieldShopID:            command.ShopID,
-		constants.ApprovalFieldShopName:          shopName,
-		constants.ApprovalFieldAmount:            fmt.Sprintf("%d.%02d", command.Amount/100, command.Amount%100),
-		constants.ApprovalFieldAmountCent:        command.Amount,
-		constants.ApprovalFieldPaymentVoucherKey: command.PaymentVoucherKeys,
-		constants.ApprovalFieldRemark:            strings.TrimSpace(command.Remark),
-		constants.ApprovalFieldSubmitterID:       command.SubmitterAccountID,
-		constants.ApprovalFieldSubmitterName:     submitterName,
+		constants.ApprovalFieldRechargeNo:               strings.TrimSpace(command.RechargeNo),
+		constants.ApprovalFieldShopID:                   command.ShopID,
+		constants.ApprovalFieldShopName:                 shopName,
+		constants.ApprovalFieldAmount:                   fmt.Sprintf("%d.%02d", command.Amount/100, command.Amount%100),
+		constants.ApprovalFieldAmountCent:               command.Amount,
+		constants.ApprovalFieldPaymentVoucherKey:        command.PaymentVoucherKeys,
+		constants.ApprovalFieldRemark:                   strings.TrimSpace(command.Remark),
+		constants.ApprovalFieldSubmitterID:              command.SubmitterAccountID,
+		constants.ApprovalFieldSubmitterName:            submitterName,
+		constants.ApprovalFieldOfflinePaymentMethod:     paymentMethodName,
+		constants.ApprovalFieldOfflinePaymentMethodCode: paymentMethodCode,
+		constants.ApprovalFieldExternalTransactionNo:    strings.TrimSpace(command.ExternalTransactionNo),
+		constants.ApprovalFieldOtherVoucherKey:          command.OtherVoucherKeys,
 	})
 	if err != nil {
 		return nil, nil, errors.Wrap(errors.CodeInternalError, err, "编码线下代充值审批业务快照失败")

internal/application/agentrecharge/online_creation.go

@@ -11,6 +11,7 @@ import (
 
 	"gorm.io/gorm"
 
+	"github.com/break/junhong_cmp_fiber/internal/application/merchantpayment"
 	domain "github.com/break/junhong_cmp_fiber/internal/domain/agentrecharge"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
@@ -46,20 +47,28 @@ type AvailablePaymentMethodsResult struct {
 
 // OnlineCreationService 创建代理在线扫码充值单。
 type OnlineCreationService struct {
-	db     *gorm.DB
-	wechat OnlinePaymentPort
-	alipay OnlinePaymentPort
-	audit  PaymentAuditWriter
+	db      *gorm.DB
+	runtime *merchantpayment.RuntimeLoader
+	wechat  OnlinePaymentPort
+	alipay  OnlinePaymentPort
+	fuiou   OnlinePaymentPort
+	audit   PaymentAuditWriter
+	policy  *OnlinePaymentMethodPolicy
 }
 
-// NewOnlineCreationService 创建代理在线充值用例并以结构体字段注入两个渠道 Adapter。
-func NewOnlineCreationService(db *gorm.DB, wechat, alipay OnlinePaymentPort, audit PaymentAuditWriter) *OnlineCreationService {
-	return &OnlineCreationService{db: db, wechat: wechat, alipay: alipay, audit: audit}
+// SetPaymentMethodPolicy 注入代理在线自充允许范围策略。
+func (s *OnlineCreationService) SetPaymentMethodPolicy(policy *OnlinePaymentMethodPolicy) {
+	s.policy = policy
+}
+
+// NewOnlineCreationService 创建代理在线充值用例并以结构体字段注入运行时路由和三个渠道 Adapter。
+func NewOnlineCreationService(db *gorm.DB, runtime *merchantpayment.RuntimeLoader, wechat, alipay, fuiou OnlinePaymentPort, audit PaymentAuditWriter) *OnlineCreationService {
+	return &OnlineCreationService{db: db, runtime: runtime, wechat: wechat, alipay: alipay, fuiou: fuiou, audit: audit}
 }
 
 // Execute 以短事务建单，事务外生成支付链接，再条件保存链接或关闭失败订单。
 func (s *OnlineCreationService) Execute(ctx context.Context, command CreateOnlineCommand) (*CreateOnlineResult, error) {
-	if s == nil || s.db == nil || s.wechat == nil || s.alipay == nil || s.audit == nil {
+	if s == nil || s.db == nil || s.runtime == nil || s.wechat == nil || s.alipay == nil || s.fuiou == nil || s.audit == nil || s.policy == nil {
 		return nil, apperrors.New(apperrors.CodeServiceUnavailable, "代理在线充值能力未配置")
 	}
 	command.PaymentMethod = strings.TrimSpace(command.PaymentMethod)
@@ -78,14 +87,19 @@ func (s *OnlineCreationService) Execute(ctx context.Context, command CreateOnlin
 	if err != nil {
 		return nil, apperrors.Wrap(apperrors.CodeInternalError, err, "生成在线充值请求指纹失败")
 	}
+	// 幂等回放先于允许范围门禁：同一 request_id 的重试属于既有单，不是新单，
+	// 不因允许范围变更被拒绝；允许范围只拦截会真正新建充值单与支付单的路径。
 	if replay, found, err := s.loadReplay(ctx, command, fingerprint); err != nil || found {
 		return replay, err
 	}
-	account, shop, wallet, config, adapter, err := s.loadCreationFacts(ctx, command)
+	if err := s.policy.IsAllowed(ctx, command.PaymentMethod); err != nil {
+		return nil, err
+	}
+	account, shop, wallet, err := s.loadCreationFacts(ctx, command)
 	if err != nil {
 		return nil, err
 	}
-	result, err := s.createLocalFacts(ctx, command, fingerprint.Value, account, shop, wallet, config)
+	result, config, adapter, err := s.createLocalFacts(ctx, command, fingerprint.Value, account, shop, wallet)
 	if err != nil {
 		if replay, found, replayErr := s.loadReplay(ctx, command, fingerprint); replayErr != nil || found {
 			return replay, replayErr
@@ -124,26 +138,56 @@ func (s *OnlineCreationService) Execute(ctx context.Context, command CreateOnlin
 	return result, nil
 }
 
-// AvailablePaymentMethods 按固定顺序返回配置完整的在线支付方式。
+// AvailablePaymentMethods 按允许范围与可用商户池交集返回在线支付方式。
 func (s *OnlineCreationService) AvailablePaymentMethods(ctx context.Context, userType int) (AvailablePaymentMethodsResult, error) {
 	result := AvailablePaymentMethodsResult{
 		Methods: []string{}, MinAmount: constants.AgentOnlineRechargeMinAmount, MaxAmount: constants.AgentRechargeMaxAmount,
 	}
-	if userType != constants.UserTypeAgent {
-		return result, apperrors.New(apperrors.CodeForbidden, "仅代理账号可以查询在线支付方式")
+	if s == nil || s.db == nil || s.runtime == nil {
+		return result, apperrors.New(apperrors.CodeServiceUnavailable, "代理在线充值能力未配置")
 	}
-	var config model.WechatConfig
-	if err := s.db.WithContext(ctx).Where("is_active = ?", true).First(&config).Error; err != nil {
-		if stderrors.Is(err, gorm.ErrRecordNotFound) {
-			return result, nil
+	if userType != constants.UserTypeAgent && userType != constants.UserTypePlatform {
+		return result, apperrors.New(apperrors.CodeForbidden, "仅代理或平台账号可以查询在线支付方式")
+	}
+	if s.policy == nil {
+		return result, apperrors.New(apperrors.CodeServiceUnavailable, "代理在线充值允许范围策略未配置")
+	}
+	allowed, err := s.policy.AllowedMethods(ctx)
+	if err != nil {
+		return result, err
+	}
+	for _, method := range allowed {
+		var merchants []model.PaymentMerchant
+		err := s.db.WithContext(ctx).
+			Model(&model.PaymentMerchant{}).
+			Joins("JOIN tb_payment_merchant_pool_member AS member ON member.merchant_id = tb_payment_merchant.id AND member.deleted_at IS NULL").
+			Joins("JOIN tb_payment_merchant_pool AS pool ON pool.id = member.pool_id AND pool.deleted_at IS NULL").
+			Where("pool.payment_method = ? AND pool.status = ? AND tb_payment_merchant.payment_method = ? AND tb_payment_merchant.status = ?", method, model.PaymentMerchantStatusEnabled, method, model.PaymentMerchantStatusEnabled).
+			Order("member.sort_order ASC").Find(&merchants).Error
+		if err != nil {
+			return result, apperrors.Wrap(apperrors.CodeDatabaseError, err, "查询代理在线支付商户池失败")
+		}
+		for index := range merchants {
+			// 仅微信直连（v3/v2）商户需要全局授权配置中的 AppID；富友商户不依赖该配置。
+			var authorization *model.WechatAuthorization
+			merchant := &merchants[index]
+			if merchant.ProviderType == model.ProviderTypeWechat || merchant.ProviderType == model.ProviderTypeWechatV2 {
+				var authErr error
+				authorization, authErr = s.runtime.LoadAuthorization(ctx)
+				if authErr != nil {
+					continue
+				}
+			}
+			config, configErr := merchantpayment.MerchantConfig(merchant, authorization)
+			if configErr != nil {
+				continue
+			}
+			adapter := s.adapter(method, config)
+			if adapter != nil && adapter.Available(config) {
+				result.Methods = append(result.Methods, method)
+				break
+			}
 		}
-		return result, apperrors.Wrap(apperrors.CodeDatabaseError, err, "查询生效支付配置失败")
-	}
-	if s.wechat.Available(&config) {
-		result.Methods = append(result.Methods, constants.RechargeMethodWechat)
-	}
-	if s.alipay.Available(&config) {
-		result.Methods = append(result.Methods, constants.RechargeMethodAlipay)
 	}
 	return result, nil
 }
@@ -151,40 +195,29 @@ func (s *OnlineCreationService) AvailablePaymentMethods(ctx context.Context, use
 func (s *OnlineCreationService) loadCreationFacts(
 	ctx context.Context,
 	command CreateOnlineCommand,
-) (*model.Account, *model.Shop, *model.AgentWallet, *model.WechatConfig, OnlinePaymentPort, error) {
+) (*model.Account, *model.Shop, *model.AgentWallet, error) {
 	var account model.Account
 	if err := s.db.WithContext(ctx).Where("id = ? AND user_type = ? AND status = ?", command.AccountID, constants.UserTypeAgent, constants.StatusEnabled).First(&account).Error; err != nil || account.ShopID == nil || *account.ShopID != command.CurrentShopID {
 		if err != nil && !stderrors.Is(err, gorm.ErrRecordNotFound) {
-			return nil, nil, nil, nil, nil, apperrors.Wrap(apperrors.CodeDatabaseError, err, "查询在线充值账号失败")
+			return nil, nil, nil, apperrors.Wrap(apperrors.CodeDatabaseError, err, "查询在线充值账号失败")
 		}
-		return nil, nil, nil, nil, nil, apperrors.New(apperrors.CodeForbidden, "当前代理账号不可为该店铺充值")
+		return nil, nil, nil, apperrors.New(apperrors.CodeForbidden, "当前代理账号不可为该店铺充值")
 	}
 	var shop model.Shop
 	if err := s.db.WithContext(ctx).Where("id = ? AND status = ?", command.CurrentShopID, constants.StatusEnabled).First(&shop).Error; err != nil {
 		if stderrors.Is(err, gorm.ErrRecordNotFound) {
-			return nil, nil, nil, nil, nil, apperrors.New(apperrors.CodeForbidden, "无权限操作该资源或资源不存在")
+			return nil, nil, nil, apperrors.New(apperrors.CodeForbidden, "无权限操作该资源或资源不存在")
 		}
-		return nil, nil, nil, nil, nil, apperrors.Wrap(apperrors.CodeDatabaseError, err, "查询当前店铺失败")
+		return nil, nil, nil, apperrors.Wrap(apperrors.CodeDatabaseError, err, "查询当前店铺失败")
 	}
 	var wallet model.AgentWallet
 	if err := s.db.WithContext(ctx).Where("shop_id = ? AND wallet_type = ? AND status = ?", command.CurrentShopID, constants.AgentWalletTypeMain, constants.AgentWalletStatusNormal).First(&wallet).Error; err != nil {
 		if stderrors.Is(err, gorm.ErrRecordNotFound) {
-			return nil, nil, nil, nil, nil, apperrors.New(apperrors.CodeWalletNotFound, "当前店铺主钱包不存在或不可用")
+			return nil, nil, nil, apperrors.New(apperrors.CodeWalletNotFound, "当前店铺主钱包不存在或不可用")
 		}
-		return nil, nil, nil, nil, nil, apperrors.Wrap(apperrors.CodeDatabaseError, err, "查询当前店铺主钱包失败")
+		return nil, nil, nil, apperrors.Wrap(apperrors.CodeDatabaseError, err, "查询当前店铺主钱包失败")
 	}
-	var config model.WechatConfig
-	if err := s.db.WithContext(ctx).Where("is_active = ?", true).First(&config).Error; err != nil {
-		if stderrors.Is(err, gorm.ErrRecordNotFound) {
-			return nil, nil, nil, nil, nil, apperrors.New(apperrors.CodeNoPaymentConfig)
-		}
-		return nil, nil, nil, nil, nil, apperrors.Wrap(apperrors.CodeDatabaseError, err, "查询生效支付配置失败")
-	}
-	adapter := s.adapter(command.PaymentMethod)
-	if adapter == nil || !adapter.Available(&config) {
-		return nil, nil, nil, nil, nil, apperrors.New(apperrors.CodeNoPaymentConfig)
-	}
-	return &account, &shop, &wallet, &config, adapter, nil
+	return &account, &shop, &wallet, nil
 }
 
 func (s *OnlineCreationService) createLocalFacts(
@@ -194,36 +227,58 @@ func (s *OnlineCreationService) createLocalFacts(
 	account *model.Account,
 	shop *model.Shop,
 	wallet *model.AgentWallet,
-	config *model.WechatConfig,
-) (*CreateOnlineResult, error) {
+) (*CreateOnlineResult, *model.WechatConfig, OnlinePaymentPort, error) {
 	rechargeNo, err := newBusinessNo(constants.AgentRechargeOrderPrefix, time.Now().Format("20060102150405"))
 	if err != nil {
-		return nil, err
+		return nil, nil, nil, err
 	}
 	paymentNo, err := newBusinessNo("PAY", fmt.Sprintf("%d", time.Now().UnixMilli()))
 	if err != nil {
-		return nil, err
-	}
-	expireMinutes := config.AliPayExpireMinutes
-	if expireMinutes <= 0 {
-		expireMinutes = model.DefaultAliPayExpireMinutes
-	}
-	expireAt := time.Now().Add(time.Duration(expireMinutes) * time.Minute)
-	channel, requestID := command.PaymentMethod, command.RequestID
-	record := &model.AgentRechargeRecord{
-		UserID: account.ID, AgentWalletID: wallet.ID, ShopID: shop.ID, RechargeNo: rechargeNo,
-		Amount: command.Amount, PaymentMethod: command.PaymentMethod, PaymentChannel: &channel,
-		PaymentConfigID: &config.ID, Status: constants.RechargeStatusPending,
-		RequestID: &requestID, RequestFingerprint: &fingerprint,
-		ShopIDTag: wallet.ShopIDTag, EnterpriseIDTag: wallet.EnterpriseIDTag,
-	}
-	payment := &model.Payment{
-		PaymentNo: paymentNo, OrderType: model.PaymentOrderTypeAgentRecharge,
-		PaymentMethod: command.PaymentMethod, MerchantIdentity: paymentMerchantIdentity(command.PaymentMethod, config),
-		Amount: command.Amount, Status: model.PaymentRecordStatusPending,
-		PaymentConfigID: &config.ID, ExpireAt: &expireAt,
+		return nil, nil, nil, err
 	}
+	var record *model.AgentRechargeRecord
+	var payment *model.Payment
+	var config *model.WechatConfig
+	var adapter OnlinePaymentPort
 	err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		route, err := s.runtime.SelectForNewPaymentWithTx(ctx, tx, command.PaymentMethod, time.Now())
+		if err != nil {
+			return err
+		}
+		// 仅微信直连（v3/v2）商户需要全局授权配置中的 AppID；富友商户不依赖该配置。
+		var authorization *model.WechatAuthorization
+		if route.Merchant.ProviderType == model.ProviderTypeWechat || route.Merchant.ProviderType == model.ProviderTypeWechatV2 {
+			authorization, err = s.runtime.LoadAuthorization(ctx)
+			if err != nil {
+				return err
+			}
+		}
+		config, err = merchantpayment.MerchantConfig(route.Merchant, authorization)
+		if err != nil {
+			return err
+		}
+		adapter = s.adapter(command.PaymentMethod, config)
+		if adapter == nil || !adapter.Available(config) {
+			return apperrors.New(apperrors.CodeNoPaymentConfig)
+		}
+		expireMinutes := config.AliPayExpireMinutes
+		if expireMinutes <= 0 {
+			expireMinutes = model.DefaultAliPayExpireMinutes
+		}
+		expireAt := time.Now().Add(time.Duration(expireMinutes) * time.Minute)
+		channel, requestID := paymentChannel(command.PaymentMethod, config), command.RequestID
+		record = &model.AgentRechargeRecord{
+			UserID: account.ID, AgentWalletID: wallet.ID, ShopID: shop.ID, RechargeNo: rechargeNo,
+			Amount: command.Amount, PaymentMethod: command.PaymentMethod, PaymentChannel: &channel,
+			Status: constants.RechargeStatusPending, RequestID: &requestID, RequestFingerprint: &fingerprint,
+			ShopIDTag: wallet.ShopIDTag, EnterpriseIDTag: wallet.EnterpriseIDTag,
+		}
+		payment = &model.Payment{
+			PaymentNo: paymentNo, OrderType: model.PaymentOrderTypeAgentRecharge,
+			PaymentMethod: command.PaymentMethod, Amount: command.Amount,
+			Status: model.PaymentRecordStatusPending, ExpireAt: &expireAt,
+		}
+		merchantpayment.FreezeRoute(payment, route)
 		if err := tx.Create(record).Error; err != nil {
 			return err
 		}
@@ -237,9 +292,13 @@ func (s *OnlineCreationService) createLocalFacts(
 		})
 	})
 	if err != nil {
-		return nil, apperrors.Wrap(apperrors.CodeDatabaseError, err, "创建在线充值本地订单失败")
+		var appErr *apperrors.AppError
+		if stderrors.As(err, &appErr) {
+			return nil, nil, nil, err
+		}
+		return nil, nil, nil, apperrors.Wrap(apperrors.CodeDatabaseError, err, "创建在线充值本地订单失败")
 	}
-	return &CreateOnlineResult{Recharge: record, Payment: payment}, nil
+	return &CreateOnlineResult{Recharge: record, Payment: payment}, config, adapter, nil
 }
 
 func paymentMerchantIdentity(paymentMethod string, config *model.WechatConfig) string {
@@ -247,6 +306,9 @@ func paymentMerchantIdentity(paymentMethod string, config *model.WechatConfig) s
 		return ""
 	}
 	if paymentMethod == constants.RechargeMethodWechat {
+		if config.ProviderType == model.ProviderTypeFuiou {
+			return config.FyMchntCd
+		}
 		return config.WxMchID
 	}
 	if paymentMethod == constants.RechargeMethodAlipay {
@@ -255,6 +317,14 @@ func paymentMerchantIdentity(paymentMethod string, config *model.WechatConfig) s
 	return ""
 }
 
+// paymentChannel 返回实际支付渠道：富友配置下微信业务方式落库为 fuiou，其余与业务方式一致。
+func paymentChannel(paymentMethod string, config *model.WechatConfig) string {
+	if paymentMethod == constants.RechargeMethodWechat && config != nil && config.ProviderType == model.ProviderTypeFuiou {
+		return model.ProviderTypeFuiou
+	}
+	return paymentMethod
+}
+
 func (s *OnlineCreationService) loadReplay(
 	ctx context.Context,
 	command CreateOnlineCommand,
@@ -316,8 +386,11 @@ func (s *OnlineCreationService) closeFailedCreation(ctx context.Context, result
 	})
 }
 
-func (s *OnlineCreationService) adapter(paymentMethod string) OnlinePaymentPort {
+func (s *OnlineCreationService) adapter(paymentMethod string, config *model.WechatConfig) OnlinePaymentPort {
 	if paymentMethod == constants.RechargeMethodWechat {
+		if config != nil && config.ProviderType == model.ProviderTypeFuiou {
+			return s.fuiou
+		}
 		return s.wechat
 	}
 	if paymentMethod == constants.RechargeMethodAlipay {

internal/application/agentrecharge/online_payment_policy.go

@@ -0,0 +1,58 @@
+package agentrecharge
+
+import (
+	"context"
+
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	apperrors "github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// OnlinePaymentMethodConfigReader 提供代理在线自充允许范围的严格读取能力。
+type OnlinePaymentMethodConfigReader interface {
+	GetStrict(ctx context.Context, key string) (string, error)
+}
+
+// OnlinePaymentMethodPolicy 将受控配置值映射为对外可见的线上支付方式集合。
+type OnlinePaymentMethodPolicy struct {
+	reader OnlinePaymentMethodConfigReader
+}
+
+// NewOnlinePaymentMethodPolicy 创建代理在线自充允许范围策略。
+func NewOnlinePaymentMethodPolicy(reader OnlinePaymentMethodConfigReader) *OnlinePaymentMethodPolicy {
+	return &OnlinePaymentMethodPolicy{reader: reader}
+}
+
+// AllowedMethods 严格读取允许范围；配置缺失使用注册默认值，非法值失败关闭。
+func (p *OnlinePaymentMethodPolicy) AllowedMethods(ctx context.Context) ([]string, error) {
+	if p == nil || p.reader == nil {
+		return nil, apperrors.New(apperrors.CodeServiceUnavailable, "代理在线充值允许范围未配置")
+	}
+	value, err := p.reader.GetStrict(ctx, constants.SystemConfigAgentSelfRechargeAllowedMethods)
+	if err != nil {
+		return nil, apperrors.Wrap(apperrors.CodeNoPaymentConfig, err, "读取代理在线充值允许范围失败")
+	}
+	switch value {
+	case constants.AgentSelfRechargeAllowedWechatOnly:
+		return []string{constants.RechargeMethodWechat}, nil
+	case constants.AgentSelfRechargeAllowedAlipayOnly:
+		return []string{constants.RechargeMethodAlipay}, nil
+	case constants.AgentSelfRechargeAllowedBoth:
+		return []string{constants.RechargeMethodWechat, constants.RechargeMethodAlipay}, nil
+	default:
+		return nil, apperrors.New(apperrors.CodeNoPaymentConfig, "代理在线充值允许范围值非法")
+	}
+}
+
+// IsAllowed 判断业务支付方式是否在当前受控允许范围内。
+func (p *OnlinePaymentMethodPolicy) IsAllowed(ctx context.Context, method string) error {
+	methods, err := p.AllowedMethods(ctx)
+	if err != nil {
+		return err
+	}
+	for _, allowed := range methods {
+		if allowed == method {
+			return nil
+		}
+	}
+	return apperrors.New(apperrors.CodeNoPaymentConfig, "当前支付方式不在代理在线充值允许范围内")
+}

internal/application/agentrecharge/payment_voucher_ocr.go

@@ -0,0 +1,109 @@
+package agentrecharge
+
+import (
+	"context"
+	"encoding/base64"
+	"io"
+	"net/http"
+	"strings"
+
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	apperrors "github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/storage"
+)
+
+// PaymentVoucherObjectStore 提供付款凭证附件的元数据与内容读取能力。
+type PaymentVoucherObjectStore interface {
+	Stat(ctx context.Context, key string) (*storage.ObjectMetadata, error)
+	Download(ctx context.Context, key string) (io.ReadCloser, error)
+}
+
+// PaymentVoucherRecognizer 是付款凭证识别的外部能力接缝，只暴露支付单号。
+type PaymentVoucherRecognizer interface {
+	ExtractPaymentVoucherOrderNumber(ctx context.Context, imageBase64 string) (string, error)
+}
+
+// PaymentVoucherRecognitionResult 是识别结果中本系统消费的唯一字段。
+type PaymentVoucherRecognitionResult struct {
+	// ExternalTransactionNo 是识别出的支付单号，仅作交易流水号表单预填值。
+	ExternalTransactionNo string
+}
+
+// PaymentVoucherOCRService 按附件对象键识别付款凭证，只返回交易流水号预填值。
+// 识别不创建申请、不写入任何资金事实字段；其余识别字段一律不返回、不落库。
+//
+// ENG-AUDIT-001 事实决定：识别调用不产生状态变更、不涉及资金与权限，因此
+// 不写 Audit Event、Domain Ledger、Integration Log 与 Outbox；调用记录由 Access Log 与
+// Gateway 客户端的路径级日志承载，识别载荷与原始结果不进入任何一类事实。
+type PaymentVoucherOCRService struct {
+	objects    PaymentVoucherObjectStore
+	recognizer PaymentVoucherRecognizer
+}
+
+// NewPaymentVoucherOCRService 创建付款凭证识别用例。
+func NewPaymentVoucherOCRService(objects PaymentVoucherObjectStore, recognizer PaymentVoucherRecognizer) *PaymentVoucherOCRService {
+	return &PaymentVoucherOCRService{objects: objects, recognizer: recognizer}
+}
+
+// Recognize 校验附件为图片后调用识别能力，只返回交易流水号预填值。
+// 非图片、对象不存在、内容为空或识别失败都返回明确失败，不阻断人工填写。
+func (s *PaymentVoucherOCRService) Recognize(ctx context.Context, objectKey string) (*PaymentVoucherRecognitionResult, error) {
+	if s == nil || s.objects == nil || s.recognizer == nil {
+		return nil, apperrors.New(apperrors.CodeServiceUnavailable, "付款凭证识别能力未配置")
+	}
+	key := strings.TrimSpace(objectKey)
+	if key == "" || len([]rune(key)) > constants.AgentRechargeVoucherKeyMaxLength {
+		return nil, apperrors.New(apperrors.CodeInvalidParam, "付款凭证对象键无效")
+	}
+	metadata, err := s.objects.Stat(ctx, key)
+	if err != nil {
+		return nil, apperrors.Wrap(apperrors.CodeInvalidParam, err, "付款凭证对象不存在或不可读")
+	}
+	if metadata == nil || metadata.Size <= 0 {
+		return nil, apperrors.New(apperrors.CodeInvalidParam, "付款凭证对象内容为空")
+	}
+	if metadata.Size > constants.AgentRechargeVoucherMaxBytes {
+		return nil, apperrors.New(apperrors.CodeInvalidParam, "付款凭证图片超过允许大小")
+	}
+	reader, err := s.objects.Download(ctx, key)
+	if err != nil {
+		return nil, apperrors.Wrap(apperrors.CodeInvalidParam, err, "读取付款凭证对象失败")
+	}
+	defer func() { _ = reader.Close() }()
+	content, err := io.ReadAll(io.LimitReader(reader, constants.AgentRechargeVoucherMaxBytes+1))
+	if err != nil {
+		return nil, apperrors.Wrap(apperrors.CodeInvalidParam, err, "读取付款凭证内容失败")
+	}
+	if int64(len(content)) > constants.AgentRechargeVoucherMaxBytes {
+		return nil, apperrors.New(apperrors.CodeInvalidParam, "付款凭证图片超过允许大小")
+	}
+	if len(content) == 0 {
+		return nil, apperrors.New(apperrors.CodeInvalidParam, "付款凭证对象内容为空")
+	}
+	if !isPaymentVoucherImage(metadata.ContentType, content) {
+		return nil, apperrors.New(apperrors.CodeInvalidParam, "付款凭证必须是图片文件")
+	}
+	// base64 编码只存在于本次调用内存中，禁止写入日志、审计或错误信息。
+	orderNumber, err := s.recognizer.ExtractPaymentVoucherOrderNumber(ctx, base64.StdEncoding.EncodeToString(content))
+	if err != nil {
+		return nil, err
+	}
+	if strings.TrimSpace(orderNumber) == "" {
+		return nil, apperrors.New(apperrors.CodeGatewayInvalidResp, "未从付款凭证中识别出交易流水号")
+	}
+	return &PaymentVoucherRecognitionResult{ExternalTransactionNo: strings.TrimSpace(orderNumber)}, nil
+}
+
+// isPaymentVoucherImage 校验对象声明的类型为图片，并用内容嗅探拦截被改名的非图片文件。
+// 嗅探结果为空或 application/octet-stream 表示未知容器（如 webp），交由识别服务判定；
+// 明确识别为其他类型的（PDF、压缩包、文本等）直接拒绝。
+func isPaymentVoucherImage(declaredContentType string, content []byte) bool {
+	if !strings.HasPrefix(strings.ToLower(strings.TrimSpace(declaredContentType)), "image/") {
+		return false
+	}
+	sniffed := strings.ToLower(strings.TrimSpace(http.DetectContentType(content)))
+	if sniffed == "" || sniffed == "application/octet-stream" || strings.HasPrefix(sniffed, "image/") {
+		return true
+	}
+	return false
+}

internal/application/agentrecharge/recover_online_payment.go

@@ -6,6 +6,7 @@ import (
 
 	"gorm.io/gorm"
 
+	merchantpayment "github.com/break/junhong_cmp_fiber/internal/application/merchantpayment"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
@@ -14,21 +15,23 @@ import (
 // RecoverOnlinePaymentService 批量收敛长期缺少支付链接或待支付的代理在线充值。
 type RecoverOnlinePaymentService struct {
 	db      *gorm.DB
+	runtime *merchantpayment.RuntimeLoader
 	wechat  OnlinePaymentPort
 	alipay  OnlinePaymentPort
+	fuiou   OnlinePaymentPort
 	confirm *ConfirmOnlinePaymentService
 	audit   PaymentAuditWriter
 	now     func() time.Time
 }
 
 // NewRecoverOnlinePaymentService 创建代理在线充值支付恢复用例。
-func NewRecoverOnlinePaymentService(db *gorm.DB, wechat, alipay OnlinePaymentPort, confirm *ConfirmOnlinePaymentService, audit PaymentAuditWriter) *RecoverOnlinePaymentService {
-	return &RecoverOnlinePaymentService{db: db, wechat: wechat, alipay: alipay, confirm: confirm, audit: audit, now: time.Now}
+func NewRecoverOnlinePaymentService(db *gorm.DB, runtime *merchantpayment.RuntimeLoader, wechat, alipay, fuiou OnlinePaymentPort, confirm *ConfirmOnlinePaymentService, audit PaymentAuditWriter) *RecoverOnlinePaymentService {
+	return &RecoverOnlinePaymentService{db: db, runtime: runtime, wechat: wechat, alipay: alipay, fuiou: fuiou, confirm: confirm, audit: audit, now: time.Now}
 }
 
 // ProcessBatch 按固定批次读取本地待处理事实并调用对应渠道收敛状态。
 func (s *RecoverOnlinePaymentService) ProcessBatch(ctx context.Context) (int, error) {
-	if s == nil || s.db == nil || s.wechat == nil || s.alipay == nil || s.confirm == nil || s.audit == nil {
+	if s == nil || s.db == nil || s.runtime == nil || s.wechat == nil || s.alipay == nil || s.fuiou == nil || s.confirm == nil || s.audit == nil {
 		return 0, errors.New(errors.CodeServiceUnavailable, "代理在线充值支付恢复能力未配置")
 	}
 	now := s.now().UTC()
@@ -51,7 +54,13 @@ func (s *RecoverOnlinePaymentService) ProcessBatch(ctx context.Context) (int, er
 	for index := range payments {
 		payment := &payments[index]
 		recharge := recharges[payment.OrderID]
-		config := recoveryConfig(payment, configs)
+		config, configErr := s.recoveryConfig(ctx, payment, configs)
+		if configErr != nil {
+			if firstErr == nil {
+				firstErr = configErr
+			}
+			continue
+		}
 		if recharge == nil || config == nil {
 			if firstErr == nil {
 				firstErr = errors.New(errors.CodeConflict, "待恢复支付单缺少充值单或创建配置")
@@ -70,7 +79,7 @@ func (s *RecoverOnlinePaymentService) ProcessBatch(ctx context.Context) (int, er
 }
 
 func (s *RecoverOnlinePaymentService) recoverOne(ctx context.Context, payment *model.Payment, recharge *model.AgentRechargeRecord, config *model.WechatConfig, now time.Time) error {
-	adapter := s.adapter(payment.PaymentMethod)
+	adapter := s.adapter(payment.PaymentMethod, config)
 	if adapter == nil {
 		return errors.New(errors.CodeNoPaymentConfig, "代理充值创建时支付配置不可用")
 	}
@@ -140,7 +149,7 @@ func (s *RecoverOnlinePaymentService) loadRecoveryFacts(ctx context.Context, pay
 	configIDs := make([]uint, 0, len(payments))
 	for index := range payments {
 		rechargeIDs = append(rechargeIDs, payments[index].OrderID)
-		if payments[index].PaymentConfigID != nil {
+		if payments[index].MerchantID == nil && payments[index].PaymentConfigID != nil {
 			configIDs = append(configIDs, *payments[index].PaymentConfigID)
 		}
 	}
@@ -150,8 +159,10 @@ func (s *RecoverOnlinePaymentService) loadRecoveryFacts(ctx context.Context, pay
 	}
 	var configRows []model.WechatConfig
 	if len(configIDs) > 0 {
-		if err := s.db.WithContext(ctx).Where("id IN ?", configIDs).Find(&configRows).Error; err != nil {
-			return nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "批量查询代理充值创建配置失败")
+		// merchant_id 为空仅为留存期内历史支付；独立 Change 删除旧路径前，
+		// 必须按其 payment_config_id 读取，包括已软删除的原始配置。
+		if err := s.db.WithContext(ctx).Unscoped().Where("id IN ?", configIDs).Find(&configRows).Error; err != nil {
+			return nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "批量查询代理充值历史配置失败")
 		}
 	}
 	recharges := make(map[uint]*model.AgentRechargeRecord, len(rechargeRows))
@@ -165,11 +176,27 @@ func (s *RecoverOnlinePaymentService) loadRecoveryFacts(ctx context.Context, pay
 	return recharges, configs, nil
 }
 
-func recoveryConfig(payment *model.Payment, configs map[uint]*model.WechatConfig) *model.WechatConfig {
-	if payment.PaymentConfigID == nil {
-		return nil
+// recoveryConfig 对冻结商户支付单按当前凭证版本加载；历史支付单保持 payment_config_id 路径。
+func (s *RecoverOnlinePaymentService) recoveryConfig(ctx context.Context, payment *model.Payment, configs map[uint]*model.WechatConfig) (*model.WechatConfig, error) {
+	if payment.MerchantID != nil {
+		merchant, err := s.runtime.LoadMerchant(ctx, *payment.MerchantID)
+		if err != nil {
+			return nil, err
+		}
+		// 仅微信直连（v3/v2）商户需要全局授权配置中的 AppID；富友商户不依赖该配置。
+		var authorization *model.WechatAuthorization
+		if merchant.ProviderType == model.ProviderTypeWechat || merchant.ProviderType == model.ProviderTypeWechatV2 {
+			authorization, err = s.runtime.LoadAuthorization(ctx)
+			if err != nil {
+				return nil, err
+			}
+		}
+		return merchantpayment.MerchantConfig(merchant, authorization)
 	}
-	return configs[*payment.PaymentConfigID]
+	if payment.PaymentConfigID == nil {
+		return nil, nil
+	}
+	return configs[*payment.PaymentConfigID], nil
 }
 
 func (s *RecoverOnlinePaymentService) closePending(ctx context.Context, payment *model.Payment, recharge *model.AgentRechargeRecord) error {
@@ -200,8 +227,11 @@ func (s *RecoverOnlinePaymentService) closePending(ctx context.Context, payment
 	})
 }
 
-func (s *RecoverOnlinePaymentService) adapter(paymentMethod string) OnlinePaymentPort {
+func (s *RecoverOnlinePaymentService) adapter(paymentMethod string, config *model.WechatConfig) OnlinePaymentPort {
 	if paymentMethod == constants.RechargeMethodWechat {
+		if config != nil && config.ProviderType == model.ProviderTypeFuiou {
+			return s.fuiou
+		}
 		return s.wechat
 	}
 	if paymentMethod == constants.RechargeMethodAlipay {

internal/application/auditarchive/integration.go

@@ -57,26 +57,9 @@ func (s *Service) ArchiveIntegrationDate(ctx context.Context, archiveDate time.T
 	return s.archiveIntegrationDate(ctx, archiveDate, false)
 }
 
-// FinalizePreviousIntegrationMonth 复核并终结上一个完整自然月的 Integration Log 归档。
-func (s *Service) FinalizePreviousIntegrationMonth(ctx context.Context) error {
-	now := time.Now().In(s.location)
-	return s.FinalizeIntegrationMonth(ctx, now.AddDate(0, -1, 0))
-}
-
-// FinalizeIntegrationMonth 逐日复核指定完整自然月，并为变化内容创建最终 revision。
-func (s *Service) FinalizeIntegrationMonth(ctx context.Context, month time.Time) error {
-	monthStart := time.Date(month.In(s.location).Year(), month.In(s.location).Month(), 1, 0, 0, 0, 0, s.location)
-	currentMonth := time.Now().In(s.location)
-	currentMonthStart := time.Date(currentMonth.Year(), currentMonth.Month(), 1, 0, 0, 0, 0, s.location)
-	if !monthStart.Before(currentMonthStart) {
-		return fmt.Errorf("只能终结已经结束的 Integration Log 完整自然月")
-	}
-	for date := monthStart; date.Before(monthStart.AddDate(0, 1, 0)); date = date.AddDate(0, 0, 1) {
-		if err := s.archiveIntegrationDate(ctx, date, true); err != nil {
-			return fmt.Errorf("终结 %s Integration Log 归档失败: %w", date.Format(time.DateOnly), err)
-		}
-	}
-	return nil
+// FinalizeIntegrationDate 为指定已结束自然日形成 Integration Log 最终归档版本。
+func (s *Service) FinalizeIntegrationDate(ctx context.Context, archiveDate time.Time) error {
+	return s.archiveIntegrationDate(ctx, archiveDate, true)
 }
 
 func (s *Service) archiveIntegrationDate(ctx context.Context, archiveDate time.Time, final bool) error {
@@ -94,22 +77,20 @@ func (s *Service) archiveIntegrationDate(ctx context.Context, archiveDate time.T
 	if err != nil {
 		return err
 	}
+	if final && run.Status == constants.ArchiveStatusSuccess && run.IsFinal && run.CleanedAt != nil {
+		terminalCount, countErr := s.integrationTerminalCount(ctx, start, end)
+		if countErr != nil {
+			return countErr
+		}
+		if terminalCount == 0 {
+			return nil
+		}
+	}
 	file, err := s.buildIntegrationArchiveFile(ctx, start, end)
 	if err != nil {
 		return err
 	}
 	defer os.Remove(file.path)
-	if final {
-		pending, pendingErr := s.integrationPendingCount(ctx, start, end)
-		if pendingErr != nil {
-			return pendingErr
-		}
-		if pending > 0 {
-			_ = s.db.WithContext(ctx).Model(&model.LogArchiveRun{}).Where("id = ?", run.ID).
-				Updates(map[string]any{"is_final": false, "error_summary": "存在 pending Integration Log，无法形成最终归档", "updated_at": time.Now()}).Error
-			return fmt.Errorf("仍有 %d 条 pending Integration Log，无法形成最终归档", pending)
-		}
-	}
 	if run.Status == constants.ArchiveStatusSuccess && run.RecordCount == file.recordCount && run.SHA256 == file.sha256 {
 		valid, validateErr := s.validateIntegrationRun(ctx, run)
 		if validateErr == nil && valid && (!final || run.IsFinal) {
@@ -165,7 +146,8 @@ func (s *Service) acquireIntegrationRun(ctx context.Context, run *model.LogArchi
 		Where("id = ? AND (status <> ? OR updated_at < ?)", run.ID, constants.ArchiveStatusRunning, now.Add(-3*time.Hour)).
 		Updates(map[string]any{
 			"status": constants.ArchiveStatusRunning, "revision": revision, "is_final": false,
-			"attempt_count": gorm.Expr("attempt_count + 1"), "error_summary": "", "completed_at": nil, "updated_at": now,
+			"attempt_count": gorm.Expr("attempt_count + 1"), "error_summary": "", "completed_at": nil,
+			"cleanup_started_at": nil, "cleaned_at": nil, "updated_at": now,
 		})
 	if result.Error != nil {
 		return false, fmt.Errorf("锁定 Integration Log 归档任务失败: %w", result.Error)
@@ -320,16 +302,6 @@ func (s *Service) integrationRecordCount(ctx context.Context, start, end time.Ti
 	return count, nil
 }
 
-func (s *Service) integrationPendingCount(ctx context.Context, start, end time.Time) (int64, error) {
-	var count int64
-	if err := s.db.WithContext(ctx).Model(&model.IntegrationLog{}).
-		Where("created_at >= ? AND created_at < ? AND result = ?", start, end, constants.IntegrationResultPending).
-		Count(&count).Error; err != nil {
-		return 0, fmt.Errorf("统计 pending Integration Log 失败: %w", err)
-	}
-	return count, nil
-}
-
 func integrationObjectKeys(date time.Time, revision int) (string, string) {
 	prefix := fmt.Sprintf("audit-archive/v1/%04d/%02d/%02d", date.Year(), date.Month(), date.Day())
 	name := fmt.Sprintf("integration-logs-%s-r%d", date.Format(time.DateOnly), revision)

internal/application/auditarchive/retention.go

@@ -7,11 +7,9 @@ import (
 	"io"
 	"os"
 	"strconv"
-	"strings"
 	"time"
 
 	"github.com/bytedance/sonic"
-	"gorm.io/gorm"
 
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
@@ -19,25 +17,18 @@ import (
 
 const maxManifestBytes = 1024 * 1024
 
-// RetentionAudit 描述月度物理清理的统一审计事实。
+// RetentionAudit 保留系统审计 Writer 的输入兼容类型。
 type RetentionAudit struct {
-	EventID          string
-	Month            string
-	Summary          string
-	Result           string
-	ErrorSummary     string
-	RangeStart       time.Time
-	RangeEnd         time.Time
-	EventCount       int64
-	ResourceCount    int64
-	IntegrationCount int64
-	ManifestKeys     []string
-	DurationMS       int64
+	EventID, Month, Summary, Result, ErrorSummary string
+	RangeStart, RangeEnd                          time.Time
+	EventCount, ResourceCount, IntegrationCount   int64
+	ManifestKeys                                  []string
+	DurationMS                                    int64
 }
 
-// RetentionResult 是月度留存清理的结构化执行结果。
+// RetentionResult 是单日留存处理结果。
 type RetentionResult struct {
-	Month            string
+	ArchiveDate      string
 	EventCount       int64
 	ResourceCount    int64
 	IntegrationCount int64
@@ -46,191 +37,150 @@ type RetentionResult struct {
 	Duration         time.Duration
 }
 
-type retentionRuns struct {
-	audit       []*model.LogArchiveRun
-	integration []*model.LogArchiveRun
+// RetentionBlockedError 描述阻断日期推进的安全上下文。
+type RetentionBlockedError struct {
+	ArchiveDate string
+	Source      string
+	Err         error
 }
 
-// CleanupPreviousMonth 校验并物理清理上一个完整自然月的在线审计日志。
-func (s *Service) CleanupPreviousMonth(ctx context.Context) (RetentionResult, error) {
-	now := time.Now().In(s.location)
-	return s.CleanupMonth(ctx, now.AddDate(0, -1, 0))
+func (e *RetentionBlockedError) Error() string {
+	return e.ArchiveDate + " " + e.Source + ": " + e.Err.Error()
 }
+func (e *RetentionBlockedError) Unwrap() error { return e.Err }
 
-// ValidatePreviousMonth 只读校验上一个完整自然月的归档与清理门禁。
-func (s *Service) ValidatePreviousMonth(ctx context.Context) (RetentionResult, error) {
-	now := time.Now().In(s.location)
-	return s.ValidateMonth(ctx, now.AddDate(0, -1, 0))
-}
-
-// ValidateMonth 只读校验指定完整自然月，不写清理断点且不删除在线数据。
-func (s *Service) ValidateMonth(ctx context.Context, month time.Time) (result RetentionResult, err error) {
+// RetainPendingDays 每次最多处理一个最早待处理的上海自然日，避免单任务跨历史日期长时间占用数据库。
+func (s *Service) RetainPendingDays(ctx context.Context, cleanup bool) ([]RetentionResult, error) {
 	if s.db == nil || s.store == nil {
-		return result, fmt.Errorf("日志留存演练数据库或对象存储未配置")
+		return nil, fmt.Errorf("日志日留存数据库或对象存储未配置")
 	}
-	start, end, err := s.retentionMonthRange(month)
+	start, end, err := s.pendingRetentionRange(ctx)
 	if err != nil {
-		return result, err
+		return nil, err
 	}
+	if !start.Before(end) {
+		return nil, nil
+	}
+	result, err := s.retainDate(ctx, start, cleanup)
+	if err != nil {
+		return nil, &RetentionBlockedError{ArchiveDate: start.Format(time.DateOnly), Source: constants.AuditArchiveSource, Err: err}
+	}
+	return []RetentionResult{result}, nil
+}
+
+// RetainDate 校验并按需清理指定已结束自然日，供受控演练使用。
+func (s *Service) RetainDate(ctx context.Context, date time.Time, cleanup bool) (RetentionResult, error) {
+	return s.retainDate(ctx, date, cleanup)
+}
+
+func (s *Service) pendingRetentionRange(ctx context.Context) (time.Time, time.Time, error) {
+	today := time.Now().In(s.location)
+	end := time.Date(today.Year(), today.Month(), today.Day(), 0, 0, 0, 0, s.location)
+	var earliest *time.Time
+	for _, item := range []struct{ table, column, condition string }{
+		{"tb_audit_event", "created_at", ""},
+		{"tb_integration_log", "created_at", "result <> 'pending'"},
+	} {
+		query := s.db.WithContext(ctx).Table(item.table).Select("MIN(" + item.column + ")")
+		if item.condition != "" {
+			query = query.Where(item.condition)
+		}
+		var value *time.Time
+		if err := query.Scan(&value).Error; err != nil {
+			return time.Time{}, time.Time{}, fmt.Errorf("查询日留存起点失败: %w", err)
+		}
+		if value != nil && (earliest == nil || value.Before(*earliest)) {
+			local := value.In(s.location)
+			earliest = &local
+		}
+	}
+	if earliest == nil {
+		return end, end, nil
+	}
+	start := time.Date(earliest.Year(), earliest.Month(), earliest.Day(), 0, 0, 0, 0, s.location)
+	return start, end, nil
+}
+
+func (s *Service) retainDate(ctx context.Context, date time.Time, cleanup bool) (RetentionResult, error) {
 	startedAt := time.Now()
-	result.Month = start.Format("2006-01")
-	runs, err := s.loadRetentionRuns(ctx, start, end)
+	auditResult, err := s.retainAuditDate(ctx, date, cleanup)
 	if err != nil {
-		return result, err
+		return RetentionResult{}, err
 	}
-	if err := s.validateRetentionRuns(ctx, start, end, runs); err != nil {
-		return result, err
+	integrationResult, err := s.retainIntegrationDate(ctx, date, cleanup)
+	if err != nil {
+		return RetentionResult{}, err
 	}
-	summarizeRetentionRuns(runs, &result)
+	result := RetentionResult{ArchiveDate: date.Format(time.DateOnly), EventCount: auditResult.EventCount, ResourceCount: auditResult.ResourceCount, IntegrationCount: integrationResult.IntegrationCount, ManifestKeys: append(auditResult.ManifestKeys, integrationResult.ManifestKeys...)}
 	result.EstimatedBatches = estimatedRetentionBatches(result)
 	result.Duration = time.Since(startedAt)
 	return result, nil
 }
 
-// CleanupMonth 校验归档硬门禁后按固定顺序物理清理指定完整自然月。
-func (s *Service) CleanupMonth(ctx context.Context, month time.Time) (result RetentionResult, cleanupErr error) {
-	if s.db == nil || s.store == nil || s.audit == nil {
-		return result, fmt.Errorf("日志留存清理数据库、对象存储或审计 Writer 未配置")
-	}
-	start, end, err := s.retentionMonthRange(month)
+func (s *Service) retainAuditDate(ctx context.Context, date time.Time, cleanup bool) (RetentionResult, error) {
+	run, err := s.retentionRun(ctx, date, constants.AuditArchiveSource)
 	if err != nil {
-		return result, err
+		return RetentionResult{}, err
 	}
-	startedAt := time.Now()
-	result.Month = start.Format("2006-01")
-	cleanupErr = s.executeRetention(ctx, start, end, &result)
-	result.Duration = time.Since(startedAt)
-	if auditErr := s.recordRetentionAudit(ctx, start, end, result, cleanupErr); auditErr != nil {
-		if cleanupErr != nil {
-			return result, fmt.Errorf("%w；记录留存清理失败审计失败: %v", cleanupErr, auditErr)
+	if run == nil || run.Status != constants.ArchiveStatusSuccess {
+		if err := s.ArchiveDate(ctx, date); err != nil {
+			return RetentionResult{}, fmt.Errorf("Audit 归档失败: %w", err)
+		}
+		run, err = s.retentionRun(ctx, date, constants.AuditArchiveSource)
+		if err != nil {
+			return RetentionResult{}, err
 		}
-		return result, fmt.Errorf("记录留存清理成功审计失败: %w", auditErr)
 	}
-	return result, cleanupErr
+	if err := s.validateAuditRetentionDay(ctx, date, run); err != nil {
+		return RetentionResult{}, fmt.Errorf("Audit 完整性校验失败: %w", err)
+	}
+	result := RetentionResult{ArchiveDate: date.Format(time.DateOnly), EventCount: run.EventCount, ResourceCount: run.ResourceCount, ManifestKeys: []string{run.ManifestKey}}
+	if cleanup {
+		if err := s.cleanupAuditDate(ctx, date, run); err != nil {
+			return result, err
+		}
+	}
+	return result, nil
 }
 
-func (s *Service) retentionMonthRange(month time.Time) (time.Time, time.Time, error) {
-	start := time.Date(month.In(s.location).Year(), month.In(s.location).Month(), 1, 0, 0, 0, 0, s.location)
-	end := start.AddDate(0, 1, 0)
-	now := time.Now().In(s.location)
-	currentMonth := time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, s.location)
-	if !end.Before(currentMonth) && !end.Equal(currentMonth) {
-		return time.Time{}, time.Time{}, fmt.Errorf("只能清理已经结束的完整自然月")
-	}
-	return start, end, nil
-}
-
-func (s *Service) executeRetention(ctx context.Context, start, end time.Time, result *RetentionResult) error {
-	started, err := s.retentionCleanupStarted(ctx, start, end)
+func (s *Service) retainIntegrationDate(ctx context.Context, date time.Time, cleanup bool) (RetentionResult, error) {
+	run, err := s.retentionRun(ctx, date, constants.IntegrationArchiveSource)
 	if err != nil {
-		return err
+		return RetentionResult{}, err
 	}
-	if !started {
-		lastDay := end.AddDate(0, 0, -1)
-		if err := s.ArchiveDate(ctx, lastDay); err != nil {
-			return fmt.Errorf("完成上月最后一天 Audit 归档失败: %w", err)
-		}
-		if err := s.ArchiveIntegrationDate(ctx, lastDay); err != nil {
-			return fmt.Errorf("完成上月最后一天 Integration Log 归档失败: %w", err)
-		}
-		if err := s.FinalizeIntegrationMonth(ctx, start); err != nil {
-			return err
+	if run == nil || run.Status != constants.ArchiveStatusSuccess {
+		if err := s.ArchiveIntegrationDate(ctx, date); err != nil {
+			return RetentionResult{}, fmt.Errorf("Integration Log 归档失败: %w", err)
 		}
 	}
-	runs, err := s.loadRetentionRuns(ctx, start, end)
+	if err := s.FinalizeIntegrationDate(ctx, date); err != nil {
+		return RetentionResult{}, fmt.Errorf("Integration Log 最终归档失败: %w", err)
+	}
+	run, err = s.retentionRun(ctx, date, constants.IntegrationArchiveSource)
 	if err != nil {
-		return err
+		return RetentionResult{}, err
 	}
-	if err := s.validateRetentionRuns(ctx, start, end, runs); err != nil {
-		return err
+	if err := s.validateIntegrationRetentionDay(ctx, date, run); err != nil {
+		return RetentionResult{}, fmt.Errorf("Integration Log 完整性校验失败: %w", err)
 	}
-	summarizeRetentionRuns(runs, result)
-	if err := s.cleanupAuditMonth(ctx, start, end, runs.audit); err != nil {
-		return err
+	result := RetentionResult{ArchiveDate: date.Format(time.DateOnly), IntegrationCount: run.RecordCount, ManifestKeys: []string{run.ManifestKey}}
+	if cleanup {
+		if err := s.cleanupIntegrationDate(ctx, date, run); err != nil {
+			return result, err
+		}
 	}
-	return s.cleanupIntegrationMonth(ctx, start, end, runs.integration)
+	return result, nil
 }
 
-func (s *Service) retentionCleanupStarted(ctx context.Context, start, end time.Time) (bool, error) {
-	var count int64
-	err := s.db.WithContext(ctx).Model(&model.LogArchiveRun{}).
-		Where("archive_date >= ? AND archive_date < ? AND instance_id = ? AND cleanup_started_at IS NOT NULL",
-			start.Format(time.DateOnly), end.Format(time.DateOnly), s.instanceID).
-		Count(&count).Error
-	if err != nil {
-		return false, fmt.Errorf("读取月度清理断点失败: %w", err)
+func (s *Service) retentionRun(ctx context.Context, date time.Time, source string) (*model.LogArchiveRun, error) {
+	var runs []model.LogArchiveRun
+	if err := s.db.WithContext(ctx).Where("source = ? AND archive_date = ? AND instance_id = ?", source, date.Format(time.DateOnly), s.instanceID).Find(&runs).Error; err != nil {
+		return nil, fmt.Errorf("读取日归档账本失败: %w", err)
 	}
-	return count > 0, nil
-}
-
-func (s *Service) loadRetentionRuns(ctx context.Context, start, end time.Time) (retentionRuns, error) {
-	var rows []model.LogArchiveRun
-	err := s.db.WithContext(ctx).Where(
-		"source IN ? AND archive_date >= ? AND archive_date < ? AND instance_id = ?",
-		[]string{constants.AuditArchiveSource, constants.IntegrationArchiveSource}, start.Format(time.DateOnly), end.Format(time.DateOnly), s.instanceID,
-	).Order("archive_date ASC, source ASC").Find(&rows).Error
-	if err != nil {
-		return retentionRuns{}, fmt.Errorf("读取月度归档账本失败: %w", err)
+	if len(runs) == 0 {
+		return nil, nil
 	}
-	days := int(end.Sub(start).Hours() / 24)
-	if len(rows) != days*2 {
-		return retentionRuns{}, fmt.Errorf("月度归档账本缺日：期望 %d 条，实际 %d 条", days*2, len(rows))
-	}
-	runs := retentionRuns{audit: make([]*model.LogArchiveRun, 0, days), integration: make([]*model.LogArchiveRun, 0, days)}
-	for index := range rows {
-		run := &rows[index]
-		switch run.Source {
-		case constants.AuditArchiveSource:
-			runs.audit = append(runs.audit, run)
-		case constants.IntegrationArchiveSource:
-			runs.integration = append(runs.integration, run)
-		}
-	}
-	if len(runs.audit) != days || len(runs.integration) != days {
-		return retentionRuns{}, fmt.Errorf("月度 Audit 或 Integration 归档账本不完整")
-	}
-	return runs, nil
-}
-
-func (s *Service) validateRetentionRuns(ctx context.Context, start, end time.Time, runs retentionRuns) error {
-	if err := validateCleanupLedgerState(runs.audit); err != nil {
-		return fmt.Errorf("Audit 清理断点非法: %w", err)
-	}
-	if err := validateCleanupLedgerState(runs.integration); err != nil {
-		return fmt.Errorf("Integration 清理断点非法: %w", err)
-	}
-	for index := range runs.audit {
-		date := start.AddDate(0, 0, index)
-		if err := s.validateAuditRetentionDay(ctx, date, runs.audit[index]); err != nil {
-			return fmt.Errorf("%s Audit 清理门禁失败: %w", date.Format(time.DateOnly), err)
-		}
-		if err := s.validateIntegrationRetentionDay(ctx, date, runs.integration[index]); err != nil {
-			return fmt.Errorf("%s Integration 清理门禁失败: %w", date.Format(time.DateOnly), err)
-		}
-	}
-	return nil
-}
-
-func validateCleanupLedgerState(runs []*model.LogArchiveRun) error {
-	started, cleaned := 0, 0
-	for _, run := range runs {
-		if run.CleanupStartedAt != nil {
-			started++
-		}
-		if run.CleanedAt != nil {
-			cleaned++
-		}
-	}
-	if started != 0 && started != len(runs) {
-		return fmt.Errorf("清理开始断点不是整月原子状态")
-	}
-	if cleaned != 0 && cleaned != len(runs) {
-		return fmt.Errorf("清理完成断点不是整月原子状态")
-	}
-	if cleaned > 0 && started == 0 {
-		return fmt.Errorf("清理完成但缺少开始断点")
-	}
-	return nil
+	return &runs[0], nil
 }
 
 func (s *Service) validateAuditRetentionDay(ctx context.Context, date time.Time, run *model.LogArchiveRun) error {
@@ -258,25 +208,25 @@ func (s *Service) validateIntegrationRetentionDay(ctx context.Context, date time
 	if err != nil {
 		return err
 	}
-	if run.CleanedAt != nil {
-		if count != 0 {
-			return fmt.Errorf("已标记清理完成但数据库仍有 %d 条记录", count)
-		}
-		return nil
-	}
-	if run.CleanupStartedAt != nil {
-		if count > run.RecordCount {
-			return fmt.Errorf("续跑窗口记录数超过最终归档数量")
-		}
-		return nil
-	}
-	file, err := s.buildIntegrationArchiveFile(ctx, run.RangeStart, run.RangeEnd)
+	terminalCount, err := s.integrationTerminalCount(ctx, run.RangeStart, run.RangeEnd)
 	if err != nil {
 		return err
 	}
-	defer os.Remove(file.path)
-	if file.recordCount != run.RecordCount || file.sha256 != run.SHA256 {
-		return fmt.Errorf("数据库当前 Integration 内容与最终 revision 不一致")
+	if run.CleanedAt != nil && terminalCount != 0 {
+		return fmt.Errorf("已标记清理完成但数据库仍有 %d 条终态记录", terminalCount)
+	}
+	if run.CleanupStartedAt != nil && count > run.RecordCount {
+		return fmt.Errorf("续跑窗口记录数超过最终归档数量")
+	}
+	if terminalCount > 0 && run.CleanupStartedAt == nil {
+		file, err := s.buildIntegrationArchiveFile(ctx, run.RangeStart, run.RangeEnd)
+		if err != nil {
+			return err
+		}
+		defer os.Remove(file.path)
+		if file.recordCount != run.RecordCount || file.sha256 != run.SHA256 {
+			return fmt.Errorf("数据库当前 Integration 内容与最终 revision 不一致")
+		}
 	}
 	return nil
 }
@@ -285,8 +235,7 @@ func validateRunBase(run *model.LogArchiveRun, date time.Time, schema string, fi
 	if run.Status != constants.ArchiveStatusSuccess || run.SchemaVersion != schema {
 		return fmt.Errorf("归档状态或 schema version 不符合清理要求")
 	}
-	if run.ArchiveDate.Format(time.DateOnly) != date.Format(time.DateOnly) ||
-		!run.RangeStart.Equal(date) || !run.RangeEnd.Equal(date.AddDate(0, 0, 1)) {
+	if run.ArchiveDate.Format(time.DateOnly) != date.Format(time.DateOnly) || !run.RangeStart.Equal(date) || !run.RangeEnd.Equal(date.AddDate(0, 0, 1)) {
 		return fmt.Errorf("归档日期或半开时间范围不一致")
 	}
 	if final && !run.IsFinal {
@@ -297,21 +246,14 @@ func validateRunBase(run *model.LogArchiveRun, date time.Time, schema string, fi
 	}
 	return nil
 }
-
 func validateRemainingCounts(run *model.LogArchiveRun, events, resources int64) error {
-	if run.CleanedAt != nil {
-		if events != 0 || resources != 0 {
-			return fmt.Errorf("已标记清理完成但数据库仍有事件或资源")
-		}
-		return nil
+	if run.CleanedAt != nil && (events != 0 || resources != 0) {
+		return fmt.Errorf("已标记清理完成但数据库仍有事件或资源")
 	}
-	if run.CleanupStartedAt != nil {
-		if events > run.EventCount || resources > run.ResourceCount {
-			return fmt.Errorf("续跑窗口数量超过已归档数量")
-		}
-		return nil
+	if run.CleanupStartedAt != nil && (events > run.EventCount || resources > run.ResourceCount) {
+		return fmt.Errorf("续跑窗口数量超过已归档数量")
 	}
-	if events != run.EventCount || resources != run.ResourceCount {
+	if run.CleanupStartedAt == nil && (events != run.EventCount || resources != run.ResourceCount) {
 		return fmt.Errorf("数据库事件或资源数量与 manifest 不一致")
 	}
 	return nil
@@ -322,43 +264,27 @@ func (s *Service) validateAuditManifest(ctx context.Context, run *model.LogArchi
 	if err := s.readManifest(ctx, run.ManifestKey, &manifest); err != nil {
 		return err
 	}
-	if manifest.Source != run.Source || manifest.SchemaVersion != run.SchemaVersion || manifest.Status != constants.ArchiveStatusSuccess ||
-		manifest.ArchiveDate != run.ArchiveDate.Format(time.DateOnly) || manifest.Timezone != constants.AuditArchiveTimezone ||
-		manifest.InstanceID != run.InstanceID || !manifest.RangeStart.Equal(run.RangeStart) || !manifest.RangeEnd.Equal(run.RangeEnd) ||
-		manifest.EventCount != run.EventCount || manifest.ResourceCount != run.ResourceCount ||
-		manifest.CompressedBytes != run.CompressedBytes || manifest.ObjectKey != run.ObjectKey ||
-		manifest.SHA256 != run.SHA256 || manifest.Revision != run.Revision {
+	if manifest.Source != run.Source || manifest.SchemaVersion != run.SchemaVersion || manifest.Status != constants.ArchiveStatusSuccess || manifest.ArchiveDate != run.ArchiveDate.Format(time.DateOnly) || manifest.Timezone != constants.AuditArchiveTimezone || manifest.InstanceID != run.InstanceID || !manifest.RangeStart.Equal(run.RangeStart) || !manifest.RangeEnd.Equal(run.RangeEnd) || manifest.EventCount != run.EventCount || manifest.ResourceCount != run.ResourceCount || manifest.CompressedBytes != run.CompressedBytes || manifest.ObjectKey != run.ObjectKey || manifest.SHA256 != run.SHA256 || manifest.Revision != run.Revision {
 		return fmt.Errorf("Audit manifest 与 ledger 不一致")
 	}
-	if err := s.verifyObject(ctx, run.ManifestKey, -1, map[string]string{
-		"source": constants.AuditArchiveSource, "data-sha256": run.SHA256, "revision": strconv.Itoa(run.Revision),
-	}); err != nil {
+	if err := s.verifyObject(ctx, run.ManifestKey, -1, map[string]string{"source": constants.AuditArchiveSource, "data-sha256": run.SHA256, "revision": strconv.Itoa(run.Revision)}); err != nil {
 		return err
 	}
 	return s.verifyRetentionObject(ctx, run, false)
 }
-
 func (s *Service) validateIntegrationManifest(ctx context.Context, run *model.LogArchiveRun) error {
 	var manifest integrationArchiveManifest
 	if err := s.readManifest(ctx, run.ManifestKey, &manifest); err != nil {
 		return err
 	}
-	if manifest.Source != run.Source || manifest.SchemaVersion != run.SchemaVersion || manifest.Status != constants.ArchiveStatusSuccess || !manifest.Final ||
-		manifest.ArchiveDate != run.ArchiveDate.Format(time.DateOnly) || manifest.Timezone != constants.AuditArchiveTimezone ||
-		manifest.InstanceID != run.InstanceID || !manifest.RangeStart.Equal(run.RangeStart) || !manifest.RangeEnd.Equal(run.RangeEnd) ||
-		manifest.RecordCount != run.RecordCount || manifest.CompressedBytes != run.CompressedBytes ||
-		manifest.ObjectKey != run.ObjectKey || manifest.SHA256 != run.SHA256 || manifest.Revision != run.Revision {
+	if manifest.Source != run.Source || manifest.SchemaVersion != run.SchemaVersion || manifest.Status != constants.ArchiveStatusSuccess || !manifest.Final || manifest.ArchiveDate != run.ArchiveDate.Format(time.DateOnly) || manifest.Timezone != constants.AuditArchiveTimezone || manifest.InstanceID != run.InstanceID || !manifest.RangeStart.Equal(run.RangeStart) || !manifest.RangeEnd.Equal(run.RangeEnd) || manifest.RecordCount != run.RecordCount || manifest.CompressedBytes != run.CompressedBytes || manifest.ObjectKey != run.ObjectKey || manifest.SHA256 != run.SHA256 || manifest.Revision != run.Revision {
 		return fmt.Errorf("Integration manifest 与最终 ledger 不一致")
 	}
-	if err := s.verifyObject(ctx, run.ManifestKey, -1, map[string]string{
-		"source": constants.IntegrationArchiveSource, "data-sha256": run.SHA256,
-		"revision": strconv.Itoa(run.Revision), "final": "true",
-	}); err != nil {
+	if err := s.verifyObject(ctx, run.ManifestKey, -1, map[string]string{"source": constants.IntegrationArchiveSource, "data-sha256": run.SHA256, "revision": strconv.Itoa(run.Revision), "final": "true"}); err != nil {
 		return err
 	}
 	return s.verifyRetentionObject(ctx, run, true)
 }
-
 func (s *Service) readManifest(ctx context.Context, key string, target any) error {
 	object, err := s.store.Stat(ctx, key)
 	if err != nil {
@@ -384,13 +310,8 @@ func (s *Service) readManifest(ctx context.Context, key string, target any) erro
 	}
 	return nil
 }
-
 func (s *Service) verifyRetentionObject(ctx context.Context, run *model.LogArchiveRun, final bool) error {
-	metadata := map[string]string{
-		"schema-version": run.SchemaVersion, "source": run.Source,
-		"archive-date": run.RangeStart.Format(time.DateOnly), "timezone": constants.AuditArchiveTimezone,
-		"sha256": run.SHA256, "revision": strconv.Itoa(run.Revision),
-	}
+	metadata := map[string]string{"schema-version": run.SchemaVersion, "source": run.Source, "archive-date": run.RangeStart.Format(time.DateOnly), "timezone": constants.AuditArchiveTimezone, "sha256": run.SHA256, "revision": strconv.Itoa(run.Revision)}
 	if run.Source == constants.AuditArchiveSource {
 		metadata["event-count"] = strconv.FormatInt(run.EventCount, 10)
 		metadata["resource-count"] = strconv.FormatInt(run.ResourceCount, 10)
@@ -419,53 +340,39 @@ func (s *Service) verifyRetentionObject(ctx context.Context, run *model.LogArchi
 	}
 	return nil
 }
-
-func summarizeRetentionRuns(runs retentionRuns, result *RetentionResult) {
-	result.ManifestKeys = make([]string, 0, len(runs.audit)+len(runs.integration))
-	for _, run := range runs.audit {
-		result.EventCount += run.EventCount
-		result.ResourceCount += run.ResourceCount
-		result.ManifestKeys = append(result.ManifestKeys, run.ManifestKey)
-	}
-	for _, run := range runs.integration {
-		result.IntegrationCount += run.RecordCount
-		result.ManifestKeys = append(result.ManifestKeys, run.ManifestKey)
-	}
-}
-
 func estimatedRetentionBatches(result RetentionResult) int64 {
-	batchSize := int64(constants.AuditRetentionDeleteBatchSize)
-	return (result.EventCount+batchSize-1)/batchSize +
-		(result.ResourceCount+batchSize-1)/batchSize +
-		(result.IntegrationCount+batchSize-1)/batchSize
+	batch := int64(constants.AuditRetentionDeleteBatchSize)
+	return (result.EventCount+batch-1)/batch + (result.ResourceCount+batch-1)/batch + (result.IntegrationCount+batch-1)/batch
 }
-
-func (s *Service) cleanupAuditMonth(ctx context.Context, start, end time.Time, runs []*model.LogArchiveRun) error {
-	if allRunsCleaned(runs) {
+func (s *Service) cleanupAuditDate(ctx context.Context, date time.Time, run *model.LogArchiveRun) error {
+	if run.CleanedAt != nil {
 		return nil
 	}
-	if err := s.markCleanupStarted(ctx, constants.AuditArchiveSource, start, end); err != nil {
+	if err := s.markCleanupStarted(ctx, constants.AuditArchiveSource, date); err != nil {
 		return err
 	}
-	if err := s.deleteAuditResources(ctx, start, end); err != nil {
+	if err := s.deleteAuditResources(ctx, date, date.AddDate(0, 0, 1)); err != nil {
 		return err
 	}
-	if err := s.deleteAuditEvents(ctx, start, end); err != nil {
+	if err := s.deleteAuditEvents(ctx, date, date.AddDate(0, 0, 1)); err != nil {
 		return err
 	}
-	return s.markCleaned(ctx, constants.AuditArchiveSource, start, end)
+	return s.markCleaned(ctx, constants.AuditArchiveSource, date)
 }
-
-func (s *Service) cleanupIntegrationMonth(ctx context.Context, start, end time.Time, runs []*model.LogArchiveRun) error {
-	if allRunsCleaned(runs) {
+func (s *Service) cleanupIntegrationDate(ctx context.Context, date time.Time, run *model.LogArchiveRun) error {
+	terminalCount, err := s.integrationTerminalCount(ctx, date, date.AddDate(0, 0, 1))
+	if err != nil {
+		return err
+	}
+	if run.CleanedAt != nil && terminalCount == 0 {
 		return nil
 	}
-	if err := s.markCleanupStarted(ctx, constants.IntegrationArchiveSource, start, end); err != nil {
+	if err := s.markCleanupStarted(ctx, constants.IntegrationArchiveSource, date); err != nil {
 		return err
 	}
+	end := date.AddDate(0, 0, 1)
 	for {
-		subquery := s.db.Model(&model.IntegrationLog{}).Select("id").
-			Where("created_at >= ? AND created_at < ?", start, end).Order("id ASC").Limit(constants.AuditRetentionDeleteBatchSize)
+		subquery := s.db.Model(&model.IntegrationLog{}).Select("id").Where("created_at >= ? AND created_at < ? AND result <> ?", date, end, constants.IntegrationResultPending).Order("id ASC").Limit(constants.AuditRetentionDeleteBatchSize)
 		deleted := s.db.WithContext(ctx).Where("id IN (?)", subquery).Delete(&model.IntegrationLog{})
 		if deleted.Error != nil {
 			return fmt.Errorf("分批物理删除 Integration Log 失败: %w", deleted.Error)
@@ -474,15 +381,21 @@ func (s *Service) cleanupIntegrationMonth(ctx context.Context, start, end time.T
 			break
 		}
 	}
-	return s.markCleaned(ctx, constants.IntegrationArchiveSource, start, end)
+	return s.markCleaned(ctx, constants.IntegrationArchiveSource, date)
+}
+func (s *Service) integrationTerminalCount(ctx context.Context, start, end time.Time) (int64, error) {
+	var count int64
+	if err := s.db.WithContext(ctx).Model(&model.IntegrationLog{}).
+		Where("created_at >= ? AND created_at < ? AND result <> ?", start, end, constants.IntegrationResultPending).
+		Count(&count).Error; err != nil {
+		return 0, fmt.Errorf("统计终态 Integration Log 失败: %w", err)
+	}
+	return count, nil
 }
 
 func (s *Service) deleteAuditResources(ctx context.Context, start, end time.Time) error {
 	for {
-		subquery := s.db.Model(&model.AuditEventResource{}).Select("tb_audit_event_resource.id").
-			Joins("JOIN tb_audit_event ON tb_audit_event.id = tb_audit_event_resource.audit_event_id").
-			Where("tb_audit_event.created_at >= ? AND tb_audit_event.created_at < ?", start, end).
-			Order("tb_audit_event_resource.id ASC").Limit(constants.AuditRetentionDeleteBatchSize)
+		subquery := s.db.Model(&model.AuditEventResource{}).Select("tb_audit_event_resource.id").Joins("JOIN tb_audit_event ON tb_audit_event.id = tb_audit_event_resource.audit_event_id").Where("tb_audit_event.created_at >= ? AND tb_audit_event.created_at < ?", start, end).Order("tb_audit_event_resource.id ASC").Limit(constants.AuditRetentionDeleteBatchSize)
 		deleted := s.db.WithContext(ctx).Where("id IN (?)", subquery).Delete(&model.AuditEventResource{})
 		if deleted.Error != nil {
 			return fmt.Errorf("分批物理删除 Audit Event Resource 失败: %w", deleted.Error)
@@ -492,11 +405,9 @@ func (s *Service) deleteAuditResources(ctx context.Context, start, end time.Time
 		}
 	}
 }
-
 func (s *Service) deleteAuditEvents(ctx context.Context, start, end time.Time) error {
 	for {
-		subquery := s.db.Model(&model.AuditEvent{}).Select("id").
-			Where("created_at >= ? AND created_at < ?", start, end).Order("id ASC").Limit(constants.AuditRetentionDeleteBatchSize)
+		subquery := s.db.Model(&model.AuditEvent{}).Select("id").Where("created_at >= ? AND created_at < ?", start, end).Order("id ASC").Limit(constants.AuditRetentionDeleteBatchSize)
 		deleted := s.db.WithContext(ctx).Where("id IN (?)", subquery).Delete(&model.AuditEvent{})
 		if deleted.Error != nil {
 			return fmt.Errorf("分批物理删除 Audit Event 失败: %w", deleted.Error)
@@ -506,75 +417,19 @@ func (s *Service) deleteAuditEvents(ctx context.Context, start, end time.Time) e
 		}
 	}
 }
-
-func (s *Service) markCleanupStarted(ctx context.Context, source string, start, end time.Time) error {
+func (s *Service) markCleanupStarted(ctx context.Context, source string, date time.Time) error {
 	now := time.Now()
-	result := s.db.WithContext(ctx).Model(&model.LogArchiveRun{}).
-		Where("source = ? AND archive_date >= ? AND archive_date < ? AND instance_id = ? AND cleanup_started_at IS NULL",
-			source, start.Format(time.DateOnly), end.Format(time.DateOnly), s.instanceID).
-		Updates(map[string]any{"cleanup_started_at": now, "updated_at": now})
+	result := s.db.WithContext(ctx).Model(&model.LogArchiveRun{}).Where("source = ? AND archive_date = ? AND instance_id = ? AND cleanup_started_at IS NULL", source, date.Format(time.DateOnly), s.instanceID).Updates(map[string]any{"cleanup_started_at": now, "updated_at": now})
 	if result.Error != nil {
-		return fmt.Errorf("记录月度清理开始断点失败: %w", result.Error)
-	}
-	return s.validateCleanupMarkerCount(ctx, source, start, end, "cleanup_started_at IS NOT NULL", "开始")
-}
-
-func (s *Service) markCleaned(ctx context.Context, source string, start, end time.Time) error {
-	now := time.Now()
-	result := s.db.WithContext(ctx).Model(&model.LogArchiveRun{}).
-		Where("source = ? AND archive_date >= ? AND archive_date < ? AND instance_id = ? AND cleanup_started_at IS NOT NULL",
-			source, start.Format(time.DateOnly), end.Format(time.DateOnly), s.instanceID).
-		Updates(map[string]any{"cleaned_at": now, "updated_at": now})
-	if result.Error != nil {
-		return fmt.Errorf("记录月度清理完成断点失败: %w", result.Error)
-	}
-	return s.validateCleanupMarkerCount(ctx, source, start, end, "cleaned_at IS NOT NULL", "完成")
-}
-
-func (s *Service) validateCleanupMarkerCount(ctx context.Context, source string, start, end time.Time, marker, label string) error {
-	var count int64
-	err := s.db.WithContext(ctx).Model(&model.LogArchiveRun{}).
-		Where("source = ? AND archive_date >= ? AND archive_date < ? AND instance_id = ? AND "+marker,
-			source, start.Format(time.DateOnly), end.Format(time.DateOnly), s.instanceID).
-		Count(&count).Error
-	if err != nil {
-		return fmt.Errorf("复核月度清理%s断点失败: %w", label, err)
-	}
-	expected := int64(end.Sub(start).Hours() / 24)
-	if count != expected {
-		return fmt.Errorf("月度清理%s断点不完整：期望 %d 条，实际 %d 条", label, expected, count)
+		return fmt.Errorf("记录日清理开始断点失败: %w", result.Error)
 	}
 	return nil
 }
-
-func allRunsCleaned(runs []*model.LogArchiveRun) bool {
-	return len(runs) > 0 && runs[0].CleanedAt != nil
-}
-
-func (s *Service) recordRetentionAudit(ctx context.Context, start, end time.Time, result RetentionResult, cleanupErr error) error {
-	audit := RetentionAudit{
-		Month: result.Month, RangeStart: start, RangeEnd: end,
-		EventCount: result.EventCount, ResourceCount: result.ResourceCount,
-		IntegrationCount: result.IntegrationCount, ManifestKeys: result.ManifestKeys,
-		DurationMS: result.Duration.Milliseconds(), Result: constants.AuditResultSuccess,
-		Summary: "完成已归档在线日志月度物理清理",
-		EventID: "evt_retention_" + strings.ReplaceAll(result.Month, "-", "_"),
+func (s *Service) markCleaned(ctx context.Context, source string, date time.Time) error {
+	now := time.Now()
+	result := s.db.WithContext(ctx).Model(&model.LogArchiveRun{}).Where("source = ? AND archive_date = ? AND instance_id = ? AND cleanup_started_at IS NOT NULL", source, date.Format(time.DateOnly), s.instanceID).Updates(map[string]any{"cleaned_at": now, "updated_at": now})
+	if result.Error != nil {
+		return fmt.Errorf("记录日清理完成断点失败: %w", result.Error)
 	}
-	if cleanupErr != nil {
-		audit.EventID = ""
-		audit.Result = constants.AuditResultFailed
-		audit.Summary = "已归档在线日志月度物理清理失败"
-		audit.ErrorSummary = truncateRetentionError(cleanupErr)
-	}
-	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
-		return s.audit.WriteRetentionCleanup(ctx, tx, audit)
-	})
-}
-
-func truncateRetentionError(err error) string {
-	value := []rune(err.Error())
-	if len(value) > 500 {
-		value = value[:500]
-	}
-	return string(value)
+	return nil
 }

internal/application/employeecollection/application.go

@@ -0,0 +1,671 @@
+package employeecollection
+
+import (
+	"context"
+	"fmt"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/bytedance/sonic"
+	"github.com/google/uuid"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	approvalapp "github.com/break/junhong_cmp_fiber/internal/application/approval"
+	employeecollectiondomain "github.com/break/junhong_cmp_fiber/internal/domain/employeecollection"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+)
+
+// ApplicationAllocationCommand 描述核销申请中单张账单的本次分摊。
+type ApplicationAllocationCommand struct {
+	BillID uint
+	Amount int64
+}
+
+// SubmitApplicationCommand 描述创建或重提核销申请的稳定输入。
+type SubmitApplicationCommand struct {
+	PaymentMethodID       uint
+	PaidAmount            int64
+	PayerName             string
+	PaidAt                time.Time
+	ExternalTransactionNo string
+	PaymentVoucherKeys    []string
+	Remark                string
+	ActingReason          string
+	Allocations           []ApplicationAllocationCommand
+}
+
+// ApplicationSubmitResult 返回已原子保存的申请、审批尝试记录与分摊。
+type ApplicationSubmitResult struct {
+	Application    *model.EmployeeCollectionApplication
+	Attempt        *model.EmployeeCollectionApplicationAttempt
+	Allocations    []*model.EmployeeCollectionApplicationAllocation
+	Bills          []*model.EmployeeCollectionBill
+	InstanceID     uint
+	InstanceStatus int
+}
+
+// ApplicationService 创建与重提核销申请。
+// 申请、审批尝试记录、审批实例与账单预占在同一事务完成；任一校验失败都不留下半成品事实。
+type ApplicationService struct {
+	db       *gorm.DB
+	approval approvalapp.Port
+	audit    ApplicationAuditWriter
+}
+
+// NewApplicationService 创建核销申请用例。
+func NewApplicationService(db *gorm.DB, approval approvalapp.Port, audit ApplicationAuditWriter) *ApplicationService {
+	return &ApplicationService{db: db, approval: approval, audit: audit}
+}
+
+// Create 为本人可见账单创建核销申请；超级管理员可为账单欠款人代办并必须填写代办原因。
+func (s *ApplicationService) Create(ctx context.Context, command SubmitApplicationCommand) (*ApplicationSubmitResult, error) {
+	if err := s.ensureReady(); err != nil {
+		return nil, err
+	}
+	caller, err := currentApplicationCaller(ctx)
+	if err != nil {
+		return nil, err
+	}
+	return s.submit(ctx, caller, 0, command)
+}
+
+// Resubmit 修改并重提已驳回的核销申请，新增审批尝试记录与新的企业微信审批实例。
+func (s *ApplicationService) Resubmit(ctx context.Context, applicationID uint, command SubmitApplicationCommand) (*ApplicationSubmitResult, error) {
+	if err := s.ensureReady(); err != nil {
+		return nil, err
+	}
+	caller, err := currentApplicationCaller(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if applicationID == 0 {
+		return nil, errors.New(errors.CodeEmployeeCollectionApplicationNotFound)
+	}
+	return s.submit(ctx, caller, applicationID, command)
+}
+
+// ensureReady 校验用例依赖完整，缺失时失败关闭，避免绕过企业微信终审。
+func (s *ApplicationService) ensureReady() error {
+	if s == nil || s.db == nil || s.approval == nil || s.audit == nil {
+		return errors.New(errors.CodeServiceUnavailable, "核销申请能力尚未配置")
+	}
+	return nil
+}
+
+// applicationCaller 是发起核销申请的真实操作者。
+type applicationCaller struct {
+	AccountID   uint
+	AccountName string
+	IsAdmin     bool
+}
+
+// currentApplicationCaller 从上下文取当前操作者，未认证时拒绝。
+func currentApplicationCaller(ctx context.Context) (applicationCaller, error) {
+	accountID := middleware.GetUserIDFromContext(ctx)
+	if accountID == 0 {
+		return applicationCaller{}, errors.New(errors.CodeUnauthorized)
+	}
+	return applicationCaller{
+		AccountID:   accountID,
+		AccountName: middleware.GetUsernameFromContext(ctx),
+		IsAdmin:     middleware.GetUserTypeFromContext(ctx) == constants.UserTypeSuperAdmin,
+	}, nil
+}
+
+// submit 在同一事务内完成校验、加锁、写申请、写审批尝试记录、创建审批实例与账单预占。
+// 加锁次序全仓统一为「申请行 → 账单行（ID 升序）」，与审批终态消费者保持一致，避免死锁。
+func (s *ApplicationService) submit(
+	ctx context.Context,
+	caller applicationCaller,
+	applicationID uint,
+	command SubmitApplicationCommand,
+) (*ApplicationSubmitResult, error) {
+	if command.PaymentMethodID == 0 {
+		return nil, errors.New(errors.CodeInvalidParam, "核销申请必须选择线下收款方式")
+	}
+	allocationCommands, err := sortedAllocationCommands(command.Allocations)
+	if err != nil {
+		return nil, err
+	}
+	correlationID := "employee_collection:application:" + uuid.NewString()
+	preparation, err := s.approval.Prepare(ctx, approvalapp.PrepareRequest{
+		BusinessType:       constants.ApprovalBusinessTypeEmployeeCollection,
+		SubmitterAccountID: caller.AccountID, CorrelationID: correlationID,
+	})
+	if err != nil {
+		return nil, err
+	}
+	var result *ApplicationSubmitResult
+	err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var existing *model.EmployeeCollectionApplication
+		if applicationID != 0 {
+			existing, err = lockApplication(ctx, tx, applicationID)
+			if err != nil {
+				return err
+			}
+			if err := employeecollectiondomain.ValidateApplicationResubmit(existing.Status); err != nil {
+				return err
+			}
+			if existing.ApplicantAccountID != caller.AccountID && !caller.IsAdmin {
+				return errors.New(errors.CodeEmployeeCollectionApplicationNotFound)
+			}
+		}
+		bills, err := lockBillsInAscendingOrder(ctx, tx, allocationCommands)
+		if err != nil {
+			return err
+		}
+		paymentMethod, err := loadEnabledPaymentMethod(ctx, tx, command.PaymentMethodID)
+		if err != nil {
+			return err
+		}
+		applicantAccountID, err := resolveApplicantAccountID(caller, existing, bills)
+		if err != nil {
+			return err
+		}
+		acting := applicantAccountID != caller.AccountID
+		normalized, err := employeecollectiondomain.NormalizeApplicationInput(employeecollectiondomain.ApplicationInput{
+			PaidAmount: command.PaidAmount, PayerName: command.PayerName, PaidAt: command.PaidAt,
+			ExternalTransactionNo: command.ExternalTransactionNo, Remark: command.Remark,
+			ActingReason: command.ActingReason, PaymentVoucherKeys: command.PaymentVoucherKeys,
+		}, acting)
+		if err != nil {
+			return err
+		}
+		candidates := make([]employeecollectiondomain.AllocationCandidate, 0, len(allocationCommands))
+		for _, item := range allocationCommands {
+			bill := bills[item.BillID]
+			candidates = append(candidates, employeecollectiondomain.AllocationCandidate{
+				BillID: item.BillID, BillStatus: bill.Status, Amount: item.Amount,
+				Available: billAmounts(bill).Available(),
+			})
+		}
+		if err := employeecollectiondomain.ValidateAllocations(normalized.PaidAmount, candidates); err != nil {
+			return err
+		}
+
+		application, beforeData, err := prepareApplication(
+			ctx, tx, caller, existing, applicantAccountID, paymentMethod, normalized)
+		if err != nil {
+			return err
+		}
+		attemptNo, err := nextAttemptNo(ctx, tx, application.ID)
+		if err != nil {
+			return err
+		}
+		attempt, err := buildAttempt(ctx, tx, application.ID, attemptNo, caller, paymentMethod, normalized, bills, allocationCommands)
+		if err != nil {
+			return err
+		}
+		submitterSnapshot, requestSnapshot, err := approvalSnapshots(application.ID, caller, paymentMethod, normalized, bills, allocationCommands)
+		if err != nil {
+			return err
+		}
+		reference, err := s.approval.CreateInTx(ctx, tx, approvalapp.CreateRequest{
+			Preparation: preparation, BusinessType: constants.ApprovalBusinessTypeEmployeeCollection,
+			BusinessID: attempt.ID, SubmitterAccountID: caller.AccountID,
+			SubmitterSnapshot: submitterSnapshot, RequestSnapshot: requestSnapshot,
+			CorrelationID: correlationID,
+		})
+		if err != nil {
+			return err
+		}
+		if err := attachAttemptInstance(ctx, tx, attempt, reference.InstanceID); err != nil {
+			return err
+		}
+		if err := updateApplicationLatest(ctx, tx, application, attempt, reference.InstanceID); err != nil {
+			return err
+		}
+		allocations, reservedBills, err := createAllocations(ctx, tx, application.ID, attempt.ID, caller, bills, allocationCommands)
+		if err != nil {
+			return err
+		}
+		submitEventID, err := composeAuditEventID(
+			"employee_collection", "application", uintText(application.ID), "attempt", intText(attempt.AttemptNo), "submit")
+		if err != nil {
+			return err
+		}
+		if err := s.audit.WriteEmployeeCollectionApplication(ctx, tx, ApplicationAudit{
+			EventID:     submitEventID,
+			ActionCode:  constants.AuditActionEmployeeCollectionApplicationSubmitted,
+			Summary:     submitSummary(existing != nil),
+			Application: application, Attempt: attempt, Allocations: allocations, Bills: reservedBills,
+			BeforeData: beforeData, AfterData: applicationAuditSnapshot(application),
+			CorrelationID: correlationID,
+		}); err != nil {
+			return err
+		}
+		result = &ApplicationSubmitResult{
+			Application: application, Attempt: attempt, Allocations: allocations,
+			Bills: reservedBills, InstanceID: reference.InstanceID, InstanceStatus: reference.Status,
+		}
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return result, nil
+}
+
+// submitSummary 区分首次提交与重提的审计摘要。
+func submitSummary(resubmit bool) string {
+	if resubmit {
+		return "重提员工代收款核销申请"
+	}
+	return "提交员工代收款核销申请"
+}
+
+// sortedAllocationCommands 校验分摊入参基本形态并按账单 ID 升序返回，保证锁序唯一。
+func sortedAllocationCommands(items []ApplicationAllocationCommand) ([]ApplicationAllocationCommand, error) {
+	if len(items) == 0 {
+		return nil, errors.New(errors.CodeInvalidParam, "核销申请至少需要一个账单分摊")
+	}
+	if len(items) > constants.EmployeeCollectionAllocationMaxCount {
+		return nil, errors.New(errors.CodeInvalidParam, "核销申请账单分摊数量超出限制")
+	}
+	seen := make(map[uint]struct{}, len(items))
+	for _, item := range items {
+		if item.BillID == 0 {
+			return nil, errors.New(errors.CodeInvalidParam, "账单分摊缺少目标账单")
+		}
+		if item.Amount <= 0 {
+			return nil, errors.New(errors.CodeEmployeeCollectionAllocationAmountInvalid)
+		}
+		if _, exists := seen[item.BillID]; exists {
+			return nil, errors.New(errors.CodeInvalidParam, "同一账单不能重复分摊")
+		}
+		seen[item.BillID] = struct{}{}
+	}
+	sorted := append([]ApplicationAllocationCommand(nil), items...)
+	sort.Slice(sorted, func(i, j int) bool { return sorted[i].BillID < sorted[j].BillID })
+	return sorted, nil
+}
+
+// lockApplication 以行锁读取核销申请，未找到返回稳定不存在错误。
+func lockApplication(ctx context.Context, tx *gorm.DB, id uint) (*model.EmployeeCollectionApplication, error) {
+	var application model.EmployeeCollectionApplication
+	if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).
+		First(&application, id).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeEmployeeCollectionApplicationNotFound)
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "锁定核销申请失败")
+	}
+	return &application, nil
+}
+
+// lockBillsInAscendingOrder 按账单 ID 升序逐行加锁并返回账单事实。
+// 单条 `WHERE id IN (...) ORDER BY id FOR UPDATE` 在 PostgreSQL 中先取行加锁再排序，
+// 无法保证加锁次序；因此对每个账单各发一条只锁一行的语句，由调用方保证 ID 升序且不重复。
+func lockBillsInAscendingOrder(
+	ctx context.Context,
+	tx *gorm.DB,
+	items []ApplicationAllocationCommand,
+) (map[uint]*model.EmployeeCollectionBill, error) {
+	bills := make(map[uint]*model.EmployeeCollectionBill, len(items))
+	for _, item := range items {
+		var bill model.EmployeeCollectionBill
+		if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).
+			First(&bill, item.BillID).Error; err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return nil, errors.New(errors.CodeEmployeeCollectionBillNotFound)
+			}
+			return nil, errors.Wrap(errors.CodeDatabaseError, err, "锁定员工代收款账单失败")
+		}
+		bills[item.BillID] = &bill
+	}
+	return bills, nil
+}
+
+// loadEnabledPaymentMethod 读取启用中的线下收款方式字典项作为冻结来源。
+func loadEnabledPaymentMethod(ctx context.Context, tx *gorm.DB, id uint) (*model.EmployeeCollectionPaymentMethod, error) {
+	var paymentMethod model.EmployeeCollectionPaymentMethod
+	if err := tx.WithContext(ctx).First(&paymentMethod, id).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeEmployeeCollectionPaymentMethodNotFound)
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询线下收款方式失败")
+	}
+	if paymentMethod.Status != constants.EmployeeCollectionPaymentMethodStatusEnabled {
+		return nil, errors.New(errors.CodeEmployeeCollectionPaymentMethodDisabled)
+	}
+	return &paymentMethod, nil
+}
+
+// resolveApplicantAccountID 依据所选账单确定申请人。
+// 新建：非超级管理员只能选择本人欠款账单；超级管理员代办时全部账单必须属于同一欠款人。
+// 重提：被选账单必须仍属于原申请人，申请人的其他越权访问与不存在返回同一错误。
+func resolveApplicantAccountID(
+	caller applicationCaller,
+	existing *model.EmployeeCollectionApplication,
+	bills map[uint]*model.EmployeeCollectionBill,
+) (uint, error) {
+	if existing != nil {
+		applicant := existing.ApplicantAccountID
+		for _, bill := range bills {
+			if bill.DebtorAccountID != applicant {
+				return 0, errors.New(errors.CodeEmployeeCollectionBillNotFound)
+			}
+		}
+		return applicant, nil
+	}
+	applicant := uint(0)
+	for _, bill := range bills {
+		if !caller.IsAdmin && bill.DebtorAccountID != caller.AccountID {
+			return 0, errors.New(errors.CodeEmployeeCollectionBillNotFound)
+		}
+		if applicant == 0 {
+			applicant = bill.DebtorAccountID
+			continue
+		}
+		if applicant != bill.DebtorAccountID {
+			return 0, errors.New(errors.CodeInvalidParam, "代办核销申请时全部账单必须属于同一欠款人")
+		}
+	}
+	return applicant, nil
+}
+
+// billAmounts 将账单持久化事实映射为领域金额事实。
+func billAmounts(bill *model.EmployeeCollectionBill) employeecollectiondomain.BillAmounts {
+	return employeecollectiondomain.BillAmounts{
+		Receivable: bill.ReceivableAmount, Received: bill.ReceivedAmount, Reserved: bill.ReservedAmount,
+		Closed: bill.Status == constants.EmployeeCollectionBillStatusClosed,
+	}
+}
+
+// nextAttemptNo 返回该申请的下一条审批尝试序号；申请行已加锁，序号在同一事务内唯一。
+func nextAttemptNo(ctx context.Context, tx *gorm.DB, applicationID uint) (int, error) {
+	var row struct {
+		MaxAttemptNo int
+	}
+	if err := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplicationAttempt{}).
+		Select("COALESCE(MAX(attempt_no), 0) AS max_attempt_no").
+		Where("application_id = ?", applicationID).Scan(&row).Error; err != nil {
+		return 0, errors.Wrap(errors.CodeDatabaseError, err, "查询核销审批尝试序号失败")
+	}
+	return row.MaxAttemptNo + 1, nil
+}
+
+// prepareApplication 新建或就地更新核销申请，返回申请事实与变更前快照。
+// 重提使用 expected-status 条件更新，状态已变化时返回冲突。
+func prepareApplication(
+	ctx context.Context,
+	tx *gorm.DB,
+	caller applicationCaller,
+	existing *model.EmployeeCollectionApplication,
+	applicantAccountID uint,
+	paymentMethod *model.EmployeeCollectionPaymentMethod,
+	normalized employeecollectiondomain.NormalizedApplicationInput,
+) (*model.EmployeeCollectionApplication, map[string]any, error) {
+	actingOperatorID := uint(0)
+	if applicantAccountID != caller.AccountID {
+		actingOperatorID = caller.AccountID
+	}
+	if existing == nil {
+		application := &model.EmployeeCollectionApplication{
+			ApplicantAccountID: applicantAccountID, ActingOperatorID: actingOperatorID,
+			ActingReason:    normalized.ActingReason,
+			PaymentMethodID: paymentMethod.ID, PaymentMethodCode: paymentMethod.Code,
+			PaymentMethodName: paymentMethod.Name, PaidAmount: normalized.PaidAmount,
+			PayerName: normalized.PayerName, PaidAt: normalized.PaidAt,
+			ExternalTransactionNo: normalized.ExternalTransactionNo,
+			PaymentVoucherKeys:    model.StringJSONBArray(normalized.PaymentVoucherKeys),
+			Remark:                normalized.Remark,
+			Status:                constants.EmployeeCollectionApplicationStatusPending,
+			Creator:               caller.AccountID, Updater: caller.AccountID,
+		}
+		if err := tx.WithContext(ctx).Create(application).Error; err != nil {
+			return nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "创建核销申请失败")
+		}
+		return application, nil, nil
+	}
+	beforeData := applicationAuditSnapshot(existing)
+	expectedStatus := existing.Status
+	result := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplication{}).
+		Where("id = ? AND status = ?", existing.ID, expectedStatus).
+		Updates(map[string]any{
+			"acting_operator_id":      actingOperatorID,
+			"acting_reason":           normalized.ActingReason,
+			"payment_method_id":       paymentMethod.ID,
+			"payment_method_code":     paymentMethod.Code,
+			"payment_method_name":     paymentMethod.Name,
+			"paid_amount":             normalized.PaidAmount,
+			"payer_name":              normalized.PayerName,
+			"paid_at":                 normalized.PaidAt,
+			"external_transaction_no": normalized.ExternalTransactionNo,
+			"payment_voucher_keys":    model.StringJSONBArray(normalized.PaymentVoucherKeys),
+			"remark":                  normalized.Remark,
+			"status":                  constants.EmployeeCollectionApplicationStatusPending,
+			"decided_at":              nil,
+			"terminal_reason":         "",
+			"updater":                 caller.AccountID,
+		})
+	if result.Error != nil {
+		return nil, nil, errors.Wrap(errors.CodeDatabaseError, result.Error, "更新核销申请失败")
+	}
+	if result.RowsAffected != 1 {
+		return nil, nil, errors.New(errors.CodeConflict, "核销申请状态已变化，请刷新后重试")
+	}
+	existing.ActingOperatorID = actingOperatorID
+	existing.ActingReason = normalized.ActingReason
+	existing.PaymentMethodID = paymentMethod.ID
+	existing.PaymentMethodCode = paymentMethod.Code
+	existing.PaymentMethodName = paymentMethod.Name
+	existing.PaidAmount = normalized.PaidAmount
+	existing.PayerName = normalized.PayerName
+	existing.PaidAt = normalized.PaidAt
+	existing.ExternalTransactionNo = normalized.ExternalTransactionNo
+	existing.PaymentVoucherKeys = model.StringJSONBArray(normalized.PaymentVoucherKeys)
+	existing.Remark = normalized.Remark
+	existing.Status = constants.EmployeeCollectionApplicationStatusPending
+	existing.DecidedAt = nil
+	existing.TerminalReason = ""
+	existing.Updater = caller.AccountID
+	return existing, beforeData, nil
+}
+
+// buildAttempt 新增一条不可变审批尝试记录，冻结当次收款方式、外部付款、附件与账单分摊快照。
+func buildAttempt(
+	ctx context.Context,
+	tx *gorm.DB,
+	applicationID uint,
+	attemptNo int,
+	caller applicationCaller,
+	paymentMethod *model.EmployeeCollectionPaymentMethod,
+	normalized employeecollectiondomain.NormalizedApplicationInput,
+	bills map[uint]*model.EmployeeCollectionBill,
+	items []ApplicationAllocationCommand,
+) (*model.EmployeeCollectionApplicationAttempt, error) {
+	snapshot, err := allocationSnapshot(bills, items)
+	if err != nil {
+		return nil, err
+	}
+	attempt := &model.EmployeeCollectionApplicationAttempt{
+		ApplicationID: applicationID, AttemptNo: attemptNo,
+		PaymentMethodID: paymentMethod.ID, PaymentMethodCode: paymentMethod.Code, PaymentMethodName: paymentMethod.Name,
+		PaidAmount: normalized.PaidAmount, PayerName: normalized.PayerName, PaidAt: normalized.PaidAt,
+		ExternalTransactionNo: normalized.ExternalTransactionNo,
+		PaymentVoucherKeys:    model.StringJSONBArray(normalized.PaymentVoucherKeys),
+		Remark:                normalized.Remark, SubmittedByAccountID: caller.AccountID,
+		ActingReason: normalized.ActingReason, AllocationSnapshot: snapshot,
+	}
+	if err := tx.WithContext(ctx).Create(attempt).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "创建核销审批尝试记录失败")
+	}
+	return attempt, nil
+}
+
+// allocationSnapshot 生成账单分摊快照，只保存账单摘要与金额，不含付款凭证内容。
+func allocationSnapshot(
+	bills map[uint]*model.EmployeeCollectionBill,
+	items []ApplicationAllocationCommand,
+) ([]byte, error) {
+	entries := make([]map[string]any, 0, len(items))
+	for _, item := range items {
+		bill := bills[item.BillID]
+		entries = append(entries, map[string]any{
+			"bill_id": bill.ID, "source_type": bill.SourceType, "source_no": bill.SourceNo,
+			"bill_status": bill.Status, "receivable_amount": bill.ReceivableAmount,
+			"received_amount": bill.ReceivedAmount, "reserved_amount": bill.ReservedAmount,
+			"amount": item.Amount,
+		})
+	}
+	payload, err := sonic.Marshal(entries)
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "序列化账单分摊快照失败")
+	}
+	return payload, nil
+}
+
+// approvalSnapshots 生成通用审批的提交人快照与企业微信表单业务快照。
+// 表单快照必须包含审批人核验所需的付款信息，因此保留经人工确认的完整外部流水号。
+func approvalSnapshots(
+	applicationID uint,
+	caller applicationCaller,
+	paymentMethod *model.EmployeeCollectionPaymentMethod,
+	normalized employeecollectiondomain.NormalizedApplicationInput,
+	bills map[uint]*model.EmployeeCollectionBill,
+	items []ApplicationAllocationCommand,
+) ([]byte, []byte, error) {
+	submitterSnapshot, err := sonic.Marshal(map[string]any{
+		"account_id": caller.AccountID, "account_name": caller.AccountName,
+	})
+	if err != nil {
+		return nil, nil, errors.Wrap(errors.CodeInternalError, err, "编码核销申请提交人快照失败")
+	}
+	requestSnapshot, err := sonic.Marshal(map[string]any{
+		constants.ApprovalFieldCollectionApplicationID:         applicationID,
+		constants.ApprovalFieldCollectionPaymentMethod:         paymentMethod.Name,
+		constants.ApprovalFieldCollectionPaidAmount:            formatAmountYuan(normalized.PaidAmount),
+		constants.ApprovalFieldCollectionPaidAmountCent:        normalized.PaidAmount,
+		constants.ApprovalFieldCollectionPayerName:             normalized.PayerName,
+		constants.ApprovalFieldCollectionPaidAt:                normalized.PaidAt.Format(time.RFC3339),
+		constants.ApprovalFieldCollectionExternalTransactionNo: normalized.ExternalTransactionNo,
+		constants.ApprovalFieldPaymentVoucherKey:               normalized.PaymentVoucherKeys,
+		constants.ApprovalFieldRemark:                          normalized.Remark,
+		constants.ApprovalFieldSubmitterID:                     caller.AccountID,
+		constants.ApprovalFieldSubmitterName:                   caller.AccountName,
+		constants.ApprovalFieldCollectionBillCount:             len(items),
+		constants.ApprovalFieldCollectionBillSummary:           allocationSummary(bills, items),
+	})
+	if err != nil {
+		return nil, nil, errors.Wrap(errors.CodeInternalError, err, "编码核销审批业务快照失败")
+	}
+	return submitterSnapshot, requestSnapshot, nil
+}
+
+// allocationSummary 生成给审批人阅读的账单分摊摘要。
+func allocationSummary(bills map[uint]*model.EmployeeCollectionBill, items []ApplicationAllocationCommand) string {
+	parts := make([]string, 0, len(items))
+	for _, item := range items {
+		bill := bills[item.BillID]
+		parts = append(parts, fmt.Sprintf("账单%d（%s）应收%s 本次分摊%s",
+			bill.ID, bill.SourceNo, formatAmountYuan(bill.ReceivableAmount), formatAmountYuan(item.Amount)))
+	}
+	return strings.Join(parts, "；")
+}
+
+// formatAmountYuan 将分金额格式化为元字符串，仅用于展示与审批表单。
+func formatAmountYuan(amount int64) string {
+	return fmt.Sprintf("%d.%02d", amount/100, amount%100)
+}
+
+// attachAttemptInstance 把审批实例 ID 回写到本次审批尝试记录，写入一次后不可修改。
+func attachAttemptInstance(ctx context.Context, tx *gorm.DB, attempt *model.EmployeeCollectionApplicationAttempt, instanceID uint) error {
+	result := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplicationAttempt{}).
+		Where("id = ? AND approval_instance_id IS NULL", attempt.ID).
+		Update("approval_instance_id", instanceID)
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "关联核销审批实例失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "核销审批实例关联已变化")
+	}
+	attempt.ApprovalInstanceID = &instanceID
+	return nil
+}
+
+// updateApplicationLatest 更新申请的最新审批尝试与审批实例引用，仅用于展示。
+func updateApplicationLatest(
+	ctx context.Context,
+	tx *gorm.DB,
+	application *model.EmployeeCollectionApplication,
+	attempt *model.EmployeeCollectionApplicationAttempt,
+	instanceID uint,
+) error {
+	result := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplication{}).
+		Where("id = ?", application.ID).
+		Updates(map[string]any{
+			"latest_attempt_id": attempt.ID, "latest_approval_instance_id": instanceID,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "更新核销申请最新审批实例失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "核销申请最新审批实例更新已变化")
+	}
+	application.LatestAttemptID = attempt.ID
+	application.LatestApprovalInstanceID = instanceID
+	return nil
+}
+
+// createAllocations 写入分摊行并按账单 ID 升序预占余额。
+// 预占使用条件更新并要求 RowsAffected 为 1，避免并发申请超额占用同一账单。
+func createAllocations(
+	ctx context.Context,
+	tx *gorm.DB,
+	applicationID uint,
+	attemptID uint,
+	caller applicationCaller,
+	bills map[uint]*model.EmployeeCollectionBill,
+	items []ApplicationAllocationCommand,
+) ([]*model.EmployeeCollectionApplicationAllocation, []*model.EmployeeCollectionBill, error) {
+	allocations := make([]*model.EmployeeCollectionApplicationAllocation, 0, len(items))
+	reservedBills := make([]*model.EmployeeCollectionBill, 0, len(items))
+	for _, item := range items {
+		bill := bills[item.BillID]
+		allocation := &model.EmployeeCollectionApplicationAllocation{
+			ApplicationID: applicationID, AttemptID: attemptID, BillID: bill.ID,
+			Amount: item.Amount, Status: constants.EmployeeCollectionAllocationStatusPending,
+			Creator: caller.AccountID, Updater: caller.AccountID,
+		}
+		if err := tx.WithContext(ctx).Create(allocation).Error; err != nil {
+			return nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "写入核销分摊失败")
+		}
+		result := tx.WithContext(ctx).Model(&model.EmployeeCollectionBill{}).
+			Where("id = ? AND reserved_amount + ? <= receivable_amount - received_amount", bill.ID, item.Amount).
+			Updates(map[string]any{
+				"reserved_amount": gorm.Expr("reserved_amount + ?", item.Amount),
+				"updater":         caller.AccountID,
+			})
+		if result.Error != nil {
+			return nil, nil, errors.Wrap(errors.CodeDatabaseError, result.Error, "预占账单可核销余额失败")
+		}
+		if result.RowsAffected != 1 {
+			return nil, nil, errors.New(errors.CodeEmployeeCollectionAllocationExceeded)
+		}
+		bill.ReservedAmount += item.Amount
+		allocations = append(allocations, allocation)
+		reservedBills = append(reservedBills, bill)
+	}
+	return allocations, reservedBills, nil
+}
+
+// applicationAuditSnapshot 生成申请审计快照，外部交易流水号按脱敏值记录。
+func applicationAuditSnapshot(application *model.EmployeeCollectionApplication) map[string]any {
+	return map[string]any{
+		"id": application.ID, "applicant_account_id": application.ApplicantAccountID,
+		"acting_operator_id": application.ActingOperatorID,
+		"payment_method_id":  application.PaymentMethodID, "payment_method_code": application.PaymentMethodCode,
+		"paid_amount": application.PaidAmount, "payer_name": application.PayerName,
+		"external_transaction_no_masked": employeecollectiondomain.MaskExternalTransactionNo(application.ExternalTransactionNo),
+		"voucher_count":                  len(application.PaymentVoucherKeys),
+		"status":                         application.Status,
+		"latest_attempt_id":              application.LatestAttemptID,
+		"latest_approval_instance_id":    application.LatestApprovalInstanceID,
+	}
+}

internal/application/employeecollection/application_audit.go

@@ -0,0 +1,37 @@
+package employeecollection
+
+import (
+	"context"
+
+	"gorm.io/gorm"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+)
+
+// ApplicationAudit 描述核销申请、审批尝试记录与受影响账单的事实变化。
+type ApplicationAudit struct {
+	// EventID 是审计事件稳定标识，同一业务事实重复重放时保持相同值。
+	EventID string
+	// ActionCode 是已注册的核销申请审计动作码。
+	ActionCode string
+	// Summary 是给人工阅读的中文摘要。
+	Summary string
+	// Application 是本次动作后的核销申请事实。
+	Application *model.EmployeeCollectionApplication
+	// Attempt 是本次动作对应的审批尝试记录。
+	Attempt *model.EmployeeCollectionApplicationAttempt
+	// Allocations 是本次动作涉及的分摊事实。
+	Allocations []*model.EmployeeCollectionApplicationAllocation
+	// Bills 是本次动作影响的员工代收款账单事实。
+	Bills []*model.EmployeeCollectionBill
+	// BeforeData 与 AfterData 是脱敏前后的字段快照，不得包含付款凭证内容。
+	BeforeData map[string]any
+	AfterData  map[string]any
+	// CorrelationID 是申请链路标识。
+	CorrelationID string
+}
+
+// ApplicationAuditWriter 在员工代收款核销事务内追加统一 Audit Event。
+type ApplicationAuditWriter interface {
+	WriteEmployeeCollectionApplication(ctx context.Context, tx *gorm.DB, change ApplicationAudit) error
+}

internal/application/employeecollection/approval_decision.go

@@ -0,0 +1,501 @@
+package employeecollection
+
+import (
+	"context"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	approvalapp "github.com/break/junhong_cmp_fiber/internal/application/approval"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/auditcontext"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// ApprovalDecisionHandler 将渠道无关企业微信审批终态应用到员工代收款核销申请。
+// 通过才增加账单已核销金额，驳回才释放预占；重复、乱序或延迟回调都不重复入账。
+type ApprovalDecisionHandler struct {
+	db    *gorm.DB
+	audit ApplicationAuditWriter
+}
+
+// NewApprovalDecisionHandler 创建员工代收款核销审批终态消费者。
+func NewApprovalDecisionHandler(db *gorm.DB, audit ApplicationAuditWriter) *ApprovalDecisionHandler {
+	return &ApprovalDecisionHandler{db: db, audit: audit}
+}
+
+// Handle 幂等消费标准审批终态。
+// 业务标识为审批尝试记录主键：先锁定尝试记录并校验审批实例一致，再按申请与账单 ID 升序加锁。
+func (h *ApprovalDecisionHandler) Handle(ctx context.Context, event approvalapp.TerminalDecisionEvent) error {
+	if h == nil || h.db == nil || h.audit == nil {
+		return errors.New(errors.CodeInternalError, "员工代收款核销审批终态能力未配置")
+	}
+	if event.BusinessType != constants.ApprovalBusinessTypeEmployeeCollection || event.BusinessID == 0 || event.InstanceID == 0 {
+		return errors.New(errors.CodeInvalidParam, "员工代收款核销审批终态参数无效")
+	}
+	ctx = auditcontext.With(ctx, auditcontext.Context{CorrelationID: event.CorrelationID, ParentEventID: event.EventID})
+	return h.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var attempt model.EmployeeCollectionApplicationAttempt
+		if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).
+			First(&attempt, event.BusinessID).Error; err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return errors.New(errors.CodeNotFound, "核销审批尝试记录不存在")
+			}
+			return errors.Wrap(errors.CodeDatabaseError, err, "锁定核销审批尝试记录失败")
+		}
+		if attempt.ApprovalInstanceID == nil || *attempt.ApprovalInstanceID != event.InstanceID {
+			return errors.New(errors.CodeConflict, "核销审批尝试记录关联的审批实例不一致")
+		}
+		application, err := lockApplication(ctx, tx, attempt.ApplicationID)
+		if err != nil {
+			return err
+		}
+		if application.LatestAttemptID != attempt.ID {
+			// 已被更新尝试取代的历史尝试终态不再改变申请事实。
+			return nil
+		}
+		switch event.Decision {
+		case constants.ApprovalDecisionApproved:
+			return h.applyApproved(ctx, tx, application, &attempt, event)
+		case constants.ApprovalDecisionRejected:
+			return h.applyClosed(ctx, tx, application, &attempt, event,
+				constants.EmployeeCollectionApplicationStatusRejected, "企业微信审批已驳回")
+		case constants.ApprovalDecisionCancelled:
+			return h.applyClosed(ctx, tx, application, &attempt, event,
+				constants.EmployeeCollectionApplicationStatusRevoked, "企业微信审批已撤销")
+		case constants.ApprovalDecisionDeleted:
+			return h.applyClosed(ctx, tx, application, &attempt, event,
+				constants.EmployeeCollectionApplicationStatusRevoked, "企业微信审批已删除")
+		case constants.ApprovalDecisionRevokedAfterApproved:
+			return h.applyRevoked(ctx, tx, application, &attempt, event)
+		default:
+			return errors.New(errors.CodeInvalidParam, "不支持的核销申请审批终态")
+		}
+	})
+}
+
+// applyApproved 将本次尝试的全部预占分摊转入已核销并重算账单状态。
+// 仅当申请仍处于审批中时推进，重复或乱序回调不重复增加已核销金额。
+func (h *ApprovalDecisionHandler) applyApproved(
+	ctx context.Context,
+	tx *gorm.DB,
+	application *model.EmployeeCollectionApplication,
+	attempt *model.EmployeeCollectionApplicationAttempt,
+	event approvalapp.TerminalDecisionEvent,
+) error {
+	if application.Status != constants.EmployeeCollectionApplicationStatusPending {
+		return nil
+	}
+	allocations, err := loadAttemptAllocations(ctx, tx, attempt.ID)
+	if err != nil {
+		return err
+	}
+	if _, err := lockBillsInAscendingOrder(ctx, tx, allocationCommandsOf(allocations)); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	for _, allocation := range allocations {
+		if err := approveAllocation(ctx, tx, allocation, now); err != nil {
+			return err
+		}
+		if err := settleBillReservation(ctx, tx, allocation); err != nil {
+			return err
+		}
+	}
+	result := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplication{}).
+		Where("id = ? AND status = ?", application.ID, constants.EmployeeCollectionApplicationStatusPending).
+		Updates(map[string]any{
+			"status":     constants.EmployeeCollectionApplicationStatusApproved,
+			"decided_at": now, "updater": 0,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "标记核销申请已通过失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "核销申请状态已变化")
+	}
+	before := application.Status
+	application.Status = constants.EmployeeCollectionApplicationStatusApproved
+	application.DecidedAt = &now
+	application.Updater = 0
+	bills, err := reloadBills(ctx, tx, allocationCommandsOf(allocations))
+	if err != nil {
+		return err
+	}
+	approvedEventID, err := decisionEventID(application.ID, attempt.AttemptNo, "approved")
+	if err != nil {
+		return err
+	}
+	return h.audit.WriteEmployeeCollectionApplication(ctx, tx, ApplicationAudit{
+		EventID:     approvedEventID,
+		ActionCode:  constants.AuditActionEmployeeCollectionApplicationApproved,
+		Summary:     "企业微信审批通过，核销分摊转入已核销",
+		Application: application, Attempt: attempt, Allocations: allocations, Bills: bills,
+		BeforeData: map[string]any{"status": before},
+		AfterData:  applicationAuditSnapshot(application), CorrelationID: event.CorrelationID,
+	})
+}
+
+// applyClosed 处理最终驳回与渠道撤销、删除：释放全部预占并把申请置为对应终态。
+func (h *ApprovalDecisionHandler) applyClosed(
+	ctx context.Context,
+	tx *gorm.DB,
+	application *model.EmployeeCollectionApplication,
+	attempt *model.EmployeeCollectionApplicationAttempt,
+	event approvalapp.TerminalDecisionEvent,
+	targetStatus int,
+	reason string,
+) error {
+	if application.Status != constants.EmployeeCollectionApplicationStatusPending {
+		return nil
+	}
+	allocations, err := loadAttemptAllocations(ctx, tx, attempt.ID)
+	if err != nil {
+		return err
+	}
+	if _, err := lockBillsInAscendingOrder(ctx, tx, allocationCommandsOf(allocations)); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	for _, allocation := range allocations {
+		if err := releaseAllocation(ctx, tx, allocation, now); err != nil {
+			return err
+		}
+		if err := releaseBillReservation(ctx, tx, allocation); err != nil {
+			return err
+		}
+	}
+	terminalReason := ""
+	if targetStatus == constants.EmployeeCollectionApplicationStatusRevoked {
+		terminalReason = reason
+	}
+	result := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplication{}).
+		Where("id = ? AND status = ?", application.ID, constants.EmployeeCollectionApplicationStatusPending).
+		Updates(map[string]any{
+			"status": targetStatus, "decided_at": now,
+			"terminal_reason": terminalReason, "updater": 0,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "更新核销申请终态失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "核销申请状态已变化")
+	}
+	before := application.Status
+	application.Status = targetStatus
+	application.DecidedAt = &now
+	application.TerminalReason = terminalReason
+	application.Updater = 0
+	bills, err := reloadBills(ctx, tx, allocationCommandsOf(allocations))
+	if err != nil {
+		return err
+	}
+	closedEventID, err := decisionEventID(application.ID, attempt.AttemptNo, decisionEventSuffix(event.Decision))
+	if err != nil {
+		return err
+	}
+	return h.audit.WriteEmployeeCollectionApplication(ctx, tx, ApplicationAudit{
+		EventID:     closedEventID,
+		ActionCode:  constants.AuditActionEmployeeCollectionApplicationRejected,
+		Summary:     "企业微信审批未通过，核销申请预占已释放",
+		Application: application, Attempt: attempt, Allocations: allocations, Bills: bills,
+		BeforeData: map[string]any{"status": before},
+		AfterData:  applicationAuditSnapshot(application), CorrelationID: event.CorrelationID,
+	})
+}
+
+// applyRevoked 处理通过后撤销。
+// 申请已通过：不回滚已核销金额，只转异常终态并禁止自动重提。
+// 申请仍在审批中（渠道乱序投递）：释放全部审批中预占并转异常终态，避免预占永久占用账单。
+func (h *ApprovalDecisionHandler) applyRevoked(
+	ctx context.Context,
+	tx *gorm.DB,
+	application *model.EmployeeCollectionApplication,
+	attempt *model.EmployeeCollectionApplicationAttempt,
+	event approvalapp.TerminalDecisionEvent,
+) error {
+	switch application.Status {
+	case constants.EmployeeCollectionApplicationStatusApproved:
+		return h.revokeApproved(ctx, tx, application, attempt, event)
+	case constants.EmployeeCollectionApplicationStatusPending:
+		return h.revokePending(ctx, tx, application, attempt, event)
+	default:
+		// 已驳回、已撤销等终态不再改变事实。
+		return nil
+	}
+}
+
+// revokeApproved 在已通过态撤销：保留已核销金额，仅转异常终态。
+func (h *ApprovalDecisionHandler) revokeApproved(
+	ctx context.Context,
+	tx *gorm.DB,
+	application *model.EmployeeCollectionApplication,
+	attempt *model.EmployeeCollectionApplicationAttempt,
+	event approvalapp.TerminalDecisionEvent,
+) error {
+	now := time.Now().UTC()
+	terminalReason := "企业微信通过后撤销"
+	result := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplication{}).
+		Where("id = ? AND status = ?", application.ID, constants.EmployeeCollectionApplicationStatusApproved).
+		Updates(map[string]any{
+			"status":     constants.EmployeeCollectionApplicationStatusRevoked,
+			"decided_at": now, "terminal_reason": terminalReason, "updater": 0,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "标记核销申请通过后撤销失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "核销申请状态已变化")
+	}
+	before := application.Status
+	application.Status = constants.EmployeeCollectionApplicationStatusRevoked
+	application.DecidedAt = &now
+	application.TerminalReason = terminalReason
+	application.Updater = 0
+	allocations, err := loadAttemptAllocations(ctx, tx, attempt.ID)
+	if err != nil {
+		return err
+	}
+	bills, err := reloadBills(ctx, tx, allocationCommandsOf(allocations))
+	if err != nil {
+		return err
+	}
+	revokedEventID, err := decisionEventID(application.ID, attempt.AttemptNo, "revoked")
+	if err != nil {
+		return err
+	}
+	return h.audit.WriteEmployeeCollectionApplication(ctx, tx, ApplicationAudit{
+		EventID:     revokedEventID,
+		ActionCode:  constants.AuditActionEmployeeCollectionApplicationRevoked,
+		Summary:     "企业微信通过后撤销，已核销金额不回滚",
+		Application: application, Attempt: attempt, Allocations: allocations, Bills: bills,
+		BeforeData: map[string]any{"status": before},
+		AfterData:  applicationAuditSnapshot(application), CorrelationID: event.CorrelationID,
+	})
+}
+
+// revokePending 在审批中态撤销：释放全部审批中预占并转异常终态。
+func (h *ApprovalDecisionHandler) revokePending(
+	ctx context.Context,
+	tx *gorm.DB,
+	application *model.EmployeeCollectionApplication,
+	attempt *model.EmployeeCollectionApplicationAttempt,
+	event approvalapp.TerminalDecisionEvent,
+) error {
+	allocations, err := loadAttemptAllocations(ctx, tx, attempt.ID)
+	if err != nil {
+		return err
+	}
+	if _, err := lockBillsInAscendingOrder(ctx, tx, allocationCommandsOf(allocations)); err != nil {
+		return err
+	}
+	now := time.Now().UTC()
+	for _, allocation := range allocations {
+		if err := releaseAllocation(ctx, tx, allocation, now); err != nil {
+			return err
+		}
+		if err := releaseBillReservation(ctx, tx, allocation); err != nil {
+			return err
+		}
+	}
+	terminalReason := "企业微信通过后在本地审批中状态被撤销"
+	result := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplication{}).
+		Where("id = ? AND status = ?", application.ID, constants.EmployeeCollectionApplicationStatusPending).
+		Updates(map[string]any{
+			"status":     constants.EmployeeCollectionApplicationStatusRevoked,
+			"decided_at": now, "terminal_reason": terminalReason, "updater": 0,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "标记核销申请撤销失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "核销申请状态已变化")
+	}
+	before := application.Status
+	application.Status = constants.EmployeeCollectionApplicationStatusRevoked
+	application.DecidedAt = &now
+	application.TerminalReason = terminalReason
+	application.Updater = 0
+	bills, err := reloadBills(ctx, tx, allocationCommandsOf(allocations))
+	if err != nil {
+		return err
+	}
+	revokedEventID, err := decisionEventID(application.ID, attempt.AttemptNo, "revoked")
+	if err != nil {
+		return err
+	}
+	return h.audit.WriteEmployeeCollectionApplication(ctx, tx, ApplicationAudit{
+		EventID:     revokedEventID,
+		ActionCode:  constants.AuditActionEmployeeCollectionApplicationRevoked,
+		Summary:     "企业微信通过后撤销，申请仍在审批中，已释放预占",
+		Application: application, Attempt: attempt, Allocations: allocations, Bills: bills,
+		BeforeData: map[string]any{"status": before},
+		AfterData:  applicationAuditSnapshot(application), CorrelationID: event.CorrelationID,
+	})
+}
+
+// loadAttemptAllocations 按账单 ID 升序读取本次尝试的分摊，保证后续加锁与写入次序唯一。
+func loadAttemptAllocations(ctx context.Context, tx *gorm.DB, attemptID uint) ([]*model.EmployeeCollectionApplicationAllocation, error) {
+	var allocations []model.EmployeeCollectionApplicationAllocation
+	if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("attempt_id = ?", attemptID).Order("bill_id ASC, id ASC").Find(&allocations).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询核销审批尝试分摊失败")
+	}
+	if len(allocations) == 0 {
+		return nil, errors.New(errors.CodeConflict, "核销审批尝试记录缺少分摊事实")
+	}
+	result := make([]*model.EmployeeCollectionApplicationAllocation, 0, len(allocations))
+	for index := range allocations {
+		result = append(result, &allocations[index])
+	}
+	return result, nil
+}
+
+// allocationCommandsOf 提取分摊涉及的账单与金额，用于复用升序加锁函数。
+func allocationCommandsOf(allocations []*model.EmployeeCollectionApplicationAllocation) []ApplicationAllocationCommand {
+	items := make([]ApplicationAllocationCommand, 0, len(allocations))
+	for _, allocation := range allocations {
+		items = append(items, ApplicationAllocationCommand{BillID: allocation.BillID, Amount: allocation.Amount})
+	}
+	return items
+}
+
+// approveAllocation 把分摊从审批中预占条件更新为已通过；重复处理时返回冲突。
+func approveAllocation(
+	ctx context.Context,
+	tx *gorm.DB,
+	allocation *model.EmployeeCollectionApplicationAllocation,
+	now time.Time,
+) error {
+	result := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplicationAllocation{}).
+		Where("id = ? AND status = ?", allocation.ID, constants.EmployeeCollectionAllocationStatusPending).
+		Updates(map[string]any{
+			"status": constants.EmployeeCollectionAllocationStatusApproved, "released_at": now, "updater": 0,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "标记核销分摊已通过失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "核销分摊状态已变化")
+	}
+	allocation.Status = constants.EmployeeCollectionAllocationStatusApproved
+	allocation.ReleasedAt = &now
+	return nil
+}
+
+// releaseAllocation 把分摊从审批中预占条件更新为已释放；重复处理时返回冲突。
+func releaseAllocation(
+	ctx context.Context,
+	tx *gorm.DB,
+	allocation *model.EmployeeCollectionApplicationAllocation,
+	now time.Time,
+) error {
+	result := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplicationAllocation{}).
+		Where("id = ? AND status = ?", allocation.ID, constants.EmployeeCollectionAllocationStatusPending).
+		Updates(map[string]any{
+			"status": constants.EmployeeCollectionAllocationStatusReleased, "released_at": now, "updater": 0,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "释放核销分摊预占失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "核销分摊状态已变化")
+	}
+	allocation.Status = constants.EmployeeCollectionAllocationStatusReleased
+	allocation.ReleasedAt = &now
+	return nil
+}
+
+// settleBillReservation 将账单预占转为已核销并重算账单状态。
+// 条件更新要求账单预占不小于分摊金额，并检查 RowsAffected，避免并发下重复入账。
+func settleBillReservation(
+	ctx context.Context,
+	tx *gorm.DB,
+	allocation *model.EmployeeCollectionApplicationAllocation,
+) error {
+	result := tx.WithContext(ctx).Model(&model.EmployeeCollectionBill{}).
+		Where("id = ? AND reserved_amount >= ?", allocation.BillID, allocation.Amount).
+		Updates(map[string]any{
+			"received_amount": gorm.Expr("received_amount + ?", allocation.Amount),
+			"reserved_amount": gorm.Expr("reserved_amount - ?", allocation.Amount),
+			"status": gorm.Expr(
+				"CASE WHEN received_amount + ? >= receivable_amount THEN ?::smallint WHEN received_amount + ? > 0 THEN ?::smallint ELSE ?::smallint END",
+				allocation.Amount, constants.EmployeeCollectionBillStatusSettled,
+				allocation.Amount, constants.EmployeeCollectionBillStatusPartial,
+				constants.EmployeeCollectionBillStatusPending,
+			),
+			"updater": 0,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "账单预占转入已核销失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "账单预占已变化，核销未入账")
+	}
+	return nil
+}
+
+// releaseBillReservation 释放账单预占金额，条件更新并检查 RowsAffected。
+func releaseBillReservation(
+	ctx context.Context,
+	tx *gorm.DB,
+	allocation *model.EmployeeCollectionApplicationAllocation,
+) error {
+	result := tx.WithContext(ctx).Model(&model.EmployeeCollectionBill{}).
+		Where("id = ? AND reserved_amount >= ?", allocation.BillID, allocation.Amount).
+		Updates(map[string]any{
+			"reserved_amount": gorm.Expr("reserved_amount - ?", allocation.Amount),
+			"updater":         0,
+		})
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "释放账单预占失败")
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "账单预占已变化")
+	}
+	return nil
+}
+
+// reloadBills 重新读取受影响账单，保证审计快照反映终态金额。
+// 账单行已在同一事务内持有排他锁，这里只做一次按 ID 升序的普通读取。
+func reloadBills(
+	ctx context.Context,
+	tx *gorm.DB,
+	items []ApplicationAllocationCommand,
+) ([]*model.EmployeeCollectionBill, error) {
+	billIDs := make([]uint, 0, len(items))
+	for _, item := range items {
+		billIDs = append(billIDs, item.BillID)
+	}
+	var bills []model.EmployeeCollectionBill
+	if err := tx.WithContext(ctx).Where("id IN ?", billIDs).Order("id ASC").Find(&bills).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询受影响员工代收款账单失败")
+	}
+	result := make([]*model.EmployeeCollectionBill, 0, len(bills))
+	for index := range bills {
+		result = append(result, &bills[index])
+	}
+	return result, nil
+}
+
+// decisionEventID 生成审批终态审计事件的稳定标识，并约束在审计列宽内。
+func decisionEventID(applicationID uint, attemptNo int, suffix string) (string, error) {
+	return composeAuditEventID(
+		"employee_collection", "application", uintText(applicationID), "attempt", intText(attemptNo), suffix)
+}
+
+// decisionEventSuffix 把渠道决策映射为审计事件后缀。
+func decisionEventSuffix(decision string) string {
+	switch decision {
+	case constants.ApprovalDecisionRejected:
+		return "rejected"
+	case constants.ApprovalDecisionCancelled:
+		return "cancelled"
+	case constants.ApprovalDecisionDeleted:
+		return "deleted"
+	default:
+		return "closed"
+	}
+}

internal/application/employeecollection/audit_event.go

@@ -0,0 +1,31 @@
+package employeecollection
+
+import (
+	"strconv"
+	"strings"
+
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// auditEventMaxLength 是统一审计事件标识的列宽上限，与 tb_audit_event.event_id 保持一致。
+const auditEventMaxLength = 64
+
+// composeAuditEventID 以冒号连接业务标识片段，生成确定性的审计事件标识。
+// 超出审计列宽时返回稳定错误，避免写入时分段截断或事务被数据库拒绝。
+func composeAuditEventID(parts ...string) (string, error) {
+	eventID := strings.Join(parts, ":")
+	if len(eventID) > auditEventMaxLength {
+		return "", errors.New(errors.CodeInternalError, "审计事件标识超出长度限制")
+	}
+	return eventID, nil
+}
+
+// uintText 将主键转为审计标识片段。
+func uintText(value uint) string {
+	return strconv.FormatUint(uint64(value), 10)
+}
+
+// intText 将序号转为审计标识片段。
+func intText(value int) string {
+	return strconv.Itoa(value)
+}

internal/application/employeecollection/bill_close.go

@@ -0,0 +1,118 @@
+package employeecollection
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	employeecollectiondomain "github.com/break/junhong_cmp_fiber/internal/domain/employeecollection"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// BillCloseService 关闭员工代收款账单。
+// 仅超级管理员可关闭，且只允许关闭仍待核销或部分核销、且不存在审批中分摊的账单。
+type BillCloseService struct {
+	db    *gorm.DB
+	audit BillAuditWriter
+}
+
+// NewBillCloseService 创建账单关闭事务脚本。
+func NewBillCloseService(db *gorm.DB, audit BillAuditWriter) *BillCloseService {
+	return &BillCloseService{db: db, audit: audit}
+}
+
+// Close 关闭账单：作废未核销余额、保留已核销金额，并在同一事务内写关闭审计。
+// 并发关闭通过行锁加 expected-status 条件更新兜底，状态已变化时返回冲突。
+func (s *BillCloseService) Close(ctx context.Context, id uint, reason string) (*model.EmployeeCollectionBill, error) {
+	operatorID, err := requireSuperAdmin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if s == nil || s.db == nil || s.audit == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "账单关闭能力尚未配置")
+	}
+	if id == 0 {
+		return nil, errors.New(errors.CodeEmployeeCollectionBillNotFound)
+	}
+	closeReason := strings.TrimSpace(reason)
+	var closed *model.EmployeeCollectionBill
+	err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		bill, err := lockBill(ctx, tx, id)
+		if err != nil {
+			return err
+		}
+		var pendingAllocations int64
+		if err := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplicationAllocation{}).
+			Where("bill_id = ? AND status = ?", id, constants.EmployeeCollectionAllocationStatusPending).
+			Count(&pendingAllocations).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "统计账单审批中分摊失败")
+		}
+		if err := employeecollectiondomain.ValidateBillClose(employeecollectiondomain.BillCloseInput{
+			Status: bill.Status, PendingAllocations: pendingAllocations, Reason: closeReason,
+		}); err != nil {
+			return err
+		}
+		before := *bill
+		closedAt := time.Now().UTC()
+		result := tx.WithContext(ctx).Model(&model.EmployeeCollectionBill{}).
+			Where("id = ? AND status = ?", bill.ID, bill.Status).
+			Updates(map[string]any{
+				"status":        constants.EmployeeCollectionBillStatusClosed,
+				"closed_reason": closeReason,
+				"closed_at":     closedAt,
+				"updater":       operatorID,
+			})
+		if result.Error != nil {
+			return errors.Wrap(errors.CodeDatabaseError, result.Error, "关闭员工代收款账单失败")
+		}
+		if result.RowsAffected != 1 {
+			return errors.New(errors.CodeConflict, "账单状态已变化，请刷新后重试")
+		}
+		bill.Status = constants.EmployeeCollectionBillStatusClosed
+		bill.ClosedReason = closeReason
+		bill.ClosedAt = &closedAt
+		bill.Updater = operatorID
+		closeEventID, err := composeAuditEventID("employee_collection", "bill", uintText(bill.ID), "close")
+		if err != nil {
+			return err
+		}
+		if err := s.audit.WriteEmployeeCollectionBill(ctx, tx, BillAudit{
+			EventID:    closeEventID,
+			ActionCode: constants.AuditActionEmployeeCollectionBillClosed, Summary: "关闭员工代收款账单",
+			Bill: bill,
+			BeforeData: map[string]any{
+				"status": before.Status, "closed_reason": before.ClosedReason,
+			},
+			AfterData: map[string]any{
+				"status": bill.Status, "closed_reason": bill.ClosedReason,
+			},
+			CorrelationID: bill.SourceNo,
+		}); err != nil {
+			return err
+		}
+		closed = bill
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return closed, nil
+}
+
+// lockBill 以行锁读取账单，未找到返回稳定不存在错误。
+func lockBill(ctx context.Context, tx *gorm.DB, id uint) (*model.EmployeeCollectionBill, error) {
+	var bill model.EmployeeCollectionBill
+	if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).
+		First(&bill, id).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeEmployeeCollectionBillNotFound)
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "锁定员工代收款账单失败")
+	}
+	return &bill, nil
+}

internal/application/employeecollection/bill_creation.go

@@ -0,0 +1,233 @@
+package employeecollection
+
+import (
+	"context"
+
+	"github.com/bytedance/sonic"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	employeecollectiondomain "github.com/break/junhong_cmp_fiber/internal/domain/employeecollection"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// BillAudit 描述员工代收款账单事实的实际变化。
+type BillAudit struct {
+	// EventID 是审计事件稳定标识，同一业务事实重复重放时保持相同值。
+	EventID string
+	// ActionCode 是已注册的账单审计动作码。
+	ActionCode string
+	// Summary 是给人工阅读的中文摘要。
+	Summary string
+	// Bill 是本次动作后的账单事实。
+	Bill *model.EmployeeCollectionBill
+	// BeforeData 与 AfterData 是脱敏前后的字段快照。
+	BeforeData map[string]any
+	AfterData  map[string]any
+	// CorrelationID 是来源业务链路标识。
+	CorrelationID string
+}
+
+// BillAuditWriter 在员工代收款业务事务内追加统一 Audit Event。
+type BillAuditWriter interface {
+	WriteEmployeeCollectionBill(ctx context.Context, tx *gorm.DB, change BillAudit) error
+}
+
+// BillCreationService 在来源成功事务内按来源唯一键幂等创建员工代收款账单。
+// 建账只由来源成功事务携带的来源主键触发，不存在扫描历史订单或充值补建的路径。
+type BillCreationService struct {
+	audit BillAuditWriter
+}
+
+// NewBillCreationService 创建员工代收款建账用例。
+func NewBillCreationService(audit BillAuditWriter) *BillCreationService {
+	return &BillCreationService{audit: audit}
+}
+
+// CreateFromOrderInTx 在后台线下套餐订单激活事务内建账。
+// 判据见 employeecollectiondomain.ShouldCreateBillForOrder；不满足判据时返回 (nil, nil)。
+// 重复订单事务、重放或重试都命中 source_key 唯一约束并返回既有账单，不使订单事务失败。
+func (s *BillCreationService) CreateFromOrderInTx(
+	ctx context.Context,
+	tx *gorm.DB,
+	order *model.Order,
+	hasGiftPackage bool,
+) (*model.EmployeeCollectionBill, error) {
+	if s == nil || tx == nil || s.audit == nil {
+		return nil, errors.New(errors.CodeInternalError, "员工代收款建账用例未完整配置")
+	}
+	if order == nil || order.ID == 0 {
+		return nil, errors.New(errors.CodeInvalidParam, "员工代收款建账缺少来源订单")
+	}
+	if !employeecollectiondomain.ShouldCreateBillForOrder(
+		employeecollectiondomain.OrderBillSubjectFromOrder(order, hasGiftPackage)) {
+		return nil, nil
+	}
+	if order.OperatorAccountID == nil || *order.OperatorAccountID == 0 {
+		return nil, errors.New(errors.CodeInternalError, "线下套餐订单缺少欠款人账号")
+	}
+	debtorAccountID := *order.OperatorAccountID
+	debtorSnapshot, err := marshalSnapshot(map[string]any{
+		"account_id": debtorAccountID, "account_name": order.OperatorAccountName,
+		"account_type": order.OperatorAccountType,
+	})
+	if err != nil {
+		return nil, err
+	}
+	// shop_id 与 seller_shop_id 同时写入：店铺筛选统一读 shop_id，seller_shop_id 保留兼容口径。
+	customerSnapshot, err := marshalSnapshot(map[string]any{
+		"buyer_type": order.BuyerType, "buyer_id": order.BuyerID,
+		"buyer_nickname": order.BuyerNickname,
+		"shop_id":        order.SellerShopID, "seller_shop_id": order.SellerShopID,
+		"asset_identifier": order.AssetIdentifier,
+	})
+	if err != nil {
+		return nil, err
+	}
+	sourceKey := employeecollectiondomain.OrderSourceKey(order.ID)
+	bill := &model.EmployeeCollectionBill{
+		SourceType:       constants.EmployeeCollectionSourceTypeOrder,
+		SourceID:         order.ID,
+		SourceKey:        sourceKey,
+		SourceNo:         order.OrderNo,
+		DebtorAccountID:  debtorAccountID,
+		DebtorSnapshot:   debtorSnapshot,
+		CustomerSnapshot: customerSnapshot,
+		ReceivableAmount: *order.ActualPaidAmount,
+		Status:           constants.EmployeeCollectionBillStatusPending,
+		Creator:          debtorAccountID,
+		Updater:          debtorAccountID,
+	}
+	return s.persistInTx(ctx, tx, bill,
+		[]string{"employee_collection", "bill", "order", uintText(order.ID), "create"},
+		"后台线下套餐订单创建员工代收款账单", order.OrderNo)
+}
+
+// CreateFromRechargeInTx 在代理线下充值入账事务内建账。
+// 判据见 employeecollectiondomain.ShouldCreateBillForRecharge；欠款人为发起充值的后台账号。
+// 覆盖企业微信终审通过入账与后台人工确认入账两条入口，重复入账不重复建账。
+func (s *BillCreationService) CreateFromRechargeInTx(
+	ctx context.Context,
+	tx *gorm.DB,
+	record *model.AgentRechargeRecord,
+) (*model.EmployeeCollectionBill, error) {
+	if s == nil || tx == nil || s.audit == nil {
+		return nil, errors.New(errors.CodeInternalError, "员工代收款建账用例未完整配置")
+	}
+	if record == nil || record.ID == 0 {
+		return nil, errors.New(errors.CodeInvalidParam, "员工代收款建账缺少来源充值记录")
+	}
+	if !employeecollectiondomain.ShouldCreateBillForRecharge(employeecollectiondomain.RechargeBillSubject{
+		PaymentMethod: record.PaymentMethod, Amount: record.Amount,
+	}) {
+		return nil, nil
+	}
+	if record.UserID == 0 {
+		return nil, errors.New(errors.CodeInternalError, "线下充值记录缺少发起账号")
+	}
+	debtorName, err := rechargeAccountName(ctx, tx, record.UserID)
+	if err != nil {
+		return nil, err
+	}
+	debtorSnapshot, err := marshalSnapshot(map[string]any{
+		"account_id": record.UserID, "account_name": debtorName,
+		"account_type": model.OperatorAccountTypePlatform,
+	})
+	if err != nil {
+		return nil, err
+	}
+	customerSnapshot, err := marshalSnapshot(map[string]any{
+		"shop_id": record.ShopID, "agent_wallet_id": record.AgentWalletID,
+		"payment_method": record.PaymentMethod, "recharge_no": record.RechargeNo,
+	})
+	if err != nil {
+		return nil, err
+	}
+	sourceKey := employeecollectiondomain.RechargeSourceKey(record.ID)
+	bill := &model.EmployeeCollectionBill{
+		SourceType:       constants.EmployeeCollectionSourceTypeRecharge,
+		SourceID:         record.ID,
+		SourceKey:        sourceKey,
+		SourceNo:         record.RechargeNo,
+		DebtorAccountID:  record.UserID,
+		DebtorSnapshot:   debtorSnapshot,
+		CustomerSnapshot: customerSnapshot,
+		ReceivableAmount: record.Amount,
+		Status:           constants.EmployeeCollectionBillStatusPending,
+		Creator:          record.UserID,
+		Updater:          record.UserID,
+	}
+	return s.persistInTx(ctx, tx, bill,
+		[]string{"employee_collection", "bill", "recharge", uintText(record.ID), "create"},
+		"代理线下充值入账创建员工代收款账单", record.RechargeNo)
+}
+
+// persistInTx 以来源唯一键幂等写入账单：已存在同一来源账单时返回既有事实且不重复审计。
+func (s *BillCreationService) persistInTx(
+	ctx context.Context,
+	tx *gorm.DB,
+	bill *model.EmployeeCollectionBill,
+	eventIDParts []string,
+	summary string,
+	correlationID string,
+) (*model.EmployeeCollectionBill, error) {
+	eventID, err := composeAuditEventID(eventIDParts...)
+	if err != nil {
+		return nil, err
+	}
+	result := tx.WithContext(ctx).Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "source_key"}},
+		DoNothing: true,
+	}).Create(bill)
+	if result.Error != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, result.Error, "创建员工代收款账单失败")
+	}
+	if result.RowsAffected == 0 {
+		var existing model.EmployeeCollectionBill
+		if err := tx.WithContext(ctx).Where("source_key = ?", bill.SourceKey).First(&existing).Error; err != nil {
+			return nil, errors.Wrap(errors.CodeDatabaseError, err, "读取既有员工代收款账单失败")
+		}
+		return &existing, nil
+	}
+	if err := s.audit.WriteEmployeeCollectionBill(ctx, tx, BillAudit{
+		EventID: eventID, ActionCode: constants.AuditActionEmployeeCollectionBillCreated, Summary: summary,
+		Bill: bill, AfterData: billAuditSnapshot(bill), CorrelationID: correlationID,
+	}); err != nil {
+		return nil, err
+	}
+	return bill, nil
+}
+
+// marshalSnapshot 将只读业务快照序列化为 jsonb，快照不得包含付款凭证或外部交易敏感内容。
+func marshalSnapshot(snapshot map[string]any) ([]byte, error) {
+	payload, err := sonic.Marshal(snapshot)
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "序列化员工代收款账单快照失败")
+	}
+	return payload, nil
+}
+
+// rechargeAccountName 读取充值发起账号名称用于欠款人快照；账号已被删除时留空名称。
+func rechargeAccountName(ctx context.Context, tx *gorm.DB, accountID uint) (string, error) {
+	var account model.Account
+	if err := tx.WithContext(ctx).Unscoped().First(&account, accountID).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return "", nil
+		}
+		return "", errors.Wrap(errors.CodeDatabaseError, err, "查询线下充值发起账号失败")
+	}
+	return account.Username, nil
+}
+
+// billAuditSnapshot 生成账单审计快照，只包含 ID、来源、金额与状态，不含凭证内容。
+func billAuditSnapshot(bill *model.EmployeeCollectionBill) map[string]any {
+	return map[string]any{
+		"id": bill.ID, "source_type": bill.SourceType, "source_id": bill.SourceID,
+		"source_key": bill.SourceKey, "source_no": bill.SourceNo,
+		"debtor_account_id": bill.DebtorAccountID, "receivable_amount": bill.ReceivableAmount,
+		"received_amount": bill.ReceivedAmount, "reserved_amount": bill.ReservedAmount,
+		"status": bill.Status,
+	}
+}

internal/application/employeecollection/payment_method.go

@@ -0,0 +1,346 @@
+// Package employeecollection 收口员工代收款账单、核销申请与线下收款方式字典的写用例。
+// 写用例在事务内保存业务事实与审计事实，读取由 internal/query 提供。
+package employeecollection
+
+import (
+	"context"
+	stdErrors "errors"
+	"strconv"
+
+	"github.com/jackc/pgx/v5/pgconn"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	systemconfigapp "github.com/break/junhong_cmp_fiber/internal/application/systemconfig"
+	employeecollectiondomain "github.com/break/junhong_cmp_fiber/internal/domain/employeecollection"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+)
+
+// AuditWriter 接收员工代收款用例在业务事务内产生的配置审计事实。
+type AuditWriter interface {
+	WriteConfigChange(ctx context.Context, tx *gorm.DB, audit systemconfigapp.ChangeAudit) error
+}
+
+// PaymentMethodService 维护线下收款方式字典。
+// 已启用的字典项由其稳定编码对外，被核销申请引用后只可停用，不允许物理删除或改编码。
+type PaymentMethodService struct {
+	db    *gorm.DB
+	audit AuditWriter
+}
+
+// NewPaymentMethodService 创建线下收款方式字典事务脚本。
+func NewPaymentMethodService(db *gorm.DB, audit AuditWriter) *PaymentMethodService {
+	return &PaymentMethodService{db: db, audit: audit}
+}
+
+// Create 创建线下收款方式，并在同一事务内写入配置审计。
+func (s *PaymentMethodService) Create(
+	ctx context.Context,
+	request dto.CreateEmployeeCollectionPaymentMethodRequest,
+) (*dto.EmployeeCollectionPaymentMethodResponse, error) {
+	operatorID, err := requireSuperAdmin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if s == nil || s.db == nil || s.audit == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "线下收款方式维护能力尚未配置")
+	}
+	status := constants.EmployeeCollectionPaymentMethodStatusDisabled
+	if request.Enabled != nil && *request.Enabled {
+		status = constants.EmployeeCollectionPaymentMethodStatusEnabled
+	}
+	var sortOrder int64
+	if request.Sort != nil {
+		sortOrder = *request.Sort
+	}
+	normalized, err := employeecollectiondomain.NormalizePaymentMethodInput(employeecollectiondomain.PaymentMethodInput{
+		Code: request.Code, Name: request.Name, SortOrder: sortOrder, Status: status, Remark: request.Remark,
+	})
+	if err != nil {
+		return nil, err
+	}
+	paymentMethod := &model.EmployeeCollectionPaymentMethod{
+		Code: normalized.Code, Name: normalized.Name, SortOrder: normalized.SortOrder,
+		Status: normalized.Status, Remark: normalized.Remark,
+		BaseModel: model.BaseModel{Creator: operatorID, Updater: operatorID},
+	}
+	err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := ensurePaymentMethodCodeAvailable(ctx, tx, normalized.Code, 0); err != nil {
+			return err
+		}
+		if err := tx.WithContext(ctx).Create(paymentMethod).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "创建线下收款方式失败")
+		}
+		return s.audit.WriteConfigChange(ctx, tx, systemconfigapp.ChangeAudit{
+			OperatorID: operatorID, OperationType: constants.AuditOperationEmployeeCollectionPaymentMethodCreate,
+			Description: "创建线下收款方式", ConfigKey: paymentMethodAuditConfigKey(paymentMethod.ID),
+			Module: constants.EmployeeCollectionAuditModule, ResourceID: paymentMethodAuditResourceID(paymentMethod.ID),
+			DisplayName: paymentMethod.Name, Identity: paymentMethodAuditIdentity(paymentMethod),
+			AfterData: paymentMethodAuditSnapshot(paymentMethod), Result: constants.AuditResultSuccess,
+		})
+	})
+	if err != nil {
+		return nil, mapPaymentMethodCodeConflict(err)
+	}
+	return toPaymentMethodResponse(paymentMethod), nil
+}
+
+// Update 修改线下收款方式的名称、排序、启停与备注，并在未被引用时允许修改稳定编码。
+func (s *PaymentMethodService) Update(
+	ctx context.Context,
+	id uint,
+	request dto.UpdateEmployeeCollectionPaymentMethodRequest,
+) (*dto.EmployeeCollectionPaymentMethodResponse, error) {
+	operatorID, err := requireSuperAdmin(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if s == nil || s.db == nil || s.audit == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "线下收款方式维护能力尚未配置")
+	}
+	if id == 0 {
+		return nil, errors.New(errors.CodeEmployeeCollectionPaymentMethodNotFound)
+	}
+	var updated *model.EmployeeCollectionPaymentMethod
+	err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		paymentMethod, err := lockPaymentMethod(ctx, tx, id)
+		if err != nil {
+			return err
+		}
+		before := *paymentMethod
+		beforeData := paymentMethodAuditSnapshot(&before)
+
+		if request.Code != nil {
+			code := *request.Code
+			normalized, err := employeecollectiondomain.NormalizePaymentMethodInput(employeecollectiondomain.PaymentMethodInput{
+				Code: code, Name: paymentMethod.Name, SortOrder: paymentMethod.SortOrder,
+				Status: paymentMethod.Status, Remark: paymentMethod.Remark,
+			})
+			if err != nil {
+				return err
+			}
+			if normalized.Code != paymentMethod.Code {
+				referenced, err := countPaymentMethodReferences(ctx, tx, id)
+				if err != nil {
+					return err
+				}
+				if referenced > 0 {
+					return errors.New(errors.CodeEmployeeCollectionPaymentMethodReferenced,
+						"线下收款方式已被核销申请或代理充值申请引用，不能修改稳定编码")
+				}
+				if err := ensurePaymentMethodCodeAvailable(ctx, tx, normalized.Code, id); err != nil {
+					return err
+				}
+			}
+			paymentMethod.Code = normalized.Code
+		}
+		if request.Name != nil {
+			paymentMethod.Name = *request.Name
+		}
+		if request.Sort != nil {
+			paymentMethod.SortOrder = *request.Sort
+		}
+		if request.Enabled != nil {
+			if *request.Enabled {
+				paymentMethod.Status = constants.EmployeeCollectionPaymentMethodStatusEnabled
+			} else {
+				paymentMethod.Status = constants.EmployeeCollectionPaymentMethodStatusDisabled
+			}
+		}
+		if request.Remark != nil {
+			paymentMethod.Remark = *request.Remark
+		}
+		normalized, err := employeecollectiondomain.NormalizePaymentMethodInput(employeecollectiondomain.PaymentMethodInput{
+			Code: paymentMethod.Code, Name: paymentMethod.Name, SortOrder: paymentMethod.SortOrder,
+			Status: paymentMethod.Status, Remark: paymentMethod.Remark,
+		})
+		if err != nil {
+			return err
+		}
+		paymentMethod.Code = normalized.Code
+		paymentMethod.Name = normalized.Name
+		paymentMethod.SortOrder = normalized.SortOrder
+		paymentMethod.Status = normalized.Status
+		paymentMethod.Remark = normalized.Remark
+		paymentMethod.Updater = operatorID
+
+		if err := tx.WithContext(ctx).Save(paymentMethod).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "更新线下收款方式失败")
+		}
+		if err := s.audit.WriteConfigChange(ctx, tx, systemconfigapp.ChangeAudit{
+			OperatorID: operatorID, OperationType: constants.AuditOperationEmployeeCollectionPaymentMethodUpdate,
+			Description: "更新线下收款方式", ConfigKey: paymentMethodAuditConfigKey(paymentMethod.ID),
+			Module: constants.EmployeeCollectionAuditModule, ResourceID: paymentMethodAuditResourceID(paymentMethod.ID),
+			DisplayName: paymentMethod.Name, Identity: paymentMethodAuditIdentity(paymentMethod),
+			BeforeData: beforeData, AfterData: paymentMethodAuditSnapshot(paymentMethod),
+			Result: constants.AuditResultSuccess,
+		}); err != nil {
+			return err
+		}
+		updated = paymentMethod
+		return nil
+	})
+	if err != nil {
+		return nil, mapPaymentMethodCodeConflict(err)
+	}
+	return toPaymentMethodResponse(updated), nil
+}
+
+// Delete 物理删除未被任何核销申请引用的线下收款方式，并写入配置审计。
+// 已被引用的字典项只允许停用，保证历史申请继续显示冻结名称。
+func (s *PaymentMethodService) Delete(ctx context.Context, id uint) error {
+	operatorID, err := requireSuperAdmin(ctx)
+	if err != nil {
+		return err
+	}
+	if s == nil || s.db == nil || s.audit == nil {
+		return errors.New(errors.CodeServiceUnavailable, "线下收款方式维护能力尚未配置")
+	}
+	if id == 0 {
+		return errors.New(errors.CodeEmployeeCollectionPaymentMethodNotFound)
+	}
+	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		paymentMethod, err := lockPaymentMethod(ctx, tx, id)
+		if err != nil {
+			return err
+		}
+		referenced, err := countPaymentMethodReferences(ctx, tx, id)
+		if err != nil {
+			return err
+		}
+		if referenced > 0 {
+			return errors.New(errors.CodeEmployeeCollectionPaymentMethodReferenced)
+		}
+		beforeData := paymentMethodAuditSnapshot(paymentMethod)
+		paymentMethod.Updater = operatorID
+		if err := tx.WithContext(ctx).Save(paymentMethod).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "更新线下收款方式失败")
+		}
+		if err := tx.WithContext(ctx).Delete(paymentMethod).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "删除线下收款方式失败")
+		}
+		return s.audit.WriteConfigChange(ctx, tx, systemconfigapp.ChangeAudit{
+			OperatorID: operatorID, OperationType: constants.AuditOperationEmployeeCollectionPaymentMethodDelete,
+			Description: "删除线下收款方式", ConfigKey: paymentMethodAuditConfigKey(paymentMethod.ID),
+			Module: constants.EmployeeCollectionAuditModule, ResourceID: paymentMethodAuditResourceID(paymentMethod.ID),
+			DisplayName: paymentMethod.Name, Identity: paymentMethodAuditIdentity(paymentMethod),
+			BeforeData: beforeData, Result: constants.AuditResultSuccess,
+		})
+	})
+}
+
+// requireSuperAdmin 校验当前调用者是超级管理员，并返回其账号 ID。
+// 字典维护不对外开放，未授权一律返回同一禁止访问错误。
+func requireSuperAdmin(ctx context.Context) (uint, error) {
+	if middleware.GetUserTypeFromContext(ctx) != constants.UserTypeSuperAdmin {
+		return 0, errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")
+	}
+	operatorID := middleware.GetUserIDFromContext(ctx)
+	if operatorID == 0 {
+		return 0, errors.New(errors.CodeUnauthorized)
+	}
+	return operatorID, nil
+}
+
+// lockPaymentMethod 以行锁读取线下收款方式，未找到返回稳定不存在错误。
+func lockPaymentMethod(ctx context.Context, tx *gorm.DB, id uint) (*model.EmployeeCollectionPaymentMethod, error) {
+	var paymentMethod model.EmployeeCollectionPaymentMethod
+	err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).
+		First(&paymentMethod, id).Error
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeEmployeeCollectionPaymentMethodNotFound)
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询线下收款方式失败")
+	}
+	return &paymentMethod, nil
+}
+
+// ensurePaymentMethodCodeAvailable 校验稳定编码在未删除记录中唯一，excludeID 用于更新自身。
+func ensurePaymentMethodCodeAvailable(ctx context.Context, tx *gorm.DB, code string, excludeID uint) error {
+	query := tx.WithContext(ctx).Model(&model.EmployeeCollectionPaymentMethod{}).Where("code = ?", code)
+	if excludeID != 0 {
+		query = query.Where("id <> ?", excludeID)
+	}
+	var count int64
+	if err := query.Count(&count).Error; err != nil {
+		return errors.Wrap(errors.CodeDatabaseError, err, "校验线下收款方式编码失败")
+	}
+	if count > 0 {
+		return errors.New(errors.CodeEmployeeCollectionPaymentMethodCodeExists)
+	}
+	return nil
+}
+
+// countPaymentMethodReferences 统计引用该收款方式的核销申请与代理充值申请数量。
+// 两类引用任一存在即禁止物理删除与改码，历史快照由各自记录冻结。
+func countPaymentMethodReferences(ctx context.Context, tx *gorm.DB, id uint) (int64, error) {
+	var applicationCount int64
+	if err := tx.WithContext(ctx).Model(&model.EmployeeCollectionApplication{}).
+		Where("payment_method_id = ?", id).Count(&applicationCount).Error; err != nil {
+		return 0, errors.Wrap(errors.CodeDatabaseError, err, "统计线下收款方式引用失败")
+	}
+	if applicationCount > 0 {
+		return applicationCount, nil
+	}
+	var rechargeCount int64
+	if err := tx.WithContext(ctx).Model(&model.AgentRechargeRecord{}).
+		Where("offline_payment_method_id = ?", id).Count(&rechargeCount).Error; err != nil {
+		return 0, errors.Wrap(errors.CodeDatabaseError, err, "统计代理充值线下收款方式引用失败")
+	}
+	return rechargeCount, nil
+}
+
+// mapPaymentMethodCodeConflict 把稳定编码唯一索引冲突映射为稳定业务错误。
+// 并发创建或改码时唯一索引是最终裁决，避免把约束冲突暴露成内部错误。
+func mapPaymentMethodCodeConflict(err error) error {
+	var pgErr *pgconn.PgError
+	if stdErrors.As(err, &pgErr) && pgErr.Code == "23505" {
+		return errors.New(errors.CodeEmployeeCollectionPaymentMethodCodeExists)
+	}
+	return err
+}
+
+// toPaymentMethodResponse 将字典项投影为对外响应。
+func toPaymentMethodResponse(paymentMethod *model.EmployeeCollectionPaymentMethod) *dto.EmployeeCollectionPaymentMethodResponse {
+	if paymentMethod == nil {
+		return nil
+	}
+	return &dto.EmployeeCollectionPaymentMethodResponse{
+		ID: paymentMethod.ID, Code: paymentMethod.Code, Name: paymentMethod.Name,
+		Enabled: paymentMethod.Status == constants.EmployeeCollectionPaymentMethodStatusEnabled,
+		Sort:    paymentMethod.SortOrder, Remark: paymentMethod.Remark,
+		CreatedAt: paymentMethod.CreatedAt, UpdatedAt: paymentMethod.UpdatedAt,
+	}
+}
+
+// paymentMethodAuditConfigKey 生成字典项的审计配置键。
+func paymentMethodAuditConfigKey(id uint) string {
+	return constants.EmployeeCollectionAuditConfigKeyPrefix + "." + strconv.FormatUint(uint64(id), 10)
+}
+
+// paymentMethodAuditResourceID 生成字典项审计资源标识。
+func paymentMethodAuditResourceID(id uint) *string {
+	value := strconv.FormatUint(uint64(id), 10)
+	return &value
+}
+
+// paymentMethodAuditIdentity 生成字典项审计身份快照，不含任何凭证内容。
+func paymentMethodAuditIdentity(paymentMethod *model.EmployeeCollectionPaymentMethod) map[string]any {
+	return map[string]any{
+		"id": paymentMethod.ID, "code": paymentMethod.Code, "name": paymentMethod.Name,
+		"status": paymentMethod.Status, "sort": paymentMethod.SortOrder,
+	}
+}
+
+// paymentMethodAuditSnapshot 生成字典项审计前后值快照，不含任何凭证内容。
+func paymentMethodAuditSnapshot(paymentMethod *model.EmployeeCollectionPaymentMethod) map[string]any {
+	return map[string]any{
+		"id": paymentMethod.ID, "code": paymentMethod.Code, "name": paymentMethod.Name,
+		"status": paymentMethod.Status, "sort": paymentMethod.SortOrder, "remark": paymentMethod.Remark,
+	}
+}

internal/application/employeecollection/refund_offset.go

@@ -0,0 +1,161 @@
+package employeecollection
+
+import (
+	"context"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	employeecollectiondomain "github.com/break/junhong_cmp_fiber/internal/domain/employeecollection"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// RefundOffsetSource 是来源订单退款成功的事实快照。
+type RefundOffsetSource struct {
+	// RefundID 表示本次退款申请 ID。
+	RefundID uint
+	// OrderID 表示退款关联的来源订单 ID。
+	OrderID uint
+	// RefundAmount 表示本次退款成功金额（分），与退款入账使用的金额为同一实参。
+	RefundAmount int64
+}
+
+// RefundOffsetService 在既有退款成功事务内冲销或提示员工代收款账单。
+// 只处理来源为后台线下套餐订单的账单，其他订单直接跳过，不阻断退款链路。
+type RefundOffsetService struct {
+	audit BillAuditWriter
+}
+
+// NewRefundOffsetService 创建退款冲销用例。
+func NewRefundOffsetService(audit BillAuditWriter) *RefundOffsetService {
+	return &RefundOffsetService{audit: audit}
+}
+
+// ApplyInTx 在既有退款成功事务内按来源唯一键 order:{id} 查找账单并幂等写入冲销事实。
+// 同一退款对同一账单至多一条关联：重复投递时关联写入影响 0 行，不再冲减、不再写审计、
+// 也不依赖退款事务的 changed 标志。
+func (s *RefundOffsetService) ApplyInTx(ctx context.Context, tx *gorm.DB, source RefundOffsetSource) error {
+	if s == nil || tx == nil || s.audit == nil {
+		return errors.New(errors.CodeInternalError, "员工代收款退款冲销能力未配置")
+	}
+	if source.RefundID == 0 || source.OrderID == 0 || source.RefundAmount <= 0 {
+		return errors.New(errors.CodeInvalidParam, "员工代收款退款冲销参数无效")
+	}
+	var bill model.EmployeeCollectionBill
+	if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).
+		Where("source_key = ?", employeecollectiondomain.OrderSourceKey(source.OrderID)).
+		First(&bill).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			// 来源订单未产生员工代收款账单，跳过而不阻断退款。
+			return nil
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "锁定来源订单员工代收款账单失败")
+	}
+	decision, err := employeecollectiondomain.DecideRefundOffset(billAmounts(&bill), source.RefundAmount)
+	if err != nil {
+		return err
+	}
+	record := &model.EmployeeCollectionBillRefund{
+		BillID: bill.ID, RefundID: source.RefundID, SourceOrderID: source.OrderID,
+		RefundAmount: source.RefundAmount, BillReceivableAmount: bill.ReceivableAmount,
+		Outcome: decision.Outcome, ReducedAmount: decision.ReducedAmount,
+	}
+	result := tx.WithContext(ctx).Clauses(clause.OnConflict{
+		Columns:   []clause.Column{{Name: "bill_id"}, {Name: "refund_id"}},
+		DoNothing: true,
+	}).Create(record)
+	if result.Error != nil {
+		return errors.Wrap(errors.CodeDatabaseError, result.Error, "写入员工代收款退款冲销关联失败")
+	}
+	if result.RowsAffected == 0 {
+		// 同一退款已冲销过同一账单，保留既有事实。
+		return nil
+	}
+	before := bill
+	if err := applyRefundOutcome(ctx, tx, &bill, decision); err != nil {
+		return err
+	}
+	offsetEventID, err := composeAuditEventID(
+		"employee_collection", "bill", "order", uintText(source.OrderID), "refund", uintText(source.RefundID))
+	if err != nil {
+		return err
+	}
+	return s.audit.WriteEmployeeCollectionBill(ctx, tx, BillAudit{
+		EventID:    offsetEventID,
+		ActionCode: constants.AuditActionEmployeeCollectionBillRefundOffseted,
+		Summary:    constants.GetEmployeeCollectionRefundOutcomeName(decision.Outcome),
+		Bill:       &bill,
+		BeforeData: map[string]any{
+			"receivable_amount": before.ReceivableAmount, "received_amount": before.ReceivedAmount,
+			"reserved_amount": before.ReservedAmount, "status": before.Status,
+		},
+		AfterData: map[string]any{
+			"receivable_amount": bill.ReceivableAmount, "received_amount": bill.ReceivedAmount,
+			"reserved_amount": bill.ReservedAmount, "status": bill.Status,
+			"refund_id": source.RefundID, "refund_amount": source.RefundAmount, "outcome": decision.Outcome,
+		},
+		CorrelationID: bill.SourceNo,
+	})
+}
+
+// applyRefundOutcome 按判定结果修改账单：全额退款关闭、部分冲减应收，提示结果不修改金额与状态。
+// 关闭与冲减都使用 expected-status 条件更新并检查 RowsAffected，避免并发覆盖。
+func applyRefundOutcome(
+	ctx context.Context,
+	tx *gorm.DB,
+	bill *model.EmployeeCollectionBill,
+	decision employeecollectiondomain.RefundOffsetDecision,
+) error {
+	expectedStatus := bill.Status
+	switch decision.Outcome {
+	case constants.EmployeeCollectionRefundOutcomeHintOnly:
+		return nil
+	case constants.EmployeeCollectionRefundOutcomeClosedFull:
+		closedAt := time.Now().UTC()
+		result := tx.WithContext(ctx).Model(&model.EmployeeCollectionBill{}).
+			Where("id = ? AND status = ?", bill.ID, expectedStatus).
+			Updates(map[string]any{
+				"status":        constants.EmployeeCollectionBillStatusClosed,
+				"closed_reason": "来源订单全额退款",
+				"closed_at":     closedAt,
+				"updater":       0,
+			})
+		if result.Error != nil {
+			return errors.Wrap(errors.CodeDatabaseError, result.Error, "关闭来源订单全额退款账单失败")
+		}
+		if result.RowsAffected != 1 {
+			return errors.New(errors.CodeConflict, "员工代收款账单状态已变化，退款冲销未完成")
+		}
+		bill.Status = constants.EmployeeCollectionBillStatusClosed
+		bill.ClosedReason = "来源订单全额退款"
+		bill.ClosedAt = &closedAt
+		return nil
+	case constants.EmployeeCollectionRefundOutcomeReduced:
+		amounts, err := billAmounts(bill).ReduceReceivable(decision.ReducedAmount)
+		if err != nil {
+			return err
+		}
+		nextStatus := amounts.DerivedStatus()
+		result := tx.WithContext(ctx).Model(&model.EmployeeCollectionBill{}).
+			Where("id = ? AND status = ?", bill.ID, expectedStatus).
+			Updates(map[string]any{
+				"receivable_amount": amounts.Receivable,
+				"status":            nextStatus,
+				"updater":           0,
+			})
+		if result.Error != nil {
+			return errors.Wrap(errors.CodeDatabaseError, result.Error, "冲减来源订单退款账单应收失败")
+		}
+		if result.RowsAffected != 1 {
+			return errors.New(errors.CodeConflict, "员工代收款账单状态已变化，退款冲减未完成")
+		}
+		bill.ReceivableAmount = amounts.Receivable
+		bill.Status = nextStatus
+		return nil
+	default:
+		return errors.New(errors.CodeInternalError, "不支持的退款冲销处理结果")
+	}
+}

internal/application/merchantpayment/management.go

@@ -0,0 +1,721 @@
+// Package merchantpayment provides merchant pool payment routing use cases.
+package merchantpayment
+
+import (
+	"context"
+	"reflect"
+	"strconv"
+	"strings"
+	"time"
+
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	systemconfigapp "github.com/break/junhong_cmp_fiber/internal/application/systemconfig"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"github.com/bytedance/sonic"
+)
+
+// ManagementService 负责商户、商户池与授权配置写入。
+type ManagementService struct {
+	db    *gorm.DB
+	audit systemconfigapp.AuditWriter
+}
+
+// NewManagementService 创建商户配置用例。
+func NewManagementService(db *gorm.DB, audit systemconfigapp.AuditWriter) *ManagementService {
+	return &ManagementService{db: db, audit: audit}
+}
+
+func requireManager(ctx context.Context) error {
+	kind := middleware.GetUserTypeFromContext(ctx)
+	if kind != constants.UserTypeSuperAdmin && kind != constants.UserTypePlatform {
+		return errors.New(errors.CodeForbidden, "无权限访问支付商户配置")
+	}
+	return nil
+}
+
+func normalizePage(page, size int) (int, int) {
+	if page < 1 {
+		page = 1
+	}
+	if size < 1 {
+		size = 20
+	}
+	if size > 100 {
+		size = 100
+	}
+	return page, size
+}
+
+func validPaymentMethod(method string) bool {
+	return method == "wechat" || method == "alipay"
+}
+
+func validateMerchantConfiguration(paymentMethod, providerType, merchantIdentity string, credentials model.JSONB) error {
+	paymentMethod, providerType, merchantIdentity = strings.TrimSpace(paymentMethod), strings.TrimSpace(providerType), strings.TrimSpace(merchantIdentity)
+	if !validPaymentMethod(paymentMethod) || merchantIdentity == "" || len(credentials) == 0 {
+		return errors.New(errors.CodeInvalidParam, "支付商户配置不完整")
+	}
+	var config model.WechatConfig
+	raw, err := sonic.Marshal(credentials)
+	if err != nil || sonic.Unmarshal(raw, &config) != nil {
+		return errors.New(errors.CodeInvalidParam, "支付商户凭证格式无效")
+	}
+	switch paymentMethod {
+	case "wechat":
+		switch providerType {
+		case model.ProviderTypeWechat:
+			if config.WxMchID != merchantIdentity || strings.TrimSpace(config.WxAPIV3Key) == "" || strings.TrimSpace(config.WxCertContent) == "" || strings.TrimSpace(config.WxKeyContent) == "" || strings.TrimSpace(config.WxSerialNo) == "" || strings.TrimSpace(config.WxNotifyURL) == "" {
+				return errors.New(errors.CodeInvalidParam, "微信直连商户凭证不完整或身份不一致")
+			}
+		case model.ProviderTypeWechatV2:
+			if config.WxMchID != merchantIdentity || strings.TrimSpace(config.WxAPIV2Key) == "" || strings.TrimSpace(config.WxNotifyURL) == "" {
+				return errors.New(errors.CodeInvalidParam, "微信 v2 商户凭证不完整或身份不一致")
+			}
+		case model.ProviderTypeFuiou:
+			if config.FyMchntCd != merchantIdentity || strings.TrimSpace(config.FyInsCd) == "" || strings.TrimSpace(config.FyTermID) == "" || strings.TrimSpace(config.FyPrivateKey) == "" || strings.TrimSpace(config.FyPublicKey) == "" || strings.TrimSpace(config.FyAPIURL) == "" || strings.TrimSpace(config.FyNotifyURL) == "" {
+				return errors.New(errors.CodeInvalidParam, "富友商户凭证不完整或身份不一致")
+			}
+		default:
+			return errors.New(errors.CodeInvalidParam, "微信支付服务商类型无效")
+		}
+	case "alipay":
+		if providerType != "alipay" || config.AliAppID != merchantIdentity || strings.TrimSpace(config.AliPrivateKey) == "" || strings.TrimSpace(config.AliPublicKey) == "" || strings.TrimSpace(config.AliNotifyURL) == "" || strings.TrimSpace(config.AliReturnURL) == "" {
+			return errors.New(errors.CodeInvalidParam, "支付宝商户凭证不完整或身份不一致")
+		}
+	}
+	return nil
+}
+
+func validatePoolRequest(req dto.PaymentMerchantPoolRequest) error {
+	if !validPaymentMethod(strings.TrimSpace(req.PaymentMethod)) {
+		return errors.New(errors.CodeInvalidParam, "支付方式仅支持微信或支付宝")
+	}
+	switch req.Strategy {
+	case model.PaymentMerchantStrategyAmount:
+		if req.ThresholdAmount == nil || *req.ThresholdAmount <= 0 || req.ThresholdCount != nil || req.StatisticCycle == nil || !validStatisticCycle(*req.StatisticCycle) || req.TimePeriodValue != nil || req.TimePeriodUnit != nil || req.TimePeriodStartedAt != nil {
+			return errors.New(errors.CodeInvalidParam, "金额轮询策略参数不完整")
+		}
+	case model.PaymentMerchantStrategyCount:
+		if req.ThresholdCount == nil || *req.ThresholdCount <= 0 || req.ThresholdAmount != nil || req.StatisticCycle == nil || !validStatisticCycle(*req.StatisticCycle) || req.TimePeriodValue != nil || req.TimePeriodUnit != nil || req.TimePeriodStartedAt != nil {
+			return errors.New(errors.CodeInvalidParam, "笔数轮询策略参数不完整")
+		}
+	case model.PaymentMerchantStrategyTime:
+		if req.TimePeriodValue == nil || *req.TimePeriodValue < 1 || req.TimePeriodUnit == nil || !validTimeUnit(*req.TimePeriodUnit) || req.TimePeriodStartedAt == nil || req.ThresholdAmount != nil || req.ThresholdCount != nil || req.StatisticCycle != nil {
+			return errors.New(errors.CodeInvalidParam, "时间轮询策略参数不完整")
+		}
+	default:
+		return errors.New(errors.CodeInvalidParam, "不支持的商户池轮询策略")
+	}
+	return nil
+}
+
+func validStatisticCycle(value string) bool {
+	return value == "round" || value == "day" || value == "month"
+}
+func validTimeUnit(value string) bool { return value == "minute" || value == "hour" || value == "day" }
+
+func (s *ManagementService) writeAudit(ctx context.Context, tx *gorm.DB, operation, description, key, name string, id uint, identity, before, after map[string]any) error {
+	if s.audit == nil {
+		return errors.New(errors.CodeInvalidStatus, "支付商户管理审计接缝未配置")
+	}
+	resourceID := strconv.FormatUint(uint64(id), 10)
+	return s.audit.WriteConfigChange(ctx, tx, systemconfigapp.ChangeAudit{
+		OperatorID: middleware.GetUserIDFromContext(ctx), OperationType: operation, Description: description,
+		ConfigKey: key, Module: "payment_merchant", ResourceID: &resourceID, DisplayName: name,
+		Identity: identity, BeforeData: before, AfterData: after, Result: constants.AuditResultSuccess,
+	})
+}
+
+func merchantAuditIdentity(m *model.PaymentMerchant) map[string]any {
+	return map[string]any{"id": m.ID, "name": m.Name, "payment_method": m.PaymentMethod, "provider_type": m.ProviderType, "merchant_identity": m.MerchantIdentity, "status": m.Status, "credential_version": m.CredentialVersion}
+}
+
+func poolAuditIdentity(p *model.PaymentMerchantPool) map[string]any {
+	return map[string]any{"id": p.ID, "name": p.Name, "payment_method": p.PaymentMethod, "strategy": p.Strategy, "status": p.Status, "routing_epoch": p.RoutingEpoch}
+}
+
+func authorizationAuditIdentity(a *model.WechatAuthorization) map[string]any {
+	return map[string]any{"id": a.ID, "status": a.Status, "credential_version": a.CredentialVersion, "oa_app_id": a.OaAppID, "miniapp_app_id": a.MiniappAppID}
+}
+
+// CreateMerchant 创建独立管理的支付商户。
+func (s *ManagementService) CreateMerchant(ctx context.Context, req dto.PaymentMerchantRequest) (*dto.PaymentMerchantResponse, error) {
+	if err := requireManager(ctx); err != nil {
+		return nil, err
+	}
+	if s == nil || s.db == nil || strings.TrimSpace(req.Name) == "" || len(req.Credentials) == 0 {
+		return nil, errors.New(errors.CodeInvalidParam, "商户参数或凭证不完整")
+	}
+	if !validPaymentMethod(strings.TrimSpace(req.PaymentMethod)) {
+		return nil, errors.New(errors.CodeInvalidParam, "支付方式仅支持微信或支付宝")
+	}
+	m := &model.PaymentMerchant{Name: strings.TrimSpace(req.Name), PaymentMethod: strings.TrimSpace(req.PaymentMethod), ProviderType: strings.TrimSpace(req.ProviderType), MerchantIdentity: strings.TrimSpace(req.MerchantIdentity), Credentials: req.Credentials, CredentialVersion: 1, Remark: strings.TrimSpace(req.Remark), BaseModel: model.BaseModel{Creator: middleware.GetUserIDFromContext(ctx), Updater: middleware.GetUserIDFromContext(ctx)}}
+	if req.Enabled {
+		m.Status = model.PaymentMerchantStatusEnabled
+	}
+	if m.MerchantIdentity == "" || m.ProviderType == "" {
+		return nil, errors.New(errors.CodeInvalidParam, "商户身份或服务商类型不能为空")
+	}
+	if err := validateMerchantConfiguration(m.PaymentMethod, m.ProviderType, m.MerchantIdentity, m.Credentials); err != nil {
+		return nil, err
+	}
+	if err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Create(m).Error; err != nil {
+			return err
+		}
+		return s.writeAudit(ctx, tx, constants.AuditOperationPaymentConfigCreate, "创建支付商户", "payment_merchant:"+strconv.FormatUint(uint64(m.ID), 10), m.Name, m.ID, merchantAuditIdentity(m), nil, merchantAuditIdentity(m))
+	}); err != nil {
+		if appErr, ok := err.(*errors.AppError); ok {
+			return nil, appErr
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "创建支付商户失败")
+	}
+	return merchantResponse(m), nil
+}
+
+// ListMerchants returns the privileged configuration projection.
+
+// ListPools returns one page of merchant pools and their ordered members without per-pool member queries.
+func (s *ManagementService) ListPools(ctx context.Context, req dto.PaymentMerchantPoolListRequest) ([]*dto.PaymentMerchantPoolResponse, int64, error) {
+	if err := requireManager(ctx); err != nil {
+		return nil, 0, err
+	}
+	page, size := normalizePage(req.Page, req.PageSize)
+	query := s.db.WithContext(ctx).Model(&model.PaymentMerchantPool{})
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, errors.Wrap(errors.CodeDatabaseError, err, "统计商户池失败")
+	}
+	var pools []model.PaymentMerchantPool
+	if err := query.Order("id DESC").Offset((page - 1) * size).Limit(size).Find(&pools).Error; err != nil {
+		return nil, 0, errors.Wrap(errors.CodeDatabaseError, err, "查询商户池失败")
+	}
+	poolIDs := make([]uint, 0, len(pools))
+	for index := range pools {
+		poolIDs = append(poolIDs, pools[index].ID)
+	}
+	membersByPool := make(map[uint][]uint, len(pools))
+	if len(poolIDs) > 0 {
+		var members []model.PaymentMerchantPoolMember
+		if err := s.db.WithContext(ctx).Where("pool_id IN ?", poolIDs).Order("pool_id ASC, sort_order ASC").Find(&members).Error; err != nil {
+			return nil, 0, errors.Wrap(errors.CodeDatabaseError, err, "查询商户池成员失败")
+		}
+		for index := range members {
+			member := &members[index]
+			membersByPool[member.PoolID] = append(membersByPool[member.PoolID], member.MerchantID)
+		}
+	}
+	result := make([]*dto.PaymentMerchantPoolResponse, 0, len(pools))
+	for index := range pools {
+		pool := &pools[index]
+		result = append(result, &dto.PaymentMerchantPoolResponse{ID: pool.ID, Name: pool.Name, PaymentMethod: pool.PaymentMethod, Enabled: pool.Status == model.PaymentMerchantStatusEnabled, Strategy: pool.Strategy, ThresholdAmount: pool.ThresholdAmount, ThresholdCount: pool.ThresholdCount, StatisticCycle: pool.StatisticCycle, TimePeriodValue: pool.TimePeriodValue, TimePeriodUnit: pool.TimePeriodUnit, TimePeriodStartedAt: pool.TimePeriodStartedAt, RoutingEpoch: pool.RoutingEpoch, MemberIDs: membersByPool[pool.ID], Remark: pool.Remark})
+	}
+	return result, total, nil
+}
+
+// GetPool 查询一个商户池及其有序成员。
+func (s *ManagementService) GetPool(ctx context.Context, id uint) (*dto.PaymentMerchantPoolResponse, error) {
+	if err := requireManager(ctx); err != nil {
+		return nil, err
+	}
+	var pool model.PaymentMerchantPool
+	if err := s.db.WithContext(ctx).First(&pool, id).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "商户池不存在")
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询商户池失败")
+	}
+	return poolResponse(ctx, s.db, &pool)
+}
+
+// ListMerchants 分页查询特权商户配置。
+func (s *ManagementService) ListMerchants(ctx context.Context, req dto.PaymentMerchantListRequest) ([]*dto.PaymentMerchantResponse, int64, error) {
+	if err := requireManager(ctx); err != nil {
+		return nil, 0, err
+	}
+	page, size := normalizePage(req.Page, req.PageSize)
+	query := s.db.WithContext(ctx).Model(&model.PaymentMerchant{})
+	if req.PaymentMethod != nil {
+		query = query.Where("payment_method = ?", strings.TrimSpace(*req.PaymentMethod))
+	}
+	if req.Enabled != nil {
+		status := model.PaymentMerchantStatusDisabled
+		if *req.Enabled {
+			status = model.PaymentMerchantStatusEnabled
+		}
+		query = query.Where("status = ?", status)
+	}
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return nil, 0, errors.Wrap(errors.CodeDatabaseError, err, "查询支付商户失败")
+	}
+	var rows []model.PaymentMerchant
+	if err := query.Order("id DESC").Offset((page - 1) * size).Limit(size).Find(&rows).Error; err != nil {
+		return nil, 0, errors.Wrap(errors.CodeDatabaseError, err, "查询支付商户失败")
+	}
+	result := make([]*dto.PaymentMerchantResponse, 0, len(rows))
+	for index := range rows {
+		result = append(result, merchantResponse(&rows[index]))
+	}
+	return result, total, nil
+}
+
+// GetMerchant 查询一个特权商户配置。
+func (s *ManagementService) GetMerchant(ctx context.Context, id uint) (*dto.PaymentMerchantResponse, error) {
+	if err := requireManager(ctx); err != nil {
+		return nil, err
+	}
+	var m model.PaymentMerchant
+	if err := s.db.WithContext(ctx).First(&m, id).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "支付商户不存在")
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询支付商户失败")
+	}
+	return merchantResponse(&m), nil
+}
+
+// UpdateMerchant 更新商户凭证和可变配置。
+func (s *ManagementService) UpdateMerchant(ctx context.Context, id uint, req dto.PaymentMerchantUpdateRequest) (*dto.PaymentMerchantResponse, error) {
+	if err := requireManager(ctx); err != nil {
+		return nil, err
+	}
+	if req.PaymentMethod != nil && !validPaymentMethod(strings.TrimSpace(*req.PaymentMethod)) {
+		return nil, errors.New(errors.CodeInvalidParam, "支付方式仅支持微信或支付宝")
+	}
+	var m model.PaymentMerchant
+	if err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&m, id).Error; err != nil {
+			return err
+		}
+		before := merchantAuditIdentity(&m)
+		previous := m
+		var refs int64
+		if err := tx.Model(&model.Payment{}).Where("merchant_id = ?", id).Count(&refs).Error; err != nil {
+			return err
+		}
+		if refs > 0 && ((req.PaymentMethod != nil && *req.PaymentMethod != m.PaymentMethod) || (req.ProviderType != nil && *req.ProviderType != m.ProviderType) || (req.MerchantIdentity != nil && *req.MerchantIdentity != m.MerchantIdentity)) {
+			return errors.New(errors.CodeConflict, "已被支付单引用，不能修改收款身份")
+		}
+		if req.Name != nil {
+			m.Name = strings.TrimSpace(*req.Name)
+		}
+		if req.PaymentMethod != nil {
+			m.PaymentMethod = strings.TrimSpace(*req.PaymentMethod)
+		}
+		if req.ProviderType != nil {
+			m.ProviderType = strings.TrimSpace(*req.ProviderType)
+		}
+		if req.MerchantIdentity != nil {
+			m.MerchantIdentity = strings.TrimSpace(*req.MerchantIdentity)
+		}
+		if req.Remark != nil {
+			m.Remark = strings.TrimSpace(*req.Remark)
+		}
+		if req.Enabled != nil {
+			m.Status = model.PaymentMerchantStatusDisabled
+			if *req.Enabled {
+				m.Status = model.PaymentMerchantStatusEnabled
+			}
+		}
+		if req.Credentials != nil && !reflect.DeepEqual(m.Credentials, *req.Credentials) {
+			m.Credentials = *req.Credentials
+		}
+		if previous.Name != m.Name || previous.PaymentMethod != m.PaymentMethod || previous.ProviderType != m.ProviderType || previous.MerchantIdentity != m.MerchantIdentity || previous.Status != m.Status || !reflect.DeepEqual(previous.Credentials, m.Credentials) {
+			m.CredentialVersion++
+		}
+		if err := validateMerchantConfiguration(m.PaymentMethod, m.ProviderType, m.MerchantIdentity, m.Credentials); err != nil {
+			return err
+		}
+		if err := tx.Save(&m).Error; err != nil {
+			return err
+		}
+		return s.writeAudit(ctx, tx, constants.AuditOperationPaymentConfigUpdate, "更新支付商户", "payment_merchant:"+strconv.FormatUint(uint64(m.ID), 10), m.Name, m.ID, merchantAuditIdentity(&m), before, merchantAuditIdentity(&m))
+	}); err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "支付商户不存在")
+		}
+		if appErr, ok := err.(*errors.AppError); ok {
+			return nil, appErr
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "更新支付商户失败")
+	}
+	return merchantResponse(&m), nil
+}
+
+// DeleteMerchant 仅在未被引用且二次确认后删除商户。
+func (s *ManagementService) DeleteMerchant(ctx context.Context, id uint, confirm bool) error {
+	if err := requireManager(ctx); err != nil {
+		return err
+	}
+	if !confirm {
+		return errors.New(errors.CodeInvalidParam, "删除商户必须二次确认")
+	}
+	return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var refs, members int64
+		var merchant model.PaymentMerchant
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&merchant, id).Error; err != nil {
+			return err
+		}
+		before := merchantAuditIdentity(&merchant)
+		if err := tx.Model(&model.Payment{}).Where("merchant_id = ?", id).Count(&refs).Error; err != nil {
+			return err
+		}
+		if refs > 0 {
+			return errors.New(errors.CodeConflict, "已被支付单引用的商户不能删除")
+		}
+		if err := tx.Model(&model.PaymentMerchantPoolMember{}).Where("merchant_id = ?", id).Count(&members).Error; err != nil {
+			return err
+		}
+		if members > 0 {
+			return errors.New(errors.CodeConflict, "商户仍属于商户池")
+		}
+		r := tx.Delete(&model.PaymentMerchant{}, id)
+		if r.Error != nil {
+			return r.Error
+		}
+		if r.RowsAffected == 0 {
+			return errors.New(errors.CodeNotFound, "支付商户不存在")
+		}
+		if err := s.writeAudit(ctx, tx, constants.AuditOperationPaymentConfigDelete, "删除支付商户", "payment_merchant:"+strconv.FormatUint(uint64(merchant.ID), 10), merchant.Name, merchant.ID, before, before, nil); err != nil {
+			return err
+		}
+		return nil
+	})
+}
+
+// SavePool 创建或更新商户池，并原子替换有序成员。
+func (s *ManagementService) SavePool(ctx context.Context, id uint, req dto.PaymentMerchantPoolRequest) (*dto.PaymentMerchantPoolResponse, error) {
+	if err := requireManager(ctx); err != nil {
+		return nil, err
+	}
+	if err := validatePoolRequest(req); err != nil {
+		return nil, err
+	}
+	if len(req.MemberIDs) == 0 {
+		return nil, errors.New(errors.CodeInvalidParam, "商户池至少需要一个商户")
+	}
+	var pool model.PaymentMerchantPool
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		creating := id == 0
+		var previousMemberIDs []uint
+		if !creating {
+			if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&pool, id).Error; err != nil {
+				return err
+			}
+			var previousMembers []model.PaymentMerchantPoolMember
+			if err := tx.Where("pool_id = ?", pool.ID).Order("sort_order ASC").Find(&previousMembers).Error; err != nil {
+				return err
+			}
+			previousMemberIDs = make([]uint, 0, len(previousMembers))
+			for _, member := range previousMembers {
+				previousMemberIDs = append(previousMemberIDs, member.MerchantID)
+			}
+		} else {
+			pool.Creator = middleware.GetUserIDFromContext(ctx)
+			pool.RoutingEpoch = 1
+		}
+		before := poolAuditIdentity(&pool)
+		if err := validatePoolMembers(ctx, tx, req.PaymentMethod, req.MemberIDs); err != nil {
+			return err
+		}
+		if !creating && poolEpochChanged(&pool, &req, previousMemberIDs) {
+			pool.RoutingEpoch++
+		}
+		pool.Name, pool.PaymentMethod, pool.Strategy, pool.Remark = strings.TrimSpace(req.Name), strings.TrimSpace(req.PaymentMethod), strings.TrimSpace(req.Strategy), strings.TrimSpace(req.Remark)
+		pool.ThresholdAmount, pool.ThresholdCount, pool.StatisticCycle, pool.TimePeriodValue, pool.TimePeriodUnit, pool.TimePeriodStartedAt = req.ThresholdAmount, req.ThresholdCount, req.StatisticCycle, req.TimePeriodValue, req.TimePeriodUnit, req.TimePeriodStartedAt
+		if req.Enabled {
+			var others int64
+			if err := tx.Model(&model.PaymentMerchantPool{}).Where("payment_method = ? AND status = ? AND id <> ?", pool.PaymentMethod, model.PaymentMerchantStatusEnabled, pool.ID).Count(&others).Error; err != nil {
+				return err
+			}
+			if others > 0 {
+				return errors.New(errors.CodeConflict, "该支付方式已有启用商户池")
+			}
+		}
+		pool.Status = model.PaymentMerchantStatusDisabled
+		if req.Enabled {
+			pool.Status = model.PaymentMerchantStatusEnabled
+		}
+		pool.Updater = middleware.GetUserIDFromContext(ctx)
+		if creating {
+			if err := tx.Create(&pool).Error; err != nil {
+				return err
+			}
+		} else if err := tx.Save(&pool).Error; err != nil {
+			return err
+		}
+		if err := tx.Where("pool_id = ?", pool.ID).Delete(&model.PaymentMerchantPoolMember{}).Error; err != nil {
+			return err
+		}
+		members := make([]model.PaymentMerchantPoolMember, 0, len(req.MemberIDs))
+		for i, merchantID := range req.MemberIDs {
+			members = append(members, model.PaymentMerchantPoolMember{PoolID: pool.ID, MerchantID: merchantID, SortOrder: int64(i), BaseModel: model.BaseModel{Creator: middleware.GetUserIDFromContext(ctx), Updater: middleware.GetUserIDFromContext(ctx)}})
+		}
+		if err := tx.Create(&members).Error; err != nil {
+			return err
+		}
+		op := constants.AuditOperationPaymentConfigUpdate
+		summary := "更新商户池"
+		if creating {
+			op = constants.AuditOperationPaymentConfigCreate
+			summary = "创建商户池"
+		}
+		return s.writeAudit(ctx, tx, op, summary, "payment_merchant_pool:"+strconv.FormatUint(uint64(pool.ID), 10), pool.Name, pool.ID, poolAuditIdentity(&pool), before, poolAuditIdentity(&pool))
+	})
+	if err != nil {
+		if appErr, ok := err.(*errors.AppError); ok {
+			return nil, appErr
+		}
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "商户池不存在")
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "保存商户池失败")
+	}
+	return poolResponse(ctx, s.db, &pool)
+}
+
+// SetPoolEnabled enables or disables a pool after rechecking the active-pool and member invariants.
+func (s *ManagementService) SetPoolEnabled(ctx context.Context, id uint, enabled bool) (*dto.PaymentMerchantPoolResponse, error) {
+	if err := requireManager(ctx); err != nil {
+		return nil, err
+	}
+	var pool model.PaymentMerchantPool
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&pool, id).Error; err != nil {
+			return err
+		}
+		before := poolAuditIdentity(&pool)
+		if enabled {
+			var others int64
+			if err := tx.Model(&model.PaymentMerchantPool{}).Where("payment_method = ? AND status = ? AND id <> ?", pool.PaymentMethod, model.PaymentMerchantStatusEnabled, pool.ID).Count(&others).Error; err != nil {
+				return err
+			}
+			if others > 0 {
+				return errors.New(errors.CodeConflict, "该支付方式已有启用商户池")
+			}
+			var members []model.PaymentMerchantPoolMember
+			if err := tx.Where("pool_id = ?", pool.ID).Order("sort_order ASC").Find(&members).Error; err != nil {
+				return err
+			}
+			ids := make([]uint, 0, len(members))
+			for _, member := range members {
+				ids = append(ids, member.MerchantID)
+			}
+			if err := validatePoolMembers(ctx, tx, pool.PaymentMethod, ids); err != nil {
+				return err
+			}
+			pool.Status = model.PaymentMerchantStatusEnabled
+		} else {
+			pool.Status = model.PaymentMerchantStatusDisabled
+		}
+		pool.Updater = middleware.GetUserIDFromContext(ctx)
+		if err := tx.Save(&pool).Error; err != nil {
+			return err
+		}
+		op := constants.AuditOperationPaymentConfigDeactivate
+		summary := "停用商户池"
+		if enabled {
+			op = constants.AuditOperationPaymentConfigActivate
+			summary = "启用商户池"
+		}
+		return s.writeAudit(ctx, tx, op, summary, "payment_merchant_pool:"+strconv.FormatUint(uint64(pool.ID), 10), pool.Name, pool.ID, poolAuditIdentity(&pool), before, poolAuditIdentity(&pool))
+	})
+	if err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "商户池不存在")
+		}
+		if appErr, ok := err.(*errors.AppError); ok {
+			return nil, appErr
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "更新商户池状态失败")
+	}
+	return poolResponse(ctx, s.db, &pool)
+}
+
+func validatePoolMembers(ctx context.Context, tx *gorm.DB, method string, ids []uint) error {
+	seen := map[uint]struct{}{}
+
+	for _, id := range ids {
+		if id == 0 {
+			return errors.New(errors.CodeInvalidParam, "商户ID无效")
+		}
+		if _, ok := seen[id]; ok {
+			return errors.New(errors.CodeInvalidParam, "商户池成员不能重复")
+		}
+		seen[id] = struct{}{}
+	}
+	var merchants []model.PaymentMerchant
+	if err := tx.WithContext(ctx).Where("id IN ? AND payment_method = ? AND status = ?", ids, method, model.PaymentMerchantStatusEnabled).Find(&merchants).Error; err != nil {
+		return err
+	}
+	if len(merchants) != len(ids) {
+		return errors.New(errors.CodeConflict, "商户池成员必须存在、启用且支付方式一致")
+	}
+	for index := range merchants {
+		merchant := &merchants[index]
+		if err := validateMerchantConfiguration(merchant.PaymentMethod, merchant.ProviderType, merchant.MerchantIdentity, merchant.Credentials); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+func poolEpochChanged(pool *model.PaymentMerchantPool, request *dto.PaymentMerchantPoolRequest, previousMemberIDs []uint) bool {
+	if pool.PaymentMethod != strings.TrimSpace(request.PaymentMethod) ||
+		pool.Strategy != request.Strategy ||
+		!sameString(pool.StatisticCycle, request.StatisticCycle) ||
+		!sameInt64(pool.TimePeriodValue, request.TimePeriodValue) ||
+		!sameString(pool.TimePeriodUnit, request.TimePeriodUnit) ||
+		!sameTime(pool.TimePeriodStartedAt, request.TimePeriodStartedAt) {
+		return true
+	}
+	if sameMemberOrder(previousMemberIDs, request.MemberIDs) {
+		return false
+	}
+	return pool.StatisticCycle == nil || (*pool.StatisticCycle != "day" && *pool.StatisticCycle != "month") || !sameMemberSet(previousMemberIDs, request.MemberIDs)
+}
+
+func sameMemberOrder(left, right []uint) bool {
+	if len(left) != len(right) {
+		return false
+	}
+	for i := range left {
+		if left[i] != right[i] {
+			return false
+		}
+	}
+	return true
+}
+
+func sameMemberSet(left, right []uint) bool {
+	if len(left) != len(right) {
+		return false
+	}
+	seen := make(map[uint]struct{}, len(left))
+	for _, id := range left {
+		seen[id] = struct{}{}
+	}
+	for _, id := range right {
+		if _, ok := seen[id]; !ok {
+			return false
+		}
+	}
+	return true
+}
+
+func sameString(left, right *string) bool {
+	if left == nil || right == nil {
+		return left == right
+	}
+	return *left == *right
+}
+
+func sameInt64(left, right *int64) bool {
+	if left == nil || right == nil {
+		return left == right
+	}
+	return *left == *right
+}
+
+func sameTime(a, b *time.Time) bool {
+	if a == nil || b == nil {
+		return a == b
+	}
+	return a.Equal(*b)
+}
+func merchantResponse(m *model.PaymentMerchant) *dto.PaymentMerchantResponse {
+	return &dto.PaymentMerchantResponse{ID: m.ID, Name: m.Name, PaymentMethod: m.PaymentMethod, ProviderType: m.ProviderType, MerchantIdentity: m.MerchantIdentity, Credentials: m.Credentials, CredentialVersion: m.CredentialVersion, Enabled: m.Status == model.PaymentMerchantStatusEnabled, Remark: m.Remark, CreatedAt: m.CreatedAt, UpdatedAt: m.UpdatedAt}
+}
+func poolResponse(ctx context.Context, db *gorm.DB, p *model.PaymentMerchantPool) (*dto.PaymentMerchantPoolResponse, error) {
+	var rows []model.PaymentMerchantPoolMember
+	if err := db.WithContext(ctx).Where("pool_id = ?", p.ID).Order("sort_order ASC").Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	ids := make([]uint, 0, len(rows))
+	for _, row := range rows {
+		ids = append(ids, row.MerchantID)
+	}
+	return &dto.PaymentMerchantPoolResponse{ID: p.ID, Name: p.Name, PaymentMethod: p.PaymentMethod, Enabled: p.Status == model.PaymentMerchantStatusEnabled, Strategy: p.Strategy, ThresholdAmount: p.ThresholdAmount, ThresholdCount: p.ThresholdCount, StatisticCycle: p.StatisticCycle, TimePeriodValue: p.TimePeriodValue, TimePeriodUnit: p.TimePeriodUnit, TimePeriodStartedAt: p.TimePeriodStartedAt, RoutingEpoch: p.RoutingEpoch, MemberIDs: ids, Remark: p.Remark}, nil
+}
+
+// GetAuthorization 查询特权全局授权配置。
+func (s *ManagementService) GetAuthorization(ctx context.Context) (*dto.WechatAuthorizationResponse, error) {
+	if err := requireManager(ctx); err != nil {
+		return nil, err
+	}
+	var a model.WechatAuthorization
+	if err := s.db.WithContext(ctx).First(&a).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, nil
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询微信授权配置失败")
+	}
+	return authorizationResponse(&a), nil
+}
+
+// SaveAuthorization 创建或更新唯一启用的授权配置。
+func (s *ManagementService) SaveAuthorization(ctx context.Context, req dto.WechatAuthorizationRequest) (*dto.WechatAuthorizationResponse, error) {
+	if err := requireManager(ctx); err != nil {
+		return nil, err
+	}
+	if req.Enabled && (strings.TrimSpace(req.OaAppID) == "" || strings.TrimSpace(req.OaAppSecret) == "" || strings.TrimSpace(req.MiniappAppID) == "" || strings.TrimSpace(req.MiniappAppSecret) == "") {
+		return nil, errors.New(errors.CodeInvalidParam, "启用微信授权配置时公众号和小程序凭证必须完整")
+	}
+	var authorization model.WechatAuthorization
+	err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&authorization).Error
+		if err != nil && err != gorm.ErrRecordNotFound {
+			return err
+		}
+		previousStatus := authorization.Status
+		creating := err == gorm.ErrRecordNotFound
+		before := authorizationAuditIdentity(&authorization)
+		if creating {
+			authorization.Creator = middleware.GetUserIDFromContext(ctx)
+			authorization.CredentialVersion = 1
+		}
+		changed := authorization.OaAppID != req.OaAppID || authorization.OaAppSecret != req.OaAppSecret || authorization.OaToken != req.OaToken || authorization.OaAesKey != req.OaAesKey || authorization.OaOAuthRedirectURL != req.OaOAuthRedirectURL || authorization.MiniappAppID != req.MiniappAppID || authorization.MiniappAppSecret != req.MiniappAppSecret
+		authorization.OaAppID, authorization.OaAppSecret, authorization.OaToken, authorization.OaAesKey, authorization.OaOAuthRedirectURL, authorization.MiniappAppID, authorization.MiniappAppSecret = req.OaAppID, req.OaAppSecret, req.OaToken, req.OaAesKey, req.OaOAuthRedirectURL, req.MiniappAppID, req.MiniappAppSecret
+		authorization.Status = model.PaymentMerchantStatusDisabled
+		if req.Enabled {
+			authorization.Status = model.PaymentMerchantStatusEnabled
+		}
+		if !creating && (changed || previousStatus != authorization.Status) {
+			authorization.CredentialVersion++
+		}
+		authorization.Updater = middleware.GetUserIDFromContext(ctx)
+		if creating {
+			if err := tx.Create(&authorization).Error; err != nil {
+				return err
+			}
+		} else {
+			if err := tx.Save(&authorization).Error; err != nil {
+				return err
+			}
+		}
+		op := constants.AuditOperationPaymentConfigUpdate
+		summary := "更新微信授权配置"
+		if creating {
+			op = constants.AuditOperationPaymentConfigCreate
+			summary = "创建微信授权配置"
+		}
+		return s.writeAudit(ctx, tx, op, summary, "wechat_authorization:"+strconv.FormatUint(uint64(authorization.ID), 10), "微信授权配置", authorization.ID, authorizationAuditIdentity(&authorization), before, authorizationAuditIdentity(&authorization))
+	})
+	if err != nil {
+		if appErr, ok := err.(*errors.AppError); ok {
+			return nil, appErr
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "保存微信授权配置失败")
+	}
+	return authorizationResponse(&authorization), nil
+}
+func authorizationResponse(a *model.WechatAuthorization) *dto.WechatAuthorizationResponse {
+	return &dto.WechatAuthorizationResponse{ID: a.ID, OaAppID: a.OaAppID, OaAppSecret: a.OaAppSecret, OaToken: a.OaToken, OaAesKey: a.OaAesKey, OaOAuthRedirectURL: a.OaOAuthRedirectURL, MiniappAppID: a.MiniappAppID, MiniappAppSecret: a.MiniappAppSecret, CredentialVersion: a.CredentialVersion, Enabled: a.Status == model.PaymentMerchantStatusEnabled, UpdatedAt: a.UpdatedAt}
+}

internal/application/merchantpayment/routing.go

@@ -0,0 +1,386 @@
+package merchantpayment
+
+import (
+	"context"
+	"fmt"
+	"strings"
+	"time"
+
+	"github.com/bytedance/sonic"
+	"github.com/redis/go-redis/v9"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// RouteSelection is the non-sensitive route frozen onto a new payment.
+type RouteSelection struct {
+	Merchant *model.PaymentMerchant
+	Pool     *model.PaymentMerchantPool
+}
+
+// RuntimeLoader loads current merchant and authorization credentials by version.
+type RuntimeLoader struct {
+	db    *gorm.DB
+	redis *redis.Client
+}
+
+// merchantCachePayload is used only for the internal versioned Redis cache and deliberately includes credentials.
+// It must never be used for DTOs, logs, audits, or payment snapshots.
+type merchantCachePayload struct {
+	ID                uint        `json:"id"`
+	Name              string      `json:"name"`
+	PaymentMethod     string      `json:"payment_method"`
+	ProviderType      string      `json:"provider_type"`
+	MerchantIdentity  string      `json:"merchant_identity"`
+	Credentials       model.JSONB `json:"credentials"`
+	CredentialVersion int64       `json:"credential_version"`
+	Status            int         `json:"status"`
+	Remark            string      `json:"remark"`
+}
+
+func merchantCachePayloadFrom(merchant *model.PaymentMerchant) merchantCachePayload {
+	return merchantCachePayload{ID: merchant.ID, Name: merchant.Name, PaymentMethod: merchant.PaymentMethod, ProviderType: merchant.ProviderType, MerchantIdentity: merchant.MerchantIdentity, Credentials: merchant.Credentials, CredentialVersion: merchant.CredentialVersion, Status: merchant.Status, Remark: merchant.Remark}
+}
+
+func (p merchantCachePayload) merchant() *model.PaymentMerchant {
+	return &model.PaymentMerchant{Model: gorm.Model{ID: p.ID}, Name: p.Name, PaymentMethod: p.PaymentMethod, ProviderType: p.ProviderType, MerchantIdentity: p.MerchantIdentity, Credentials: p.Credentials, CredentialVersion: p.CredentialVersion, Status: p.Status, Remark: p.Remark}
+}
+
+// authorizationCachePayload is used only for the internal versioned Redis cache and deliberately includes secrets.
+// It must never be used for DTOs, logs, audits, or payment snapshots.
+type authorizationCachePayload struct {
+	ID                 uint   `json:"id"`
+	OaAppID            string `json:"oa_app_id"`
+	OaAppSecret        string `json:"oa_app_secret"`
+	OaToken            string `json:"oa_token"`
+	OaAesKey           string `json:"oa_aes_key"`
+	OaOAuthRedirectURL string `json:"oa_oauth_redirect_url"`
+	MiniappAppID       string `json:"miniapp_app_id"`
+	MiniappAppSecret   string `json:"miniapp_app_secret"`
+	CredentialVersion  int64  `json:"credential_version"`
+	Status             int    `json:"status"`
+}
+
+func authorizationCachePayloadFrom(authorization *model.WechatAuthorization) authorizationCachePayload {
+	return authorizationCachePayload{ID: authorization.ID, OaAppID: authorization.OaAppID, OaAppSecret: authorization.OaAppSecret, OaToken: authorization.OaToken, OaAesKey: authorization.OaAesKey, OaOAuthRedirectURL: authorization.OaOAuthRedirectURL, MiniappAppID: authorization.MiniappAppID, MiniappAppSecret: authorization.MiniappAppSecret, CredentialVersion: authorization.CredentialVersion, Status: authorization.Status}
+}
+
+func (p authorizationCachePayload) authorization() *model.WechatAuthorization {
+	return &model.WechatAuthorization{Model: gorm.Model{ID: p.ID}, OaAppID: p.OaAppID, OaAppSecret: p.OaAppSecret, OaToken: p.OaToken, OaAesKey: p.OaAesKey, OaOAuthRedirectURL: p.OaOAuthRedirectURL, MiniappAppID: p.MiniappAppID, MiniappAppSecret: p.MiniappAppSecret, CredentialVersion: p.CredentialVersion, Status: p.Status}
+}
+
+func NewRuntimeLoader(db *gorm.DB, redis *redis.Client) *RuntimeLoader {
+	return &RuntimeLoader{db: db, redis: redis}
+}
+
+// LoadMerchant first reads the current version from the primary database, then uses only that version's cache entry.
+// Disabled merchants remain loadable for frozen historical payments.
+func (l *RuntimeLoader) LoadMerchant(ctx context.Context, id uint) (*model.PaymentMerchant, error) {
+	if l == nil || l.db == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "支付商户加载能力未配置")
+	}
+	return l.loadMerchant(ctx, l.db, id)
+}
+
+// loadMerchant 先从当前事务或主库读取版本，再仅命中该版本的缓存。
+// 版本在凭证事务提交时递增，因此提交前遗留的旧缓存永远不会被新读取命中。
+func (l *RuntimeLoader) loadMerchant(ctx context.Context, db *gorm.DB, id uint) (*model.PaymentMerchant, error) {
+	var current model.PaymentMerchant
+	if err := db.WithContext(ctx).First(&current, id).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "支付商户不存在")
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "读取支付商户失败")
+	}
+	key := fmt.Sprintf("payment:merchant:%d:%d", current.ID, current.CredentialVersion)
+	if l.redis != nil {
+		if text, err := l.redis.Get(ctx, key).Result(); err == nil {
+			var cached merchantCachePayload
+			if sonic.UnmarshalString(text, &cached) == nil && cached.ID == current.ID && cached.CredentialVersion == current.CredentialVersion {
+				return cached.merchant(), nil
+			}
+		}
+	}
+	if l.redis != nil {
+		if text, err := sonic.MarshalString(merchantCachePayloadFrom(&current)); err == nil {
+			_ = l.redis.Set(ctx, key, text, time.Hour).Err()
+		}
+	}
+	return &current, nil
+}
+
+// LoadAuthorization first reads the current enabled version and only then resolves its versioned cache entry.
+func (l *RuntimeLoader) LoadAuthorization(ctx context.Context) (*model.WechatAuthorization, error) {
+	if l == nil || l.db == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "微信授权加载能力未配置")
+	}
+	var current model.WechatAuthorization
+	if err := l.db.WithContext(ctx).Where("status = ?", model.PaymentMerchantStatusEnabled).First(&current).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeWechatConfigUnavailable, "微信授权未配置")
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "读取微信授权配置失败")
+	}
+	key := fmt.Sprintf("payment:wechat-authorization:%d:%d", current.ID, current.CredentialVersion)
+	if l.redis != nil {
+		if text, err := l.redis.Get(ctx, key).Result(); err == nil {
+			var cached authorizationCachePayload
+			if sonic.UnmarshalString(text, &cached) == nil && cached.ID == current.ID && cached.CredentialVersion == current.CredentialVersion {
+				return cached.authorization(), nil
+			}
+		}
+	}
+	if l.redis != nil {
+		if text, err := sonic.MarshalString(authorizationCachePayloadFrom(&current)); err == nil {
+			_ = l.redis.Set(ctx, key, text, time.Hour).Err()
+		}
+	}
+	return &current, nil
+}
+
+// MerchantConfig adapts the merchant credential payload to existing channel constructors without persisting credentials in a payment snapshot.
+func MerchantConfig(merchant *model.PaymentMerchant, authorization *model.WechatAuthorization) (*model.WechatConfig, error) {
+	if merchant == nil {
+		return nil, errors.New(errors.CodeNoPaymentConfig, "支付商户不存在")
+	}
+	if authorization == nil {
+		authorization = &model.WechatAuthorization{}
+	}
+	raw, err := sonic.Marshal(merchant.Credentials)
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeInvalidParam, err, "支付商户凭证格式无效")
+	}
+	var cfg model.WechatConfig
+	if err := sonic.Unmarshal(raw, &cfg); err != nil {
+		return nil, errors.Wrap(errors.CodeInvalidParam, err, "支付商户凭证格式无效")
+	}
+	cfg.ID = merchant.ID
+	cfg.ProviderType = merchant.ProviderType
+	cfg.IsActive = true
+	if authorization != nil {
+		cfg.OaAppID = authorization.OaAppID
+		cfg.OaAppSecret = authorization.OaAppSecret
+		cfg.OaToken = authorization.OaToken
+		cfg.OaAesKey = authorization.OaAesKey
+		cfg.OaOAuthRedirectURL = authorization.OaOAuthRedirectURL
+		cfg.MiniappAppID = authorization.MiniappAppID
+		cfg.MiniappAppSecret = authorization.MiniappAppSecret
+	}
+	return &cfg, nil
+}
+
+// MerchantConfigWithAuthorization 在需要 AppID 的渠道实例前，按当前版本加载全局微信授权配置。
+// 授权字段只进入内存中的渠道配置，绝不写入支付快照、普通 DTO、日志、审计或导出。
+func (l *RuntimeLoader) MerchantConfigWithAuthorization(ctx context.Context, merchant *model.PaymentMerchant) (*model.WechatConfig, error) {
+	authorization, err := l.LoadAuthorization(ctx)
+	if err != nil {
+		return nil, err
+	}
+	return MerchantConfig(merchant, authorization)
+}
+
+// SelectForNewPayment atomically reads the active pool and chooses its current eligible member.
+func (l *RuntimeLoader) SelectForNewPayment(ctx context.Context, paymentMethod string, now time.Time) (*RouteSelection, error) {
+	if l == nil || l.db == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "商户池路由能力未配置")
+	}
+	var out *RouteSelection
+	err := l.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var err error
+		out, err = l.SelectForNewPaymentWithTx(ctx, tx, paymentMethod, now)
+		return err
+	})
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+// SelectForNewPaymentWithTx chooses an eligible merchant while retaining the caller's business transaction.
+func (l *RuntimeLoader) SelectForNewPaymentWithTx(ctx context.Context, tx *gorm.DB, paymentMethod string, now time.Time) (*RouteSelection, error) {
+	if l == nil || tx == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "商户池路由能力未配置")
+	}
+	var pool model.PaymentMerchantPool
+	if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).Where("payment_method = ? AND status = ?", paymentMethod, model.PaymentMerchantStatusEnabled).First(&pool).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNoPaymentConfig, "暂无可用商户")
+		}
+		return nil, err
+	}
+	var members []model.PaymentMerchantPoolMember
+	if err := tx.WithContext(ctx).Where("pool_id = ?", pool.ID).Order("sort_order ASC").Find(&members).Error; err != nil {
+		return nil, err
+	}
+	if len(members) == 0 {
+		return nil, errors.New(errors.CodeNoPaymentConfig, "暂无可用商户")
+	}
+	ids := make([]uint, 0, len(members))
+	for _, member := range members {
+		ids = append(ids, member.MerchantID)
+	}
+	var merchants []model.PaymentMerchant
+	if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).Where("id IN ? AND payment_method = ? AND status = ?", ids, pool.PaymentMethod, model.PaymentMerchantStatusEnabled).Find(&merchants).Error; err != nil {
+		return nil, err
+	}
+	byID := make(map[uint]*model.PaymentMerchant, len(merchants))
+	for i := range merchants {
+		byID[merchants[i].ID] = &merchants[i]
+	}
+	ordered := make([]*model.PaymentMerchant, 0, len(members))
+	for _, member := range members {
+		if merchant := byID[member.MerchantID]; merchant != nil {
+			ordered = append(ordered, merchant)
+		}
+	}
+	chosen, err := chooseMerchant(ctx, tx, &pool, ordered, now)
+	if err != nil {
+		return nil, err
+	}
+	// 新支付在冻结前也按“商户 ID + 当前版本”读取缓存；事务锁保证本次
+	// 选择与凭证版本属于同一提交边界，避免新建支付误用旧版本缓存。
+	chosen, err = l.loadMerchant(ctx, tx, chosen.ID)
+	if err != nil {
+		return nil, err
+	}
+	return &RouteSelection{Merchant: chosen, Pool: &pool}, nil
+}
+
+func chooseMerchant(ctx context.Context, tx *gorm.DB, pool *model.PaymentMerchantPool, merchants []*model.PaymentMerchant, now time.Time) (*model.PaymentMerchant, error) {
+	if len(merchants) == 0 {
+		return nil, errors.New(errors.CodeNoPaymentConfig, "暂无可用商户")
+	}
+	if pool.Strategy == model.PaymentMerchantStrategyTime {
+		return chooseTimedMerchant(pool, merchants, now)
+	}
+	if pool.Strategy != model.PaymentMerchantStrategyAmount && pool.Strategy != model.PaymentMerchantStrategyCount {
+		return nil, errors.New(errors.CodeInvalidStatus, "商户池轮询策略无效")
+	}
+	if pool.StatisticCycle == nil {
+		return nil, errors.New(errors.CodeInvalidStatus, "商户池统计周期未配置")
+	}
+
+	query := tx.WithContext(ctx).Where("pool_id = ? AND routing_epoch = ?", pool.ID, pool.RoutingEpoch)
+	if start, limited := routingWindowStart(*pool.StatisticCycle, now); limited {
+		query = query.Where("paid_at >= ?", start)
+	}
+	var rows []model.PaymentMerchantRoutingSuccess
+	if err := query.Find(&rows).Error; err != nil {
+		return nil, err
+	}
+	amounts := make(map[uint]int64, len(merchants))
+	counts := make(map[uint]int64, len(merchants))
+	for _, row := range rows {
+		amounts[row.MerchantID] += row.Amount
+		counts[row.MerchantID]++
+	}
+	for _, merchant := range merchants {
+		if pool.Strategy == model.PaymentMerchantStrategyAmount {
+			if pool.ThresholdAmount == nil {
+				return nil, errors.New(errors.CodeInvalidStatus, "金额轮询阈值未配置")
+			}
+			if amounts[merchant.ID] < *pool.ThresholdAmount {
+				return merchant, nil
+			}
+			continue
+		}
+		if pool.ThresholdCount == nil {
+			return nil, errors.New(errors.CodeInvalidStatus, "笔数轮询阈值未配置")
+		}
+		if counts[merchant.ID] < *pool.ThresholdCount {
+			return merchant, nil
+		}
+	}
+	if *pool.StatisticCycle != "round" {
+		return nil, errors.New(errors.CodeNoPaymentConfig, "当前统计周期内暂无可用商户")
+	}
+	if err := advanceRoutingEpoch(ctx, tx, pool); err != nil {
+		return nil, err
+	}
+	return merchants[0], nil
+}
+
+func chooseTimedMerchant(pool *model.PaymentMerchantPool, merchants []*model.PaymentMerchant, now time.Time) (*model.PaymentMerchant, error) {
+	if pool.TimePeriodStartedAt == nil || pool.TimePeriodValue == nil || pool.TimePeriodUnit == nil {
+		return nil, errors.New(errors.CodeInvalidStatus, "时间轮询配置不完整")
+	}
+	unit := time.Minute
+	switch *pool.TimePeriodUnit {
+	case "hour":
+		unit = time.Hour
+	case "day":
+		unit = 24 * time.Hour
+	case "minute":
+	default:
+		return nil, errors.New(errors.CodeInvalidStatus, "时间轮询单位无效")
+	}
+	period := unit * time.Duration(*pool.TimePeriodValue)
+	if period <= 0 {
+		return nil, errors.New(errors.CodeInvalidStatus, "时间轮询周期无效")
+	}
+	slot := now.Sub(*pool.TimePeriodStartedAt) / period
+	if slot < 0 {
+		slot = 0
+	}
+	return merchants[int(slot%time.Duration(len(merchants)))], nil
+}
+
+func routingWindowStart(cycle string, now time.Time) (time.Time, bool) {
+	local := now.In(now.Location())
+	switch cycle {
+	case "day":
+		return time.Date(local.Year(), local.Month(), local.Day(), 0, 0, 0, 0, local.Location()), true
+	case "month":
+		return time.Date(local.Year(), local.Month(), 1, 0, 0, 0, 0, local.Location()), true
+	default:
+		return time.Time{}, false
+	}
+}
+
+func advanceRoutingEpoch(ctx context.Context, tx *gorm.DB, pool *model.PaymentMerchantPool) error {
+	next := pool.RoutingEpoch + 1
+	result := tx.WithContext(ctx).Model(&model.PaymentMerchantPool{}).Where("id = ? AND routing_epoch = ?", pool.ID, pool.RoutingEpoch).Update("routing_epoch", next)
+	if result.Error != nil {
+		return result.Error
+	}
+	if result.RowsAffected != 1 {
+		return errors.New(errors.CodeConflict, "商户池统计世代已变化")
+	}
+	pool.RoutingEpoch = next
+	return nil
+}
+
+// FreezeRoute writes only non-sensitive route facts onto the payment.
+func FreezeRoute(payment *model.Payment, route *RouteSelection) {
+	if payment == nil || route == nil || route.Merchant == nil || route.Pool == nil {
+		return
+	}
+	payment.MerchantID = &route.Merchant.ID
+	payment.MerchantPoolID = &route.Pool.ID
+	payment.MerchantIdentity = route.Merchant.MerchantIdentity
+	payment.MerchantNameSnapshot = route.Merchant.Name
+	payment.MerchantPaymentMethodSnapshot = route.Merchant.PaymentMethod
+	payment.MerchantProviderTypeSnapshot = route.Merchant.ProviderType
+	payment.MerchantPoolNameSnapshot = route.Pool.Name
+	payment.RoutingStrategySnapshot = route.Pool.Strategy
+	epoch := route.Pool.RoutingEpoch
+	payment.RoutingEpoch = &epoch
+}
+
+// RecordFirstSuccess 在支付成功事务内写入支付不可变的路由事实。
+func RecordFirstSuccess(ctx context.Context, tx *gorm.DB, payment *model.Payment, paidAt time.Time) error {
+	if payment == nil || payment.MerchantID == nil || payment.MerchantPoolID == nil || payment.RoutingEpoch == nil {
+		return nil
+	}
+	fact := model.PaymentMerchantRoutingSuccess{PaymentID: payment.ID, MerchantID: *payment.MerchantID, PoolID: *payment.MerchantPoolID, RoutingEpoch: *payment.RoutingEpoch, Amount: payment.Amount, PaidAt: paidAt}
+	if err := tx.WithContext(ctx).Create(&fact).Error; err != nil {
+		if strings.Contains(err.Error(), "duplicate key") {
+			return nil
+		}
+		return errors.Wrap(errors.CodeDatabaseError, err, "写入商户池成功统计失败")
+	}
+	return nil
+}

internal/application/refundapproval/creation.go

@@ -8,6 +8,7 @@ import (
 
 	"github.com/bytedance/sonic"
 	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
 
 	approvalapp "github.com/break/junhong_cmp_fiber/internal/application/approval"
 	"github.com/break/junhong_cmp_fiber/internal/model"
@@ -55,6 +56,99 @@ func NewCreationService(db *gorm.DB, approval approvalapp.Port, audit AuditWrite
 }
 
 // Execute 在业务写入前校验审批渠道，并在同一事务冻结退款事实和审批事实。
+// TriggerHistorical 为历史待审批退款补发一次企业微信审批。
+func (s *CreationService) TriggerHistorical(ctx context.Context, refundID uint) (*CreateResult, error) {
+	if s == nil || s.db == nil || s.approval == nil || s.audit == nil || refundID == 0 {
+		return nil, errors.New(errors.CodeServiceUnavailable, "退款审批能力未配置")
+	}
+
+	var refund model.RefundRequest
+	if err := s.db.WithContext(ctx).First(&refund, refundID).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "退款申请不存在")
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询历史退款申请失败")
+	}
+	if refund.Status != model.RefundStatusPending || refund.ApprovalInstanceID != nil {
+		return nil, errors.New(errors.CodeConflict, "退款申请状态不允许补发审批")
+	}
+
+	account, err := s.loadSubmitter(ctx, refund.Creator)
+	if err != nil {
+		return nil, err
+	}
+	var order model.Order
+	if err := s.db.WithContext(ctx).First(&order, refund.OrderID).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeNotFound, "退款关联订单不存在")
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询退款关联订单失败")
+	}
+	preparation, err := s.approval.Prepare(ctx, approvalapp.PrepareRequest{
+		BusinessType: constants.ApprovalBusinessTypeRefund, SubmitterAccountID: refund.Creator,
+		CorrelationID: refund.RefundNo,
+	})
+	if err != nil {
+		return nil, err
+	}
+	submitterSnapshot, requestSnapshot, err := refundSnapshots(&refund, account)
+	if err != nil {
+		return nil, err
+	}
+
+	var approvalStatus int
+	err = s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+		var current model.RefundRequest
+		if err := tx.WithContext(ctx).Clauses(clause.Locking{Strength: "UPDATE"}).First(&current, refundID).Error; err != nil {
+			if err == gorm.ErrRecordNotFound {
+				return errors.New(errors.CodeNotFound, "退款申请不存在")
+			}
+			return errors.Wrap(errors.CodeDatabaseError, err, "锁定历史退款申请失败")
+		}
+		if current.Status != model.RefundStatusPending || current.ApprovalInstanceID != nil {
+			return errors.New(errors.CodeConflict, "退款申请状态不允许补发审批")
+		}
+
+		var currentOrder model.Order
+		if err := tx.WithContext(ctx).First(&currentOrder, current.OrderID).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "查询退款关联订单失败")
+		}
+		reference, err := s.approval.CreateInTx(ctx, tx, approvalapp.CreateRequest{
+			Preparation: preparation, BusinessType: constants.ApprovalBusinessTypeRefund,
+			BusinessID: current.ID, SubmitterAccountID: current.Creator,
+			SubmitterSnapshot: submitterSnapshot, RequestSnapshot: requestSnapshot,
+			CorrelationID: current.RefundNo,
+		})
+		if err != nil {
+			return err
+		}
+		result := tx.WithContext(ctx).Model(&model.RefundRequest{}).
+			Where("id = ? AND status = ? AND approval_instance_id IS NULL", current.ID, model.RefundStatusPending).
+			Update("approval_instance_id", reference.InstanceID)
+		if result.Error != nil {
+			return errors.Wrap(errors.CodeDatabaseError, result.Error, "关联退款审批实例失败")
+		}
+		if result.RowsAffected != 1 {
+			return errors.New(errors.CodeConflict, "退款审批实例关联已变化")
+		}
+		current.ApprovalInstanceID = &reference.InstanceID
+		refund = current
+		order = currentOrder
+		approvalStatus = reference.Status
+		var instance model.ApprovalInstance
+		if err := tx.WithContext(ctx).First(&instance, reference.InstanceID).Error; err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "查询退款审批审计快照失败")
+		}
+		return s.audit.WriteRefundApplication(ctx, tx, ApplicationAudit{
+			Refund: &current, Order: &currentOrder, Approval: &instance, Submitter: account,
+		})
+	})
+	if err != nil {
+		return nil, err
+	}
+	return &CreateResult{Refund: &refund, SubmitterName: account.Username, ApprovalStatus: approvalStatus}, nil
+}
+
 func (s *CreationService) Execute(ctx context.Context, command CreateCommand) (*CreateResult, error) {
 	if s == nil || s.db == nil || s.approval == nil || s.audit == nil {
 		return nil, errors.New(errors.CodeServiceUnavailable, "退款审批能力未配置")

internal/application/wecom/scene.go

@@ -317,6 +317,10 @@ func sceneBusinessFields(businessType string) ([]dto.WeComBusinessFieldResponse,
 			{Code: constants.ApprovalFieldRemark, Name: "备注", ValueType: constants.ApprovalFieldValueTypeString, Description: "员工提交线下代充值时填写的备注"},
 			{Code: constants.ApprovalFieldSubmitterID, Name: "提交人账号 ID", ValueType: constants.ApprovalFieldValueTypeInteger, Description: "本系统真实业务提交人账号 ID"},
 			{Code: constants.ApprovalFieldSubmitterName, Name: "提交人名称", ValueType: constants.ApprovalFieldValueTypeString, Description: "本系统真实业务提交人名称快照"},
+			{Code: constants.ApprovalFieldOfflinePaymentMethod, Name: "线下收款方式", ValueType: constants.ApprovalFieldValueTypeString, Description: "本次充值使用的线下收款方式名称快照"},
+			{Code: constants.ApprovalFieldOfflinePaymentMethodCode, Name: "线下收款方式编码", ValueType: constants.ApprovalFieldValueTypeString, Description: "本次充值使用的线下收款方式稳定编码快照"},
+			{Code: constants.ApprovalFieldExternalTransactionNo, Name: "交易流水号", ValueType: constants.ApprovalFieldValueTypeString, Description: "人工确认的第三方交易流水号，用于审批人核验；与在线渠道交易号无关"},
+			{Code: constants.ApprovalFieldOtherVoucherKey, Name: "其他凭证", ValueType: constants.ApprovalFieldValueTypeFileList, Description: "提交时上传到企微文件控件的其他凭证列表"},
 		}, true
 	case constants.ApprovalBusinessTypeRefund:
 		return []dto.WeComBusinessFieldResponse{
@@ -333,6 +337,22 @@ func sceneBusinessFields(businessType string) ([]dto.WeComBusinessFieldResponse,
 			{Code: constants.ApprovalFieldSubmitterID, Name: "提交人账号 ID", ValueType: constants.ApprovalFieldValueTypeInteger, Description: "本系统真实业务提交人账号 ID"},
 			{Code: constants.ApprovalFieldSubmitterName, Name: "提交人名称", ValueType: constants.ApprovalFieldValueTypeString, Description: "本系统真实业务提交人名称快照"},
 		}, true
+	case constants.ApprovalBusinessTypeEmployeeCollection:
+		return []dto.WeComBusinessFieldResponse{
+			{Code: constants.ApprovalFieldCollectionApplicationID, Name: "核销申请 ID", ValueType: constants.ApprovalFieldValueTypeInteger, Description: "员工代收款核销申请的系统 ID"},
+			{Code: constants.ApprovalFieldCollectionPaymentMethod, Name: "线下收款方式", ValueType: constants.ApprovalFieldValueTypeString, Description: "本次外部付款使用的线下收款方式名称快照"},
+			{Code: constants.ApprovalFieldCollectionPaidAmount, Name: "付款金额", ValueType: constants.ApprovalFieldValueTypeMoney, Description: "以元为单位且保留两位小数的人工确认付款金额"},
+			{Code: constants.ApprovalFieldCollectionPaidAmountCent, Name: "付款金额（分）", ValueType: constants.ApprovalFieldValueTypeInteger, Description: "以分为单位的人工确认付款金额整数"},
+			{Code: constants.ApprovalFieldCollectionPayerName, Name: "付款方", ValueType: constants.ApprovalFieldValueTypeString, Description: "本次外部付款的付款方名称"},
+			{Code: constants.ApprovalFieldCollectionPaidAt, Name: "付款时间", ValueType: constants.ApprovalFieldValueTypeString, Description: "本次外部付款时间，RFC3339 格式"},
+			{Code: constants.ApprovalFieldCollectionExternalTransactionNo, Name: "外部交易流水号", ValueType: constants.ApprovalFieldValueTypeString, Description: "人工确认的第三方交易流水号，用于审批人核验"},
+			{Code: constants.ApprovalFieldPaymentVoucherKey, Name: "付款凭证", ValueType: constants.ApprovalFieldValueTypeFileList, Description: "提交时上传到企微文件控件的付款凭证列表"},
+			{Code: constants.ApprovalFieldRemark, Name: "备注", ValueType: constants.ApprovalFieldValueTypeString, Description: "申请人填写的核销备注"},
+			{Code: constants.ApprovalFieldCollectionBillCount, Name: "分摊账单数量", ValueType: constants.ApprovalFieldValueTypeInteger, Description: "本次核销分摊的账单数量"},
+			{Code: constants.ApprovalFieldCollectionBillSummary, Name: "账单分摊摘要", ValueType: constants.ApprovalFieldValueTypeString, Description: "本次各账单应收金额与分摊金额摘要"},
+			{Code: constants.ApprovalFieldSubmitterID, Name: "提交人账号 ID", ValueType: constants.ApprovalFieldValueTypeInteger, Description: "本系统真实业务提交人账号 ID"},
+			{Code: constants.ApprovalFieldSubmitterName, Name: "提交人名称", ValueType: constants.ApprovalFieldValueTypeString, Description: "本系统真实业务提交人名称快照"},
+		}, true
 	default:
 		return nil, false
 	}
@@ -353,14 +373,27 @@ func normalizeSceneMapping(mapping []dto.WeComControlMappingItem) []dto.WeComCon
 }
 
 func validApprovalBusinessType(businessType string) bool {
-	return businessType == constants.ApprovalBusinessTypeRefund || businessType == constants.ApprovalBusinessTypeOfflineRecharge
+	switch businessType {
+	case constants.ApprovalBusinessTypeRefund,
+		constants.ApprovalBusinessTypeOfflineRecharge,
+		constants.ApprovalBusinessTypeEmployeeCollection:
+		return true
+	default:
+		return false
+	}
 }
 
 func approvalBusinessTypeName(businessType string) string {
-	if businessType == constants.ApprovalBusinessTypeRefund {
+	switch businessType {
+	case constants.ApprovalBusinessTypeRefund:
 		return "退款审批"
+	case constants.ApprovalBusinessTypeOfflineRecharge:
+		return "员工线下代充值审批"
+	case constants.ApprovalBusinessTypeEmployeeCollection:
+		return "员工代收款核销审批"
+	default:
+		return "未知审批业务类型"
 	}
-	return "员工线下代充值审批"
 }
 
 func sceneAuditSnapshot(scene *model.WeComApprovalScene) map[string]any {

internal/bootstrap/handlers.go

@@ -1,6 +1,9 @@
 package bootstrap
 
 import (
+	agentrechargeApp "github.com/break/junhong_cmp_fiber/internal/application/agentrecharge"
+	employeecollectionApp "github.com/break/junhong_cmp_fiber/internal/application/employeecollection"
+	merchantPaymentApp "github.com/break/junhong_cmp_fiber/internal/application/merchantpayment"
 	notificationApp "github.com/break/junhong_cmp_fiber/internal/application/notification"
 	roleApp "github.com/break/junhong_cmp_fiber/internal/application/role"
 	shopApp "github.com/break/junhong_cmp_fiber/internal/application/shop"
@@ -21,6 +24,7 @@ import (
 	agentRechargeQuery "github.com/break/junhong_cmp_fiber/internal/query/agentrecharge"
 	assetQuery "github.com/break/junhong_cmp_fiber/internal/query/asset"
 	auditQuery "github.com/break/junhong_cmp_fiber/internal/query/audit"
+	employeecollectionQuery "github.com/break/junhong_cmp_fiber/internal/query/employeecollection"
 	exchangeQuery "github.com/break/junhong_cmp_fiber/internal/query/exchange"
 	integrationQuery "github.com/break/junhong_cmp_fiber/internal/query/integration"
 	notificationQuery "github.com/break/junhong_cmp_fiber/internal/query/notification"
@@ -86,7 +90,6 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
 		personalCustomerOpenIDStore,
 		personalCustomerStore,
 		personalCustomerPhoneStore,
-		svc.WechatConfig,
 		svc.Order,
 		packageSeriesStore,
 		shopSeriesAllocationStore,
@@ -108,9 +111,13 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
 		systemConfigCache = systemConfigInfra.NewRedisCache(deps.Redis)
 	}
 	systemConfigReader := systemConfigInfra.NewReader(deps.DB, systemConfigRegistry, systemConfigCache, systemConfigAlerts)
+	if svc.AgentRechargeOnline != nil {
+		svc.AgentRechargeOnline.SetPaymentMethodPolicy(agentrechargeApp.NewOnlinePaymentMethodPolicy(systemConfigReader))
+	}
 	paymentMethodPolicy := paymentmethod.NewPolicy(systemConfigReader)
 	clientOrderService.SetPaymentMethodPolicy(paymentMethodPolicy)
 	clientOrderService.SetPaymentAudit(svc.AccessAudit, integrationlog.NewRepository(deps.DB))
+	clientOrderService.SetLegacyPaymentConfigService(svc.WechatConfig)
 	systemConfigList := systemConfigQuery.NewListQuery(systemConfigReader)
 	systemConfigAudit := deps.SystemConfigAudit
 	if systemConfigAudit == nil {
@@ -173,7 +180,7 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
 			return handler
 		}(),
 		ClientWallet: func() *app.ClientWalletHandler {
-			handler := app.NewClientWalletHandler(svc.Asset, svc.CustomerBinding, assetWalletStore, assetWalletTransactionStore, rechargeOrderStore, paymentStore, svc.Recharge, personalCustomerOpenIDStore, svc.WechatConfig, deps.Redis, deps.Logger, deps.DB, iotCardStore, deviceStore)
+			handler := app.NewClientWalletHandler(svc.Asset, svc.CustomerBinding, assetWalletStore, assetWalletTransactionStore, rechargeOrderStore, paymentStore, svc.Recharge, personalCustomerOpenIDStore, deps.Redis, deps.Logger, deps.DB, iotCardStore, deviceStore)
 			handler.SetPaymentMethodPolicy(paymentMethodPolicy)
 			handler.SetPaymentAudit(svc.AccessAudit, integrationlog.NewRepository(deps.DB))
 			return handler
@@ -284,11 +291,25 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
 			h.SetAssetService(svc.Asset)
 			return h
 		}(),
-		WechatConfig: admin.NewWechatConfigHandler(svc.WechatConfig),
+		WechatConfig:    admin.NewWechatConfigHandler(svc.WechatConfig),
+		PaymentMerchant: admin.NewPaymentMerchantHandler(merchantPaymentApp.NewManagementService(deps.DB, systemConfigAudit)),
+		EmployeeCollection: func() *admin.EmployeeCollectionHandler {
+			handler := admin.NewEmployeeCollectionHandler(
+				employeecollectionApp.NewPaymentMethodService(deps.DB, svc.AccessAudit),
+				employeecollectionApp.NewBillCloseService(deps.DB, svc.AccessAudit),
+				employeecollectionApp.NewApplicationService(deps.DB, svc.Approval, svc.AccessAudit),
+			)
+			handler.SetPaymentMethodQuery(employeecollectionQuery.NewPaymentMethodQuery(deps.DB))
+			handler.SetBillQuery(employeecollectionQuery.NewBillQuery(deps.DB))
+			handler.SetApplicationQuery(employeecollectionQuery.NewApplicationQuery(deps.DB))
+			return handler
+		}(),
 		AgentRecharge: func() *admin.AgentRechargeHandler {
 			handler := admin.NewAgentRechargeHandler(svc.AgentRecharge, validate)
 			handler.SetOnlineCreationService(svc.AgentRechargeOnline)
 			handler.SetPaymentStatusQuery(agentRechargeQuery.NewPaymentStatusQuery(deps.DB))
+			handler.SetPaymentVoucherOCRService(svc.AgentRechargeVoucherOCR)
+			handler.SetSystemConfigUpdateService(systemConfigUpdate)
 			return handler
 		}(),
 		Refund:                 admin.NewRefundHandler(svc.Refund),

internal/bootstrap/payment_method_config.go

@@ -15,6 +15,7 @@ func registerPaymentMethodConfigDefinitions(registry *systemconfig.Registry, log
 	definitions := []systemconfig.Definition{
 		{Key: constants.SystemConfigPaymentAllowedCard, Module: constants.SystemConfigModulePayment, ValueType: constants.SystemConfigTypeJSON, DefaultValue: `["wallet","wechat","alipay"]`, Description: "卡资产允许的C端支付方式", Control: "payment_methods", Validator: paymentmethod.ValidateConfigValue},
 		{Key: constants.SystemConfigPaymentAllowedDevice, Module: constants.SystemConfigModulePayment, ValueType: constants.SystemConfigTypeJSON, DefaultValue: `["wallet","wechat","alipay"]`, Description: "设备资产允许的C端支付方式", Control: "payment_methods", Validator: paymentmethod.ValidateConfigValue},
+		{Key: constants.SystemConfigAgentSelfRechargeAllowedMethods, Module: constants.SystemConfigModulePayment, ValueType: constants.SystemConfigTypeString, DefaultValue: constants.AgentSelfRechargeAllowedBoth, Description: "代理在线自充允许的支付方式范围", Control: "payment_methods", EnumValues: []string{constants.AgentSelfRechargeAllowedWechatOnly, constants.AgentSelfRechargeAllowedAlipayOnly, constants.AgentSelfRechargeAllowedBoth}},
 	}
 	for _, definition := range definitions {
 		if existing, exists := registry.Get(definition.Key); exists {

internal/bootstrap/services.go

@@ -8,7 +8,9 @@ import (
 	agentrechargeApp "github.com/break/junhong_cmp_fiber/internal/application/agentrecharge"
 	approvalApp "github.com/break/junhong_cmp_fiber/internal/application/approval"
 	cardObservationApp "github.com/break/junhong_cmp_fiber/internal/application/cardobservation"
+	employeecollectionApp "github.com/break/junhong_cmp_fiber/internal/application/employeecollection"
 	exchangeApp "github.com/break/junhong_cmp_fiber/internal/application/exchange"
+	merchantpayment "github.com/break/junhong_cmp_fiber/internal/application/merchantpayment"
 	refundapprovalApp "github.com/break/junhong_cmp_fiber/internal/application/refundapproval"
 	walletapp "github.com/break/junhong_cmp_fiber/internal/application/wallet"
 	approvalInfra "github.com/break/junhong_cmp_fiber/internal/infrastructure/approval"
@@ -127,6 +129,7 @@ type services struct {
 	AgentRecharge               *agentRechargeSvc.Service
 	AgentRechargeOnline         *agentrechargeApp.OnlineCreationService
 	AgentRechargePaymentConfirm *agentrechargeApp.ConfirmOnlinePaymentService
+	AgentRechargeVoucherOCR     *agentrechargeApp.PaymentVoucherOCRService
 	PackageActivation           *packageSvc.ActivationService
 	Refund                      *refundSvc.Service
 	TrafficQuery                *trafficSvc.QueryService
@@ -264,6 +267,10 @@ func initServices(s *stores, deps *Dependencies) *services {
 	packageSeriesService := packageSeriesSvc.New(s.PackageSeries, s.ShopSeriesAllocation, s.Package)
 	packageSeriesService.SetAccessAudit(deps.DB, auditWriter)
 	orderService := orderSvc.New(deps.DB, deps.Redis, s.Order, s.OrderItem, s.AgentWallet, s.AssetWallet, s.Payment, purchaseValidation, s.ShopPackageAllocation, s.ShopSeriesAllocation, s.IotCard, s.Device, s.PackageSeries, s.PackageUsage, s.Package, wechatConfig, deps.WechatPayment, paymentLoader, deps.QueueClient, deps.Logger, s.AssetIdentifier, s.PersonalCustomer, s.PersonalCustomerPhone)
+	// 员工代收款建账用例在订单、充值入账与退款冲销的事务内复用同一实例。
+	employeeCollectionBillCreation := employeecollectionApp.NewBillCreationService(auditWriter)
+	orderService.SetEmployeeCollectionBillCreation(employeeCollectionBillCreation)
+	orderService.SetResumeCallback(stopResumeService)
 	orderService.SetLifecycleAudit(auditWriter)
 	orderService.SetPaymentIntegrationLog(integrationlog.NewRepository(deps.DB))
 	orderService.SetObservationSeriesEventWriter(observationSeriesEvents)
@@ -286,8 +293,10 @@ func initServices(s *stores, deps *Dependencies) *services {
 	paymentIntegration := integrationlog.NewRepository(deps.DB)
 	agentRechargeOnline := agentrechargeApp.NewOnlineCreationService(
 		deps.DB,
+		merchantpayment.NewRuntimeLoader(deps.DB, deps.Redis),
 		paymentInfra.NewWechatWebAdapter(wechat.NewRedisCache(deps.Redis), paymentIntegration, deps.Logger),
 		paymentInfra.NewAlipayWapAdapter(paymentIntegration, deps.Logger),
+		paymentInfra.NewFuiouScanAdapter(paymentIntegration, deps.Logger),
 		auditWriter,
 	)
 	agentRechargePaymentConfirm := agentrechargeApp.NewConfirmOnlinePaymentService(
@@ -295,6 +304,11 @@ func initServices(s *stores, deps *Dependencies) *services {
 		paymentInfra.NewAgentRechargePaymentEventWriter(outbox.NewRepository()),
 		auditWriter,
 	)
+	// 付款凭证识别需要对象存储与 Gateway；任一缺失时不装配，接口统一返回能力未配置。
+	var agentRechargeVoucherOCR *agentrechargeApp.PaymentVoucherOCRService
+	if deps.StorageService != nil && deps.GatewayClient != nil {
+		agentRechargeVoucherOCR = agentrechargeApp.NewPaymentVoucherOCRService(deps.StorageService.Provider(), deps.GatewayClient)
+	}
 	refundService := refundSvc.New(
 		deps.DB,
 		s.RefundRequest,
@@ -312,6 +326,7 @@ func initServices(s *stores, deps *Dependencies) *services {
 	)
 	refundService.SetAgentWalletRefundService(walletapp.NewRefundService(walletinfra.NewRefundEventWriter(walletOutbox), nil))
 	refundService.SetNotificationOutbox(walletOutbox)
+	refundService.SetPaymentMerchantRuntime(merchantpayment.NewRuntimeLoader(deps.DB, deps.Redis))
 	refundService.SetLifecycleAudit(auditWriter)
 	exchangeService := exchangeSvc.New(deps.DB, s.ExchangeOrder, s.IotCard, s.Device, s.AssetWallet, s.AssetWalletTransaction, s.PackageUsage, s.PackageUsageDailyRecord, s.ResourceTag, customerBinding, deps.Logger)
 	exchangeService.SetShippingCreatedNotifier(exchangeApp.NewShippingCreatedNotifier(exchangeInfra.NewShippingNotificationWriter(outbox.NewRepository())))
@@ -319,7 +334,6 @@ func initServices(s *stores, deps *Dependencies) *services {
 	assetService := assetSvc.New(deps.DB, s.Device, s.IotCard, s.PackageUsage, s.Package, s.PackageSeries, s.DeviceSimBinding, s.Shop, deps.Redis, iotCard, deps.GatewayClient, s.AssetIdentifier, s.Order, s.OrderItem, s.ExchangeOrder)
 	assetService.SetAccessAudit(auditWriter)
 	agentOpenAPI := agentOpenAPISvc.New(assetService, packageService, orderService, shopCommission, stopResumeService, device, s.IotCard, s.PackageUsage, s.Package, s.PackageSeries, s.AgentWallet, s.DeviceSimBinding, s.Device)
-	agentOpenAPI.SetObservationSeriesDispatcher(observationSeries)
 	wecomApplicationRepository := wecomInfra.NewApplicationRepository(deps.DB)
 	wecomSceneRepository := wecomInfra.NewSceneRepository(deps.DB)
 	wecomMemberRepository := wecomInfra.NewMemberRepository(deps.DB)
@@ -348,6 +362,10 @@ func initServices(s *stores, deps *Dependencies) *services {
 		agentrechargeApp.NewOfflineCreationService(deps.DB, approvalCreationService, auditWriter),
 	)
 	agentRechargeService.SetRechargeAudit(auditWriter)
+	agentRechargeService.SetEmployeeCollectionBillCreation(employeeCollectionBillCreation)
+	refundService.SetEmployeeCollectionRefundOffset(
+		employeecollectionApp.NewRefundOffsetService(auditWriter),
+	)
 	refundService.SetRefundApprovalCreationService(
 		refundapprovalApp.NewCreationService(deps.DB, approvalCreationService, auditWriter),
 	)
@@ -453,6 +471,7 @@ func initServices(s *stores, deps *Dependencies) *services {
 		AgentRecharge:               agentRechargeService,
 		AgentRechargeOnline:         agentRechargeOnline,
 		AgentRechargePaymentConfirm: agentRechargePaymentConfirm,
+		AgentRechargeVoucherOCR:     agentRechargeVoucherOCR,
 		PackageActivation:           packageActivation,
 		TrafficQuery:                trafficSvc.NewQueryService(deps.Redis, s.CardDailyUsage),
 		OperationPassword:           operationPassword,

internal/bootstrap/types.go

@@ -68,6 +68,8 @@ type Handlers struct {
 	AssetLifecycle              *admin.AssetLifecycleHandler
 	AssetWallet                 *admin.AssetWalletHandler
 	WechatConfig                *admin.WechatConfigHandler
+	PaymentMerchant             *admin.PaymentMerchantHandler
+	EmployeeCollection          *admin.EmployeeCollectionHandler
 	AgentRecharge               *admin.AgentRechargeHandler
 	Refund                      *admin.RefundHandler
 	OrderPackageInvalidate      *admin.OrderPackageInvalidateHandler

internal/domain/agentrecharge/payment_confirmation.go

@@ -3,6 +3,7 @@ package agentrecharge
 import (
 	"strings"
 
+	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 )
@@ -23,25 +24,28 @@ const (
 
 // PaymentConfirmationFacts 是支付确认所需的渠道与本地权威事实。
 type PaymentConfirmationFacts struct {
-	OrderType                 string
-	ExpectedOrderType         string
-	PaymentMethod             string
-	RechargePaymentMethod     string
-	RechargePaymentChannel    string
-	PaymentConfigID           uint
-	RechargePaymentConfigID   uint
-	ConfirmedConfigID         uint
-	MerchantIdentity          string
-	ConfirmedMerchantIdentity string
-	PaymentAmount             int64
-	RechargeAmount            int64
-	ConfirmedAmount           int64
-	PaymentOrderID            uint
-	RechargeID                uint
-	PaymentState              PaymentState
-	RechargeStatus            int
-	StoredTradeNo             string
-	ConfirmedTradeNo          string
+	OrderType                   string
+	ExpectedOrderType           string
+	PaymentMethod               string
+	RechargePaymentMethod       string
+	RechargePaymentChannel      string
+	PaymentConfigID             uint
+	RechargePaymentConfigID     uint
+	ConfirmedConfigID           uint
+	FrozenMerchant              bool
+	FrozenMerchantPaymentMethod string
+	FrozenMerchantProviderType  string
+	MerchantIdentity            string
+	ConfirmedMerchantIdentity   string
+	PaymentAmount               int64
+	RechargeAmount              int64
+	ConfirmedAmount             int64
+	PaymentOrderID              uint
+	RechargeID                  uint
+	PaymentState                PaymentState
+	RechargeStatus              int
+	StoredTradeNo               string
+	ConfirmedTradeNo            string
 }
 
 // ValidatePaymentConfirmation 校验支付确认不变量，并返回是否属于完全一致的重复确认。
@@ -51,12 +55,28 @@ func ValidatePaymentConfirmation(facts PaymentConfirmationFacts) (bool, error) {
 		return false, errors.New(errors.CodeConflict, "支付单与代理充值单关联不一致")
 	}
 	method := strings.TrimSpace(facts.PaymentMethod)
-	if method == "" || method != strings.TrimSpace(facts.RechargePaymentMethod) ||
-		method != strings.TrimSpace(facts.RechargePaymentChannel) {
+	if method == "" || method != strings.TrimSpace(facts.RechargePaymentMethod) {
+		return false, errors.New(errors.CodeConflict, "支付渠道与代理充值单不一致")
+	}
+	channel := strings.TrimSpace(facts.RechargePaymentChannel)
+	if channel != method && !(method == constants.RechargeMethodWechat && channel == model.ProviderTypeFuiou) {
 		return false, errors.New(errors.CodeConflict, "支付渠道与代理充值单不一致")
 	}
 	identity := strings.TrimSpace(facts.MerchantIdentity)
-	if facts.PaymentConfigID == 0 || facts.PaymentConfigID != facts.RechargePaymentConfigID ||
+	if facts.FrozenMerchant {
+		frozenMethod := strings.TrimSpace(facts.FrozenMerchantPaymentMethod)
+		providerType := strings.TrimSpace(facts.FrozenMerchantProviderType)
+		if identity == "" || frozenMethod != method || providerType == "" {
+			return false, errors.New(errors.CodeConflict, "冻结商户支付事实不一致")
+		}
+		expectedChannel := method
+		if method == constants.RechargeMethodWechat && providerType == model.ProviderTypeFuiou {
+			expectedChannel = model.ProviderTypeFuiou
+		}
+		if channel != expectedChannel {
+			return false, errors.New(errors.CodeConflict, "支付渠道与冻结商户不一致")
+		}
+	} else if facts.PaymentConfigID == 0 || facts.PaymentConfigID != facts.RechargePaymentConfigID ||
 		facts.PaymentConfigID != facts.ConfirmedConfigID || identity == "" ||
 		identity != strings.TrimSpace(facts.ConfirmedMerchantIdentity) {
 		return false, errors.New(errors.CodeConflict, "支付配置身份与创建记录不一致")

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
+}

internal/gateway/client.go

@@ -99,8 +99,6 @@ func (c *Client) WithRetry(maxRetries int) *Client {
 // 流程：包装参数 → 序列化 → 加密 → 签名 → HTTP POST（带重试）→ 解析响应 → 检查业务状态码
 // params: 请求参数结构体，内部自动包装为 {"params": <JSON>} 格式
 func (c *Client) doRequest(ctx context.Context, path string, params interface{}) (json.RawMessage, error) {
-	startTime := time.Now()
-
 	// 将参数包装为 {"params": ...} 格式后序列化
 	wrapper := requestWrapper{Params: params}
 	dataBytes, err := sonic.Marshal(wrapper)
@@ -115,6 +113,28 @@ func (c *Client) doRequest(ctx context.Context, path string, params interface{})
 		return nil, err
 	}
 
+	return c.executeWithRetry(ctx, path, encryptedData, true)
+}
+
+// doRequestWithoutPayloadLog 执行 Gateway 请求，但不记录请求体与响应体。
+// 仅用于载荷含敏感内容（如付款凭证图片）的能力；成功与失败都只记录路径、耗时与结果摘要。
+func (c *Client) doRequestWithoutPayloadLog(ctx context.Context, path string, params interface{}) (json.RawMessage, error) {
+	dataBytes, err := sonic.Marshal(requestWrapper{Params: params})
+	if err != nil {
+		return nil, errors.Wrap(errors.CodeInternalError, err, "序列化业务数据失败")
+	}
+	encryptedData, err := aesEncrypt(dataBytes, c.appSecret)
+	if err != nil {
+		return nil, err
+	}
+	return c.executeWithRetry(ctx, path, encryptedData, false)
+}
+
+// executeWithRetry 按现有重试语义发送一次已加密请求。
+// logPayload 为 false 时不记录响应体，只记录路径、耗时与结果字节数摘要。
+func (c *Client) executeWithRetry(ctx context.Context, path, encryptedData string, logPayload bool) (json.RawMessage, error) {
+	startTime := time.Now()
+
 	// 带重试的 HTTP 请求
 	var lastErr error
 	observer, _ := ctx.Value(attemptObserverKey{}).(AttemptObserver)
@@ -160,11 +180,19 @@ func (c *Client) doRequest(ctx context.Context, path string, params interface{})
 
 		// 成功
 		duration := time.Since(startTime)
-		c.logger.Debug("Gateway 请求成功",
-			zap.String("path", path),
-			zap.Duration("duration", duration),
-			zap.Any("result", result),
-		)
+		if logPayload {
+			c.logger.Debug("Gateway 请求成功",
+				zap.String("path", path),
+				zap.Duration("duration", duration),
+				zap.Any("result", result),
+			)
+		} else {
+			c.logger.Debug("Gateway 请求成功",
+				zap.String("path", path),
+				zap.Duration("duration", duration),
+				zap.Int("result_bytes", len(result)),
+			)
+		}
 		return result, nil
 	}
 

internal/gateway/payment_voucher.go

@@ -0,0 +1,60 @@
+// Package gateway 提供付款凭证识别能力，仅用于交易流水号表单预填。
+// 识别结果不是资金事实，也不代表系统已完成任何资金动作。
+package gateway
+
+import (
+	"context"
+	"reflect"
+	"strings"
+
+	"github.com/bytedance/sonic"
+	"go.uber.org/zap"
+
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// paymentVoucherRecognitionPath 是付款凭证识别接口路径。
+const paymentVoucherRecognitionPath = "/ai/ocr/extract-payment"
+
+// PaymentVoucherExtractionRequest 是付款凭证识别请求，只传图片内容。
+type PaymentVoucherExtractionRequest struct {
+	// ImageBase64 是付款凭证图片的 base64 编码内容。
+	ImageBase64 string `json:"image_base64"`
+}
+
+// paymentVoucherExtraction 只解码本系统消费的支付单号。
+// 识别响应还含 amount（数值）、payee、payment_method、payment_time 与 remark，
+// 这些字段刻意不声明、不解码：既不进入响应、不预填、不落库，也不被本进程持有，
+// 同时避免上游字段类型漂移（实测 amount 为 JSON 数值）导致整条响应解析失败。
+type paymentVoucherExtraction struct {
+	OrderNumber string `json:"order_number"`
+}
+
+// ExtractPaymentVoucherOrderNumber 识别付款凭证图片并只返回识别出的支付单号。
+// 该能力刻意不使用记录完整请求体与响应体的泛型入口，日志只含路径、耗时与结果摘要；
+// 返回空字符串表示识别服务未给出支付单号，由调用方决定失败口径。
+func (c *Client) ExtractPaymentVoucherOrderNumber(ctx context.Context, imageBase64 string) (string, error) {
+	if strings.TrimSpace(imageBase64) == "" {
+		return "", errors.New(errors.CodeInvalidParam, "付款凭证图片内容不能为空")
+	}
+	data, err := c.doRequestWithoutPayloadLog(ctx, paymentVoucherRecognitionPath, PaymentVoucherExtractionRequest{
+		ImageBase64: imageBase64,
+	})
+	if err != nil {
+		return "", err
+	}
+	var extraction paymentVoucherExtraction
+	if err := sonic.Unmarshal(data, &extraction); err != nil {
+		// 刻意不记录 err.Error()：sonic 的类型错误消息会内嵌响应 JSON 原文片段，
+		// 一旦进入日志或错误上下文就等于记录识别原始结果（金额、单号等）。
+		// 只记录可诊断且非敏感的摘要：路径、响应字节数与错误类型名，
+		// 足以区分语法错、类型错与空响应，又不携带任何载荷内容。
+		c.logger.Warn("付款凭证识别响应解析失败",
+			zap.String("path", paymentVoucherRecognitionPath),
+			zap.Int("result_bytes", len(data)),
+			zap.String("err_kind", reflect.TypeOf(err).String()),
+		)
+		return "", errors.New(errors.CodeGatewayInvalidResp, "解析付款凭证识别结果失败")
+	}
+	return strings.TrimSpace(extraction.OrderNumber), nil
+}

internal/handler/admin/agent_recharge.go

@@ -4,12 +4,14 @@ import (
 	"bytes"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/bytedance/sonic"
 	"github.com/go-playground/validator/v10"
 	"github.com/gofiber/fiber/v2"
 
 	agentrechargeapp "github.com/break/junhong_cmp_fiber/internal/application/agentrecharge"
+	systemconfigapp "github.com/break/junhong_cmp_fiber/internal/application/systemconfig"
 	"github.com/break/junhong_cmp_fiber/internal/model/dto"
 	agentrechargequery "github.com/break/junhong_cmp_fiber/internal/query/agentrecharge"
 	agentRechargeSvc "github.com/break/junhong_cmp_fiber/internal/service/agent_recharge"
@@ -24,6 +26,8 @@ type AgentRechargeHandler struct {
 	service   *agentRechargeSvc.Service
 	online    *agentrechargeapp.OnlineCreationService
 	status    *agentrechargequery.PaymentStatusQuery
+	ocr       *agentrechargeapp.PaymentVoucherOCRService
+	config    *systemconfigapp.UpdateService
 	validator *validator.Validate
 }
 
@@ -37,6 +41,16 @@ func (h *AgentRechargeHandler) SetPaymentStatusQuery(query *agentrechargequery.P
 	h.status = query
 }
 
+// SetPaymentVoucherOCRService 注入付款凭证识别用例。
+func (h *AgentRechargeHandler) SetPaymentVoucherOCRService(service *agentrechargeapp.PaymentVoucherOCRService) {
+	h.ocr = service
+}
+
+// SetSystemConfigUpdateService 注入受控系统配置写服务，用于代理自充允许范围修改。
+func (h *AgentRechargeHandler) SetSystemConfigUpdateService(service *systemconfigapp.UpdateService) {
+	h.config = service
+}
+
 // NewAgentRechargeHandler 创建代理预充值 Handler
 func NewAgentRechargeHandler(service *agentRechargeSvc.Service, validator *validator.Validate) *AgentRechargeHandler {
 	return &AgentRechargeHandler{service: service, validator: validator}
@@ -73,8 +87,9 @@ func (h *AgentRechargeHandler) createOnline(c *fiber.Ctx, req dto.CreateAgentRec
 	if h.online == nil {
 		return errors.New(errors.CodeServiceUnavailable, "代理在线充值能力未配置")
 	}
-	if req.ShopID != nil || len(req.PaymentVoucherKey) > 0 || strings.TrimSpace(req.Remark) != "" {
-		return errors.New(errors.CodeInvalidParam, "在线充值不能指定店铺、支付凭证或运营备注")
+	if req.ShopID != nil || len(req.PaymentVoucherKey) > 0 || len(req.OtherVoucherKey) > 0 ||
+		req.OfflinePaymentMethodID != 0 || strings.TrimSpace(req.ExternalTransactionNo) != "" || strings.TrimSpace(req.Remark) != "" {
+		return errors.New(errors.CodeInvalidParam, "在线充值不能指定店铺、收款方式、交易流水号、支付凭证或运营备注")
 	}
 	result, err := h.online.Execute(c.UserContext(), agentrechargeapp.CreateOnlineCommand{
 		AccountID: middleware.GetUserIDFromContext(c.UserContext()), UserType: middleware.GetUserTypeFromContext(c.UserContext()),
@@ -108,6 +123,69 @@ func (h *AgentRechargeHandler) PaymentMethods(c *fiber.Ctx) error {
 	})
 }
 
+// SelfRechargePaymentMethods 查询代理自充实际可用支付方式。
+// GET /api/admin/agent-self-recharge-payment-methods
+// 响应只含交集结果，不含允许范围、商户身份或凭证。
+func (h *AgentRechargeHandler) SelfRechargePaymentMethods(c *fiber.Ctx) error {
+	return h.PaymentMethods(c)
+}
+
+// UpdateSelfRechargePaymentMethods 修改代理在线自充允许范围。
+// PUT /api/admin/agent-self-recharge-payment-methods
+// 复用受控系统配置写服务，获得超级管理员限定、咨询锁串行与前后值审计。
+func (h *AgentRechargeHandler) UpdateSelfRechargePaymentMethods(c *fiber.Ctx) error {
+	var req dto.AgentSelfRechargePaymentMethodsUpdateRequest
+	decoder := sonic.ConfigStd.NewDecoder(bytes.NewReader(c.Body()))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	if err := h.validator.Struct(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if h.config == nil {
+		return errors.New(errors.CodeServiceUnavailable, "代理自充允许范围维护能力未配置")
+	}
+	item, err := h.config.Execute(c.UserContext(), constants.SystemConfigAgentSelfRechargeAllowedMethods,
+		dto.UpdateSystemConfigRequest{Value: req.AllowedMethods})
+	if err != nil {
+		return err
+	}
+	updatedAt := ""
+	if item.UpdatedAt != nil {
+		updatedAt = item.UpdatedAt.UTC().Format(time.RFC3339)
+	}
+	return response.Success(c, &dto.AgentSelfRechargePaymentMethodsUpdateResponse{
+		AllowedMethods: item.Value, AllowedMethodsName: constants.GetAgentSelfRechargeAllowedMethodsName(item.Value),
+		UpdatedAt: updatedAt,
+	})
+}
+
+// PaymentVoucherOCR 识别付款凭证，只返回交易流水号预填值。
+// POST /api/admin/agent-recharges/payment-voucher-ocr
+// 识别失败返回明确失败，不影响提交人人工填写交易流水号后创建申请。
+func (h *AgentRechargeHandler) PaymentVoucherOCR(c *fiber.Ctx) error {
+	var req dto.AgentRechargePaymentVoucherOCRRequest
+	decoder := sonic.ConfigStd.NewDecoder(bytes.NewReader(c.Body()))
+	decoder.DisallowUnknownFields()
+	if err := decoder.Decode(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	if err := h.validator.Struct(&req); err != nil {
+		return errors.New(errors.CodeInvalidParam)
+	}
+	if h.ocr == nil {
+		return errors.New(errors.CodeServiceUnavailable, "付款凭证识别能力未配置")
+	}
+	result, err := h.ocr.Recognize(c.UserContext(), req.PaymentVoucherKey)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, &dto.AgentRechargePaymentVoucherOCRResponse{
+		ExternalTransactionNo: result.ExternalTransactionNo,
+	})
+}
+
 // List 查询代理充值订单列表
 // GET /api/admin/agent-recharges
 func (h *AgentRechargeHandler) List(c *fiber.Ctx) error {
@@ -143,6 +221,20 @@ func (h *AgentRechargeHandler) Get(c *fiber.Ctx) error {
 	return response.Success(c, result)
 }
 
+// TriggerApproval 主动补发历史线下代理充值审批。
+// POST /api/admin/agent-recharges/:id/trigger-approval
+func (h *AgentRechargeHandler) TriggerApproval(c *fiber.Ctx) error {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil || id == 0 {
+		return errors.New(errors.CodeInvalidParam, "无效的充值记录ID")
+	}
+	result, err := h.service.TriggerApproval(c.UserContext(), uint(id))
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
 // PaymentStatus 查询代理充值本地支付与到账状态。
 // GET /api/admin/agent-recharges/:id/payment-status
 func (h *AgentRechargeHandler) PaymentStatus(c *fiber.Ctx) error {

internal/handler/admin/employee_collection.go

@@ -0,0 +1,272 @@
+package admin
+
+import (
+	"strings"
+	"time"
+
+	"github.com/gofiber/fiber/v2"
+
+	employeecollectionapp "github.com/break/junhong_cmp_fiber/internal/application/employeecollection"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	employeecollectionquery "github.com/break/junhong_cmp_fiber/internal/query/employeecollection"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/response"
+)
+
+// EmployeeCollectionHandler 处理员工代收款账单、核销申请与线下收款方式字典请求。
+// 边界只做绑定、路径参数校验与统一响应，状态、金额与权限不变量由应用用例判断。
+type EmployeeCollectionHandler struct {
+	paymentMethod      *employeecollectionapp.PaymentMethodService
+	paymentMethodQuery *employeecollectionquery.PaymentMethodQuery
+	billClose          *employeecollectionapp.BillCloseService
+	billQuery          *employeecollectionquery.BillQuery
+	application        *employeecollectionapp.ApplicationService
+	applicationQuery   *employeecollectionquery.ApplicationQuery
+}
+
+// NewEmployeeCollectionHandler 创建员工代收款处理器。
+func NewEmployeeCollectionHandler(
+	service *employeecollectionapp.PaymentMethodService,
+	billClose *employeecollectionapp.BillCloseService,
+	application *employeecollectionapp.ApplicationService,
+) *EmployeeCollectionHandler {
+	return &EmployeeCollectionHandler{paymentMethod: service, billClose: billClose, application: application}
+}
+
+// SetApplicationQuery 注入核销申请只读投影。
+func (h *EmployeeCollectionHandler) SetApplicationQuery(query *employeecollectionquery.ApplicationQuery) {
+	h.applicationQuery = query
+}
+
+// SetPaymentMethodQuery 注入线下收款方式字典只读投影。
+func (h *EmployeeCollectionHandler) SetPaymentMethodQuery(query *employeecollectionquery.PaymentMethodQuery) {
+	h.paymentMethodQuery = query
+}
+
+// SetBillQuery 注入员工代收款账单只读投影。
+func (h *EmployeeCollectionHandler) SetBillQuery(query *employeecollectionquery.BillQuery) {
+	h.billQuery = query
+}
+
+// CreatePaymentMethod 创建线下收款方式。
+// POST /api/admin/employee-collection-payment-methods
+func (h *EmployeeCollectionHandler) CreatePaymentMethod(c *fiber.Ctx) error {
+	var request dto.CreateEmployeeCollectionPaymentMethodRequest
+	if err := c.BodyParser(&request); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	result, err := h.paymentMethod.Create(c.UserContext(), request)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// UpdatePaymentMethod 更新线下收款方式，支持修改名称、排序、启停、备注与未被引用时的稳定编码。
+// PUT /api/admin/employee-collection-payment-methods/:id
+func (h *EmployeeCollectionHandler) UpdatePaymentMethod(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	var request dto.UpdateEmployeeCollectionPaymentMethodRequest
+	if err := c.BodyParser(&request); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	result, err := h.paymentMethod.Update(c.UserContext(), id, request)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// DeletePaymentMethod 删除未被核销申请引用的线下收款方式。
+// DELETE /api/admin/employee-collection-payment-methods/:id
+func (h *EmployeeCollectionHandler) DeletePaymentMethod(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	if err := h.paymentMethod.Delete(c.UserContext(), id); err != nil {
+		return err
+	}
+	return response.Success(c, nil)
+}
+
+// ListPaymentMethods 分页查询线下收款方式。
+// GET /api/admin/employee-collection-payment-methods
+func (h *EmployeeCollectionHandler) ListPaymentMethods(c *fiber.Ctx) error {
+	var request dto.EmployeeCollectionPaymentMethodListRequest
+	if err := c.QueryParser(&request); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	result, err := h.paymentMethodQuery.List(c.UserContext(), request)
+	if err != nil {
+		return err
+	}
+	return response.SuccessWithPagination(c, result.List, result.Total, result.Page, result.PageSize)
+}
+
+// ListBills 分页查询员工代收款账单。
+// GET /api/admin/employee-collection-bills
+func (h *EmployeeCollectionHandler) ListBills(c *fiber.Ctx) error {
+	var request dto.EmployeeCollectionBillListRequest
+	if err := c.QueryParser(&request); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	result, err := h.billQuery.List(c.UserContext(), request)
+	if err != nil {
+		return err
+	}
+	return response.SuccessWithPagination(c, result.List, result.Total, result.Page, result.PageSize)
+}
+
+// StatisticsBills 汇总员工代收款账单金额与待处理数量。
+// GET /api/admin/employee-collection-bills/statistics
+func (h *EmployeeCollectionHandler) StatisticsBills(c *fiber.Ctx) error {
+	var request dto.EmployeeCollectionBillStatisticsRequest
+	if err := c.QueryParser(&request); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	result, err := h.billQuery.Statistics(c.UserContext(), request)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// GetBill 查询员工代收款账单详情。
+// GET /api/admin/employee-collection-bills/:id
+func (h *EmployeeCollectionHandler) GetBill(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	result, err := h.billQuery.Detail(c.UserContext(), id)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// CloseBill 关闭员工代收款账单，仅超级管理员可操作。
+// POST /api/admin/employee-collection-bills/:id/close
+func (h *EmployeeCollectionHandler) CloseBill(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	var request dto.CloseEmployeeCollectionBillRequest
+	if err := c.BodyParser(&request); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	bill, err := h.billClose.Close(c.UserContext(), id, request.Reason)
+	if err != nil {
+		return err
+	}
+	result, err := employeecollectionquery.ProjectBill(bill)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// CreateApplication 为本人可见账单创建核销申请。
+// POST /api/admin/employee-collection-applications
+func (h *EmployeeCollectionHandler) CreateApplication(c *fiber.Ctx) error {
+	request, err := bindApplicationRequest(c)
+	if err != nil {
+		return err
+	}
+	result, err := h.application.Create(c.UserContext(), request)
+	if err != nil {
+		return err
+	}
+	projected, err := employeecollectionquery.ProjectApplicationSubmit(employeecollectionquery.ApplicationSubmitProjection{
+		Application: result.Application, Attempt: result.Attempt, Allocations: result.Allocations,
+		Bills: result.Bills, InstanceID: result.InstanceID, InstanceStatus: result.InstanceStatus,
+	})
+	if err != nil {
+		return err
+	}
+	return response.Success(c, projected)
+}
+
+// ResubmitApplication 修改并重提已驳回的核销申请。
+// PUT /api/admin/employee-collection-applications/:id
+func (h *EmployeeCollectionHandler) ResubmitApplication(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	request, err := bindApplicationRequest(c)
+	if err != nil {
+		return err
+	}
+	result, err := h.application.Resubmit(c.UserContext(), id, request)
+	if err != nil {
+		return err
+	}
+	projected, err := employeecollectionquery.ProjectApplicationSubmit(employeecollectionquery.ApplicationSubmitProjection{
+		Application: result.Application, Attempt: result.Attempt, Allocations: result.Allocations,
+		Bills: result.Bills, InstanceID: result.InstanceID, InstanceStatus: result.InstanceStatus,
+	})
+	if err != nil {
+		return err
+	}
+	return response.Success(c, projected)
+}
+
+// ListApplications 分页查询核销申请。
+// GET /api/admin/employee-collection-applications
+func (h *EmployeeCollectionHandler) ListApplications(c *fiber.Ctx) error {
+	var request dto.EmployeeCollectionApplicationListRequest
+	if err := c.QueryParser(&request); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	result, err := h.applicationQuery.List(c.UserContext(), request)
+	if err != nil {
+		return err
+	}
+	return response.SuccessWithPagination(c, result.List, result.Total, result.Page, result.PageSize)
+}
+
+// GetApplication 查询核销申请详情，含分摊与全部审批尝试历史。
+// GET /api/admin/employee-collection-applications/:id
+func (h *EmployeeCollectionHandler) GetApplication(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	result, err := h.applicationQuery.Detail(c.UserContext(), id)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// bindApplicationRequest 绑定并转换创建或重提核销申请请求。
+// 付款时间按带时区的 RFC3339 解析；其余边界与业务校验由应用用例统一判断。
+func bindApplicationRequest(c *fiber.Ctx) (employeecollectionapp.SubmitApplicationCommand, error) {
+	var request dto.SubmitEmployeeCollectionApplicationRequest
+	if err := c.BodyParser(&request); err != nil {
+		return employeecollectionapp.SubmitApplicationCommand{}, errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	paidAt, err := time.Parse(time.RFC3339, strings.TrimSpace(request.PaidAt))
+	if err != nil {
+		return employeecollectionapp.SubmitApplicationCommand{}, errors.New(errors.CodeInvalidParam, "付款时间必须为带时区的 RFC3339 格式")
+	}
+	allocations := make([]employeecollectionapp.ApplicationAllocationCommand, 0, len(request.Allocations))
+	for _, item := range request.Allocations {
+		allocations = append(allocations, employeecollectionapp.ApplicationAllocationCommand{
+			BillID: item.BillID, Amount: item.Amount,
+		})
+	}
+	return employeecollectionapp.SubmitApplicationCommand{
+		PaymentMethodID: request.PaymentMethodID, PaidAmount: request.PaidAmount,
+		PayerName: request.PayerName, PaidAt: paidAt,
+		ExternalTransactionNo: request.ExternalTransactionNo,
+		PaymentVoucherKeys:    request.PaymentVoucherKeys, Remark: request.Remark,
+		ActingReason: request.ActingReason, Allocations: allocations,
+	}, nil
+}

internal/handler/admin/payment_merchant.go

@@ -0,0 +1,218 @@
+package admin
+
+import (
+	"strconv"
+
+	"github.com/gofiber/fiber/v2"
+
+	merchantpayment "github.com/break/junhong_cmp_fiber/internal/application/merchantpayment"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/response"
+)
+
+// PaymentMerchantHandler 处理特权商户与商户池配置请求。
+type PaymentMerchantHandler struct {
+	service *merchantpayment.ManagementService
+}
+
+// NewPaymentMerchantHandler 创建商户池管理处理器。
+func NewPaymentMerchantHandler(service *merchantpayment.ManagementService) *PaymentMerchantHandler {
+	return &PaymentMerchantHandler{service: service}
+}
+func pathID(c *fiber.Ctx) (uint, error) {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil || id == 0 {
+		return 0, errors.New(errors.CodeInvalidParam, "无效的路径ID")
+	}
+	return uint(id), nil
+}
+
+// CreateMerchant 创建支付商户。
+// POST /api/admin/payment-merchants
+func (h *PaymentMerchantHandler) CreateMerchant(c *fiber.Ctx) error {
+	var r dto.PaymentMerchantRequest
+	if err := c.BodyParser(&r); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	v, err := h.service.CreateMerchant(c.UserContext(), r)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, v)
+}
+
+// ListMerchants 分页查询支付商户。
+// GET /api/admin/payment-merchants
+func (h *PaymentMerchantHandler) ListMerchants(c *fiber.Ctx) error {
+	var r dto.PaymentMerchantListRequest
+	if err := c.QueryParser(&r); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	v, n, err := h.service.ListMerchants(c.UserContext(), r)
+	if err != nil {
+		return err
+	}
+	return response.SuccessWithPagination(c, v, n, r.Page, r.PageSize)
+}
+
+// GetMerchant 查询支付商户详情。
+// GET /api/admin/payment-merchants/:id
+func (h *PaymentMerchantHandler) GetMerchant(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	v, err := h.service.GetMerchant(c.UserContext(), id)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, v)
+}
+
+// UpdateMerchant 更新支付商户。
+// PUT /api/admin/payment-merchants/:id
+func (h *PaymentMerchantHandler) UpdateMerchant(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	var r dto.PaymentMerchantUpdateRequest
+	if err := c.BodyParser(&r); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	v, err := h.service.UpdateMerchant(c.UserContext(), id, r)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, v)
+}
+
+// DeleteMerchant 删除支付商户。
+// DELETE /api/admin/payment-merchants/:id
+func (h *PaymentMerchantHandler) DeleteMerchant(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	var r dto.PaymentMerchantDeleteRequest
+	if err := c.BodyParser(&r); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	if err := h.service.DeleteMerchant(c.UserContext(), id, r.Confirm); err != nil {
+		return err
+	}
+	return response.Success(c, nil)
+}
+
+// CreatePool 创建商户池。
+// POST /api/admin/payment-merchant-pools
+func (h *PaymentMerchantHandler) CreatePool(c *fiber.Ctx) error {
+	var r dto.PaymentMerchantPoolRequest
+	if err := c.BodyParser(&r); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	v, err := h.service.SavePool(c.UserContext(), 0, r)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, v)
+}
+
+// UpdatePool 更新商户池。
+// PUT /api/admin/payment-merchant-pools/:id
+func (h *PaymentMerchantHandler) UpdatePool(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	var r dto.PaymentMerchantPoolRequest
+	if err := c.BodyParser(&r); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	v, err := h.service.SavePool(c.UserContext(), id, r)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, v)
+}
+
+// EnablePool 启用商户池。
+// POST /api/admin/payment-merchant-pools/:id/enable
+func (h *PaymentMerchantHandler) EnablePool(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	result, err := h.service.SetPoolEnabled(c.UserContext(), id, true)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// DisablePool 停用商户池。
+// POST /api/admin/payment-merchant-pools/:id/disable
+func (h *PaymentMerchantHandler) DisablePool(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	result, err := h.service.SetPoolEnabled(c.UserContext(), id, false)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
+// GetAuthorization 获取微信授权配置。
+// GET /api/admin/wechat-authorizations
+func (h *PaymentMerchantHandler) GetAuthorization(c *fiber.Ctx) error {
+	v, err := h.service.GetAuthorization(c.UserContext())
+	if err != nil {
+		return err
+	}
+	return response.Success(c, v)
+}
+
+// ListPools 分页查询商户池。
+// GET /api/admin/payment-merchant-pools
+func (h *PaymentMerchantHandler) ListPools(c *fiber.Ctx) error {
+	var r dto.PaymentMerchantPoolListRequest
+	if err := c.QueryParser(&r); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	v, total, err := h.service.ListPools(c.UserContext(), r)
+	if err != nil {
+		return err
+	}
+	return response.SuccessWithPagination(c, v, total, r.Page, r.PageSize)
+}
+
+// GetPool 查询商户池详情。
+// GET /api/admin/payment-merchant-pools/:id
+func (h *PaymentMerchantHandler) GetPool(c *fiber.Ctx) error {
+	id, err := pathID(c)
+	if err != nil {
+		return err
+	}
+	v, err := h.service.GetPool(c.UserContext(), id)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, v)
+}
+
+// SaveAuthorization 保存微信授权配置。
+// PUT /api/admin/wechat-authorizations/current
+func (h *PaymentMerchantHandler) SaveAuthorization(c *fiber.Ctx) error {
+	var r dto.WechatAuthorizationRequest
+	if err := c.BodyParser(&r); err != nil {
+		return errors.New(errors.CodeInvalidParam, "请求参数解析失败")
+	}
+	v, err := h.service.SaveAuthorization(c.UserContext(), r)
+	if err != nil {
+		return err
+	}
+	return response.Success(c, v)
+}

internal/handler/admin/refund.go

@@ -69,6 +69,20 @@ func (h *RefundHandler) GetByID(c *fiber.Ctx) error {
 	return response.Success(c, result)
 }
 
+// TriggerApproval 主动补发历史退款审批
+// POST /api/admin/refunds/:id/trigger-approval
+func (h *RefundHandler) TriggerApproval(c *fiber.Ctx) error {
+	id, err := strconv.ParseUint(c.Params("id"), 10, 64)
+	if err != nil || id == 0 {
+		return errors.New(errors.CodeInvalidParam, "无效的退款申请ID")
+	}
+	result, err := h.service.TriggerApproval(c.UserContext(), uint(id))
+	if err != nil {
+		return err
+	}
+	return response.Success(c, result)
+}
+
 // Approve 审批通过退款申请
 // POST /api/admin/refunds/:id/approve
 func (h *RefundHandler) Approve(c *fiber.Ctx) error {

internal/handler/app/client_asset.go

@@ -11,6 +11,7 @@ import (
 	"github.com/break/junhong_cmp_fiber/internal/middleware"
 	"github.com/break/junhong_cmp_fiber/internal/model"
 	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	assetquery "github.com/break/junhong_cmp_fiber/internal/query/asset"
 	asset "github.com/break/junhong_cmp_fiber/internal/service/asset"
 	customerBinding "github.com/break/junhong_cmp_fiber/internal/service/customer_binding"
 	packagepkg "github.com/break/junhong_cmp_fiber/internal/service/package"
@@ -462,7 +463,7 @@ func (h *ClientAssetHandler) GetAvailablePackages(c *fiber.Ctx) error {
 	return response.Success(c, &dto.AssetPackageListResponse{Packages: items})
 }
 
-// GetPackageHistory B3 资产套餐历史
+// GetPackageHistory B3 资产套餐历史。
 // GET /api/c/v1/asset/package-history
 func (h *ClientAssetHandler) GetPackageHistory(c *fiber.Ctx) error {
 	var req dto.AssetPackageHistoryRequest
@@ -485,73 +486,93 @@ func (h *ClientAssetHandler) GetPackageHistory(c *fiber.Ctx) error {
 		return err
 	}
 
-	query := h.db.WithContext(resolved.SkipPermissionCtx).Model(&model.PackageUsage{}).
-		Where("generation = ?", resolved.Generation)
-	if resolved.Asset.AssetType == "card" {
-		query = query.Where("iot_card_id = ?", resolved.Asset.AssetID)
-	} else {
-		query = query.Where("device_id = ?", resolved.Asset.AssetID)
-	}
-	if req.Status != nil {
-		query = query.Where("status = ?", *req.Status)
-	}
-	if req.PackageType != nil {
-		query = query.Where("package_id IN (?)",
-			h.db.Model(&model.Package{}).Select("id").Where("package_type = ?", *req.PackageType))
-	}
-
-	var total int64
-	if err := query.Count(&total).Error; err != nil {
-		return errors.Wrap(errors.CodeDatabaseError, err, "查询套餐历史总数失败")
-	}
-
-	var usages []*model.PackageUsage
-	offset := (req.Page - 1) * req.PageSize
-	if err := query.Order("created_at DESC").Offset(offset).Limit(req.PageSize).Find(&usages).Error; err != nil {
-		return errors.Wrap(errors.CodeDatabaseError, err, "查询套餐历史失败")
-	}
-
-	packageMap, err := h.loadPackageMap(resolved.SkipPermissionCtx, usages)
+	history, err := assetquery.NewPackageHistoryQuery(h.db).List(resolved.SkipPermissionCtx, assetquery.PackageHistoryInput{
+		AssetType:   resolved.Asset.AssetType,
+		AssetID:     resolved.Asset.AssetID,
+		Generation:  &resolved.Generation,
+		Status:      req.Status,
+		PackageType: req.PackageType,
+		Page:        req.Page,
+		PageSize:    req.PageSize,
+	})
 	if err != nil {
 		return err
 	}
 
-	list := make([]dto.AssetPackageResponse, 0, len(usages))
-	for _, usage := range usages {
-		pkg := packageMap[usage.PackageID]
-		metrics := usage.BuildTrafficMetrics()
-		pkgName := usage.PackageName
-		pkgType := ""
-		if pkg != nil {
-			if pkgName == "" {
-				pkgName = pkg.PackageName
-			}
-			pkgType = pkg.PackageType
-		}
-
-		list = append(list, dto.AssetPackageResponse{
-			PackageUsageID:    usage.ID,
-			PackageID:         usage.PackageID,
-			PackageName:       pkgName,
-			PackageType:       pkgType,
-			UsageType:         usage.UsageType,
-			Status:            usage.Status,
-			StatusName:        packageStatusName(usage.Status),
-			RealTotalMB:       metrics.RealTotalMB,
-			RealUsedMB:        metrics.RealUsedMB,
-			VirtualTotalMB:    metrics.VirtualTotalMB,
-			VirtualUsedMB:     metrics.VirtualUsedMB,
-			ReductionPct:      metrics.ReductionPct,
-			EnableVirtualData: usage.EnableVirtualDataSnapshot,
-			ActivatedAt:       usage.ActivatedAt,
-			ExpiresAt:         usage.ExpiresAt,
-			MasterUsageID:     usage.MasterUsageID,
-			Priority:          usage.Priority,
-			CreatedAt:         usage.CreatedAt,
-		})
+	packageMap, err := h.loadPackageMap(resolved.SkipPermissionCtx, collectPackageHistoryUsages(history.Items))
+	if err != nil {
+		return err
 	}
 
-	return response.SuccessWithPagination(c, list, total, req.Page, req.PageSize)
+	items := make([]*dto.ClientAssetPackageHistoryNode, 0, len(history.Items))
+	for _, node := range history.Items {
+		items = append(items, buildClientPackageHistoryNode(node, packageMap))
+	}
+
+	return response.SuccessWithPagination(c, items, history.Total, req.Page, req.PageSize)
+}
+
+func collectPackageHistoryUsages(items []*assetquery.PackageHistoryNode) []*model.PackageUsage {
+	usages := make([]*model.PackageUsage, 0)
+	var collect func(*assetquery.PackageHistoryNode)
+	collect = func(node *assetquery.PackageHistoryNode) {
+		if node == nil || node.Usage == nil {
+			return
+		}
+		usages = append(usages, node.Usage)
+		for _, child := range node.Children {
+			collect(child)
+		}
+	}
+	for _, item := range items {
+		collect(item)
+	}
+	return usages
+}
+
+func buildClientPackageHistoryNode(node *assetquery.PackageHistoryNode, packageMap map[uint]*model.Package) *dto.ClientAssetPackageHistoryNode {
+	usage := node.Usage
+	pkg := packageMap[usage.PackageID]
+	metrics := usage.BuildTrafficMetrics()
+	packageName := usage.PackageName
+	packageType := ""
+	if pkg != nil {
+		if packageName == "" {
+			packageName = pkg.PackageName
+		}
+		packageType = pkg.PackageType
+	}
+
+	item := &dto.ClientAssetPackageHistoryNode{
+		PackageUsageID:    usage.ID,
+		PackageID:         usage.PackageID,
+		PackageName:       packageName,
+		PackageType:       packageType,
+		UsageType:         usage.UsageType,
+		Status:            usage.Status,
+		StatusName:        packageStatusName(usage.Status),
+		RealTotalMB:       metrics.RealTotalMB,
+		RealUsedMB:        metrics.RealUsedMB,
+		VirtualTotalMB:    metrics.VirtualTotalMB,
+		VirtualUsedMB:     metrics.VirtualUsedMB,
+		ReductionPct:      metrics.ReductionPct,
+		EnableVirtualData: usage.EnableVirtualDataSnapshot,
+		ActivatedAt:       usage.ActivatedAt,
+		ExpiresAt:         usage.ExpiresAt,
+		MasterUsageID:     usage.MasterUsageID,
+		Priority:          usage.Priority,
+		CreatedAt:         usage.CreatedAt,
+		Children:          make([]*dto.ClientAssetPackageHistoryNode, 0, len(node.Children)),
+	}
+	if node.RelationshipStatus != "" {
+		item.RelationshipStatus = node.RelationshipStatus
+		item.RelationshipStatusName = "关联主套餐缺失"
+	}
+	for _, child := range node.Children {
+		item.Children = append(item.Children, buildClientPackageHistoryNode(child, packageMap))
+	}
+	item.ExpandByDefault = len(item.Children) > 0
+	return item
 }
 
 // RefreshAsset B4 资产刷新

internal/handler/app/client_wallet.go

@@ -8,6 +8,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/break/junhong_cmp_fiber/internal/application/merchantpayment"
 	"github.com/break/junhong_cmp_fiber/internal/infrastructure/audit"
 	"github.com/break/junhong_cmp_fiber/internal/infrastructure/integrationlog"
 	"github.com/break/junhong_cmp_fiber/internal/middleware"
@@ -16,7 +17,7 @@ import (
 	asset "github.com/break/junhong_cmp_fiber/internal/service/asset"
 	customerBinding "github.com/break/junhong_cmp_fiber/internal/service/customer_binding"
 	rechargeSvc "github.com/break/junhong_cmp_fiber/internal/service/recharge"
-	wechatConfigSvc "github.com/break/junhong_cmp_fiber/internal/service/wechat_config"
+
 	"github.com/break/junhong_cmp_fiber/internal/store/postgres"
 	"github.com/break/junhong_cmp_fiber/pkg/alipay"
 	"github.com/break/junhong_cmp_fiber/pkg/constants"
@@ -41,7 +42,7 @@ type ClientWalletHandler struct {
 	paymentStore        *postgres.PaymentStore
 	rechargeService     *rechargeSvc.Service
 	openIDStore         *postgres.PersonalCustomerOpenIDStore
-	wechatConfigService *wechatConfigSvc.Service
+	merchantRuntime     *merchantpayment.RuntimeLoader
 	redis               *redis.Client
 	logger              *zap.Logger
 	db                  *gorm.DB
@@ -73,7 +74,6 @@ func NewClientWalletHandler(
 	paymentStore *postgres.PaymentStore,
 	rechargeService *rechargeSvc.Service,
 	openIDStore *postgres.PersonalCustomerOpenIDStore,
-	wechatConfigService *wechatConfigSvc.Service,
 	redisClient *redis.Client,
 	logger *zap.Logger,
 	db *gorm.DB,
@@ -81,20 +81,20 @@ func NewClientWalletHandler(
 	deviceStore *postgres.DeviceStore,
 ) *ClientWalletHandler {
 	return &ClientWalletHandler{
-		assetService:        assetService,
-		customerBinding:     binding,
-		walletStore:         walletStore,
-		transactionStore:    transactionStore,
-		rechargeOrderStore:  rechargeOrderStore,
-		paymentStore:        paymentStore,
-		rechargeService:     rechargeService,
-		openIDStore:         openIDStore,
-		wechatConfigService: wechatConfigService,
-		redis:               redisClient,
-		logger:              logger,
-		db:                  db,
-		iotCardStore:        iotCardStore,
-		deviceStore:         deviceStore,
+		assetService:       assetService,
+		customerBinding:    binding,
+		walletStore:        walletStore,
+		transactionStore:   transactionStore,
+		rechargeOrderStore: rechargeOrderStore,
+		paymentStore:       paymentStore,
+		rechargeService:    rechargeService,
+		openIDStore:        openIDStore,
+		merchantRuntime:    merchantpayment.NewRuntimeLoader(db, redisClient),
+		redis:              redisClient,
+		logger:             logger,
+		db:                 db,
+		iotCardStore:       iotCardStore,
+		deviceStore:        deviceStore,
 	}
 }
 
@@ -321,19 +321,11 @@ func (h *ClientWalletHandler) CreateRecharge(c *fiber.Ctx) error {
 	// 	}
 	// }
 
-	config, err := h.wechatConfigService.GetActiveConfig(resolved.SkipPermissionCtx)
-	if err != nil {
-		return err
-	}
-	if config == nil {
-		return errors.New(errors.CodeWechatConfigUnavailable)
-	}
-
 	switch req.PaymentMethod {
 	case constants.RechargeMethodAlipay:
-		return h.createAlipayRecharge(c, resolved, config, wallet, req)
+		return h.createAlipayRecharge(c, resolved, wallet, req)
 	case constants.RechargeMethodWechat:
-		return h.createWechatRecharge(c, resolved, config, wallet, req)
+		return h.createWechatRecharge(c, resolved, wallet, req)
 	default:
 		return errors.New(errors.CodePaymentMethodUnavailable)
 	}
@@ -343,15 +335,13 @@ func (h *ClientWalletHandler) CreateRecharge(c *fiber.Ctx) error {
 func (h *ClientWalletHandler) createWechatRecharge(
 	c *fiber.Ctx,
 	resolved *resolvedWalletAssetContext,
-	config *model.WechatConfig,
 	wallet *model.AssetWallet,
 	req dto.ClientCreateRechargeRequest,
 ) error {
-	appID, err := pickAppIDByType(config, req.AppType)
+	authorization, appID, err := h.loadWechatAuthorization(resolved.SkipPermissionCtx, req.AppType)
 	if err != nil {
 		return err
 	}
-
 	openID, err := h.findOpenIDByCustomerAndAppID(resolved.SkipPermissionCtx, resolved.CustomerID, appID)
 	if err != nil {
 		return err
@@ -359,9 +349,47 @@ func (h *ClientWalletHandler) createWechatRecharge(
 
 	rechargeNo := generateClientRechargeNo()
 	paymentNo := generateClientPaymentNo()
+	rechargeOrder := &model.RechargeOrder{
+		RechargeOrderNo: rechargeNo,
+		UserID:          resolved.CustomerID,
+		AssetWalletID:   wallet.ID,
+		ResourceType:    resolved.ResourceType,
+		ResourceID:      resolved.Asset.AssetID,
+		Amount:          req.Amount,
+		Status:          model.RechargeOrderStatusPending,
+		ShopIDTag:       wallet.ShopIDTag,
+		EnterpriseIDTag: wallet.EnterpriseIDTag,
+		OperatorType:    constants.OperatorTypePersonalCustomer,
+		Generation:      resolved.Generation,
+	}
+	payment := &model.Payment{
+		PaymentNo:     paymentNo,
+		OrderID:       rechargeOrder.ID,
+		OrderType:     model.PaymentOrderTypeRecharge,
+		PaymentMethod: model.PaymentByWechat,
+		Amount:        req.Amount,
+		Status:        model.PaymentRecordStatusPending,
+	}
+	var config *model.WechatConfig
+	if err := h.db.WithContext(resolved.SkipPermissionCtx).Transaction(func(tx *gorm.DB) error {
+		route, selectedConfig, err := h.selectMerchantConfig(resolved.SkipPermissionCtx, tx, model.PaymentByWechat, authorization)
+		if err != nil {
+			return err
+		}
+		config = selectedConfig
+		merchantpayment.FreezeRoute(payment, route)
+		if err := h.rechargeOrderStore.CreateWithTx(resolved.SkipPermissionCtx, tx, rechargeOrder); err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "创建充值订单失败")
+		}
+		payment.OrderID = rechargeOrder.ID
+		if err := h.paymentStore.CreateWithTx(resolved.SkipPermissionCtx, tx, payment); err != nil {
+			return errors.Wrap(errors.CodeDatabaseError, err, "创建支付记录失败")
+		}
+		return h.appendRechargePaymentCreatedAudit(resolved.SkipPermissionCtx, tx, payment, rechargeOrder)
+	}); err != nil {
+		return err
+	}
 
-	// 先初始化生效支付通道并创建预支付订单，确认支付通道可用
-	// 避免先写入充值记录后支付初始化失败，导致产生孤儿记录
 	attempt, startedAt, err := h.startRechargePaymentAttempt(resolved.SkipPermissionCtx, config, paymentNo, rechargeNo, req.Amount)
 	if err != nil {
 		return err
@@ -380,49 +408,15 @@ func (h *ClientWalletHandler) createWechatRecharge(
 		if completeErr := h.completeRechargePaymentAttempt(resolved.SkipPermissionCtx, attempt, startedAt, constants.IntegrationResultUnknown, "request_unknown", "充值支付预下单结果未知"); completeErr != nil {
 			return completeErr
 		}
+		if updateErr := h.markRechargePaymentFailed(resolved.SkipPermissionCtx, payment); updateErr != nil {
+			return updateErr
+		}
 		return err
 	}
 	if err := h.completeRechargePaymentAttempt(resolved.SkipPermissionCtx, attempt, startedAt, constants.IntegrationResultSuccess, "SUCCESS", ""); err != nil {
 		return err
 	}
 
-	// 支付通道确认可用后，再创建充值订单和支付记录
-	rechargeOrder := &model.RechargeOrder{
-		RechargeOrderNo: rechargeNo,
-		UserID:          resolved.CustomerID,
-		AssetWalletID:   wallet.ID,
-		ResourceType:    resolved.ResourceType,
-		ResourceID:      resolved.Asset.AssetID,
-		Amount:          req.Amount,
-		Status:          model.RechargeOrderStatusPending,
-		PaymentConfigID: &config.ID,
-		ShopIDTag:       wallet.ShopIDTag,
-		EnterpriseIDTag: wallet.EnterpriseIDTag,
-		OperatorType:    constants.OperatorTypePersonalCustomer,
-		Generation:      resolved.Generation,
-	}
-	payment := &model.Payment{
-		PaymentNo:       paymentNo,
-		OrderID:         rechargeOrder.ID,
-		OrderType:       model.PaymentOrderTypeRecharge,
-		PaymentMethod:   model.PaymentByWechat,
-		Amount:          req.Amount,
-		Status:          model.PaymentRecordStatusPending,
-		PaymentConfigID: &config.ID,
-	}
-	if err := h.db.WithContext(resolved.SkipPermissionCtx).Transaction(func(tx *gorm.DB) error {
-		if err := h.rechargeOrderStore.CreateWithTx(resolved.SkipPermissionCtx, tx, rechargeOrder); err != nil {
-			return errors.Wrap(errors.CodeDatabaseError, err, "创建充值订单失败")
-		}
-		payment.OrderID = rechargeOrder.ID
-		if err := h.paymentStore.CreateWithTx(resolved.SkipPermissionCtx, tx, payment); err != nil {
-			return errors.Wrap(errors.CodeDatabaseError, err, "创建支付记录失败")
-		}
-		return h.appendRechargePaymentCreatedAudit(resolved.SkipPermissionCtx, tx, payment, rechargeOrder)
-	}); err != nil {
-		return err
-	}
-
 	return response.Success(c, &dto.ClientRechargeResponse{
 		Recharge: dto.ClientRechargeResult{
 			RechargeID: rechargeOrder.ID,
@@ -439,18 +433,11 @@ func (h *ClientWalletHandler) createWechatRecharge(
 func (h *ClientWalletHandler) createAlipayRecharge(
 	c *fiber.Ctx,
 	resolved *resolvedWalletAssetContext,
-	config *model.WechatConfig,
 	wallet *model.AssetWallet,
 	req dto.ClientCreateRechargeRequest,
 ) error {
 	rechargeNo := generateClientRechargeNo()
 	paymentNo := generateClientPaymentNo()
-	expireMinutes := config.AliPayExpireMinutes
-	if expireMinutes <= 0 {
-		expireMinutes = 30
-	}
-	expireAt := time.Now().Add(time.Duration(expireMinutes) * time.Minute)
-
 	rechargeOrder := &model.RechargeOrder{
 		RechargeOrderNo: rechargeNo,
 		UserID:          resolved.CustomerID,
@@ -459,24 +446,33 @@ func (h *ClientWalletHandler) createAlipayRecharge(
 		ResourceID:      resolved.Asset.AssetID,
 		Amount:          req.Amount,
 		Status:          model.RechargeOrderStatusPending,
-		PaymentConfigID: &config.ID,
 		ShopIDTag:       wallet.ShopIDTag,
 		EnterpriseIDTag: wallet.EnterpriseIDTag,
 		OperatorType:    constants.OperatorTypePersonalCustomer,
 		Generation:      resolved.Generation,
 	}
 	payment := &model.Payment{
-		PaymentNo:       paymentNo,
-		OrderType:       model.PaymentOrderTypeRecharge,
-		PaymentMethod:   model.PaymentByAlipay,
-		Amount:          req.Amount,
-		Status:          model.PaymentRecordStatusPending,
-		PaymentConfigID: &config.ID,
-		ExpireAt:        &expireAt,
+		PaymentNo:     paymentNo,
+		OrderType:     model.PaymentOrderTypeRecharge,
+		PaymentMethod: model.PaymentByAlipay,
+		Amount:        req.Amount,
+		Status:        model.PaymentRecordStatusPending,
 	}
-
-	// WAP URL 是本地签名，不需要先调第三方，在事务内创建充值单和支付单
+	var config *model.WechatConfig
+	var expireAt time.Time
 	if err := h.db.WithContext(resolved.SkipPermissionCtx).Transaction(func(tx *gorm.DB) error {
+		route, selectedConfig, err := h.selectMerchantConfig(resolved.SkipPermissionCtx, tx, model.PaymentByAlipay, nil)
+		if err != nil {
+			return err
+		}
+		expireMinutes := selectedConfig.AliPayExpireMinutes
+		if expireMinutes <= 0 {
+			expireMinutes = 30
+		}
+		expireAt = time.Now().Add(time.Duration(expireMinutes) * time.Minute)
+		config = selectedConfig
+		payment.ExpireAt = &expireAt
+		merchantpayment.FreezeRoute(payment, route)
 		if err := h.rechargeOrderStore.CreateWithTx(resolved.SkipPermissionCtx, tx, rechargeOrder); err != nil {
 			return errors.Wrap(errors.CodeDatabaseError, err, "创建充值订单失败")
 		}
@@ -505,7 +501,6 @@ func (h *ClientWalletHandler) createAlipayRecharge(
 		zap.String("recharge_no", rechargeNo),
 		zap.Int64("amount", req.Amount),
 		zap.Time("expire_at", expireAt),
-		zap.Uint("config_id", config.ID),
 	)
 
 	expireStr := expireAt.Format(time.RFC3339)
@@ -738,7 +733,37 @@ func parseOptionalTime(value string) (*time.Time, error) {
 	return nil, fmt.Errorf("invalid time format")
 }
 
-func pickAppIDByType(config *model.WechatConfig, appType string) (string, error) {
+func (h *ClientWalletHandler) loadWechatAuthorization(ctx context.Context, appType string) (*model.WechatAuthorization, string, error) {
+	if h.merchantRuntime == nil {
+		return nil, "", errors.New(errors.CodeServiceUnavailable, "商户池路由能力未配置")
+	}
+	authorization, err := h.merchantRuntime.LoadAuthorization(ctx)
+	if err != nil {
+		return nil, "", err
+	}
+	appID, err := pickAppIDByType(authorization, appType)
+	if err != nil {
+		return nil, "", err
+	}
+	return authorization, appID, nil
+}
+
+func (h *ClientWalletHandler) selectMerchantConfig(ctx context.Context, tx *gorm.DB, paymentMethod string, authorization *model.WechatAuthorization) (*merchantpayment.RouteSelection, *model.WechatConfig, error) {
+	if h.merchantRuntime == nil {
+		return nil, nil, errors.New(errors.CodeServiceUnavailable, "商户池路由能力未配置")
+	}
+	route, err := h.merchantRuntime.SelectForNewPaymentWithTx(ctx, tx, paymentMethod, time.Now())
+	if err != nil {
+		return nil, nil, err
+	}
+	config, err := merchantpayment.MerchantConfig(route.Merchant, authorization)
+	if err != nil {
+		return nil, nil, err
+	}
+	return route, config, nil
+}
+
+func pickAppIDByType(config *model.WechatAuthorization, appType string) (string, error) {
 	switch appType {
 	case "official_account":
 		if strings.TrimSpace(config.OaAppID) == "" {

internal/handler/app/client_wechat.go

@@ -54,7 +54,7 @@ func (h *ClientWechatHandler) GetJSSDKConfig(c *fiber.Ctx) error {
 		return errors.New(errors.CodeInvalidParam)
 	}
 
-	wechatConfig, err := h.wechatConfigService.GetActiveConfig(c.UserContext())
+	wechatConfig, err := h.wechatConfigService.GetAuthorizationConfig(c.UserContext())
 	if err != nil {
 		return err
 	}
@@ -82,7 +82,7 @@ func (h *ClientWechatHandler) GetJSSDKConfig(c *fiber.Ctx) error {
 // GetAppID 获取当前生效的公众号 AppID
 // GET /api/c/v1/wechat/appid
 func (h *ClientWechatHandler) GetAppID(c *fiber.Ctx) error {
-	wechatConfig, err := h.wechatConfigService.GetActiveConfig(c.UserContext())
+	wechatConfig, err := h.wechatConfigService.GetAuthorizationConfig(c.UserContext())
 	if err != nil {
 		return err
 	}

internal/handler/callback/payment.go

@@ -38,6 +38,7 @@ type AgentRechargeServiceInterface interface {
 type WechatConfigServiceInterface interface {
 	GetActiveConfig(ctx context.Context) (*model.WechatConfig, error)
 	GetConfigForCallback(ctx context.Context, orderNo string) (*model.WechatConfig, error)
+	GetPaymentServiceForCallback(config *model.WechatConfig) (wechat.PaymentServiceInterface, error)
 }
 
 type PaymentHandler struct {
@@ -98,7 +99,7 @@ func (h *PaymentHandler) WechatPayCallback(c *fiber.Ctx) error {
 	body := c.Body()
 	ctx := c.UserContext()
 
-	// 预解析订单号（不验签），用于按 payment_config_id 加载创建订单时所用的配置
+	// 预解析订单号（不验签），用于按支付单冻结商户或历史 payment_config_id 双读加载配置
 	orderNo, err := wechat.PeekOrderNo(body)
 	if err != nil {
 		h.logger.Error("微信回调：预解析订单号失败", zap.Error(err))
@@ -144,12 +145,13 @@ func (h *PaymentHandler) WechatPayCallback(c *fiber.Ctx) error {
 		}
 
 	case model.ProviderTypeWechat:
-		if h.wechatPayment == nil {
-			return errors.New(errors.CodeWechatCallbackInvalid, "微信 v3 支付未初始化")
+		paymentSvc, err := h.wechatConfigService.GetPaymentServiceForCallback(cfg)
+		if err != nil {
+			return errors.Wrap(errors.CodeWechatCallbackInvalid, err, "构建微信 v3 回调验签实例失败")
 		}
 		var httpReq http.Request
 		fasthttpadaptor.ConvertRequest(c.Context(), &httpReq, true)
-		_, err := h.wechatPayment.HandlePaymentNotify(&httpReq, func(result *wechat.PaymentNotifyResult) error {
+		_, err = paymentSvc.HandlePaymentNotify(&httpReq, func(result *wechat.PaymentNotifyResult) error {
 			if result.TradeState != "SUCCESS" {
 				return h.recordIgnoredPaymentCallback(ctx, verifiedPaymentCallback{
 					PaymentNo: result.OutTradeNo, TransactionID: result.TransactionID,
@@ -283,8 +285,13 @@ func (h *PaymentHandler) confirmAgentRechargePayment(ctx context.Context, callba
 	correlationID := callback.PaymentNo
 	ctx = auditcontext.With(ctx, auditcontext.Context{CorrelationID: correlationID})
 	linkage := auditcontext.From(ctx)
+	// 富友本质是微信支付上游通道，回调渠道归一化为业务方式 wechat 后再进入确认用例。
+	paymentMethod := callback.PaymentMethod
+	if paymentMethod == model.ProviderTypeFuiou {
+		paymentMethod = constants.RechargeMethodWechat
+	}
 	result, confirmErr := h.agentPaymentConfirm.Execute(ctx, agentrechargeApp.ConfirmOnlinePaymentCommand{
-		PaymentNo: callback.PaymentNo, PaymentMethod: callback.PaymentMethod, ConfigID: callback.ConfigID,
+		PaymentNo: callback.PaymentNo, PaymentMethod: paymentMethod, ConfigID: callback.ConfigID,
 		MerchantIdentity: callback.MerchantIdentity, ThirdPartyTradeNo: callback.TransactionID,
 		Amount: callback.Amount, PaidAt: callback.PaidAt, RequestID: linkage.RequestID,
 		CorrelationID: correlationID, ParentEventID: linkage.ParentEventID,
@@ -416,7 +423,7 @@ func (h *PaymentHandler) AlipayCallback(c *fiber.Ctx) error {
 		return errors.New(errors.CodeInvalidParam, "订单号不能为空")
 	}
 
-	// 按 payment_config_id 加载创建支付单时所用的配置（支持已停用配置）
+	// 按支付单冻结商户或历史 payment_config_id 双读加载配置（支持已停用配置）
 	cfg, err := h.wechatConfigService.GetConfigForCallback(ctx, outTradeNo)
 	if err != nil || cfg == nil {
 		h.logger.Error("支付宝回调：加载支付配置失败",
@@ -489,13 +496,14 @@ func (h *PaymentHandler) AlipayCallback(c *fiber.Ctx) error {
 		return errors.New(errors.CodeWechatCallbackInvalid, "支付通道校验失败")
 	}
 
-	// 校验 payment_config_id 与当前配置一致；旧数据为空时兼容并记录 warn
-	if payment.PaymentConfigID == nil {
+	// 商户支付单已由 GetConfigForCallback 按 merchant_id 绑定当前商户凭证；
+	// payment_config_id 只属于历史双读路径，不能用于否定新商户回调。
+	if payment.MerchantID == nil && payment.PaymentConfigID == nil {
 		h.logger.Warn("支付宝回调：payment_config_id 为空，跳过配置 ID 校验（旧数据兼容）",
 			zap.String("out_trade_no", outTradeNo),
 			zap.Uint("config_id", cfg.ID),
 		)
-	} else if *payment.PaymentConfigID != cfg.ID {
+	} else if payment.MerchantID == nil && *payment.PaymentConfigID != cfg.ID {
 		h.logger.Error("支付宝回调：payment_config_id 不匹配",
 			zap.String("out_trade_no", outTradeNo),
 			zap.Uint("payment_config_id", *payment.PaymentConfigID),
@@ -562,7 +570,7 @@ func (h *PaymentHandler) FuiouPayCallback(c *fiber.Ctx) error {
 	ctx := c.UserContext()
 	c.Set("Content-Type", "text/plain; charset=utf-8")
 
-	// 预解析订单号（不验签），用于按 payment_config_id 加载创建订单时所用的配置
+	// 预解析订单号（不验签），用于按支付单冻结商户或历史 payment_config_id 双读加载配置
 	preNotify, err := fuiou.ParseNotify(body)
 	if err != nil {
 		h.logger.Error("富友回调：预解析失败",

internal/infrastructure/audit/approval.go

@@ -115,6 +115,20 @@ func approvalBusinessResource(ctx context.Context, tx *gorm.DB, businessType str
 				"approval_instance_id": instanceID, "status": recharge.Status,
 			},
 		}, nil
+	case constants.ApprovalBusinessTypeEmployeeCollection:
+		var attempt model.EmployeeCollectionApplicationAttempt
+		if err := tx.WithContext(ctx).First(&attempt, businessID).Error; err != nil {
+			return ResourceInput{}, errors.Wrap(errors.CodeDatabaseError, err, "查询审批关联核销审批尝试记录失败")
+		}
+		return ResourceInput{
+			Type: constants.AuditResourceEmployeeCollectionAttempt, ID: &id,
+			Key: id, DisplayName: "审批尝试 " + id,
+			Relation: constants.AuditResourceRelationReference, Role: constants.AuditResourceRoleApprovalBusiness,
+			IdentitySnapshot: map[string]any{
+				"id": attempt.ID, "application_id": attempt.ApplicationID, "attempt_no": attempt.AttemptNo,
+				"paid_amount": attempt.PaidAmount, "approval_instance_id": instanceID,
+			},
+		}, nil
 	default:
 		return ResourceInput{}, errors.New(errors.CodeInvalidParam, "审批业务类型尚未注册审计资源")
 	}

internal/infrastructure/audit/employee_collection.go

@@ -0,0 +1,41 @@
+package audit
+
+import (
+	"context"
+	"strconv"
+
+	"gorm.io/gorm"
+
+	employeecollection "github.com/break/junhong_cmp_fiber/internal/application/employeecollection"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// WriteEmployeeCollectionBill 将员工代收款账单事实变化写入统一 Audit Event。
+// 操作者与入口来自调用方审计上下文：订单建账为后台账号入口，充值入账为 Worker 或渠道回调入口。
+func (w *Writer) WriteEmployeeCollectionBill(ctx context.Context, tx *gorm.DB, change employeecollection.BillAudit) error {
+	if change.Bill == nil || change.Bill.ID == 0 || change.Bill.SourceKey == "" {
+		return errors.New(errors.CodeInvalidParam, "员工代收款账单审计资源不完整")
+	}
+	bill := change.Bill
+	resourceID := strconv.FormatUint(uint64(bill.ID), 10)
+	return w.Append(ctx, tx, AppendInput{
+		EventID: change.EventID, ActionCode: change.ActionCode, Summary: change.Summary,
+		ScopeType: constants.AuditScopePlatform, Result: constants.AuditResultSuccess,
+		CorrelationID: change.CorrelationID,
+		Resources: []ResourceInput{{
+			Type: constants.AuditResourceEmployeeCollectionBill, ID: &resourceID,
+			Key: bill.SourceKey, DisplayName: bill.SourceNo,
+			Relation: constants.AuditResourceRelationPrimary, Role: constants.AuditResourceRoleCollectionBill,
+			IdentitySnapshot: map[string]any{
+				"id": bill.ID, "source_type": bill.SourceType, "source_id": bill.SourceID,
+				"source_key": bill.SourceKey, "source_no": bill.SourceNo,
+				"debtor_account_id": bill.DebtorAccountID, "receivable_amount": bill.ReceivableAmount,
+				"received_amount": bill.ReceivedAmount, "reserved_amount": bill.ReservedAmount,
+				"status": bill.Status,
+			},
+			BeforeData: change.BeforeData, AfterData: change.AfterData,
+			SubjectVisibility: constants.AuditSubjectResult, SubjectSummary: change.Summary,
+		}},
+	})
+}

internal/infrastructure/audit/employee_collection_application.go

@@ -0,0 +1,85 @@
+package audit
+
+import (
+	"context"
+	"strconv"
+
+	"gorm.io/gorm"
+
+	employeecollection "github.com/break/junhong_cmp_fiber/internal/application/employeecollection"
+	employeecollectiondomain "github.com/break/junhong_cmp_fiber/internal/domain/employeecollection"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// WriteEmployeeCollectionApplication 将核销申请、审批尝试记录与受影响账单写入统一 Audit Event。
+// 申请与尝试的冻结快照含付款凭证对象键，审计只记录数量与外部流水号脱敏值，不复制敏感付款内容。
+func (w *Writer) WriteEmployeeCollectionApplication(ctx context.Context, tx *gorm.DB, change employeecollection.ApplicationAudit) error {
+	if change.Application == nil || change.Application.ID == 0 {
+		return errors.New(errors.CodeInvalidParam, "核销申请审计资源不完整")
+	}
+	application := change.Application
+	applicationID := strconv.FormatUint(uint64(application.ID), 10)
+	resources := []ResourceInput{{
+		Type: constants.AuditResourceEmployeeCollectionApplication, ID: &applicationID,
+		Key: applicationID, DisplayName: "核销申请 " + applicationID,
+		Relation: constants.AuditResourceRelationPrimary, Role: constants.AuditResourceRoleCollectionApplication,
+		IdentitySnapshot: map[string]any{
+			"id": application.ID, "applicant_account_id": application.ApplicantAccountID,
+			"acting_operator_id": application.ActingOperatorID,
+			"payment_method_id":  application.PaymentMethodID, "paid_amount": application.PaidAmount,
+			"status":                      application.Status,
+			"latest_approval_instance_id": application.LatestApprovalInstanceID,
+		},
+		BeforeData: change.BeforeData, AfterData: change.AfterData,
+		SubjectVisibility: constants.AuditSubjectResult, SubjectSummary: change.Summary,
+	}}
+	if change.Attempt != nil && change.Attempt.ID != 0 {
+		attempt := change.Attempt
+		attemptID := strconv.FormatUint(uint64(attempt.ID), 10)
+		instanceID := uint(0)
+		if attempt.ApprovalInstanceID != nil {
+			instanceID = *attempt.ApprovalInstanceID
+		}
+		resources = append(resources, ResourceInput{
+			Type: constants.AuditResourceEmployeeCollectionAttempt, ID: &attemptID,
+			Key: attemptID, DisplayName: "审批尝试 " + attemptID,
+			Relation: constants.AuditResourceRelationReference, Role: constants.AuditResourceRoleCollectionAttempt,
+			IdentitySnapshot: map[string]any{
+				"id": attempt.ID, "application_id": attempt.ApplicationID, "attempt_no": attempt.AttemptNo,
+				"paid_amount": attempt.PaidAmount, "approval_instance_id": instanceID,
+			},
+			SubjectVisibility: constants.AuditSubjectResult, SubjectSummary: change.Summary,
+		})
+	}
+	for _, bill := range change.Bills {
+		if bill == nil || bill.ID == 0 {
+			continue
+		}
+		billID := strconv.FormatUint(uint64(bill.ID), 10)
+		resources = append(resources, ResourceInput{
+			Type: constants.AuditResourceEmployeeCollectionBill, ID: &billID,
+			Key: bill.SourceKey, DisplayName: bill.SourceNo,
+			Relation: constants.AuditResourceRelationAffected, Role: constants.AuditResourceRoleCollectionBillAffected,
+			IdentitySnapshot: map[string]any{
+				"id": bill.ID, "source_type": bill.SourceType, "source_id": bill.SourceID,
+				"source_key": bill.SourceKey, "debtor_account_id": bill.DebtorAccountID, "status": bill.Status,
+			},
+			SubjectVisibility: constants.AuditSubjectResult, SubjectSummary: change.Summary,
+		})
+	}
+	return w.Append(ctx, tx, AppendInput{
+		EventID: change.EventID, ActionCode: change.ActionCode, Summary: change.Summary,
+		ScopeType: constants.AuditScopePlatform, Result: constants.AuditResultSuccess,
+		CorrelationID: change.CorrelationID,
+		Metadata: map[string]any{
+			"payment_method_code": application.PaymentMethodCode,
+			"payer_name":          application.PayerName,
+			"external_transaction_no_masked": employeecollectiondomain.MaskExternalTransactionNo(
+				application.ExternalTransactionNo),
+			"voucher_count": len(application.PaymentVoucherKeys),
+			"bill_count":    len(change.Bills),
+		},
+		Resources: resources,
+	})
+}

internal/infrastructure/audit/registry.go

@@ -179,6 +179,16 @@ func NewRegistry() *Registry {
 	wecomDefaultCreatorSaved := connectionConfigAction(constants.AuditActionWeComDefaultCreatorSaved, "保存企业微信默认审批发起人", constants.AuditResourceWeComApplication, constants.AuditRiskHigh)
 	wecomMembersSynced := connectionConfigAction(constants.AuditActionWeComMembersSynced, "同步企业微信应用可见成员", constants.AuditResourceWeComApplication, constants.AuditRiskNormal)
 	wecomApprovalSceneSaved := connectionConfigAction(constants.AuditActionWeComApprovalSceneSaved, "保存企业微信审批场景配置", constants.AuditResourceWeComApprovalScene, constants.AuditRiskHigh)
+	employeeCollectionPaymentMethodCreated := connectionConfigAction(constants.AuditActionEmployeeCollectionPaymentMethodCreated, "创建线下收款方式", constants.AuditResourceEmployeeCollectionPaymentMethod, constants.AuditRiskNormal)
+	employeeCollectionPaymentMethodUpdated := connectionConfigAction(constants.AuditActionEmployeeCollectionPaymentMethodUpdated, "更新线下收款方式", constants.AuditResourceEmployeeCollectionPaymentMethod, constants.AuditRiskNormal)
+	employeeCollectionPaymentMethodDeleted := connectionConfigAction(constants.AuditActionEmployeeCollectionPaymentMethodDeleted, "删除线下收款方式", constants.AuditResourceEmployeeCollectionPaymentMethod, constants.AuditRiskHigh)
+	employeeCollectionBillCreated := employeeCollectionAction(constants.AuditActionEmployeeCollectionBillCreated, "创建员工代收款账单", constants.AuditResourceEmployeeCollectionBill)
+	employeeCollectionBillClosed := employeeCollectionAction(constants.AuditActionEmployeeCollectionBillClosed, "关闭员工代收款账单", constants.AuditResourceEmployeeCollectionBill)
+	employeeCollectionApplicationSubmitted := employeeCollectionAction(constants.AuditActionEmployeeCollectionApplicationSubmitted, "提交员工代收款核销申请", constants.AuditResourceEmployeeCollectionApplication)
+	employeeCollectionApplicationApproved := employeeCollectionAction(constants.AuditActionEmployeeCollectionApplicationApproved, "员工代收款核销申请企业微信通过", constants.AuditResourceEmployeeCollectionApplication)
+	employeeCollectionApplicationRejected := employeeCollectionAction(constants.AuditActionEmployeeCollectionApplicationRejected, "员工代收款核销申请企业微信驳回或撤销", constants.AuditResourceEmployeeCollectionApplication)
+	employeeCollectionApplicationRevoked := employeeCollectionAction(constants.AuditActionEmployeeCollectionApplicationRevoked, "员工代收款核销申请通过后撤销", constants.AuditResourceEmployeeCollectionApplication)
+	employeeCollectionBillRefundOffseted := employeeCollectionAction(constants.AuditActionEmployeeCollectionBillRefundOffseted, "来源订单退款冲销员工代收款账单", constants.AuditResourceEmployeeCollectionBill)
 	outboxReplayed := outboxRecoveryAction(
 		constants.AuditActionOutboxReplayed,
 		"人工重放 Outbox 事件",
@@ -349,245 +359,258 @@ func NewRegistry() *Registry {
 	withdrawalRejected := commissionWithdrawalAction(constants.AuditActionCommissionWithdrawalRejected, "驳回佣金提现申请")
 	return &Registry{
 		actionsByOperation: map[string]ActionDefinition{
-			constants.AuditOperationSystemConfigUpdate:        systemConfigUpdated,
-			constants.AuditOperationPaymentConfigCreate:       paymentConfigCreated,
-			constants.AuditOperationPaymentConfigUpdate:       paymentConfigUpdated,
-			constants.AuditOperationPaymentConfigDelete:       paymentConfigDeleted,
-			constants.AuditOperationPaymentConfigActivate:     paymentConfigActivated,
-			constants.AuditOperationPaymentConfigDeactivate:   paymentConfigDeactivated,
-			constants.AuditOperationCarrierCreate:             carrierCreated,
-			constants.AuditOperationCarrierUpdate:             carrierUpdated,
-			constants.AuditOperationCarrierDelete:             carrierDeleted,
-			constants.AuditOperationCarrierStatusUpdate:       carrierStatusUpdated,
-			constants.AuditOperationWeComApplicationSave:      wecomApplicationSaved,
-			constants.AuditOperationWeComDefaultCreatorSave:   wecomDefaultCreatorSaved,
-			constants.AuditOperationWeComMembersSync:          wecomMembersSynced,
-			constants.AuditOperationWeComApprovalSceneSave:    wecomApprovalSceneSaved,
-			constants.AuditOperationOutboxReplay:              outboxReplayed,
-			constants.AuditOperationOutboxReleaseExpiredLease: outboxExpiredLeaseReleased,
+			constants.AuditOperationSystemConfigUpdate:                    systemConfigUpdated,
+			constants.AuditOperationPaymentConfigCreate:                   paymentConfigCreated,
+			constants.AuditOperationPaymentConfigUpdate:                   paymentConfigUpdated,
+			constants.AuditOperationPaymentConfigDelete:                   paymentConfigDeleted,
+			constants.AuditOperationPaymentConfigActivate:                 paymentConfigActivated,
+			constants.AuditOperationPaymentConfigDeactivate:               paymentConfigDeactivated,
+			constants.AuditOperationCarrierCreate:                         carrierCreated,
+			constants.AuditOperationCarrierUpdate:                         carrierUpdated,
+			constants.AuditOperationCarrierDelete:                         carrierDeleted,
+			constants.AuditOperationCarrierStatusUpdate:                   carrierStatusUpdated,
+			constants.AuditOperationWeComApplicationSave:                  wecomApplicationSaved,
+			constants.AuditOperationWeComDefaultCreatorSave:               wecomDefaultCreatorSaved,
+			constants.AuditOperationWeComMembersSync:                      wecomMembersSynced,
+			constants.AuditOperationWeComApprovalSceneSave:                wecomApprovalSceneSaved,
+			constants.AuditOperationEmployeeCollectionPaymentMethodCreate: employeeCollectionPaymentMethodCreated,
+			constants.AuditOperationEmployeeCollectionPaymentMethodUpdate: employeeCollectionPaymentMethodUpdated,
+			constants.AuditOperationEmployeeCollectionPaymentMethodDelete: employeeCollectionPaymentMethodDeleted,
+			constants.AuditOperationOutboxReplay:                          outboxReplayed,
+			constants.AuditOperationOutboxReleaseExpiredLease:             outboxExpiredLeaseReleased,
 		},
 		actionsByCode: map[string]ActionDefinition{
-			constants.AuditActionAccountCreated:                        accountCreated,
-			constants.AuditActionAccountUpdated:                        accountUpdated,
-			constants.AuditActionAccountDeleted:                        accountDeleted,
-			constants.AuditActionAccountPasswordReset:                  accountPasswordReset,
-			constants.AuditActionAccountPasswordChanged:                accountPasswordChanged,
-			constants.AuditActionAccountWeComBound:                     accountWeComBound,
-			constants.AuditActionAuthLogin:                             authLogin,
-			constants.AuditActionAuthLogout:                            authLogout,
-			constants.AuditActionAuthTokenRefreshed:                    authTokenRefreshed,
-			constants.AuditActionAccountRolesAssigned:                  accountRolesAssigned,
-			constants.AuditActionAccountRoleRemoved:                    accountRoleRemoved,
-			constants.AuditActionShopRolesAssigned:                     shopRolesAssigned,
-			constants.AuditActionShopRoleDeleted:                       shopRoleDeleted,
-			constants.AuditActionShopCreated:                           shopCreated,
-			constants.AuditActionShopUpdated:                           shopUpdated,
-			constants.AuditActionShopEnabled:                           shopEnabled,
-			constants.AuditActionShopDisabled:                          shopDisabled,
-			constants.AuditActionShopDeleted:                           shopDeleted,
-			constants.AuditActionShopBusinessOwnerUpdated:              shopBusinessOwnerUpdated,
-			constants.AuditActionShopClientLoginLimitUpdated:           shopClientLoginLimitUpdated,
-			constants.AuditActionEnterpriseCreated:                     enterpriseCreated,
-			constants.AuditActionEnterpriseUpdated:                     enterpriseUpdated,
-			constants.AuditActionEnterpriseStatusUpdated:               enterpriseStatusUpdated,
-			constants.AuditActionEnterprisePasswordUpdated:             enterprisePasswordUpdated,
-			constants.AuditActionEnterpriseCardsAllocated:              enterpriseCardsAllocated,
-			constants.AuditActionEnterpriseCardsRecalled:               enterpriseCardsRecalled,
-			constants.AuditActionEnterpriseCardRemarkUpdated:           enterpriseCardRemarkUpdated,
-			constants.AuditActionEnterpriseDevicesAllocated:            enterpriseDevicesAllocated,
-			constants.AuditActionEnterpriseDevicesRecalled:             enterpriseDevicesRecalled,
-			constants.AuditActionPersonalCustomerProfileUpdated:        personalProfileUpdated,
-			constants.AuditActionPersonalCustomerPhoneBound:            personalPhoneBound,
-			constants.AuditActionPersonalCustomerPhoneChanged:          personalPhoneChanged,
-			constants.AuditActionPersonalCustomerWechatIdentityUpdated: personalWechatIdentityUpdated,
-			constants.AuditActionPersonalCustomerAssetBound:            personalAssetBound,
-			constants.AuditActionPersonalCustomerAssetUnbound:          personalAssetUnbound,
-			constants.AuditActionPersonalCustomerAssetBindingMigrated:  personalAssetBindingMigrated,
-			constants.AuditActionIotCardCreated:                        iotCardCreated,
-			constants.AuditActionIotCardDeleted:                        iotCardDeleted,
-			constants.AuditActionIotCardDeactivated:                    iotCardDeactivated,
-			constants.AuditActionIotCardPollingStatusUpdated:           iotCardPollingStatusUpdated,
-			constants.AuditActionIotCardPollingStatusBatchUpdated:      iotCardPollingStatusBatchUpdated,
-			constants.AuditActionIotCardBatchDeleted:                   iotCardBatchDeleted,
-			constants.AuditActionIotCardAllocationBatch:                iotCardAllocationBatch,
-			constants.AuditActionIotCardAllocated:                      iotCardAllocated,
-			constants.AuditActionIotCardRecallBatch:                    iotCardRecallBatch,
-			constants.AuditActionIotCardRecalled:                       iotCardRecalled,
-			constants.AuditActionIotCardSeriesBindingBatch:             iotCardSeriesBindingBatch,
-			constants.AuditActionIotCardSeriesBound:                    iotCardSeriesBound,
-			constants.AuditActionIotCardSpeedTierSet:                   iotCardSpeedTierSet,
-			constants.AuditActionIotCardRealnamePolicyBatchUpdated:     iotCardRealnamePolicyBatchUpdated,
-			constants.AuditActionIotCardRealnamePolicyUpdated:          iotCardRealnamePolicyUpdated,
-			constants.AuditActionIotCardRealnameStatusUpdated:          iotCardRealnameStatusUpdated,
-			constants.AuditActionIotCardRealnameCallbackSynced:         iotCardRealnameCallbackSynced,
-			constants.AuditActionIotCardManualRefreshed:                iotCardManualRefreshed,
-			constants.AuditActionIotCardPersonalRefreshed:              iotCardPersonalRefreshed,
-			constants.AuditActionIotCardWorkerRealnameSynced:           iotCardWorkerRealnameSynced,
-			constants.AuditActionIotCardWorkerTrafficSynced:            iotCardWorkerTrafficSynced,
-			constants.AuditActionIotCardWorkerNetworkSynced:            iotCardWorkerNetworkSynced,
-			constants.AuditActionIotCardManualStopped:                  iotCardManualStopped,
-			constants.AuditActionIotCardManualStarted:                  iotCardManualStarted,
-			constants.AuditActionIotCardAutoStopped:                    iotCardAutoStopped,
-			constants.AuditActionIotCardAutoStarted:                    iotCardAutoStarted,
-			constants.AuditActionIotCardOpenAPIStarted:                 iotCardOpenAPIStarted,
-			constants.AuditActionIotCardAutoStopReasonUpdated:          iotCardAutoStopReasonUpdated,
-			constants.AuditActionDeviceCreated:                         deviceCreated,
-			constants.AuditActionDeviceDeleted:                         deviceDeleted,
-			constants.AuditActionDeviceDeactivated:                     deviceDeactivated,
-			constants.AuditActionDevicePollingStatusUpdated:            devicePollingStatusUpdated,
-			constants.AuditActionDeviceAllocationBatch:                 deviceAllocationBatch,
-			constants.AuditActionDeviceAllocated:                       deviceAllocated,
-			constants.AuditActionDeviceRecallBatch:                     deviceRecallBatch,
-			constants.AuditActionDeviceRecalled:                        deviceRecalled,
-			constants.AuditActionDeviceSeriesBindingBatch:              deviceSeriesBindingBatch,
-			constants.AuditActionDeviceSeriesBound:                     deviceSeriesBound,
-			constants.AuditActionDeviceRealnamePolicyBatchUpdated:      deviceRealnamePolicyBatchUpdated,
-			constants.AuditActionDeviceRealnamePolicyUpdated:           deviceRealnamePolicyUpdated,
-			constants.AuditActionDeviceStopped:                         deviceStopped,
-			constants.AuditActionDeviceStarted:                         deviceStarted,
-			constants.AuditActionDeviceWiFiSet:                         deviceWiFiSet,
-			constants.AuditActionDeviceSwitchModeSet:                   deviceSwitchModeSet,
-			constants.AuditActionDeviceRebooted:                        deviceRebooted,
-			constants.AuditActionDeviceReset:                           deviceReset,
-			constants.AuditActionDeviceCardBound:                       deviceCardBound,
-			constants.AuditActionDeviceCardUnbound:                     deviceCardUnbound,
-			constants.AuditActionDeviceCurrentCardSwitched:             deviceCurrentCardSwitched,
-			constants.AuditActionDeviceWorkerObservationSynced:         deviceWorkerObservationSynced,
-			constants.AuditActionCardExchangeCreated:                   cardExchangeCreated,
-			constants.AuditActionCardExchangeShippingInfoSubmitted:     cardExchangeShippingInfoSubmitted,
-			constants.AuditActionCardExchangeShipped:                   cardExchangeShipped,
-			constants.AuditActionCardExchangeCompleted:                 cardExchangeCompleted,
-			constants.AuditActionCardExchangeCancelled:                 cardExchangeCancelled,
-			constants.AuditActionCardExchangeRenewed:                   cardExchangeRenewed,
-			constants.AuditActionDeviceExchangeCreated:                 deviceExchangeCreated,
-			constants.AuditActionDeviceExchangeShippingInfoSubmitted:   deviceExchangeShippingInfoSubmitted,
-			constants.AuditActionDeviceExchangeShipped:                 deviceExchangeShipped,
-			constants.AuditActionDeviceExchangeCompleted:               deviceExchangeCompleted,
-			constants.AuditActionDeviceExchangeCancelled:               deviceExchangeCancelled,
-			constants.AuditActionDeviceExchangeRenewed:                 deviceExchangeRenewed,
-			constants.AuditActionSystemConfigUpdated:                   systemConfigUpdated,
-			constants.AuditActionPaymentConfigCreated:                  paymentConfigCreated,
-			constants.AuditActionPaymentConfigUpdated:                  paymentConfigUpdated,
-			constants.AuditActionPaymentConfigDeleted:                  paymentConfigDeleted,
-			constants.AuditActionPaymentConfigActivated:                paymentConfigActivated,
-			constants.AuditActionPaymentConfigDeactivated:              paymentConfigDeactivated,
-			constants.AuditActionCarrierCreated:                        carrierCreated,
-			constants.AuditActionCarrierUpdated:                        carrierUpdated,
-			constants.AuditActionCarrierDeleted:                        carrierDeleted,
-			constants.AuditActionCarrierStatusUpdated:                  carrierStatusUpdated,
-			constants.AuditActionWeComApplicationSaved:                 wecomApplicationSaved,
-			constants.AuditActionWeComDefaultCreatorSaved:              wecomDefaultCreatorSaved,
-			constants.AuditActionWeComMembersSynced:                    wecomMembersSynced,
-			constants.AuditActionWeComApprovalSceneSaved:               wecomApprovalSceneSaved,
-			constants.AuditActionOutboxReplayed:                        outboxReplayed,
-			constants.AuditActionOutboxExpiredLeaseReleased:            outboxExpiredLeaseReleased,
-			constants.AuditActionIotCardImportTaskCreated:              iotCardImportTaskCreated,
-			constants.AuditActionIotCardImportTaskCompleted:            iotCardImportTaskCompleted,
-			constants.AuditActionDeviceImportTaskCreated:               deviceImportTaskCreated,
-			constants.AuditActionDeviceImportTaskCompleted:             deviceImportTaskCompleted,
-			constants.AuditActionAssetPackageBatchOrderTaskCreated:     assetPackageBatchOrderTaskCreated,
-			constants.AuditActionAssetPackageBatchOrderTaskCompleted:   assetPackageBatchOrderTaskCompleted,
-			constants.AuditActionOrderPackageInvalidateTaskCreated:     orderPackageInvalidateTaskCreated,
-			constants.AuditActionOrderPackageInvalidateTaskCompleted:   orderPackageInvalidateTaskCompleted,
-			constants.AuditActionOrderPackageInvalidateItem:            orderPackageInvalidateItem,
-			constants.AuditActionExportTaskCreated:                     exportTaskCreated,
-			constants.AuditActionExportTaskCancelled:                   exportTaskCancelled,
-			constants.AuditActionNotificationDelivered:                 notificationDelivered,
-			constants.AuditActionNotificationRead:                      notificationRead,
-			constants.AuditActionNotificationReadAll:                   notificationReadAll,
-			constants.AuditActionNotificationCleanup:                   notificationCleanup,
-			constants.AuditActionNotificationCleanupItem:               notificationCleanupItem,
-			constants.AuditActionLogRetentionCleanup:                   retentionCleanup,
-			constants.AuditActionPollingConfigCreated:                  pollingConfigCreated,
-			constants.AuditActionPollingConfigUpdated:                  pollingConfigUpdated,
-			constants.AuditActionPollingConfigDeleted:                  pollingConfigDeleted,
-			constants.AuditActionPollingConfigStatusUpdated:            pollingConfigStatusUpdated,
-			constants.AuditActionPollingConcurrencyUpdated:             pollingConcurrencyUpdated,
-			constants.AuditActionPollingConcurrencyReset:               pollingConcurrencyReset,
-			constants.AuditActionPollingAlertRuleCreated:               pollingAlertRuleCreated,
-			constants.AuditActionPollingAlertRuleUpdated:               pollingAlertRuleUpdated,
-			constants.AuditActionPollingAlertRuleDeleted:               pollingAlertRuleDeleted,
-			constants.AuditActionPollingManualTriggerSingle:            pollingManualTriggerSingle,
-			constants.AuditActionPollingManualTriggerBatch:             pollingManualTriggerBatch,
-			constants.AuditActionPollingManualTriggerByCondition:       pollingManualTriggerByCondition,
-			constants.AuditActionPollingManualCancelled:                pollingManualCancelled,
-			constants.AuditActionWeComCredentialsRead:                  wecomCredentialsRead,
-			constants.AuditActionRoleCreated:                           roleCreated,
-			constants.AuditActionRoleUpdated:                           roleUpdated,
-			constants.AuditActionRoleStatusUpdated:                     roleStatusUpdated,
-			constants.AuditActionRoleDefaultCreditUpdated:              roleDefaultCreditUpdated,
-			constants.AuditActionRoleDeleted:                           roleDeleted,
-			constants.AuditActionRolePermissionsAssigned:               rolePermissionsAssigned,
-			constants.AuditActionRolePermissionRemoved:                 rolePermissionRemoved,
-			constants.AuditActionRolePermissionsBatchRemoved:           rolePermissionsBatchRemoved,
-			constants.AuditActionPermissionCreated:                     permissionCreated,
-			constants.AuditActionPermissionUpdated:                     permissionUpdated,
-			constants.AuditActionPermissionDeleted:                     permissionDeleted,
-			constants.AuditActionPackageSeriesCreated:                  packageSeriesCreated,
-			constants.AuditActionPackageSeriesUpdated:                  packageSeriesUpdated,
-			constants.AuditActionPackageSeriesDeleted:                  packageSeriesDeleted,
-			constants.AuditActionPackageSeriesStatusUpdated:            packageSeriesStatusUpdated,
-			constants.AuditActionPackageCreated:                        packageCreated,
-			constants.AuditActionPackageUpdated:                        packageUpdated,
-			constants.AuditActionPackageDeleted:                        packageDeleted,
-			constants.AuditActionPackageStatusUpdated:                  packageStatusUpdated,
-			constants.AuditActionPackageShelfStatusUpdated:             packageShelfStatusUpdated,
-			constants.AuditActionShopPackageShelfStatusUpdated:         shopPackageShelfStatusUpdated,
-			constants.AuditActionPackageRetailPriceUpdated:             packageRetailPriceUpdated,
-			constants.AuditActionShopSeriesGrantCreated:                shopSeriesGrantCreated,
-			constants.AuditActionShopSeriesGrantUpdated:                shopSeriesGrantUpdated,
-			constants.AuditActionShopSeriesGrantPackagesManaged:        shopSeriesGrantPackagesManaged,
-			constants.AuditActionShopSeriesGrantDeleted:                shopSeriesGrantDeleted,
-			constants.AuditActionShopPackageBatchAllocated:             shopPackageBatchAllocated,
-			constants.AuditActionShopPackageAllocated:                  shopPackageAllocated,
-			constants.AuditActionShopPackageExpiryBaseUpdated:          shopPackageExpiryBaseUpdated,
-			constants.AuditActionShopPackageBatchPricingUpdated:        shopPackageBatchPricingUpdated,
-			constants.AuditActionShopPackagePricingItemUpdated:         shopPackagePricingItemUpdated,
-			constants.AuditActionPackageUsageActivated:                 packageUsageActivated,
-			constants.AuditActionPackageUsageExpired:                   packageUsageExpired,
-			constants.AuditActionPackageUsageTrafficDeducted:           packageUsageTrafficDeducted,
-			constants.AuditActionPackageUsageTrafficReset:              packageUsageTrafficReset,
-			constants.AuditActionPackageUsageRefundInvalidated:         packageUsageRefundInvalidated,
-			constants.AuditActionPackageUsageAssetInvalidated:          packageUsageAssetInvalidated,
-			constants.AuditActionPackageUsageExpiresAtUpdated:          packageUsageExpiresAtUpdated,
-			constants.AuditActionPackageUsageTrafficAdjusted:           packageUsageTrafficAdjusted,
-			constants.AuditActionOrderCreated:                          orderCreated,
-			constants.AuditActionOrderCancelled:                        orderCancelled,
-			constants.AuditActionOrderWalletPaid:                       orderWalletPaid,
-			constants.AuditActionOrderExpiredClosed:                    orderExpiredClosed,
-			constants.AuditActionOrderOnlinePaid:                       orderOnlinePaid,
-			constants.AuditActionAgentWalletOrderDebited:               agentWalletOrderDebited,
-			constants.AuditActionAgentWalletOrderReserved:              agentWalletOrderReserved,
-			constants.AuditActionAgentWalletOrderReleased:              agentWalletOrderReleased,
-			constants.AuditActionAgentWalletOrderCompleted:             agentWalletOrderCompleted,
-			constants.AuditActionAgentWalletBalanceAdjusted:            agentWalletBalanceAdjusted,
-			constants.AuditActionAgentWalletCreditChanged:              agentWalletCreditChanged,
-			constants.AuditActionPaymentCreated:                        paymentCreated,
-			constants.AuditActionPaymentConfirmed:                      paymentConfirmed,
-			constants.AuditActionPaymentFailed:                         paymentFailed,
-			constants.AuditActionIntegrationAttemptStarted:             integrationAttemptStarted,
-			constants.AuditActionIntegrationInboundReceived:            integrationInboundReceived,
-			constants.AuditActionAgentRechargeCreated:                  agentRechargeCreated,
-			constants.AuditActionAgentRechargeCredited:                 agentRechargeCredited,
-			constants.AuditActionAgentRechargeClosed:                   agentRechargeClosed,
-			constants.AuditActionAssetRechargeAutoPurchased:            assetRechargeAutoPurchased,
-			constants.AuditActionRefundCreated:                         refundCreated,
-			constants.AuditActionRefundApproved:                        refundApproved,
-			constants.AuditActionRefundRejected:                        refundRejected,
-			constants.AuditActionRefundReturned:                        refundReturned,
-			constants.AuditActionRefundResubmitted:                     refundResubmitted,
-			constants.AuditActionRefundCommissionInvalidated:           refundCommissionInvalidated,
-			constants.AuditActionRefundAssetProcessed:                  refundAssetProcessed,
-			constants.AuditActionApprovalRequested:                     approvalRequested,
-			constants.AuditActionApprovalSubmissionSynced:              approvalSubmissionSynced,
-			constants.AuditActionApprovalSubmissionRecovered:           approvalSubmissionRecovered,
-			constants.AuditActionApprovalDecisionSynced:                approvalDecisionSynced,
-			constants.AuditActionCommissionCalculated:                  commissionCalculated,
-			constants.AuditActionCommissionCredited:                    commissionCredited,
-			constants.AuditActionCommissionInvalidated:                 commissionInvalidated,
-			constants.AuditActionCommissionWithdrawalRequested:         withdrawalRequested,
-			constants.AuditActionCommissionWithdrawalApproved:          withdrawalApproved,
-			constants.AuditActionCommissionWithdrawalRejected:          withdrawalRejected,
+			constants.AuditActionAccountCreated:                         accountCreated,
+			constants.AuditActionAccountUpdated:                         accountUpdated,
+			constants.AuditActionAccountDeleted:                         accountDeleted,
+			constants.AuditActionAccountPasswordReset:                   accountPasswordReset,
+			constants.AuditActionAccountPasswordChanged:                 accountPasswordChanged,
+			constants.AuditActionAccountWeComBound:                      accountWeComBound,
+			constants.AuditActionAuthLogin:                              authLogin,
+			constants.AuditActionAuthLogout:                             authLogout,
+			constants.AuditActionAuthTokenRefreshed:                     authTokenRefreshed,
+			constants.AuditActionAccountRolesAssigned:                   accountRolesAssigned,
+			constants.AuditActionAccountRoleRemoved:                     accountRoleRemoved,
+			constants.AuditActionShopRolesAssigned:                      shopRolesAssigned,
+			constants.AuditActionShopRoleDeleted:                        shopRoleDeleted,
+			constants.AuditActionShopCreated:                            shopCreated,
+			constants.AuditActionShopUpdated:                            shopUpdated,
+			constants.AuditActionShopEnabled:                            shopEnabled,
+			constants.AuditActionShopDisabled:                           shopDisabled,
+			constants.AuditActionShopDeleted:                            shopDeleted,
+			constants.AuditActionShopBusinessOwnerUpdated:               shopBusinessOwnerUpdated,
+			constants.AuditActionShopClientLoginLimitUpdated:            shopClientLoginLimitUpdated,
+			constants.AuditActionEnterpriseCreated:                      enterpriseCreated,
+			constants.AuditActionEnterpriseUpdated:                      enterpriseUpdated,
+			constants.AuditActionEnterpriseStatusUpdated:                enterpriseStatusUpdated,
+			constants.AuditActionEnterprisePasswordUpdated:              enterprisePasswordUpdated,
+			constants.AuditActionEnterpriseCardsAllocated:               enterpriseCardsAllocated,
+			constants.AuditActionEnterpriseCardsRecalled:                enterpriseCardsRecalled,
+			constants.AuditActionEnterpriseCardRemarkUpdated:            enterpriseCardRemarkUpdated,
+			constants.AuditActionEnterpriseDevicesAllocated:             enterpriseDevicesAllocated,
+			constants.AuditActionEnterpriseDevicesRecalled:              enterpriseDevicesRecalled,
+			constants.AuditActionPersonalCustomerProfileUpdated:         personalProfileUpdated,
+			constants.AuditActionPersonalCustomerPhoneBound:             personalPhoneBound,
+			constants.AuditActionPersonalCustomerPhoneChanged:           personalPhoneChanged,
+			constants.AuditActionPersonalCustomerWechatIdentityUpdated:  personalWechatIdentityUpdated,
+			constants.AuditActionPersonalCustomerAssetBound:             personalAssetBound,
+			constants.AuditActionPersonalCustomerAssetUnbound:           personalAssetUnbound,
+			constants.AuditActionPersonalCustomerAssetBindingMigrated:   personalAssetBindingMigrated,
+			constants.AuditActionIotCardCreated:                         iotCardCreated,
+			constants.AuditActionIotCardDeleted:                         iotCardDeleted,
+			constants.AuditActionIotCardDeactivated:                     iotCardDeactivated,
+			constants.AuditActionIotCardPollingStatusUpdated:            iotCardPollingStatusUpdated,
+			constants.AuditActionIotCardPollingStatusBatchUpdated:       iotCardPollingStatusBatchUpdated,
+			constants.AuditActionIotCardBatchDeleted:                    iotCardBatchDeleted,
+			constants.AuditActionIotCardAllocationBatch:                 iotCardAllocationBatch,
+			constants.AuditActionIotCardAllocated:                       iotCardAllocated,
+			constants.AuditActionIotCardRecallBatch:                     iotCardRecallBatch,
+			constants.AuditActionIotCardRecalled:                        iotCardRecalled,
+			constants.AuditActionIotCardSeriesBindingBatch:              iotCardSeriesBindingBatch,
+			constants.AuditActionIotCardSeriesBound:                     iotCardSeriesBound,
+			constants.AuditActionIotCardSpeedTierSet:                    iotCardSpeedTierSet,
+			constants.AuditActionIotCardRealnamePolicyBatchUpdated:      iotCardRealnamePolicyBatchUpdated,
+			constants.AuditActionIotCardRealnamePolicyUpdated:           iotCardRealnamePolicyUpdated,
+			constants.AuditActionIotCardRealnameStatusUpdated:           iotCardRealnameStatusUpdated,
+			constants.AuditActionIotCardRealnameCallbackSynced:          iotCardRealnameCallbackSynced,
+			constants.AuditActionIotCardManualRefreshed:                 iotCardManualRefreshed,
+			constants.AuditActionIotCardPersonalRefreshed:               iotCardPersonalRefreshed,
+			constants.AuditActionIotCardWorkerRealnameSynced:            iotCardWorkerRealnameSynced,
+			constants.AuditActionIotCardWorkerTrafficSynced:             iotCardWorkerTrafficSynced,
+			constants.AuditActionIotCardWorkerNetworkSynced:             iotCardWorkerNetworkSynced,
+			constants.AuditActionIotCardManualStopped:                   iotCardManualStopped,
+			constants.AuditActionIotCardManualStarted:                   iotCardManualStarted,
+			constants.AuditActionIotCardAutoStopped:                     iotCardAutoStopped,
+			constants.AuditActionIotCardAutoStarted:                     iotCardAutoStarted,
+			constants.AuditActionIotCardOpenAPIStarted:                  iotCardOpenAPIStarted,
+			constants.AuditActionIotCardAutoStopReasonUpdated:           iotCardAutoStopReasonUpdated,
+			constants.AuditActionDeviceCreated:                          deviceCreated,
+			constants.AuditActionDeviceDeleted:                          deviceDeleted,
+			constants.AuditActionDeviceDeactivated:                      deviceDeactivated,
+			constants.AuditActionDevicePollingStatusUpdated:             devicePollingStatusUpdated,
+			constants.AuditActionDeviceAllocationBatch:                  deviceAllocationBatch,
+			constants.AuditActionDeviceAllocated:                        deviceAllocated,
+			constants.AuditActionDeviceRecallBatch:                      deviceRecallBatch,
+			constants.AuditActionDeviceRecalled:                         deviceRecalled,
+			constants.AuditActionDeviceSeriesBindingBatch:               deviceSeriesBindingBatch,
+			constants.AuditActionDeviceSeriesBound:                      deviceSeriesBound,
+			constants.AuditActionDeviceRealnamePolicyBatchUpdated:       deviceRealnamePolicyBatchUpdated,
+			constants.AuditActionDeviceRealnamePolicyUpdated:            deviceRealnamePolicyUpdated,
+			constants.AuditActionDeviceStopped:                          deviceStopped,
+			constants.AuditActionDeviceStarted:                          deviceStarted,
+			constants.AuditActionDeviceWiFiSet:                          deviceWiFiSet,
+			constants.AuditActionDeviceSwitchModeSet:                    deviceSwitchModeSet,
+			constants.AuditActionDeviceRebooted:                         deviceRebooted,
+			constants.AuditActionDeviceReset:                            deviceReset,
+			constants.AuditActionDeviceCardBound:                        deviceCardBound,
+			constants.AuditActionDeviceCardUnbound:                      deviceCardUnbound,
+			constants.AuditActionDeviceCurrentCardSwitched:              deviceCurrentCardSwitched,
+			constants.AuditActionDeviceWorkerObservationSynced:          deviceWorkerObservationSynced,
+			constants.AuditActionCardExchangeCreated:                    cardExchangeCreated,
+			constants.AuditActionCardExchangeShippingInfoSubmitted:      cardExchangeShippingInfoSubmitted,
+			constants.AuditActionCardExchangeShipped:                    cardExchangeShipped,
+			constants.AuditActionCardExchangeCompleted:                  cardExchangeCompleted,
+			constants.AuditActionCardExchangeCancelled:                  cardExchangeCancelled,
+			constants.AuditActionCardExchangeRenewed:                    cardExchangeRenewed,
+			constants.AuditActionDeviceExchangeCreated:                  deviceExchangeCreated,
+			constants.AuditActionDeviceExchangeShippingInfoSubmitted:    deviceExchangeShippingInfoSubmitted,
+			constants.AuditActionDeviceExchangeShipped:                  deviceExchangeShipped,
+			constants.AuditActionDeviceExchangeCompleted:                deviceExchangeCompleted,
+			constants.AuditActionDeviceExchangeCancelled:                deviceExchangeCancelled,
+			constants.AuditActionDeviceExchangeRenewed:                  deviceExchangeRenewed,
+			constants.AuditActionSystemConfigUpdated:                    systemConfigUpdated,
+			constants.AuditActionPaymentConfigCreated:                   paymentConfigCreated,
+			constants.AuditActionPaymentConfigUpdated:                   paymentConfigUpdated,
+			constants.AuditActionPaymentConfigDeleted:                   paymentConfigDeleted,
+			constants.AuditActionPaymentConfigActivated:                 paymentConfigActivated,
+			constants.AuditActionPaymentConfigDeactivated:               paymentConfigDeactivated,
+			constants.AuditActionCarrierCreated:                         carrierCreated,
+			constants.AuditActionCarrierUpdated:                         carrierUpdated,
+			constants.AuditActionCarrierDeleted:                         carrierDeleted,
+			constants.AuditActionCarrierStatusUpdated:                   carrierStatusUpdated,
+			constants.AuditActionEmployeeCollectionPaymentMethodCreated: employeeCollectionPaymentMethodCreated,
+			constants.AuditActionEmployeeCollectionPaymentMethodUpdated: employeeCollectionPaymentMethodUpdated,
+			constants.AuditActionEmployeeCollectionPaymentMethodDeleted: employeeCollectionPaymentMethodDeleted,
+			constants.AuditActionEmployeeCollectionBillCreated:          employeeCollectionBillCreated,
+			constants.AuditActionEmployeeCollectionBillClosed:           employeeCollectionBillClosed,
+			constants.AuditActionEmployeeCollectionApplicationSubmitted: employeeCollectionApplicationSubmitted,
+			constants.AuditActionEmployeeCollectionApplicationApproved:  employeeCollectionApplicationApproved,
+			constants.AuditActionEmployeeCollectionApplicationRejected:  employeeCollectionApplicationRejected,
+			constants.AuditActionEmployeeCollectionApplicationRevoked:   employeeCollectionApplicationRevoked,
+			constants.AuditActionEmployeeCollectionBillRefundOffseted:   employeeCollectionBillRefundOffseted,
+			constants.AuditActionWeComApplicationSaved:                  wecomApplicationSaved,
+			constants.AuditActionWeComDefaultCreatorSaved:               wecomDefaultCreatorSaved,
+			constants.AuditActionWeComMembersSynced:                     wecomMembersSynced,
+			constants.AuditActionWeComApprovalSceneSaved:                wecomApprovalSceneSaved,
+			constants.AuditActionOutboxReplayed:                         outboxReplayed,
+			constants.AuditActionOutboxExpiredLeaseReleased:             outboxExpiredLeaseReleased,
+			constants.AuditActionIotCardImportTaskCreated:               iotCardImportTaskCreated,
+			constants.AuditActionIotCardImportTaskCompleted:             iotCardImportTaskCompleted,
+			constants.AuditActionDeviceImportTaskCreated:                deviceImportTaskCreated,
+			constants.AuditActionDeviceImportTaskCompleted:              deviceImportTaskCompleted,
+			constants.AuditActionAssetPackageBatchOrderTaskCreated:      assetPackageBatchOrderTaskCreated,
+			constants.AuditActionAssetPackageBatchOrderTaskCompleted:    assetPackageBatchOrderTaskCompleted,
+			constants.AuditActionOrderPackageInvalidateTaskCreated:      orderPackageInvalidateTaskCreated,
+			constants.AuditActionOrderPackageInvalidateTaskCompleted:    orderPackageInvalidateTaskCompleted,
+			constants.AuditActionOrderPackageInvalidateItem:             orderPackageInvalidateItem,
+			constants.AuditActionExportTaskCreated:                      exportTaskCreated,
+			constants.AuditActionExportTaskCancelled:                    exportTaskCancelled,
+			constants.AuditActionNotificationDelivered:                  notificationDelivered,
+			constants.AuditActionNotificationRead:                       notificationRead,
+			constants.AuditActionNotificationReadAll:                    notificationReadAll,
+			constants.AuditActionNotificationCleanup:                    notificationCleanup,
+			constants.AuditActionNotificationCleanupItem:                notificationCleanupItem,
+			constants.AuditActionLogRetentionCleanup:                    retentionCleanup,
+			constants.AuditActionPollingConfigCreated:                   pollingConfigCreated,
+			constants.AuditActionPollingConfigUpdated:                   pollingConfigUpdated,
+			constants.AuditActionPollingConfigDeleted:                   pollingConfigDeleted,
+			constants.AuditActionPollingConfigStatusUpdated:             pollingConfigStatusUpdated,
+			constants.AuditActionPollingConcurrencyUpdated:              pollingConcurrencyUpdated,
+			constants.AuditActionPollingConcurrencyReset:                pollingConcurrencyReset,
+			constants.AuditActionPollingAlertRuleCreated:                pollingAlertRuleCreated,
+			constants.AuditActionPollingAlertRuleUpdated:                pollingAlertRuleUpdated,
+			constants.AuditActionPollingAlertRuleDeleted:                pollingAlertRuleDeleted,
+			constants.AuditActionPollingManualTriggerSingle:             pollingManualTriggerSingle,
+			constants.AuditActionPollingManualTriggerBatch:              pollingManualTriggerBatch,
+			constants.AuditActionPollingManualTriggerByCondition:        pollingManualTriggerByCondition,
+			constants.AuditActionPollingManualCancelled:                 pollingManualCancelled,
+			constants.AuditActionWeComCredentialsRead:                   wecomCredentialsRead,
+			constants.AuditActionRoleCreated:                            roleCreated,
+			constants.AuditActionRoleUpdated:                            roleUpdated,
+			constants.AuditActionRoleStatusUpdated:                      roleStatusUpdated,
+			constants.AuditActionRoleDefaultCreditUpdated:               roleDefaultCreditUpdated,
+			constants.AuditActionRoleDeleted:                            roleDeleted,
+			constants.AuditActionRolePermissionsAssigned:                rolePermissionsAssigned,
+			constants.AuditActionRolePermissionRemoved:                  rolePermissionRemoved,
+			constants.AuditActionRolePermissionsBatchRemoved:            rolePermissionsBatchRemoved,
+			constants.AuditActionPermissionCreated:                      permissionCreated,
+			constants.AuditActionPermissionUpdated:                      permissionUpdated,
+			constants.AuditActionPermissionDeleted:                      permissionDeleted,
+			constants.AuditActionPackageSeriesCreated:                   packageSeriesCreated,
+			constants.AuditActionPackageSeriesUpdated:                   packageSeriesUpdated,
+			constants.AuditActionPackageSeriesDeleted:                   packageSeriesDeleted,
+			constants.AuditActionPackageSeriesStatusUpdated:             packageSeriesStatusUpdated,
+			constants.AuditActionPackageCreated:                         packageCreated,
+			constants.AuditActionPackageUpdated:                         packageUpdated,
+			constants.AuditActionPackageDeleted:                         packageDeleted,
+			constants.AuditActionPackageStatusUpdated:                   packageStatusUpdated,
+			constants.AuditActionPackageShelfStatusUpdated:              packageShelfStatusUpdated,
+			constants.AuditActionShopPackageShelfStatusUpdated:          shopPackageShelfStatusUpdated,
+			constants.AuditActionPackageRetailPriceUpdated:              packageRetailPriceUpdated,
+			constants.AuditActionShopSeriesGrantCreated:                 shopSeriesGrantCreated,
+			constants.AuditActionShopSeriesGrantUpdated:                 shopSeriesGrantUpdated,
+			constants.AuditActionShopSeriesGrantPackagesManaged:         shopSeriesGrantPackagesManaged,
+			constants.AuditActionShopSeriesGrantDeleted:                 shopSeriesGrantDeleted,
+			constants.AuditActionShopPackageBatchAllocated:              shopPackageBatchAllocated,
+			constants.AuditActionShopPackageAllocated:                   shopPackageAllocated,
+			constants.AuditActionShopPackageExpiryBaseUpdated:           shopPackageExpiryBaseUpdated,
+			constants.AuditActionShopPackageBatchPricingUpdated:         shopPackageBatchPricingUpdated,
+			constants.AuditActionShopPackagePricingItemUpdated:          shopPackagePricingItemUpdated,
+			constants.AuditActionPackageUsageActivated:                  packageUsageActivated,
+			constants.AuditActionPackageUsageExpired:                    packageUsageExpired,
+			constants.AuditActionPackageUsageTrafficDeducted:            packageUsageTrafficDeducted,
+			constants.AuditActionPackageUsageTrafficReset:               packageUsageTrafficReset,
+			constants.AuditActionPackageUsageRefundInvalidated:          packageUsageRefundInvalidated,
+			constants.AuditActionPackageUsageAssetInvalidated:           packageUsageAssetInvalidated,
+			constants.AuditActionPackageUsageExpiresAtUpdated:           packageUsageExpiresAtUpdated,
+			constants.AuditActionPackageUsageTrafficAdjusted:            packageUsageTrafficAdjusted,
+			constants.AuditActionOrderCreated:                           orderCreated,
+			constants.AuditActionOrderCancelled:                         orderCancelled,
+			constants.AuditActionOrderWalletPaid:                        orderWalletPaid,
+			constants.AuditActionOrderExpiredClosed:                     orderExpiredClosed,
+			constants.AuditActionOrderOnlinePaid:                        orderOnlinePaid,
+			constants.AuditActionAgentWalletOrderDebited:                agentWalletOrderDebited,
+			constants.AuditActionAgentWalletOrderReserved:               agentWalletOrderReserved,
+			constants.AuditActionAgentWalletOrderReleased:               agentWalletOrderReleased,
+			constants.AuditActionAgentWalletOrderCompleted:              agentWalletOrderCompleted,
+			constants.AuditActionAgentWalletBalanceAdjusted:             agentWalletBalanceAdjusted,
+			constants.AuditActionAgentWalletCreditChanged:               agentWalletCreditChanged,
+			constants.AuditActionPaymentCreated:                         paymentCreated,
+			constants.AuditActionPaymentConfirmed:                       paymentConfirmed,
+			constants.AuditActionPaymentFailed:                          paymentFailed,
+			constants.AuditActionIntegrationAttemptStarted:              integrationAttemptStarted,
+			constants.AuditActionIntegrationInboundReceived:             integrationInboundReceived,
+			constants.AuditActionAgentRechargeCreated:                   agentRechargeCreated,
+			constants.AuditActionAgentRechargeCredited:                  agentRechargeCredited,
+			constants.AuditActionAgentRechargeClosed:                    agentRechargeClosed,
+			constants.AuditActionAssetRechargeAutoPurchased:             assetRechargeAutoPurchased,
+			constants.AuditActionRefundCreated:                          refundCreated,
+			constants.AuditActionRefundApproved:                         refundApproved,
+			constants.AuditActionRefundRejected:                         refundRejected,
+			constants.AuditActionRefundReturned:                         refundReturned,
+			constants.AuditActionRefundResubmitted:                      refundResubmitted,
+			constants.AuditActionRefundCommissionInvalidated:            refundCommissionInvalidated,
+			constants.AuditActionRefundAssetProcessed:                   refundAssetProcessed,
+			constants.AuditActionApprovalRequested:                      approvalRequested,
+			constants.AuditActionApprovalSubmissionSynced:               approvalSubmissionSynced,
+			constants.AuditActionApprovalSubmissionRecovered:            approvalSubmissionRecovered,
+			constants.AuditActionApprovalDecisionSynced:                 approvalDecisionSynced,
+			constants.AuditActionCommissionCalculated:                   commissionCalculated,
+			constants.AuditActionCommissionCredited:                     commissionCredited,
+			constants.AuditActionCommissionInvalidated:                  commissionInvalidated,
+			constants.AuditActionCommissionWithdrawalRequested:          withdrawalRequested,
+			constants.AuditActionCommissionWithdrawalApproved:           withdrawalApproved,
+			constants.AuditActionCommissionWithdrawalRejected:           withdrawalRejected,
 		},
 		resources: map[string]ResourceDefinition{
 			constants.AuditResourceAccount: {
@@ -614,6 +637,25 @@ func NewRegistry() *Registry {
 				Type: constants.AuditResourceCarrier, Name: "运营商配置",
 				IdentityFields: []string{"id", "carrier_code", "carrier_name", "carrier_type", "status"},
 			},
+			constants.AuditResourceEmployeeCollectionPaymentMethod: {
+				Type: constants.AuditResourceEmployeeCollectionPaymentMethod, Name: "线下收款方式",
+				IdentityFields: []string{"id", "code", "name", "status", "sort"},
+			},
+			constants.AuditResourceEmployeeCollectionBill: {
+				Type: constants.AuditResourceEmployeeCollectionBill, Name: "员工代收款账单",
+				IdentityFields: []string{"id", "source_type", "source_id", "source_key", "debtor_account_id", "status"},
+			},
+			constants.AuditResourceEmployeeCollectionApplication: {
+				Type: constants.AuditResourceEmployeeCollectionApplication, Name: "员工代收款核销申请",
+				IdentityFields: []string{
+					"id", "applicant_account_id", "acting_operator_id", "payment_method_id",
+					"paid_amount", "status", "latest_approval_instance_id",
+				},
+			},
+			constants.AuditResourceEmployeeCollectionAttempt: {
+				Type: constants.AuditResourceEmployeeCollectionAttempt, Name: "员工代收款核销审批尝试记录",
+				IdentityFields: []string{"id", "application_id", "attempt_no", "paid_amount", "approval_instance_id"},
+			},
 			constants.AuditResourceWeComApprovalScene: {
 				Type: constants.AuditResourceWeComApprovalScene, Name: "企业微信审批场景配置",
 				IdentityFields: []string{"id", "business_type", "application_id", "template_id", "template_name", "status"},
@@ -1227,6 +1269,23 @@ func connectionConfigAction(code, name, resourceType, risk string) ActionDefinit
 	}
 }
 
+// employeeCollectionAction 定义员工代收款账单与核销申请动作；建账发生在来源成功事务内，
+// 订单来源由后台账号触发，充值入账与审批终态由 Outbox 消费、渠道回调或恢复任务触发。
+func employeeCollectionAction(code, name, primaryResource string) ActionDefinition {
+	return ActionDefinition{
+		Code: code, Name: name, Category: constants.AuditCategoryBusiness, Risk: constants.AuditRiskHigh,
+		PrimaryResource: primaryResource, RequireTransaction: true,
+		DefaultVisibility: constants.AuditSubjectResult,
+		AllowedVisibility: []string{constants.AuditSubjectInternalOnly, constants.AuditSubjectResult},
+		AllowedOrigins: []ActionOrigin{
+			{Actor: constants.AuditActorAccount, Source: constants.AuditSourceAdminAPI},
+			{Actor: constants.AuditActorSystemTask, Source: constants.AuditSourceWorker},
+			{Actor: constants.AuditActorExternalSystem, Source: constants.AuditSourceCallback},
+			{Actor: constants.AuditActorScheduledJob, Source: constants.AuditSourceScheduler},
+		},
+	}
+}
+
 // Action 返回已注册动作定义。
 func (r *Registry) Action(code string) (ActionDefinition, bool) {
 	if r == nil {

internal/infrastructure/audit/writer_check_test.go

@@ -1,82 +0,0 @@
-package audit
-
-import (
-	"context"
-	"encoding/json"
-	"testing"
-
-	"gorm.io/gorm"
-
-	accessauditapp "github.com/break/junhong_cmp_fiber/internal/application/accessaudit"
-	"github.com/break/junhong_cmp_fiber/internal/model"
-	"github.com/break/junhong_cmp_fiber/pkg/auditfailure"
-	"github.com/break/junhong_cmp_fiber/pkg/constants"
-)
-
-func TestAppendFailureDoesNotReturnToBusiness(t *testing.T) {
-	writer := NewWriter(nil, nil)
-	input := AppendInput{ActionCode: "missing_action"}
-	before := auditfailure.SecondaryWriteFailureCount()
-	if err := writer.Append(context.Background(), nil, input); err != nil {
-		t.Fatalf("Append 返回审计失败: %v", err)
-	}
-	if err := writer.WriteAccessChange(context.Background(), nil, accessauditapp.ChangeAudit{
-		ActionCode: constants.AuditActionPersonalCustomerAssetBound,
-		OperatorID: 1,
-	}); err != nil {
-		t.Fatalf("资源构造失败返回业务: %v", err)
-	}
-	if got := auditfailure.SecondaryWriteFailureCount(); got != before+2 {
-		t.Fatalf("二次失败记录次数 = %d, want %d", got, before+2)
-	}
-	if _, err := writer.AppendAndGet(context.Background(), nil, input); err == nil {
-		t.Fatal("AppendAndGet 未保留错误语义")
-	}
-}
-
-func TestPersonalCustomerAssetBoundProjectsOnlyPersonalResources(t *testing.T) {
-	action, ok := NewRegistry().Action(constants.AuditActionPersonalCustomerAssetBound)
-	if !ok {
-		t.Fatal("未注册个人客户资产绑定审计动作")
-	}
-	resources, err := accessResources(accessauditapp.ChangeAudit{
-		ActionCode:       constants.AuditActionPersonalCustomerAssetBound,
-		PersonalCustomer: &model.PersonalCustomer{Model: gorm.Model{ID: 1}, Nickname: "客户"},
-		PersonalDevices: []accessauditapp.PersonalCustomerDeviceChange{{
-			Binding: &model.PersonalCustomerDevice{Model: gorm.Model{ID: 2}, CustomerID: 1, VirtualNo: "DEVICE-1"},
-		}},
-		PersonalICCIDs: []accessauditapp.PersonalCustomerICCIDChange{{
-			Binding: &model.PersonalCustomerICCID{Model: gorm.Model{ID: 3}, CustomerID: 1, ICCID: "ICCID-1"},
-		}},
-		SubjectVisibility: constants.AuditSubjectDetail,
-		SubjectSummary:    "绑定个人客户资产",
-		SubjectData:       map[string]any{"asset_type": constants.AuditResourceIotCard, "asset_id": uint(9)},
-	}, action.PrimaryResource)
-	if err != nil {
-		t.Fatalf("构造绑定审计资源失败: %v", err)
-	}
-	projected, err := NewWriter(nil, nil).buildResources(resources, action)
-	if err != nil {
-		t.Fatalf("构造绑定审计投影失败: %v", err)
-	}
-	want := map[string]bool{
-		constants.AuditResourcePersonalCustomer:       true,
-		constants.AuditResourcePersonalCustomerDevice: true,
-		constants.AuditResourcePersonalCustomerICCID:  true,
-	}
-	for _, resource := range projected {
-		if resource.ResourceType == constants.AuditResourceIotCard || resource.ResourceType == constants.AuditResourceDevice {
-			t.Fatalf("绑定审计投影包含内部资源: %s", resource.ResourceType)
-		}
-		delete(want, resource.ResourceType)
-		if resource.ResourceType == constants.AuditResourcePersonalCustomer {
-			var subjectData map[string]any
-			if err := json.Unmarshal(resource.SubjectData, &subjectData); err != nil || resource.SubjectVisibility != constants.AuditSubjectDetail || subjectData["asset_type"] != constants.AuditResourceIotCard || subjectData["asset_id"] != float64(9) {
-				t.Fatalf("主个人客户主体投影不完整: %#v", resource)
-			}
-		}
-	}
-	for resourceType := range want {
-		t.Fatalf("绑定审计投影缺少合法资源: %s", resourceType)
-	}
-}

internal/infrastructure/integrationlog/repository.go

@@ -45,6 +45,7 @@ type Attempt struct {
 	CorrelationID    *string
 	AuditEventID     *uint
 	InitialResult    string
+	StateChanged     bool
 	RecoveryStrategy *string
 }
 
@@ -135,7 +136,7 @@ func (r *Repository) Start(ctx context.Context, input Attempt) (*model.Integrati
 		Operation: input.Operation, ExternalID: sanitizedOptionalText(input.ExternalID), ResourceType: resourceType,
 		ResourceID: input.ResourceID, ResourceKey: sanitizedOptionalText(input.ResourceKey), TriggerSource: input.TriggerSource,
 		TriggerScene: sanitizedOptionalText(input.TriggerScene), TriggerSeries: input.TriggerSeries, ScheduledAt: input.ScheduledAt,
-		StartedAt: input.StartedAt, Attempt: input.Attempt, Result: result,
+		StartedAt: input.StartedAt, Attempt: input.Attempt, Result: result, StateChanged: input.StateChanged,
 		RequestSummary: requestSummary, Metadata: metadata, RequestID: input.RequestID,
 		CorrelationID: input.CorrelationID, AuditEventID: input.AuditEventID,
 		RecoveryStrategy: sanitizedOptionalText(input.RecoveryStrategy),
@@ -416,8 +417,8 @@ func validateAttempt(input Attempt) error {
 	if input.Direction != constants.IntegrationDirectionInbound && input.Direction != constants.IntegrationDirectionOutbound {
 		return pkgerrors.New(pkgerrors.CodeInvalidParam, "Integration Log 方向无效")
 	}
-	if input.InitialResult != "" && input.InitialResult != constants.IntegrationResultPending && !isUnsentResult(input.InitialResult) {
-		return pkgerrors.New(pkgerrors.CodeInvalidParam, "Integration Log 初始结果只能是待处理或未发送终态")
+	if input.InitialResult != "" && input.InitialResult != constants.IntegrationResultPending && !isTerminalResult(input.InitialResult) {
+		return pkgerrors.New(pkgerrors.CodeInvalidParam, "Integration Log 初始结果无效")
 	}
 	if !validGeneratedString(input.IntegrationID, constants.IntegrationIDMaxLength) ||
 		!validOptionalString(input.TriggerSeries, constants.IntegrationTriggerSeriesMaxLength) ||

internal/infrastructure/payment/fuiou_scan.go

@@ -0,0 +1,172 @@
+package payment
+
+import (
+	"context"
+	"strconv"
+	"strings"
+	"time"
+
+	"go.uber.org/zap"
+
+	agentrecharge "github.com/break/junhong_cmp_fiber/internal/application/agentrecharge"
+	"github.com/break/junhong_cmp_fiber/internal/infrastructure/integrationlog"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	apperrors "github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/fuiou"
+)
+
+// FuiouScanAdapter 按富友主扫统一下单生成微信扫码支付链接并主动查单。
+type FuiouScanAdapter struct {
+	integration *integrationlog.Repository
+	logger      *zap.Logger
+}
+
+// NewFuiouScanAdapter 创建富友扫码支付适配器。
+func NewFuiouScanAdapter(integration *integrationlog.Repository, logger *zap.Logger) *FuiouScanAdapter {
+	return &FuiouScanAdapter{integration: integration, logger: logger}
+}
+
+// Available 判断富友主扫下单、验签与查单所需的配置是否完整。
+func (a *FuiouScanAdapter) Available(config *model.WechatConfig) bool {
+	return fuiouConfigComplete(config, true)
+}
+
+// CreatePaymentURL 调用富友主扫统一下单并返回二维码链接。
+func (a *FuiouScanAdapter) CreatePaymentURL(ctx context.Context, request agentrecharge.OnlinePaymentRequest) (agentrecharge.OnlinePaymentResult, error) {
+	attempt, err := a.startAttempt(ctx, request, constants.IntegrationOperationPaymentPreCreate, request.Config.ID, request.Amount)
+	if err != nil {
+		return agentrecharge.OnlinePaymentResult{}, err
+	}
+	startedAt := time.Now()
+	client, err := a.newClient(request.Config)
+	if err != nil {
+		return agentrecharge.OnlinePaymentResult{}, a.completeUnknown(ctx, attempt.IntegrationID, startedAt, err)
+	}
+	expireMinutes := int(time.Until(request.ExpireAt).Minutes())
+	if expireMinutes < 1 {
+		expireMinutes = 1
+	}
+	resp, callErr := client.PreCreate(
+		request.PaymentNo, strconv.FormatInt(request.Amount, 10), request.Description,
+		fuiou.GetServerIP(), fuiou.OrderTypeWechat, strconv.Itoa(expireMinutes),
+	)
+	if callErr != nil {
+		return agentrecharge.OnlinePaymentResult{}, a.completeUnknown(ctx, attempt.IntegrationID, startedAt, callErr)
+	}
+	if strings.TrimSpace(resp.QrCode) == "" {
+		return agentrecharge.OnlinePaymentResult{}, a.completeFailed(ctx, attempt.IntegrationID, startedAt, "empty_qr_code", "富友主扫下单未返回二维码链接")
+	}
+	if _, err = a.integration.Complete(ctx, attempt.IntegrationID, integrationlog.Completion{
+		Result: constants.IntegrationResultSuccess, ResponseSummary: map[string]any{"success": true},
+		DurationMS: time.Since(startedAt).Milliseconds(), StateChanged: true,
+	}); err != nil {
+		return agentrecharge.OnlinePaymentResult{}, err
+	}
+	return agentrecharge.OnlinePaymentResult{QRContent: resp.QrCode}, nil
+}
+
+// Query 调用富友订单查询并按 trans_stat 返回统一查询结果。
+func (a *FuiouScanAdapter) Query(ctx context.Context, request agentrecharge.OnlinePaymentRequest) (agentrecharge.OnlinePaymentQueryResult, error) {
+	attempt, err := a.startAttempt(ctx, request, constants.IntegrationOperationPaymentQuery, request.Config.ID, 0)
+	if err != nil {
+		return agentrecharge.OnlinePaymentQueryResult{}, err
+	}
+	startedAt := time.Now()
+	client, err := a.newClient(request.Config)
+	if err != nil {
+		return agentrecharge.OnlinePaymentQueryResult{}, a.completeUnknown(ctx, attempt.IntegrationID, startedAt, err)
+	}
+	resp, callErr := client.CommonQuery(request.PaymentNo, fuiou.OrderTypeWechat)
+	if callErr != nil {
+		return agentrecharge.OnlinePaymentQueryResult{}, a.completeUnknown(ctx, attempt.IntegrationID, startedAt, callErr)
+	}
+	result := agentrecharge.OnlinePaymentQueryResult{State: mapFuiouTransStat(resp.TransStat)}
+	if result.State == agentrecharge.OnlinePaymentStatePaid {
+		result.ThirdPartyTradeNo = strings.TrimSpace(resp.TransactionId)
+		result.Amount, _ = strconv.ParseInt(strings.TrimSpace(resp.OrderAmt), 10, 64)
+		if paidAt, ok := parseWechatPaidAt(strings.TrimSpace(resp.ReservedTxnFinTs)); ok {
+			result.PaidAt = &paidAt
+		}
+	}
+	providerCode := resp.TransStat
+	if strings.TrimSpace(providerCode) == "" {
+		providerCode = "unknown"
+	}
+	if _, err = a.integration.Complete(ctx, attempt.IntegrationID, integrationlog.Completion{
+		Result: constants.IntegrationResultSuccess, ProviderCode: providerCode,
+		ResponseSummary: map[string]any{"state": result.State, "has_trade_no": result.ThirdPartyTradeNo != ""},
+		DurationMS:      time.Since(startedAt).Milliseconds(),
+	}); err != nil {
+		return agentrecharge.OnlinePaymentQueryResult{}, err
+	}
+	return result, nil
+}
+
+func fuiouConfigComplete(config *model.WechatConfig, requireActive bool) bool {
+	return config != nil && (!requireActive || config.IsActive) && config.ProviderType == model.ProviderTypeFuiou &&
+		config.FyInsCd != "" && config.FyMchntCd != "" && config.FyTermID != "" &&
+		config.FyPrivateKey != "" && config.FyPublicKey != "" && config.FyAPIURL != "" && config.FyNotifyURL != ""
+}
+
+func (a *FuiouScanAdapter) newClient(config *model.WechatConfig) (*fuiou.Client, error) {
+	if !fuiouConfigComplete(config, false) {
+		return nil, apperrors.New(apperrors.CodeNoPaymentConfig, "富友扫码支付配置不可用")
+	}
+	return fuiou.NewClient(
+		config.FyInsCd, config.FyMchntCd, config.FyTermID, config.FyAPIURL, config.FyNotifyURL,
+		config.FyPrivateKey, config.FyPublicKey, a.logger,
+	)
+}
+
+func mapFuiouTransStat(transStat string) string {
+	switch transStat {
+	case "SUCCESS":
+		return agentrecharge.OnlinePaymentStatePaid
+	case "PAYERROR", "CLOSED", "REVOKED":
+		return agentrecharge.OnlinePaymentStateClosed
+	case "USERPAYING", "NOTPAY":
+		return agentrecharge.OnlinePaymentStatePending
+	default:
+		return agentrecharge.OnlinePaymentStateUnknown
+	}
+}
+
+func (a *FuiouScanAdapter) startAttempt(ctx context.Context, request agentrecharge.OnlinePaymentRequest, operation string, configID uint, amount int64) (*model.IntegrationLog, error) {
+	resourceID, resourceKey := strconv.FormatUint(uint64(request.PaymentID), 10), request.PaymentNo
+	series := "agent-recharge-payment:" + resourceID + ":" + operation
+	correlationID := request.CorrelationID
+	return a.integration.Start(ctx, integrationlog.Attempt{
+		Provider: constants.IntegrationProviderFuiou, Direction: constants.IntegrationDirectionOutbound,
+		Operation: operation, ResourceType: constants.IntegrationResourceTypeAgentRechargePayment,
+		ResourceID: &resourceID, ResourceKey: &resourceKey, ExternalID: &resourceKey,
+		TriggerSeries: &series, CorrelationID: &correlationID,
+		RequestSummary: map[string]any{"payment_config_id": configID, "amount": amount},
+	})
+}
+
+func (a *FuiouScanAdapter) completeUnknown(ctx context.Context, integrationID string, startedAt time.Time, cause error) error {
+	if a.logger != nil {
+		a.logger.Warn("富友支付请求结果未知", zap.String("integration_id", integrationID), zap.Error(cause))
+	}
+	_, err := a.integration.Complete(ctx, integrationID, integrationlog.Completion{
+		Result: constants.IntegrationResultUnknown, ProviderCode: "request_unknown", SafeProviderMessage: "富友支付请求结果未知",
+		ResponseSummary: map[string]any{"success": false}, DurationMS: time.Since(startedAt).Milliseconds(),
+		RecoveryStrategy: "使用原支付单号主动查单，确认不存在或关闭后才允许关闭本地支付单",
+	})
+	if err != nil {
+		return err
+	}
+	return apperrors.Wrap(apperrors.CodeTimeout, cause, "富友支付请求结果未知")
+}
+
+func (a *FuiouScanAdapter) completeFailed(ctx context.Context, integrationID string, startedAt time.Time, providerCode, providerMessage string) error {
+	_, err := a.integration.Complete(ctx, integrationID, integrationlog.Completion{
+		Result: constants.IntegrationResultFailed, ProviderCode: providerCode, SafeProviderMessage: providerMessage,
+		ResponseSummary: map[string]any{"success": false}, DurationMS: time.Since(startedAt).Milliseconds(),
+	})
+	if err != nil {
+		return err
+	}
+	return apperrors.New(apperrors.CodeServiceUnavailable, providerMessage)
+}

internal/model/agent_wallet.go

@@ -74,30 +74,35 @@ func (AgentWalletTransaction) TableName() string {
 // AgentRechargeRecord 代理充值记录模型
 // 记录所有代理充值操作
 type AgentRechargeRecord struct {
-	ID                   uint             `gorm:"column:id;primaryKey" json:"id"`
-	UserID               uint             `gorm:"column:user_id;not null;index;comment:操作人用户ID" json:"user_id"`
-	AgentWalletID        uint             `gorm:"column:agent_wallet_id;not null;comment:代理钱包ID" json:"agent_wallet_id"`
-	ShopID               uint             `gorm:"column:shop_id;not null;index;comment:店铺ID(冗余字段,便于查询)" json:"shop_id"`
-	RechargeNo           string           `gorm:"column:recharge_no;type:varchar(50);not null;uniqueIndex;comment:充值订单号(格式:ARCH+时间戳+随机数)" json:"recharge_no"`
-	Amount               int64            `gorm:"column:amount;type:bigint;not null;comment:充值金额(单位:分,最小1分)" json:"amount"`
-	PaymentMethod        string           `gorm:"column:payment_method;type:varchar(20);not null;comment:支付方式(alipay-支付宝 | wechat-微信 | bank-银行转账 | offline-线下)" json:"payment_method"`
-	PaymentChannel       *string          `gorm:"column:payment_channel;type:varchar(50);comment:支付渠道" json:"payment_channel,omitempty"`
-	PaymentTransactionID *string          `gorm:"column:payment_transaction_id;type:varchar(100);comment:第三方支付交易号" json:"payment_transaction_id,omitempty"`
-	PaymentConfigID      *uint            `gorm:"column:payment_config_id;index;comment:支付配置ID(关联tb_wechat_config.id)" json:"payment_config_id,omitempty"`
-	Status               int              `gorm:"column:status;type:int;not null;default:1;comment:充值状态(1-待支付 2-已支付 3-已完成 4-已关闭 5-已退款 6-已驳回)" json:"status"`
-	PaymentVoucherKey    StringJSONBArray `gorm:"column:payment_voucher_key;type:jsonb;comment:支付凭证对象存储Key列表（线下支付时必填，最多5个，微信支付时为空）" json:"payment_voucher_key"`
-	Remark               string           `gorm:"column:remark;type:text;comment:运营备注（创建时填写，不可修改）" json:"remark,omitempty"`
-	RejectionReason      *string          `gorm:"column:rejection_reason;type:varchar(500);comment:驳回原因，仅驳回时写入" json:"rejection_reason,omitempty"`
-	ApprovalInstanceID   *uint            `gorm:"column:approval_instance_id;comment:员工线下代充值关联的唯一通用审批实例ID" json:"approval_instance_id,omitempty"`
-	RequestID            *string          `gorm:"column:request_id;type:varchar(64);comment:提交账号提供的在线充值幂等请求标识" json:"request_id,omitempty"`
-	RequestFingerprint   *string          `gorm:"column:request_fingerprint;type:varchar(64);comment:在线充值请求业务字段指纹" json:"-"`
-	PaidAt               *time.Time       `gorm:"column:paid_at;comment:支付时间" json:"paid_at,omitempty"`
-	CompletedAt          *time.Time       `gorm:"column:completed_at;comment:完成时间" json:"completed_at,omitempty"`
-	ShopIDTag            uint             `gorm:"column:shop_id_tag;not null;index;comment:店铺ID标签(多租户过滤)" json:"shop_id_tag"`
-	EnterpriseIDTag      *uint            `gorm:"column:enterprise_id_tag;index;comment:企业ID标签(多租户过滤)" json:"enterprise_id_tag,omitempty"`
-	CreatedAt            time.Time        `gorm:"column:created_at;not null;default:CURRENT_TIMESTAMP" json:"created_at"`
-	UpdatedAt            time.Time        `gorm:"column:updated_at;not null;default:CURRENT_TIMESTAMP" json:"updated_at"`
-	DeletedAt            gorm.DeletedAt   `gorm:"column:deleted_at;index" json:"deleted_at,omitempty"`
+	ID                       uint             `gorm:"column:id;primaryKey" json:"id"`
+	UserID                   uint             `gorm:"column:user_id;not null;index;comment:操作人用户ID" json:"user_id"`
+	AgentWalletID            uint             `gorm:"column:agent_wallet_id;not null;comment:代理钱包ID" json:"agent_wallet_id"`
+	ShopID                   uint             `gorm:"column:shop_id;not null;index;comment:店铺ID(冗余字段,便于查询)" json:"shop_id"`
+	RechargeNo               string           `gorm:"column:recharge_no;type:varchar(50);not null;uniqueIndex;comment:充值订单号(格式:ARCH+时间戳+随机数)" json:"recharge_no"`
+	Amount                   int64            `gorm:"column:amount;type:bigint;not null;comment:充值金额(单位:分,最小1分)" json:"amount"`
+	PaymentMethod            string           `gorm:"column:payment_method;type:varchar(20);not null;comment:支付方式(alipay-支付宝 | wechat-微信 | bank-银行转账 | offline-线下)" json:"payment_method"`
+	PaymentChannel           *string          `gorm:"column:payment_channel;type:varchar(50);comment:支付渠道" json:"payment_channel,omitempty"`
+	PaymentTransactionID     *string          `gorm:"column:payment_transaction_id;type:varchar(100);comment:第三方支付交易号" json:"payment_transaction_id,omitempty"`
+	ExternalTransactionNo    *string          `gorm:"column:external_transaction_no;type:varchar(128);comment:线下充值交易流水号(人工确认，独立于在线渠道第三方交易号)" json:"external_transaction_no,omitempty"`
+	OfflinePaymentMethodID   *uint            `gorm:"column:offline_payment_method_id;index;comment:线下收款方式字典ID(关联tb_employee_collection_payment_method.id)" json:"offline_payment_method_id,omitempty"`
+	OfflinePaymentMethodCode *string          `gorm:"column:offline_payment_method_code;type:varchar(64);comment:线下收款方式稳定编码快照" json:"offline_payment_method_code,omitempty"`
+	OfflinePaymentMethodName *string          `gorm:"column:offline_payment_method_name;type:varchar(100);comment:线下收款方式名称快照" json:"offline_payment_method_name,omitempty"`
+	OtherVoucherKeys         StringJSONBArray `gorm:"column:other_voucher_keys;type:jsonb;comment:其他凭证对象存储Key列表(可选，最多5个)" json:"other_voucher_keys"`
+	PaymentConfigID          *uint            `gorm:"column:payment_config_id;index;comment:支付配置ID(关联tb_wechat_config.id)" json:"payment_config_id,omitempty"`
+	Status                   int              `gorm:"column:status;type:int;not null;default:1;comment:充值状态(1-待支付 2-已支付 3-已完成 4-已关闭 5-已退款 6-已驳回)" json:"status"`
+	PaymentVoucherKey        StringJSONBArray `gorm:"column:payment_voucher_key;type:jsonb;comment:支付凭证对象存储Key列表（线下支付时必填，最多5个，微信支付时为空）" json:"payment_voucher_key"`
+	Remark                   string           `gorm:"column:remark;type:text;comment:运营备注（创建时填写，不可修改）" json:"remark,omitempty"`
+	RejectionReason          *string          `gorm:"column:rejection_reason;type:varchar(500);comment:驳回原因，仅驳回时写入" json:"rejection_reason,omitempty"`
+	ApprovalInstanceID       *uint            `gorm:"column:approval_instance_id;comment:员工线下代充值关联的唯一通用审批实例ID" json:"approval_instance_id,omitempty"`
+	RequestID                *string          `gorm:"column:request_id;type:varchar(64);comment:提交账号提供的在线充值幂等请求标识" json:"request_id,omitempty"`
+	RequestFingerprint       *string          `gorm:"column:request_fingerprint;type:varchar(64);comment:在线充值请求业务字段指纹" json:"-"`
+	PaidAt                   *time.Time       `gorm:"column:paid_at;comment:支付时间" json:"paid_at,omitempty"`
+	CompletedAt              *time.Time       `gorm:"column:completed_at;comment:完成时间" json:"completed_at,omitempty"`
+	ShopIDTag                uint             `gorm:"column:shop_id_tag;not null;index;comment:店铺ID标签(多租户过滤)" json:"shop_id_tag"`
+	EnterpriseIDTag          *uint            `gorm:"column:enterprise_id_tag;index;comment:企业ID标签(多租户过滤)" json:"enterprise_id_tag,omitempty"`
+	CreatedAt                time.Time        `gorm:"column:created_at;not null;default:CURRENT_TIMESTAMP" json:"created_at"`
+	UpdatedAt                time.Time        `gorm:"column:updated_at;not null;default:CURRENT_TIMESTAMP" json:"updated_at"`
+	DeletedAt                gorm.DeletedAt   `gorm:"column:deleted_at;index" json:"deleted_at,omitempty"`
 }
 
 // TableName 指定表名

internal/model/dto/agent_recharge_dto.go

@@ -2,12 +2,15 @@ package dto
 
 // CreateAgentRechargeRequest 创建代理充值请求
 type CreateAgentRechargeRequest struct {
-	ShopID            *uint    `json:"shop_id,omitempty" description:"目标店铺ID，仅平台线下代充可填；代理在线充值禁止传入"`
-	Amount            int64    `json:"amount" validate:"required,min=1,max=100000000" required:"true" minimum:"1" maximum:"100000000" description:"充值金额（分），范围1分~100万元"`
-	PaymentMethod     string   `json:"payment_method" validate:"required,oneof=wechat alipay offline" required:"true" description:"支付方式 (wechat:微信在线支付, alipay:支付宝在线支付, offline:线下转账仅平台可用)"`
-	RequestID         string   `json:"request_id,omitempty" validate:"omitempty,max=64" maxLength:"64" description:"在线充值幂等请求标识，微信或支付宝支付时必填"`
-	PaymentVoucherKey []string `json:"payment_voucher_key" validate:"omitempty,max=5,dive,max=500" maxItems:"5" description:"支付凭证对象存储Key列表（payment_method=offline 时至少1个，最多5个，微信支付时忽略）"`
-	Remark            string   `json:"remark" validate:"omitempty,max=1000" maxLength:"1000" description:"运营备注（可选，创建后只读）"`
+	ShopID                 *uint    `json:"shop_id,omitempty" description:"目标店铺ID，仅平台线下代充可填；代理在线充值禁止传入"`
+	Amount                 int64    `json:"amount" validate:"required,min=1,max=100000000" required:"true" minimum:"1" maximum:"100000000" description:"充值金额（分），范围1分~100万元"`
+	PaymentMethod          string   `json:"payment_method" validate:"required,oneof=wechat alipay offline" required:"true" description:"支付方式 (wechat:微信在线支付, alipay:支付宝在线支付, offline:线下转账仅平台可用)"`
+	RequestID              string   `json:"request_id,omitempty" validate:"omitempty,max=64" maxLength:"64" description:"在线充值幂等请求标识，微信或支付宝支付时必填"`
+	PaymentVoucherKey      []string `json:"payment_voucher_key" validate:"omitempty,max=5,dive,max=500" maxItems:"5" description:"支付凭证对象存储Key列表（payment_method=offline 时至少1个，最多5个，在线支付时禁止传入）"`
+	OtherVoucherKey        []string `json:"other_voucher_key" validate:"omitempty,max=5,dive,max=500" maxItems:"5" description:"其他凭证对象存储Key列表（线下代充可选，最多5个，在线支付时禁止传入）"`
+	OfflinePaymentMethodID uint     `json:"offline_payment_method_id" description:"线下收款方式字典ID（payment_method=offline 时必填，须取自启用中的线下收款方式字典）"`
+	ExternalTransactionNo  string   `json:"external_transaction_no" validate:"omitempty,max=128" maxLength:"128" description:"交易流水号（payment_method=offline 时必填，由付款凭证识别预填并经人工确认；系统不做跨记录去重）"`
+	Remark                 string   `json:"remark" validate:"omitempty,max=1000" maxLength:"1000" description:"运营备注（可选，创建后只读）"`
 }
 
 // AgentRechargeOnlineResponse 代理在线扫码充值创建响应。
@@ -45,6 +48,29 @@ type AgentRechargePaymentStatusResponse struct {
 	CompletedAt        *string `json:"completed_at" description:"钱包入账完成时间"`
 }
 
+// AgentSelfRechargePaymentMethodsUpdateRequest 修改代理在线自充允许范围请求。
+// 枚举取值必须在 description 与 enum 标签两处与 pkg/constants 的 AgentSelfRechargeAllowed* 保持一致。
+type AgentSelfRechargePaymentMethodsUpdateRequest struct {
+	AllowedMethods string `json:"allowed_methods" validate:"required,oneof=wechat_only alipay_only both" required:"true" enum:"wechat_only,alipay_only,both" description:"允许范围 (wechat_only:仅微信, alipay_only:仅支付宝, both:同时支持微信和支付宝)"`
+}
+
+// AgentSelfRechargePaymentMethodsUpdateResponse 修改代理在线自充允许范围响应。
+type AgentSelfRechargePaymentMethodsUpdateResponse struct {
+	AllowedMethods     string `json:"allowed_methods" description:"允许范围 (wechat_only:仅微信, alipay_only:仅支付宝, both:同时支持微信和支付宝)"`
+	AllowedMethodsName string `json:"allowed_methods_name" description:"允许范围名称（中文）"`
+	UpdatedAt          string `json:"updated_at" description:"最近更新时间，带时区 RFC3339 格式"`
+}
+
+// AgentRechargePaymentVoucherOCRRequest 付款凭证识别请求。
+type AgentRechargePaymentVoucherOCRRequest struct {
+	PaymentVoucherKey string `json:"payment_voucher_key" validate:"required,min=1,max=500" required:"true" minLength:"1" maxLength:"500" description:"付款凭证对象存储Key，必须指向已上传的图片类型附件"`
+}
+
+// AgentRechargePaymentVoucherOCRResponse 付款凭证识别响应，只返回交易流水号预填值。
+type AgentRechargePaymentVoucherOCRResponse struct {
+	ExternalTransactionNo string `json:"external_transaction_no" description:"识别出的交易流水号预填值，必须经人工确认或更正后提交；金额、备注、付款人、支付方式与支付时间一律不返回"`
+}
+
 // AgentOfflinePayRequest 代理线下充值确认请求
 type AgentOfflinePayRequest struct {
 	OperationPassword string `json:"operation_password" validate:"required" required:"true" description:"操作密码"`
@@ -58,33 +84,39 @@ type AgentOfflinePayParams struct {
 
 // AgentRechargeResponse 代理充值记录响应
 type AgentRechargeResponse struct {
-	ID                   uint     `json:"id" description:"充值记录ID"`
-	RechargeNo           string   `json:"recharge_no" description:"充值单号(ARCH前缀)"`
-	ShopID               uint     `json:"shop_id" description:"店铺ID"`
-	ShopName             string   `json:"shop_name" description:"店铺名称"`
-	AgentWalletID        uint     `json:"agent_wallet_id" description:"代理钱包ID"`
-	Amount               int64    `json:"amount" description:"充值金额（分）"`
-	PaymentMethod        string   `json:"payment_method" description:"支付方式 (wechat:微信在线支付, alipay:支付宝在线支付, offline:线下转账)"`
-	RechargeSource       string   `json:"recharge_source" description:"充值来源 (platform_offline:平台线下代充, agent_online:代理在线自充)"`
-	RechargeSourceName   string   `json:"recharge_source_name" description:"充值来源名称（中文）"`
-	PaymentChannel       string   `json:"payment_channel" description:"实际支付通道 (wechat_direct:微信直连, fuyou:富友, offline:线下转账)"`
-	PaymentConfigID      *uint    `json:"payment_config_id" description:"关联支付配置ID，线下充值为null"`
-	PaymentTransactionID string   `json:"payment_transaction_id" description:"第三方支付流水号"`
-	PaymentVoucherKey    []string `json:"payment_voucher_key" description:"支付凭证对象存储Key列表（线下支付时存在，最多5个）"`
-	Remark               string   `json:"remark,omitempty" description:"运营备注"`
-	Status               int      `json:"status" description:"状态 (1:待支付, 2:已支付, 3:已完成, 4:已关闭, 5:已退款, 6:已驳回)"`
-	StatusName           string   `json:"status_name" description:"状态名称（中文）"`
-	RejectionReason      *string  `json:"rejection_reason,omitempty" description:"驳回原因，仅 status=6 时有值"`
-	SubmitterID          uint     `json:"submitter_id" description:"提交人账号ID"`
-	SubmitterName        string   `json:"submitter_name" description:"提交人账号名称"`
-	ApprovalInstanceID   *uint    `json:"approval_instance_id,omitempty" description:"通用审批实例ID，在线充值为null"`
-	ApprovalProvider     string   `json:"approval_provider,omitempty" description:"审批渠道，企微审批为wecom"`
-	ApprovalStatus       *int     `json:"approval_status,omitempty" description:"审批状态 (0:提交中, 1:审批中, 2:已通过, 3:已拒绝, 4:已撤销, 5:通过后撤销, 6:已删除, 7:提交失败, 8:提交结果未知)"`
-	ApprovalStatusName   string   `json:"approval_status_name,omitempty" description:"审批状态名称（中文）"`
-	PaidAt               *string  `json:"paid_at" description:"支付时间"`
-	CompletedAt          *string  `json:"completed_at" description:"完成时间"`
-	CreatedAt            string   `json:"created_at" description:"创建时间"`
-	UpdatedAt            string   `json:"updated_at" description:"更新时间"`
+	ID                   uint   `json:"id" description:"充值记录ID"`
+	RechargeNo           string `json:"recharge_no" description:"充值单号(ARCH前缀)"`
+	ShopID               uint   `json:"shop_id" description:"店铺ID"`
+	ShopName             string `json:"shop_name" description:"店铺名称"`
+	AgentWalletID        uint   `json:"agent_wallet_id" description:"代理钱包ID"`
+	Amount               int64  `json:"amount" description:"充值金额（分）"`
+	PaymentMethod        string `json:"payment_method" description:"支付方式 (wechat:微信在线支付, alipay:支付宝在线支付, offline:线下转账)"`
+	RechargeSource       string `json:"recharge_source" description:"充值来源 (platform_offline:平台线下代充, agent_online:代理在线自充)"`
+	RechargeSourceName   string `json:"recharge_source_name" description:"充值来源名称（中文）"`
+	PaymentChannel       string `json:"payment_channel" description:"实际支付通道 (wechat_direct:微信直连, fuyou:富友, offline:线下转账)"`
+	PaymentConfigID      *uint  `json:"payment_config_id" description:"关联支付配置ID，线下充值为null"`
+	PaymentTransactionID string `json:"payment_transaction_id" description:"第三方支付流水号（在线渠道权威值，仅在线支付有值）"`
+	// ExternalTransactionNo 是线下充值人工确认的交易流水号，独立于在线渠道第三方交易号。
+	ExternalTransactionNo    string   `json:"external_transaction_no" description:"交易流水号（线下充值人工确认值，独立于在线渠道第三方交易号）"`
+	OfflinePaymentMethodID   uint     `json:"offline_payment_method_id,omitempty" description:"线下收款方式字典ID，仅线下充值有值"`
+	OfflinePaymentMethodCode string   `json:"offline_payment_method_code,omitempty" description:"线下收款方式稳定编码快照，仅线下充值有值"`
+	OfflinePaymentMethodName string   `json:"offline_payment_method_name,omitempty" description:"线下收款方式名称快照，仅线下充值有值"`
+	OtherVoucherKey          []string `json:"other_voucher_key" description:"其他凭证对象存储Key列表，仅线下充值有值；不返回凭证内容"`
+	PaymentVoucherKey        []string `json:"payment_voucher_key" description:"支付凭证对象存储Key列表（线下支付时存在，最多5个）"`
+	Remark                   string   `json:"remark,omitempty" description:"运营备注"`
+	Status                   int      `json:"status" description:"状态 (1:待支付, 2:已支付, 3:已完成, 4:已关闭, 5:已退款, 6:已驳回)"`
+	StatusName               string   `json:"status_name" description:"状态名称（中文）"`
+	RejectionReason          *string  `json:"rejection_reason,omitempty" description:"驳回原因，仅 status=6 时有值"`
+	SubmitterID              uint     `json:"submitter_id" description:"提交人账号ID"`
+	SubmitterName            string   `json:"submitter_name" description:"提交人账号名称"`
+	ApprovalInstanceID       *uint    `json:"approval_instance_id,omitempty" description:"通用审批实例ID，在线充值为null"`
+	ApprovalProvider         string   `json:"approval_provider,omitempty" description:"审批渠道，企微审批为wecom"`
+	ApprovalStatus           *int     `json:"approval_status,omitempty" description:"审批状态 (0:提交中, 1:审批中, 2:已通过, 3:已拒绝, 4:已撤销, 5:通过后撤销, 6:已删除, 7:提交失败, 8:提交结果未知)"`
+	ApprovalStatusName       string   `json:"approval_status_name,omitempty" description:"审批状态名称（中文）"`
+	PaidAt                   *string  `json:"paid_at" description:"支付时间"`
+	CompletedAt              *string  `json:"completed_at" description:"完成时间"`
+	CreatedAt                string   `json:"created_at" description:"创建时间"`
+	UpdatedAt                string   `json:"updated_at" description:"更新时间"`
 }
 
 // AgentRechargeRejectRequest 驳回代理充值订单请求

internal/model/dto/asset_dto.go

@@ -160,12 +160,45 @@ type AssetPackageResponse struct {
 	CreatedAt         time.Time  `json:"created_at" description:"创建时间"`
 }
 
-// AssetPackagesResult 套餐列表分页结果
+// AssetPackageHistoryNode 后台资产套餐历史层级节点。
+type AssetPackageHistoryNode struct {
+	PackageUsageID         uint                       `json:"package_usage_id" description:"套餐使用记录ID"`
+	PackageID              uint                       `json:"package_id" description:"套餐ID"`
+	PackageName            string                     `json:"package_name" description:"套餐名称"`
+	PackageType            string                     `json:"package_type" description:"套餐类型：formal/addon"`
+	ExpiryBase             string                     `json:"expiry_base,omitempty" description:"到期时间基准"`
+	OrderID                uint                       `json:"order_id" description:"关联订单ID（无订单分配时为0）"`
+	OrderNo                string                     `json:"order_no,omitempty" description:"订单号快照"`
+	RefundID               *uint                      `json:"refund_id,omitempty" description:"退款主键ID快照"`
+	RefundNo               string                     `json:"refund_no,omitempty" description:"退款单号快照"`
+	UsageType              string                     `json:"usage_type" description:"使用类型：single_card/device"`
+	Status                 int                        `json:"status" description:"状态：0待生效 1生效中 2已用完 3已过期 4已失效"`
+	StatusName             string                     `json:"status_name" description:"状态名称"`
+	RealTotalMB            int64                      `json:"real_total_mb" description:"套餐真实总量(MB)"`
+	RealUsedMB             int64                      `json:"real_used_mb" description:"套餐真实已用量(MB)"`
+	VirtualTotalMB         int64                      `json:"virtual_total_mb" description:"套餐业务停机阈值(MB)"`
+	VirtualUsedMB          float64                    `json:"virtual_used_mb" description:"套餐展示已用量(MB)"`
+	ReductionPct           float64                    `json:"reduction_pct" description:"展示增幅比例"`
+	EnableVirtualData      bool                       `json:"enable_virtual_data" description:"是否启用虚流量"`
+	ActivatedAt            *time.Time                 `json:"activated_at,omitempty" description:"激活时间"`
+	ExpiresAt              *time.Time                 `json:"expires_at,omitempty" description:"到期时间"`
+	MasterUsageID          *uint                      `json:"master_usage_id" description:"主套餐使用记录ID；普通主项为null"`
+	Priority               int                        `json:"priority" description:"优先级"`
+	PaidAmount             *int64                     `json:"paid_amount,omitempty" description:"购买成本价（分），仅平台账号可见"`
+	RetailAmount           *int64                     `json:"retail_amount,omitempty" description:"购买零售价（分）"`
+	CreatedAt              time.Time                  `json:"created_at" description:"购买创建时间"`
+	Children               []*AssetPackageHistoryNode `json:"children" nullable:"false" description:"关联加油包"`
+	ExpandByDefault        bool                       `json:"expand_by_default" description:"是否默认展开关联加油包"`
+	RelationshipStatus     string                     `json:"relationship_status,omitempty" description:"关系异常状态：master_missing"`
+	RelationshipStatusName string                     `json:"relationship_status_name,omitempty" description:"关系异常状态名称"`
+}
+
+// AssetPackagesResult 后台资产套餐历史分页结果。
 type AssetPackagesResult struct {
-	Total    int64                   `json:"total" description:"总条数"`
-	Page     int                     `json:"page" description:"当前页码"`
-	PageSize int                     `json:"page_size" description:"每页条数"`
-	Items    []*AssetPackageResponse `json:"items" description:"套餐列表"`
+	Total    int64                      `json:"total" description:"筛选后的顶层关系组总数"`
+	Page     int                        `json:"page" description:"当前页码"`
+	PageSize int                        `json:"page_size" description:"每页顶层关系组数量"`
+	Items    []*AssetPackageHistoryNode `json:"items" nullable:"false" description:"套餐历史层级列表"`
 }
 
 // AssetResolveRequest 资产解析请求

internal/model/dto/client_asset_dto.go

@@ -183,12 +183,39 @@ type AssetPackageHistoryRequest struct {
 	PageSize    int     `json:"page_size" query:"page_size" validate:"required,min=1,max=100" required:"true" minimum:"1" maximum:"100" description:"每页数量"`
 }
 
-// AssetPackageHistoryResponse B3 资产套餐历史响应
+// ClientAssetPackageHistoryNode H5 资产套餐历史层级节点。
+type ClientAssetPackageHistoryNode struct {
+	PackageUsageID         uint                             `json:"package_usage_id" description:"套餐使用记录ID"`
+	PackageID              uint                             `json:"package_id" description:"套餐ID"`
+	PackageName            string                           `json:"package_name" description:"套餐名称"`
+	OrderID                uint                             `json:"order_id" description:"历史兼容字段；本接口不填充真实订单ID，零值仍输出为0"`
+	PackageType            string                           `json:"package_type" description:"套餐类型：formal/addon"`
+	UsageType              string                           `json:"usage_type" description:"使用类型：single_card/device"`
+	Status                 int                              `json:"status" description:"状态：0待生效 1生效中 2已用完 3已过期 4已失效"`
+	StatusName             string                           `json:"status_name" description:"状态名称"`
+	RealTotalMB            int64                            `json:"real_total_mb" description:"套餐真实总量(MB)"`
+	RealUsedMB             int64                            `json:"real_used_mb" description:"套餐真实已用量(MB)"`
+	VirtualTotalMB         int64                            `json:"virtual_total_mb" description:"套餐业务停机阈值(MB)"`
+	VirtualUsedMB          float64                          `json:"virtual_used_mb" description:"套餐展示已用量(MB)"`
+	ReductionPct           float64                          `json:"reduction_pct" description:"展示增幅比例"`
+	EnableVirtualData      bool                             `json:"enable_virtual_data" description:"是否启用虚流量"`
+	ActivatedAt            *time.Time                       `json:"activated_at,omitempty" description:"激活时间"`
+	ExpiresAt              *time.Time                       `json:"expires_at,omitempty" description:"到期时间"`
+	MasterUsageID          *uint                            `json:"master_usage_id" description:"主套餐使用记录ID；普通主项为null"`
+	Priority               int                              `json:"priority" description:"优先级"`
+	CreatedAt              time.Time                        `json:"created_at" description:"购买创建时间"`
+	Children               []*ClientAssetPackageHistoryNode `json:"children" nullable:"false" description:"关联加油包"`
+	ExpandByDefault        bool                             `json:"expand_by_default" description:"是否默认展开关联加油包"`
+	RelationshipStatus     string                           `json:"relationship_status,omitempty" description:"关系异常状态：master_missing"`
+	RelationshipStatusName string                           `json:"relationship_status_name,omitempty" description:"关系异常状态名称"`
+}
+
+// AssetPackageHistoryResponse B3 资产套餐历史层级响应。
 type AssetPackageHistoryResponse struct {
-	List     []AssetPackageResponse `json:"items" description:"套餐历史列表"`
-	Total    int64                  `json:"total" description:"总数"`
-	Page     int                    `json:"page" description:"页码"`
-	PageSize int                    `json:"size" description:"每页数量"`
+	List     []*ClientAssetPackageHistoryNode `json:"items" nullable:"false" description:"套餐历史层级列表"`
+	Total    int64                            `json:"total" description:"筛选后的顶层关系组总数"`
+	Page     int                              `json:"page" description:"页码"`
+	PageSize int                              `json:"size" description:"每页顶层关系组数量"`
 }
 
 // ========================================

internal/model/dto/employee_collection_dto.go

@@ -0,0 +1,305 @@
+package dto
+
+import "time"
+
+// CreateEmployeeCollectionPaymentMethodRequest 创建线下收款方式请求
+// 枚举说明：enabled 对应 constants.EmployeeCollectionPaymentMethodStatusEnabled/Disabled（1 启用、0 停用）。
+type CreateEmployeeCollectionPaymentMethodRequest struct {
+	Code    string `json:"code" validate:"required,min=1,max=64" required:"true" minLength:"1" maxLength:"64" description:"收款方式稳定编码，1-64 字符，未删除记录中唯一，被核销申请引用后不可修改"`
+	Name    string `json:"name" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"收款方式名称，1-100 字符"`
+	Sort    *int64 `json:"sort" validate:"omitempty,min=0" minimum:"0" description:"排序值，非负整数，默认 0"`
+	Enabled *bool  `json:"enabled" description:"是否启用，默认启用；停用后新核销申请不可选择该方式"`
+	Remark  string `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"备注，最多 500 字符"`
+}
+
+// UpdateEmployeeCollectionPaymentMethodRequest 更新线下收款方式请求
+// 全部字段可选：仅传入的字段被修改；已启用即被核销申请引用的记录不允许修改稳定编码。
+type UpdateEmployeeCollectionPaymentMethodRequest struct {
+	Code    *string `json:"code" validate:"omitempty,min=1,max=64" minLength:"1" maxLength:"64" description:"收款方式稳定编码，仅未被核销申请引用时可修改"`
+	Name    *string `json:"name" validate:"omitempty,min=1,max=100" minLength:"1" maxLength:"100" description:"收款方式名称"`
+	Sort    *int64  `json:"sort" validate:"omitempty,min=0" minimum:"0" description:"排序值，非负整数"`
+	Enabled *bool   `json:"enabled" description:"是否启用；停用后新核销申请不可选择该方式，历史申请仍展示冻结名称"`
+	Remark  *string `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"备注，最多 500 字符"`
+}
+
+// EmployeeCollectionPaymentMethodListRequest 查询线下收款方式列表请求
+type EmployeeCollectionPaymentMethodListRequest struct {
+	Page     int    `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码，默认1"`
+	PageSize int    `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页条数，默认20，最大100"`
+	Enabled  *bool  `json:"enabled" query:"enabled" description:"按启用状态过滤；超级管理员可查询全部，其他后台账号仅返回启用项"`
+	Keyword  string `json:"keyword" query:"keyword" validate:"omitempty,max=100" maxLength:"100" description:"按稳定编码或名称模糊搜索，最多 100 字符"`
+}
+
+// EmployeeCollectionPaymentMethodResponse 线下收款方式响应
+// 对外契约字段固定为 id/code/name/enabled，其余字段为维护与展示补充。
+type EmployeeCollectionPaymentMethodResponse struct {
+	ID        uint      `json:"id" description:"收款方式ID"`
+	Code      string    `json:"code" description:"收款方式稳定编码"`
+	Name      string    `json:"name" description:"收款方式名称"`
+	Enabled   bool      `json:"enabled" description:"是否启用；停用后新核销申请不可选择该方式"`
+	Sort      int64     `json:"sort" description:"排序值"`
+	Remark    string    `json:"remark" description:"备注"`
+	CreatedAt time.Time `json:"created_at" description:"创建时间"`
+	UpdatedAt time.Time `json:"updated_at" description:"更新时间"`
+}
+
+// EmployeeCollectionPaymentMethodListResponse 线下收款方式列表响应
+type EmployeeCollectionPaymentMethodListResponse struct {
+	List     []*EmployeeCollectionPaymentMethodResponse `json:"items" description:"收款方式列表"`
+	Total    int64                                      `json:"total" description:"总数"`
+	Page     int                                        `json:"page" description:"当前页码"`
+	PageSize int                                        `json:"size" description:"每页条数"`
+}
+
+// EmployeeCollectionBillListRequest 查询员工代收款账单列表请求。
+// 枚举说明：source_type 对应 constants.EmployeeCollectionSourceTypeOrder/Recharge，
+// status 对应 constants.EmployeeCollectionBillStatusPending/Partial/Settled/Closed。
+type EmployeeCollectionBillListRequest struct {
+	Page            int     `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码，默认1"`
+	PageSize        int     `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页条数，默认20，最大100"`
+	SourceType      *string `json:"source_type" query:"source_type" validate:"omitempty,oneof=order recharge" enum:"order,recharge" description:"按来源类型过滤 (order:后台线下套餐订单, recharge:代理线下充值)"`
+	SourceNo        *string `json:"source_no" query:"source_no" validate:"omitempty,max=64" maxLength:"64" description:"按来源单号精确过滤"`
+	Status          *int    `json:"status" query:"status" validate:"omitempty,oneof=0 1 2 3" enum:"0,1,2,3" description:"按账单状态过滤 (0:待核销, 1:部分核销, 2:已核销, 3:已关闭)"`
+	DebtorAccountID *uint   `json:"debtor_account_id" query:"debtor_account_id" description:"按欠款人后台账号ID过滤；非超级管理员固定为当前账号，该参数被忽略"`
+	CustomerID      *uint   `json:"customer_id" query:"customer_id" description:"按来源客户或店铺ID过滤，匹配来源订单买家或充值归属店铺"`
+	CreatedFrom     *string `json:"created_from" query:"created_from" description:"创建时间起始（YYYY-MM-DD，含当日 00:00:00）"`
+	CreatedTo       *string `json:"created_to" query:"created_to" description:"创建时间截止（YYYY-MM-DD，含当日 23:59:59）"`
+}
+
+// EmployeeCollectionBillStatisticsRequest 查询员工代收款账单统计请求。
+// 与账单列表使用同一批筛选字段与可见性范围，但不接受分页参数。
+type EmployeeCollectionBillStatisticsRequest struct {
+	SourceType      *string `json:"source_type" query:"source_type" validate:"omitempty,oneof=order recharge" enum:"order,recharge" description:"按来源类型过滤 (order:后台线下套餐订单, recharge:代理线下充值)"`
+	SourceNo        *string `json:"source_no" query:"source_no" validate:"omitempty,max=64" maxLength:"64" description:"按来源单号精确过滤"`
+	Status          *int    `json:"status" query:"status" validate:"omitempty,oneof=0 1 2 3" enum:"0,1,2,3" description:"按账单状态过滤 (0:待核销, 1:部分核销, 2:已核销, 3:已关闭)"`
+	DebtorAccountID *uint   `json:"debtor_account_id" query:"debtor_account_id" description:"按欠款人后台账号ID过滤；非超级管理员固定为当前账号，该参数被忽略"`
+	CustomerID      *uint   `json:"customer_id" query:"customer_id" description:"按来源客户或店铺ID过滤，匹配来源订单买家或充值归属店铺"`
+	CreatedFrom     *string `json:"created_from" query:"created_from" description:"创建时间起始（YYYY-MM-DD，含当日 00:00:00）"`
+	CreatedTo       *string `json:"created_to" query:"created_to" description:"创建时间截止（YYYY-MM-DD，含当日 23:59:59）"`
+}
+
+// EmployeeCollectionBillResponse 员工代收款账单行响应。
+type EmployeeCollectionBillResponse struct {
+	ID               uint           `json:"id" description:"账单ID"`
+	SourceType       string         `json:"source_type" description:"来源类型 (order:后台线下套餐订单, recharge:代理线下充值)"`
+	SourceTypeName   string         `json:"source_type_name" description:"来源类型中文名称"`
+	SourceID         uint           `json:"source_id" description:"来源业务主键ID"`
+	SourceNo         string         `json:"source_no" description:"来源单号"`
+	DebtorAccountID  uint           `json:"debtor_account_id" description:"欠款人后台账号ID"`
+	DebtorSnapshot   map[string]any `json:"debtor_snapshot" description:"欠款人账号只读快照（账号ID、名称、类型）"`
+	CustomerSnapshot map[string]any `json:"customer_snapshot" description:"来源客户或店铺只读快照，不含付款凭证内容"`
+	ReceivableAmount int64          `json:"receivable_amount" description:"应收金额（分）"`
+	ReceivedAmount   int64          `json:"received_amount" description:"已核销金额（分），仅企业微信最终通过的分摊计入"`
+	ReservedAmount   int64          `json:"reserved_amount" description:"审批中预占金额（分）"`
+	RemainingAmount  int64          `json:"remaining_amount" description:"剩余可核销金额（分），已关闭账单为 0"`
+	Status           int            `json:"status" description:"账单状态 (0:待核销, 1:部分核销, 2:已核销, 3:已关闭)"`
+	StatusName       string         `json:"status_name" description:"账单状态中文名称"`
+	ApprovalPending  bool           `json:"approval_pending" description:"是否存在审批中分摊（预占大于零）"`
+	ClosedReason     string         `json:"closed_reason" description:"关闭原因，仅已关闭账单有值"`
+	ClosedAt         *time.Time     `json:"closed_at,omitempty" description:"关闭时间"`
+	CreatedAt        time.Time      `json:"created_at" description:"创建时间"`
+	UpdatedAt        time.Time      `json:"updated_at" description:"最近更新时间"`
+}
+
+// EmployeeCollectionBillListResponse 员工代收款账单列表响应。
+type EmployeeCollectionBillListResponse struct {
+	List     []*EmployeeCollectionBillResponse `json:"items" description:"账单列表"`
+	Total    int64                             `json:"total" description:"总数"`
+	Page     int                               `json:"page" description:"当前页码"`
+	PageSize int                               `json:"size" description:"每页条数"`
+}
+
+// EmployeeCollectionBillStatisticsResponse 员工代收款账单统计响应。
+// 与账单列表使用同一筛选条件与可见性范围。
+type EmployeeCollectionBillStatisticsResponse struct {
+	ReceivableTotal  int64 `json:"receivable_total" description:"应收金额合计（分）"`
+	ReceivedTotal    int64 `json:"received_total" description:"已核销金额合计（分）"`
+	UnsettledTotal   int64 `json:"unsettled_total" description:"未核销金额合计（分），已关闭账单未核销余额按 0 计入"`
+	PendingBillCount int64 `json:"pending_bill_count" description:"待处理账单数，即待核销或部分核销账单数量"`
+}
+
+// EmployeeCollectionBillRefundResponse 账单退款冲销关联响应。
+type EmployeeCollectionBillRefundResponse struct {
+	ID                   uint      `json:"id" description:"冲销关联ID"`
+	RefundID             uint      `json:"refund_id" description:"退款申请ID"`
+	SourceOrderID        uint      `json:"source_order_id" description:"账单来源订单ID"`
+	RefundAmount         int64     `json:"refund_amount" description:"本次退款成功金额（分）"`
+	BillReceivableAmount int64     `json:"bill_receivable_amount" description:"冲销前账单应收金额快照（分）"`
+	Outcome              string    `json:"outcome" description:"处理结果 (closed_full:来源订单全额退款关闭, reduced:按退款金额冲减应收, hint_only:仅记录退款关联提示)"`
+	OutcomeName          string    `json:"outcome_name" description:"处理结果中文名称"`
+	ReducedAmount        int64     `json:"reduced_amount" description:"实际冲减应收金额（分）"`
+	CreatedAt            time.Time `json:"created_at" description:"创建时间"`
+}
+
+// EmployeeCollectionBillAllocationResponse 账单分摊响应。
+type EmployeeCollectionBillAllocationResponse struct {
+	ID                    uint       `json:"id" description:"分摊ID"`
+	ApplicationID         uint       `json:"application_id" description:"核销申请ID"`
+	ApplicationStatus     int        `json:"application_status" description:"申请状态 (0:审批中, 1:已通过, 2:已驳回, 3:已撤销或已关闭)"`
+	ApplicationStatusName string     `json:"application_status_name" description:"申请状态中文名称"`
+	AttemptID             uint       `json:"attempt_id" description:"所属审批尝试记录ID"`
+	Amount                int64      `json:"amount" description:"本次分摊金额（分）"`
+	Status                int        `json:"status" description:"分摊状态 (0:审批中预占, 1:已通过, 2:已驳回或已释放)"`
+	StatusName            string     `json:"status_name" description:"分摊状态中文名称"`
+	ReleasedAt            *time.Time `json:"released_at,omitempty" description:"预占释放时间，审批中为空"`
+	CreatedAt             time.Time  `json:"created_at" description:"创建时间"`
+}
+
+// EmployeeCollectionBillAttemptResponse 申请审批尝试记录响应，材料为本次提交的冻结快照。
+type EmployeeCollectionBillAttemptResponse struct {
+	ID                    uint             `json:"id" description:"审批尝试记录ID，同时是通用审批业务ID"`
+	AttemptNo             int              `json:"attempt_no" description:"第几次提交，从 1 递增"`
+	PaymentMethodID       uint             `json:"payment_method_id" description:"本次冻结的收款方式字典ID"`
+	PaymentMethodCode     string           `json:"payment_method_code" description:"本次冻结的收款方式稳定编码"`
+	PaymentMethodName     string           `json:"payment_method_name" description:"本次冻结的收款方式名称"`
+	PaidAmount            int64            `json:"paid_amount" description:"本次冻结的付款金额（分）"`
+	PayerName             string           `json:"payer_name" description:"付款方名称"`
+	PaidAt                time.Time        `json:"paid_at" description:"付款时间"`
+	ExternalTransactionNo string           `json:"external_transaction_no" description:"人工确认的外部交易流水号，申请人可原样核对与重用"`
+	PaymentVoucherKeys    []string         `json:"payment_voucher_keys" description:"支付凭证对象存储Key列表，仅返回对象键引用"`
+	Remark                string           `json:"remark" description:"本次提交备注"`
+	SubmittedByAccountID  uint             `json:"submitted_by_account_id" description:"本次实际提交账号ID，代办时为超级管理员"`
+	ActingReason          string           `json:"acting_reason" description:"本次代办原因，非代办为空"`
+	AllocationSnapshot    []map[string]any `json:"allocation_snapshot" description:"本次冻结的账单分摊快照"`
+	ApprovalInstanceID    *uint            `json:"approval_instance_id,omitempty" description:"本次尝试关联的通用审批实例ID"`
+	ApprovalStatus        *int             `json:"approval_status,omitempty" description:"通用审批实例状态 (0:提交中, 1:审批中, 2:已通过, 3:已拒绝, 4:已撤销, 5:通过后撤销, 6:已删除, 7:提交失败, 8:提交结果未知)"`
+	ApprovalStatusName    string           `json:"approval_status_name" description:"通用审批实例状态中文名称"`
+	ApprovalOpinion       string           `json:"approval_opinion" description:"渠道审批意见文本，取自通用审批实例终态决策快照；无意见时为空"`
+	CreatedAt             time.Time        `json:"created_at" description:"创建时间"`
+}
+
+// EmployeeCollectionBillApplicationResponse 账单关联的核销申请响应，含审批历史。
+type EmployeeCollectionBillApplicationResponse struct {
+	ID                       uint                                     `json:"id" description:"核销申请ID"`
+	ApplicantAccountID       uint                                     `json:"applicant_account_id" description:"申请人后台账号ID"`
+	ActingOperatorID         uint                                     `json:"acting_operator_id" description:"实际代办的超级管理员账号ID，0 表示本人办理"`
+	ActingReason             string                                   `json:"acting_reason" description:"代办原因，非代办为空"`
+	PaymentMethodID          uint                                     `json:"payment_method_id" description:"线下收款方式字典ID"`
+	PaymentMethodCode        string                                   `json:"payment_method_code" description:"收款方式稳定编码快照"`
+	PaymentMethodName        string                                   `json:"payment_method_name" description:"收款方式名称快照"`
+	PaidAmount               int64                                    `json:"paid_amount" description:"人工确认的付款金额（分）"`
+	PayerName                string                                   `json:"payer_name" description:"付款方名称"`
+	PaidAt                   time.Time                                `json:"paid_at" description:"付款时间"`
+	ExternalTransactionNo    string                                   `json:"external_transaction_no" description:"外部交易流水号"`
+	PaymentVoucherKeys       []string                                 `json:"payment_voucher_keys" description:"支付凭证对象存储Key列表，仅返回对象键引用"`
+	Remark                   string                                   `json:"remark" description:"申请备注"`
+	Status                   int                                      `json:"status" description:"申请状态 (0:审批中, 1:已通过, 2:已驳回, 3:已撤销或已关闭)"`
+	StatusName               string                                   `json:"status_name" description:"申请状态中文名称"`
+	LatestApprovalInstanceID uint                                     `json:"latest_approval_instance_id" description:"最新通用审批实例ID，仅用于展示"`
+	DecidedAt                *time.Time                               `json:"decided_at,omitempty" description:"审批终态到达时间"`
+	TerminalReason           string                                   `json:"terminal_reason" description:"异常终态说明，如企业微信通过后撤销"`
+	CreatedAt                time.Time                                `json:"created_at" description:"创建时间"`
+	Attempts                 []*EmployeeCollectionBillAttemptResponse `json:"attempts" description:"该申请的审批尝试记录，按提交顺序排列"`
+}
+
+// EmployeeCollectionBillDetailResponse 员工代收款账单详情响应。
+type EmployeeCollectionBillDetailResponse struct {
+	Bill         *EmployeeCollectionBillResponse              `json:"bill" description:"账单事实"`
+	Refunds      []*EmployeeCollectionBillRefundResponse      `json:"refunds" description:"来源订单退款冲销关联"`
+	Allocations  []*EmployeeCollectionBillAllocationResponse  `json:"allocations" description:"该账单的核销分摊"`
+	Applications []*EmployeeCollectionBillApplicationResponse `json:"applications" description:"涉及该账单的核销申请与审批历史"`
+}
+
+// CloseEmployeeCollectionBillRequest 关闭员工代收款账单请求
+type CloseEmployeeCollectionBillRequest struct {
+	Reason string `json:"reason" validate:"required,min=1,max=500" required:"true" minLength:"1" maxLength:"500" description:"关闭原因，必填，最多 500 字符"`
+}
+
+// EmployeeCollectionApplicationAllocationRequest 核销申请中的单张账单分摊。
+type EmployeeCollectionApplicationAllocationRequest struct {
+	BillID uint  `json:"bill_id" validate:"required" required:"true" description:"目标员工代收款账单ID"`
+	Amount int64 `json:"amount" validate:"required,min=1" required:"true" minimum:"1" description:"本次分摊金额（分），必须大于零且不超过该账单可核销余额"`
+}
+
+// SubmitEmployeeCollectionApplicationRequest 创建或重提核销申请请求。
+// 枚举说明：allocations 由申请人提交，服务端按账单可核销余额与付款金额严格校验。
+type SubmitEmployeeCollectionApplicationRequest struct {
+	PaymentMethodID       uint                                             `json:"payment_method_id" validate:"required" required:"true" description:"线下收款方式字典ID，必须是启用中的字典项"`
+	PaidAmount            int64                                            `json:"paid_amount" validate:"required,min=1" required:"true" minimum:"1" description:"人工确认的付款金额（分），必须大于零"`
+	PayerName             string                                           `json:"payer_name" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"付款方名称，1-100 字符"`
+	PaidAt                string                                           `json:"paid_at" validate:"required" required:"true" description:"付款时间，带时区的 RFC3339 格式，如 2026-08-31T10:00:00+08:00"`
+	ExternalTransactionNo string                                           `json:"external_transaction_no" validate:"required,min=1,max=128" required:"true" minLength:"1" maxLength:"128" description:"经人工确认的外部交易流水号，OCR 结果必须人工更正后提交"`
+	PaymentVoucherKeys    []string                                         `json:"payment_voucher_keys" validate:"required,min=1,max=5,dive,min=1,max=512" required:"true" minItems:"1" maxItems:"5" description:"支付凭证对象存储Key列表，1-5 个既有对象键引用"`
+	Remark                string                                           `json:"remark" validate:"omitempty,max=500" maxLength:"500" description:"申请备注，最多 500 字符"`
+	ActingReason          string                                           `json:"acting_reason" validate:"omitempty,max=500" maxLength:"500" description:"超级管理员代办原因，1-500 字符；代办时必填，本人办理不得填写"`
+	Allocations           []EmployeeCollectionApplicationAllocationRequest `json:"allocations" validate:"required,min=1,max=50,dive" required:"true" minItems:"1" maxItems:"50" description:"账单分摊列表，至少一条；每张账单本次只能出现一次"`
+}
+
+// EmployeeCollectionApplicationListRequest 查询核销申请列表请求。
+type EmployeeCollectionApplicationListRequest struct {
+	Page               int     `json:"page" query:"page" validate:"omitempty,min=1" minimum:"1" description:"页码，默认1"`
+	PageSize           int     `json:"page_size" query:"page_size" validate:"omitempty,min=1,max=100" minimum:"1" maximum:"100" description:"每页条数，默认20，最大100"`
+	Status             *int    `json:"status" query:"status" validate:"omitempty,oneof=0 1 2 3" enum:"0,1,2,3" description:"按申请状态过滤 (0:审批中, 1:已通过, 2:已驳回, 3:已撤销或已关闭)"`
+	ApplicantAccountID *uint   `json:"applicant_account_id" query:"applicant_account_id" description:"按申请人账号ID过滤；非超级管理员固定为当前账号，该参数被忽略"`
+	PaymentMethodID    *uint   `json:"payment_method_id" query:"payment_method_id" description:"按线下收款方式字典ID过滤"`
+	CreatedFrom        *string `json:"created_from" query:"created_from" description:"创建时间起始（YYYY-MM-DD，含当日 00:00:00）"`
+	CreatedTo          *string `json:"created_to" query:"created_to" description:"创建时间截止（YYYY-MM-DD，含当日 23:59:59）"`
+}
+
+// EmployeeCollectionApplicationResponse 核销申请行响应。
+type EmployeeCollectionApplicationResponse struct {
+	ID                       uint       `json:"id" description:"核销申请ID"`
+	ApplicantAccountID       uint       `json:"applicant_account_id" description:"申请人后台账号ID"`
+	ActingOperatorID         uint       `json:"acting_operator_id" description:"实际代办的超级管理员账号ID，0 表示本人办理"`
+	ActingReason             string     `json:"acting_reason" description:"代办原因，非代办为空"`
+	PaymentMethodID          uint       `json:"payment_method_id" description:"线下收款方式字典ID"`
+	PaymentMethodCode        string     `json:"payment_method_code" description:"收款方式稳定编码快照"`
+	PaymentMethodName        string     `json:"payment_method_name" description:"收款方式名称快照，字典改名不影响历史申请"`
+	PaidAmount               int64      `json:"paid_amount" description:"人工确认的付款金额（分）"`
+	PayerName                string     `json:"payer_name" description:"付款方名称"`
+	PaidAt                   time.Time  `json:"paid_at" description:"付款时间"`
+	ExternalTransactionNo    string     `json:"external_transaction_no" description:"人工确认的外部交易流水号，申请人可原样核对与重用"`
+	PaymentVoucherKeys       []string   `json:"payment_voucher_keys" description:"支付凭证对象存储Key列表，仅返回对象键引用"`
+	Remark                   string     `json:"remark" description:"申请备注"`
+	Status                   int        `json:"status" description:"申请状态 (0:审批中, 1:已通过, 2:已驳回, 3:已撤销或已关闭)"`
+	StatusName               string     `json:"status_name" description:"申请状态中文名称"`
+	LatestAttemptID          uint       `json:"latest_attempt_id" description:"最新审批尝试记录ID，仅用于展示"`
+	LatestApprovalInstanceID uint       `json:"latest_approval_instance_id" description:"最新通用审批实例ID，仅用于展示"`
+	DecidedAt                *time.Time `json:"decided_at,omitempty" description:"审批终态到达时间"`
+	TerminalReason           string     `json:"terminal_reason" description:"异常终态说明，如企业微信通过后撤销"`
+	CreatedAt                time.Time  `json:"created_at" description:"创建时间"`
+	UpdatedAt                time.Time  `json:"updated_at" description:"最近更新时间"`
+}
+
+// EmployeeCollectionApplicationListResponse 核销申请列表响应。
+type EmployeeCollectionApplicationListResponse struct {
+	List     []*EmployeeCollectionApplicationResponse `json:"items" description:"核销申请列表"`
+	Total    int64                                    `json:"total" description:"总数"`
+	Page     int                                      `json:"page" description:"当前页码"`
+	PageSize int                                      `json:"size" description:"每页条数"`
+}
+
+// EmployeeCollectionApplicationAllocationResponse 核销申请分摊响应，含目标账单只读摘要。
+type EmployeeCollectionApplicationAllocationResponse struct {
+	ID                   uint       `json:"id" description:"分摊ID"`
+	BillID               uint       `json:"bill_id" description:"目标账单ID"`
+	Amount               int64      `json:"amount" description:"本次分摊金额（分）"`
+	Status               int        `json:"status" description:"分摊状态 (0:审批中预占, 1:已通过, 2:已驳回或已释放)"`
+	StatusName           string     `json:"status_name" description:"分摊状态中文名称"`
+	ReleasedAt           *time.Time `json:"released_at,omitempty" description:"预占释放时间，审批中为空"`
+	BillSourceType       string     `json:"bill_source_type" description:"账单来源类型 (order:后台线下套餐订单, recharge:代理线下充值)"`
+	BillSourceNo         string     `json:"bill_source_no" description:"账单来源单号"`
+	BillReceivableAmount int64      `json:"bill_receivable_amount" description:"账单应收金额（分）"`
+	BillReceivedAmount   int64      `json:"bill_received_amount" description:"账单已核销金额（分）"`
+	BillReservedAmount   int64      `json:"bill_reserved_amount" description:"账单审批中预占金额（分）"`
+	BillStatus           int        `json:"bill_status" description:"账单状态 (0:待核销, 1:部分核销, 2:已核销, 3:已关闭)"`
+	BillStatusName       string     `json:"bill_status_name" description:"账单状态中文名称"`
+	CreatedAt            time.Time  `json:"created_at" description:"创建时间"`
+}
+
+// EmployeeCollectionApplicationSubmitResponse 创建或重提核销申请响应。
+type EmployeeCollectionApplicationSubmitResponse struct {
+	Application        *EmployeeCollectionApplicationResponse             `json:"application" description:"核销申请事实"`
+	Attempt            *EmployeeCollectionBillAttemptResponse             `json:"attempt" description:"本次新增的审批尝试记录与冻结快照"`
+	Allocations        []*EmployeeCollectionApplicationAllocationResponse `json:"allocations" description:"本次账单分摊与预占结果"`
+	ApprovalInstanceID uint                                               `json:"approval_instance_id" description:"本次创建的企业微信通用审批实例ID"`
+	ApprovalStatus     int                                                `json:"approval_status" description:"通用审批实例状态 (0:提交中, 1:审批中, 2:已通过, 3:已拒绝, 4:已撤销, 5:通过后撤销, 6:已删除, 7:提交失败, 8:提交结果未知)"`
+	ApprovalStatusName string                                             `json:"approval_status_name" description:"通用审批实例状态中文名称"`
+}
+
+// EmployeeCollectionApplicationDetailResponse 核销申请详情响应。
+type EmployeeCollectionApplicationDetailResponse struct {
+	Application *EmployeeCollectionApplicationResponse             `json:"application" description:"核销申请事实与最新审批引用"`
+	Allocations []*EmployeeCollectionApplicationAllocationResponse `json:"allocations" description:"该申请当前的账单分摊"`
+	Attempts    []*EmployeeCollectionBillAttemptResponse           `json:"attempts" description:"全部审批尝试记录，按提交顺序排列，历史材料不被覆盖"`
+}

internal/model/dto/order_dto.go

@@ -15,7 +15,7 @@ type CreateAdminOrderRequest struct {
 	Identifier        string   `json:"identifier" validate:"required,min=1,max=100" required:"true" minLength:"1" maxLength:"100" description:"资产标识符（卡支持 ICCID，设备支持 VirtualNo、IMEI 或 SN）"`
 	PackageIDs        []uint   `json:"package_ids" validate:"required,min=1,max=10,dive,min=1" required:"true" minItems:"1" maxItems:"10" description:"套餐ID列表"`
 	PaymentMethod     string   `json:"payment_method" validate:"required,oneof=wallet offline" required:"true" description:"支付方式 (wallet:钱包支付, offline:线下支付)"`
-	PaymentVoucherKey []string `json:"payment_voucher_key" validate:"omitempty,max=5,dive,max=500" maxItems:"5" description:"线下支付凭证对象存储file_key列表（payment_method=offline时至少1个，最多5个，通过/storage/upload-url上传图片后获得）"`
+	PaymentVoucherKey []string `json:"payment_voucher_key" validate:"omitempty,max=5,dive,max=500" maxItems:"5" description:"线下支付凭证对象存储file_key列表（最多5个，通过/storage/upload-url上传图片后获得）；线下订单需付款凭证，但实际收款金额大于 0 且由平台账号操作的非赠送线下订单会生成员工代收款账单，该场景凭证由核销申请环节提供，创建订单时可为空"`
 }
 
 type OrderListRequest struct {

internal/model/dto/payment_merchant_dto.go

@@ -0,0 +1,124 @@
+package dto
+
+import (
+	"time"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+)
+
+// PaymentMerchantRequest 是受控商户管理写入请求。
+type PaymentMerchantRequest struct {
+	Name             string      `json:"name" validate:"required,min=1,max=100" description:"商户名称"`
+	PaymentMethod    string      `json:"payment_method" validate:"required,oneof=wechat alipay" enum:"wechat,alipay" description:"支付方式：wechat=微信支付，alipay=支付宝支付"`
+	ProviderType     string      `json:"provider_type" validate:"required,max=30" description:"服务商类型：微信仅支持 wechat、wechat_v2、fuiou；支付宝为 alipay"`
+	MerchantIdentity string      `json:"merchant_identity" validate:"required,max=100" description:"商户号或应用标识"`
+	Credentials      model.JSONB `json:"credentials" description:"商户受控凭证，仅专用管理接口传输"`
+	Enabled          bool        `json:"enabled" description:"是否启用"`
+	Remark           string      `json:"remark" validate:"max=1000" description:"备注"`
+}
+
+// PaymentMerchantUpdateRequest 是受控商户管理更新请求。
+type PaymentMerchantUpdateRequest struct {
+	Name             *string      `json:"name" description:"商户名称"`
+	PaymentMethod    *string      `json:"payment_method" enum:"wechat,alipay" description:"支付方式：wechat=微信支付，alipay=支付宝支付"`
+	ProviderType     *string      `json:"provider_type" description:"服务商类型：微信仅支持 wechat、wechat_v2、fuiou；支付宝为 alipay"`
+	MerchantIdentity *string      `json:"merchant_identity" description:"商户号或应用标识"`
+	Credentials      *model.JSONB `json:"credentials" description:"商户受控凭证"`
+	Enabled          *bool        `json:"enabled" description:"是否启用"`
+	Remark           *string      `json:"remark" description:"备注"`
+}
+
+// PaymentMerchantDeleteRequest 是受控商户删除二次确认请求。
+type PaymentMerchantDeleteRequest struct {
+	Confirm bool `json:"confirm" validate:"required" description:"确认删除，必须为true"`
+}
+
+// PaymentMerchantListRequest 是支付商户分页查询条件。
+type PaymentMerchantListRequest struct {
+	Page          int     `query:"page" description:"页码"`
+	PageSize      int     `query:"page_size" description:"每页数量"`
+	PaymentMethod *string `query:"payment_method" enum:"wechat,alipay" description:"支付方式：wechat=微信支付，alipay=支付宝支付"`
+	Enabled       *bool   `query:"enabled" description:"是否启用"`
+}
+
+// PaymentMerchantResponse 是受控商户管理响应。
+type PaymentMerchantResponse struct {
+	ID                uint        `json:"id" description:"商户ID"`
+	Name              string      `json:"name" description:"商户名称"`
+	PaymentMethod     string      `json:"payment_method" enum:"wechat,alipay" description:"支付方式：wechat=微信支付，alipay=支付宝支付"`
+	ProviderType      string      `json:"provider_type" description:"服务商类型"`
+	MerchantIdentity  string      `json:"merchant_identity" description:"商户号或应用标识"`
+	Credentials       model.JSONB `json:"credentials" description:"商户受控凭证，仅专用管理接口返回"`
+	CredentialVersion int64       `json:"credential_version" description:"凭证版本"`
+	Enabled           bool        `json:"enabled" description:"是否启用"`
+	Remark            string      `json:"remark" description:"备注"`
+	CreatedAt         time.Time   `json:"created_at" description:"创建时间"`
+	UpdatedAt         time.Time   `json:"updated_at" description:"更新时间"`
+}
+
+// PaymentMerchantPoolRequest 是商户池创建或更新请求。
+type PaymentMerchantPoolRequest struct {
+	Name                string     `json:"name" validate:"required,min=1,max=100" description:"商户池名称"`
+	PaymentMethod       string     `json:"payment_method" validate:"required,oneof=wechat alipay" enum:"wechat,alipay" description:"支付方式：wechat=微信支付，alipay=支付宝支付"`
+	Enabled             bool       `json:"enabled" description:"是否启用"`
+	Strategy            string     `json:"strategy" validate:"required,oneof=amount count time" enum:"amount,count,time" description:"轮询策略：amount=金额阈值，count=笔数阈值，time=按时间段轮换"`
+	ThresholdAmount     *int64     `json:"threshold_amount" description:"金额轮询阈值，单位分；仅 amount 策略"`
+	ThresholdCount      *int64     `json:"threshold_count" description:"笔数轮询阈值；仅 count 策略"`
+	StatisticCycle      *string    `json:"statistic_cycle" enum:"round,day,month" description:"金额/笔数统计周期：round=每轮，day=自然日，month=自然月"`
+	TimePeriodValue     *int64     `json:"time_period_value" description:"时间轮询周期数值；仅 time 策略，最小 1"`
+	TimePeriodUnit      *string    `json:"time_period_unit" enum:"minute,hour,day" description:"时间轮询单位：minute=分钟，hour=小时，day=天"`
+	TimePeriodStartedAt *time.Time `json:"time_period_started_at" description:"时间轮询起始时间；仅 time 策略"`
+	MemberIDs           []uint     `json:"member_ids" validate:"required,min=1" description:"有序商户ID列表"`
+	Remark              string     `json:"remark" description:"备注"`
+}
+
+// PaymentMerchantPoolListRequest 是商户池分页查询条件。
+type PaymentMerchantPoolListRequest struct {
+	Page     int `query:"page" description:"页码"`
+	PageSize int `query:"page_size" description:"每页数量"`
+}
+
+// PaymentMerchantPoolResponse 是商户池管理响应。
+type PaymentMerchantPoolResponse struct {
+	ID                  uint       `json:"id" description:"商户池ID"`
+	Name                string     `json:"name" description:"商户池名称"`
+	PaymentMethod       string     `json:"payment_method" enum:"wechat,alipay" description:"支付方式：wechat=微信支付，alipay=支付宝支付"`
+	Enabled             bool       `json:"enabled" description:"是否启用"`
+	Strategy            string     `json:"strategy" enum:"amount,count,time" description:"轮询策略：amount=金额阈值，count=笔数阈值，time=按时间段轮换"`
+	ThresholdAmount     *int64     `json:"threshold_amount,omitempty" description:"金额阈值，分"`
+	ThresholdCount      *int64     `json:"threshold_count,omitempty" description:"笔数阈值"`
+	StatisticCycle      *string    `json:"statistic_cycle,omitempty" enum:"round,day,month" description:"统计周期：round=每轮，day=自然日，month=自然月"`
+	TimePeriodValue     *int64     `json:"time_period_value,omitempty" description:"时间周期数值"`
+	TimePeriodUnit      *string    `json:"time_period_unit,omitempty" enum:"minute,hour,day" description:"时间单位：minute=分钟，hour=小时，day=天"`
+	TimePeriodStartedAt *time.Time `json:"time_period_started_at,omitempty" description:"时间轮询起始时间"`
+	RoutingEpoch        int64      `json:"routing_epoch" description:"当前路由统计世代"`
+	MemberIDs           []uint     `json:"member_ids" description:"有序商户ID列表"`
+	Remark              string     `json:"remark" description:"备注"`
+}
+
+// WechatAuthorizationRequest 是微信授权配置管理写入请求。
+type WechatAuthorizationRequest struct {
+	OaAppID            string `json:"oa_app_id" description:"公众号AppID"`
+	OaAppSecret        string `json:"oa_app_secret" description:"公众号AppSecret"`
+	OaToken            string `json:"oa_token" description:"公众号Token"`
+	OaAesKey           string `json:"oa_aes_key" description:"公众号AES密钥"`
+	OaOAuthRedirectURL string `json:"oa_oauth_redirect_url" description:"公众号OAuth回调地址"`
+	MiniappAppID       string `json:"miniapp_app_id" description:"小程序AppID"`
+	MiniappAppSecret   string `json:"miniapp_app_secret" description:"小程序AppSecret"`
+	Enabled            bool   `json:"enabled" description:"是否启用"`
+}
+
+// WechatAuthorizationResponse 是微信授权配置管理响应。
+type WechatAuthorizationResponse struct {
+	ID                 uint      `json:"id" description:"授权配置ID"`
+	OaAppID            string    `json:"oa_app_id" description:"公众号AppID"`
+	OaAppSecret        string    `json:"oa_app_secret" description:"公众号AppSecret，仅专用管理接口返回"`
+	OaToken            string    `json:"oa_token" description:"公众号Token，仅专用管理接口返回"`
+	OaAesKey           string    `json:"oa_aes_key" description:"公众号AES密钥，仅专用管理接口返回"`
+	OaOAuthRedirectURL string    `json:"oa_oauth_redirect_url" description:"公众号OAuth回调地址"`
+	MiniappAppID       string    `json:"miniapp_app_id" description:"小程序AppID"`
+	MiniappAppSecret   string    `json:"miniapp_app_secret" description:"小程序AppSecret，仅专用管理接口返回"`
+	CredentialVersion  int64     `json:"credential_version" description:"凭证版本"`
+	Enabled            bool      `json:"enabled" description:"是否启用"`
+	UpdatedAt          time.Time `json:"updated_at" description:"更新时间"`
+}

internal/model/dto/wecom_scene_dto.go

@@ -23,7 +23,7 @@ type InspectWeComTemplateParams struct {
 
 // WeComBusinessFieldListParams 查询企业微信审批场景可映射字段路径参数。
 type WeComBusinessFieldListParams struct {
-	BusinessType string `path:"business_type" required:"true" description:"业务类型 (refund_approval:退款审批, offline_recharge_approval:员工线下代充值审批)"`
+	BusinessType string `path:"business_type" required:"true" enum:"refund_approval,offline_recharge_approval,employee_collection_approval" description:"业务类型 (refund_approval:退款审批, offline_recharge_approval:员工线下代充值审批, employee_collection_approval:员工代收款核销审批)"`
 }
 
 // WeComBusinessFieldResponse 企业微信审批场景可映射业务字段响应。
@@ -67,7 +67,7 @@ type SaveWeComApprovalSceneRequest struct {
 
 // SaveWeComApprovalSceneParams 保存企业微信审批场景路径与请求参数。
 type SaveWeComApprovalSceneParams struct {
-	BusinessType string `path:"business_type" required:"true" description:"业务类型 (refund_approval:退款审批, offline_recharge_approval:员工线下代充值审批)；可先调用 GET /api/admin/wecom/scenes/{business_type}/fields 查询允许映射的业务字段"`
+	BusinessType string `path:"business_type" required:"true" enum:"refund_approval,offline_recharge_approval,employee_collection_approval" description:"业务类型 (refund_approval:退款审批, offline_recharge_approval:员工线下代充值审批, employee_collection_approval:员工代收款核销审批)；可先调用 GET /api/admin/wecom/scenes/{business_type}/fields 查询允许映射的业务字段"`
 	SaveWeComApprovalSceneRequest
 }
 

internal/model/employee_collection.go

@@ -0,0 +1,150 @@
+package model
+
+import (
+	"time"
+
+	"gorm.io/datatypes"
+	"gorm.io/gorm"
+)
+
+// EmployeeCollectionPaymentMethod 是线下收款方式字典项。
+// 状态语义见 constants.EmployeeCollectionPaymentMethodStatus*；被业务引用后只可停用。
+type EmployeeCollectionPaymentMethod struct {
+	gorm.Model
+	BaseModel `gorm:"embedded"`
+	Code      string `gorm:"column:code;type:varchar(64);not null;comment:稳定编码，未删除记录中唯一" json:"code"`
+	Name      string `gorm:"column:name;type:varchar(100);not null;comment:收款方式名称" json:"name"`
+	SortOrder int64  `gorm:"column:sort_order;type:bigint;not null;default:0;comment:排序值，从 0 递增" json:"sort_order"`
+	Status    int    `gorm:"column:status;type:smallint;not null;default:1;comment:状态 0-禁用 1-启用" json:"status"`
+	Remark    string `gorm:"column:remark;type:varchar(500);not null;default:'';comment:备注" json:"remark"`
+}
+
+// TableName 指定线下收款方式字典表名。
+func (EmployeeCollectionPaymentMethod) TableName() string {
+	return "tb_employee_collection_payment_method"
+}
+
+// EmployeeCollectionBill 是后台账号代客户经办业务形成的本地暂挂欠款。
+// 由来源成功事务按来源唯一键 SourceKey 幂等创建，不存在历史扫描或手工建账路径。
+type EmployeeCollectionBill struct {
+	ID               uint           `gorm:"column:id;primaryKey;autoIncrement" json:"id"`
+	SourceType       string         `gorm:"column:source_type;type:varchar(20);not null;comment:来源类型 order/recharge" json:"source_type"`
+	SourceID         uint           `gorm:"column:source_id;not null;comment:来源业务主键ID" json:"source_id"`
+	SourceKey        string         `gorm:"column:source_key;type:varchar(64);not null;comment:来源唯一键 order:{id} / recharge:{id}" json:"source_key"`
+	SourceNo         string         `gorm:"column:source_no;type:varchar(64);not null;default:'';comment:来源单号快照" json:"source_no"`
+	DebtorAccountID  uint           `gorm:"column:debtor_account_id;not null;comment:欠款人后台账号ID" json:"debtor_account_id"`
+	DebtorSnapshot   datatypes.JSON `gorm:"column:debtor_snapshot;type:jsonb;not null;comment:欠款人账号快照" json:"debtor_snapshot"`
+	CustomerSnapshot datatypes.JSON `gorm:"column:customer_snapshot;type:jsonb;not null;comment:来源客户或店铺只读快照" json:"customer_snapshot"`
+	ReceivableAmount int64          `gorm:"column:receivable_amount;type:bigint;not null;comment:应收金额（分）" json:"receivable_amount"`
+	ReceivedAmount   int64          `gorm:"column:received_amount;type:bigint;not null;default:0;comment:已核销金额（分）" json:"received_amount"`
+	ReservedAmount   int64          `gorm:"column:reserved_amount;type:bigint;not null;default:0;comment:审批中预占金额（分）" json:"reserved_amount"`
+	Status           int            `gorm:"column:status;type:smallint;not null;default:0;comment:状态 0-待核销 1-部分核销 2-已核销 3-已关闭" json:"status"`
+	ClosedReason     string         `gorm:"column:closed_reason;type:varchar(500);not null;default:'';comment:关闭原因" json:"closed_reason"`
+	ClosedAt         *time.Time     `gorm:"column:closed_at;type:timestamptz;comment:关闭时间" json:"closed_at,omitempty"`
+	Creator          uint           `gorm:"column:creator;not null;default:0;comment:创建人用户ID" json:"creator"`
+	Updater          uint           `gorm:"column:updater;not null;default:0;comment:最近更新人用户ID" json:"updater"`
+	CreatedAt        time.Time      `gorm:"column:created_at;type:timestamptz;not null;autoCreateTime" json:"created_at"`
+	UpdatedAt        time.Time      `gorm:"column:updated_at;type:timestamptz;not null;autoUpdateTime" json:"updated_at"`
+}
+
+// TableName 指定员工代收款账单表名。
+func (EmployeeCollectionBill) TableName() string {
+	return "tb_employee_collection_bill"
+}
+
+// EmployeeCollectionApplication 是一笔外部付款的核销申请，只保存最新审批实例ID用于展示。
+type EmployeeCollectionApplication struct {
+	ID                       uint             `gorm:"column:id;primaryKey;autoIncrement" json:"id"`
+	ApplicantAccountID       uint             `gorm:"column:applicant_account_id;not null;comment:申请人后台账号ID" json:"applicant_account_id"`
+	ActingOperatorID         uint             `gorm:"column:acting_operator_id;not null;default:0;comment:实际代办的超级管理员账号ID，0 表示本人办理" json:"acting_operator_id"`
+	ActingReason             string           `gorm:"column:acting_reason;type:varchar(500);not null;default:'';comment:代办原因" json:"acting_reason"`
+	PaymentMethodID          uint             `gorm:"column:payment_method_id;not null;comment:线下收款方式字典ID" json:"payment_method_id"`
+	PaymentMethodCode        string           `gorm:"column:payment_method_code;type:varchar(64);not null;comment:收款方式编码快照" json:"payment_method_code"`
+	PaymentMethodName        string           `gorm:"column:payment_method_name;type:varchar(100);not null;comment:收款方式名称快照" json:"payment_method_name"`
+	PaidAmount               int64            `gorm:"column:paid_amount;type:bigint;not null;comment:人工确认付款金额（分）" json:"paid_amount"`
+	PayerName                string           `gorm:"column:payer_name;type:varchar(100);not null;default:'';comment:付款方名称" json:"payer_name"`
+	PaidAt                   time.Time        `gorm:"column:paid_at;type:timestamptz;not null;comment:付款时间" json:"paid_at"`
+	ExternalTransactionNo    string           `gorm:"column:external_transaction_no;type:varchar(128);not null;default:'';comment:外部交易流水号" json:"external_transaction_no"`
+	PaymentVoucherKeys       StringJSONBArray `gorm:"column:payment_voucher_keys;type:jsonb;not null;comment:支付凭证对象存储Key列表" json:"payment_voucher_keys"`
+	Remark                   string           `gorm:"column:remark;type:varchar(500);not null;default:'';comment:申请备注" json:"remark"`
+	Status                   int              `gorm:"column:status;type:smallint;not null;default:0;comment:状态 0-审批中 1-已通过 2-已驳回 3-已撤销或已关闭" json:"status"`
+	LatestAttemptID          uint             `gorm:"column:latest_attempt_id;not null;default:0;comment:最新审批尝试记录ID" json:"latest_attempt_id"`
+	LatestApprovalInstanceID uint             `gorm:"column:latest_approval_instance_id;not null;default:0;comment:最新通用审批实例ID" json:"latest_approval_instance_id"`
+	DecidedAt                *time.Time       `gorm:"column:decided_at;type:timestamptz;comment:审批终态到达时间" json:"decided_at,omitempty"`
+	TerminalReason           string           `gorm:"column:terminal_reason;type:varchar(500);not null;default:'';comment:异常终态说明" json:"terminal_reason"`
+	Creator                  uint             `gorm:"column:creator;not null;default:0;comment:创建人用户ID" json:"creator"`
+	Updater                  uint             `gorm:"column:updater;not null;default:0;comment:最近更新人用户ID" json:"updater"`
+	CreatedAt                time.Time        `gorm:"column:created_at;type:timestamptz;not null;autoCreateTime" json:"created_at"`
+	UpdatedAt                time.Time        `gorm:"column:updated_at;type:timestamptz;not null;autoUpdateTime" json:"updated_at"`
+}
+
+// TableName 指定核销申请表名。
+func (EmployeeCollectionApplication) TableName() string {
+	return "tb_employee_collection_application"
+}
+
+// EmployeeCollectionApplicationAttempt 是同一申请每次提交或重提对应的不可变审批材料。
+// 其主键同时作为通用审批实例的业务ID，使每次提交各自持有独立审批实例。
+type EmployeeCollectionApplicationAttempt struct {
+	ID                    uint             `gorm:"column:id;primaryKey;autoIncrement" json:"id"`
+	ApplicationID         uint             `gorm:"column:application_id;not null;comment:所属核销申请ID" json:"application_id"`
+	AttemptNo             int              `gorm:"column:attempt_no;type:int;not null;comment:第几次提交，从 1 递增" json:"attempt_no"`
+	PaymentMethodID       uint             `gorm:"column:payment_method_id;not null;comment:本次冻结的收款方式字典ID" json:"payment_method_id"`
+	PaymentMethodCode     string           `gorm:"column:payment_method_code;type:varchar(64);not null;comment:本次冻结的收款方式编码" json:"payment_method_code"`
+	PaymentMethodName     string           `gorm:"column:payment_method_name;type:varchar(100);not null;comment:本次冻结的收款方式名称" json:"payment_method_name"`
+	PaidAmount            int64            `gorm:"column:paid_amount;type:bigint;not null;comment:本次冻结的付款金额（分）" json:"paid_amount"`
+	PayerName             string           `gorm:"column:payer_name;type:varchar(100);not null;default:'';comment:本次冻结的付款方名称" json:"payer_name"`
+	PaidAt                time.Time        `gorm:"column:paid_at;type:timestamptz;not null;comment:本次冻结的付款时间" json:"paid_at"`
+	ExternalTransactionNo string           `gorm:"column:external_transaction_no;type:varchar(128);not null;default:'';comment:本次冻结的外部交易流水号" json:"external_transaction_no"`
+	PaymentVoucherKeys    StringJSONBArray `gorm:"column:payment_voucher_keys;type:jsonb;not null;comment:本次冻结的支付凭证对象键列表" json:"payment_voucher_keys"`
+	Remark                string           `gorm:"column:remark;type:varchar(500);not null;default:'';comment:本次冻结的备注" json:"remark"`
+	SubmittedByAccountID  uint             `gorm:"column:submitted_by_account_id;not null;comment:本次实际提交账号ID" json:"submitted_by_account_id"`
+	ActingReason          string           `gorm:"column:acting_reason;type:varchar(500);not null;default:'';comment:本次代办原因" json:"acting_reason"`
+	AllocationSnapshot    datatypes.JSON   `gorm:"column:allocation_snapshot;type:jsonb;not null;comment:本次冻结的账单分摊快照" json:"allocation_snapshot"`
+	ApprovalInstanceID    *uint            `gorm:"column:approval_instance_id;comment:本次尝试关联的通用审批实例ID" json:"approval_instance_id,omitempty"`
+	CreatedAt             time.Time        `gorm:"column:created_at;type:timestamptz;not null;autoCreateTime" json:"created_at"`
+}
+
+// TableName 指定审批尝试记录表名。
+func (EmployeeCollectionApplicationAttempt) TableName() string {
+	return "tb_employee_collection_application_attempt"
+}
+
+// EmployeeCollectionApplicationAllocation 是申请对单张账单的本次分摊。
+// 审批中预占账单余额，终态释放预占或转入已核销金额。
+type EmployeeCollectionApplicationAllocation struct {
+	ID            uint       `gorm:"column:id;primaryKey;autoIncrement" json:"id"`
+	ApplicationID uint       `gorm:"column:application_id;not null;comment:所属核销申请ID" json:"application_id"`
+	AttemptID     uint       `gorm:"column:attempt_id;not null;comment:所属审批尝试记录ID" json:"attempt_id"`
+	BillID        uint       `gorm:"column:bill_id;not null;comment:目标账单ID" json:"bill_id"`
+	Amount        int64      `gorm:"column:amount;type:bigint;not null;comment:本次分摊金额（分）" json:"amount"`
+	Status        int        `gorm:"column:status;type:smallint;not null;default:0;comment:状态 0-审批中预占 1-已通过 2-已驳回或已释放" json:"status"`
+	ReleasedAt    *time.Time `gorm:"column:released_at;type:timestamptz;comment:预占释放时间" json:"released_at,omitempty"`
+	Creator       uint       `gorm:"column:creator;not null;default:0;comment:创建人用户ID" json:"creator"`
+	Updater       uint       `gorm:"column:updater;not null;default:0;comment:最近更新人用户ID" json:"updater"`
+	CreatedAt     time.Time  `gorm:"column:created_at;type:timestamptz;not null;autoCreateTime" json:"created_at"`
+	UpdatedAt     time.Time  `gorm:"column:updated_at;type:timestamptz;not null;autoUpdateTime" json:"updated_at"`
+}
+
+// TableName 指定申请分摊表名。
+func (EmployeeCollectionApplicationAllocation) TableName() string {
+	return "tb_employee_collection_application_allocation"
+}
+
+// EmployeeCollectionBillRefund 是来源订单退款与账单之间的唯一冲销关联事实。
+type EmployeeCollectionBillRefund struct {
+	ID                   uint      `gorm:"column:id;primaryKey;autoIncrement" json:"id"`
+	BillID               uint      `gorm:"column:bill_id;not null;comment:目标账单ID" json:"bill_id"`
+	RefundID             uint      `gorm:"column:refund_id;not null;comment:退款申请ID" json:"refund_id"`
+	SourceOrderID        uint      `gorm:"column:source_order_id;not null;comment:账单来源订单ID" json:"source_order_id"`
+	RefundAmount         int64     `gorm:"column:refund_amount;type:bigint;not null;comment:本次退款成功金额（分）" json:"refund_amount"`
+	BillReceivableAmount int64     `gorm:"column:bill_receivable_amount;type:bigint;not null;comment:冲销前账单应收金额快照（分）" json:"bill_receivable_amount"`
+	Outcome              string    `gorm:"column:outcome;type:varchar(20);not null;comment:处理结果 closed_full/reduced/hint_only" json:"outcome"`
+	ReducedAmount        int64     `gorm:"column:reduced_amount;type:bigint;not null;default:0;comment:实际冲减应收金额（分）" json:"reduced_amount"`
+	CreatedAt            time.Time `gorm:"column:created_at;type:timestamptz;not null;autoCreateTime" json:"created_at"`
+}
+
+// TableName 指定退款冲销关联表名。
+func (EmployeeCollectionBillRefund) TableName() string {
+	return "tb_employee_collection_bill_refund"
+}

internal/model/order.go

@@ -75,7 +75,8 @@ type Order struct {
 	// 支付配置
 	PaymentConfigID *uint `gorm:"column:payment_config_id;index;comment:支付配置ID(关联tb_wechat_config.id)" json:"payment_config_id,omitempty"`
 
-	// 线下支付凭证对象存储 file_key 列表（最多5个，仅线下支付订单必填）
+	// 线下支付凭证对象存储 file_key 列表（最多5个，线下支付订单必填；
+	// 会生成员工代收款账单的线下订单除外，该场景凭证由核销申请环节提供）
 	PaymentVoucherKey StringJSONBArray `gorm:"column:payment_voucher_key;type:jsonb;comment:线下支付凭证对象存储file_key列表（jsonb存储[]string）" json:"payment_voucher_key"`
 }
 

internal/model/payment.go

@@ -8,23 +8,31 @@ import (
 )
 
 type Payment struct {
-	ID                uint           `gorm:"column:id;primaryKey" json:"id"`
-	PaymentNo         string         `gorm:"column:payment_no;type:varchar(40);uniqueIndex;not null" json:"payment_no"`
-	OrderID           uint           `gorm:"column:order_id;not null" json:"order_id"`
-	OrderType         string         `gorm:"column:order_type;type:varchar(30);not null" json:"order_type"`
-	PaymentMethod     string         `gorm:"column:payment_method;type:varchar(20);not null" json:"payment_method"`
-	MerchantIdentity  string         `gorm:"column:merchant_identity;type:varchar(100)" json:"-"`
-	Amount            int64          `gorm:"column:amount;type:bigint;not null" json:"amount"`
-	Status            int            `gorm:"column:status;type:smallint;not null;default:0" json:"status"`
-	ThirdPartyTradeNo string         `gorm:"column:third_party_trade_no;type:varchar(100)" json:"third_party_trade_no,omitempty"`
-	PaymentConfigID   *uint          `gorm:"column:payment_config_id" json:"payment_config_id,omitempty"`
-	PaymentVoucherKey string         `gorm:"column:payment_voucher_key;type:varchar(500)" json:"payment_voucher_key,omitempty"`
-	QRContent         string         `gorm:"column:qr_content;type:text" json:"-"`
-	PaidAt            *time.Time     `gorm:"column:paid_at" json:"paid_at,omitempty"`
-	ExpireAt          *time.Time     `gorm:"column:expire_at" json:"expire_at,omitempty"`
-	CreatedAt         time.Time      `gorm:"column:created_at;not null;default:CURRENT_TIMESTAMP" json:"created_at"`
-	UpdatedAt         time.Time      `gorm:"column:updated_at;not null;default:CURRENT_TIMESTAMP" json:"updated_at"`
-	DeletedAt         gorm.DeletedAt `gorm:"column:deleted_at;index" json:"deleted_at,omitempty"`
+	ID                            uint           `gorm:"column:id;primaryKey" json:"id"`
+	PaymentNo                     string         `gorm:"column:payment_no;type:varchar(40);uniqueIndex;not null" json:"payment_no"`
+	OrderID                       uint           `gorm:"column:order_id;not null" json:"order_id"`
+	OrderType                     string         `gorm:"column:order_type;type:varchar(30);not null" json:"order_type"`
+	PaymentMethod                 string         `gorm:"column:payment_method;type:varchar(20);not null" json:"payment_method"`
+	MerchantIdentity              string         `gorm:"column:merchant_identity;type:varchar(100)" json:"-"`
+	MerchantID                    *uint          `gorm:"column:merchant_id" json:"merchant_id,omitempty"`
+	MerchantPoolID                *uint          `gorm:"column:merchant_pool_id" json:"merchant_pool_id,omitempty"`
+	MerchantNameSnapshot          string         `gorm:"column:merchant_name_snapshot" json:"merchant_name_snapshot,omitempty"`
+	MerchantPaymentMethodSnapshot string         `gorm:"column:merchant_payment_method_snapshot" json:"merchant_payment_method_snapshot,omitempty"`
+	MerchantProviderTypeSnapshot  string         `gorm:"column:merchant_provider_type_snapshot" json:"merchant_provider_type_snapshot,omitempty"`
+	MerchantPoolNameSnapshot      string         `gorm:"column:merchant_pool_name_snapshot" json:"merchant_pool_name_snapshot,omitempty"`
+	RoutingStrategySnapshot       string         `gorm:"column:routing_strategy_snapshot" json:"routing_strategy_snapshot,omitempty"`
+	RoutingEpoch                  *int64         `gorm:"column:routing_epoch" json:"routing_epoch,omitempty"`
+	Amount                        int64          `gorm:"column:amount;type:bigint;not null" json:"amount"`
+	Status                        int            `gorm:"column:status;type:smallint;not null;default:0" json:"status"`
+	ThirdPartyTradeNo             string         `gorm:"column:third_party_trade_no;type:varchar(100)" json:"third_party_trade_no,omitempty"`
+	PaymentConfigID               *uint          `gorm:"column:payment_config_id" json:"payment_config_id,omitempty"`
+	PaymentVoucherKey             string         `gorm:"column:payment_voucher_key;type:varchar(500)" json:"payment_voucher_key,omitempty"`
+	QRContent                     string         `gorm:"column:qr_content;type:text" json:"-"`
+	PaidAt                        *time.Time     `gorm:"column:paid_at" json:"paid_at,omitempty"`
+	ExpireAt                      *time.Time     `gorm:"column:expire_at" json:"expire_at,omitempty"`
+	CreatedAt                     time.Time      `gorm:"column:created_at;not null;default:CURRENT_TIMESTAMP" json:"created_at"`
+	UpdatedAt                     time.Time      `gorm:"column:updated_at;not null;default:CURRENT_TIMESTAMP" json:"updated_at"`
+	DeletedAt                     gorm.DeletedAt `gorm:"column:deleted_at;index" json:"deleted_at,omitempty"`
 }
 
 func (Payment) TableName() string {

internal/model/payment_merchant.go

@@ -0,0 +1,94 @@
+package model
+
+import (
+	"time"
+
+	"gorm.io/gorm"
+)
+
+const (
+	PaymentMerchantStatusDisabled = 0
+	PaymentMerchantStatusEnabled  = 1
+
+	PaymentMerchantStrategyAmount = "amount"
+	PaymentMerchantStrategyCount  = "count"
+	PaymentMerchantStrategyTime   = "time"
+)
+
+// PaymentMerchant 是实际收款商户，凭证只保存在受控字段。
+type PaymentMerchant struct {
+	gorm.Model
+	BaseModel         `gorm:"embedded"`
+	Name              string `gorm:"column:name" json:"name"`
+	PaymentMethod     string `gorm:"column:payment_method" json:"payment_method"`
+	ProviderType      string `gorm:"column:provider_type" json:"provider_type"`
+	MerchantIdentity  string `gorm:"column:merchant_identity" json:"merchant_identity"`
+	Credentials       JSONB  `gorm:"column:credentials;type:jsonb" json:"-"`
+	CredentialVersion int64  `gorm:"column:credential_version" json:"credential_version"`
+	Status            int    `gorm:"column:status" json:"status"`
+	Remark            string `gorm:"column:remark" json:"remark"`
+}
+
+func (PaymentMerchant) TableName() string { return "tb_payment_merchant" }
+
+// PaymentMerchantPool 是一种支付方式的商户轮询池。
+type PaymentMerchantPool struct {
+	gorm.Model
+	BaseModel           `gorm:"embedded"`
+	Name                string     `gorm:"column:name" json:"name"`
+	PaymentMethod       string     `gorm:"column:payment_method" json:"payment_method"`
+	Status              int        `gorm:"column:status" json:"status"`
+	Strategy            string     `gorm:"column:strategy" json:"strategy"`
+	ThresholdAmount     *int64     `gorm:"column:threshold_amount" json:"threshold_amount,omitempty"`
+	ThresholdCount      *int64     `gorm:"column:threshold_count" json:"threshold_count,omitempty"`
+	StatisticCycle      *string    `gorm:"column:statistic_cycle" json:"statistic_cycle,omitempty"`
+	TimePeriodValue     *int64     `gorm:"column:time_period_value" json:"time_period_value,omitempty"`
+	TimePeriodUnit      *string    `gorm:"column:time_period_unit" json:"time_period_unit,omitempty"`
+	TimePeriodStartedAt *time.Time `gorm:"column:time_period_started_at" json:"time_period_started_at,omitempty"`
+	RoutingEpoch        int64      `gorm:"column:routing_epoch" json:"routing_epoch"`
+	Remark              string     `gorm:"column:remark" json:"remark"`
+}
+
+func (PaymentMerchantPool) TableName() string { return "tb_payment_merchant_pool" }
+
+// PaymentMerchantPoolMember 是商户池内按顺序参与轮询的商户。
+type PaymentMerchantPoolMember struct {
+	gorm.Model
+	BaseModel  `gorm:"embedded"`
+	PoolID     uint  `gorm:"column:pool_id" json:"pool_id"`
+	MerchantID uint  `gorm:"column:merchant_id" json:"merchant_id"`
+	SortOrder  int64 `gorm:"column:sort_order" json:"sort_order"`
+}
+
+func (PaymentMerchantPoolMember) TableName() string { return "tb_payment_merchant_pool_member" }
+
+// WechatAuthorization 是 C 端微信 OAuth、小程序与支付 AppID 的全局授权配置。
+type WechatAuthorization struct {
+	gorm.Model
+	BaseModel          `gorm:"embedded"`
+	OaAppID            string `gorm:"column:oa_app_id" json:"oa_app_id"`
+	OaAppSecret        string `gorm:"column:oa_app_secret" json:"-"`
+	OaToken            string `gorm:"column:oa_token" json:"-"`
+	OaAesKey           string `gorm:"column:oa_aes_key" json:"-"`
+	OaOAuthRedirectURL string `gorm:"column:oa_oauth_redirect_url" json:"oa_oauth_redirect_url"`
+	MiniappAppID       string `gorm:"column:miniapp_app_id" json:"miniapp_app_id"`
+	MiniappAppSecret   string `gorm:"column:miniapp_app_secret" json:"-"`
+	CredentialVersion  int64  `gorm:"column:credential_version" json:"credential_version"`
+	Status             int    `gorm:"column:status" json:"status"`
+}
+
+func (WechatAuthorization) TableName() string { return "tb_wechat_authorization" }
+
+// PaymentMerchantRoutingSuccess 是支付首次成功的唯一统计事实。
+type PaymentMerchantRoutingSuccess struct {
+	ID           uint      `gorm:"column:id;primaryKey" json:"id"`
+	PaymentID    uint      `gorm:"column:payment_id" json:"payment_id"`
+	MerchantID   uint      `gorm:"column:merchant_id" json:"merchant_id"`
+	PoolID       uint      `gorm:"column:pool_id" json:"pool_id"`
+	RoutingEpoch int64     `gorm:"column:routing_epoch" json:"routing_epoch"`
+	Amount       int64     `gorm:"column:amount" json:"amount"`
+	PaidAt       time.Time `gorm:"column:paid_at" json:"paid_at"`
+	CreatedAt    time.Time `gorm:"column:created_at" json:"created_at"`
+}
+
+func (PaymentMerchantRoutingSuccess) TableName() string { return "tb_payment_merchant_routing_success" }

internal/polling/package_activation_handler.go

@@ -223,29 +223,14 @@ func (h *PackageActivationHandler) findAndActivateOrphanPackages(ctx context.Con
 	count := 0
 	for _, usage := range orphanUsages {
 		carrierType, carrierID := h.getCarrierInfo(usage)
-		activated, activationErr := h.activationService.ActivateNextPendingMainPackage(ctx, carrierType, carrierID)
-		if activationErr != nil {
-			h.logger.Warn("孤儿套餐同步激活失败",
+		if err := h.enqueueActivationTask(ctx, usage.ID, carrierType, carrierID, "orphan_recovery"); err != nil {
+			h.logger.Warn("提交孤儿套餐激活任务失败",
 				zap.Uint("package_usage_id", usage.ID),
 				zap.String("carrier_type", carrierType),
 				zap.Uint("carrier_id", carrierID),
-				zap.String("activation_source", "orphan_recovery"),
-				zap.Error(activationErr))
+				zap.Error(err))
 			continue
 		}
-		if !activated {
-			h.logger.Info("孤儿套餐本轮未激活",
-				zap.Uint("package_usage_id", usage.ID),
-				zap.String("carrier_type", carrierType),
-				zap.Uint("carrier_id", carrierID),
-				zap.String("activation_source", "orphan_recovery"))
-			continue
-		}
-		h.logger.Info("孤儿套餐同步激活成功",
-			zap.Uint("package_usage_id", usage.ID),
-			zap.String("carrier_type", carrierType),
-			zap.Uint("carrier_id", carrierID),
-			zap.String("activation_source", "orphan_recovery"))
 		count++
 	}
 
@@ -268,7 +253,8 @@ func (h *PackageActivationHandler) findExpiredMainPackages(ctx context.Context)
 }
 
 // processExpiredPackage 处理单个过期套餐
-// 流程：先同步最新流量 → 事务内标记过期和失效加油包 → 提交后同步接续并触发停机检查
+// 流程：先同步最新流量 → 事务内标记过期和失效加油包 → 提交后投递下一套餐；
+// 仅明确没有后续套餐时才触发停机检查，避免与异步激活任务竞态。
 func (h *PackageActivationHandler) processExpiredPackage(ctx context.Context, pkg *model.PackageUsage) error {
 	carrierType, carrierID := h.getCarrierInfo(pkg)
 
@@ -324,30 +310,17 @@ func (h *PackageActivationHandler) processExpiredPackage(ctx context.Context, pk
 		return nil
 	}
 
+	// 事务提交后再投递，确保消费者只能读取到旧套餐已经过期的状态。
 	if carrierType != "" && carrierID > 0 {
-		activated, activationErr := h.activationService.ActivateNextPendingMainPackage(ctx, carrierType, carrierID)
-		if activationErr != nil {
-			h.logger.Warn("过期后同步接续套餐失败",
-				zap.Uint("expired_package_usage_id", pkg.ID),
-				zap.String("carrier_type", carrierType),
-				zap.Uint("carrier_id", carrierID),
-				zap.String("activation_source", "expired_package"),
-				zap.Error(activationErr))
-		} else if activated {
-			h.logger.Info("过期后同步接续套餐成功",
-				zap.Uint("expired_package_usage_id", pkg.ID),
-				zap.String("carrier_type", carrierType),
-				zap.Uint("carrier_id", carrierID),
-				zap.String("activation_source", "expired_package"))
-		} else {
-			h.logger.Info("过期后本轮未接续套餐",
-				zap.Uint("expired_package_usage_id", pkg.ID),
-				zap.String("carrier_type", carrierType),
-				zap.Uint("carrier_id", carrierID),
-				zap.String("activation_source", "expired_package"))
+		activationEnqueued, err := h.activateNextPackage(ctx, h.db.WithContext(ctx), carrierType, carrierID)
+		if err != nil {
+			// 激活结果未知时不能将其当作无套餐；孤儿扫描和套餐轮询会继续兜底。
+			return err
+		}
+		if activationEnqueued {
+			return nil
 		}
 		h.triggerStopAfterExpiry(ctx, carrierType, carrierID)
-		return activationErr
 	}
 
 	return nil
@@ -401,8 +374,36 @@ func (h *PackageActivationHandler) getCarrierInfo(pkg *model.PackageUsage) (stri
 	return "", 0
 }
 
-// triggerStopAfterExpiry 套餐过期后异步触发停机检查
-// 仅在确认无后续生效套餐时有效；CheckAndStopCard 内部有幂等保护，重复调用安全
+// activateNextPackage 提交下一个待生效主套餐的异步激活任务。
+// 返回 true 表示已找到并成功提交后续套餐；false 表示不存在后续套餐。
+func (h *PackageActivationHandler) activateNextPackage(ctx context.Context, tx *gorm.DB, carrierType string, carrierID uint) (bool, error) {
+	var nextPkg model.PackageUsage
+	query := tx.Where("status = ?", constants.PackageUsageStatusPending).
+		Where("master_usage_id IS NULL").
+		Order("priority ASC, created_at ASC, id ASC").
+		Limit(1)
+
+	if carrierType == constants.AssetTypeIotCard {
+		query = query.Where("iot_card_id = ?", carrierID)
+	} else if carrierType == constants.AssetTypeDevice {
+		query = query.Where("device_id = ?", carrierID)
+	}
+
+	if err := query.First(&nextPkg).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return false, nil
+		}
+		return false, err
+	}
+
+	if err := h.enqueueActivationTask(ctx, nextPkg.ID, carrierType, carrierID, "queue"); err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
+// triggerStopAfterExpiry 在明确无后续套餐时异步触发停机检查。
+// 后续套餐存在时，停机重评估由激活任务在完成后顺序执行。
 func (h *PackageActivationHandler) triggerStopAfterExpiry(ctx context.Context, carrierType string, carrierID uint) {
 	if h.stopResumeCallback == nil {
 		return
@@ -441,6 +442,42 @@ func (h *PackageActivationHandler) triggerStopAfterExpiry(ctx context.Context, c
 	}
 }
 
+// reconcileCarrierAfterActivation 在套餐激活任务完成后按最新事实重评估停复机。
+// 它必须在激活调用返回后执行，不能与激活任务并发读取过期权益快照。
+func (h *PackageActivationHandler) reconcileCarrierAfterActivation(ctx context.Context, packageUsageID uint, carrierType string, carrierID uint) error {
+	if h.stopResumeCallback == nil {
+		h.logger.Warn("套餐激活后停复机回调未注入，跳过重评估",
+			zap.Uint("package_usage_id", packageUsageID),
+			zap.String("carrier_type", carrierType),
+			zap.Uint("carrier_id", carrierID))
+		return nil
+	}
+	if carrierID == 0 {
+		return errors.New(errors.CodeInvalidParam, "套餐使用记录缺少有效载体")
+	}
+
+	if carrierType == constants.AssetTypeIotCard {
+		if err := h.stopResumeCallback.CheckAndStopCard(ctx, carrierID); err != nil {
+			return err
+		}
+		return nil
+	}
+	if carrierType != constants.AssetTypeDevice {
+		return errors.New(errors.CodeInvalidParam, "套餐使用记录载体类型无效")
+	}
+
+	bindings, err := h.deviceSimBinding.ListByDeviceID(ctx, carrierID)
+	if err != nil {
+		return err
+	}
+	for _, binding := range bindings {
+		if err := h.stopResumeCallback.CheckAndStopCard(ctx, binding.IotCardID); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
 // enqueueActivationTask 提交套餐激活任务到 Asynq
 func (h *PackageActivationHandler) enqueueActivationTask(ctx context.Context, packageUsageID uint, carrierType string, carrierID uint, activationType string) error {
 	linkage := auditcontext.From(ctx)
@@ -509,14 +546,7 @@ func (h *PackageActivationHandler) HandlePackageQueueActivation(ctx context.Cont
 		return err
 	}
 
-	// 幂等性检查：如果已经是生效状态，跳过
-	if pkg.Status == constants.PackageUsageStatusActive {
-		h.logger.Info("套餐已激活，跳过",
-			zap.Uint("package_usage_id", payload.PackageUsageID))
-		return nil
-	}
-
-	// 调用 ActivationService 执行激活
+	// 调用 ActivationService 执行激活。即使套餐已由其他任务激活，仍须重新评估停复机。
 	if h.activationService != nil {
 		if err := h.activationService.ActivateSpecificPackage(ctx, payload.PackageUsageID); err != nil {
 			h.logger.Error("套餐激活失败",
@@ -531,8 +561,20 @@ func (h *PackageActivationHandler) HandlePackageQueueActivation(ctx context.Cont
 		return errors.New(errors.CodeInternalError, "激活服务未注入，无法执行套餐激活")
 	}
 
-	h.logger.Info("套餐激活成功",
-		zap.Uint("package_usage_id", payload.PackageUsageID))
+	carrierType, carrierID := h.getCarrierInfo(&pkg)
+	if err := h.reconcileCarrierAfterActivation(ctx, payload.PackageUsageID, carrierType, carrierID); err != nil {
+		h.logger.Error("套餐激活后停复机重评估失败",
+			zap.Uint("package_usage_id", payload.PackageUsageID),
+			zap.String("carrier_type", carrierType),
+			zap.Uint("carrier_id", carrierID),
+			zap.Error(err))
+		return err
+	}
+
+	h.logger.Info("套餐激活及停复机重评估完成",
+		zap.Uint("package_usage_id", payload.PackageUsageID),
+		zap.String("carrier_type", carrierType),
+		zap.Uint("carrier_id", carrierID))
 
 	return nil
 }

internal/polling/queue_manager.go

@@ -98,6 +98,20 @@ func (m *PollingQueueManager) Requeue(ctx context.Context, cardID uint, taskType
 	}).Err()
 }
 
+// EnsureQueued 仅在任务当前不在分片队列中时补入任务，不覆盖已有任务的执行时间。
+func (m *PollingQueueManager) EnsureQueued(ctx context.Context, cardID uint, taskType string, nextCheckAt time.Time) (bool, error) {
+	shardID := int(cardID) % m.shardCount
+	key := constants.RedisPollingShardQueueKey(shardID, taskType)
+	added, err := m.redis.ZAddArgs(ctx, key, redis.ZAddArgs{
+		NX: true,
+		Members: []redis.Z{{
+			Score:  float64(nextCheckAt.Unix()),
+			Member: fmt.Sprintf("%d", cardID),
+		}},
+	}).Result()
+	return added > 0, err
+}
+
 // RemoveFromAllQueues 从所有分片的所有5个队列（realname/carddata/package/protect/card_status）移除指定卡
 // 修复 Bug3：旧实现漏掉 protect 队列
 func (m *PollingQueueManager) RemoveFromAllQueues(ctx context.Context, cardID uint) error {

internal/query/asset/package_history.go

@@ -0,0 +1,304 @@
+package asset
+
+import (
+	"context"
+	"sort"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"gorm.io/gorm"
+)
+
+const relationshipStatusMasterMissing = "master_missing"
+
+// PackageHistoryQuery 读取资产范围内的套餐使用关系。
+type PackageHistoryQuery struct {
+	db *gorm.DB
+}
+
+// PackageHistoryInput 定义已完成入口授权后的套餐历史读取范围。
+type PackageHistoryInput struct {
+	AssetType   string
+	AssetID     uint
+	Generation  *int
+	Status      *int
+	PackageType *string
+	Page        int
+	PageSize    int
+}
+
+// PackageHistoryResult 保存筛选后的顶层关系组总数和分页后的关系组。
+type PackageHistoryResult struct {
+	Total int64
+	Items []*PackageHistoryNode
+}
+
+// PackageHistoryNode 保存一个套餐使用记录及其可展示关联子项。
+type PackageHistoryNode struct {
+	Usage              *model.PackageUsage
+	Children           []*PackageHistoryNode
+	RelationshipStatus string
+}
+
+type packageUsagePresence struct {
+	ID         uint
+	IotCardID  uint
+	DeviceID   uint
+	Generation int
+	DeletedAt  gorm.DeletedAt
+}
+
+// NewPackageHistoryQuery 创建套餐历史关系查询。
+func NewPackageHistoryQuery(db *gorm.DB) *PackageHistoryQuery {
+	return &PackageHistoryQuery{db: db}
+}
+
+// List 在既有资产和世代范围内读取完整关系，再按整组应用筛选、排序和分页。
+func (q *PackageHistoryQuery) List(ctx context.Context, input PackageHistoryInput) (*PackageHistoryResult, error) {
+	query, err := q.baseUsageQuery(ctx, input)
+	if err != nil {
+		return nil, err
+	}
+
+	var usages []*model.PackageUsage
+	if err := query.Find(&usages).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询套餐历史失败")
+	}
+
+	usageByID := make(map[uint]*model.PackageUsage, len(usages))
+	for _, usage := range usages {
+		usageByID[usage.ID] = usage
+	}
+
+	missingMasterIDs := unresolvedMasterIDs(usages, usageByID)
+	presentMasters, err := q.lookupMasterUsagePresence(ctx, missingMasterIDs)
+	if err != nil {
+		return nil, err
+	}
+
+	items := make([]*PackageHistoryNode, 0, len(usages))
+	nodes := make(map[uint]*PackageHistoryNode, len(usages))
+	for _, usage := range usages {
+		nodes[usage.ID] = &PackageHistoryNode{Usage: usage, Children: make([]*PackageHistoryNode, 0)}
+	}
+	for _, usage := range usages {
+		node := nodes[usage.ID]
+		if usage.MasterUsageID == nil {
+			items = append(items, node)
+			continue
+		}
+
+		master, inRange := nodes[*usage.MasterUsageID]
+		if inRange {
+			master.Children = append(master.Children, node)
+			continue
+		}
+		if _, exists := presentMasters[*usage.MasterUsageID]; exists {
+			return nil, errors.New(errors.CodeDatabaseError, "读取套餐历史关联失败")
+		}
+		node.RelationshipStatus = relationshipStatusMasterMissing
+		items = append(items, node)
+	}
+
+	matchingPackageIDs, err := q.matchingPackageIDs(ctx, input.PackageType, usages)
+	if err != nil {
+		return nil, err
+	}
+	items = filterPackageHistoryGroups(items, input.Status, matchingPackageIDs)
+	sortPackageHistoryGroups(items)
+	total := int64(len(items))
+
+	return &PackageHistoryResult{
+		Total: total,
+		Items: paginatePackageHistoryGroups(items, input.Page, input.PageSize),
+	}, nil
+}
+
+func (q *PackageHistoryQuery) baseUsageQuery(ctx context.Context, input PackageHistoryInput) (*gorm.DB, error) {
+	query := q.db.WithContext(ctx).Model(&model.PackageUsage{})
+	switch input.AssetType {
+	case "card":
+		query = query.Where("iot_card_id = ?", input.AssetID)
+	case "device":
+		query = query.Where("device_id = ?", input.AssetID)
+	default:
+		return nil, errors.New(errors.CodeInvalidParam, "资产类型非法")
+	}
+	if input.Generation != nil {
+		query = query.Where("generation = ?", *input.Generation)
+	}
+	return query, nil
+}
+
+func (q *PackageHistoryQuery) matchingPackageIDs(ctx context.Context, packageType *string, usages []*model.PackageUsage) (map[uint]struct{}, error) {
+	if packageType == nil {
+		return nil, nil
+	}
+
+	usagePackageIDs := collectPackageHistoryUsagePackageIDs(usages)
+	result := make(map[uint]struct{})
+	if len(usagePackageIDs) == 0 {
+		return result, nil
+	}
+
+	var ids []uint
+	if err := q.db.WithContext(ctx).Model(&model.Package{}).
+		Where("id IN ? AND package_type = ?", usagePackageIDs, *packageType).
+		Pluck("id", &ids).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询套餐类型资格失败")
+	}
+	for _, id := range ids {
+		result[id] = struct{}{}
+	}
+	return result, nil
+}
+
+func collectPackageHistoryUsagePackageIDs(usages []*model.PackageUsage) []uint {
+	ids := make([]uint, 0, len(usages))
+	seen := make(map[uint]struct{}, len(usages))
+	for _, usage := range usages {
+		if usage == nil || usage.PackageID == 0 {
+			continue
+		}
+		if _, exists := seen[usage.PackageID]; exists {
+			continue
+		}
+		seen[usage.PackageID] = struct{}{}
+		ids = append(ids, usage.PackageID)
+	}
+	return ids
+}
+
+func filterPackageHistoryGroups(items []*PackageHistoryNode, status *int, packageIDs map[uint]struct{}) []*PackageHistoryNode {
+	filtered := make([]*PackageHistoryNode, 0, len(items))
+	for _, item := range items {
+		if matchesPackageHistoryUsage(item.Usage, status, packageIDs) {
+			filtered = append(filtered, item)
+			continue
+		}
+		for _, child := range item.Children {
+			if matchesPackageHistoryUsage(child.Usage, status, packageIDs) {
+				filtered = append(filtered, item)
+				break
+			}
+		}
+	}
+	return filtered
+}
+
+func matchesPackageHistoryUsage(usage *model.PackageUsage, status *int, packageIDs map[uint]struct{}) bool {
+	if status != nil && usage.Status != *status {
+		return false
+	}
+	if packageIDs == nil {
+		return true
+	}
+	_, ok := packageIDs[usage.PackageID]
+	return ok
+}
+
+func sortPackageHistoryGroups(items []*PackageHistoryNode) {
+	for _, item := range items {
+		sort.Slice(item.Children, func(i, j int) bool {
+			return packageHistoryChildLess(item.Children[i].Usage, item.Children[j].Usage)
+		})
+	}
+	sort.Slice(items, func(i, j int) bool {
+		left := items[i].Usage
+		right := items[j].Usage
+		if left.CreatedAt.Equal(right.CreatedAt) {
+			return left.ID > right.ID
+		}
+		return left.CreatedAt.After(right.CreatedAt)
+	})
+}
+
+func packageHistoryChildLess(left, right *model.PackageUsage) bool {
+	leftBucket := packageHistoryChildBucket(left)
+	rightBucket := packageHistoryChildBucket(right)
+	if leftBucket != rightBucket {
+		return leftBucket < rightBucket
+	}
+
+	leftTime := left.CreatedAt
+	rightTime := right.CreatedAt
+	if leftBucket == 0 {
+		leftTime = *left.ActivatedAt
+		rightTime = *right.ActivatedAt
+	}
+	if leftTime.Equal(rightTime) {
+		return left.ID < right.ID
+	}
+	return leftTime.Before(rightTime)
+}
+
+func packageHistoryChildBucket(usage *model.PackageUsage) int {
+	if usage.Status == constants.PackageUsageStatusPending {
+		return 2
+	}
+	if usage.ActivatedAt != nil {
+		return 0
+	}
+	return 1
+}
+
+func paginatePackageHistoryGroups(items []*PackageHistoryNode, page, pageSize int) []*PackageHistoryNode {
+	if len(items) == 0 {
+		return make([]*PackageHistoryNode, 0)
+	}
+	if page < 1 {
+		page = 1
+	}
+	if pageSize < 1 {
+		pageSize = 1
+	}
+	if page > (len(items)-1)/pageSize+1 {
+		return make([]*PackageHistoryNode, 0)
+	}
+	start := (page - 1) * pageSize
+	end := start + pageSize
+	if end > len(items) {
+		end = len(items)
+	}
+	return items[start:end]
+}
+
+func unresolvedMasterIDs(usages []*model.PackageUsage, usageByID map[uint]*model.PackageUsage) []uint {
+	ids := make([]uint, 0)
+	seen := make(map[uint]struct{})
+	for _, usage := range usages {
+		if usage.MasterUsageID == nil {
+			continue
+		}
+		masterID := *usage.MasterUsageID
+		if _, found := usageByID[masterID]; found {
+			continue
+		}
+		if _, alreadySeen := seen[masterID]; alreadySeen {
+			continue
+		}
+		seen[masterID] = struct{}{}
+		ids = append(ids, masterID)
+	}
+	return ids
+}
+
+func (q *PackageHistoryQuery) lookupMasterUsagePresence(ctx context.Context, ids []uint) (map[uint]packageUsagePresence, error) {
+	found := make(map[uint]packageUsagePresence, len(ids))
+	if len(ids) == 0 {
+		return found, nil
+	}
+
+	var records []packageUsagePresence
+	if err := q.db.WithContext(ctx).Unscoped().Model(&model.PackageUsage{}).
+		Select("id, iot_card_id, device_id, generation, deleted_at").
+		Where("id IN ?", ids).
+		Find(&records).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "核对套餐主记录失败")
+	}
+	for _, record := range records {
+		found[record.ID] = record
+	}
+	return found, nil
+}

internal/query/employeecollection/application.go

@@ -0,0 +1,308 @@
+package employeecollection
+
+import (
+	"context"
+
+	"gorm.io/gorm"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+)
+
+// ApplicationQuery 查询员工代收款核销申请列表与详情。
+// Query 只做权限范围、筛选、分页与 DTO 投影，不修改任何状态。
+type ApplicationQuery struct {
+	db *gorm.DB
+}
+
+// NewApplicationQuery 创建核销申请查询。
+func NewApplicationQuery(db *gorm.DB) *ApplicationQuery {
+	return &ApplicationQuery{db: db}
+}
+
+// List 分页查询当前可见范围内的核销申请。
+func (q *ApplicationQuery) List(
+	ctx context.Context,
+	request dto.EmployeeCollectionApplicationListRequest,
+) (*dto.EmployeeCollectionApplicationListResponse, error) {
+	query, err := q.applyApplicationScope(ctx, request)
+	if err != nil {
+		return nil, err
+	}
+	page, pageSize := normalizePage(request.Page, request.PageSize)
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询核销申请总数失败")
+	}
+	var applications []model.EmployeeCollectionApplication
+	if err := query.Order("created_at DESC, id DESC").
+		Offset((page - 1) * pageSize).Limit(pageSize).
+		Find(&applications).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询核销申请列表失败")
+	}
+	list := make([]*dto.EmployeeCollectionApplicationResponse, 0, len(applications))
+	for index := range applications {
+		list = append(list, ProjectApplication(&applications[index]))
+	}
+	return &dto.EmployeeCollectionApplicationListResponse{
+		List: list, Total: total, Page: page, PageSize: pageSize,
+	}, nil
+}
+
+// Detail 返回当前可见范围内的核销申请详情，包含全部分摊与审批尝试历史。
+// 不可见与不存在返回同一错误，不产生可枚举差异。
+func (q *ApplicationQuery) Detail(ctx context.Context, id uint) (*dto.EmployeeCollectionApplicationDetailResponse, error) {
+	if q == nil || q.db == nil || id == 0 {
+		return nil, errors.New(errors.CodeEmployeeCollectionApplicationNotFound)
+	}
+	scoped, err := applyApplicationVisibility(ctx, q.db.WithContext(ctx).Model(&model.EmployeeCollectionApplication{}))
+	if err != nil {
+		return nil, err
+	}
+	var application model.EmployeeCollectionApplication
+	if err := scoped.Where("id = ?", id).First(&application).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeEmployeeCollectionApplicationNotFound)
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询核销申请详情失败")
+	}
+	allocations, err := q.applicationAllocations(ctx, application.ID)
+	if err != nil {
+		return nil, err
+	}
+	attempts, err := q.applicationAttemptList(ctx, application.ID)
+	if err != nil {
+		return nil, err
+	}
+	return &dto.EmployeeCollectionApplicationDetailResponse{
+		Application: ProjectApplication(&application), Allocations: allocations, Attempts: attempts,
+	}, nil
+}
+
+// applyApplicationScope 生成同时应用可见性与筛选条件的核销申请查询。
+func (q *ApplicationQuery) applyApplicationScope(
+	ctx context.Context,
+	request dto.EmployeeCollectionApplicationListRequest,
+) (*gorm.DB, error) {
+	if q == nil || q.db == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "核销申请查询尚未配置")
+	}
+	query, err := applyApplicationVisibility(ctx, q.db.WithContext(ctx).Model(&model.EmployeeCollectionApplication{}))
+	if err != nil {
+		return nil, err
+	}
+	if request.ApplicantAccountID != nil && *request.ApplicantAccountID > 0 {
+		query = query.Where("applicant_account_id = ?", *request.ApplicantAccountID)
+	}
+	if request.PaymentMethodID != nil && *request.PaymentMethodID > 0 {
+		query = query.Where("payment_method_id = ?", *request.PaymentMethodID)
+	}
+	if request.Status != nil {
+		switch *request.Status {
+		case constants.EmployeeCollectionApplicationStatusPending,
+			constants.EmployeeCollectionApplicationStatusApproved,
+			constants.EmployeeCollectionApplicationStatusRejected,
+			constants.EmployeeCollectionApplicationStatusRevoked:
+			query = query.Where("status = ?", *request.Status)
+		default:
+			return nil, errors.New(errors.CodeInvalidParam, "不支持的核销申请状态")
+		}
+	}
+	if request.CreatedFrom != nil {
+		from, err := parseBillDate(*request.CreatedFrom)
+		if err != nil {
+			return nil, err
+		}
+		if from != nil {
+			query = query.Where("created_at >= ?", *from)
+		}
+	}
+	if request.CreatedTo != nil {
+		to, err := parseBillDate(*request.CreatedTo)
+		if err != nil {
+			return nil, err
+		}
+		if to != nil {
+			query = query.Where("created_at < ?", to.AddDate(0, 0, 1))
+		}
+	}
+	return query, nil
+}
+
+// applyApplicationVisibility 应用核销申请可见性：超级管理员见全部，其他账号仅见本人申请。
+func applyApplicationVisibility(ctx context.Context, query *gorm.DB) (*gorm.DB, error) {
+	if middleware.GetUserTypeFromContext(ctx) == constants.UserTypeSuperAdmin {
+		return query, nil
+	}
+	accountID := middleware.GetUserIDFromContext(ctx)
+	if accountID == 0 {
+		return nil, errors.New(errors.CodeUnauthorized)
+	}
+	return query.Where("applicant_account_id = ?", accountID), nil
+}
+
+// applicationAllocations 读取申请的全部分摊并附带目标账单只读摘要。
+func (q *ApplicationQuery) applicationAllocations(
+	ctx context.Context,
+	applicationID uint,
+) ([]*dto.EmployeeCollectionApplicationAllocationResponse, error) {
+	var allocations []model.EmployeeCollectionApplicationAllocation
+	if err := q.db.WithContext(ctx).Where("application_id = ?", applicationID).
+		Order("bill_id ASC, id ASC").Find(&allocations).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询核销申请分摊失败")
+	}
+	billIDs := make([]uint, 0, len(allocations))
+	for index := range allocations {
+		billIDs = append(billIDs, allocations[index].BillID)
+	}
+	bills := make(map[uint]model.EmployeeCollectionBill, len(billIDs))
+	if len(billIDs) > 0 {
+		var loaded []model.EmployeeCollectionBill
+		if err := q.db.WithContext(ctx).Where("id IN ?", billIDs).Find(&loaded).Error; err != nil {
+			return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询核销分摊目标账单失败")
+		}
+		for index := range loaded {
+			bills[loaded[index].ID] = loaded[index]
+		}
+	}
+	result := make([]*dto.EmployeeCollectionApplicationAllocationResponse, 0, len(allocations))
+	for index := range allocations {
+		allocation := allocations[index]
+		bill := bills[allocation.BillID]
+		result = append(result, &dto.EmployeeCollectionApplicationAllocationResponse{
+			ID: allocation.ID, BillID: allocation.BillID, Amount: allocation.Amount,
+			Status: allocation.Status, StatusName: constants.GetEmployeeCollectionAllocationStatusName(allocation.Status),
+			ReleasedAt:     allocation.ReleasedAt,
+			BillSourceType: bill.SourceType, BillSourceNo: bill.SourceNo,
+			BillReceivableAmount: bill.ReceivableAmount, BillReceivedAmount: bill.ReceivedAmount,
+			BillReservedAmount: bill.ReservedAmount,
+			BillStatus:         bill.Status, BillStatusName: constants.GetEmployeeCollectionBillStatusName(bill.Status),
+			CreatedAt: allocation.CreatedAt,
+		})
+	}
+	return result, nil
+}
+
+// applicationAttemptList 读取申请的全部审批尝试记录与审批实例状态。
+func (q *ApplicationQuery) applicationAttemptList(
+	ctx context.Context,
+	applicationID uint,
+) ([]*dto.EmployeeCollectionBillAttemptResponse, error) {
+	var attempts []model.EmployeeCollectionApplicationAttempt
+	if err := q.db.WithContext(ctx).Where("application_id = ?", applicationID).
+		Order("attempt_no ASC, id ASC").Find(&attempts).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询核销审批尝试记录失败")
+	}
+	approvalStatus, approvalOpinions, err := approvalStatusOfAttempts(ctx, q.db, attempts)
+	if err != nil {
+		return nil, err
+	}
+	return attemptResponses(applicationID, attempts, approvalStatus, approvalOpinions)
+}
+
+// ProjectApplication 将核销申请事实投影为对外响应，附件只返回对象键引用。
+func ProjectApplication(application *model.EmployeeCollectionApplication) *dto.EmployeeCollectionApplicationResponse {
+	if application == nil {
+		return nil
+	}
+	vouchers := []string(application.PaymentVoucherKeys)
+	if vouchers == nil {
+		vouchers = []string{}
+	}
+	return &dto.EmployeeCollectionApplicationResponse{
+		ID: application.ID, ApplicantAccountID: application.ApplicantAccountID,
+		ActingOperatorID: application.ActingOperatorID, ActingReason: application.ActingReason,
+		PaymentMethodID: application.PaymentMethodID, PaymentMethodCode: application.PaymentMethodCode,
+		PaymentMethodName: application.PaymentMethodName, PaidAmount: application.PaidAmount,
+		PayerName: application.PayerName, PaidAt: application.PaidAt,
+		ExternalTransactionNo: application.ExternalTransactionNo, PaymentVoucherKeys: vouchers,
+		Remark: application.Remark, Status: application.Status,
+		StatusName:               constants.GetEmployeeCollectionApplicationStatusName(application.Status),
+		LatestAttemptID:          application.LatestAttemptID,
+		LatestApprovalInstanceID: application.LatestApprovalInstanceID,
+		DecidedAt:                application.DecidedAt, TerminalReason: application.TerminalReason,
+		CreatedAt: application.CreatedAt, UpdatedAt: application.UpdatedAt,
+	}
+}
+
+// ApplicationSubmitProjection 是创建或重提核销申请返回的投影输入。
+type ApplicationSubmitProjection struct {
+	Application    *model.EmployeeCollectionApplication
+	Attempt        *model.EmployeeCollectionApplicationAttempt
+	Allocations    []*model.EmployeeCollectionApplicationAllocation
+	Bills          []*model.EmployeeCollectionBill
+	InstanceID     uint
+	InstanceStatus int
+}
+
+// ProjectApplicationSubmit 组装创建或重提核销申请的响应。
+// 附件只返回对象键引用，审批状态取本次创建的通用审批实例状态，不返回对象存储内容。
+func ProjectApplicationSubmit(projection ApplicationSubmitProjection) (*dto.EmployeeCollectionApplicationSubmitResponse, error) {
+	allocations, err := projectSubmitAllocations(projection.Allocations, projection.Bills)
+	if err != nil {
+		return nil, err
+	}
+	var attempts []*dto.EmployeeCollectionBillAttemptResponse
+	if projection.Attempt != nil {
+		approvalStatus := map[uint]int{}
+		if projection.InstanceID > 0 {
+			approvalStatus[projection.InstanceID] = projection.InstanceStatus
+		}
+		attempts, err = attemptResponses(
+			projection.Attempt.ApplicationID,
+			[]model.EmployeeCollectionApplicationAttempt{*projection.Attempt},
+			approvalStatus, map[uint]string{},
+		)
+		if err != nil {
+			return nil, err
+		}
+	}
+	response := &dto.EmployeeCollectionApplicationSubmitResponse{
+		Application:        ProjectApplication(projection.Application),
+		Allocations:        allocations,
+		ApprovalInstanceID: projection.InstanceID,
+		ApprovalStatus:     projection.InstanceStatus,
+		ApprovalStatusName: constants.GetApprovalStatusName(projection.InstanceStatus),
+	}
+	if len(attempts) > 0 {
+		response.Attempt = attempts[0]
+	}
+	return response, nil
+}
+
+// projectSubmitAllocations 将分摊与目标账单摘要投影为响应。
+func projectSubmitAllocations(
+	allocations []*model.EmployeeCollectionApplicationAllocation,
+	bills []*model.EmployeeCollectionBill,
+) ([]*dto.EmployeeCollectionApplicationAllocationResponse, error) {
+	billByID := make(map[uint]*model.EmployeeCollectionBill, len(bills))
+	for _, bill := range bills {
+		if bill != nil {
+			billByID[bill.ID] = bill
+		}
+	}
+	result := make([]*dto.EmployeeCollectionApplicationAllocationResponse, 0, len(allocations))
+	for _, allocation := range allocations {
+		if allocation == nil {
+			continue
+		}
+		bill := billByID[allocation.BillID]
+		if bill == nil {
+			return nil, errors.New(errors.CodeInternalError, "核销分摊缺少目标账单事实")
+		}
+		result = append(result, &dto.EmployeeCollectionApplicationAllocationResponse{
+			ID: allocation.ID, BillID: allocation.BillID, Amount: allocation.Amount,
+			Status: allocation.Status, StatusName: constants.GetEmployeeCollectionAllocationStatusName(allocation.Status),
+			ReleasedAt:     allocation.ReleasedAt,
+			BillSourceType: bill.SourceType, BillSourceNo: bill.SourceNo,
+			BillReceivableAmount: bill.ReceivableAmount, BillReceivedAmount: bill.ReceivedAmount,
+			BillReservedAmount: bill.ReservedAmount,
+			BillStatus:         bill.Status, BillStatusName: constants.GetEmployeeCollectionBillStatusName(bill.Status),
+			CreatedAt: allocation.CreatedAt,
+		})
+	}
+	return result, nil
+}

internal/query/employeecollection/bill.go

@@ -0,0 +1,497 @@
+package employeecollection
+
+import (
+	"context"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/bytedance/sonic"
+	"gorm.io/gorm"
+
+	employeecollectiondomain "github.com/break/junhong_cmp_fiber/internal/domain/employeecollection"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+)
+
+// billDateLayout 是账单筛选使用的自然日格式。
+const billDateLayout = "2006-01-02"
+
+// BillQuery 查询员工代收款账单列表、统计与详情。
+// 列表与统计共用 applyBillScope 生成的同一个 *gorm.DB，禁止两处各写一套筛选。
+type BillQuery struct {
+	db *gorm.DB
+}
+
+// NewBillQuery 创建员工代收款账单查询。
+func NewBillQuery(db *gorm.DB) *BillQuery {
+	return &BillQuery{db: db}
+}
+
+// List 分页查询当前可见范围内的员工代收款账单。
+func (q *BillQuery) List(ctx context.Context, request dto.EmployeeCollectionBillListRequest) (*dto.EmployeeCollectionBillListResponse, error) {
+	query, err := q.applyBillScope(ctx, billFilterOfList(request))
+	if err != nil {
+		return nil, err
+	}
+	page, pageSize := normalizePage(request.Page, request.PageSize)
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询员工代收款账单总数失败")
+	}
+	var bills []model.EmployeeCollectionBill
+	if err := query.Order("created_at DESC, id DESC").
+		Offset((page - 1) * pageSize).Limit(pageSize).
+		Find(&bills).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询员工代收款账单列表失败")
+	}
+	list := make([]*dto.EmployeeCollectionBillResponse, 0, len(bills))
+	for index := range bills {
+		item, err := ProjectBill(&bills[index])
+		if err != nil {
+			return nil, err
+		}
+		list = append(list, item)
+	}
+	return &dto.EmployeeCollectionBillListResponse{
+		List: list, Total: total, Page: page, PageSize: pageSize,
+	}, nil
+}
+
+// Statistics 汇总当前可见范围内的应收、已核销、未核销金额与待处理账单数。
+// 使用与列表完全相同的可见性与筛选条件。
+func (q *BillQuery) Statistics(
+	ctx context.Context,
+	request dto.EmployeeCollectionBillStatisticsRequest,
+) (*dto.EmployeeCollectionBillStatisticsResponse, error) {
+	query, err := q.applyBillScope(ctx, billFilterOfStatistics(request))
+	if err != nil {
+		return nil, err
+	}
+	var row struct {
+		ReceivableTotal  int64
+		ReceivedTotal    int64
+		UnsettledTotal   int64
+		PendingBillCount int64
+	}
+	if err := query.Select(
+		`COALESCE(SUM(receivable_amount), 0) AS receivable_total,
+		 COALESCE(SUM(received_amount), 0) AS received_total,
+		 COALESCE(SUM(CASE WHEN status = ? THEN 0 ELSE receivable_amount - received_amount END), 0) AS unsettled_total,
+		 COALESCE(SUM(CASE WHEN status IN (?, ?) THEN 1 ELSE 0 END), 0) AS pending_bill_count`,
+		constants.EmployeeCollectionBillStatusClosed,
+		constants.EmployeeCollectionBillStatusPending,
+		constants.EmployeeCollectionBillStatusPartial,
+	).Scan(&row).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询员工代收款账单统计失败")
+	}
+	return &dto.EmployeeCollectionBillStatisticsResponse{
+		ReceivableTotal: row.ReceivableTotal, ReceivedTotal: row.ReceivedTotal,
+		UnsettledTotal: row.UnsettledTotal, PendingBillCount: row.PendingBillCount,
+	}, nil
+}
+
+// Detail 返回当前可见范围内的账单详情，包含退款冲销、分摊与申请审批历史。
+// 不可见与不存在返回同一错误，不产生可枚举差异。
+func (q *BillQuery) Detail(ctx context.Context, id uint) (*dto.EmployeeCollectionBillDetailResponse, error) {
+	if q == nil || q.db == nil || id == 0 {
+		return nil, errors.New(errors.CodeEmployeeCollectionBillNotFound)
+	}
+	scoped, err := applyBillVisibility(ctx, q.db.WithContext(ctx).Model(&model.EmployeeCollectionBill{}))
+	if err != nil {
+		return nil, err
+	}
+	var bill model.EmployeeCollectionBill
+	if err := scoped.Where("id = ?", id).First(&bill).Error; err != nil {
+		if err == gorm.ErrRecordNotFound {
+			return nil, errors.New(errors.CodeEmployeeCollectionBillNotFound)
+		}
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询员工代收款账单详情失败")
+	}
+	billResponse, err := ProjectBill(&bill)
+	if err != nil {
+		return nil, err
+	}
+	refunds, err := q.billRefunds(ctx, bill.ID)
+	if err != nil {
+		return nil, err
+	}
+	allocations, applicationIDs, err := q.billAllocations(ctx, bill.ID)
+	if err != nil {
+		return nil, err
+	}
+	applications, err := q.billApplications(ctx, applicationIDs)
+	if err != nil {
+		return nil, err
+	}
+	return &dto.EmployeeCollectionBillDetailResponse{
+		Bill: billResponse, Refunds: refunds, Allocations: allocations, Applications: applications,
+	}, nil
+}
+
+// applyBillScope 生成同时应用可见性与筛选条件的账单查询。
+// 列表、统计与关闭后的可见性校验都必须走这一处，避免筛选或数据范围分叉。
+func (q *BillQuery) applyBillScope(ctx context.Context, filter billFilter) (*gorm.DB, error) {
+	if q == nil || q.db == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "员工代收款账单查询尚未配置")
+	}
+	query, err := applyBillVisibility(ctx, q.db.WithContext(ctx).Model(&model.EmployeeCollectionBill{}))
+	if err != nil {
+		return nil, err
+	}
+	return applyBillFilters(query, filter)
+}
+
+// billFilter 账单列表与统计共用的筛选条件，屏蔽两种请求 DTO 的字段差异。
+type billFilter struct {
+	SourceType      *string
+	SourceNo        *string
+	Status          *int
+	DebtorAccountID *uint
+	CustomerID      *uint
+	CreatedFrom     *string
+	CreatedTo       *string
+}
+
+// billFilterOfList 投影账单列表请求的筛选字段。
+func billFilterOfList(request dto.EmployeeCollectionBillListRequest) billFilter {
+	return billFilter{
+		SourceType: request.SourceType, SourceNo: request.SourceNo, Status: request.Status,
+		DebtorAccountID: request.DebtorAccountID, CustomerID: request.CustomerID,
+		CreatedFrom: request.CreatedFrom, CreatedTo: request.CreatedTo,
+	}
+}
+
+// billFilterOfStatistics 投影账单统计请求的筛选字段。
+func billFilterOfStatistics(request dto.EmployeeCollectionBillStatisticsRequest) billFilter {
+	return billFilter{
+		SourceType: request.SourceType, SourceNo: request.SourceNo, Status: request.Status,
+		DebtorAccountID: request.DebtorAccountID, CustomerID: request.CustomerID,
+		CreatedFrom: request.CreatedFrom, CreatedTo: request.CreatedTo,
+	}
+}
+
+// applyBillVisibility 应用账单可见性：超级管理员见全部，其他账号仅见本人欠款账单。
+func applyBillVisibility(ctx context.Context, query *gorm.DB) (*gorm.DB, error) {
+	if middleware.GetUserTypeFromContext(ctx) == constants.UserTypeSuperAdmin {
+		return query, nil
+	}
+	accountID := middleware.GetUserIDFromContext(ctx)
+	if accountID == 0 {
+		return nil, errors.New(errors.CodeUnauthorized)
+	}
+	return query.Where("debtor_account_id = ?", accountID), nil
+}
+
+// applyBillFilters 应用账单列表与统计共用的筛选条件。
+func applyBillFilters(query *gorm.DB, request billFilter) (*gorm.DB, error) {
+	if request.DebtorAccountID != nil && *request.DebtorAccountID > 0 {
+		query = query.Where("debtor_account_id = ?", *request.DebtorAccountID)
+	}
+	if request.SourceType != nil {
+		sourceType := strings.TrimSpace(*request.SourceType)
+		switch sourceType {
+		case "":
+		case constants.EmployeeCollectionSourceTypeOrder, constants.EmployeeCollectionSourceTypeRecharge:
+			query = query.Where("source_type = ?", sourceType)
+		default:
+			return nil, errors.New(errors.CodeInvalidParam, "不支持的账单来源类型")
+		}
+	}
+	if request.SourceNo != nil {
+		if sourceNo := strings.TrimSpace(*request.SourceNo); sourceNo != "" {
+			query = query.Where("source_no = ?", sourceNo)
+		}
+	}
+	if request.Status != nil {
+		switch *request.Status {
+		case constants.EmployeeCollectionBillStatusPending, constants.EmployeeCollectionBillStatusPartial,
+			constants.EmployeeCollectionBillStatusSettled, constants.EmployeeCollectionBillStatusClosed:
+			query = query.Where("status = ?", *request.Status)
+		default:
+			return nil, errors.New(errors.CodeInvalidParam, "不支持的账单状态")
+		}
+	}
+	if request.CustomerID != nil && *request.CustomerID > 0 {
+		customerID := strconv.FormatUint(uint64(*request.CustomerID), 10)
+		query = query.Where("customer_snapshot->>'buyer_id' = ? OR customer_snapshot->>'shop_id' = ?", customerID, customerID)
+	}
+	if request.CreatedFrom != nil {
+		from, err := parseBillDate(*request.CreatedFrom)
+		if err != nil {
+			return nil, err
+		}
+		if from != nil {
+			query = query.Where("created_at >= ?", *from)
+		}
+	}
+	if request.CreatedTo != nil {
+		to, err := parseBillDate(*request.CreatedTo)
+		if err != nil {
+			return nil, err
+		}
+		if to != nil {
+			query = query.Where("created_at < ?", to.AddDate(0, 0, 1))
+		}
+	}
+	return query, nil
+}
+
+// parseBillDate 解析自然日筛选值；空值表示不筛选。
+func parseBillDate(value string) (*time.Time, error) {
+	trimmed := strings.TrimSpace(value)
+	if trimmed == "" {
+		return nil, nil
+	}
+	parsed, err := time.ParseInLocation(billDateLayout, trimmed, time.Local)
+	if err != nil {
+		return nil, errors.New(errors.CodeInvalidParam, "账单筛选日期格式必须为 YYYY-MM-DD")
+	}
+	return &parsed, nil
+}
+
+// billRefunds 读取账单的来源订单退款冲销关联。
+func (q *BillQuery) billRefunds(ctx context.Context, billID uint) ([]*dto.EmployeeCollectionBillRefundResponse, error) {
+	var refunds []model.EmployeeCollectionBillRefund
+	if err := q.db.WithContext(ctx).Where("bill_id = ?", billID).Order("id ASC").Find(&refunds).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询账单退款冲销关联失败")
+	}
+	result := make([]*dto.EmployeeCollectionBillRefundResponse, 0, len(refunds))
+	for index := range refunds {
+		item := refunds[index]
+		result = append(result, &dto.EmployeeCollectionBillRefundResponse{
+			ID: item.ID, RefundID: item.RefundID, SourceOrderID: item.SourceOrderID,
+			RefundAmount: item.RefundAmount, BillReceivableAmount: item.BillReceivableAmount,
+			Outcome: item.Outcome, OutcomeName: constants.GetEmployeeCollectionRefundOutcomeName(item.Outcome),
+			ReducedAmount: item.ReducedAmount, CreatedAt: item.CreatedAt,
+		})
+	}
+	return result, nil
+}
+
+// billAllocations 读取账单分摊，并返回涉及的去重申请 ID。
+func (q *BillQuery) billAllocations(ctx context.Context, billID uint) ([]*dto.EmployeeCollectionBillAllocationResponse, []uint, error) {
+	var allocations []model.EmployeeCollectionApplicationAllocation
+	if err := q.db.WithContext(ctx).Where("bill_id = ?", billID).Order("id ASC").Find(&allocations).Error; err != nil {
+		return nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "查询账单分摊失败")
+	}
+	applicationIDs := make([]uint, 0, len(allocations))
+	seen := make(map[uint]struct{}, len(allocations))
+	for index := range allocations {
+		if _, exists := seen[allocations[index].ApplicationID]; !exists {
+			seen[allocations[index].ApplicationID] = struct{}{}
+			applicationIDs = append(applicationIDs, allocations[index].ApplicationID)
+		}
+	}
+	applicationStatus := make(map[uint]int, len(applicationIDs))
+	if len(applicationIDs) > 0 {
+		var applications []model.EmployeeCollectionApplication
+		if err := q.db.WithContext(ctx).Select("id", "status").
+			Where("id IN ?", applicationIDs).Find(&applications).Error; err != nil {
+			return nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "查询账单分摊所属申请失败")
+		}
+		for index := range applications {
+			applicationStatus[applications[index].ID] = applications[index].Status
+		}
+	}
+	result := make([]*dto.EmployeeCollectionBillAllocationResponse, 0, len(allocations))
+	for index := range allocations {
+		item := allocations[index]
+		status := applicationStatus[item.ApplicationID]
+		result = append(result, &dto.EmployeeCollectionBillAllocationResponse{
+			ID: item.ID, ApplicationID: item.ApplicationID,
+			ApplicationStatus: status, ApplicationStatusName: constants.GetEmployeeCollectionApplicationStatusName(status),
+			AttemptID: item.AttemptID, Amount: item.Amount,
+			Status: item.Status, StatusName: constants.GetEmployeeCollectionAllocationStatusName(item.Status),
+			ReleasedAt: item.ReleasedAt, CreatedAt: item.CreatedAt,
+		})
+	}
+	return result, applicationIDs, nil
+}
+
+// billApplications 读取涉及该账单的申请及其审批尝试历史。
+func (q *BillQuery) billApplications(ctx context.Context, applicationIDs []uint) ([]*dto.EmployeeCollectionBillApplicationResponse, error) {
+	if len(applicationIDs) == 0 {
+		return []*dto.EmployeeCollectionBillApplicationResponse{}, nil
+	}
+	var applications []model.EmployeeCollectionApplication
+	if err := q.db.WithContext(ctx).Where("id IN ?", applicationIDs).Order("id ASC").Find(&applications).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询账单关联核销申请失败")
+	}
+	attemptsByApplication, approvalStatus, approvalOpinions, err := q.applicationAttempts(ctx, applicationIDs)
+	if err != nil {
+		return nil, err
+	}
+	result := make([]*dto.EmployeeCollectionBillApplicationResponse, 0, len(applications))
+	for index := range applications {
+		application := applications[index]
+		vouchers := []string(application.PaymentVoucherKeys)
+		if vouchers == nil {
+			vouchers = []string{}
+		}
+		attempts, err := attemptResponses(
+			application.ID, attemptsByApplication[application.ID], approvalStatus, approvalOpinions)
+		if err != nil {
+			return nil, err
+		}
+		result = append(result, &dto.EmployeeCollectionBillApplicationResponse{
+			ID: application.ID, ApplicantAccountID: application.ApplicantAccountID,
+			ActingOperatorID: application.ActingOperatorID, ActingReason: application.ActingReason,
+			PaymentMethodID: application.PaymentMethodID, PaymentMethodCode: application.PaymentMethodCode,
+			PaymentMethodName: application.PaymentMethodName, PaidAmount: application.PaidAmount,
+			PayerName: application.PayerName, PaidAt: application.PaidAt,
+			ExternalTransactionNo: application.ExternalTransactionNo, PaymentVoucherKeys: vouchers,
+			Remark: application.Remark, Status: application.Status,
+			StatusName:               constants.GetEmployeeCollectionApplicationStatusName(application.Status),
+			LatestApprovalInstanceID: application.LatestApprovalInstanceID,
+			DecidedAt:                application.DecidedAt, TerminalReason: application.TerminalReason,
+			CreatedAt: application.CreatedAt,
+			Attempts:  attempts,
+		})
+	}
+	return result, nil
+}
+
+// applicationAttempts 读取申请的审批尝试记录、审批实例状态与审批意见。
+func (q *BillQuery) applicationAttempts(
+	ctx context.Context,
+	applicationIDs []uint,
+) (map[uint][]model.EmployeeCollectionApplicationAttempt, map[uint]int, map[uint]string, error) {
+	var attempts []model.EmployeeCollectionApplicationAttempt
+	if err := q.db.WithContext(ctx).Where("application_id IN ?", applicationIDs).
+		Order("application_id ASC, attempt_no ASC").Find(&attempts).Error; err != nil {
+		return nil, nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "查询审批尝试记录失败")
+	}
+	approvalStatus, approvalOpinions, err := approvalStatusOfAttempts(ctx, q.db, attempts)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+	grouped := make(map[uint][]model.EmployeeCollectionApplicationAttempt, len(applicationIDs))
+	for index := range attempts {
+		grouped[attempts[index].ApplicationID] = append(grouped[attempts[index].ApplicationID], attempts[index])
+	}
+	return grouped, approvalStatus, approvalOpinions, nil
+}
+
+// approvalStatusOfAttempts 批量读取审批尝试记录关联的通用审批实例状态与终态审批意见。
+func approvalStatusOfAttempts(
+	ctx context.Context,
+	db *gorm.DB,
+	attempts []model.EmployeeCollectionApplicationAttempt,
+) (map[uint]int, map[uint]string, error) {
+	instanceIDs := make([]uint, 0, len(attempts))
+	for index := range attempts {
+		if attempts[index].ApprovalInstanceID != nil {
+			instanceIDs = append(instanceIDs, *attempts[index].ApprovalInstanceID)
+		}
+	}
+	approvalStatus := make(map[uint]int, len(instanceIDs))
+	approvalOpinions := make(map[uint]string, len(instanceIDs))
+	if len(instanceIDs) == 0 {
+		return approvalStatus, approvalOpinions, nil
+	}
+	columns := []string{"id", "status", "decision_snapshot"}
+	var instances []model.ApprovalInstance
+	if err := db.WithContext(ctx).Select(columns).
+		Where("id IN ?", instanceIDs).Find(&instances).Error; err != nil {
+		return nil, nil, errors.Wrap(errors.CodeDatabaseError, err, "查询审批实例状态失败")
+	}
+	for index := range instances {
+		approvalStatus[instances[index].ID] = instances[index].Status
+		if opinion := employeecollectiondomain.ExtractApprovalOpinion(instances[index].DecisionSnapshot); opinion != "" {
+			approvalOpinions[instances[index].ID] = opinion
+		}
+	}
+	return approvalStatus, approvalOpinions, nil
+}
+
+// attemptResponses 投影审批尝试记录，附件只返回对象键引用与审批实例引用。
+func attemptResponses(
+	applicationID uint,
+	attempts []model.EmployeeCollectionApplicationAttempt,
+	approvalStatus map[uint]int,
+	approvalOpinions map[uint]string,
+) ([]*dto.EmployeeCollectionBillAttemptResponse, error) {
+	result := make([]*dto.EmployeeCollectionBillAttemptResponse, 0, len(attempts))
+	for index := range attempts {
+		attempt := attempts[index]
+		if attempt.ApplicationID != applicationID {
+			continue
+		}
+		vouchers := []string(attempt.PaymentVoucherKeys)
+		if vouchers == nil {
+			vouchers = []string{}
+		}
+		snapshot := make([]map[string]any, 0)
+		if len(attempt.AllocationSnapshot) > 0 {
+			if err := sonic.Unmarshal(attempt.AllocationSnapshot, &snapshot); err != nil {
+				return nil, errors.Wrap(errors.CodeInternalError, err, "解析审批尝试分摊快照失败")
+			}
+		}
+		var status *int
+		statusName := ""
+		opinion := ""
+		if attempt.ApprovalInstanceID != nil {
+			if value, ok := approvalStatus[*attempt.ApprovalInstanceID]; ok {
+				status = &value
+				statusName = constants.GetApprovalStatusName(value)
+			}
+			opinion = approvalOpinions[*attempt.ApprovalInstanceID]
+		}
+		result = append(result, &dto.EmployeeCollectionBillAttemptResponse{
+			ID: attempt.ID, AttemptNo: attempt.AttemptNo,
+			PaymentMethodID: attempt.PaymentMethodID, PaymentMethodCode: attempt.PaymentMethodCode,
+			PaymentMethodName: attempt.PaymentMethodName, PaidAmount: attempt.PaidAmount,
+			PayerName: attempt.PayerName, PaidAt: attempt.PaidAt,
+			ExternalTransactionNo: attempt.ExternalTransactionNo, PaymentVoucherKeys: vouchers,
+			Remark: attempt.Remark, SubmittedByAccountID: attempt.SubmittedByAccountID,
+			ActingReason: attempt.ActingReason, AllocationSnapshot: snapshot,
+			ApprovalInstanceID: attempt.ApprovalInstanceID,
+			ApprovalStatus:     status, ApprovalStatusName: statusName,
+			ApprovalOpinion: opinion, CreatedAt: attempt.CreatedAt,
+		})
+	}
+	return result, nil
+}
+
+// ProjectBill 将账单事实投影为对外响应；关闭用例与查询共用同一投影。
+func ProjectBill(bill *model.EmployeeCollectionBill) (*dto.EmployeeCollectionBillResponse, error) {
+	if bill == nil {
+		return nil, errors.New(errors.CodeEmployeeCollectionBillNotFound)
+	}
+	debtorSnapshot := make(map[string]any)
+	if len(bill.DebtorSnapshot) > 0 {
+		if err := sonic.Unmarshal(bill.DebtorSnapshot, &debtorSnapshot); err != nil {
+			return nil, errors.Wrap(errors.CodeInternalError, err, "解析账单欠款人快照失败")
+		}
+	}
+	customerSnapshot := make(map[string]any)
+	if len(bill.CustomerSnapshot) > 0 {
+		if err := sonic.Unmarshal(bill.CustomerSnapshot, &customerSnapshot); err != nil {
+			return nil, errors.Wrap(errors.CodeInternalError, err, "解析账单客户快照失败")
+		}
+	}
+	remaining := int64(0)
+	if bill.Status != constants.EmployeeCollectionBillStatusClosed {
+		remaining = bill.ReceivableAmount - bill.ReceivedAmount - bill.ReservedAmount
+		if remaining < 0 {
+			remaining = 0
+		}
+	}
+	return &dto.EmployeeCollectionBillResponse{
+		ID: bill.ID, SourceType: bill.SourceType,
+		SourceTypeName: constants.GetEmployeeCollectionSourceTypeName(bill.SourceType),
+		SourceID:       bill.SourceID, SourceNo: bill.SourceNo,
+		DebtorAccountID: bill.DebtorAccountID, DebtorSnapshot: debtorSnapshot,
+		CustomerSnapshot: customerSnapshot,
+		ReceivableAmount: bill.ReceivableAmount, ReceivedAmount: bill.ReceivedAmount,
+		ReservedAmount: bill.ReservedAmount, RemainingAmount: remaining,
+		Status: bill.Status, StatusName: constants.GetEmployeeCollectionBillStatusName(bill.Status),
+		ApprovalPending: bill.ReservedAmount > 0,
+		ClosedReason:    bill.ClosedReason, ClosedAt: bill.ClosedAt,
+		CreatedAt: bill.CreatedAt, UpdatedAt: bill.UpdatedAt,
+	}, nil
+}

internal/query/employeecollection/payment_method.go

@@ -0,0 +1,99 @@
+// Package employeecollection 提供员工代收款账单与线下收款方式字典的只读投影。
+// Query 只做权限范围、筛选、分页与 DTO 投影，不修改任何状态。
+package employeecollection
+
+import (
+	"context"
+	"strings"
+
+	"gorm.io/gorm"
+
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+)
+
+// PaymentMethodQuery 查询线下收款方式字典。
+type PaymentMethodQuery struct {
+	db *gorm.DB
+}
+
+// NewPaymentMethodQuery 创建线下收款方式字典查询。
+func NewPaymentMethodQuery(db *gorm.DB) *PaymentMethodQuery {
+	return &PaymentMethodQuery{db: db}
+}
+
+// List 分页查询线下收款方式。
+// 超级管理员可查询全部字典项；其他后台账号仅返回启用项，保证停用方式不可用于新申请。
+func (q *PaymentMethodQuery) List(
+	ctx context.Context,
+	request dto.EmployeeCollectionPaymentMethodListRequest,
+) (*dto.EmployeeCollectionPaymentMethodListResponse, error) {
+	if q == nil || q.db == nil {
+		return nil, errors.New(errors.CodeServiceUnavailable, "线下收款方式查询尚未配置")
+	}
+	isSuperAdmin := middleware.GetUserTypeFromContext(ctx) == constants.UserTypeSuperAdmin
+	if !isSuperAdmin && middleware.GetUserIDFromContext(ctx) == 0 {
+		return nil, errors.New(errors.CodeUnauthorized)
+	}
+	page, pageSize := normalizePage(request.Page, request.PageSize)
+
+	query := q.db.WithContext(ctx).Model(&model.EmployeeCollectionPaymentMethod{})
+	if !isSuperAdmin {
+		query = query.Where("status = ?", constants.EmployeeCollectionPaymentMethodStatusEnabled)
+	} else if request.Enabled != nil {
+		status := constants.EmployeeCollectionPaymentMethodStatusDisabled
+		if *request.Enabled {
+			status = constants.EmployeeCollectionPaymentMethodStatusEnabled
+		}
+		query = query.Where("status = ?", status)
+	}
+	if keyword := strings.TrimSpace(request.Keyword); keyword != "" {
+		pattern := "%" + keyword + "%"
+		query = query.Where("code LIKE ? OR name LIKE ?", pattern, pattern)
+	}
+
+	var total int64
+	if err := query.Count(&total).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询线下收款方式总数失败")
+	}
+	var items []model.EmployeeCollectionPaymentMethod
+	if err := query.Order("sort_order ASC, id ASC").
+		Offset((page - 1) * pageSize).Limit(pageSize).
+		Find(&items).Error; err != nil {
+		return nil, errors.Wrap(errors.CodeDatabaseError, err, "查询线下收款方式列表失败")
+	}
+	list := make([]*dto.EmployeeCollectionPaymentMethodResponse, 0, len(items))
+	for index := range items {
+		list = append(list, toPaymentMethodResponse(&items[index]))
+	}
+	return &dto.EmployeeCollectionPaymentMethodListResponse{
+		List: list, Total: total, Page: page, PageSize: pageSize,
+	}, nil
+}
+
+// toPaymentMethodResponse 将字典项投影为对外响应，只暴露既有对象键与稳定字段。
+func toPaymentMethodResponse(paymentMethod *model.EmployeeCollectionPaymentMethod) *dto.EmployeeCollectionPaymentMethodResponse {
+	return &dto.EmployeeCollectionPaymentMethodResponse{
+		ID: paymentMethod.ID, Code: paymentMethod.Code, Name: paymentMethod.Name,
+		Enabled: paymentMethod.Status == constants.EmployeeCollectionPaymentMethodStatusEnabled,
+		Sort:    paymentMethod.SortOrder, Remark: paymentMethod.Remark,
+		CreatedAt: paymentMethod.CreatedAt, UpdatedAt: paymentMethod.UpdatedAt,
+	}
+}
+
+// normalizePage 归一化分页参数，执行 DefaultPageSize 与 MaxPageSize 上限。
+func normalizePage(page, pageSize int) (int, int) {
+	if page <= 0 {
+		page = constants.DefaultPage
+	}
+	if pageSize <= 0 {
+		pageSize = constants.DefaultPageSize
+	}
+	if pageSize > constants.MaxPageSize {
+		pageSize = constants.MaxPageSize
+	}
+	return page, pageSize
+}

internal/query/retention/retention.go

@@ -13,75 +13,108 @@ import (
 	"github.com/break/junhong_cmp_fiber/pkg/errors"
 )
 
-// Source 表示受在线留存边界约束的数据源。
 type Source string
 
 const (
-	// SourceAudit 表示统一审计事件。
-	SourceAudit Source = constants.AuditArchiveSource
-	// SourceIntegration 表示外部交互日志。
+	SourceAudit       Source = constants.AuditArchiveSource
 	SourceIntegration Source = constants.IntegrationArchiveSource
 )
 
-// Info 是查询响应公开的在线留存边界。
 type Info struct {
 	OnlineFrom     time.Time  `json:"online_from" description:"当前可在线查询的最早时间"`
 	ArchivedBefore *time.Time `json:"archived_before" description:"早于该时间的数据已归档；尚未清理时为空"`
 	Timezone       string     `json:"timezone" description:"留存自然日时区"`
 }
 
-// Load 从归档账本读取已完成物理清理的数据边界。
+// Load 仅公开从最早在线日期开始连续完成物理清理的边界，绝不跨越清理空洞。
 func Load(ctx context.Context, db *gorm.DB, sources ...Source) (Info, error) {
 	location, err := time.LoadLocation(constants.AuditArchiveTimezone)
 	if err != nil {
 		return Info{}, errors.Wrap(errors.CodeInternalError, err, "加载审计留存时区失败")
 	}
-	now := time.Now().In(location)
-	info := Info{OnlineFrom: time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, location), Timezone: constants.AuditArchiveTimezone}
+	boundaries := make([]sourceRetention, 0, len(sources))
 	for _, source := range sources {
-		boundary, cleaned, err := sourceBoundary(ctx, db, source, location)
+		boundary, err := sourceBoundary(ctx, db, source, location)
 		if err != nil {
 			return Info{}, err
 		}
-		if boundary.Before(info.OnlineFrom) && info.ArchivedBefore == nil {
-			info.OnlineFrom = boundary
+		boundaries = append(boundaries, boundary)
+	}
+	now := time.Now().In(location)
+	fallback := time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, location)
+	info := Info{OnlineFrom: fallback, Timezone: constants.AuditArchiveTimezone}
+	if len(boundaries) == 0 {
+		return info, nil
+	}
+	for _, boundary := range boundaries {
+		if boundary.onlineFrom.Before(info.OnlineFrom) {
+			info.OnlineFrom = boundary.onlineFrom
 		}
-		if cleaned && (info.ArchivedBefore == nil || boundary.After(*info.ArchivedBefore)) {
-			value := boundary
-			info.ArchivedBefore = &value
-			info.OnlineFrom = boundary
+	}
+	if len(boundaries) == 1 && boundaries[0].cleaned {
+		value := boundaries[0].onlineFrom
+		info.ArchivedBefore = &value
+		return info, nil
+	}
+	if len(boundaries) > 1 {
+		common := boundaries[0].onlineFrom
+		allCleaned := boundaries[0].cleaned
+		for _, boundary := range boundaries[1:] {
+			if boundary.onlineFrom.Before(common) {
+				common = boundary.onlineFrom
+			}
+			allCleaned = allCleaned && boundary.cleaned
+		}
+		if allCleaned {
+			info.OnlineFrom = common
+			info.ArchivedBefore = &common
 		}
 	}
 	return info, nil
 }
 
-func sourceBoundary(ctx context.Context, db *gorm.DB, source Source, location *time.Location) (time.Time, bool, error) {
-	var cleanedEnd sql.NullTime
-	if err := db.WithContext(ctx).Model(&model.LogArchiveRun{}).
-		Where("source = ? AND cleaned_at IS NOT NULL", source).
-		Select("MAX(range_end)").Scan(&cleanedEnd).Error; err != nil {
-		return time.Time{}, false, errors.Wrap(errors.CodeDatabaseError, err, "查询审计留存清理边界失败")
-	}
-	if cleanedEnd.Valid {
-		return cleanedEnd.Time.In(location), true, nil
-	}
+type sourceRetention struct {
+	onlineFrom time.Time
+	cleaned    bool
+}
 
-	var earliest sql.NullTime
-	table, column := "tb_audit_event", "occurred_at"
+func sourceBoundary(ctx context.Context, db *gorm.DB, source Source, location *time.Location) (sourceRetention, error) {
+	table, column := "tb_audit_event", "created_at"
 	if source == SourceIntegration {
 		table, column = "tb_integration_log", "created_at"
 	}
-	if err := db.WithContext(ctx).Table(table).Select("MIN(" + column + ")").Scan(&earliest).Error; err != nil {
-		return time.Time{}, false, errors.Wrap(errors.CodeDatabaseError, err, "查询审计在线数据边界失败")
+	var earliestOnline, earliestLedger sql.NullTime
+	if err := db.WithContext(ctx).Table(table).Select("MIN(" + column + ")").Scan(&earliestOnline).Error; err != nil {
+		return sourceRetention{}, errors.Wrap(errors.CodeDatabaseError, err, "查询审计在线数据边界失败")
 	}
-	if earliest.Valid {
-		return earliest.Time.In(location), false, nil
+	if err := db.WithContext(ctx).Model(&model.LogArchiveRun{}).Where("source = ?", source).Select("MIN(archive_date)").Scan(&earliestLedger).Error; err != nil {
+		return sourceRetention{}, errors.Wrap(errors.CodeDatabaseError, err, "查询审计留存账本边界失败")
 	}
-	now := time.Now().In(location)
-	return time.Date(now.Year(), now.Month(), 1, 0, 0, 0, 0, location), false, nil
+	if !earliestOnline.Valid && !earliestLedger.Valid {
+		now := time.Now().In(location)
+		return sourceRetention{onlineFrom: time.Date(now.Year(), now.Month(), now.Day(), 0, 0, 0, 0, location)}, nil
+	}
+	start := earliestLedger.Time.In(location)
+	if earliestOnline.Valid && (!earliestLedger.Valid || earliestOnline.Time.Before(earliestLedger.Time)) {
+		start = earliestOnline.Time.In(location)
+	}
+	start = time.Date(start.Year(), start.Month(), start.Day(), 0, 0, 0, 0, location)
+	var rows []model.LogArchiveRun
+	if err := db.WithContext(ctx).Where("source = ? AND archive_date >= ?", source, start.Format(time.DateOnly)).Order("archive_date ASC").Find(&rows).Error; err != nil {
+		return sourceRetention{}, errors.Wrap(errors.CodeDatabaseError, err, "查询审计留存清理边界失败")
+	}
+	expected := start
+	for _, row := range rows {
+		date := row.ArchiveDate
+		date = time.Date(date.Year(), date.Month(), date.Day(), 0, 0, 0, 0, location)
+		if !date.Equal(expected) || row.CleanedAt == nil {
+			break
+		}
+		expected = expected.AddDate(0, 0, 1)
+	}
+	return sourceRetention{onlineFrom: expected, cleaned: !expected.Equal(start)}, nil
 }
 
-// NormalizeRange 将缺省范围收敛到在线窗口，并拒绝归档或跨边界查询。
 func NormalizeRange(info Info, from, to *time.Time, maxRange ...time.Duration) (*time.Time, *time.Time, error) {
 	explicitFrom := from != nil
 	if from != nil && info.ArchivedBefore != nil && from.Before(info.OnlineFrom) {
@@ -110,7 +143,6 @@ func NormalizeRange(info Info, from, to *time.Time, maxRange ...time.Duration) (
 	}
 	return from, to, nil
 }
-
 func archivedError(info Info) error {
 	return errors.NewWithData(errors.CodeAuditDataArchived, map[string]any{"retention": info})
 }

internal/routes/admin.go

@@ -126,7 +126,16 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
 	if handlers.WechatConfig != nil {
 		registerWechatConfigRoutes(authGroup, handlers.WechatConfig, doc, basePath)
 	}
+	if handlers.PaymentMerchant != nil {
+		registerPaymentMerchantRoutes(authGroup, handlers.PaymentMerchant, doc, basePath)
+	}
+	if handlers.EmployeeCollection != nil {
+		registerEmployeeCollectionRoutes(authGroup, handlers.EmployeeCollection, doc, basePath)
+		registerEmployeeCollectionBillRoutes(authGroup, handlers.EmployeeCollection, doc, basePath)
+		registerEmployeeCollectionApplicationRoutes(authGroup, handlers.EmployeeCollection, doc, basePath)
+	}
 	if handlers.AgentRecharge != nil {
+		registerAgentSelfRechargePaymentMethodRoutes(authGroup, handlers.AgentRecharge, doc, basePath)
 		registerAgentRechargeRoutes(authGroup, handlers.AgentRecharge, doc, basePath)
 	}
 	if handlers.Refund != nil {

internal/routes/agent_recharge.go

@@ -45,6 +45,15 @@ func registerAgentRechargeRoutes(router fiber.Router, handler *admin.AgentRechar
 		Auth:    true,
 	})
 
+	Register(group, doc, groupPath, "POST", "/payment-voucher-ocr", handler.PaymentVoucherOCR, RouteSpec{
+		Summary:     "识别付款凭证中的交易流水号",
+		Description: "按付款凭证对象键调用识别能力，只返回交易流水号预填值供人工确认或更正；识别结果不写入任何资金事实，失败不阻断人工填写。",
+		Tags:        []string{"代理预充值"},
+		Input:       new(dto.AgentRechargePaymentVoucherOCRRequest),
+		Output:      new(dto.AgentRechargePaymentVoucherOCRResponse),
+		Auth:        true,
+	})
+
 	Register(group, doc, groupPath, "GET", "/:id/payment-status", handler.PaymentStatus, RouteSpec{
 		Summary: "查询代理充值本地支付与到账状态",
 		Tags:    []string{"代理预充值"},
@@ -61,6 +70,14 @@ func registerAgentRechargeRoutes(router fiber.Router, handler *admin.AgentRechar
 		Auth:    true,
 	})
 
+	Register(group, doc, groupPath, "POST", "/:id/trigger-approval", handler.TriggerApproval, RouteSpec{
+		Summary: "补发历史线下代理充值审批",
+		Tags:    []string{"代理预充值"},
+		Input:   new(dto.IDReq),
+		Output:  new(dto.AgentRechargeResponse),
+		Auth:    true,
+	})
+
 	Register(group, doc, groupPath, "POST", "/:id/offline-pay", handler.OfflinePay, RouteSpec{
 		Summary: "确认线下充值",
 		Tags:    []string{"代理预充值"},

internal/routes/agent_self_recharge_payment_method.go

@@ -0,0 +1,49 @@
+package routes
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+// registerAgentSelfRechargePaymentMethodRoutes 注册代理自充允许范围读取与修改路由。
+// 读取对代理与平台账号开放，返回的是允许范围与可用商户池的交集；修改仅超级管理员可用。
+// 该路径不在代理充值业务组内，因此读取与写入的角色门禁在此显式声明。
+func registerAgentSelfRechargePaymentMethodRoutes(router fiber.Router, handler *admin.AgentRechargeHandler, doc *openapi.Generator, basePath string) {
+	group := router.Group("/agent-self-recharge-payment-methods", func(c *fiber.Ctx) error {
+		userType := middleware.GetUserTypeFromContext(c.UserContext())
+		if c.Method() == fiber.MethodPut {
+			if userType != constants.UserTypeSuperAdmin {
+				return errors.New(errors.CodeForbidden, "仅超级管理员可以修改代理自充允许范围")
+			}
+			return c.Next()
+		}
+		if userType != constants.UserTypeAgent && userType != constants.UserTypePlatform {
+			return errors.New(errors.CodeForbidden, "仅代理或平台账号可以查询代理自充可用支付方式")
+		}
+		return c.Next()
+	})
+	groupPath := basePath + "/agent-self-recharge-payment-methods"
+
+	Register(group, doc, groupPath, "GET", "", handler.SelfRechargePaymentMethods, RouteSpec{
+		Summary:     "查询代理自充实际可用支付方式",
+		Description: "返回超级管理员允许范围与当前可用商户池支付方式的交集，固定顺序；交集为空时返回空列表且不报错。响应不含允许范围本身、商户身份或凭证。",
+		Tags:        []string{"代理预充值"},
+		Output:      new(dto.AgentRechargePaymentMethodsResponse),
+		Auth:        true,
+	})
+
+	Register(group, doc, groupPath, "PUT", "", handler.UpdateSelfRechargePaymentMethods, RouteSpec{
+		Summary:     "修改代理在线自充允许范围",
+		Description: "仅超级管理员可修改，取值仅限仅微信、仅支付宝、同时支持；每次修改记录操作者、修改前后值与时间，且只影响后续新单。",
+		Tags:        []string{"代理预充值"},
+		Input:       new(dto.AgentSelfRechargePaymentMethodsUpdateRequest),
+		Output:      new(dto.AgentSelfRechargePaymentMethodsUpdateResponse),
+		Auth:        true,
+	})
+}

internal/routes/asset.go

@@ -40,8 +40,8 @@ func registerAssetRoutes(router fiber.Router, handler *admin.AssetHandler, walle
 	})
 
 	Register(assets, doc, groupPath, "GET", "/:identifier/packages", handler.Packages, RouteSpec{
-		Summary:     "资产套餐列表",
-		Description: "查询该资产所有套餐记录，含虚流量换算结果。支持分页与 status 状态筛选。",
+		Summary:     "资产套餐历史",
+		Description: "查询该资产全部世代的套餐历史层级。每个主套餐及其关联加油包占一个分页名额，total 为筛选后的顶层项数量；支持 status 按同一使用记录筛选。关联主套餐物理缺失返回异常独立项，存在但不可展示的关联主套餐返回统一读取错误。",
 		Tags:        []string{"资产管理"},
 		Input:       new(dto.AssetPackagesRequest),
 		Output:      new(dto.AssetPackagesResult),

internal/routes/employee_collection.go

@@ -0,0 +1,149 @@
+package routes
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+// requireEmployeeCollectionConfigAccess 限制线下收款方式字典维护仅超级管理员可用，
+// 非超级管理员与其他不可见资源返回同一禁止访问错误，避免可枚举差异。
+func requireEmployeeCollectionConfigAccess(handler fiber.Handler) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		if middleware.GetUserTypeFromContext(c.UserContext()) != constants.UserTypeSuperAdmin {
+			return errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")
+		}
+		return handler(c)
+	}
+}
+
+func registerEmployeeCollectionRoutes(router fiber.Router, handler *admin.EmployeeCollectionHandler, doc *openapi.Generator, basePath string) {
+	// 路由前缀必须交给 Group：Register 的 basePath 只用于生成 OpenAPI 文档，不参与路由注册，
+	// 否则相对路径会落到 /api/admin 根上并抢占同层后续路由。
+	group := router.Group("/employee-collection-payment-methods")
+	paymentMethodPath := basePath + "/employee-collection-payment-methods"
+	wrap := requireEmployeeCollectionConfigAccess
+
+	Register(group, doc, paymentMethodPath, "GET", "", handler.ListPaymentMethods, RouteSpec{
+		Summary:     "查询线下收款方式",
+		Description: "超级管理员可查询全部字典项；其他后台账号仅返回启用项，用于新核销申请选择收款方式。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.EmployeeCollectionPaymentMethodListRequest),
+		Output:      new(dto.EmployeeCollectionPaymentMethodListResponse),
+		Auth:        true,
+	})
+	Register(group, doc, paymentMethodPath, "POST", "", wrap(handler.CreatePaymentMethod), RouteSpec{
+		Summary:     "创建线下收款方式",
+		Description: "仅超级管理员。稳定编码在未删除记录中唯一。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.CreateEmployeeCollectionPaymentMethodRequest),
+		Output:      new(dto.EmployeeCollectionPaymentMethodResponse),
+		Auth:        true,
+	})
+	Register(group, doc, paymentMethodPath, "PUT", "/:id", wrap(handler.UpdatePaymentMethod), RouteSpec{
+		Summary:     "更新线下收款方式",
+		Description: "仅超级管理员。可修改名称、排序、启停与备注；已被核销申请引用时不允许修改稳定编码。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.IDReq),
+		Body:        new(dto.UpdateEmployeeCollectionPaymentMethodRequest),
+		Output:      new(dto.EmployeeCollectionPaymentMethodResponse),
+		Auth:        true,
+	})
+	Register(group, doc, paymentMethodPath, "DELETE", "/:id", wrap(handler.DeletePaymentMethod), RouteSpec{
+		Summary:     "删除线下收款方式",
+		Description: "仅超级管理员。已被核销申请引用的字典项不可物理删除，只能停用。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.IDReq),
+		Output:      nil,
+		Auth:        true,
+	})
+}
+
+// registerEmployeeCollectionBillRoutes 注册员工代收款账单查询、统计与关闭路由。
+// 账单可见性由应用层强制：欠款人仅见本人账单，超级管理员见全部。
+func registerEmployeeCollectionBillRoutes(router fiber.Router, handler *admin.EmployeeCollectionHandler, doc *openapi.Generator, basePath string) {
+	group := router.Group("/employee-collection-bills")
+	billPath := basePath + "/employee-collection-bills"
+	adminOnly := requireEmployeeCollectionConfigAccess
+
+	Register(group, doc, billPath, "GET", "", handler.ListBills, RouteSpec{
+		Summary:     "查询员工代收款账单",
+		Description: "欠款人仅返回本人欠款账单，超级管理员返回全部；支持来源、状态、时间、欠款人、客户筛选与分页。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.EmployeeCollectionBillListRequest),
+		Output:      new(dto.EmployeeCollectionBillListResponse),
+		Auth:        true,
+	})
+	// 统计必须先于 /:id 注册，保证路径按字面量优先匹配。
+	Register(group, doc, billPath, "GET", "/statistics", handler.StatisticsBills, RouteSpec{
+		Summary:     "查询员工代收款账单统计",
+		Description: "与账单列表使用相同筛选条件与可见性范围，返回应收、已核销、未核销金额合计与待处理账单数；不接受分页参数。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.EmployeeCollectionBillStatisticsRequest),
+		Output:      new(dto.EmployeeCollectionBillStatisticsResponse),
+		Auth:        true,
+	})
+	Register(group, doc, billPath, "GET", "/:id", handler.GetBill, RouteSpec{
+		Summary:     "查询员工代收款账单详情",
+		Description: "返回账单、来源退款冲销、分摊、核销申请与企业微信审批历史；附件只返回对象键引用。无权限与不存在返回同一错误。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.IDReq),
+		Output:      new(dto.EmployeeCollectionBillDetailResponse),
+		Auth:        true,
+	})
+	Register(group, doc, billPath, "POST", "/:id/close", adminOnly(handler.CloseBill), RouteSpec{
+		Summary:     "关闭员工代收款账单",
+		Description: "仅超级管理员。仅允许关闭待核销或部分核销且不存在审批中分摊的账单；关闭只作废未核销余额并保留已核销金额。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.IDReq),
+		Body:        new(dto.CloseEmployeeCollectionBillRequest),
+		Output:      new(dto.EmployeeCollectionBillResponse),
+		Auth:        true,
+	})
+}
+
+// registerEmployeeCollectionApplicationRoutes 注册核销申请的创建、重提与受控查询路由。
+// 可见性与代办权限由应用层强制：非超级管理员只能为本人账单操作，超级管理员代办必须填写原因。
+func registerEmployeeCollectionApplicationRoutes(router fiber.Router, handler *admin.EmployeeCollectionHandler, doc *openapi.Generator, basePath string) {
+	group := router.Group("/employee-collection-applications")
+	applicationPath := basePath + "/employee-collection-applications"
+
+	Register(group, doc, applicationPath, "POST", "", handler.CreateApplication, RouteSpec{
+		Summary:     "创建核销申请",
+		Description: "员工为本人可见账单创建；超级管理员可为账单欠款人代办且必须填写 acting_reason。服务端按账单可核销余额与付款金额校验分摊，任一失败不保存申请与预占。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.SubmitEmployeeCollectionApplicationRequest),
+		Output:      new(dto.EmployeeCollectionApplicationSubmitResponse),
+		Auth:        true,
+	})
+	Register(group, doc, applicationPath, "GET", "", handler.ListApplications, RouteSpec{
+		Summary:     "查询核销申请",
+		Description: "非超级管理员仅返回本人申请，超级管理员返回全部；支持状态、收款方式、申请人与创建时间筛选和分页。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.EmployeeCollectionApplicationListRequest),
+		Output:      new(dto.EmployeeCollectionApplicationListResponse),
+		Auth:        true,
+	})
+	Register(group, doc, applicationPath, "GET", "/:id", handler.GetApplication, RouteSpec{
+		Summary:     "查询核销申请详情",
+		Description: "返回申请事实、账单分摊与全部审批尝试历史；附件只返回对象键引用。无权限与不存在返回同一错误。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.IDReq),
+		Output:      new(dto.EmployeeCollectionApplicationDetailResponse),
+		Auth:        true,
+	})
+	Register(group, doc, applicationPath, "PUT", "/:id", handler.ResubmitApplication, RouteSpec{
+		Summary:     "修改并重提核销申请",
+		Description: "仅申请人或被代办的超级管理员，且仅已驳回申请可修改；重提新增一条审批尝试记录与新的企业微信审批实例，历史材料不被覆盖。",
+		Tags:        []string{"员工代收款"},
+		Input:       new(dto.IDReq),
+		Body:        new(dto.SubmitEmployeeCollectionApplicationRequest),
+		Output:      new(dto.EmployeeCollectionApplicationSubmitResponse),
+		Auth:        true,
+	})
+}

internal/routes/payment_merchant.go

@@ -0,0 +1,42 @@
+package routes
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+	"github.com/break/junhong_cmp_fiber/pkg/middleware"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+// requirePaymentMerchantAccess 校验当前用户是否有权访问支付商户配置，
+// 仅允许超级管理员和平台用户，其他角色直接返回无权限错误。
+func requirePaymentMerchantAccess(handler fiber.Handler) fiber.Handler {
+	return func(c *fiber.Ctx) error {
+		kind := middleware.GetUserTypeFromContext(c.UserContext())
+		if kind != constants.UserTypeSuperAdmin && kind != constants.UserTypePlatform {
+			return errors.New(errors.CodeForbidden, "无权限访问支付商户配置")
+		}
+		return handler(c)
+	}
+}
+
+func registerPaymentMerchantRoutes(router fiber.Router, handler *admin.PaymentMerchantHandler, doc *openapi.Generator, basePath string) {
+	group := router
+	wrap := requirePaymentMerchantAccess
+	Register(group, doc, basePath, "GET", "/payment-merchants", wrap(handler.ListMerchants), RouteSpec{Summary: "查询支付商户", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"支付商户管理"}, Input: new(dto.PaymentMerchantListRequest), Output: new(dto.PaymentMerchantResponse), Auth: true})
+	Register(group, doc, basePath, "POST", "/payment-merchants", wrap(handler.CreateMerchant), RouteSpec{Summary: "创建支付商户", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"支付商户管理"}, Input: new(dto.PaymentMerchantRequest), Output: new(dto.PaymentMerchantResponse), Auth: true})
+	Register(group, doc, basePath, "GET", "/payment-merchants/:id", wrap(handler.GetMerchant), RouteSpec{Summary: "查询支付商户详情", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"支付商户管理"}, Input: new(dto.IDReq), Output: new(dto.PaymentMerchantResponse), Auth: true})
+	Register(group, doc, basePath, "PUT", "/payment-merchants/:id", wrap(handler.UpdateMerchant), RouteSpec{Summary: "更新支付商户", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"支付商户管理"}, Input: new(dto.IDReq), Body: new(dto.PaymentMerchantUpdateRequest), Output: new(dto.PaymentMerchantResponse), Auth: true})
+	Register(group, doc, basePath, "DELETE", "/payment-merchants/:id", wrap(handler.DeleteMerchant), RouteSpec{Summary: "删除支付商户", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"支付商户管理"}, Input: new(dto.IDReq), Body: new(dto.PaymentMerchantDeleteRequest), Output: nil, Auth: true})
+	Register(group, doc, basePath, "GET", "/payment-merchant-pools", wrap(handler.ListPools), RouteSpec{Summary: "查询商户池", Description: "仅超级管理员和平台用户可访问。支持分页，返回当前页商户池及其有序成员。", Tags: []string{"商户池管理"}, Input: new(dto.PaymentMerchantPoolListRequest), Output: new(dto.PaymentMerchantPoolResponse), Auth: true})
+	Register(group, doc, basePath, "GET", "/payment-merchant-pools/:id", wrap(handler.GetPool), RouteSpec{Summary: "查询商户池详情", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"商户池管理"}, Input: new(dto.IDReq), Output: new(dto.PaymentMerchantPoolResponse), Auth: true})
+	Register(group, doc, basePath, "POST", "/payment-merchant-pools", wrap(handler.CreatePool), RouteSpec{Summary: "创建商户池", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"商户池管理"}, Input: new(dto.PaymentMerchantPoolRequest), Output: new(dto.PaymentMerchantPoolResponse), Auth: true})
+	Register(group, doc, basePath, "PUT", "/payment-merchant-pools/:id", wrap(handler.UpdatePool), RouteSpec{Summary: "更新商户池", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"商户池管理"}, Input: new(dto.IDReq), Body: new(dto.PaymentMerchantPoolRequest), Output: new(dto.PaymentMerchantPoolResponse), Auth: true})
+	Register(group, doc, basePath, "POST", "/payment-merchant-pools/:id/enable", wrap(handler.EnablePool), RouteSpec{Summary: "启用商户池", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"商户池管理"}, Input: new(dto.IDReq), Output: new(dto.PaymentMerchantPoolResponse), Auth: true})
+	Register(group, doc, basePath, "POST", "/payment-merchant-pools/:id/disable", wrap(handler.DisablePool), RouteSpec{Summary: "停用商户池", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"商户池管理"}, Input: new(dto.IDReq), Output: new(dto.PaymentMerchantPoolResponse), Auth: true})
+	Register(group, doc, basePath, "GET", "/wechat-authorizations", wrap(handler.GetAuthorization), RouteSpec{Summary: "获取微信授权配置", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"微信授权配置"}, Output: new(dto.WechatAuthorizationResponse), Auth: true})
+	Register(group, doc, basePath, "PUT", "/wechat-authorizations/current", wrap(handler.SaveAuthorization), RouteSpec{Summary: "保存微信授权配置", Description: "仅超级管理员和平台用户可访问。", Tags: []string{"微信授权配置"}, Input: new(dto.WechatAuthorizationRequest), Output: new(dto.WechatAuthorizationResponse), Auth: true})
+}

internal/routes/personal.go

@@ -156,11 +156,12 @@ func RegisterPersonalCustomerRoutes(router fiber.Router, doc *openapi.Generator,
 	})
 
 	Register(authGroup, doc, basePath, "GET", "/asset/package-history", handlers.ClientAsset.GetPackageHistory, RouteSpec{
-		Summary: "资产套餐历史",
-		Tags:    []string{"个人客户 - 资产"},
-		Auth:    true,
-		Input:   &dto.AssetPackageHistoryRequest{},
-		Output:  &dto.AssetPackageHistoryResponse{},
+		Summary:     "资产套餐历史",
+		Description: "查询客户已绑定资产当前世代的套餐历史层级。每个主套餐及其关联加油包占一个分页名额，total 为筛选后的顶层项数量；status 与 package_type 必须由同一使用记录联合命中，命中任一成员即返回完整关系组。关联主套餐物理缺失返回异常独立项，存在但不可展示的关联主套餐返回统一读取错误。",
+		Tags:        []string{"个人客户 - 资产"},
+		Auth:        true,
+		Input:       &dto.AssetPackageHistoryRequest{},
+		Output:      &dto.AssetPackageHistoryResponse{},
 	})
 
 	Register(authGroup, doc, basePath, "POST", "/asset/refresh", handlers.ClientAsset.RefreshAsset, RouteSpec{

internal/routes/refund.go

@@ -49,6 +49,14 @@ func registerRefundRoutes(router fiber.Router, handler *admin.RefundHandler, doc
 		Auth:    true,
 	})
 
+	Register(refund, doc, groupPath, "POST", "/:id/trigger-approval", handler.TriggerApproval, RouteSpec{
+		Summary: "补发历史退款审批",
+		Tags:    []string{"退款管理"},
+		Input:   new(dto.RefundIDRequest),
+		Output:  new(dto.RefundResponse),
+		Auth:    true,
+	})
+
 	Register(refund, doc, groupPath, "POST", "/:id/approve", handler.Approve, RouteSpec{
 		Summary: "审批通过退款申请",
 		Tags:    []string{"退款管理"},