fix(代理分销注册): 验证码改为落库成功后消费并细化失败原因

公开扫码注册原先在审批准备前就消费短信验证码，落库前的任何失败都会烧掉验证码，
客户重试只能得到统一的“分销码不可用”，掩盖了真实失败原因。

- 验证码校验与消费拆分为 CheckCode 与 ConsumeCode，注册记录与审批实例落库成功后才原子消费；
  校验不消费、消费一次性，落库前失败时同一验证码可直接重试
- 分销码无效、所属店铺已停用、上级店铺缺少启用的主账号、验证码错误分别返回各自错误码与提示
- 注册必填字段缺失与请求参数校验失败提示定位到具体字段
- 同步公开接口描述与 agent-distribution-withdrawal 主 Spec 行为契约

internal/handler/app/agent_distribution.go

@@ -6,6 +6,7 @@ import (
 
 	distributionapp "github.com/break/junhong_cmp_fiber/internal/application/distributionwithdrawal"
 	distributiondomain "github.com/break/junhong_cmp_fiber/internal/domain/distribution"
+	"github.com/break/junhong_cmp_fiber/internal/handler/validation"
 	"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"
@@ -29,7 +30,8 @@ func NewAgentDistributionHandler(
 // RegisterAgentDistribution 提交代理扫码注册
 // POST /api/c/v1/agent-distribution-registrations
 // 无需认证、JWT、角色或权限；只创建待审批注册记录，不返回任何账号凭证。
-// 无效分销码、停用上级、验证码无效或已消费统一返回“分销码不可用”且不落库。
+// 分销码无效、上级店铺停用、上级店铺缺少启用的主账号、短信验证码无效分别返回各自提示且不落库；
+// 短信验证码在注册记录落库成功后消费，落库前的失败不消耗验证码。
 func (h *AgentDistributionHandler) RegisterAgentDistribution(c *fiber.Ctx) error {
 	if h.service == nil {
 		return errors.New(errors.CodeServiceUnavailable, "代理分销注册能力尚未配置")
@@ -42,7 +44,7 @@ func (h *AgentDistributionHandler) RegisterAgentDistribution(c *fiber.Ctx) error
 		return errors.New(errors.CodeInternalError, "代理分销注册校验器未配置")
 	}
 	if err := h.validator.Struct(&req); err != nil {
-		return errors.New(errors.CodeInvalidParam, "注册参数不合法")
+		return errors.New(errors.CodeInvalidParam, validation.Message("注册参数不合法", &req, err))
 	}
 	result, err := h.service.Register(c.UserContext(), distributiondomain.RegistrationInput{
 		DistributionCode: req.DistributionCode,