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）

openspec/specs/order-payment/spec.md

@@ -107,3 +107,162 @@
 #### Scenario: 余额扣减后套餐激活失败
 - **WHEN** 余额扣减成功但套餐激活失败
 - **THEN** 事务回滚，余额恢复，订单状态不变
+## ADDED Requirements
+
+### Requirement: 后台钱包一步支付
+
+系统 SHALL 支持后台订单创建时使用钱包支付立即完成订单，无需后续调用支付接口。
+
+#### Scenario: 后台订单创建时钱包支付
+- **WHEN** 代理在后台创建订单，支付方式为 wallet，钱包余额充足
+- **THEN** 系统创建订单，立即扣减钱包余额，订单状态为已支付（`payment_status` = 2），激活套餐
+
+#### Scenario: 后台钱包支付余额不足
+- **WHEN** 代理在后台创建订单，支付方式为 wallet，钱包余额不足
+- **THEN** 系统返回错误"余额不足"，订单创建失败
+
+#### Scenario: 后台钱包支付订单响应
+- **WHEN** 后台钱包支付订单创建成功
+- **THEN** API 响应包含已支付的订单信息，`payment_status` = 2，`payment_method` = "wallet"，`paid_at` 为当前时间
+
+#### Scenario: 后台钱包支付不创建待支付订单
+- **WHEN** 代理在后台创建 wallet 订单
+- **THEN** 系统不创建待支付订单（`payment_status` != 1），直接完成支付
+
+---
+
+### Requirement: H5 钱包两步支付保持不变
+
+系统 SHALL 保持 H5 端钱包支付的两步流程（创建待支付订单 → 调用支付接口）。
+
+#### Scenario: H5 创建待支付订单
+- **WHEN** 个人客户在 H5 端创建订单，支付方式为 wallet
+- **THEN** 系统创建订单，`payment_status` = 1（待支付），不扣减钱包余额
+
+#### Scenario: H5 调用 WalletPay 接口支付
+- **WHEN** 个人客户调用 WalletPay 接口支付待支付订单
+- **THEN** 系统扣减钱包余额，更新订单状态为已支付，激活套餐
+
+#### Scenario: H5 和后台钱包支付流程独立
+- **WHEN** H5 端创建 wallet 订单
+- **THEN** 不影响后台 wallet 订单的一步支付逻辑
+
+---
+
+### Requirement: 钱包流水记录扩展
+
+系统 SHALL 在钱包流水中记录交易子类型和关联店铺，支持按场景筛选。
+
+#### Scenario: 自购钱包流水
+- **WHEN** 代理为自己的资源购买套餐，使用 wallet
+- **THEN** 钱包流水的 `transaction_subtype` = "self_purchase"，`related_shop_id` 为 NULL，`remark` = "购买套餐"
+
+#### Scenario: 代购钱包流水
+- **WHEN** 代理为下级代理购买套餐，使用 wallet
+- **THEN** 钱包流水的 `transaction_subtype` = "purchase_for_subordinate"，`related_shop_id` = 下级代理店铺 ID，`remark` = "为下级代理【XX】购买套餐"
+
+#### Scenario: 钱包流水查询店铺名称
+- **WHEN** 创建代购钱包流水
+- **THEN** 系统查询下级店铺名称，填充到 `remark` 字段
+
+#### Scenario: 钱包流水筛选
+- **WHEN** 代理查询钱包流水，筛选 `transaction_subtype` = "purchase_for_subordinate"
+- **THEN** 系统返回所有为下级代理购买的流水记录
+
+---
+
+### Requirement: 钱包支付乐观锁
+
+系统 SHALL 使用乐观锁防止钱包并发扣款导致余额不一致。
+
+#### Scenario: 钱包扣款使用 version 字段
+- **WHEN** 扣减钱包余额
+- **THEN** SQL 语句包含 `WHERE balance >= ? AND version = ?`，更新时 `version + 1`
+
+#### Scenario: 钱包并发扣款失败
+- **WHEN** 两个请求同时扣减同一钱包
+- **THEN** 只有一个请求成功，另一个返回"余额不足或并发冲突"
+
+#### Scenario: 乐观锁重试逻辑
+- **WHEN** 钱包扣款因 version 冲突失败
+- **THEN** 系统不自动重试，返回错误（由客户端决定是否重试）
+
+---
+
+### Requirement: 钱包支付幂等性
+
+系统 SHALL 防止同一订单重复创建和重复扣款。
+
+#### Scenario: 订单创建幂等性检查
+- **WHEN** 同一买家对同一载体的同一套餐组合在短时间内重复创建订单
+- **THEN** 系统返回已创建的订单，不重复扣款
+
+#### Scenario: 幂等性使用 Redis 业务键
+- **WHEN** 检查订单幂等性
+- **THEN** 系统使用 Redis key `order:idempotency:{buyer_type}:{buyer_id}:{order_type}:{carrier_type}:{carrier_id}:{sorted_package_ids}`
+
+#### Scenario: 幂等性 TTL
+- **WHEN** 订单创建成功后标记幂等性
+- **THEN** Redis key 的 TTL 为 3 分钟
+
+#### Scenario: 分布式锁防止并发
+- **WHEN** 订单创建前检查幂等性
+- **THEN** 系统使用分布式锁 `order:create:lock:{carrier_type}:{carrier_id}`，TTL 10 秒
+
+---
+
+### Requirement: 后台订单 API 响应扩展
+
+系统 SHALL 在后台订单创建和查询 API 响应中包含钱包支付相关字段。
+
+#### Scenario: 订单响应包含实际支付金额
+- **WHEN** 查询钱包支付的订单
+- **THEN** 响应包含 `actual_paid_amount` 字段
+
+#### Scenario: 订单响应包含操作者信息
+- **WHEN** 查询代购订单
+- **THEN** 响应包含 `operator_id`、`operator_type`、`operator_name` 字段
+
+#### Scenario: 订单响应包含购买备注
+- **WHEN** 查询上级代理购买的订单
+- **THEN** 响应包含 `purchase_remark` 字段，如"由上级代理【XX】购买"
+
+---
+
+### Requirement: 钱包支付错误处理
+
+系统 SHALL 在钱包支付失败时返回明确的错误信息。
+
+#### Scenario: 钱包不存在
+- **WHEN** 钱包支付时钱包不存在
+- **THEN** 系统返回错误"钱包不存在"（`CodeWalletNotFound`）
+
+#### Scenario: 余额不足
+- **WHEN** 钱包支付时余额不足
+- **THEN** 系统返回错误"余额不足"（`CodeInsufficientBalance`）
+
+#### Scenario: 并发冲突
+- **WHEN** 钱包扣款因 version 冲突失败
+- **THEN** 系统返回错误"余额不足或并发冲突"（`CodeInsufficientBalance`）
+
+#### Scenario: 套餐激活失败
+- **WHEN** 钱包扣款成功但套餐激活失败
+- **THEN** 事务回滚，钱包余额恢复，返回激活失败错误
+
+---
+
+### Requirement: 钱包支付与第三方支付的区别
+
+系统 SHALL 区分后台钱包支付和第三方支付的业务逻辑。
+
+#### Scenario: 后台不支持第三方支付
+- **WHEN** 代理在后台创建订单时选择 wechat 或 alipay
+- **THEN** 系统返回错误"后台只支持 wallet 和 offline 支付方式"
+
+#### Scenario: H5 支持第三方支付
+- **WHEN** 个人客户在 H5 端创建订单时选择 wechat 或 alipay
+- **THEN** 系统创建待支付订单，返回支付参数（prepay_id 或 h5_url）
+
+#### Scenario: 钱包支付不需要支付参数
+- **WHEN** 后台钱包支付订单创建成功
+- **THEN** 响应不包含 prepay_id、h5_url 等第三方支付参数

