From 94954aa8a56d7604621938656f67f72f2269cbcc Mon Sep 17 00:00:00 2001 From: yml2213 Date: Thu, 8 Oct 2026 14:54:25 +0800 Subject: [PATCH] =?UTF-8?q?docs(=E6=8A=96=E9=9F=B3-=E7=A0=81=E9=80=9F?= =?UTF-8?q?=E8=BE=BE):=20=E6=9C=80=E5=B0=8F=E6=8E=A5=E5=85=A5=E5=BE=85?= =?UTF-8?q?=E7=A1=AE=E8=AE=A4=E9=97=AE=E9=A2=98=E6=B8=85=E5=8D=95=EF=BC=88?= =?UTF-8?q?=E5=8F=AF=E7=9B=B4=E6=8E=A5=E8=BD=AC=E5=8F=91=E7=9A=84=E9=97=AE?= =?UTF-8?q?=E8=AF=A2=20+=20=E7=AD=94=E5=A4=8D=E8=B7=9F=E8=B8=AA=E8=A1=A8?= =?UTF-8?q?=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 06-待确认问题清单.md（273 行），把最小接入开工前必须问清的问题按 「平台方 / 业务方 / 内部技术」拆好，每条都写明为什么问、卡住什么、什么算回答。 - 给平台方 8 组（约 40 条子问题），4 组标阻塞： Q1 order.message 可用性（测试接口仅支持特定商户，message_type=2 是否会改 抖店发货状态、content 是否支持 URL）； Q2 coupons.syncV2 订单号粒度（子单 s_id？多子单能否分别同步？重复同步语义？ 同步成功后买家在哪儿看到卡券 —— 看不到则第③步直接断）； Q3 券码/链接格式（cert_no 字符集与长度、cert_link 是否支持带 # 的 hash 路由、 是否必须 HTTPS、255 上限、grant_time 格式）； Q4 verifyV3 核销语义（前置条件、是否不可逆、重复核销、是否触发结算，以及文档里 verifyV3 的抖店路径写成 verifyV2 的疑点）； 另有 Q5 cancelVerify 约束、Q6 推送可靠性、Q7 post_tel/buyer_words 取值 （决定能否做手机号后4位二次校验）、Q8 账号环境与计费频控。 - 给业务方 8 条，3 条标阻塞：B1 能否接受「知道订单号即可兑换」的枚举风险 （不接受就要牺牲只输订单号的体验）、B2 兑换后给买家发什么、B3 核销时机。 - 内部技术 6 条待拍板：域名路径、幂等键、履约通道（人工兜底但仍须加商品解析 分支）、券码格式、配置存放、买家信息留存边界。 - 附「可直接转发给平台方的一段话」（IM 复制即用）与 16 行答复跟踪表。 同步更新 README 索引。 --- docs/抖音-码速达/06-待确认问题清单.md | 273 ++++++++++++++++++++++++++ docs/抖音-码速达/README.md | 1 + 2 files changed, 274 insertions(+) create mode 100644 docs/抖音-码速达/06-待确认问题清单.md diff --git a/docs/抖音-码速达/06-待确认问题清单.md b/docs/抖音-码速达/06-待确认问题清单.md new file mode 100644 index 00000000..72cc605d --- /dev/null +++ b/docs/抖音-码速达/06-待确认问题清单.md @@ -0,0 +1,273 @@ +# 抖音码速达 · 接入待确认问题清单 + +> 用途：把「最小接入」开工前必须问清楚的问题**按对象拆好**，可直接复制给对方；每条都标注了「为什么问 / 卡住什么 / 什么算回答了」。 +> 上下文：[05-最小接入方案分析.md](05-最小接入方案分析.md)（最小闭环：收单 → 发券 → 固定链接兑换 → 核销 + 发链接）。 +> 整理日期：2026-10-08 ｜ 分支：`dev` + +--- + +## 0. 一页速览 + +| 对象 | 条目 | 其中 ★阻塞 | 核心阻塞点 | +| --- | --- | --- | --- | +| 平台方（码速达） | 8 组、约 40 条子问题 | 4 组（Q1~Q4） | ①`order.message` 能不能用 ②券码/链接格式限制 ③买家侧在哪看到卡券 ④核销语义 | +| 业务方 / 产品 | 8 条 | 3 条（B1~B3） | ①能否接受「订单号可枚举」风险 ②核销时机 ③兑换后发什么 | +| 内部技术（我们自己拍） | 6 条 | 0 | 域名/路径、幂等键、履约由谁做 | + +**开工前必须拿到答案的 3 个**： +1. `order.message` 我们的商户号能不能用（Q1）—— 不能用就要换 `topup.result.url`。 +2. `cert_link` 是否支持带 `#` 的 hash 路由、长度上限（Q3-4）—— 直接决定固定兑换链接长什么样。 +3. 业务能否接受「知道订单号即可兑换」（B1）—— 决定要不要加二次校验、兑换页交互形态。 + +--- + +## 1. 给平台方（码速达） + +### Q1 ★阻塞 · 消息发送接口能不能用 + +**问题**：文档里 `order.message`（订单消息测试）标注「测试接口，仅支持特定商户」。我们的商户号（uid）**能否使用**？如果不能，是否有正式的消息下发接口（把链接/文案推给买家）？ + +**为什么问**：最小方案第④步「核销后给买家发去使用链接」完全依赖它。 + +**还要问清楚**： +- `message_type` 各值语义：`1-订单状态`、`2-订单发货`、`4-图片`、`5-视频`；**发 `2` 会不会把抖店订单置为「已发货」**（我们不想意外改变订单状态）？ +- `content` 是否支持 URL、支持换行吗、长度上限多少？ +- 调用频率限制？单订单能否重复发送（我们不想骚扰买家）？ +- 返回里没有业务数据（只有 `code/message`），**如何确认消息真的送达买家**？ + +**算回答**：明确「可用/不可用 + message_type 推荐值 + 频控 + 能否重复发」；若不可用，给出替代通道。 + +--- + +### Q2 ★阻塞 · `coupons.syncV2` 的订单号粒度 + +**问题**：`syncV2` 的 `order_id` 文档写「子订单ID」——确认是**子订单号（`s_ids` 里的值）**而不是父订单号（`p_id`）吗？ + +**为什么问**：`trade_TradePaid` 消息只给 `p_id` 和 `s_ids`，我们要决定按哪个粒度落库和发券。 + +**还要问清楚**： +- 一个父订单有**多个子订单**时：能不能分别同步（每个子单一张券）？还是必须一次把整个父单的券在一个 `cert_list` 里发？ +- `cert_list` 单次最大条数？ +- 同一个 `order_id` **重复同步**会覆盖、报错、还是追加？（决定我们的重试策略） +- 同步成功后**买家在哪里看到这张卡券**（抖店订单详情 / 抖店「卡券」入口 / 短信 / 站内消息）？进入路径是什么？ + ⚠️ 这个如果买家找不到卡券，整个最小方案的第③步就断了。 +- 券的**有效期**由谁定（我们发券时给 `grant_time`，有效期是平台默认还是可配）？ + +**算回答**：明确粒度 + 重复同步语义 + 买家查看路径（最好给一张截图或路径说明）。 + +--- + +### Q3 ★阻塞 · 券码与链接的格式约束 + +**问题**：`cert_no` 和 `cert_link` 有什么硬性限制？ + +**具体要问**： +1. `cert_no`：长度上下限？字符集（**能不能带字母**？我们计划用 `DYC` + Crockford Base32 十六位，共 19 位）？是否必须全局唯一？是否要求纯数字？ +2. `cert_link`： + - 长度上限确认是 **255** 吗？ + - 必须 HTTPS 吗？ + - **是否支持带 `#` 的 hash 路由**（例如 `https://order.khhao.com/#/redeem`）？还是必须用 path 形式（`https://order.khhao.com/redeem`）？—— 这条直接决定我们的固定链接写法。 + - 是否支持带 query 参数（以后可能要带订单号后 6 位做防伪）？ + - 链接是**给买家点击跳转**，还是仅做展示？ +3. `grant_time`：格式（`YYYY-MM-DD HH:MM:SS`？）、必填还是可空、时区是否按北京时间？ +4. `coupons.list` 返回里的 `cert_id` / `out_cert_id` 是什么？我们同步时只给 `cert_no`，会不会导致这两个值缺失、影响买家侧展示？ + +**算回答**：给出字段约束表；`cert_link` 最好能让你们**实测一条我们的示例链接**（我们提供，你贴到平台确认能跳转）。 + +--- + +### Q4 ★阻塞 · `coupons.verifyV3` 的核销语义 + +**问题**：核销上报后的行为与限制。 + +**具体要问**： +- `cert_no` 必须是**我们通过 syncV2 同步过**的券吗？没同步过直接核销会怎样？ +- 核销**是否不可逆**（只能靠 `cancelVerify` 冲正）？ +- 有无**核销时效**（发券后 N 天内必须核销？超时会怎样）？ +- **重复核销**返回什么（幂等成功 / 报错）？ +- 核销后买家侧/平台侧会发生什么：券状态变化？订单状态变化？**是否触发我们的结算/分账**？ +- ⚠️ 文档里 `coupons.verifyV3` 的「抖店原始路径」写的是 `/coupons/verifyV2`（与 method 不一致），确认一下是文档笔误还是真有两个版本？ + +**算回答**：核销的前置条件 + 幂等语义 + 副作用（尤其是否影响结算）。 + +--- + +### Q5 · `coupons.cancelVerify` 与异常兜底 + +**问题**： +- `cancel_verify_count`（取消核销总次数）是否必填？语义是「总共可取消几次」还是「本次取消的是第几次」？ +- `batch_no` 幂等号的规则（谁生成、多久内有效、重复提交的行为）？ +- 核销后**多久内**可以取消？次数上限？ +- 如果我们的券发错了（比如商品对不上），除了 `cancelVerify` 还有别的处理方式吗（作废/换券）？ + +**算回答**：取消核销的完整约束。 + +--- + +### Q6 · 消息推送的可靠性约定 + +**问题**： +- 推送**失败重试策略**：重试几次、间隔多久、单次超时多少秒、要求我们返回什么（HTTP 200？特定 body？） +- 我们处理失败（比如拉订单详情失败）时应该返回什么？**返回 4xx/5xx 会不会触发重推**？（我们倾向于「未处理成功就返回失败，让平台重推」） +- `trade_TradePaid` 到达时，**`order.orderDetail` 能立刻查到完整商品明细吗**？会不会有时间差（我们怕查到空明细）？ +- 推送有没有**顺序保证**？（例如 `trade_TradePaid` 与 `refund_RefundSuccess` 的先后） +- 一个 uid 绑定多个店铺时，消息里的 `shop_id` 如何区分？我们要不要为每个店铺单独配置？ + +**算回答**：给一份「推送可靠性说明」（重试/超时/应答规范/时序保证）。 + +--- + +### Q7 · 数据与隐私 + +**问题**： +- `order.orderDetail` 的 `post_tel` / `post_receiver` 在**虚拟商品、卡券类订单**里**是否有值**？（决定我们能不能做「订单号 + 手机号后 4 位」的二次校验） +- `buyer_words`（买家留言）在充值/卡券类订单里，是否就是**买家要充值的账号**？这是我们发货的关键输入。 +- `doudian_open_id` 是加密串，我们只做内部留存、不对外展示，是否符合平台要求？ +- 有没有关于**买家信息留存时长**的合规要求？ + +**算回答**：明确 `post_tel` / `buyer_words` 在目标品类下的实际取值。 + +--- + +### Q8 · 账户、环境与计费 + +**问题**： +- `uid`（抖店商户号）与「用户秘钥」的分配流程？**一个 uid 能否绑定多个抖店店铺**？ +- 有没有**测试环境 / 沙箱店铺**？`order.message` 能否在沙箱里给我们发测试消息？ +- 密钥**轮换**流程（多密钥并存？切换窗口？） +- 各接口的金豆消耗确认：`order.orderDetail` 高级（2 金豆）、`coupons.syncV2` 基础（1）、`coupons.verifyV3` 高级（2）、`order.message` 高级（2）—— 与文档一致吗？有没有**包量/折扣**？ +- 有没有**调用频控**（QPS / 日限额）？超限返回什么错误码？ +- 消息推送配置（`message.config`）是我们自己调接口设置，还是你们后台代配？`message_url` 是否要求备案域名/HTTPS？ + +**算回答**：账号与环境开通清单 + 计费与频控书面确认。 + +--- + +## 2. 给业务方 / 产品 + +### B1 ★阻塞 · 能否接受「知道订单号即可兑换」 + +**背景**：新的固定兑换链接不带 token，用户输入订单号即可进入兑换流程。这意味着**任何人只要拿到别人的订单号，就能兑换别人的商品**。订单号会出现在买家聊天记录、订单截图、客服工单里。 + +**问**： +- 能否接受这个风险（我们会做限流 + 状态校验 + 一次性核销 + 异常告警）？ +- 如果不能接受，是否接受**加一道校验**（订单号 + 手机号后 4 位 / 下单日期），代价是用户要多填一个字段？ + +**影响**：决定兑换页是「1 个输入框」还是「2 个输入框」，以及要不要先确认平台侧能提供手机号。 + +--- + +### B2 ★阻塞 · 兑换成功后给买家发什么 + +**问**： +- 兑换成功后，买家应该看到什么：卡密（我们自己发的码）？第三方链接（充值页/网盘）？还是只提示「已为您充值成功」？ +- 第④步的通知走哪条路：`order.message`（测试接口）还是 `topup.result` 的 `url` 字段（正式）？ +- 通知文案谁来定？ + +**影响**：决定第④步的实现方式，以及兑换结果页的设计。 + +--- + +### B3 ★阻塞 · 核销时机 + +**问**：用户在我们页面点「兑换」的瞬间就上报核销，还是等**实际履约完成**（人工发货/自动发货成功）后再上报？ + +**背景**：核销上报后平台侧显示「已核销」。如果这时我们还没真正发货，买家会拿「已核销」来投诉；反过来说，如果等人工确认，买家在页面上会看到「处理中」。 + +**建议**：人工兜底场景下，等确认发货后核销（页面上显示「处理中，请稍后查看」）。 + +**影响**：决定兑换页第 3 屏是「立即出结果」还是「处理中 + 轮询」。 + +--- + +### B4 · 兑换背后的履约由谁做 + +**问**：兑换之后，商品由谁交付？ +- 打手接单（走现有接单平台 + 接单模板）？ +- 客服人工处理（后台任务列表）？ +- 自动（调用第三方接口）？ + +**影响**：决定最小版是不是「人工兜底」就够，以及要不要接通 `product-resolution-service` 的商品匹配分支。 + +--- + +### B5 · 退款/取消后怎么处理 + +**问**：订单退款或取消后： +- 券码作废 + 兑换页拒绝，是否足够？ +- 需要主动通知客服/联系买家吗？ +- 如果买家**已经兑换**了才退款，怎么处理（追缴？作废？不处理？）？ + +**影响**：决定最小版要不要做「已兑换后退款」的处置流程。 + +--- + +### B6 · 最小版先上哪些商品 + +**问**：先拿哪几个商品/店铺跑通？一件商品发**一张券**（整单核销）还是按 `item_num` **按件发券**？ + +**建议**：最小版先「一单一张券」，避免券数与兑换次数对不上。 + +--- + +### B7 · 老的 token 领取链接怎么办 + +**问**：现有 `/claim/:token` 的领取链接（91 卡券链路）继续保留，还是也要切到新的固定兑换链接？两套并存期间的客服口径是什么？ + +--- + +### B8 · 兑换页的文案与品牌 + +**问**：页面标题、logo、客服入口（微信/电话）、异常提示文案谁来定？是否需要与抖店店铺风格一致？ + +--- + +## 3. 内部技术待拍板 + +| # | 问题 | 建议 | +| --- | --- | --- | +| T1 | 兑换页地址与形态 | `https:///#/redeem`，前端新增 `/redeem` 路由，与 `/collect` 同级；若平台不支持 hash 链接，改为 `https:///redeem`（Caddy 侧加 rewrite） | +| T2 | 幂等键 | 消息：`topic:pub_time:p_id:s_id`（body 哈希兜底）；券：`order_id + cert_no` 唯一 | +| T3 | 履约通道 | 最小版直接用 `manual_dispatch`（人工兜底），**但仍必须**在 `product-resolution-service.ts:165/346` 加 `douyin_mashida` 分支，否则订单 `isConfigured=false` 不会建任务 | +| T4 | 券码格式 | `DYC` + Crockford Base32 16 位（照抄 `kuaishou-industry-voucher-repo.ts:49-52`），等平台方 Q3 确认后定稿 | +| T5 | 配置存放 | 走 `app_config_entries`（后台可改 + 脱敏），不走 env（可绕开 `env-documentation.test.ts:57/63` 的白名单约束） | +| T6 | 买家信息留存 | `post_tel` / `buyer_words` / `doudian_open_id` **只进 `orders` 与原始报文**，不进 `work_orders.material_json`、不下发打手（沿用现有隐私红线） | + +--- + +## 4. 可直接转发给平台方的一段话 + +> 你好，我们准备接入贵平台，先做一个最小闭环：接收 `trade_TradePaid` 消息 → 调 `order.orderDetail` 获取商品信息 → 生成我们自己的券码（前缀 DYC）→ 调 `coupons.syncV2` 同步给贵平台 → 买家在我们固定兑换页输入订单号兑换 → 调 `coupons.verifyV3` 上报核销。 +> +> 开工前想确认几件事： +> 1. `order.message`（订单消息测试）我们的商户号能否使用？`message_type=2`（订单发货消息）会不会改变抖店订单的发货状态？content 是否支持 URL、长度上限多少？ +> 2. `coupons.syncV2` 的 `order_id` 是子订单号还是父订单号？多子订单能否分别同步？重复同步是覆盖还是报错？同步成功后买家在**哪里**能看到这张券（抖店订单详情？卡券入口？）？ +> 3. `cert_no` 的格式限制（长度/字符集，能否用 DYC + 16 位 Base32 字母数字）？`cert_link` 是否支持带 `#` 的 hash 路由、是否必须 HTTPS、长度上限是否 255？ +> 4. `coupons.verifyV3` 核销是否不可逆？重复核销返回什么？核销是否会触发结算？另外文档里 verifyV3 对应的抖店路径写的是 `/coupons/verifyV2`，请确认。 +> 5. 消息推送的失败重试策略、超时时间、对我们应答的要求；`trade_TradePaid` 到达时 `order.orderDetail` 能否立即查到完整商品明细？ +> 6. 我们的 uid 能否绑定多个店铺？有没有测试环境？各接口的计费与频控能否书面确认？ +> +> 另外麻烦确认：`order.orderDetail` 的 `post_tel`、`buyer_words` 在虚拟商品/卡券类订单里是否有值（我们要判断能否用手机号后 4 位做二次校验）。 + +--- + +## 5. 答复跟踪表（拿到答案后回填） + +| # | 问题 | 优先级 | 状态 | 答案 / 结论 | 影响的实现 | +| --- | --- | --- | --- | --- | --- | +| Q1 | `order.message` 可用性 | ★阻塞 | 待问 | | 第④步发链接方式 | +| Q2 | `syncV2` 订单号粒度 | ★阻塞 | 待问 | | 落库粒度、发券数量 | +| Q3 | 券码 / 链接格式 | ★阻塞 | 待问 | | 固定链接写法、券码生成 | +| Q4 | `verifyV3` 核销语义 | ★阻塞 | 待问 | | 核销时机与幂等 | +| Q5 | `cancelVerify` 约束 | 一般 | 待问 | | 异常兜底 | +| Q6 | 推送可靠性 | 重要 | 待问 | | 应答与重试策略 | +| Q7 | `post_tel`/`buyer_words` 取值 | 重要 | 待问 | | 二次校验可行性 | +| Q8 | 账号/环境/计费 | 重要 | 待问 | | 联调准备 | +| B1 | 订单号可枚举风险 | ★阻塞 | 待定 | | 兑换页交互 | +| B2 | 兑换后发什么 | ★阻塞 | 待定 | | 第④步与结果页 | +| B3 | 核销时机 | ★阻塞 | 待定 | | 结果页形态 | +| B4 | 履约由谁做 | 重要 | 待定 | | 是否接打手 | +| B5 | 退款处置 | 重要 | 待定 | | 作废流程 | +| B6 | 先上哪些商品 | 重要 | 待定 | | 联调范围 | +| B7 | 老链接是否保留 | 一般 | 待定 | | 并存期策略 | +| B8 | 页面文案品牌 | 一般 | 待定 | | 前端设计 | diff --git a/docs/抖音-码速达/README.md b/docs/抖音-码速达/README.md index 2e0898de..23aa776c 100644 --- a/docs/抖音-码速达/README.md +++ b/docs/抖音-码速达/README.md @@ -31,6 +31,7 @@ | [03-消息推送规范与签名.md](03-消息推送规范与签名.md) | 推送参数、data 提交方式、签名与验签、消息设置、示例代码 | | [04-结合本项目的深度分析.md](04-结合本项目的深度分析.md) | **接入本仓库（order_site）的深度分析**：能力映射、差距清单、待拍板决策、分期实施、风险与合规红线 | | [05-最小接入方案分析.md](05-最小接入方案分析.md) | **最小接入（跑通优先）方案**：只做 收单→发券→固定链接兑换→核销发链接，含固定兑换链接的安全性分析 | +| [06-待确认问题清单.md](06-待确认问题清单.md) | 开工前要问清的问题：按「平台方 / 业务方 / 内部技术」拆好，含可直接转发的话术与答复跟踪表 | | `接口API/` | 16 个接口逐条文档（请求参数、返回参数与示例、签名原串示例） | | `消息推送/` | 14 条消息逐条文档（topic、data 字段、示例 JSON、签名原串示例） | | `data/raw_data.json` | 页面内嵌原始数据（api / message / fee / menu 四块，完整未删减） |