docs(douyin-mashida): 记录商品展示口径(内部 SKU 为主)

新增 §4.10:说明 code=内部 SKU / product_name=引流标题的区别,
以及三个界面(后台列表、后台详情、兑换中心)统一以内部 SKU 为主的展示规则,
并注明实现只对 douyin_mashida 生效、不影响其它平台。
This commit is contained in:
yml2213
2026-10-09 13:31:51 +08:00
parent 7834ee7bef
commit d12dce7575
@@ -151,7 +151,23 @@ applyRawBigIntegerOverrides(parsed, rawText) // p_id / order_id / s_id / s_ids
不是文档示例里的 `77977`;`sku_order_list[].order_id` 是**字符串**,本例与父单号相同。
联调时以真实响应为准。
### 4.10 平台真实推送的形态(实测抓到的原文)
### 4.10 商品展示口径:**内部 SKU 才是商品**
平台 `sku_order_list[].code` 是商家维护的**内部 SKU**(如「幸运币2个」),
`product_name` 是店铺里用来**引流**的长标题(如「【测试专用】和平精英皮肤小店入口…」)。
商家按内部 SKU 认货(后续履约匹配也用它),所以三个界面统一以**内部 SKU 为主**:
| 界面 | 展示 |
| --- | --- |
| 后台订单列表「商品 / 任务」 | 内部 SKU(主) + 引流标题(副,蓝色 tag) |
| 后台订单详情「商品明细」 | 商品 = 内部 SKU;SKU/规格 = 引流标题 |
| 兑换中心 `/redeem` | 商品 = 内部 SKU(粗体) + 引流标题(灰色小字) |
实现落在两个共享解析器(`admin-read-shared-helpers.ts` 的 `resolveOrderItemTitle` /
`resolveOrderItemSkuNick`)和 `redeem-service.ts:buildSummary`,
**只对 `source === 'douyin_mashida'` 生效**,其它平台展示逻辑不变。
### 4.11 平台真实推送的形态(实测抓到的原文)
订阅配好后,一笔真实付款的推送**约 6 秒**到达,来源 IP 是平台服务器(`118.31.56.230`),
body 原文(注意 `p_id`/`s_ids` 是**裸数字**、`pay_time` 是**秒级**):
@@ -165,13 +181,13 @@ body 原文(注意 `p_id`/`s_ids` 是**裸数字**、`pay_time` 是**秒级**
- `p_id` 是 19 位裸数字 → 正好验证了 §4.1 的精度修复(落库/回执全程精确);
- 端到端耗时:付款 12:55:05 → 推送 12:55:11 → 建单+发券+`syncV2` 完成 12:55:12。
### 4.11 平台推送是**订阅制**(不配就永远收不到)
### 4.12 平台推送是**订阅制**(不配就永远收不到)
填好 `uid`/`secret` 只代表我们能调平台,平台**不会**自动推消息过来:
必须调「消息设置」`message.config` 配置 `message_url` + `topics` + `status=1`。
而且**不补推**订阅之前的历史订单。详见 [08-公网联调.md](08-公网联调.md) §2。
### 4.12 退款/取消消息文档没列字段
### 4.13 退款/取消消息文档没列字段
`refund_*`、`trade_TradeCanceled`、`trade_TradeSuccess` 这几条文档里 `props` 是空的(很可能只是文档缺失)。
代码按「有 `p_id` 就作废券、没有就留痕等人工」处理 —— **不抛错**,避免平台无意义重推。