foodie-server/specs/036-multi-store-checkout/contracts/api.md

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

以下是 036 后端接口契约，部署前仍须执行已登记迁移并完成 App 联调；路径存在不代表已上线。路径均为 /system/multiStoreCheckout 前缀；用户接口使用 @RequestHeader String token，POST 使用明确 DTO 与 @RequestBody，GET 参数显式声明。App 由前端人员按本文接入，本仓库不修改 App 源码。错误响应使用现有 AjaxResult 及项目 i18n 消息。新用户/骑手接口必须发送 X-Multi-Store-Capability: batch-cards-v1；缺失或未知值返回 errorCode=UPGRADE_REQUIRED。普通单旧接口不要求此头。两端卡片语义见 联合方案。

用户流程

方法与路径	请求关键字段	成功响应	拒绝条件
POST /quote	地址 ID、顺序候选店与商品/规格/数量、同骑手、各店即时/预约时段、逐店备注	quoteToken、有效至、锚点/围栏、参与店及逐店原运费/折后运费/商品价/实付/可选支付方式、圈外店和不兼容原因、规则版本	店/商品/配送资格不合格、支付方式仅转账、报价配置非法；圈外店仅报告不创建
POST /batches	requestKey、quoteToken、参与店 ID 列表、逐店 paymentMethods:[{storeId,payType}]，可选顶层发票字段同普通下单	父批次号、子单号/金额/已选方式及状态/可选方式、两个截止时间；逐店备注已按报价快照固化到子单 remarks，可开票子单保存发票意图；含未付线上子单为 PENDING，全到付为 ACTIVE，但 ACTIVE 不等于已开放	报价过期、成员/地址/价格/规则变化、逐店方式缺漏/重复/夹带非参与店/不可用、电子发票无可开票店或资料校验失败、权限不符；同用户同 requestKey 且付款及发票载荷相同返回原批次，否则拒绝冲突
GET /batches/{batchId}	token + 路径批次 ID	批次/逐店支付选择、真实实收、到付确认、退款与履约状态、截止时间、关联订单	非本人批次拒绝，不暴露其他用户父/子/组
POST /batches/members/payment	body {batchId,orderId,payType,clientRequestId}，payType = 1/2/3/5	新批次的安全改选：到付返回批次状态，线上返回 ONLINE_PENDING；网关创建仍走原接口	批次已生效/过操作截止、该店在途支付已实收或渠道核实未通过、商家不可用、归属不符；6 转账始终不支持。存在在途尝试时服务端先逐笔向渠道核实，确定未付（OMG UNPAID/FAILED、LINE 未捕获）即放行改选
POST /batches/cancel	body {batchId,reason:"USER_CANCEL",clientRequestId}	当前入口只返回是否成功关闭未生效批次的布尔值；退款真实进度待详情接口返回	已 ACTIVE 须走子单取消规则；退款处理中不伪称退款成功
POST /batches/members/cancel	body {batchId,orderId,reason:"USER_CANCEL",clientRequestId}	当前入口只返回是否成功取消该子单；退款真实进度待详情接口返回，其他成员费用快照不变	未生效不允许单店取消；骑手已接/取餐拒绝用户取消；并发接组只能一方成功

每店报价另外区分 discountedFreight（骑手毛运费）、merchantDeliverySubsidy（商家免运承担）、customerDeliveryFee（客户运费）及 amount（优惠后商品金额＋客户运费）。商家满额免运以多店折后运费为基数：原运费40、八折后32、全免时客户运费0、商家补贴32、骑手仍收32。到付给商家金额为 amount - discountedFreight；普通单的免运口径不改。

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

036 子单调用原 LINE/OMG 创建入口、OMG 重试入口同样须携带上述能力头，旧版 App 不能通过原网关入口绕过逐店收银。原 LINE/OMG 网关查询、异步回调、补单继续按原交易事实核实，不以客户端能力头作为可信付款事实。 LINE 创建使用 {ddId:orderNo}；OMG 创建使用 {orderId:orderNo,paymentMethod:"CREDIT"} 对应 payType=2，或 paymentMethod:"APPLE_PAY" 对应 payType=5。POST /batches/members/payment 只选付款方式，不替代上述网关创建，也不返回跳转凭证。

骑手/平台

