huang
66e12e9629
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m57s
42 lines
2.5 KiB
Markdown
42 lines
2.5 KiB
Markdown
## 订单操作者与佣金语义兼容映射清单
|
|
|
|
### 1. 历史字段现状
|
|
|
|
- `tb_order.operator_id`：历史上混用了“真实操作者账号 ID”和“代理店铺 ID”两种语义。
|
|
- `tb_order.operator_type`：历史上仅承载 `platform/agent`，且与 `operator_id` 的 ID 体系并不稳定一致。
|
|
- `tb_order.creator`：后台订单通常可回溯真实账号，但旧响应逻辑没有统一优先使用该字段补齐平台操作者展示。
|
|
- `tb_order.commission_status`：历史上仅有 `1=待计算`、`2=已计算`，无法表达“无佣金”和“链路异常待人工处理”。
|
|
|
|
### 2. 新增权威字段
|
|
|
|
- `operator_account_id`：真实操作者账号/主体 ID。
|
|
- `operator_account_type`：真实操作者类型，使用 `platform/agent/enterprise/personal_customer` 语义。
|
|
- `operator_account_name`：真实操作者名称快照。
|
|
- `commission_result`：佣金业务结果，使用 `0=未知 1=有佣金 2=无佣金 3=链路异常`。
|
|
|
|
### 3. 写路径兼容策略
|
|
|
|
- 新订单统一写入 `operator_account_*` 权威字段。
|
|
- 保留写入 legacy `operator_id/operator_type`，但仅作为兼容读取兜底，不再作为新语义权威来源。
|
|
- `seller_shop_id` 继续作为差价佣金链路起点，不再从 `operator_id/operator_type` 推导佣金归属。
|
|
|
|
### 4. 读路径兼容策略
|
|
|
|
- 响应层优先读取 `operator_account_*`。
|
|
- 若新字段为空：
|
|
- 优先尝试 `creator` 回填后台账号名称。
|
|
- 对客户端个人客户订单，回填个人客户昵称。
|
|
- 对历史代理订单，若 `operator_id/operator_type` 仍承载店铺语义，则回退展示店铺名称，但不回写新字段。
|
|
- `commission_result` 为空时，按历史订单状态与佣金记录兜底推断，不直接篡改旧列值。
|
|
|
|
### 5. 高风险兼容点
|
|
|
|
- `internal/store/postgres/order_store.go` 中旧逻辑把 `operator_id IN subordinateShopIDs` 作为代理权限过滤条件；当 `operator_id` 不再表示店铺 ID 后，该条件必须迁移到 `seller_shop_id`，历史订单仅保留兜底分支。
|
|
- `internal/service/order/service.go` 当前 `operator_name` 仅在 `operator_type=agent` 时按店铺名称回填，会导致平台旧订单长期空白。
|
|
- `internal/service/commission_calculation/service.go` 当前仅把订单写成“已计算”，无法区分“有佣金 / 无佣金 / 链路异常”。
|
|
|
|
### 6. 本次实现范围内的迁移原则
|
|
|
|
- 只做增量字段迁移，不删除旧列。
|
|
- 不在本次 migration 中批量强制回填历史订单，只在运行时兼容读取并为后续人工校验提供依据。
|