junhong_cmp_fiber/openspec/changes/archive/2026-01-31-fix-force-recharge-missing-interfaces/design.md

Context

在 add-force-recharge-system 功能归档后，发现两个关键遗漏：

1. 套餐系列分配强充配置不可管理：

   • 数据库字段已添加：enable_force_recharge、force_recharge_amount、force_recharge_trigger_type
   • Service 层已使用这些字段进行强充验证（RechargeService.GetRechargeCheck、OrderService.GetPurchaseCheck）
   • 但 DTO 层完全没有暴露这些字段，管理员无法通过 API 配置

2. 后台订单创建逻辑重复：

   • 存在两套 DTO：CreateOrderRequest 和 CreatePurchaseOnBehalfRequest（字段完全相同）
   • 存在两个 Service 方法：Create 和 CreatePurchaseOnBehalf（核心逻辑相似，仅支付方式和成本价计算不同）
   • 实际业务中，后台订单只有两种支付方式：
     • wallet：扣代理钱包，需要强充验证，触发佣金
     • offline：线下已收款，不扣钱包，不触发佣金（即代购）

现有架构：

• 强充验证逻辑完整：RechargeService、OrderService 已实现
• 数据模型完整：ShopSeriesAllocation.enable_force_recharge 等字段已存在
• 仅缺少管理接口暴露

Goals / Non-Goals

Goals:

• 暴露强充配置字段到套餐系列分配的 CRUD 接口
• 统一后台订单创建接口，使用 payment_method 字段区分普通订单和代购订单
• 删除重复代码和冗余 DTO
• 保持现有业务逻辑不变（强充验证、佣金计算、成本价计算）

Non-Goals:

• 不修改强充验证逻辑（已在 add-force-recharge-system 中实现）
• 不修改数据库结构（字段已存在）
• 不修改 H5 订单接口（H5 仅支持微信/支付宝支付，不涉及 offline）
• 不修改佣金计算逻辑（CommissionCalculationService 已正确处理 is_purchase_on_behalf）

Decisions

决策 1：强充配置字段作为可选字段暴露

决策：在套餐系列分配的 DTO 中增加强充配置字段，作为可选字段（omitempty）

理由：

• 强充是累计充值强充的可选配置（enable_force_recharge 默认 false）
• 与一次性佣金配置保持一致（也是可选配置）
• 向后兼容：现有数据默认值为 false/0，不影响现有逻辑

实现：

// CreateShopSeriesAllocationRequest
type CreateShopSeriesAllocationRequest struct {
    // ... 现有字段
    EnableForceRecharge      *bool  `json:"enable_force_recharge" description:"是否启用强充(累计充值强充)"`
    ForceRechargeAmount      *int64 `json:"force_recharge_amount" description:"强充金额(分,0表示使用阈值金额)"`
    ForceRechargeTriggerType *int   `json:"force_recharge_trigger_type" description:"强充触发类型(1:单次充值, 2:累计充值)"`
}

// UpdateShopSeriesAllocationRequest (同上)

// ShopSeriesAllocationResponse
type ShopSeriesAllocationResponse struct {
    // ... 现有字段
    EnableForceRecharge      bool  `json:"enable_force_recharge" description:"是否启用强充"`
    ForceRechargeAmount      int64 `json:"force_recharge_amount" description:"强充金额(分)"`
    ForceRechargeTriggerType int   `json:"force_recharge_trigger_type" description:"强充触发类型"`
}

替代方案：

• ❌ 独立接口配置强充：增加接口复杂度，与现有设计不一致
• ❌ 强制字段：破坏向后兼容性，现有创建请求会失败

决策 2：使用 payment_method 字段统一订单创建

决策：在 CreateOrderRequest 增加 payment_method 必填字段，删除 CreatePurchaseOnBehalfRequest

理由：

• 后台订单本质上只有两种支付方式：wallet 和 offline
• is_purchase_on_behalf 是业务标识，应由系统自动设置，不应由前端传递
• 减少 DTO 冗余，统一接口设计

映射关系：

payment_method = "wallet"  → is_purchase_on_behalf = false (普通订单)
payment_method = "offline" → is_purchase_on_behalf = true  (代购订单)

实现：

type CreateOrderRequest struct {
    OrderType     string `json:"order_type" validate:"required,oneof=single_card device"`
    IotCardID     *uint  `json:"iot_card_id" validate:"required_if=OrderType single_card"`
    DeviceID      *uint  `json:"device_id" validate:"required_if=OrderType device"`
    PackageIDs    []uint `json:"package_ids" validate:"required,min=1,max=10"`
    PaymentMethod string `json:"payment_method" validate:"required,oneof=wallet offline"` // 新增
}

替代方案：

• ❌ 保留两个 DTO：代码重复，维护成本高
• ❌ 使用 is_purchase_on_behalf 字段：业务标识不应由前端控制，存在安全风险

决策 3：Service 层合并逻辑但保留代码分支

决策：合并 Service.Create 和 Service.CreatePurchaseOnBehalf 为统一方法，内部使用 if/else 分支处理

理由：

• 两个方法核心流程相似（验证 → 计算价格 → 创建订单 → 激活套餐 → 触发佣金）
• 关键差异仅在：
  • 成本价计算：普通订单用卖家成本价，代购用买家成本价
  • 支付状态：普通订单待支付，代购直接已支付
  • 佣金触发：通过 is_purchase_on_behalf 标识控制
• 统一方法减少接口暴露，降低复杂度

