## Why 代理在后台使用钱包支付(wallet)创建订单时,系统只创建待支付订单(payment_status = pending),不扣款也不激活套餐,导致订单无法完成。后台没有支付接口,代理无法对待支付订单进行支付。这个问题阻塞了代理的核心业务场景:代理帮客户购买套餐(代购),从自己钱包扣款并立即激活。 ## What Changes - **新增订单角色追踪字段**:在订单表中新增 `operator_id`(操作者ID)、`operator_type`(操作者类型)、`actual_paid_amount`(实际支付金额)、`purchase_role`(订单角色)字段,用于区分"谁下单"和"谁买单" - **支持代理钱包一步购买**:代理在后台使用 wallet 创建订单时,立即检查余额、扣款、激活套餐,订单状态直接为已支付(一步完成,无需后续支付接口) - **区分代购场景**: - 代理自购(资源属于自己):从自己钱包扣自己的成本价,订单金额 = 实际支付 - 代理代购(资源属于下级):从自己钱包扣自己的成本价,但订单金额显示下级成本价(让下级看到他的成本) - 平台代购(offline):保持现有逻辑(不扣款,立即激活) - **订单查询增强**:代理可以查询 `buyer_id = 自己` 或 `operator_id = 自己` 的订单(看到自己作为买家或操作者的所有订单) - **钱包流水记录**:钱包扣款时记录交易子类型(自购 / 给下级购买)和关联店铺ID,支持按场景筛选 - **佣金逻辑调整**:代理代购订单不产生佣金(操作者已赚取成本价差),只有平台代购才触发佣金计算 ## Capabilities ### New Capabilities - `agent-order-role-tracking`: 订单角色追踪能力,记录并区分订单中的操作者、买家、支付者等角色关系,支持多种代购场景的数据查询和业务分析 ### Modified Capabilities - `purchase-on-behalf`: 扩展代购订单需求,新增代理使用钱包(wallet)代购的场景,区别于现有的平台线下(offline)代购 - `order-payment`: 新增后台订单钱包一步支付需求,代理创建订单时立即扣款并激活套餐,区别于 H5 端的两步支付流程(创建待支付订单 → 调用支付接口) ## Impact ### 数据库变更 - **订单表**(`tb_order`)新增字段: - `operator_id` (INT, 可空):操作者ID - `operator_type` (VARCHAR, 可空):操作者类型(platform/agent) - `actual_paid_amount` (BIGINT, 可空):实际支付金额(分) - `purchase_role` (VARCHAR):订单角色枚举(self_purchase/purchased_by_parent/purchased_by_platform/purchase_for_subordinate) - 新增索引:`idx_orders_operator_id`、`idx_orders_purchase_role` - **钱包流水表**(`tb_agent_wallet_transaction`)新增/确认字段(如果不存在): - `transaction_subtype` (VARCHAR):交易子类型(细分 order_payment 场景) - `related_shop_id` (INT, 可空):关联店铺ID(代购时记录下级店铺) ### 受影响的模块 - `internal/model/order.go`:新增字段和枚举常量 - `internal/model/agent_wallet.go`:确认流水表字段 - `internal/model/dto/order_dto.go`:OrderResponse 新增字段,OrderListRequest 新增筛选参数 - `internal/service/order/service.go`:重构 `Create()` 方法,新增 `createOrderWithWalletPayment()` 方法 - `internal/store/postgres/order_store.go`:修改 `List()` 支持 OR 查询(buyer_id 或 operator_id) - `internal/handler/admin/order.go`:调整权限检查和查询逻辑 ### API 影响 - **后台订单创建 API**(POST `/api/admin/orders`): - 行为变更:代理使用 wallet 支付时,订单直接完成(payment_status = paid),无需后续支付 - 响应新增字段:`operator_id`, `operator_type`, `actual_paid_amount`, `purchase_role`, `is_purchased_by_parent`, `purchase_remark` - **订单列表 API**(GET `/api/admin/orders`): - 新增查询参数:`purchase_role`(可选,筛选订单角色类型) - 查询逻辑变更:代理可以看到作为操作者或买家的所有订单 ### 兼容性 - **向后兼容**:现有订单字段为空值,不影响已有订单查询 - **平台代购(offline)逻辑不变**:保持现有行为 - **H5 钱包支付不受影响**:H5 端仍使用两步流程(创建待支付订单 → 调用 WalletPay 接口)