# 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）