feat(代理分销提现): 落地扫码注册、提现资料资格与企微终审提现

AUG26-008。

- 迁移 000214–000217：tb_shop 全局唯一且不可修改的随机分销码（含存量回填）、
  tb_agent_distribution_registration 待审批注册记录、tb_withdrawal_qualification 资料版本、
  tb_commission_withdrawal_request_attempt 审批尝试记录，以及提现申请的 latest_*/异常标记列；
  不修改既有迁移，down 在存在本 Change 业务事实或新类型场景行时拒绝破坏性回滚。
- 公开接口 POST /api/c/v1/agent-distribution-registrations：无认证，复用既有短信验证码校验、
  消费与限流；无效分销码、停用上级、验证码无效或已消费统一返回「分销码不可用」且不落库，
  审批通过前不创建店铺、账号或钱包。
- 审批通过才在同一事务内建启用店铺、代理主账号、钱包、上级层级与业务员快照，驳回不建实体，
  重复回调不重复建实体，提交后清理上级下级缓存。
- 提现资料资格按不可变版本保存，替换合同或法人身份证即新增版本并同事务失效旧有效版本；
  超管作废原因必填；代理停用与店铺删除联动失效。
- 提现每次提交或重提新增不可变审批尝试记录并冻结金额；企业微信通过仅一次从冻结扣减、
  保持状态 2 并写 paid_at（不使用状态 4），驳回/cancelled/deleted 仅一次释放，
  通过后撤销不回滚、不重新冻结、只写正交异常标记；加锁顺序统一为申请→尝试→钱包。
- 本地人工终审对已关联审批实例的申请返回状态冲突，approval_instance_id 为空的存量申请保持既有行为，
  不新增任何配置开关。
- 补齐审批业务类型注册点全集：业务类型与场景字段常量、场景 DTO 两处枚举与中文描述、
  场景字段白名单/合法类型/中文名、数据库 CHECK、Worker 决策消费者与装配、审批审计资源映射，
  以及三个新审计资源与 13 个审计动作；失败/拒绝审计改为必达。
- 新增后台路由与 OpenAPI：资格提交/查询/作废、提现申请/重提/详情、店铺详情返回只读分销码。
- 归档本 Change：主 Spec 新增 agent-distribution-withdrawal 能力（5 个 Requirement）。

验证（junhong_cmp_test + Redis DB 6，显式 DB_*，未重置整库）：
- 迁移 up → version 217 且 dirty=false → down 3 → up 回 217，fixture 复核残留为 0。
- 受控状态机脚手架 227 项通过 / 0 项失败，覆盖 18 组场景（幂等与乱序回调、资金冻结/释放/重提、
  退款回扣 × 在途提现并发、负向场景拒绝审计与 14 个动作码审计真实落库）。
- gofmt 空、go build/go vet 通过、gendocs 与工作区逐字节一致、context-health 通过、
  openspec validate --strict 通过、doctor healthy；自动化测试按项目决策为 N/A。

运行期前置（未完成，非代码交付物）：由超管经 PUT /api/admin/wecom/scenes/{business_type} 为
agent_distribution_approval、withdrawal_qualification_approval、commission_withdrawal_approval
配置启用场景与模板控件映射；未配置时相应提交失败关闭。

internal/bootstrap/handlers.go

@@ -24,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"
+	distributionwithdrawalQuery "github.com/break/junhong_cmp_fiber/internal/query/distributionwithdrawal"
 	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"
