抖音团购核销落地执行清单

决策口径与目标

总体排期与关键路径

责任分工（角色占位）

说明：「负责」为该项主要责任人；「配合」为提供输入或承接落地动作。客户端 / 前端为新增列，承接手机端摄像头识码与扫码页开发（复用 APP 已有扫码组件）。所有 占位角色 请在启动会上确认到具体人员，建议本项产品牵头、商务/后端双线执行，每周至少一次对齐会（与 RTB 例会合并）。

产品经理交付物：PRD 与原型设计

交付节奏与依赖

功能需求条目（PRD 需覆盖）

条目编号用于挂接后端交付项（P0/P1/P2）与 测试用例清单；范围以 决策口径 的 MVP 为准，次卡是否纳入取决于试点门店是否售卖次卡商品。

A · 核销主流程（店员端 APP）— P0

• 摄像头识码复用与体验（对应 R-01 / R-02，复用 APP 已有扫码组件）
  复用现有扫码组件：识别抖音券码短链文本，不做重复的识码 SDK 集成。识码页提供手电筒 / 补光开关（弱光、暗屏场景）；识别失败给「调亮屏幕 / 避开反光 / 摘除手机膜」引导文案并可重扫；识别成功提供震动 + 提示音反馈便于连续快速操作（逐张核销，扫一张即进验券流程）。若复用组件已具备补光 / 提示音能力则直接随组件覆盖，不重复开发。
• 手动输码兜底（无 PC / 扫码枪时的备用入口）
  当顾客券码在他人手机、屏幕过暗或多次识别失败时，可切「手动输入券码」完成同样流程；输码页校验格式并提示可复制粘贴长链。

B · 撤销核销与异常边界 — P0

C · 门店授权与映射（运营后台 / 店长端）— P1

D · 团购对账（运营后台）— P1

E · 信息同步回调（退款自动冲销）— 必接

F · 次卡支持（视试点门店售卖情况，与后端确认）— P2

G · 小程序侧联动（剑琅美遇 · 后续迭代，本期仅落库契约）— 后续

原型页面清单（由产品经理产出）

横切状态模板：空态 / 断网 / 超时 / 无权限 四类通用提示页建议统一设计，覆盖全部页面。

PRD 评审与验收要求

• 可追踪性
  PRD 条目带编号（R-xx），挂接后端交付项（P0/P1/P2）与 测试用例清单（Phase 5），任一改动可追溯到人 / 需求 / 用例。
• 必备覆盖
  重复核销幂等、异常与边界、退款回调冲销、撤销 1 小时时限、跨门店权限，缺一不可入审。
• 埋点建议
  核销入口打开率、验券结果分布、核销成功率、失败原因占比、撤销率，作为上线复盘与后续优化依据。另加「摄像头识码成功率 / 识别失败重扫率」：手机扫手机屏是本期关键体验点，用该指标评估贴膜 / 亮度 / 反光等场景是否影响核销效率，作为是否需补充硬件（蓝牙扫码枪）或强化引导的判断依据。
• 评审节奏
  主链路原型 v0.5 先内部评审 → 携试点店长确认 → 冻结后再进 P0 开发（第 2 周）；P1/P2 需求随开发批次滚动评审，避免阻塞排期。
• 版本与变更
  PRD 记录版本与变更日志；平台规则变化（撤销时限、接口字段、费率）同步修订并通知后端 / 测试。

① 服务商平台入驻与资质认证

1. 注册服务商平台账号
   访问抖音开放平台服务商平台（partner.open-douyin.com）注册账号；同时可先在开发者平台入驻指引确认材料要求。注册邮箱/手机建议使用公司公共账号，避免离职交接问题。
2. 认证「生活服务商家应用代开发」能力
   登录服务商平台 → 控制台 → 「第三方生活服务商家应用」页面 → 认证「生活服务商家应用代开发」能力。在「认证服务能力-基础信息」页签填基础信息 → 下一步 → 「认证服务能力-经营信息」页签填经营信息并上传应用工具介绍 → 提交审核。
3. 等待能力认证审核（约 10 个工作日）
   平台审核反馈通过站内通知；建议提交后即通过平台右下角「开发者助手 → 生活服务问答」留言确认进度，必要时请对接 BD 协助加速。审核期间后端同步开始开发，不空等。
4. 完成对公认证（审核通过后立即）
   在「认证服务能力-对公认证」页签选择任一方式：法定代表人/经营者支付宝人脸识别（实时完成，推荐）或 平台打款验证（0-2 小时，48 小时内输入打款金额，仅 2 次机会）。也可选银行账户实名 / 客户打款 / 申请授权验证。若人脸与打款均不便，预先安排好法人配合窗口。
5. 签署合作协议并确认可创建应用
   对公认证完成后，控制台出现「创建三方应用」入口即代表入驻完成。验收标准：可在「第三方应用」区域点击创建第三方生活服务商家应用。

② 创建应用与申请解决方案

1. 创建「第三方生活服务商家应用」
   控制台 → 「第三方应用」→ 「创建三方应用」→ 选择「第三方生活服务商家应用」 → 填写应用名称、上传应用图标，勾选《生活服务技术服务商合作协议》→ 提交。等待审核（约 1 个工作日）。
   凭证说明：创建成功后 APPID = ClientKey，AppSecret = ClientSecret。AppSecret 由服务端保管，严禁下发到 APP 端或写入前端代码。
2. 申请「到综行业解决方案」权限
   进入目标应用详情 → 左侧「解决方案」→ 找到「到综解决方案」（覆盖休闲娱乐、丽人、运动健身等，剑琅美业门店属此类）→ 点击「申请开通」，建议「按能力开通」，勾选本期需要的能力：门店映射及匹配、团购核销、团购对账；其余（三方码、预置码、会员接入等）暂不开通。等待审核（约 3 个工作日）。
