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/application/shop/create.go

@@ -10,6 +10,7 @@ import (
 	"gorm.io/gorm"
 
 	accessauditapp "github.com/break/junhong_cmp_fiber/internal/application/accessaudit"
+	distributiondomain "github.com/break/junhong_cmp_fiber/internal/domain/distribution"
 	"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"
@@ -112,8 +113,9 @@ func createShop(ctx context.Context, tx *gorm.DB, request *dto.CreateShopRequest
 	}
 	shop.Creator = operatorID
 	shop.Updater = operatorID
-	if err := tx.Create(shop).Error; err != nil {
-		return nil, errors.Wrap(errors.CodeDatabaseError, err, "创建店铺失败")
+	// 分销码在创建时随机生成且唯一；冲突时重新生成并重试，不提供人工指定或编辑入口。
+	if err := CreateShopWithDistributionCode(ctx, tx, shop); err != nil {
+		return nil, err
 	}
 
 	account := &model.Account{
@@ -201,6 +203,8 @@ func (s *CreateService) fail(ctx context.Context, request *dto.CreateShopRequest
 func shopCreationData(shop *model.Shop) map[string]any {
 	data := shopProfileData(shop)
 	data["shop_code"] = shop.ShopCode
+	// 分销码是本 Change 新增的建店事实，按脱敏值记录，口径与审批建店路径一致。
+	data["distribution_code_masked"] = distributiondomain.MaskDistributionCode(shop.DistributionCode)
 	data["parent_id"] = shop.ParentID
 	data["level"] = shop.Level
 	return data
@@ -285,7 +289,8 @@ func recordExists(tx *gorm.DB, target any, query string, value any) (bool, error
 
 func newShopResponse(shop *model.Shop, parentName string) *dto.ShopResponse {
 	return &dto.ShopResponse{
-		ID: shop.ID, ShopName: shop.ShopName, ShopCode: shop.ShopCode, ParentID: shop.ParentID,
+		ID: shop.ID, ShopName: shop.ShopName, ShopCode: shop.ShopCode,
+		DistributionCode: shop.DistributionCode, ParentID: shop.ParentID,
 		BusinessOwnerAccountID: shop.BusinessOwnerAccountID,
 		ParentShopName:         parentName, Level: shop.Level, ContactName: shop.ContactName,
 		ContactPhone: shop.ContactPhone, Province: shop.Province, City: shop.City,

internal/application/shop/distribution_code.go

@@ -0,0 +1,95 @@
+package shop
+
+import (
+	"context"
+	stderrors "errors"
+	"reflect"
+
+	"github.com/jackc/pgx/v5/pgconn"
+	"gorm.io/gorm"
+
+	distributiondomain "github.com/break/junhong_cmp_fiber/internal/domain/distribution"
+	"github.com/break/junhong_cmp_fiber/internal/model"
+	"github.com/break/junhong_cmp_fiber/pkg/constants"
+	"github.com/break/junhong_cmp_fiber/pkg/errors"
+)
+
+// distributionCodeConstraint 是分销码条件唯一索引名，用于识别唯一冲突并重试。
+const distributionCodeConstraint = "uk_shop_distribution_code"
+
+// distributionCodeSavepoint 是分销码冲突重试使用的保存点名称。
+const distributionCodeSavepoint = "shop_distribution_code_retry"
+
+// CreateShopWithDistributionCode 在事务内为新店铺生成全局唯一随机分销码并创建店铺。
+//
+// 每次尝试都重新生成随机码；Create 命中分销码唯一约束时重新生成并重试，
+// 最多 constants.ShopDistributionCodeMaxAttempts 次。其他唯一冲突（店铺编号等）不重试，
+// 直接返回数据库错误。
+//
+// 重试依赖真实保存点：每条 Create 包在 GORM 的嵌套事务中执行，冲突时 GORM 自动
+// 回滚到内部保存点，外层事务因此仍可用（PostgreSQL 唯一冲突会中止整个事务，
+// 不回滚到保存点则后续语句必然 25P02，重试不可能生效）。这里刻意不使用裸
+// SavePoint/RollbackTo：GORM 的嵌套事务会自行处理 PrepareStmt 下的连接池切换。
+func CreateShopWithDistributionCode(ctx context.Context, tx *gorm.DB, shop *model.Shop) error {
+	if tx == nil || shop == nil {
+		return errors.New(errors.CodeInvalidParam, "创建店铺参数无效")
+	}
+	// 失败关闭：必须在调用方的事务句柄内执行，否则嵌套事务会自行开启并提交一个新事务，
+	// 破坏调用方的原子性（建店事务与注册审批通过事务均满足该前提）。
+	if !inTransaction(tx) {
+		return errors.New(errors.CodeInvalidStatus, "创建店铺必须传入事务句柄")
+	}
+	for range constants.ShopDistributionCodeMaxAttempts {
+		code, err := distributiondomain.GenerateDistributionCode()
+		if err != nil {
+			return err
+		}
+		if occupied, err := distributionCodeOccupied(ctx, tx, code); err != nil {
+			return err
+		} else if occupied {
+			// 预检命中直接换码，避免把可预期的冲突交给数据库。
+			continue
+		}
+		shop.DistributionCode = code
+		shop.ID = 0
+		createErr := tx.WithContext(ctx).Transaction(func(inner *gorm.DB) error {
+			return inner.Create(shop).Error
+		})
+		if createErr == nil {
+			return nil
+		}
+		if !isDistributionCodeConflict(createErr) {
+			return errors.Wrap(errors.CodeDatabaseError, createErr, "创建店铺失败")
+		}
+		// 分销码冲突：GORM 已回滚到内部保存点，外层事务仍可继续，换码重试。
+	}
+	return errors.New(errors.CodeConflict, "生成分销码冲突，请重试")
+}
+
+// inTransaction 判断句柄是否为已开启的事务，与 GORM 自身识别嵌套事务的方式一致。
+func inTransaction(tx *gorm.DB) bool {
+	if tx == nil || tx.Statement == nil {
+		return false
+	}
+	committer, ok := tx.Statement.ConnPool.(gorm.TxCommitter)
+	return ok && committer != nil && !reflect.ValueOf(committer).IsNil()
+}
+
+// distributionCodeOccupied 预检分销码是否已被未删除店铺占用。
+func distributionCodeOccupied(ctx context.Context, tx *gorm.DB, code string) (bool, error) {
+	var count int64
+	if err := tx.WithContext(ctx).Model(&model.Shop{}).
+		Where("distribution_code = ?", code).Count(&count).Error; err != nil {
+		return false, errors.Wrap(errors.CodeDatabaseError, err, "校验分销码唯一性失败")
+	}
+	return count > 0, nil
+}
+
+// isDistributionCodeConflict 判断错误是否为分销码条件唯一索引冲突。
+func isDistributionCodeConflict(err error) bool {
+	var pgErr *pgconn.PgError
+	if !stderrors.As(err, &pgErr) {
+		return false
+	}
+	return pgErr.Code == "23505" && pgErr.ConstraintName == distributionCodeConstraint
+}

internal/application/shop/update.go

@@ -16,8 +16,21 @@ import (
 
 // UpdateService 收口店铺资料与业务员归属的简单写事务脚本。
 type UpdateService struct {
-	db    *gorm.DB
-	audit accessauditapp.Writer
+	db                       *gorm.DB
+	audit                    accessauditapp.Writer
+	qualificationInvalidator WithdrawalQualificationInvalidator
+}
+
+// WithdrawalQualificationInvalidator 在店铺停用事务内联动失效提现资料资格。
+// 接口定义在应用层，具体实现由装配注入，避免应用层依赖下游用例包。
+type WithdrawalQualificationInvalidator interface {
+	InvalidateByShopDisable(ctx context.Context, tx *gorm.DB, shopID uint, reason string) error
+}
+
+// SetWithdrawalQualificationInvalidator 注入店铺停用联动的提现资料资格失效接缝。
+// 未注入时停用不联动，用于不依赖该能力的旧装配路径。
+func (s *UpdateService) SetWithdrawalQualificationInvalidator(invalidator WithdrawalQualificationInvalidator) {
+	s.qualificationInvalidator = invalidator
 }
 
 // NewUpdateService 创建店铺更新事务脚本。
@@ -81,6 +94,8 @@ func (s *UpdateService) Update(ctx context.Context, shopID uint, request *dto.Up
 		shop.Address = request.Address
 		shop.Status = request.Status
 		shop.Updater = operatorID
+		// 分销码创建后不可修改：Save 写全列，这里显式保留加锁读取到的原值。
+		shop.DistributionCode = before.DistributionCode
 		if err := tx.Save(&shop).Error; err != nil {
 			return errors.Wrap(errors.CodeDatabaseError, err, "更新店铺失败")
 		}
@@ -110,6 +125,14 @@ func (s *UpdateService) Update(ctx context.Context, shopID uint, request *dto.Up
 		if err := s.writeStateAudits(ctx, tx, &before, &shop, parentShop, operatorID); err != nil {
 			return err
 		}
+		// 店铺停用必须使该店铺全部有效提现资料资格失效，且与停用同事务提交。
+		if before.Status != constants.ShopStatusDisabled && shop.Status == constants.ShopStatusDisabled &&
+			s.qualificationInvalidator != nil {
+			if err := s.qualificationInvalidator.InvalidateByShopDisable(
+				ctx, tx, shop.ID, "代理店铺已停用，提现资料资格自动失效"); err != nil {
+				return err
+			}
+		}
 		return nil
 	})
 	if err != nil {