实现结构：

func (s *Service) Create(ctx context.Context, req *dto.CreateOrderRequest, userType string, shopID, userID uint) (*dto.OrderResponse, error) {
    // 1. 通用验证（资源存在、套餐有效）
    validationResult, err := s.validatePurchase(ctx, req)
    
    // 2. 根据 payment_method 分支处理
    var order *model.Order
    if req.PaymentMethod == model.PaymentMethodOffline {
        // 代购逻辑
        order = s.buildPurchaseOnBehalfOrder(ctx, req, validationResult, userID)
    } else {
        // 普通逻辑
        order = s.buildNormalOrder(ctx, req, validationResult, shopID, userID)
    }
    
    // 3. 通用创建流程（保存订单 → 激活套餐 → 触发佣金）
    return s.createOrderCommon(ctx, order, validationResult)
}

替代方案：

• ❌ 保留两个独立方法：Handler 需要路由逻辑，接口复杂度高
• ❌ 完全合并为一个线性方法：可读性差，分支逻辑混乱

决策 4：Handler 层权限验证前置

决策：在 OrderHandler.Create 中根据 payment_method 进行权限验证，再调用 Service

理由：

• 权限验证是 Handler 层职责
• 提前拦截非法请求，避免无效的 Service 调用
• 明确业务规则：offline 仅平台可用，wallet 代理和平台都可用

实现：

func (h *OrderHandler) Create(c *fiber.Ctx) error {
    var req dto.CreateOrderRequest
    // ... 解析请求
    
    ctx := c.UserContext()
    userType := middleware.GetUserTypeFromContext(ctx)
    shopID := middleware.GetShopIDFromContext(ctx)
    userID := middleware.GetUserIDFromContext(ctx)
    
    // 权限验证
    if req.PaymentMethod == model.PaymentMethodOffline {
        if userType != constants.UserTypeSuperAdmin && userType != constants.UserTypePlatform {
            return errors.New(errors.CodeForbidden, "只有平台可以使用线下支付")
        }
    } else if req.PaymentMethod == model.PaymentMethodWallet {
        if userType != constants.UserTypeAgent && 
           userType != constants.UserTypePlatform && 
           userType != constants.UserTypeSuperAdmin {
            return errors.New(errors.CodeForbidden, "无权创建订单")
        }
    }
    
    // 调用统一方法
    order, err := h.service.Create(ctx, &req, userType, shopID, userID)
    return response.Success(c, order)
}

替代方案：

• ❌ Service 层验证：违反分层原则，Handler 应负责权限
• ❌ 中间件验证：无法访问请求体字段

Risks / Trade-offs

风险 1：CreateOrderRequest 字段变更可能影响前端

风险：新增 payment_method 必填字段后，现有前端调用会失败

缓解措施：

• 这是后台管理接口，前端由团队控制，可同步修改
• 如需兼容，可设置默认值（wallet），但不推荐（隐式行为会引起混淆）

推荐：要求前端同步修改，明确传递 payment_method

风险 2：删除 CreatePurchaseOnBehalfRequest 可能影响现有调用

风险：如果其他代码引用了 CreatePurchaseOnBehalfRequest DTO，会编译失败

缓解措施：

• 通过 grep 搜索确认无引用（仅在 Service 测试中使用）
• 修改测试用例，使用 CreateOrderRequest 替代

验证步骤：

grep -r "CreatePurchaseOnBehalfRequest" internal/

风险 3：Service 方法签名变更可能影响现有调用

风险：Service.Create 方法签名变更（增加 userType、userID 参数），现有调用方可能失败

缓解措施：

• 通过 LSP 查找所有调用方
• 仅有 OrderHandler.Create 和测试用例调用，影响范围可控

影响范围：

• internal/handler/admin/order.go
• internal/handler/h5/order.go（H5 订单不使用 offline，不受影响）
• internal/service/order/service_test.go

权衡 4：合并方法增加了单个方法的复杂度

权衡：Service.Create 方法内部有 if/else 分支，复杂度略微增加

接受理由：

• 两个独立方法的维护成本更高（重复代码、接口复杂）
• 内部分支清晰，使用辅助方法拆分逻辑（buildPurchaseOnBehalfOrder、buildNormalOrder）
• 测试覆盖两种分支场景，确保正确性

Migration Plan

部署步骤

1. 代码变更：

   • 修改 DTO（3 个文件）
   • 修改 Service（2 个文件）
   • 修改 Handler（1 个文件）
   • 修改测试用例（2 个文件）

2. 测试验证：

   • 运行单元测试确保所有测试通过
   • 运行 lsp_diagnostics 检查类型错误
   • 本地验证接口功能

3. 部署：

   • 无数据库迁移，直接部署即可
   • 通知前端团队同步修改 POST /api/admin/orders 调用

4. 验证：

   • 测试套餐系列分配的创建/更新/查询，确认强充配置正常显示
   • 测试后台订单创建（wallet 和 offline），确认业务逻辑正确

回滚策略

如果发现问题，可以：

1. 回滚代码到上一版本（Git revert）
2. 无数据库变更，回滚无风险
3. 强充配置字段可选，即使旧代码未传递也不会出错

兼容性保障

• 强充配置字段：可选字段，默认值 false/0，现有数据不受影响
• 订单创建接口：payment_method 必填，需前端同步修改（可控）
• 删除的 DTO 和方法：仅内部使用，无外部依赖

Open Questions

无待解决问题。