3. 验证接口凭据可用
   解决方案开通后，调用 POST https://open.douyin.com/oauth/client_token/（grant_type=client_credential）获取 access_token。client_token 有效期约 2 小时，需缓存并按期刷新。所有接口请求头需携带 access-token，POST 接口另需 content-type: application/json，域名统一 https://open.douyin.com，路径以 / 结尾。
4. 内部验收
   后端凭据获取成功、能列出目标解决方案已开通能力；如调用报「无权限/未获得该能力」，通过「开发者助手-生活服务问答」或对接 BD 核查权限状态。

③ 试点门店授权与绑定

授权方式一：抖音来客手动授权（首批推荐，零开发）

1. 门店侧发起授权
   门店运营/店长登录抖音来客 PC 端 → 左侧「店铺管理」→ 「服务方应用授权」→ 「服务商代理」页签 → 点击「新增授权」→ 搜索选择「剑琅联盟」应用、选择授权行业（到综）与授权范围 → 提交。
2. 服务商侧确认授权
   剑琅登录服务商平台控制台 → 进入目标生活服务商家应用 → 左侧「授权管理」→ 查询并确认该抖音来客商户的授权关系。确认后即可为门店调通接口。
3. 门店信息绑定
   通过「门店映射及匹配」能力获取/核对门店 poi_id；在剑琅后台建立「抖音门店 → 剑琅门店」映射，配置该门店允许的核销范围与默认业绩归属员工规则。

授权方式二：SaaS 收银系统内嵌授权（后续版本升级）

官方推荐方案：商家在剑琅联盟系统内即可完成授权，无需登录抖音来客。到综解决方案支持此方式，接入「能力授权 & 门店绑定 SDK」即可。体验好但需要额外开发量，与赶排期相悖，故本期不开发，作为 M2 上线后体验升级项排入迭代。落地时：门店在剑琅后台一键发起授权 → 跳转完成抖音授权 → 自动回调绑定 → 剑琅免登录服务商平台操作。

④ 开发与联调（客户端扫码 + 后端接口）

关键实现要点（开发必读）

• 抖音券码必须先「验券准备」再「验券」
  验券准备与验券调用需一一对应；验券成功后原二维码失效。二维码扫出的是短链（如 https://v.douyin.com/xxxx，长度不固定、不要截断），需先 GET 转发为长链再解析券信息。
• 纯手机端摄像头识码（无 PC / 扫码枪）
  店员用 APP 手机摄像头扫顾客手机屏幕上的抖音券二维码。复用 APP 已有扫码组件，端上只负责把二维码识别成短链文本并上送，不在端上解析券信息（短链转长链、券信息解析统一在后端适配层完成）。关注扫手机屏体验：补光开关（暗屏）、失败引导（调亮 / 避开反光 / 摘除手机膜）、识别成功震动 + 提示音反馈；逐张核销，扫一张即进验券流程，不引入连续扫码。需在试点前用真实手机屏幕验证识码成功率（亮度 / 贴膜 / 曲面屏场景）。
• 验券结果要区分「业务失败」与「技术异常」
  官方要求对 result 字段做业务匹配：result 非 0 是业务提示（如券已使用、金额不符），不是技术异常，需按业务提示处理并提示店员；技术异常（网络/5xx）走重试。
• 幂等设计
  验券接口用 verify_token 做短时幂等；撤销核销支持按次幂等（cancel_token，有效期 1 小时）。核销前先查券状态做预校验，避免本地与平台状态不一致。
• 撤销核销有 1 小时限制
  平台仅允许核销后 1 小时内撤销。产品上建议店员确认核销做二次确认弹窗，减少误操作；超时撤销只能走人工/平台客服流程。
• 信息同步回调验签
  抖音调用剑琅服务端接口时请求头带 x-life-clientkey、x-life-sign；验签规则：以 client_secret 开头，URL 参数按 key 字典序 + http_body（POST）串联，sha256 后比对。http_body 用原始 []byte 参与签名，勿反序列化后重序列化（会导致字段顺序变化验签失败）。
• 次卡字段
  验券准备返回 time_card（总次数/已使用次数）；一次核销多份在 encrypted_codes 中传多个相同加密码；撤销按次数传 times_card_cancel_count。注意：分门店结算场景不要传按次撤销相关字段。
• 密钥与安全
  ClientSecret / 密钥存服务端（环境变量或密钥管理），接口统一 HTTPS；日志脱敏，不落明文券码全量信息。

联调与错峰安排（与 RTB 批次并行预案）

⑤ 测试、验收与试点上线

测试方案（二选一或并用）

测试用例覆盖清单

平台验收与上线要求（官方必检项）

• result 业务匹配
  验券 result 非 0 必须有对应业务处理，不可当纯异常。
• 重试机制
  抖音侧接口失败需有重试，针对服务抖动一般重试即可解决。
• 预校验
  核销前预查券状态，避免双方订单状态不一致。
• 信息同步接口必接
  避免平台强制退款而剑琅无感知。
• 上线检查
  灰度 1 家试点真券 → 全链路核对（核销记录/开单/对账）→ 扩至 3-5 家 → 平台侧确认应用可用状态。灰度前须在试点门店用店员真实手机完成摄像头识码验证（覆盖不同手机品牌 / 贴膜 / 亮度场景，确认不依赖 PC / 扫码枪）。

⑥ 门店培训、运营支持与对账

抖音核销接口速查

开发时以官方接口文档为准，接口路径一律 HTTPS 且以 / 结尾。更多接口（券状态查询、批量查询、门店映射及匹配、团购对账）见下方附录链接。

风险与应对

官方文档附录