huang
66e12e9629
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m57s
79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
## 订单操作者与产业链佣金语义修复功能总结
|
||
|
||
### 1. 变更目标
|
||
|
||
本次变更围绕两个历史语义问题展开：
|
||
|
||
1. 订单 `operator_id/operator_type` 混用了“真实操作者账号”和“代理店铺 ID”，导致平台订单无法稳定显示真实操作者。
|
||
2. 订单 `commission_status` 只区分“待计算/已计算”，无法表达“有佣金 / 无佣金 / 链路异常待人工处理”的真实业务结果。
|
||
|
||
### 2. 已完成的核心改动
|
||
|
||
#### 2.1 订单操作者改为账号语义
|
||
|
||
- 新增权威字段：
|
||
- `operator_account_id`
|
||
- `operator_account_type`
|
||
- `operator_account_name`
|
||
- 后台订单创建、H5 代理订单创建、客户端个人客户订单、自动购包订单都会写入真实操作者快照。
|
||
- 旧 `operator_id/operator_type` 保留为历史兼容字段，不再作为新语义权威来源。
|
||
|
||
#### 2.2 订单响应分离“操作者账号”和“业务店铺”
|
||
|
||
- `operator_id/operator_type/operator_name` 现在按真实操作者账号语义返回。
|
||
- 新增 `seller_shop_id/seller_shop_name`，用于表达业务归属店铺展示。
|
||
- 历史订单优先使用新字段；若缺失，则按 `creator`、个人客户昵称、旧店铺型 `operator_id` 顺序兜底，避免平台旧订单出现空白操作者名称。
|
||
|
||
#### 2.3 订单佣金状态拆成“流程状态 + 业务结果”
|
||
|
||
- `commission_status` 现在表示流程状态：
|
||
- `1=待计算`
|
||
- `2=已完成`
|
||
- `3=待人工处理`
|
||
- 新增 `commission_result` 表示业务结果：
|
||
- `0=未知`
|
||
- `1=有佣金`
|
||
- `2=无佣金`
|
||
- `3=链路异常`
|
||
|
||
#### 2.4 差价佣金任务结果显式落单
|
||
|
||
- 佣金 worker 结束后会显式写回订单：
|
||
- `已完成 + 有佣金`
|
||
- `已完成 + 无佣金`
|
||
- `待人工处理 + 链路异常`
|
||
- 0 佣金订单不再长期停留在“待计算”。
|
||
|
||
#### 2.5 入队与幂等语义修复
|
||
|
||
- 钱包支付创建订单后，所有仍处于 `待计算` 的适用订单都会入队佣金任务，不再只覆盖特定购买角色。
|
||
- 重复支付回调、重复钱包支付不会重复入队。
|
||
- worker 对 `已完成/待人工处理` 订单直接跳过，避免重复补偿处理。
|
||
|
||
### 3. 兼容策略
|
||
|
||
- migration 仅新增字段，不删除旧列。
|
||
- 历史订单读取时：
|
||
- 优先使用 `operator_account_*`
|
||
- 其次使用 `creator` 回填账号名
|
||
- 对旧代理订单保留店铺名兜底展示
|
||
- 历史订单的 `commission_result` 若未回填，则在响应层按佣金记录只读推断。
|
||
|
||
### 4. 受影响文件
|
||
|
||
- `internal/model/order.go`
|
||
- `internal/model/dto/order_dto.go`
|
||
- `internal/service/order/service.go`
|
||
- `internal/service/client_order/service.go`
|
||
- `internal/service/commission_calculation/service.go`
|
||
- `internal/store/postgres/order_store.go`
|
||
- `internal/task/auto_purchase.go`
|
||
- `pkg/constants/iot.go`
|
||
- `migrations/000140_add_order_operator_snapshot_and_commission_result.*.sql`
|
||
|
||
### 5. 风险提示
|
||
|
||
- 历史订单若 `creator` 无法映射到账号，仍会退回旧店铺型操作者展示，仅保证“可读”而不强行伪造账号 ID。
|
||
- `commission_result=0` 仅作为历史兼容态存在；新计算链路应尽量落为明确业务结果。
|
||
- 本次不重构一次性佣金规则本身，只保证其异常待审记录能纳入订单最终流程结果判断。
|