feat: 实现订单支付功能模块

- 新增订单管理、支付回调、购买验证等核心服务
- 实现订单、订单项目的数据存储层和 API 接口
- 添加订单数据库迁移和 DTO 定义
- 更新 API 文档和路由配置
- 同步 3 个新规范到主规范库（订单管理、订单支付、套餐购买验证）
- 完成 OpenSpec 变更归档

Ultraworked with Sisyphus

openspec/changes/add-order-payment/tasks.md

@@ -1,106 +0,0 @@
-## 1. 新增模型
-
-- [ ] 1.1 创建 `internal/model/order.go`，定义 Order 模型（order_no, order_type, buyer_type, buyer_id, iot_card_id, device_id, total_amount, payment_method, payment_status, paid_at, commission_status, commission_config_version）
-- [ ] 1.2 定义 OrderItem 模型（order_id, package_id, package_name, quantity, unit_price, amount）
-
-## 2. 数据库迁移
-
-- [ ] 2.1 创建迁移文件，创建 tb_order 表
-- [ ] 2.2 创建 tb_order_item 表
-- [ ] 2.3 添加索引（order_no 唯一索引, buyer_type+buyer_id, payment_status, iot_card_id, device_id）
-- [ ] 2.4 本地执行迁移验证
-
-## 3. 订单 DTO
-
-- [ ] 3.1 创建 `internal/model/dto/order.go`，定义 CreateOrderRequest（order_type, iot_card_id/device_id, package_ids）
-- [ ] 3.2 定义 OrderListRequest（payment_status, order_type, start_time, end_time, page, page_size）
-- [ ] 3.3 定义 PayOrderRequest（payment_method）
-- [ ] 3.4 定义 OrderResponse（包含订单信息和明细列表）
-- [ ] 3.5 定义 OrderItemResponse
-
-## 4. 订单 Store
-
-- [ ] 4.1 创建 `internal/store/postgres/order_store.go`，实现 Create 方法（事务创建订单和明细）
-- [ ] 4.2 实现 GetByID 方法（含明细）
-- [ ] 4.3 实现 GetByOrderNo 方法
-- [ ] 4.4 实现 Update 方法
-- [ ] 4.5 实现 List 方法（支持分页和筛选）
-- [ ] 4.6 实现 UpdatePaymentStatus 方法
-- [ ] 4.7 实现 GenerateOrderNo 方法（ORD + 时间戳 + 随机数）
-
-## 5. 订单明细 Store
-
-- [ ] 5.1 创建 `internal/store/postgres/order_item_store.go`，实现 BatchCreate 方法
-- [ ] 5.2 实现 ListByOrderID 方法
-
-## 6. 购买验证 Service
-
-- [ ] 6.1 创建 `internal/service/purchase_validation/service.go`，实现 ValidateCardPurchase 方法
-- [ ] 6.2 实现 ValidateDevicePurchase 方法
-- [ ] 6.3 实现 ValidatePackageStatus 方法
-- [ ] 6.4 实现 GetPurchasePrice 方法（根据买家身份返回价格）
-
-## 7. 订单 Service
-
-- [ ] 7.1 创建 `internal/service/order/service.go`，实现 Create 方法（验证权限、创建订单和明细、快照佣金配置版本）
-- [ ] 7.2 实现 Get 方法
-- [ ] 7.3 实现 List 方法
-- [ ] 7.4 实现 Cancel 方法（验证状态、更新为已取消）
-- [ ] 7.5 实现 WalletPay 方法（事务：扣减余额、更新状态、激活套餐、更新销售统计）
-- [ ] 7.6 实现 HandlePaymentCallback 方法（验证签名、幂等处理、激活套餐、更新销售统计）
-- [ ] 7.7 实现 ActivatePackage 辅助方法（创建 PackageUsage 记录、更新 ShopSeriesCommissionStats）
-- [ ] 7.8 实现 SnapshotCommissionConfig 辅助方法（查询并快照当前佣金配置版本）
-
-## 8. 订单 Handler（后台）
-
-- [ ] 8.1 创建 `internal/handler/admin/order.go`，实现 Create 接口
-- [ ] 8.2 实现 Get 接口
-- [ ] 8.3 实现 List 接口
-- [ ] 8.4 实现 Cancel 接口
-
-## 9. 订单 Handler（H5）
-
-- [ ] 9.1 创建 `internal/handler/h5/order.go`，实现 Create 接口
-- [ ] 9.2 实现 Get 接口
-- [ ] 9.3 实现 List 接口
-- [ ] 9.4 实现 WalletPay 接口
-
-## 10. 支付回调 Handler
-
-- [ ] 10.1 创建 `internal/handler/callback/payment.go`，实现 WechatPayCallback 接口
-- [ ] 10.2 实现 AlipayCallback 接口
-
-## 11. Bootstrap 注册
-
-- [ ] 11.1 在 stores.go 中注册 OrderStore, OrderItemStore
-- [ ] 11.2 在 services.go 中注册 PurchaseValidationService, OrderService
-- [ ] 11.3 在 handlers.go 中注册 AdminOrderHandler, H5OrderHandler, PaymentCallbackHandler
-
-## 12. 路由注册
-
-- [ ] 12.1 注册 `/api/admin/orders` 路由组（POST, GET, GET/:id, POST/:id/cancel）
-- [ ] 12.2 注册 `/api/h5/orders` 路由组（POST, GET, GET/:id, POST/:id/pay）
-- [ ] 12.3 注册 `/api/callback/wechat-pay` 回调路由
-- [ ] 12.4 注册 `/api/callback/alipay` 回调路由
-
-## 13. 文档生成器更新
-
-- [ ] 13.1 在 docs.go 和 gendocs/main.go 中添加新 Handler
-- [ ] 13.2 执行文档生成验证
-
-## 14. 测试
-
-- [ ] 14.1 OrderStore 单元测试
-- [ ] 14.2 PurchaseValidationService 单元测试（覆盖各种验证场景）
-- [ ] 14.3 OrderService 单元测试（覆盖创建、支付、取消）
-- [ ] 14.4 WalletPay 事务测试（覆盖成功和失败回滚）
-- [ ] 14.5 订单创建 API 集成测试
-- [ ] 14.6 钱包支付 API 集成测试
-- [ ] 14.7 执行 `go test ./...` 确认通过
-
-## 15. 最终验证
-
-- [ ] 15.1 执行 `go build ./...` 确认编译通过
-- [ ] 15.2 启动服务，手动测试订单创建流程
-- [ ] 15.3 手动测试钱包支付流程
-- [ ] 15.4 验证套餐激活（PackageUsage 记录创建）