• 骑手待抢列表对同骑手配送组只返回一个任务，显示各店及总计；已生效、到预约开放时点才可见。POST /system/multiStoreCheckout/groups/accept，JSON {groupId,version,clientRequestId}，原子承接全部有效成员；旧单笔接单 API 对组成员拒绝拆抢。骑手仍逐子单取餐/送达。接组须以创建时首店为位置基准，在同一骑手锁内重验资格、位置时效、接单范围、容量与成员状态。首店到其他门店的合并围栏另行校验，不用最近店替代首店。组详情路径为 GET /groups/{groupId}，待抢/已接列表和角标使用下节的统一口径。
• 组详情 members[] 逐子单返回 legacyOrder、juli、jvli：juli 在传入骑手 longitude/latitude（成对可选，只传其一拒绝）时按定位到订单坐标的直线公里距离计算，与统一列表同口径，不传为空；jvli 为建单时服务端道路里程的公里快照，并与 legacyOrder.jvli 一致；历史无快照时为空。组卡顶层没有单一门店配送距离。
• 商家已接未取但实际无法供餐：POST /merchant/members/cancelUnavailable，body {batchId,orderId,reason:"MERCHANT_UNAVAILABLE",clientRequestId}。仅授权门店、已接组中尚未被骑手取餐的本子单可取消；本店实收登记原路退款意图，其他店不补差；最后一个有效子单取消时结清组和父单。
• 平台配置 GET/PUT /system/multiStoreCheckout/config：开关、围栏米、最多店数、缓冲分钟、可增删改折扣阶梯；保存会校验并更新规则版本，仅影响新报价。平台退款跟进列表显示各商家渠道、实收、退款意图/结果/待人工处理，不提供“手工标记渠道已退款”。
• 平台退款跟进只读接口 GET /system/multiStoreCheckout/admin/refunds?page=1&size=20&status=ALL，可按 PENDING/PROCESSING/UNKNOWN/FAILED/MANUAL_REVIEW/REFUNDED 过滤；需要现有 system:order:list 权限，按退款意图逐笔分页，返回 batchId/memberId/orderId/storeId/channel/amount/merchantOrderNo/intentStatus/gatewayStatus/effectiveStatus。仅 REFUNDED 表示原渠道已证实退款；测试 OMG 无法实际退款时不得手工置为成功。
• 平台 GET /system/order/list 仍以子单为行；当前页 036 真成员附加 multiStore={orderId,batchId,groupId,parentOrderNo,checkoutStatus,groupStatus,paymentState}，普通单为 null，不改变原分页数量。平台 GET /system/multiStoreCheckout/admin/batches/{batchId} 使用 system:order:list 权限，返回只读批次和逐店进度，不暴露 App 的 allowedActions；既有 App /batches/{batchId} 仍严格检查用户归属。平台普通状态修改入口对 036 成员直接拒绝，非 036 订单沿原流程。
• 平台配置只读写独立 order_checkout_config，不占用 sys_config。GET 返回 enabled/fenceMeters/maxStores/confirmationBufferMinutes/version/tiers，其中 tiers 为门槛数字键到系数的对象；PUT 将 tiers 作为 {minimumStores,ratio} 数组传入，并回传新版本。缺表或缺行时读取保守关闭，保存拒绝并提示先执行 036 迁移；客户端旧 version 不能覆盖新配置。
• 新任务通知出站与预约旧时点扫描按持久记录幂等重试；组只推一个待抢任务，独立成员各推一个。用户付款通知与订单取餐/送达通知继续独立，不在未全额就绪时发骑手/商家履约新单。
• 036 组新任务推送额外带 groupId、eventId；前端用 groupId 打开组详情，并按 eventId 去重重试推送。后端 SENT 是已提交到项目现有异步推送通道，不等于设备已送达。

时间和兼容示例

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 降低最大门店数时，存在超限未结束未承接组则保存失败、原配置和版本不变；提示先处理存量组。已接组不受影响；失败不暗中取消订单或改变费用。

组合列表、角标和详情的实施目标（2026-10-19）

本节定义前端接入契约，尚未上线。新用户端调用 GET /user/cards?page=1&size=10&tab=all，同一外卖订单列表返回普通单与 036 批次卡；新骑手端调用 GET /rider/tasks?page=1&size=10&tab=newTask&longitude=...&latitude=...，返回普通外卖任务与同骑手配送组卡。骑手角标调用 GET /rider/taskCount?longitude=...&latitude=...；用户各主阶段数量如页面需要，由 GET /user/cardCount 同口径返回。两端均使用 token 确认身份，参数显式声明，不接受传入用户/骑手 ID。GET /batches/{batchId} 与 GET /groups/{groupId} 为组合详情；普通单点击仍走现有详情。退款/售后是补充筛选，可以与一个主流程页签交叉，不改变唯一主阶段。骑手列表/角标方法已归原骑手控制器，对外 URL 与响应不变；待抢组须实际开放并写入 openedAt 才可见，不能仅凭 ACTIVE 判断。

统一列表响应沿现有骑手列表习惯使用 data.records、data.total、data.current、data.size；page 从 1 起，size 限定为正数并设置服务端上限。total 是过滤后的卡片数，不是子单数。先按归属、Tab、开放/资格和组合关系得到卡片集合，再排序、分页，最后批量填充本页成员摘要；不能先分页 pos_order 再在 App 拼组。相同排序键以 cardKey 稳定打破平局；新任务有有效骑手坐标时按首店距离升序，其余按现有普通外卖 Tab 的创建时间方向。角标与列表共享同一过滤和组去重规则，刷新/并发变化以服务端最新结果为准。

