feat: 实现套餐管理模块，包含套餐系列、双状态管理、废弃模型清理
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m24s
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 5m24s
- 新增套餐系列管理 (CRUD + 状态切换) - 新增套餐管理 (CRUD + 启用/禁用 + 上架/下架双状态) - 清理 8 个废弃分佣模型及对应数据库表 - Package 模型新增建议成本价、建议售价、上架状态字段 - 完整的 Store/Service/Handler 三层实现 - 包含单元测试和集成测试 - 归档 add-package-module change - 新增多个 OpenSpec changes (订单支付、店铺套餐分配、一次性分佣、卡设备系列绑定)
This commit is contained in:
2
openspec/changes/add-order-payment/.openspec.yaml
Normal file
2
openspec/changes/add-order-payment/.openspec.yaml
Normal file
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-01-27
|
||||
237
openspec/changes/add-order-payment/design.md
Normal file
237
openspec/changes/add-order-payment/design.md
Normal file
@@ -0,0 +1,237 @@
|
||||
## Context
|
||||
|
||||
Phase 3 完成了卡/设备的套餐系列关联，现在需要实现订单和支付流程。核心是"强充"机制：用户必须通过购买套餐来充值，不能直接给钱包充值。这确保每笔资金流入都有对应的套餐购买记录。
|
||||
|
||||
**三类买家**：
|
||||
1. 个人客户：通过 H5/小程序购买，使用卡/设备钱包或第三方支付
|
||||
2. 代理商：通过后台购买，使用店铺钱包
|
||||
3. 企业客户：后台直接分配套餐，不走订单流程（本期不做）
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
**Goals:**
|
||||
- 设计订单和订单明细模型
|
||||
- 实现套餐购买订单创建流程
|
||||
- 实现钱包支付和第三方支付回调
|
||||
- 验证购买权限（卡/设备的套餐系列关联）
|
||||
- 套餐生效后更新流量额度
|
||||
|
||||
**Non-Goals:**
|
||||
- 不实现企业客户的套餐分配（后台直接操作）
|
||||
- 不实现第三方支付发起（仅处理回调）
|
||||
- 不实现佣金计算（Phase 5）
|
||||
- 不实现退款流程
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. 订单模型设计
|
||||
|
||||
**决策**：Order + OrderItem 两级结构
|
||||
|
||||
```go
|
||||
// Order 订单模型
|
||||
type Order struct {
|
||||
gorm.Model
|
||||
BaseModel
|
||||
OrderNo string // 订单号（唯一）
|
||||
OrderType string // 订单类型: single_card-单卡购买 device-设备购买
|
||||
BuyerType string // 买家类型: personal-个人客户 agent-代理商
|
||||
BuyerID uint // 买家ID（个人客户ID或店铺ID）
|
||||
IotCardID uint // IoT卡ID（单卡购买时）
|
||||
DeviceID uint // 设备ID（设备购买时）
|
||||
TotalAmount int64 // 订单总金额（分）
|
||||
PaymentMethod string // 支付方式: wallet-钱包 wechat-微信 alipay-支付宝
|
||||
PaymentStatus int // 支付状态: 1-待支付 2-已支付 3-已取消 4-已退款
|
||||
PaidAt *time.Time // 支付时间
|
||||
CommissionStatus int // 佣金状态: 1-待计算 2-已计算
|
||||
}
|
||||
|
||||
// OrderItem 订单明细模型
|
||||
type OrderItem struct {
|
||||
gorm.Model
|
||||
BaseModel
|
||||
OrderID uint // 订单ID
|
||||
PackageID uint // 套餐ID
|
||||
PackageName string // 套餐名称（快照）
|
||||
Quantity int // 数量（通常为1）
|
||||
UnitPrice int64 // 单价（分）
|
||||
Amount int64 // 小计（分）
|
||||
}
|
||||
```
|
||||
|
||||
**理由**：
|
||||
- 支持一个订单购买多个套餐（虽然初期可能只买一个）
|
||||
- 快照套餐名称，避免套餐修改影响历史订单
|
||||
- 佣金状态用于 Phase 5 的异步佣金计算
|
||||
|
||||
### 2. 订单号生成规则
|
||||
|
||||
**决策**：时间戳 + 随机数
|
||||
|
||||
```
|
||||
格式：ORD{YYYYMMDDHHMMSS}{6位随机数}
|
||||
示例：ORD20260127143052123456
|
||||
```
|
||||
|
||||
**理由**：
|
||||
- 可读性好，包含时间信息
|
||||
- 随机数避免并发冲突
|
||||
- 长度固定，便于存储和展示
|
||||
|
||||
### 3. 购买价格确定
|
||||
|
||||
**决策**：使用 Package.suggested_retail_price 作为统一售价
|
||||
|
||||
```
|
||||
个人客户购买：支付金额 = Package.suggested_retail_price
|
||||
代理为店铺购买：支付金额 = 代理的成本价（用于囤货/测试）
|
||||
```
|
||||
|
||||
**理由**：
|
||||
- 简化首期实现，所有终端用户统一售价
|
||||
- 代理的利润 = suggested_retail_price - 成本价
|
||||
- 后续如需支持代理自定义售价，可扩展 ShopPackageAllocation 增加 retail_price 字段
|
||||
|
||||
**非首期功能**：
|
||||
- 代理自定义售价
|
||||
- 促销折扣价
|
||||
|
||||
---
|
||||
|
||||
### 4. 购买权限验证
|
||||
|
||||
**决策**：多层验证
|
||||
|
||||
```go
|
||||
func ValidatePurchase(card/device, packageID) error {
|
||||
// 1. 获取卡/设备的 series_allocation_id
|
||||
allocationID := card.SeriesAllocationID
|
||||
if allocationID == 0 {
|
||||
return "该卡未关联套餐系列"
|
||||
}
|
||||
|
||||
// 2. 获取套餐信息
|
||||
pkg := GetPackage(packageID)
|
||||
|
||||
// 3. 验证套餐属于该系列
|
||||
allocation := GetAllocation(allocationID)
|
||||
if pkg.SeriesID != allocation.SeriesID {
|
||||
return "该套餐不在可购买范围内"
|
||||
}
|
||||
|
||||
// 4. 验证套餐状态
|
||||
if pkg.Status != 1 || pkg.ShelfStatus != 1 {
|
||||
return "该套餐已下架"
|
||||
}
|
||||
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
### 5. 支付流程
|
||||
|
||||
**决策**：同步钱包支付 + 异步第三方支付
|
||||
|
||||
```
|
||||
钱包支付流程：
|
||||
1. 创建订单（待支付）
|
||||
2. 检查钱包余额
|
||||
3. 扣减钱包余额（事务）
|
||||
4. 更新订单状态（已支付）
|
||||
5. 套餐生效
|
||||
6. 触发佣金计算（异步）
|
||||
|
||||
第三方支付流程：
|
||||
1. 创建订单（待支付）
|
||||
2. 返回订单信息，前端发起支付
|
||||
3. 支付回调更新订单状态
|
||||
4. 套餐生效
|
||||
5. 触发佣金计算（异步）
|
||||
```
|
||||
|
||||
### 6. 套餐生效逻辑
|
||||
|
||||
**决策**：创建 PackageUsage 记录
|
||||
|
||||
```go
|
||||
func ActivatePackage(order *Order) {
|
||||
for _, item := range order.Items {
|
||||
pkg := GetPackage(item.PackageID)
|
||||
|
||||
usage := &PackageUsage{
|
||||
OrderID: order.ID,
|
||||
PackageID: item.PackageID,
|
||||
UsageType: order.OrderType, // single_card 或 device
|
||||
IotCardID: order.IotCardID,
|
||||
DeviceID: order.DeviceID,
|
||||
DataLimitMB: pkg.DataAmountMB,
|
||||
ActivatedAt: time.Now(),
|
||||
ExpiresAt: time.Now().AddDate(0, pkg.DurationMonths, 0),
|
||||
Status: 1, // 生效中
|
||||
}
|
||||
CreatePackageUsage(usage)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 7. API 设计
|
||||
|
||||
```
|
||||
# 订单管理（后台）
|
||||
POST /api/admin/orders 代理创建订单
|
||||
GET /api/admin/orders 订单列表
|
||||
GET /api/admin/orders/:id 订单详情
|
||||
POST /api/admin/orders/:id/cancel 取消订单
|
||||
|
||||
# 订单操作（H5/个人客户）
|
||||
POST /api/h5/orders 个人客户创建订单
|
||||
GET /api/h5/orders 我的订单列表
|
||||
GET /api/h5/orders/:id 订单详情
|
||||
POST /api/h5/orders/:id/pay 钱包支付
|
||||
|
||||
# 支付回调
|
||||
POST /api/callback/wechat-pay 微信支付回调
|
||||
POST /api/callback/alipay 支付宝回调
|
||||
```
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
### 风险 1：并发支付
|
||||
|
||||
**风险**：同一订单被重复支付
|
||||
|
||||
**缓解**：
|
||||
- 支付前检查订单状态
|
||||
- 使用数据库乐观锁或 Redis 分布式锁
|
||||
- 支付回调幂等处理
|
||||
|
||||
### 风险 2：套餐生效失败
|
||||
|
||||
**风险**：支付成功但套餐生效失败
|
||||
|
||||
**缓解**：
|
||||
- 使用事务保证支付和套餐生效原子性
|
||||
- 失败时自动退款或人工处理
|
||||
- 记录详细日志便于排查
|
||||
|
||||
### 风险 3：价格不一致
|
||||
|
||||
**风险**：下单时和支付时套餐价格变化
|
||||
|
||||
**缓解**：
|
||||
- 订单中存储下单时的价格快照
|
||||
- 支付时使用订单金额，不重新查询套餐价格
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **订单超时取消？**
|
||||
- 当前设计：不自动取消
|
||||
- 待确认：是否需要定时任务取消超时未支付订单？
|
||||
|
||||
2. **部分支付？**
|
||||
- 当前设计：不支持
|
||||
- 待确认：是否需要支持钱包余额不足时组合支付？
|
||||
|
||||
3. **代理为终端用户购买？**
|
||||
- 当前设计：代理只能为自己店铺购买
|
||||
- 待确认：是否需要代理帮终端用户购买的场景？
|
||||
70
openspec/changes/add-order-payment/proposal.md
Normal file
70
openspec/changes/add-order-payment/proposal.md
Normal file
@@ -0,0 +1,70 @@
|
||||
## Why
|
||||
|
||||
Phase 3 完成了卡/设备的套餐系列关联，现在需要实现订单和支付流程。核心是"强充"机制：用户不能直接给钱包充值，必须通过购买套餐来充值。这样每笔充值都有对应的套餐购买记录，便于佣金计算和业务追踪。
|
||||
|
||||
## What Changes
|
||||
|
||||
**新增模型：**
|
||||
- `Order`：订单模型，记录套餐购买信息
|
||||
- `OrderItem`：订单明细（支持一个订单购买多个套餐）
|
||||
|
||||
**Order 核心字段：**
|
||||
- 订单号、订单类型（单卡购买/设备购买）
|
||||
- 买家信息（个人客户/代理店铺）
|
||||
- 关联的卡/设备 ID
|
||||
- 支付金额、支付状态、支付方式
|
||||
- 佣金计算状态
|
||||
|
||||
**强充业务流程：**
|
||||
1. 用户选择套餐，创建订单
|
||||
2. 用户支付（微信/支付宝/钱包余额）
|
||||
3. 支付成功后，套餐生效，流量额度增加
|
||||
4. 触发佣金计算（Phase 5）
|
||||
|
||||
**新增 API：**
|
||||
- 创建套餐购买订单
|
||||
- 查询订单列表/详情
|
||||
- 订单支付（钱包支付）
|
||||
- 支付回调处理
|
||||
- 取消订单
|
||||
|
||||
**业务规则：**
|
||||
- 只能购买卡/设备关联的套餐系列下的套餐
|
||||
- 只能购买已上架且启用的套餐
|
||||
- 设备购买时，套餐分配给设备下所有卡（流量共享）
|
||||
- 订单金额 = 套餐零售价（代理设置的售价）
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `order-management`: 订单管理 - 创建/查询/取消套餐购买订单
|
||||
- `order-payment`: 订单支付 - 钱包支付、第三方支付回调处理
|
||||
- `package-purchase-validation`: 套餐购买验证 - 验证卡/设备是否有权购买指定套餐
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
<!-- 无 -->
|
||||
|
||||
## Impact
|
||||
|
||||
**代码影响：**
|
||||
- `internal/model/` - 新增 order.go（Order, OrderItem）
|
||||
- `migrations/` - 创建 tb_order, tb_order_item 表
|
||||
- `internal/handler/` - 新增订单 Handler（admin + app/h5）
|
||||
- `internal/service/` - 新增订单 Service
|
||||
- `internal/store/postgres/` - 新增订单 Store
|
||||
- `internal/model/dto/` - 新增订单相关 DTO
|
||||
|
||||
**API 影响：**
|
||||
- 新增 `/api/admin/orders/*` 后台订单管理
|
||||
- 新增 `/api/h5/orders/*` H5 端订单操作
|
||||
- 新增 `/api/app/orders/*` 个人客户订单操作
|
||||
|
||||
**数据库影响：**
|
||||
- 新增表：`tb_order`, `tb_order_item`
|
||||
|
||||
**依赖关系：**
|
||||
- 依赖 Phase 3（add-card-device-series-bindng）完成
|
||||
- Phase 5（一次性佣金）依赖本期
|
||||
- 依赖现有 Wallet 模型
|
||||
@@ -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** 每个订单的订单号都唯一
|
||||
@@ -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** 事务回滚，余额恢复，订单状态不变
|
||||
@@ -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** 验证失败，返回 "该设备未关联套餐系列"
|
||||
105
openspec/changes/add-order-payment/tasks.md
Normal file
105
openspec/changes/add-order-payment/tasks.md
Normal file
@@ -0,0 +1,105 @@
|
||||
## 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）
|
||||
- [ ] 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 记录）
|
||||
|
||||
## 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 记录创建）
|
||||
Reference in New Issue
Block a user