Kiro IDE/CLI/Crew：AI编程智能体三叉戟闭环实践
2026/10/23 9:43:53
核销服务由无限聚核提供，美团、抖音团购核销一站式接入。
搜「美团验券接口」，前排经常是官方「券码验证」文档片段，或教程里一步打完「验券」的半截示例。开发真正卡的是：准备和执行哪一步改券状态？服务零售和到店餐饮是不是同一套？跳过准备会发生什么？
一句话回答：美团团购验券固定两段——先验券准备，再执行验券。准备只读，不改券状态、不发权益；真正扣券在执行步，且必须原样回传准备拿到的不透明凭证。自研走美团开放平台准备／验券接口族；接第三方用统一「预核销 → 核销」，platform=1表示美团。餐饮文档里的msprepare／msconsume是另一路由，勿与服务零售混抄。依据公开平台说明与无限聚核公开 API／FAQ，查阅日期 2026-10-21，以当期文档为准。
- 准备 ≠ 核销：准备成功只能进确认页；
- 执行才写状态：凭证（如
ticketInfo）整段原文回传； - 餐饮／服务零售分开：
msprepare／msconsume不是服务零售通用名； - 成功认明确字段：聚合侧认顶层
success=true； - 失败分三类：可原样重试、明确拒绝停手、已核销转核对。
一、先认准你要接的「验券」
| 说法 | 属于谁 | 下一步 | 作用 |
|---|---|---|---|
| 输码验券校验／验券准备 | 美团服务零售 | 执行验券 | 查可用券，换凭证 |
| 执行验券 | 同上 | 可选撤销 | 真正核销 |
msprepare→msconsume | 美团到店餐饮 | 餐饮撤销另路径 | 仅餐饮路由 |
| 聚合预核销 → 核销 | 第三方统一接口 | 传撤销凭证 | platform区分美团／抖音 |
口语「验一下券」可能指准备也可能指执行；代码里必须拆成两步 RPC。抖音是certificate.prepare→verify，与美团餐饮msconsume不是一条链路——本文只咬合美团验券接口。
二、最小闭环：准备 → 确认 → 执行
验券准备（预核销）
传门店标识 + 券码（聚合另加platform=1）。拿到展示信息与不透明凭证。不改券状态，不发权益。顾客确认
用准备返回的名称、售价、张数做确认页，再执行。执行验券
回传同一组门店、平台、券码、数量 + 凭证原文。成功后再落本地订单与权益。（可选）撤销
用执行成功保存的撤销凭证，在平台时限内撤销（美团侧常见约 10 分钟，以当期说明为准）。撤销 ≠ 消费者退款。
聚合语义名（Host 以公开文档为准）：
- 准备：
ddzh-tuangou-receipt-prepare→ 存ticketInfo - 执行：
ddzh-tuangou-receipt-consume→ 认success=true，存wxdgOrderNo、data[]、consumeCredential[] - 撤销：
ddzh-tuangou-receipt-cancel→ 传consumeCredential
shopId必须是聚合具体门店ID，不是商户 ID、不是你系统门店主键、不是经营宝门店码。
三、ticketInfo 当黑盒
| 要 | 不要 |
|---|---|
| 服务端整段保存 | 解析后删字段再序列化 |
| 核销原样回传 | 用凭证猜商品／门店 ID |
| 成功后再发权益 | 准备成功就写「已核销」 |
商品可先用展示名＋售价与本地配置预匹配；以核销成功返回明细为准。匹配不到唯一商品先完善配置。
四、成功／失败／重试：别跳步补枪
成功（聚合）：只认success=true；保存首次完整响应与撤销凭证下标对应关系，再发权益。
失败三类：
| 类别 | 举例 | 动作 |
|---|---|---|
| 可重试 | CONSUME_IN_PROGRESS、RESULT_UNKNOWN、SERVICE_UNAVAILABLE、PROVIDER_UNAVAILABLE，或超时无响应 | 原请求有限重试 |
| 明确拒绝 | PLATFORM_REJECTED等 | 停重试，展示原因 |
| 已核销提示 | ALREADY_CONSUMED（常见code=10500） | 停重试，用原单号核对；不补发、不编造凭证 |
重试禁止：重新准备、换参数、让顾客重输码。
五、自研 vs 聚合（只谈验券主链路）
| 维度 | 自研开放平台 | 第三方聚合 |
|---|---|---|
| 前置 | 资质＋商家 token | 建店＋店主授权 |
| 准备／执行 | 平台准备／验券族 | 统一预核销／核销，platform=1 |
| 幂等 | 按平台文档 | 接口防重复核；业务仍按券码＋本地单去重 |
| 餐饮 | 改走msprepare／msconsume等 | 建店选对业态 |
需要 Java HttpClient 示意时看「美团核销 Java」专文；本文不复读长示例，只讲跳步风险与字段纪律。
六、联调自检
- 业态路径未混用；
- 准备成功文案是「待确认」不是「已核销」；
- 凭证整段落库，执行五元组一致；
- 成功字段与撤销凭证都落库；
- 未知态禁止引导重输码；
- 已核销类走核对；
- 撤销与退款流程分开。
常见问题
美团验券接口是一步还是两步？
两步：先准备，再执行。跳过准备或把准备当已核销，是最常见错误。
预核销和验券准备是一回事吗？
开发语境里常把准备口语叫预核销。财务软件的「预核销」是另一概念，勿做技术主标题。
msprepare／msconsume 能当通用名吗？
不能，它们属于到店餐饮。服务零售用当期服务零售接口族；聚合用统一接口 +platform=1。
执行超时怎么办？
保留原请求，仅白名单错误码或无响应时原样有限重试；不要重新准备、不要重输码；仍不确定查券状态或对账。