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

Why

在 add-force-recharge-system 功能归档后发现遗漏了关键的管理接口：(1) 套餐系列分配表虽然增加了强充配置字段（enable_force_recharge、force_recharge_amount、force_recharge_trigger_type），但创建/更新/查询接口完全没有暴露这些字段，管理员无法通过 API 配置强充要求；(2) 后台订单接口设计不合理，存在两套独立的创建订单逻辑（普通订单和代购订单），但实际业务中后台订单只有钱包支付和线下支付两种方式，代购本质就是线下支付，不应该独立处理。这导致管理员只能通过直接修改数据库来配置强充，且代码存在重复逻辑和冗余 DTO。

What Changes

• 修复套餐系列分配接口：在 CreateShopSeriesAllocationRequest、UpdateShopSeriesAllocationRequest、ShopSeriesAllocationResponse 中增加强充配置字段
• 修复 ShopSeriesAllocationService：在 Create、Update、buildResponse 方法中处理强充配置的创建、更新和返回
• 统一后台订单接口：在 CreateOrderRequest 增加 payment_method 字段（wallet/offline），删除 CreatePurchaseOnBehalfRequest 冗余 DTO
• 合并订单创建逻辑：将 Service.Create 和 Service.CreatePurchaseOnBehalf 合并为统一方法，根据 payment_method 自动设置 is_purchase_on_behalf 标识
• 修改订单权限验证：OrderHandler.Create 增加支付方式权限检查（offline 仅平台可用，wallet 代理和平台都可用）

Capabilities

New Capabilities

无新增 capabilities

Modified Capabilities

• shop-series-allocation: 增加强充配置字段的 CRUD 接口支持（enable_force_recharge、force_recharge_amount、force_recharge_trigger_type）
• order-management: 统一后台订单创建接口，使用 payment_method 字段替代独立的代购接口，合并重复逻辑

Impact

API 变更

• 修改接口：
  • POST /api/admin/shop-series-allocations - Request 增加强充配置字段（enable_force_recharge、force_recharge_amount、force_recharge_trigger_type）
  • PUT /api/admin/shop-series-allocations/:id - Request 增加强充配置字段
  • GET /api/admin/shop-series-allocations/:id - Response 增加强充配置字段
  • GET /api/admin/shop-series-allocations - Response 列表项增加强充配置字段
  • POST /api/admin/orders - Request 增加 payment_method 字段（wallet/offline），支持统一创建普通订单和代购订单
• 删除接口：
  • 无需删除接口（原 POST /api/admin/orders/purchase-check 保留，仍然有效）

DTO 变更

• 修改 DTO：
  • CreateShopSeriesAllocationRequest - 增加 3 个字段
  • UpdateShopSeriesAllocationRequest - 增加 3 个字段
  • ShopSeriesAllocationResponse - 增加 3 个字段
  • CreateOrderRequest - 增加 payment_method 字段
• 删除 DTO：
  • CreatePurchaseOnBehalfRequest - 冗余，已被统一到 CreateOrderRequest

Service 层变更

• ShopSeriesAllocationService：
  • Create 方法：处理强充配置字段的保存
  • Update 方法：处理强充配置字段的更新
  • buildResponse 方法：返回强充配置字段
• OrderService：
  • Create 方法：增加 payment_method 参数处理，合并代购逻辑（根据 payment_method 自动设置 is_purchase_on_behalf）
  • 删除 CreatePurchaseOnBehalf 方法（逻辑合并到 Create）

Handler 层变更

• OrderHandler.Create：
  • 增加支付方式权限验证（offline 仅平台，wallet 代理和平台）
  • 调用统一的 service.Create 方法

数据库变更

无（字段已在 add-force-recharge-system 中添加）

业务逻辑影响

• 强充配置管理：管理员可以通过 API 配置强充要求，无需直接修改数据库
• 订单创建逻辑：统一处理，减少代码重复，is_purchase_on_behalf 自动根据 payment_method 设置（offline = true, wallet = false）
• 权限控制：明确 offline 支付仅平台可用，wallet 支付代理和平台都可用

测试影响

• 单元测试：需要修改 ShopSeriesAllocationService 和 OrderService 的测试用例
• 集成测试：需要修改套餐系列分配和订单创建的集成测试
• 测试覆盖率：保持 90%+ 覆盖率

向后兼容性

• ✅ 向后兼容：
  • 套餐系列分配的强充字段为可选（默认 false/0），现有数据不受影响
  • 订单接口增加 payment_method 字段为必填，但这是管理后台接口，无外部集成
• ⚠️ 需要注意：
  • CreatePurchaseOnBehalfRequest DTO 删除，如有使用需迁移到 CreateOrderRequest
  • OrderService.CreatePurchaseOnBehalf 方法删除，调用方需改为 Create 方法