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/routes/admin.go

@@ -31,6 +31,9 @@ func RegisterAdminRoutes(router fiber.Router, handlers *bootstrap.Handlers, midd
 	if handlers.ShopCommission != nil {
 		registerShopCommissionRoutes(authGroup, handlers.ShopCommission, doc, basePath)
 	}
+	if handlers.WithdrawalQualification != nil {
+		registerWithdrawalQualificationRoutes(authGroup, handlers.WithdrawalQualification, doc, basePath)
+	}
 	if handlers.Shop != nil {
 		registerShopDetailRoute(authGroup, handlers.Shop, doc, basePath)
 	}

internal/routes/agent_distribution_public.go

@@ -0,0 +1,25 @@
+package routes
+
+import (
+	"github.com/gofiber/fiber/v2"
+
+	"github.com/break/junhong_cmp_fiber/internal/handler/app"
+	"github.com/break/junhong_cmp_fiber/internal/model/dto"
+	"github.com/break/junhong_cmp_fiber/pkg/openapi"
+)
+
+// registerAgentDistributionPublicRoutes 注册代理分销公开路由。
+// Fiber 的 Group.Use() 会匹配该前缀下所有请求，因此公开路由必须在个人客户路由的 Use() 之前注册。
+func registerAgentDistributionPublicRoutes(router fiber.Router, handler *app.AgentDistributionHandler, doc *openapi.Generator, basePath string) {
+	if handler == nil {
+		return
+	}
+	Register(router, doc, basePath, "POST", "/agent-distribution-registrations", handler.RegisterAgentDistribution, RouteSpec{
+		Summary:     "代理扫码注册",
+		Description: "公开接口，无需认证。请求必须携带有效分销码、短信已验证手机号与密码；无效分销码、分销码所属店铺已停用、验证码无效或已被消费统一返回“分销码不可用”，且不创建注册记录、店铺或账号。通过后仍需企业微信终审才会创建店铺与代理账号。",
+		Tags:        []string{"个人客户 - 代理分销注册"},
+		Auth:        false,
+		Input:       new(dto.CreateAgentDistributionRegistrationReq),
+		Output:      new(dto.CreateAgentDistributionRegistrationResp),
+	})
+}

internal/routes/personal.go

@@ -22,6 +22,9 @@ func RegisterPersonalCustomerRoutes(router fiber.Router, doc *openapi.Generator,
 	authBasePath := "/auth"
 
 	// === 公开路由（无需认证）===
+	// 代理扫码注册必须在任何 Use() 调用之前注册，否则会被后续认证中间件拦截。
+	registerAgentDistributionPublicRoutes(router, handlers.AgentDistribution, doc, basePath)
+
 	Register(router, doc, basePath, "GET", "/wechat/appid", handlers.ClientWechat.GetAppID, RouteSpec{
 		Summary:     "获取当前生效的公众号 AppID",
 		Description: "用于 C 端免登录场景获取当前生效微信配置中的公众号 AppID，响应仅返回 app_id 字段",

internal/routes/shop.go

@@ -191,6 +191,24 @@ func registerShopCommissionRoutes(router fiber.Router, handler *admin.ShopCommis
 		Auth:    true,
 	})
 
+	Register(shops, doc, groupPath, "PUT", "/:shop_id/withdrawal-requests/:id", handler.ResubmitWithdrawal, RouteSpec{
+		Summary:     "重提被驳回的提现申请",
+		Description: "仅本人代理店铺，且仅已被企业微信驳回的申请可重提。事务内先释放旧未结算冻结再按新金额冻结，新增审批尝试记录与新的审批实例，历史尝试与审批结果不被覆盖。",
+		Tags:        []string{"代理商资金管理"},
+		Input:       new(dto.ResubmitWithdrawalReq),
+		Output:      new(dto.CreateMyWithdrawalResp),
+		Auth:        true,
+	})
+
+	Register(shops, doc, groupPath, "GET", "/:shop_id/withdrawal-requests/:id", handler.WithdrawalDetail, RouteSpec{
+		Summary:     "提现申请详情",
+		Description: "返回指定提现申请及其全部审批尝试记录与正交异常标记，用于详情展示；仅限有数据范围的后台账号。",
+		Tags:        []string{"代理商资金管理"},
+		Input:       new(dto.ShopWithdrawalRequestDetailReq),
+		Output:      new(dto.ShopWithdrawalRequestDetailResp),
+		Auth:        true,
+	})
+
 	commissionRecords := router.Group("/commission-records")
 	crPath := basePath + "/commission-records"
 
@@ -210,3 +228,39 @@ func agentFundManagement(handler fiber.Handler) fiber.Handler {
 		return handler(c)
 	}
 }
+
+// registerWithdrawalQualificationRoutes 注册提现资料资格路由。
+// 资格提交与查询沿用既有认证与数据范围校验，绝不公开。
+func registerWithdrawalQualificationRoutes(router fiber.Router, handler *admin.WithdrawalQualificationHandler, doc *openapi.Generator, basePath string) {
+	shops := router.Group("/shops")
+	shopsPath := basePath + "/shops"
+	qualifications := router.Group("/withdrawal-qualifications")
+	qualificationPath := basePath + "/withdrawal-qualifications"
+
+	Register(shops, doc, shopsPath, "POST", "/:shop_id/withdrawal-qualifications", agentFundManagement(handler.SubmitWithdrawalQualification), RouteSpec{
+		Summary:     "提交提现资料资格",
+		Description: "仅本人代理店铺。合同与法人身份证正反面必填；企业必填统一社会信用代码，个人填写法人身份证号。替换合同或法人身份证时同一事务新增资料版本并使旧有效版本失效，需重新审批通过后才可提现。",
+		Tags:        []string{"代理商提现资格"},
+		Input:       new(dto.SubmitWithdrawalQualificationReq),
+		Output:      new(dto.SubmitWithdrawalQualificationResp),
+		Auth:        true,
+	})
+
+	Register(shops, doc, shopsPath, "GET", "/:shop_id/withdrawal-qualifications", agentFundManagement(handler.ListWithdrawalQualifications), RouteSpec{
+		Summary:     "查询提现资料资格版本",
+		Description: "仅返回当前账号数据范围内店铺的资料版本，按版本从新到旧；证件号脱敏，附件只返回对象存储 Key 引用。",
+		Tags:        []string{"代理商提现资格"},
+		Input:       new(dto.WithdrawalQualificationListReq),
+		Output:      new(dto.WithdrawalQualificationPageResult),
+		Auth:        true,
+	})
+
+	Register(qualifications, doc, qualificationPath, "POST", "/:id/void", agentFundManagement(handler.VoidWithdrawalQualification), RouteSpec{
+		Summary:     "作废提现资料资格",
+		Description: "仅超级管理员；reason 必填。作废后该资格失效且原因可查询，代理提现被拒绝直至重新审批通过。",
+		Tags:        []string{"代理商提现资格"},
+		Input:       new(dto.VoidWithdrawalQualificationParams),
+		Output:      nil,
+		Auth:        true,
+	})
+}