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
配置启用场景与模板控件映射；未配置时相应提交失败关闭。

pkg/constants/agent_distribution.go

@@ -0,0 +1,29 @@
+package constants
+
+const (
+	// AgentDistributionRegistrationStatusPending 表示注册记录等待企业微信终审。
+	AgentDistributionRegistrationStatusPending = 0
+	// AgentDistributionRegistrationStatusApproved 表示注册记录已通过并已建立店铺与代理账号。
+	AgentDistributionRegistrationStatusApproved = 1
+	// AgentDistributionRegistrationStatusRejected 表示注册记录已驳回，未创建任何实体。
+	AgentDistributionRegistrationStatusRejected = 2
+)
+
+const (
+	// ShopDistributionCodeMaxAttempts 表示建店事务内生成分销码的最大尝试次数。
+	ShopDistributionCodeMaxAttempts = 5
+)
+
+// GetAgentDistributionRegistrationStatusName 返回注册记录状态的中文名称。
+func GetAgentDistributionRegistrationStatusName(status int) string {
+	switch status {
+	case AgentDistributionRegistrationStatusPending:
+		return "待审批"
+	case AgentDistributionRegistrationStatusApproved:
+		return "已通过"
+	case AgentDistributionRegistrationStatusRejected:
+		return "已驳回"
+	default:
+		return "未知"
+	}
+}

pkg/constants/approval.go