openspec/changes/archive/2026-01-28-add-order-payment/tasks.md

@@ -0,0 +1,106 @@
+## 1. 新增模型
+
+- [x] 1.1 创建 `internal/model/order.go`，定义 Order 模型（order_no, order_type, buyer_type, buyer_id, iot_card_id, device_id, total_amount, payment_method, payment_status, paid_at, commission_status, commission_config_version）
+- [x] 1.2 定义 OrderItem 模型（order_id, package_id, package_name, quantity, unit_price, amount）
+
+## 2. 数据库迁移
+
+- [x] 2.1 创建迁移文件，创建 tb_order 表
+- [x] 2.2 创建 tb_order_item 表
+- [x] 2.3 添加索引（order_no 唯一索引, buyer_type+buyer_id, payment_status, iot_card_id, device_id）
+- [x] 2.4 本地执行迁移验证
+
+## 3. 订单 DTO
+
+- [x] 3.1 创建 `internal/model/dto/order.go`，定义 CreateOrderRequest（order_type, iot_card_id/device_id, package_ids）
+- [x] 3.2 定义 OrderListRequest（payment_status, order_type, start_time, end_time, page, page_size）
+- [x] 3.3 定义 PayOrderRequest（payment_method）
+- [x] 3.4 定义 OrderResponse（包含订单信息和明细列表）
+- [x] 3.5 定义 OrderItemResponse
+
+## 4. 订单 Store
+
+- [x] 4.1 创建 `internal/store/postgres/order_store.go`，实现 Create 方法（事务创建订单和明细）
+- [x] 4.2 实现 GetByID 方法（含明细）
+- [x] 4.3 实现 GetByOrderNo 方法
+- [x] 4.4 实现 Update 方法
+- [x] 4.5 实现 List 方法（支持分页和筛选）
+- [x] 4.6 实现 UpdatePaymentStatus 方法
+- [x] 4.7 实现 GenerateOrderNo 方法（ORD + 时间戳 + 随机数）
+
+## 5. 订单明细 Store
+
+- [x] 5.1 创建 `internal/store/postgres/order_item_store.go`，实现 BatchCreate 方法
+- [x] 5.2 实现 ListByOrderID 方法
+
+## 6. 购买验证 Service
+
+- [x] 6.1 创建 `internal/service/purchase_validation/service.go`，实现 ValidateCardPurchase 方法
+- [x] 6.2 实现 ValidateDevicePurchase 方法
+- [x] 6.3 实现 ValidatePackageStatus 方法
+- [x] 6.4 实现 GetPurchasePrice 方法（根据买家身份返回价格）
+
+## 7. 订单 Service
+
+- [x] 7.1 创建 `internal/service/order/service.go`，实现 Create 方法（验证权限、创建订单和明细、快照佣金配置版本）
+- [x] 7.2 实现 Get 方法
+- [x] 7.3 实现 List 方法
+- [x] 7.4 实现 Cancel 方法（验证状态、更新为已取消）
+- [x] 7.5 实现 WalletPay 方法（事务：扣减余额、更新状态、激活套餐、更新销售统计）
+- [x] 7.6 实现 HandlePaymentCallback 方法（验证签名、幂等处理、激活套餐、更新销售统计）
+- [x] 7.7 实现 ActivatePackage 辅助方法（创建 PackageUsage 记录、更新 ShopSeriesCommissionStats）
+- [x] 7.8 实现 SnapshotCommissionConfig 辅助方法（查询并快照当前佣金配置版本）
+
+## 8. 订单 Handler（后台）
+
+- [x] 8.1 创建 `internal/handler/admin/order.go`，实现 Create 接口
+- [x] 8.2 实现 Get 接口
+- [x] 8.3 实现 List 接口
+- [x] 8.4 实现 Cancel 接口
+
+## 9. 订单 Handler（H5）
+
+- [x] 9.1 创建 `internal/handler/h5/order.go`，实现 Create 接口
+- [x] 9.2 实现 Get 接口
+- [x] 9.3 实现 List 接口
+- [x] 9.4 实现 WalletPay 接口
+
+## 10. 支付回调 Handler
+
+- [x] 10.1 创建 `internal/handler/callback/payment.go`，实现 WechatPayCallback 接口
+- [x] 10.2 实现 AlipayCallback 接口
+
+## 11. Bootstrap 注册
+
+- [x] 11.1 在 stores.go 中注册 OrderStore, OrderItemStore
+- [x] 11.2 在 services.go 中注册 PurchaseValidationService, OrderService
+- [x] 11.3 在 handlers.go 中注册 AdminOrderHandler, H5OrderHandler, PaymentCallbackHandler
+
+## 12. 路由注册
+
+- [x] 12.1 注册 `/api/admin/orders` 路由组（POST, GET, GET/:id, POST/:id/cancel）
+- [x] 12.2 注册 `/api/h5/orders` 路由组（POST, GET, GET/:id, POST/:id/pay）
+- [x] 12.3 注册 `/api/callback/wechat-pay` 回调路由
+- [x] 12.4 注册 `/api/callback/alipay` 回调路由
+
+## 13. 文档生成器更新
+
+- [x] 13.1 在 docs.go 和 gendocs/main.go 中添加新 Handler
+- [x] 13.2 执行文档生成验证
+
+## 14. 测试
+
+- [x] 14.1 OrderStore 单元测试
+- [x] 14.2 PurchaseValidationService 单元测试（覆盖各种验证场景）
+- [x] 14.3 OrderService 单元测试（覆盖创建、支付、取消）
+- [x] 14.4 WalletPay 事务测试（覆盖成功和失败回滚）
+- [x] 14.5 订单创建 API 集成测试
+- [x] 14.6 钱包支付 API 集成测试
+- [x] 14.7 执行 `go test ./...` 确认通过
+
+## 15. 最终验证
+
+- [x] 15.1 执行 `go build ./...` 确认编译通过
+- [x] 15.2 启动服务，手动测试订单创建流程
+- [x] 15.3 手动测试钱包支付流程
+- [x] 15.4 验证套餐激活（PackageUsage 记录创建）