openspec/specs/purchase-on-behalf/spec.md

@@ -143,3 +143,134 @@
 #### Scenario: 线下支付只用于代购
 - **WHEN** payment_method = "offline"
 - **THEN** 订单必须标记为 is_purchase_on_behalf = true
+## ADDED Requirements
+
+### Requirement: 代理钱包代购
+
+系统 SHALL 允许代理使用钱包支付（wallet）为下级代理创建代购订单，从自己钱包扣款并立即激活套餐。
+
+#### Scenario: 代理为下级代理钱包代购
+- **WHEN** 代理选择下级代理的资源创建订单，支付方式为 wallet
+- **THEN** 系统创建订单，`buyer_id` = 下级代理店铺 ID，`operator_id` = 操作者店铺 ID，`is_purchase_on_behalf` = true，`payment_method` = "wallet"，`payment_status` = 2（已支付）
+
+#### Scenario: 钱包代购扣款操作者钱包
+- **WHEN** 代理使用 wallet 为下级代理购买套餐
+- **THEN** 系统从操作者（上级代理）的钱包扣款
+
+#### Scenario: 钱包代购使用操作者成本价扣款
+- **WHEN** 一级代理（成本价 80 元）为二级代理（成本价 100 元）的资源创建 wallet 代购订单
+- **THEN** 系统从一级代理钱包扣款 80 元（操作者成本价）
+
+#### Scenario: 钱包代购订单金额显示买家成本价
+- **WHEN** 一级代理为二级代理钱包代购
+- **THEN** 订单的 `total_amount` = 100 元（买家成本价），`actual_paid_amount` = 80 元（操作者实际扣款）
+
+#### Scenario: 钱包代购余额不足
+- **WHEN** 代理使用 wallet 代购，但钱包余额不足
+- **THEN** 系统返回错误"余额不足"，订单创建失败
+
+#### Scenario: 钱包代购自动激活套餐
+- **WHEN** 钱包代购订单创建成功
+- **THEN** 系统自动激活套餐（创建 PackageUsage 记录）
+
+#### Scenario: 钱包代购不触发佣金
+- **WHEN** 代理使用 wallet 代购订单完成
+- **THEN** 系统不计算佣金，不发放佣金（操作者已赚取成本价差）
+
+#### Scenario: 钱包代购创建钱包流水
+- **WHEN** 代理使用 wallet 代购扣款成功
+- **THEN** 系统创建钱包流水记录，`transaction_type` = "deduct"，`transaction_subtype` = "purchase_for_subordinate"，`related_shop_id` = 下级代理店铺 ID
+
+---
+
+### Requirement: 代理自购使用钱包
+
+系统 SHALL 允许代理使用钱包支付为自己的资源购买套餐，立即扣款并激活。
+
+#### Scenario: 代理为自己的资源购买套餐
+- **WHEN** 代理选择自己的资源创建订单，支付方式为 wallet
+- **THEN** 系统创建订单，`buyer_id` = 代理店铺 ID，`operator_id` = 代理店铺 ID，`is_purchase_on_behalf` = false，`payment_method` = "wallet"，`payment_status` = 2（已支付）
+
+#### Scenario: 代理自购扣款自己成本价
+- **WHEN** 代理为自己的资源购买套餐，成本价 80 元
+- **THEN** 系统从代理钱包扣款 80 元，订单金额 = 80 元，实际支付 = 80 元
+
+#### Scenario: 代理自购自动激活套餐
+- **WHEN** 代理自购订单创建成功
+- **THEN** 系统自动激活套餐
+
+#### Scenario: 代理自购创建钱包流水
+- **WHEN** 代理自购扣款成功
+- **THEN** 系统创建钱包流水记录，`transaction_type` = "deduct"，`transaction_subtype` = "self_purchase"
+
+---
+
+### Requirement: 钱包代购权限控制
+
+系统 SHALL 在后台订单创建 API 中允许代理使用 wallet 支付方式。
+
+#### Scenario: 代理可使用 wallet
+- **WHEN** 代理账号创建订单时选择支付方式为 wallet
+- **THEN** 系统允许创建订单（不返回权限错误）
+
+#### Scenario: 平台可使用 wallet
+- **WHEN** 平台账号创建订单时选择支付方式为 wallet
+- **THEN** 系统允许创建订单
+
+#### Scenario: 企业账号不可使用 wallet
+- **WHEN** 企业账号尝试在后台创建订单
+- **THEN** 系统返回错误"无权限创建订单"
+
+---
+
+### Requirement: 后台订单钱包支付与 H5 端区分
+
+系统 SHALL 区分后台订单创建和 H5 端订单创建的钱包支付流程。
+
+#### Scenario: 后台 wallet 订单一步完成
+- **WHEN** 代理在后台使用 wallet 创建订单
+- **THEN** 订单创建后立即标记为已支付（`payment_status` = 2），无需调用后续支付接口
+
+#### Scenario: H5 端 wallet 订单两步流程
+- **WHEN** 个人客户在 H5 端使用 wallet 创建订单
+- **THEN** 订单创建后标记为待支付（`payment_status` = 1），需要调用 WalletPay 接口完成支付
+
+---
+
+### Requirement: 钱包代购与平台代购的区别
+
+系统 SHALL 区分钱包代购（wallet）和平台代购（offline）的业务逻辑。
+
+#### Scenario: 平台代购不扣款
+- **WHEN** 平台使用 offline 创建代购订单
+- **THEN** 系统不扣减任何钱包余额
+
+#### Scenario: 钱包代购扣款
+- **WHEN** 代理使用 wallet 创建代购订单
+- **THEN** 系统扣减操作者钱包余额
+
+#### Scenario: 平台代购产生佣金
+- **WHEN** 平台使用 offline 创建代购订单
+- **THEN** 系统计算并发放佣金
+
+#### Scenario: 钱包代购不产生佣金
+- **WHEN** 代理使用 wallet 创建代购订单
+- **THEN** 系统不计算佣金
+
+---
+
+### Requirement: 钱包代购事务保证
+
+系统 SHALL 在事务中完成钱包代购的订单创建、扣款、流水记录、套餐激活。
+
+#### Scenario: 钱包代购事务成功
+- **WHEN** 钱包代购的所有步骤成功
+- **THEN** 事务提交，订单创建、钱包扣款、流水记录、套餐激活全部完成
+
+#### Scenario: 钱包代购事务失败回滚
+- **WHEN** 钱包代购过程中任一步骤失败（如余额不足、套餐激活失败）
+- **THEN** 事务回滚，订单不创建，钱包余额不变
+
+#### Scenario: 钱包代购并发控制
+- **WHEN** 多个请求同时为同一载体创建订单
+- **THEN** 系统使用乐观锁（version 字段）和幂等性检查防止并发问题