@@ -203,7 +204,10 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
 		Shop: func() *admin.ShopHandler {
 			handler := admin.NewShopHandler(svc.Shop, validate)
 			handler.SetCreateService(shopApp.NewCreateService(deps.DB, svc.AccessAudit))
-			handler.SetUpdateService(shopApp.NewUpdateService(deps.DB, svc.AccessAudit))
+			updateService := shopApp.NewUpdateService(deps.DB, svc.AccessAudit)
+			// 店铺停用必须联动失效提现资料资格，接入点在同一停用事务内。
+			updateService.SetWithdrawalQualificationInvalidator(svc.WithdrawalQualification)
+			handler.SetUpdateService(updateService)
 			handler.SetBusinessOwnerQuery(shopQuery.NewBusinessOwnerQuery(deps.DB))
 			handler.SetChangeCreditService(walletApp.NewChangeCreditService(deps.DB, svc.AccessAudit))
 			return handler
@@ -211,10 +215,15 @@ func initHandlers(svc *services, deps *Dependencies) *Handlers {
 		ShopRole:  admin.NewShopRoleHandler(svc.Shop),
 		AdminAuth: admin.NewAuthHandler(svc.Auth, validate),
 		ShopCommission: func() *admin.ShopCommissionHandler {
-			handler := admin.NewShopCommissionHandler(svc.ShopCommission)
+			handler := admin.NewShopCommissionHandler(svc.ShopCommission, validate)
 			handler.SetFundSummaryQuery(shopQuery.NewFundSummaryQuery(deps.DB))
+			handler.SetWithdrawalQuery(distributionwithdrawalQuery.NewQuery(deps.DB))
 			return handler
 		}(),
+		WithdrawalQualification: admin.NewWithdrawalQualificationHandler(
+			svc.WithdrawalQualification, distributionwithdrawalQuery.NewQuery(deps.DB), validate,
+		),
+		AgentDistribution:           app.NewAgentDistributionHandler(svc.DistributionRegistration, validate),
 		CommissionWithdrawal:        admin.NewCommissionWithdrawalHandler(svc.CommissionWithdrawal, validate),
 		CommissionWithdrawalSetting: admin.NewCommissionWithdrawalSettingHandler(svc.CommissionWithdrawalSetting),
 		Enterprise:                  admin.NewEnterpriseHandler(svc.Enterprise),

internal/bootstrap/services.go

@@ -8,6 +8,7 @@ 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"
+	distributionwithdrawalApp "github.com/break/junhong_cmp_fiber/internal/application/distributionwithdrawal"
 	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"
@@ -89,6 +90,9 @@ type services struct {
 	Shop                        *shopSvc.Service
 	Auth                        *authSvc.Service
 	ShopCommission              *shopCommissionSvc.Service
+	DistributionRegistration    *distributionwithdrawalApp.RegistrationService
+	WithdrawalQualification     *distributionwithdrawalApp.QualificationService
+	WithdrawalApproval          *distributionwithdrawalApp.WithdrawalService
 	CommissionWithdrawal        *commissionWithdrawalSvc.Service
 	CommissionWithdrawalSetting *commissionWithdrawalSettingSvc.Service
 	CommissionCalculation       *commissionCalculationSvc.Service
@@ -377,6 +381,18 @@ func initServices(s *stores, deps *Dependencies) *services {
 	shopService.SetAccessAudit(deps.DB, deps.Redis, auditWriter)
 	commissionWithdrawal := commissionWithdrawalSvc.New(deps.DB, s.Shop, s.Account, s.AgentWallet, s.AgentWalletTransaction, s.CommissionWithdrawalRequest)
 	commissionWithdrawal.SetAuditWriter(auditWriter)
+	// 代理分销注册、提现资格与提现终审共用同一审计 Writer 与通用审批创建接缝。
+	distributionRegistration := distributionwithdrawalApp.NewRegistrationService(
+		deps.DB, deps.VerificationService, approvalCreationService, auditWriter,
+	)
+	withdrawalQualification := distributionwithdrawalApp.NewQualificationService(
+		deps.DB, approvalCreationService, auditWriter,
+	)
+	withdrawalApproval := distributionwithdrawalApp.NewWithdrawalService(
+		deps.DB, approvalCreationService, auditWriter,
+	)
+	shopCommission.SetWithdrawalApprovalService(withdrawalApproval)
+	shopService.SetWithdrawalQualificationInvalidator(withdrawalQualification)
 	commissionCalculation := commissionCalculationSvc.New(
 		deps.DB,
 		s.CommissionRecord,
@@ -431,6 +447,9 @@ func initServices(s *stores, deps *Dependencies) *services {
 		Shop:                        shopService,
 		Auth:                        authService,
 		ShopCommission:              shopCommission,
+		DistributionRegistration:    distributionRegistration,
+		WithdrawalQualification:     withdrawalQualification,
+		WithdrawalApproval:          withdrawalApproval,
 		CommissionWithdrawal:        commissionWithdrawal,
 		CommissionWithdrawalSetting: commissionWithdrawalSettingSvc.New(deps.DB, s.Account, s.CommissionWithdrawalSetting),
 		CommissionCalculation:       commissionCalculation,

internal/bootstrap/types.go

@@ -29,6 +29,8 @@ type Handlers struct {
 	ShopRole                    *admin.ShopRoleHandler
 	AdminAuth                   *admin.AuthHandler
 	ShopCommission              *admin.ShopCommissionHandler
+	WithdrawalQualification     *admin.WithdrawalQualificationHandler
+	AgentDistribution           *app.AgentDistributionHandler
 	CommissionWithdrawal        *admin.CommissionWithdrawalHandler
 	CommissionWithdrawalSetting *admin.CommissionWithdrawalSettingHandler
 	Enterprise                  *admin.EnterpriseHandler