junhong_cmp_fiber/openspec/specs/agent-order-role-tracking/spec.md

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）