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

1. DTO 层新增 CreateAdminOrderRequest

• 1.1 在 internal/model/dto/order_dto.go 创建 CreateAdminOrderRequest 结构体，仅允许 wallet/offline 支付方式
• 1.2 添加字段验证规则：payment_method 使用 validate:"required,oneof=wallet offline"
• 1.3 复制其他字段定义：order_type、iot_card_id、device_id、package_ids（与 CreateOrderRequest 保持一致）
• 1.4 验证编译：运行 go build ./internal/model/... 确认无编译错误

2. Service 层新增 CreateAdminOrder 方法

• 2.1 在 internal/service/order/service.go 新增 CreateAdminOrder(ctx context.Context, req *dto.CreateAdminOrderRequest, buyerType string, buyerID uint) (*dto.OrderResponse, error) 方法签名
• 2.2 实现步骤 1：调用 validatePurchase() 验证购买合法性（单卡/设备购买、套餐有效性）
• 2.3 实现步骤 2：调用 checkOrderIdempotency() 检查幂等性，如果已创建则返回现有订单
• 2.4 实现步骤 3：调用 checkForceRechargeRequirement() 检查强充要求
• 2.5 实现步骤 4：提取资源所属店铺 ID 和系列 ID（复用现有逻辑）
• 2.6 实现步骤 5：根据 payment_method 路由到不同分支（offline → createOrderWithActivation，wallet → createOrderWithWalletPayment）
• 2.7 实现步骤 6：添加 else 兜底检查，返回错误"后台仅支持钱包支付或线下支付"
• 2.8 验证编译：运行 go build ./internal/service/order/... 确认无编译错误

3. Service 层新增 CreateH5Order 方法

• 3.1 在 internal/service/order/service.go 新增 CreateH5Order(ctx context.Context, req *dto.CreateOrderRequest, buyerType string, buyerID uint) (*dto.OrderResponse, error) 方法签名
• 3.2 将原 Create() 方法的完整逻辑复制到 CreateH5Order() 方法中（保持 H5 端行为不变）
• 3.3 验证编译：运行 go build ./internal/service/order/... 确认无编译错误

4. Service 层重命名原 Create 方法为 CreateLegacy

• 4.1 将 internal/service/order/service.go 的 Create() 方法重命名为 CreateLegacy()（保留作为回滚方案）
• 4.2 添加注释标记：// Deprecated: 使用 CreateAdminOrder 或 CreateH5Order 替代。保留用于回滚。
• 4.3 验证编译：运行 go build ./internal/service/order/... 确认无编译错误

5. Handler 层修复后台订单创建（admin）

• 5.1 修改 internal/handler/admin/order.go 的 Create() 方法：将 DTO 类型从 CreateOrderRequest 改为 CreateAdminOrderRequest
• 5.2 在 c.BodyParser(&req) 后添加参数验证：调用 h.validator.Struct(&req)，验证失败返回 errors.New(errors.CodeInvalidParam)
• 5.3 修改权限检查逻辑：在 else 分支添加兜底检查，返回错误"后台仅支持钱包支付或线下支付"
• 5.4 修改 Service 调用：将 h.service.Create(...) 改为 h.service.CreateAdminOrder(...)
• 5.5 验证编译：运行 go build ./internal/handler/admin/... 确认无编译错误

6. Handler 层修复 H5 端订单创建

• 6.1 修改 internal/handler/h5/order.go 的 Create() 方法：将 Service 调用从 h.service.Create(...) 改为 h.service.CreateH5Order(...)
• 6.2 确认其他逻辑保持不变（DTO 仍使用 CreateOrderRequest，支持 wallet/wechat/alipay）
• 6.3 验证编译：运行 go build ./internal/handler/h5/... 确认无编译错误

7. 错误码检查（可选）

• 7.1 检查 pkg/errors/errors.go 是否已定义以下错误码：CodeInvalidParam、CodeForbidden、CodeInsufficientBalance、CodeWalletNotFound
• 7.2 如果缺少，添加错误码定义（如 CodeInvalidPaymentMethodForAdmin = 40008）— 不需要，所有错误码已存在
• 7.3 验证编译：运行 go build ./pkg/errors/... 确认无编译错误

8. 单元测试 - CreateAdminOrder 方法（跳过：项目禁止自动化测试）

• 8.1-8.8 跳过：项目规范禁止编写自动化测试代码（AGENTS.md）

9. 单元测试 - CreateH5Order 方法（跳过：项目禁止自动化测试）

• 9.1-9.4 跳过：项目规范禁止编写自动化测试代码（AGENTS.md）

10. 集成测试 - 后台订单创建 API（跳过：需人工手动验证）

• 10.1-10.7 跳过：手动测试由用户自行完成

11. 集成测试 - H5 端订单创建 API（跳过：需人工手动验证）

• 11.1-11.5 跳过：手动测试由用户自行完成

12. 钱包余额和流水验证（跳过：需人工手动验证）

• 12.1-12.5 跳过：手动测试由用户自行完成

13. 幂等性和并发测试（跳过：需人工手动验证）

• 13.1-13.4 跳过：手动测试由用户自行完成

14. 错误日志和监控验证（跳过：需人工手动验证）

• 14.1-14.3 跳过：手动测试由用户自行完成

15. 代码质量检查

• 15.1 运行 gofmt -s -w . 格式化代码
• 15.2 运行 go vet ./... 检查代码问题
• 15.3 运行 go build ./... 确认全部编译通过
• 15.4 检查所有新增代码的中文注释：确认导出函数有文档注释，复杂逻辑有实现注释

16. 文档更新

• 16.1 更新功能总结文档：补充后台订单 API 的 Breaking Change 说明（payment_method 必填、仅允许 wallet/offline）

17. 清理和优化（部署前）

• 17.1 检查是否有未使用的导入或变量（使用 IDE 或 go vet）
• 17.2 保留 CreateLegacy() 方法作为回滚方案，已有 Deprecated 标记
• 17.3 确认所有 TODO 注释已处理或转为 issue
• 17.4 跳过：项目禁止自动化测试

18. 提交和归档

• 18.1 使用 git add 暂存所有修改文件
• 18.2 使用 /commit 创建 Git commit，提交消息："修复代理钱包订单创建逻辑漏洞"
• 18.3 使用 /opsx:verify 验证实现与规格一致
• 18.4 使用 /opsx:archive 归档变更，同步 delta specs 到主规格文档