junhong_cmp_fiber/openspec/changes/archive/2026-02-28-fix-agent-wallet-order-creation/proposal.md

Why

当前代理在后台创建订单时存在严重的逻辑漏洞：缺少参数验证、权限检查不完整、后台和 H5 端共用同一个 Service 方法，导致代理可以在钱包余额不足时创建"待支付"状态的订单，但后台没有支付界面，订单永远无法完成。这是一个关键的业务逻辑缺陷，影响代理订单的正常流转和用户体验。

What Changes

Handler 层修复（短期）

• 在 internal/handler/admin/order.go 的 Create() 方法中添加参数验证（调用 middleware.ValidateStruct(&req)）
• 在 Handler 层严格检查支付方式：后台只允许 wallet 和 offline，拒绝其他支付方式
• 修复权限检查逻辑：完整覆盖所有支付方式的权限校验

Service 层重构（长期）

• BREAKING: 拆分 OrderService.Create() 方法为两个独立方法：
  • CreateAdminOrder() - 后台订单创建（仅支持 wallet/offline，立即扣款或激活）
  • CreateH5Order() - H5 端订单创建（支持 wallet/wechat/alipay，支持待支付状态）
• CreateAdminOrder() 逻辑：
  • wallet 支付：检查余额 → 扣款 → 创建已支付订单 → 激活套餐（一步到位）
  • offline 支付：直接创建已支付订单 → 激活套餐
  • 余额不足直接拒绝，提示"余额不足"
• CreateH5Order() 逻辑：
  • wallet 支付：冻结余额 → 创建待支付订单
  • wechat/alipay 支付：创建待支付订单
  • 混合支付：冻结钱包部分 → 创建待支付订单

DTO 层修复

• 创建新的 DTO：CreateAdminOrderRequest（仅允许 wallet/offline）
• 保留现有 DTO：CreateOrderRequest（用于 H5 端，允许 wallet/wechat/alipay）

前端修复

• 后台订单创建界面必须传递 payment_method 参数
• 下拉框只显示"钱包支付"和"线下支付"选项

Capabilities

New Capabilities

• admin-order-creation: 后台订单创建流程。包含：参数验证、支付方式限制、钱包余额检查、一步到位扣款逻辑、错误处理。

Modified Capabilities

• order-payment: 修改订单支付流程需求，明确区分后台和 H5 端的支付行为差异（后台立即扣款 vs H5 端支持待支付状态）。

Impact

数据模型：

• 无数据库变更

代码影响：

• internal/model/dto/order_dto.go：
  • 新增 CreateAdminOrderRequest 结构体
  • 保留 CreateOrderRequest 用于 H5 端
• internal/handler/admin/order.go：
  • Create() 方法添加参数验证和支付方式检查
  • 调用新的 CreateAdminOrder() 方法
• internal/handler/h5/order.go：
  • Create() 方法调用新的 CreateH5Order() 方法
• internal/service/order/service.go：
  • BREAKING: 拆分 Create() 为 CreateAdminOrder() 和 CreateH5Order()
  • CreateAdminOrder() 只支持 wallet/offline，立即扣款
  • CreateH5Order() 保留现有逻辑（支持待支付状态）
• pkg/errors/errors.go：
  • 可能新增错误码（如 CodeInvalidPaymentMethodForAdmin）

API 影响：

• POST /api/admin/orders - 请求参数 DTO 变更（新增 CreateAdminOrderRequest）
• POST /api/h5/orders - 无变更（继续使用 CreateOrderRequest）

依赖：

• 无新增依赖

性能考虑：

• 无性能影响（逻辑重构，不增加额外查询）

测试要求：

• 单元测试：
  • CreateAdminOrder() 方法的各种场景（余额充足、余额不足、支付方式非法）
  • CreateH5Order() 方法的各种场景（保持现有行为）
• 集成测试：
  • 后台创建订单 API（wallet 支付、offline 支付、非法支付方式）
  • H5 端创建订单 API（保持现有测试）
• 回归测试：
  • 验证 H5 端订单创建流程不受影响

迁移风险：

• BREAKING CHANGE: 后台和 H5 端调用不同的 Service 方法
• 前端需要同步修改（确保传递 payment_method 参数）
• 部署顺序：先部署后端（向后兼容），再部署前端

回滚方案：

• 保留原 Create() 方法作为 CreateLegacy()，出现问题时快速回滚
• 灰度发布：先在测试环境验证，再逐步上线生产环境