huang
8ed3d9da93
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m0s
新增功能： - 代理在后台使用 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>
4.3 KiB
4.3 KiB
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, 可空)：操作者IDoperator_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 接口）