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>

migrations/000067_add_operator_fields_to_orders.down.sql

@@ -0,0 +1,8 @@
+-- 回滚订单表字段变更
+DROP INDEX IF EXISTS idx_orders_operator_id;
+DROP INDEX IF EXISTS idx_orders_purchase_role;
+
+ALTER TABLE tb_order DROP COLUMN IF EXISTS operator_id;
+ALTER TABLE tb_order DROP COLUMN IF EXISTS operator_type;
+ALTER TABLE tb_order DROP COLUMN IF EXISTS actual_paid_amount;
+ALTER TABLE tb_order DROP COLUMN IF EXISTS purchase_role;

migrations/000067_add_operator_fields_to_orders.up.sql

@@ -0,0 +1,16 @@
+-- 添加订单操作者和角色字段
+ALTER TABLE tb_order ADD COLUMN operator_id INT;
+ALTER TABLE tb_order ADD COLUMN operator_type VARCHAR(20);
+ALTER TABLE tb_order ADD COLUMN actual_paid_amount BIGINT;
+ALTER TABLE tb_order ADD COLUMN purchase_role VARCHAR(50);
+
+-- 添加字段注释
+COMMENT ON COLUMN tb_order.operator_id IS '操作者ID（谁下的单）';
+COMMENT ON COLUMN tb_order.operator_type IS '操作者类型（platform/agent）';
+COMMENT ON COLUMN tb_order.actual_paid_amount IS '实际支付金额（分）';
+COMMENT ON COLUMN tb_order.purchase_role IS '订单角色（self_purchase/purchased_by_parent/purchased_by_platform/purchase_for_subordinate）';
+
+-- 添加索引
+-- 注意：生产环境建议手动执行 CREATE INDEX CONCURRENTLY 避免锁表
+CREATE INDEX IF NOT EXISTS idx_orders_operator_id ON tb_order(operator_id);
+CREATE INDEX IF NOT EXISTS idx_orders_purchase_role ON tb_order(purchase_role);

migrations/000068_add_transaction_subtype_to_wallet_transaction.down.sql

@@ -0,0 +1,3 @@
+-- 回滚钱包流水表字段变更
+ALTER TABLE tb_agent_wallet_transaction DROP COLUMN IF EXISTS transaction_subtype;
+ALTER TABLE tb_agent_wallet_transaction DROP COLUMN IF EXISTS related_shop_id;

migrations/000068_add_transaction_subtype_to_wallet_transaction.up.sql

@@ -0,0 +1,24 @@
+-- 检查并添加钱包流水表字段（如果不存在）
+DO $$
+BEGIN
+    -- 检查并添加 transaction_subtype 字段
+    IF NOT EXISTS (
+        SELECT 1 FROM information_schema.columns
+        WHERE table_name='tb_agent_wallet_transaction'
+        AND column_name='transaction_subtype'
+    ) THEN
+        ALTER TABLE tb_agent_wallet_transaction ADD COLUMN transaction_subtype VARCHAR(50);
+        COMMENT ON COLUMN tb_agent_wallet_transaction.transaction_subtype IS '交易子类型（细分 order_payment 场景）';
+    END IF;
+
+    -- 检查并添加 related_shop_id 字段
+    IF NOT EXISTS (
+        SELECT 1 FROM information_schema.columns
+        WHERE table_name='tb_agent_wallet_transaction'
+        AND column_name='related_shop_id'
+    ) THEN
+        ALTER TABLE tb_agent_wallet_transaction ADD COLUMN related_shop_id INT;
+        COMMENT ON COLUMN tb_agent_wallet_transaction.related_shop_id IS '关联店铺ID（代购时记录下级店铺）';
+    END IF;
+END
+$$;

migrations/backfill_order_purchase_role.sql

@@ -0,0 +1,43 @@
+-- 数据回填脚本：为历史订单填充 purchase_role 和 operator_type
+-- 用途：将现有平台代购订单标记为 purchased_by_platform
+-- 执行时间：预计 < 1 秒（取决于历史订单数量）
+-- 回滚方法：将 purchase_role 和 operator_type 设为 NULL
+
+BEGIN;
+
+-- 1. 回填平台代购订单（offline + is_purchase_on_behalf = true）
+UPDATE tb_order
+SET
+    purchase_role = 'purchased_by_platform',
+    operator_type = 'platform'
+WHERE
+    payment_method = 'offline'
+    AND is_purchase_on_behalf = true
+    AND purchase_role IS NULL;
+
+-- 2. 显示回填统计信息
+DO $$
+DECLARE
+    updated_count INTEGER;
+BEGIN
+    SELECT COUNT(*) INTO updated_count
+    FROM tb_order
+    WHERE purchase_role = 'purchased_by_platform'
+      AND operator_type = 'platform';
+
+    RAISE NOTICE '已回填 % 条平台代购订单', updated_count;
+END $$;
+
+COMMIT;
+
+-- 验证回填结果
+SELECT
+    purchase_role,
+    operator_type,
+    payment_method,
+    is_purchase_on_behalf,
+    COUNT(*) as count
+FROM tb_order
+WHERE purchase_role IS NOT NULL
+GROUP BY purchase_role, operator_type, payment_method, is_purchase_on_behalf
+ORDER BY count DESC;