huang
8ed3d9da93
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m0s
新增功能： - 代理在后台使用 wallet 支付时，订单直接完成（扣款 + 激活套餐） - 支持代理自购和代理代购场景 - 新增订单角色追踪字段（operator_id、operator_type、actual_paid_amount、purchase_role） - 订单查询支持 OR 逻辑（buyer_id 或 operator_id） - 钱包流水记录交易子类型和关联店铺 - 佣金逻辑调整：代理代购不产生佣金 数据库变更： - 订单表新增 4 个字段和 2 个索引 - 钱包流水表新增 2 个字段 - 包含迁移脚本和回滚脚本 文档： - 功能总结文档 - 部署指南 - OpenAPI 文档更新 - Specs 同步（新增 agent-order-role-tracking capability） Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
168 lines
6.0 KiB
Markdown
168 lines
6.0 KiB
Markdown
# Capability: 订单角色追踪
|
||
|
||
## Purpose
|
||
|
||
本 capability 定义订单角色追踪能力，记录并区分订单中的操作者、买家、支付者等角色关系，支持多种代购场景的数据查询和业务分析。
|
||
|
||
## ADDED Requirements
|
||
|
||
### Requirement: 订单操作者记录
|
||
|
||
系统 SHALL 在订单创建时记录操作者信息（谁下的单），区别于买家信息（资源所属者）。
|
||
|
||
#### Scenario: 平台创建订单
|
||
- **WHEN** 平台账号创建订单
|
||
- **THEN** 订单的 `operator_id` 为 NULL，`operator_type` 为 "platform"
|
||
|
||
#### Scenario: 代理创建订单
|
||
- **WHEN** 代理账号创建订单
|
||
- **THEN** 订单的 `operator_id` 为代理店铺 ID，`operator_type` 为 "agent"
|
||
|
||
#### Scenario: 代理自购
|
||
- **WHEN** 代理为自己的资源创建订单
|
||
- **THEN** 订单的 `buyer_id` 等于 `operator_id`
|
||
|
||
#### Scenario: 代理代购
|
||
- **WHEN** 代理为下级代理的资源创建订单
|
||
- **THEN** 订单的 `buyer_id` 为资源所属店铺 ID，`operator_id` 为操作者店铺 ID，两者不同
|
||
|
||
---
|
||
|
||
### Requirement: 实际支付金额记录
|
||
|
||
系统 SHALL 记录订单的实际支付金额，区别于订单金额（买家视角的价格）。
|
||
|
||
#### Scenario: 代理自购订单
|
||
- **WHEN** 代理为自己的资源创建订单，成本价 80 元
|
||
- **THEN** 订单的 `total_amount` = 80 元，`actual_paid_amount` = 80 元
|
||
|
||
#### Scenario: 代理代购订单
|
||
- **WHEN** 一级代理（成本价 80 元）为二级代理（成本价 100 元）的资源创建订单
|
||
- **THEN** 订单的 `total_amount` = 100 元（买家成本价），`actual_paid_amount` = 80 元（操作者实际扣款）
|
||
|
||
#### Scenario: 平台代购订单
|
||
- **WHEN** 平台为代理创建订单
|
||
- **THEN** 订单的 `total_amount` = 代理成本价，`actual_paid_amount` 为 NULL（平台不扣款）
|
||
|
||
---
|
||
|
||
### Requirement: 订单角色枚举
|
||
|
||
系统 SHALL 使用 `purchase_role` 字段标识订单角色关系，支持高效筛选。
|
||
|
||
#### Scenario: 自己购买
|
||
- **WHEN** 代理为自己的资源创建订单
|
||
- **THEN** 订单的 `purchase_role` = "self_purchase"
|
||
|
||
#### Scenario: 上级代理购买
|
||
- **WHEN** 代理查询作为买家的订单，且 `operator_id` 不为 NULL 且不等于 `buyer_id`
|
||
- **THEN** 该订单的 `purchase_role` = "purchased_by_parent"（从买家视角）或 "purchase_for_subordinate"（从操作者视角）
|
||
|
||
#### Scenario: 平台代购
|
||
- **WHEN** 平台为代理创建订单
|
||
- **THEN** 订单的 `purchase_role` = "purchased_by_platform"
|
||
|
||
#### Scenario: 给下级购买
|
||
- **WHEN** 代理为下级代理的资源创建订单
|
||
- **THEN** 订单的 `purchase_role` = "purchase_for_subordinate"
|
||
|
||
---
|
||
|
||
### Requirement: 订单查询增强
|
||
|
||
系统 SHALL 支持代理查询作为买家或操作者的所有订单。
|
||
|
||
#### Scenario: 代理查询自己相关的订单
|
||
- **WHEN** 代理查询订单列表
|
||
- **THEN** 系统返回 `buyer_id = 代理店铺 ID` 或 `operator_id = 代理店铺 ID` 的所有订单
|
||
|
||
#### Scenario: 按订单角色筛选
|
||
- **WHEN** 代理查询订单列表，指定 `purchase_role = "self_purchase"`
|
||
- **THEN** 系统只返回自己购买的订单
|
||
|
||
#### Scenario: 按订单角色筛选给下级购买的订单
|
||
- **WHEN** 代理查询订单列表，指定 `purchase_role = "purchase_for_subordinate"`
|
||
- **THEN** 系统只返回为下级代理购买的订单
|
||
|
||
---
|
||
|
||
### Requirement: 订单响应包含角色信息
|
||
|
||
系统 SHALL 在订单响应中包含操作者和角色信息，支持前端展示。
|
||
|
||
#### Scenario: 订单响应包含操作者 ID
|
||
- **WHEN** 查询订单详情
|
||
- **THEN** 响应包含 `operator_id`、`operator_type` 字段
|
||
|
||
#### Scenario: 订单响应包含操作者名称
|
||
- **WHEN** 查询订单详情，且 `operator_type = "agent"`
|
||
- **THEN** 响应包含 `operator_name` 字段（从 Shop 表查询）
|
||
|
||
#### Scenario: 订单响应包含角色标识
|
||
- **WHEN** 查询订单详情
|
||
- **THEN** 响应包含 `purchase_role`、`is_purchased_by_parent`、`purchase_remark` 字段
|
||
|
||
#### Scenario: 上级代购订单的备注
|
||
- **WHEN** 查询上级代理购买的订单
|
||
- **THEN** `purchase_remark` 为"由上级代理【XX】购买"
|
||
|
||
#### Scenario: 平台代购订单的备注
|
||
- **WHEN** 查询平台代购的订单
|
||
- **THEN** `purchase_remark` 为"由平台代购"
|
||
|
||
---
|
||
|
||
### Requirement: 数据权限保持一致
|
||
|
||
系统 SHALL 确保订单角色追踪不影响现有数据权限逻辑。
|
||
|
||
#### Scenario: 代理只能查询有权限的订单
|
||
- **WHEN** 代理查询订单列表
|
||
- **THEN** 系统应用数据权限过滤，只返回 `buyer_id` 或 `operator_id` 在权限范围内的订单
|
||
|
||
#### Scenario: 平台可查询所有订单
|
||
- **WHEN** 平台账号查询订单列表
|
||
- **THEN** 系统不应用数据权限过滤，返回所有订单
|
||
|
||
---
|
||
|
||
### Requirement: 订单角色常量定义
|
||
|
||
系统 SHALL 在 `internal/model/order.go` 中定义订单角色枚举常量。
|
||
|
||
#### Scenario: 订单角色枚举值
|
||
- **WHEN** 代码中使用订单角色
|
||
- **THEN** 可用的枚举值包括：
|
||
- `PurchaseRoleSelfPurchase` = "self_purchase"
|
||
- `PurchaseRolePurchasedByParent` = "purchased_by_parent"
|
||
- `PurchaseRolePurchasedByPlatform` = "purchased_by_platform"
|
||
- `PurchaseRolePurchaseForSubordinate` = "purchase_for_subordinate"
|
||
|
||
---
|
||
|
||
### Requirement: 数据库索引支持
|
||
|
||
系统 SHALL 为订单角色追踪字段创建索引，支持高效查询。
|
||
|
||
#### Scenario: operator_id 索引
|
||
- **WHEN** 查询 `operator_id = X` 的订单
|
||
- **THEN** 数据库使用 `idx_orders_operator_id` 索引
|
||
|
||
#### Scenario: purchase_role 索引
|
||
- **WHEN** 查询 `purchase_role = 'self_purchase'` 的订单
|
||
- **THEN** 数据库使用 `idx_orders_purchase_role` 索引
|
||
|
||
---
|
||
|
||
### Requirement: 向后兼容性
|
||
|
||
系统 SHALL 确保新增字段不影响现有订单数据和查询。
|
||
|
||
#### Scenario: 现有订单字段为 NULL
|
||
- **WHEN** 查询历史订单
|
||
- **THEN** `operator_id`、`operator_type`、`actual_paid_amount`、`purchase_role` 字段为 NULL 或空值，不影响查询结果
|
||
|
||
#### Scenario: 订单列表查询兼容
|
||
- **WHEN** 代理查询订单列表，不指定 `purchase_role` 筛选
|
||
- **THEN** 系统返回所有订单，包括历史订单（role 为 NULL）
|