openspec/specs/order-management/spec.md

@@ -0,0 +1,85 @@
+## ADDED Requirements
+
+### Requirement: 创建套餐购买订单
+
+系统 SHALL 允许买家创建套餐购买订单。订单类型分为单卡购买和设备购买。创建前 MUST 验证购买权限。
+
+#### Scenario: 个人客户创建单卡订单
+- **WHEN** 个人客户为自己的卡创建订单，选择一个套餐
+- **THEN** 系统创建订单，状态为待支付，返回订单信息
+
+#### Scenario: 个人客户创建设备订单
+- **WHEN** 个人客户为自己的设备创建订单
+- **THEN** 系统创建订单，订单类型为设备购买
+
+#### Scenario: 代理创建订单
+- **WHEN** 代理为店铺关联的卡/设备创建订单
+- **THEN** 系统创建订单，买家类型为代理商，买家ID为店铺ID
+
+#### Scenario: 套餐不在可购买范围
+- **WHEN** 买家尝试购买不在关联系列下的套餐
+- **THEN** 系统返回错误 "该套餐不在可购买范围内"
+
+#### Scenario: 套餐已下架
+- **WHEN** 买家尝试购买已下架的套餐
+- **THEN** 系统返回错误 "该套餐已下架"
+
+---
+
+### Requirement: 查询订单列表
+
+系统 SHALL 提供订单列表查询，支持按支付状态、订单类型、时间范围筛选。
+
+#### Scenario: 个人客户查询自己的订单
+- **WHEN** 个人客户查询订单列表
+- **THEN** 系统只返回该客户的订单
+
+#### Scenario: 代理查询店铺订单
+- **WHEN** 代理查询订单列表
+- **THEN** 系统返回该店铺及下级店铺的订单
+
+#### Scenario: 按支付状态筛选
+- **WHEN** 指定支付状态筛选
+- **THEN** 系统只返回匹配状态的订单
+
+---
+
+### Requirement: 查询订单详情
+
+系统 SHALL 允许买家查询订单详情，包含订单明细。
+
+#### Scenario: 查询订单详情
+- **WHEN** 买家查询指定订单详情
+- **THEN** 系统返回订单信息和订单明细列表
+
+#### Scenario: 查询他人订单
+- **WHEN** 买家尝试查询不属于自己的订单
+- **THEN** 系统返回 "订单不存在" 错误
+
+---
+
+### Requirement: 取消订单
+
+系统 SHALL 允许买家取消未支付的订单。
+
+#### Scenario: 取消待支付订单
+- **WHEN** 买家取消一个待支付的订单
+- **THEN** 系统更新订单状态为已取消
+
+#### Scenario: 取消已支付订单
+- **WHEN** 买家尝试取消已支付的订单
+- **THEN** 系统返回错误 "已支付订单无法取消"
+
+---
+
+### Requirement: 订单号生成
+
+系统生成的订单号 MUST 全局唯一，格式为 ORD{YYYYMMDDHHMMSS}{6位随机数}。
+
+#### Scenario: 订单号格式
+- **WHEN** 创建新订单
+- **THEN** 订单号格式为 ORD + 14位时间戳 + 6位随机数
+
+#### Scenario: 订单号唯一
+- **WHEN** 并发创建多个订单
+- **THEN** 每个订单的订单号都唯一

