Răsfoiți Sursa

036 文档同步组详情juli定位口径并修复距离表段落粘连

api.md 骑手/平台节组详情 juli 由"无定位口径返回空"更新为现行实现:
传入骑手 longitude/latitude(成对可选,只传其一拒绝)时按定位到订单
坐标直线公里计算,与统一列表同口径,不传为空。

接入文档 6.3 成员摘要删去过时的"与旧普通订单详情一致"对比;6.1 距离
字段表修复 jvli 行与待抢组可见性段落粘连(b9e8035c 引入的渲染破损)。
qmj 1 zi în urmă
părinte
comite
53fea0bf6e

+ 1 - 1
specs/036-multi-store-checkout/contracts/api.md

@@ -23,7 +23,7 @@ LINE 创建使用 `{ddId:orderNo}`;OMG 创建使用 `{orderId:orderNo,paymentM
 ## 骑手/平台
 
 - 骑手待抢列表对同骑手配送组只返回一个任务,显示各店及总计;已生效、到预约开放时点才可见。`POST /system/multiStoreCheckout/groups/accept`,JSON `{groupId,version,clientRequestId}`,原子承接全部有效成员;旧单笔接单 API 对组成员拒绝拆抢。骑手仍逐子单取餐/送达。接组须以创建时首店为位置基准,在同一骑手锁内重验资格、位置时效、接单范围、容量与成员状态。首店到其他门店的合并围栏另行校验,不用最近店替代首店。组详情路径为 `GET /groups/{groupId}`,待抢/已接列表和角标使用下节的统一口径。
-- 组详情 `members[]` 逐子单返回 `legacyOrder`、`juli`、`jvli`:`juli` 沿旧普通详情的无定位口径返回空,`jvli` 为建单时服务端道路里程的公里快照,并与 `legacyOrder.jvli` 一致;历史无快照时为空。组卡顶层没有单一门店配送距离。
+- 组详情 `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 无法实际退款时不得手工置为成功。

+ 4 - 2
specs/036-multi-store-checkout/frontend-app-integration.md

@@ -424,7 +424,9 @@ GET /system/multiStoreCheckout/rider/tasks?page=1&size=10&tab=newTask&longitude=
 |---|---|---|---|
 | `juli` | 普通单卡、组卡 `members[]` | 骑手请求定位 → 订单坐标的直线距离(公里,两位小数) | 请求带 `longitude`/`latitude`,不传为 null |
 | `anchorDistanceMeters` | GROUP 卡 | 服务端最近骑手位置 → 首店取餐坐标(米),待抢排序也用它 | 服务端定位上报;待抢资格要求 5 分钟内新鲜 |
-| `jvli` | 组卡 `members[]` | 门店 → 收货地址的配送路线距离(公里,订单快照) | 无需参数,取自 `legacyOrder.jvli`,可能为空 |待抢组只在批次已生效且达到原预约开放时点、组 `openedAt` 已写入后可见;新任务有有效坐标时按首店距离升序,其余按创建时间方向。最后成员就绪并提交后,服务端立即尝试开放即时/已到点批次;若失败,由原分钟任务重试,预约未到也由该任务到点开放。App 不依赖固定一分钟延迟,付款后可刷新列表,未出现时以服务端状态为准;对外 URL 保持不变。
+| `jvli` | 组卡 `members[]` | 门店 → 收货地址的配送路线距离(公里,订单快照) | 无需参数,取自 `legacyOrder.jvli`,可能为空 |
+
+待抢组只在批次已生效且达到原预约开放时点、组 `openedAt` 已写入后可见;新任务有有效坐标时按首店距离升序,其余按创建时间方向。最后成员就绪并提交后,服务端立即尝试开放即时/已到点批次;若失败,由原分钟任务重试,预约未到也由该任务到点开放。App 不依赖固定一分钟延迟,付款后可刷新列表,未出现时以服务端状态为准;对外 URL 保持不变。
 
 ### 6.2 各页签任务数(角标)
 
@@ -455,7 +457,7 @@ GET /system/multiStoreCheckout/groups/{groupId}?longitude=121.5&latitude=25.03
 - `codToCollectAmount`:有效到付子单的待收总额。
 
 成员摘要(含待抢阶段)附带 `legacyOrder`/`store`/`user`/`juli`/`jvli`/`goodsCount`,
-其中 `juli` 与旧普通订单详情一致:此详情接口未传骑手定位时为 `null`;`jvli` 是该店到收货地址的道路距离(公里),与 `legacyOrder.jvli` 一致。组内每店距离不同,组卡顶层不提供单一 `jvli`。历史子单若建单时未保存距离则保持 `null`,不把直线距离伪装成原道路距离。
+其中 `juli` 为骑手定位到该店订单坐标的直线距离(公里,两位小数,口径同 6.1 距离字段表):传入 `longitude`/`latitude` 时计算,不传或订单无坐标时为 `null`;`jvli` 是该店到收货地址的道路距离(公里),与 `legacyOrder.jvli` 一致。组内每店距离不同,组卡顶层不提供单一 `jvli`。历史子单若建单时未保存距离则保持 `null`,不把直线距离伪装成原道路距离。
 其他订单字段与旧骑手列表逐单口径一致,
 可直接复用旧列表项渲染;已接单后逐店履约仍按子单详情读取(见 6.5)。如产品后续要求待抢阶段
 脱敏联系人与地址,须另行变更口径并同步两端。