feat: 实现代理钱包订单创建和订单角色追踪功能

新增功能：
- 代理在后台使用 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>

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

@@ -0,0 +1,167 @@
+# 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）