openspec/specs/order-payment/spec.md

@@ -0,0 +1,75 @@
+## ADDED Requirements
+
+### Requirement: 钱包支付
+
+系统 SHALL 支持使用钱包余额支付订单。支付成功后 MUST 扣减钱包余额并激活套餐。
+
+#### Scenario: 钱包余额充足
+- **WHEN** 买家使用钱包支付，余额充足
+- **THEN** 系统扣减钱包余额，更新订单状态为已支付，创建套餐使用记录
+
+#### Scenario: 钱包余额不足
+- **WHEN** 买家使用钱包支付，余额不足
+- **THEN** 系统返回错误 "钱包余额不足"
+
+#### Scenario: 订单已支付
+- **WHEN** 买家尝试支付已支付的订单
+- **THEN** 系统返回错误 "订单已支付"
+
+#### Scenario: 订单已取消
+- **WHEN** 买家尝试支付已取消的订单
+- **THEN** 系统返回错误 "订单已取消"
+
+---
+
+### Requirement: 第三方支付回调
+
+系统 SHALL 处理微信支付和支付宝的支付回调。回调处理 MUST 幂等。
+
+#### Scenario: 微信支付成功回调
+- **WHEN** 收到微信支付成功回调
+- **THEN** 系统验证签名，更新订单状态，激活套餐，返回成功响应
+
+#### Scenario: 支付宝成功回调
+- **WHEN** 收到支付宝支付成功回调
+- **THEN** 系统验证签名，更新订单状态，激活套餐，返回成功响应
+
+#### Scenario: 重复回调
+- **WHEN** 收到已处理订单的重复回调
+- **THEN** 系统返回成功响应，不重复处理
+
+#### Scenario: 签名验证失败
+- **WHEN** 回调签名验证失败
+- **THEN** 系统拒绝处理，返回失败响应
+
+---
+
+### Requirement: 套餐激活
+
+支付成功后系统 MUST 激活套餐，创建 PackageUsage 记录。
+
+#### Scenario: 单卡套餐激活
+- **WHEN** 单卡订单支付成功
+- **THEN** 系统创建 PackageUsage，usage_type 为 single_card，关联 iot_card_id
+
+#### Scenario: 设备套餐激活
+- **WHEN** 设备订单支付成功
+- **THEN** 系统创建 PackageUsage，usage_type 为 device，关联 device_id
+
+#### Scenario: 套餐有效期计算
+- **WHEN** 套餐激活
+- **THEN** 有效期 = 激活时间 + 套餐时长（月）
+
+---
+
+### Requirement: 支付事务保证
+
+钱包支付 MUST 在事务中完成：余额扣减、订单状态更新、套餐激活。任一步骤失败则全部回滚。
+
+#### Scenario: 事务成功
+- **WHEN** 所有步骤成功
+- **THEN** 事务提交，支付完成
+
+#### Scenario: 余额扣减后套餐激活失败
+- **WHEN** 余额扣减成功但套餐激活失败
+- **THEN** 事务回滚，余额恢复，订单状态不变

