# 多店结算接口契约（实施版）

路径均为 `/system/multiStoreCheckout` 前缀；用户接口使用 `@RequestHeader String token`，POST 使用明确 DTO 与 `@RequestBody`，GET 参数显式声明。App 仅据此接入，不修改 App 源码。错误响应使用现有 `AjaxResult` 及项目 i18n 消息，不返回硬编码单语言字符串。用户端批次卡与骑手端组任务卡、参考闪送的单工作页签/取送双进度及服务端分页建议见 [两端联合方案](../frontend-display-plan.md)，展示细节尚待确认；下方旧拟议 POST 路径若包含业务 ID，实施前须按用户已确认的“有 body 则业务参数统一放 body”要求收口。

## 用户流程

| 方法与路径 | 请求关键字段 | 成功响应 | 拒绝条件 |
|---|---|---|---|
| `POST /quote` | 地址 ID、顺序候选店与商品/规格/数量、同骑手、各店即时/预约时段 | `quoteToken`、有效至、锚点/围栏、参与店及逐店原运费/折后运费/商品价/实付/可选支付方式、圈外店和不兼容原因、规则版本 | 店/商品/配送资格不合格、支付方式仅转账、报价配置非法；圈外店仅报告不创建 |
| `POST /batches` | `requestKey`、`quoteToken`、用户明确确认的参与店 ID 列表 | 父批次号、子单号/金额/可选方式、`operationDeadlineAt`、`finalDeadlineAt`、`PENDING` | 报价过期、成员/地址/价格/规则变化、夹带圈外店、少于 2 店、权限不符；同用户同 requestKey 返回同批或拒绝载荷冲突 |
| `GET /batches/{batchId}` | token + 路径批次 ID | 批次/逐店支付选择、真实实收、到付确认、退款与履约状态、截止时间、关联订单 | 非本人批次拒绝，不暴露其他用户父/子/组 |
| `POST /batches/{batchId}/members/{orderId}/payment` | `payType` = 1/2/3/5 | 到付确认结果或线上支付凭证/跳转信息与原尝试号 | 截止后新发起、未决尝试换方式、商家不可用、金额/归属不符；6 转账始终不支持 |
| `POST /batches/{batchId}/cancel` | 可选原因 | 批次 `CANCELLED` 及每店退款真实进度 | 已 `ACTIVE` 须走子单取消规则；退款处理中不伪称退款成功 |
| `POST /batches/{batchId}/members/{orderId}/cancel` | 原因 | 该子单取消和真实退款进度、其他成员保持快照 | 未生效不允许单店取消；骑手已接/取餐拒绝用户取消；并发接组只能一方成功 |

回调/补单仍使用现有 LINE/OMG 入口，服务端以原订单/尝试号识别新批次成员：先验签与核实实收、落支付事实，再在事务内聚合批次；不得直接发履约新单通知。到付只表示用户确认按现有流程交餐付款，不伪称线上实收。用户列表应展示未选方式、部分付款、缓冲核实、待批次生效、退款中并提供继续结算入口；普通旧单字段语义不变。

## 骑手/平台

- 骑手待抢列表对同骑手配送组只返回一个任务，显示各店及总计；已生效、到预约开放时点才可见。`POST /system/multiStoreCheckout/groups/accept`，JSON `{groupId,version}`，原子承接全部有效成员；旧单笔接单 API 对组成员拒绝拆抢。骑手仍逐子单取餐/送达。组详情与待抢/已接列表、角标的响应字段待联合展示方案确认后补齐，不把现有逐单列表当作已经支持组合卡。
- 平台配置 `GET/PUT /system/multiStoreCheckout/config`：开关、围栏米、最多店数、缓冲分钟、可增删改折扣阶梯；保存会校验并更新规则版本，仅影响新报价。平台退款跟进列表显示各商家渠道、实收、退款意图/结果/待人工处理，不提供“手工标记渠道已退款”。
- 平台配置只读写独立 `order_checkout_config`，不占用 `sys_config`。GET 返回 `enabled/fenceMeters/maxStores/confirmationBufferMinutes/version/tiers`，其中 `tiers` 为门槛数字键到系数的对象；PUT 将 `tiers` 作为 `{minimumStores,ratio}` 数组传入，并回传新版本。缺表或缺行时读取保守关闭，保存拒绝并提示先执行 036 迁移；客户端旧 `version` 不能覆盖新配置。
- 新任务通知出站与预约旧时点扫描按持久记录幂等重试；组只推一个待抢任务，独立成员各推一个。用户付款通知与订单取餐/送达通知继续独立，不在未全额就绪时发骑手/商家履约新单。

## 时间和兼容示例

14:00 创建：14:15 前可发起线上/确认到付；14:14 已实际发起的线上尝试可在 14:20 前完成付款及可信确认；14:16 不可新发起或改到付；14:20 仍未全部就绪则关闭，迟到实收只退款不激活。截止在创建时快照，不因配置变更或重试延长。

普通单仍调用现有 `/createOrder`、LINE/OMG/到付入口并保持原校验与状态；新接口不得仅凭客户端传入的批次号放宽原入口。预约订单不重定义旧时间语义；2026-10-16 已确认新多店接入 037 现有无人接单规则，按父批次统一生效时间及实际开放时点判断，不以逐子单支付时间开始。

## 2026-10-16 已确认的边界补充（尚待实现）

- 批次详情返回 `activatedAt`，组详情返回 `openedAt`，并由服务端给出真实阶段/允许操作；App 不从付款时间推导无人接单倒计时。按现有阈值自动取消未承接组时，整组从待抢消失，详情保留逐店取消及退款进度，迟到实收不重开。
- 未生效预约在激活时已到或超过结束则取消，返回原预约已过期的业务结果及真实退款进度，不返回可抢状态、不自动改即时；已生效任务不由此检查取消。
- 建批后收货地址/坐标固定，地址簿变化不修改订单；首版无多店改址。用户要换地址按现有整批/子单取消权限处理后重新报价，不能只修改某店或绕过已接单禁取消。
- 配置 PUT 降低最大门店数时，存在超限未结束未承接组则保存失败、原配置和版本不变；提示先处理存量组。已接组不受影响；失败不暗中取消订单或改变费用。