@@ -10,6 +10,15 @@ const (
 	// ApprovalBusinessTypeEmployeeCollection 表示员工代收款核销审批业务场景。
 	// 该场景的业务ID取核销申请的审批尝试记录主键，使同一申请每次提交各自持有独立审批实例。
 	ApprovalBusinessTypeEmployeeCollection = "employee_collection_approval"
+	// ApprovalBusinessTypeAgentDistribution 表示代理扫码分销注册审批业务场景。
+	// 该场景的业务ID取待审批注册记录主键，审批通过才创建店铺与代理账号。
+	ApprovalBusinessTypeAgentDistribution = "agent_distribution_approval"
+	// ApprovalBusinessTypeWithdrawalQualification 表示提现资料资格审批业务场景。
+	// 该场景的业务ID取资料版本主键，替换资料即新版本新实例，历史版本不可覆盖。
+	ApprovalBusinessTypeWithdrawalQualification = "withdrawal_qualification_approval"
+	// ApprovalBusinessTypeCommissionWithdrawal 表示佣金提现终审审批业务场景。
+	// 该场景的业务ID取提现申请的审批尝试记录主键，使同一申请每次提交或重提各自持有独立审批实例。
+	ApprovalBusinessTypeCommissionWithdrawal = "commission_withdrawal_approval"
 )
 
 const (
@@ -79,6 +88,75 @@ const (
 	ApprovalFieldCollectionBillSummary = "collection_bill_summary"
 )
 
+const (
+	// ApprovalFieldDistributionCode 表示扫码注册使用的上级店铺分销码业务字段。
+	ApprovalFieldDistributionCode = "distribution_code"
+	// ApprovalFieldDistributionParentShopID 表示扫码注册上级店铺 ID 业务字段。
+	ApprovalFieldDistributionParentShopID = "distribution_parent_shop_id"
+	// ApprovalFieldDistributionParentShopName 表示扫码注册上级店铺名称业务字段。
+	ApprovalFieldDistributionParentShopName = "distribution_parent_shop_name"
+	// ApprovalFieldDistributionShopName 表示申请店铺名称业务字段。
+	ApprovalFieldDistributionShopName = "distribution_shop_name"
+	// ApprovalFieldDistributionShopCode 表示申请店铺编号业务字段。
+	ApprovalFieldDistributionShopCode = "distribution_shop_code"
+	// ApprovalFieldDistributionUsername 表示申请代理主账号用户名业务字段。
+	ApprovalFieldDistributionUsername = "distribution_username"
+	// ApprovalFieldDistributionPhoneMasked 表示脱敏后的注册手机号业务字段，禁止写入完整手机号。
+	ApprovalFieldDistributionPhoneMasked = "distribution_phone_masked"
+	// ApprovalFieldDistributionContactName 表示注册联系人姓名业务字段。
+	ApprovalFieldDistributionContactName = "distribution_contact_name"
+	// ApprovalFieldDistributionRegion 表示注册地址摘要业务字段。
+	ApprovalFieldDistributionRegion = "distribution_region"
+	// ApprovalFieldQualificationSubjectType 表示提现资格签约主体类型中文名业务字段。
+	ApprovalFieldQualificationSubjectType = "qualification_subject_type"
+	// ApprovalFieldQualificationSubjectCodeMasked 表示脱敏后的签约主体代码业务字段。
+	ApprovalFieldQualificationSubjectCodeMasked = "qualification_subject_code_masked"
+	// ApprovalFieldQualificationLegalPersonMasked 表示脱敏后的法人身份证号业务字段。
+	ApprovalFieldQualificationLegalPersonMasked = "qualification_legal_person_id_card_masked"
+	// ApprovalFieldQualificationShopID 表示提现资格所属店铺 ID 业务字段。
+	ApprovalFieldQualificationShopID = "qualification_shop_id"
+	// ApprovalFieldQualificationShopName 表示提现资格所属店铺名称业务字段。
+	ApprovalFieldQualificationShopName = "qualification_shop_name"
+	// ApprovalFieldQualificationContractKey 表示合同附件对象存储 Key 业务字段。
+	ApprovalFieldQualificationContractKey = "qualification_contract_key"
+	// ApprovalFieldQualificationIDCardFrontKey 表示法人身份证正面附件对象存储 Key 业务字段。
+	ApprovalFieldQualificationIDCardFrontKey = "qualification_id_card_front_key"
+	// ApprovalFieldQualificationIDCardBackKey 表示法人身份证反面附件对象存储 Key 业务字段。
+	ApprovalFieldQualificationIDCardBackKey = "qualification_id_card_back_key"
+	// ApprovalFieldQualificationBusinessLicenseKey 表示营业执照附件对象存储 Key 业务字段。
+	ApprovalFieldQualificationBusinessLicenseKey = "qualification_business_license_key"
+	// ApprovalFieldQualificationShopFrontKey 表示门头照附件对象存储 Key 业务字段。
+	ApprovalFieldQualificationShopFrontKey = "qualification_shop_front_key"
+	// ApprovalFieldQualificationInvoiceKey 表示发票附件对象存储 Key 业务字段。
+	ApprovalFieldQualificationInvoiceKey = "qualification_invoice_key"
+	// ApprovalFieldQualificationInvoiceTitle 表示发票抬头业务字段。
+	ApprovalFieldQualificationInvoiceTitle = "qualification_invoice_title"
+	// ApprovalFieldWithdrawalNo 表示提现单号业务字段。
+	ApprovalFieldWithdrawalNo = "withdrawal_no"
+	// ApprovalFieldWithdrawalAttemptNo 表示提现第几次提交业务字段。
+	ApprovalFieldWithdrawalAttemptNo = "withdrawal_attempt_no"
+	// ApprovalFieldWithdrawalShopID 表示提现店铺 ID 业务字段。
+	ApprovalFieldWithdrawalShopID = "withdrawal_shop_id"
+	// ApprovalFieldWithdrawalShopName 表示提现店铺名称业务字段。
+	ApprovalFieldWithdrawalShopName = "withdrawal_shop_name"
+	// ApprovalFieldWithdrawalAmount 表示提现金额元展示业务字段。
+	ApprovalFieldWithdrawalAmount = "withdrawal_amount"
+	// ApprovalFieldWithdrawalAmountCent 表示提现金额分业务字段。
+	ApprovalFieldWithdrawalAmountCent = "withdrawal_amount_cent"
+	// ApprovalFieldWithdrawalFee 表示提现手续费元展示业务字段。
+	ApprovalFieldWithdrawalFee = "withdrawal_fee"
+	// ApprovalFieldWithdrawalActualAmount 表示提现实际到账金额元展示业务字段。
+	ApprovalFieldWithdrawalActualAmount = "withdrawal_actual_amount"
+	// ApprovalFieldWithdrawalMethod 表示提现收款方式快照业务字段。
+	ApprovalFieldWithdrawalMethod = "withdrawal_method"
+	// ApprovalFieldWithdrawalAccountName 表示提现收款人姓名业务字段。
+	ApprovalFieldWithdrawalAccountName = "withdrawal_account_name"
+	// ApprovalFieldWithdrawalAccountNumber 表示提现收款账号业务字段。
+	ApprovalFieldWithdrawalAccountNumber = "withdrawal_account_number"
+	// ApprovalFieldWithdrawalInvoiceKey 表示申请级发票附件对象存储 Key 列表业务字段。
+	ApprovalFieldWithdrawalInvoiceKey = "withdrawal_invoice_key"
+)
+
 const (
 	// ApprovalFieldValueTypeString 表示业务字段值为普通字符串。
 	ApprovalFieldValueTypeString = "string"

pkg/constants/audit.go

@@ -381,6 +381,34 @@ const (
 	AuditActionCommissionWithdrawalApproved = "commission_withdrawal.approve"
 	// AuditActionCommissionWithdrawalRejected 表示驳回佣金提现申请。
 	AuditActionCommissionWithdrawalRejected = "commission_withdrawal.reject"
+	// AuditActionCommissionWithdrawalAttemptSubmitted 表示代理提交或重提佣金提现审批尝试。
+	AuditActionCommissionWithdrawalAttemptSubmitted = "commission_withdrawal.attempt_submit"
+	// AuditActionCommissionWithdrawalAttemptApproved 表示企业微信终审通过佣金提现并完成冻结扣减。
+	AuditActionCommissionWithdrawalAttemptApproved = "commission_withdrawal.attempt_approve"
+	// AuditActionCommissionWithdrawalAttemptClosed 表示企业微信驳回、撤销或删除佣金提现并释放冻结。
+	AuditActionCommissionWithdrawalAttemptClosed = "commission_withdrawal.attempt_close"
+	// AuditActionCommissionWithdrawalAnomalyFlagged 表示企业微信通过后撤销，仅写入正交异常标记。
+	AuditActionCommissionWithdrawalAnomalyFlagged = "commission_withdrawal.anomaly_flag"
+	// AuditActionCommissionWithdrawalAttemptRejected 表示提现提交在创建业务事实前被拒绝（资格无效、余额不足或越权）。
+	// 该拒绝没有提现单可挂，因此以店铺为主要资源记录拒绝事实。
+	AuditActionCommissionWithdrawalAttemptRejected = "commission_withdrawal.attempt_reject"
+	// AuditActionWithdrawalQualificationSubmitRejected 表示资格提交在创建资料版本前被拒绝（存在待审批版本或参数非法）。
+	// 该拒绝没有资料版本可挂，因此以店铺为主要资源记录拒绝事实。
+	AuditActionWithdrawalQualificationSubmitRejected = "withdrawal_qualification.submit_reject"
+	// AuditActionAgentDistributionRegistrationApproved 表示企业微信通过扫码注册并建立店铺与代理账号。
+	AuditActionAgentDistributionRegistrationApproved = "agent_distribution.registration_approve"
+	// AuditActionAgentDistributionRegistrationRejected 表示企业微信驳回扫码注册，不创建任何实体。
+	AuditActionAgentDistributionRegistrationRejected = "agent_distribution.registration_reject"
+	// AuditActionWithdrawalQualificationSubmitted 表示提交或替换提现资料资格版本。
+	AuditActionWithdrawalQualificationSubmitted = "withdrawal_qualification.submit"
+	// AuditActionWithdrawalQualificationApproved 表示提现资料资格企业微信通过并生效。
+	AuditActionWithdrawalQualificationApproved = "withdrawal_qualification.approve"
+	// AuditActionWithdrawalQualificationRejected 表示提现资料资格被企业微信驳回。
+	AuditActionWithdrawalQualificationRejected = "withdrawal_qualification.reject"
+	// AuditActionWithdrawalQualificationVoided 表示超级管理员填写原因后作废提现资料资格。
+	AuditActionWithdrawalQualificationVoided = "withdrawal_qualification.void"
+	// AuditActionWithdrawalQualificationInvalidated 表示代理店铺停用联动使有效提现资料资格失效。
+	AuditActionWithdrawalQualificationInvalidated = "withdrawal_qualification.invalidate"
 	// AuditActionSystemConfigUpdated 表示更新受控系统配置。
 	AuditActionSystemConfigUpdated = "system_config.updated"
 	// AuditActionPaymentConfigCreated 表示创建支付连接配置。
@@ -670,6 +698,12 @@ const (
 	AuditResourceCommissionRecord = "commission_record"
 	// AuditResourceCommissionWithdrawal 表示佣金提现单资源。
 	AuditResourceCommissionWithdrawal = "commission_withdrawal"
+	// AuditResourceCommissionWithdrawalAttempt 表示提现审批尝试记录资源。
+	AuditResourceCommissionWithdrawalAttempt = "commission_withdrawal_attempt"
+	// AuditResourceAgentDistributionRegistration 表示代理扫码注册待审批记录资源。
+	AuditResourceAgentDistributionRegistration = "agent_distribution_registration"
+	// AuditResourceWithdrawalQualification 表示提现资料资格版本资源。
+	AuditResourceWithdrawalQualification = "withdrawal_qualification"
 	// AuditResourceWeComApplication 表示企业微信应用配置资源。
 	AuditResourceWeComApplication = "wecom_application"
 	// AuditResourceAuthentication 表示不含 Token 或 Cookie 的认证状态资源。
@@ -922,6 +956,16 @@ const (
 	AuditResourceRoleWithdrawalWallet = "withdrawal_wallet"
 	// AuditResourceRoleWithdrawalTransaction 表示提现实际产生的钱包流水。
 	AuditResourceRoleWithdrawalTransaction = "withdrawal_transaction"
+	// AuditResourceRoleWithdrawalAttempt 表示提现审批尝试记录。
+	AuditResourceRoleWithdrawalAttempt = "withdrawal_attempt"
+	// AuditResourceRoleDistributionRegistration 表示代理扫码注册待审批记录主资源。
+	AuditResourceRoleDistributionRegistration = "distribution_registration"
+	// AuditResourceRoleDistributionParentShop 表示扫码注册的上级店铺。
+	AuditResourceRoleDistributionParentShop = "distribution_parent_shop"
+	// AuditResourceRoleQualificationTarget 表示提现资料资格版本主资源。
+	AuditResourceRoleQualificationTarget = "qualification_target"
+	// AuditResourceRoleQualificationShop 表示提现资料资格所属店铺。
+	AuditResourceRoleQualificationShop = "qualification_shop"
 	// AuditResourceRoleIotCardRelatedDevice 表示 IoT 卡操作关联的设备。
 	AuditResourceRoleIotCardRelatedDevice = "iot_card_related_device"
 	// AuditResourceRoleIotCardDeviceBinding 表示 IoT 卡操作关联的设备卡槽绑定。

pkg/constants/commission_withdrawal.go

@@ -0,0 +1,24 @@
+package constants
+
+const (
+	// WithdrawalAnomalyFlagNone 表示提现申请无正交异常。
+	WithdrawalAnomalyFlagNone = 0
+	// WithdrawalAnomalyFlagRevokedAfterApproved 表示企业微信对企业微信已通过的提现申请返回通过后撤销。
+	// 该标记不回滚已到账金额、不重新冻结、不自动重提，仅与原因一并供详情展示与人工处理。
+	WithdrawalAnomalyFlagRevokedAfterApproved = 1
+)
+
+const (
+	// WithdrawalAttemptMaxCount 表示同一提现申请允许的审批尝试上限，防止无限重提。
+	WithdrawalAttemptMaxCount = 50
+)
+
+// GetWithdrawalAnomalyName 返回提现异常标记的中文名称。
+func GetWithdrawalAnomalyName(flag int) string {
+	switch flag {
+	case WithdrawalAnomalyFlagRevokedAfterApproved:
+		return "通过后撤销"
+	default:
+		return "无异常"
+	}
+}

pkg/constants/withdrawal_qualification.go

@@ -0,0 +1,47 @@
+package constants
+
+const (
+	// WithdrawalQualificationSubjectTypeEnterprise 表示企业签约主体。
+	WithdrawalQualificationSubjectTypeEnterprise = "enterprise"
+	// WithdrawalQualificationSubjectTypePersonal 表示个人签约主体。
+	WithdrawalQualificationSubjectTypePersonal = "personal"
+)
+
+const (
+	// WithdrawalQualificationStatusPending 表示资料版本等待企业微信终审。
+	WithdrawalQualificationStatusPending = 0
+	// WithdrawalQualificationStatusApproved 表示资料版本已通过且当前有效。
+	WithdrawalQualificationStatusApproved = 1
+	// WithdrawalQualificationStatusRejected 表示资料版本已被企业微信驳回。
+	WithdrawalQualificationStatusRejected = 2
+	// WithdrawalQualificationStatusInvalidated 表示资料版本已失效或已被超级管理员作废。
+	WithdrawalQualificationStatusInvalidated = 3
+)
+
+// GetWithdrawalQualificationStatusName 返回提现资料资格状态的中文名称。
+func GetWithdrawalQualificationStatusName(status int) string {
+	switch status {
+	case WithdrawalQualificationStatusPending:
+		return "待审批"
+	case WithdrawalQualificationStatusApproved:
+		return "已通过有效"
+	case WithdrawalQualificationStatusRejected:
+		return "已驳回"
+	case WithdrawalQualificationStatusInvalidated:
+		return "已失效"
+	default:
+		return "未知"
+	}
+}
+
+// GetWithdrawalQualificationSubjectTypeName 返回签约主体类型的中文名称。
+func GetWithdrawalQualificationSubjectTypeName(subjectType string) string {
+	switch subjectType {
+	case WithdrawalQualificationSubjectTypeEnterprise:
+		return "企业"
+	case WithdrawalQualificationSubjectTypePersonal:
+		return "个人"
+	default:
+		return "未知"
+	}
+}

pkg/openapi/handlers.go

@@ -29,7 +29,9 @@ func BuildDocHandlers() *bootstrap.Handlers {
 		Shop:                        admin.NewShopHandler(nil, nil),
 		ShopRole:                    admin.NewShopRoleHandler(nil),
 		AdminAuth:                   admin.NewAuthHandler(nil, nil),
-		ShopCommission:              admin.NewShopCommissionHandler(nil),
+		ShopCommission:              admin.NewShopCommissionHandler(nil, nil),
+		WithdrawalQualification:     admin.NewWithdrawalQualificationHandler(nil, nil, nil),
+		AgentDistribution:           app.NewAgentDistributionHandler(nil, nil),
 		CommissionWithdrawal:        admin.NewCommissionWithdrawalHandler(nil, nil),
 		CommissionWithdrawalSetting: admin.NewCommissionWithdrawalSettingHandler(nil),
 		Enterprise:                  admin.NewEnterpriseHandler(nil),