huang
66e12e9629
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m57s
4.5 KiB
4.5 KiB
Why
功能 ID：feature-001-order-operator-and-chain-commission-semantics。
当前订单链路把 operator_id 混用了“真实操作者账号”和“代理店铺 ID”两种语义，导致平台下单场景无法准确追溯是谁操作，订单详情中的 operator_name 也会在平台场景下长期为空。与此同时，commission_status 又被混用了“佣金计算流程状态”和“佣金业务结果”，使“未触发计算”“已计算但无佣金”“链路断裂待人工处理”三种完全不同的业务含义被压扁成同一个字段，已经影响后台判断、补偿逻辑和后续规则演进。
现在必须把这两个核心概念拆开：订单必须准确记录真实操作者；差价佣金必须按 seller_shop_id 的完整上级链逐级计算，“无佣金”必须成为明确结果而不是继续停留在“待计算”。
What Changes
- 修正订单操作者语义：订单中的操作者字段统一表示“真实发起操作的账号”，不再复用为代理店铺 ID；平台、代理、后续其他账号类型都必须能被准确记录和展示。
- 修正订单响应与查询语义：订单详情/列表中的操作者名称按账号语义回填，店铺归属与买家归属继续由独立业务字段表达，避免“账号名”和“店铺名”混淆。
- 修正差价佣金计算规则：所有会参与差价佣金的订单都从
seller_shop_id出发，沿完整父级链逐级计算，不再使用“一级/二级代理特判”口径，也不再从operator_id/operator_type推导佣金归属。 - 修正平台代扣、代理自购、代理为下级代购等场景的触发规则：只要订单属于差价佣金适用范围，系统都必须在支付成功或自动完单后触发佣金计算；是否有佣金由链路和价差决定，而不是由操作者类型决定。
- 拆分佣金流程状态与业务结果：BREAKING 订单佣金状态语义将从“二元待计算/已计算”调整为“流程状态 + 结果语义”模型，至少区分“待计算/已完成/待人工处理”以及“有佣金/无佣金/链路异常”。
- 修正链路异常处理：当上级链断裂、配置缺失或无法继续向上分配时，系统必须明确落为“待人工处理/链路异常”，而不是和普通“已完成”混淆。
- 补充兼容迁移与手工验证方案：历史订单中
operator_id为 NULL 或保存店铺 ID 的数据需要有兼容解释和回填方案；核心验证覆盖多级代理链、无佣金订单、链路断裂订单和补偿入队场景。 - 增补文档与 OpenAPI：更新订单管理、代购订单、佣金计算、佣金触发等规范，确保前后端、运营和补偿流程都以新语义为准。
Capabilities
New Capabilities
- 无
Modified Capabilities
agent-order-role-tracking: 将订单操作者从“店铺视角”修正为“真实账号视角”，并调整订单响应中的操作者展示规则。order-management: 调整订单查询与响应中的操作者信息和佣金状态语义，明确订单字段各自承担的业务角色。purchase-on-behalf: 修正平台代扣、代理自购、代理为下级代购等场景的差价佣金规则，统一为基于seller_shop_id的链路型计算。commission-calculation: 将差价佣金定义为沿完整上级链逐级分配，并明确“无佣金”“链路异常待人工处理”等业务结果。commission-trigger: 修正佣金任务触发条件与补偿口径，确保所有适用订单都能进入计算流程，且“无佣金”不再被误判为“待计算”。
Impact
- 受影响代码：
internal/model/order.go、internal/model/dto/order_dto.go、internal/service/order/service.go、internal/service/commission_calculation/service.go、internal/store/postgres/order_store.go、internal/task/commission_calculation.go、pkg/constants/*。 - 受影响接口：后台订单创建、订单列表、订单详情，以及所有依赖订单佣金状态和操作者展示的管理端页面。
- 受影响系统：Asynq 佣金任务触发/补偿链路、钱包入账链路、运营人工排障流程、OpenAPI 文档与前端展示逻辑。
- 数据影响：可能需要为历史订单增加兼容解释或回填脚本；需要手工验证多级代理链路、0 佣金订单、链路断裂订单和平台代扣订单的状态落点。
- 性能与测试：链路计算必须继续满足逐级查询可控、列表查询分页、核心场景手工回放可验证；本变更会补充针对多级链路和补偿场景的验证清单。