openspec/specs/package-purchase-validation/spec.md

@@ -0,0 +1,67 @@
+## ADDED Requirements
+
+### Requirement: 验证卡/设备的套餐购买权限
+
+创建订单前系统 MUST 验证卡/设备是否有权购买指定套餐。
+
+#### Scenario: 卡有套餐系列关联
+- **WHEN** 卡的 series_allocation_id 有值，且套餐属于该系列
+- **THEN** 验证通过
+
+#### Scenario: 卡无套餐系列关联
+- **WHEN** 卡的 series_allocation_id 为空
+- **THEN** 验证失败，返回 "该卡未关联套餐系列"
+
+#### Scenario: 套餐不属于关联系列
+- **WHEN** 套餐的 series_id 与卡关联的分配系列不匹配
+- **THEN** 验证失败，返回 "该套餐不在可购买范围内"
+
+#### Scenario: 系列分配已禁用
+- **WHEN** 卡关联的系列分配状态为禁用
+- **THEN** 验证失败，返回 "套餐系列已禁用"
+
+---
+
+### Requirement: 验证套餐状态
+
+创建订单前系统 MUST 验证套餐处于可购买状态。
+
+#### Scenario: 套餐启用且上架
+- **WHEN** 套餐 status=1 且 shelf_status=1
+- **THEN** 验证通过
+
+#### Scenario: 套餐已禁用
+- **WHEN** 套餐 status=2
+- **THEN** 验证失败，返回 "套餐已禁用"
+
+#### Scenario: 套餐已下架
+- **WHEN** 套餐 shelf_status=2
+- **THEN** 验证失败，返回 "套餐已下架"
+
+---
+
+### Requirement: 获取购买价格
+
+系统 MUST 根据买家身份返回正确的购买价格。
+
+#### Scenario: 个人客户购买
+- **WHEN** 个人客户购买套餐
+- **THEN** 使用 Package.suggested_retail_price 作为支付金额
+
+#### Scenario: 代理为店铺购买
+- **WHEN** 代理为自己店铺购买套餐（囤货/测试）
+- **THEN** 使用代理的成本价作为支付金额
+
+---
+
+### Requirement: 设备购买时的卡验证
+
+设备购买套餐时 MUST 使用设备的 series_allocation_id 验证，不使用设备下单卡的关联。
+
+#### Scenario: 设备有系列关联
+- **WHEN** 设备的 series_allocation_id 有值
+- **THEN** 使用设备的关联验证购买权限
+
+#### Scenario: 设备无系列关联
+- **WHEN** 设备的 series_allocation_id 为空
+- **THEN** 验证失败，返回 "该设备未关联套餐系列"