字段	用户批次卡 cardType=BATCH	骑手组卡 cardType=GROUP	普通单 cardType=ORDER
身份	cardKey=BATCH:{batchId}、batchId、parentOrderNo	cardKey=GROUP:{groupId}、groupId、batchId、version	cardKey=ORDER:{orderId}、原订单 ID/单号
主阶段	checkoutStatus（PENDING/ACTIVE/CANCELLED）、primaryTab、refundSummary	primaryTab、组承接/结束状态、原预约窗口及开放时间	沿原普通订单主阶段，不套用批次状态
进度	memberCount、readyCount、pickedUpCount、deliveredCount、cancelledCount、activeCount	memberCount、activeCount、pickedUpCount、deliveredCount、cancelledCount	旧字段不变；组合计数可为空
金额	快照 totalAmount、onlinePaidAmount、codPromisedAmount、refundPendingAmount、refundedAmount，单位 TWD	discountedFreightTotal（配送毛收入）、codToCollectAmount、逐店到付给商家额，单位 TWD	原字段不改
时间/距离	createdAt、operationDeadlineAt、finalDeadlineAt、activatedAt	createdAt、openedAt、anchorDistanceMeters，接单按首店判断	旧字段不改
明细/操作	members[] 逐店付款与履约状态、allowedActions	members[] 逐店出餐/取送状态、allowedActions，待抢时联系人脱敏	原单笔操作入口

members[] 至少包含 orderId/orderNo/storeId/storeName/payType/paymentState/orderAmount/discountedFreight/deliveryStatus/cancelStatus/refundStatus，其中到付子单另有 codToCollectAmount 和 codToMerchantAmount。只读展示字段由服务端从真实成员计算，客户端不根据某个子单 payStatus 推断批次状态、不在本地重算费用、进度或可操作性。接单前组卡不透出超出原单笔待抢范围的用户联系信息；取消成员仍在详情保留历史，但从有效进度和现金待收中剔除。activeCount 为当前有效成员数，取消后可下降；memberCount 是创建时总数，不下降。已送达成员计入已取餐数，已取消成员不计入分母；混合进度按当前有效成员统计，另外显示 cancelledCount 防误解。全组结束前不能仅因某子单售后状态释放容量。 已生效待接组的用户批次卡 allowedActions 可包含 CANCEL_MEMBER；已接组中骑手逐店摘要按真实 orderState/deliveryStatus 返回 PICKUP_MEMBER 或 DELIVER_MEMBER，最终操作入口仍重新校验状态与骑手身份。

当前只读接口为 GET /user/cards、GET /user/cardCount、GET /batches/{batchId}、GET /rider/tasks、GET /rider/taskCount、GET /groups/{groupId}。组合卡 records 为先聚合后分页；普通 ORDER 卡附带 legacyOrder 原订单快照供旧内容展示。退款进度从 036 意图关联原 LINE/OMG 退款记录：BRIDGED 只是已桥接，不代表已到账；只有渠道事实 REFUNDED 才计入 refundedAmount，未知/失败/人工处理仍计入待处理。骑手待抢组仅用服务端最近位置判断首店范围；接组再次在骑手锁内复核。

旧用户 /system/order/getorderlist 与旧骑手单笔列表/角标均不展示 036 子单，不能先对子单分页再让旧 App 拼组。旧 /system/userOrder/getParentOrderDetail 对真实 036 父单返回 UPGRADE_REQUIRED，新 App 应调用带归属校验的 GET /batches/{batchId}；普通父单仍走原接口。

用户主 Tab：all/pending/active/completed/cancelled；有退款或售后记录时另支持 refund 筛选，同一卡可同时在 active 和 refund 查询中出现，但在 all 仅出现一次。骑手沿原外卖 newTask/toPickup/delivering/completed/cancelled/refund 参数：未取完的有效子单存在时始终为 toPickup，即使另一子单已送达；有效子单均已取且仍有待送/待处置时为 delivering；全部有效成员结束后进入历史。待抢组按 ACTIVE、实际开放 openedAt、原预约时点和资格过滤，且只计一张卡。业务状态、可操作性和角标由服务端返回，不以 App 页签推导权限。

用户已确认旧版 App 须升级后才能使用多店：发布前确认两端最低兼容版本和强制更新入口，配置开关在两端准备就绪前保持关闭。旧版不能发起新批次、继续逐店收银或承接组；已有批次/已接组遇旧版须引导升级，旧单笔支付/取消/接单接口仍对新批次或组成员实施服务端保护。普通单、历史单、单店转账、自取及夜市自配送继续沿旧接口和原规则；普通平台配送预约只补既有时点开放扫描，不套 036 截止。升级策略只是兼容门禁，不替代 token、订单归属、支付事实、版本和骑手锁校验。

错误至少区分 UPGRADE_REQUIRED、QUOTE_CHANGED、PAYMENT_WINDOW_CLOSED、PAYMENT_PENDING_CONFIRMATION、BATCH_CANCELLED、GROUP_CHANGED、RIDER_OUT_OF_RANGE、RIDER_CAPACITY_FULL、ORDER_ALREADY_ACCEPTED、FORBIDDEN，并以项目 i18n 消息返回；实施者可在既有错误结构中承载稳定业务码。列表过滤后的接组接口必须重新校验并返回明确原因，不能信任卡片上次可见的状态。