更新闪送 App 接口接入文档

补充我发的与我收的角色权限、收件账号绑定规则。
明确急送 Redis 骑手独占、无支付金额及发布等待口径。

docs/flash-delivery-app-api.md

@@ -2,13 +2,15 @@
 
 本文档供用户端 App 和骑手端 App 接入闪送功能使用，以当前后端实现为准。文档只描述接口契约和业务流程，不包含 App 前端实现代码。
 
+> 更新时间：2026-09-04。当前口径已包含“我发的/我收的”、创建时收件账号绑定、急送跨外卖与闪送独占；闪送仍不接入支付。
+
 ## 1. 功能范围
 
 当前闪送支持：
 
 - 帮送、帮取、加急送三种服务。
 - 共享地址簿、路线报价、立即配送和预约配送。
-- 用户发布订单、查询订单、取消订单和确认收货。
+- 用户发布订单，并按“我发的/我收的”查询订单；发件人可取消，发件人或创建时绑定的收件人可确认收货。
 - 骑手查看待抢订单、抢单、确认取件和确认送达。
 - 可选的四位交付 PIN。
 - 寄件、取件和送达图片凭证。
@@ -167,15 +169,15 @@ App 必须以响应体 `code` 判断业务是否成功，不能只依赖 HTTP
 ```text
 WAITING_ACCEPTANCE -> ACCEPTED -> PICKED_UP -> DELIVERED -> COMPLETED
           |               |
-          +---- 用户可取消 +---- 用户可取消
+          +--- 发件人可取消 +--- 发件人可取消
 ```
 
 | 值 | 含义 | 下一步 |
 |---|---|---|
-| `WAITING_ACCEPTANCE` | 待骑手接单 | 骑手抢单，或用户取消 |
-| `ACCEPTED` | 骑手已接单 | 骑手确认取件，或用户取消 |
+| `WAITING_ACCEPTANCE` | 待骑手接单 | 骑手抢单，或发件人取消 |
+| `ACCEPTED` | 骑手已接单 | 骑手确认取件，或发件人取消 |
 | `PICKED_UP` | 骑手已取件 | 骑手确认送达 |
-| `DELIVERED` | 骑手已送达 | 用户确认收货；超过 24 小时可由系统自动完成 |
+| `DELIVERED` | 骑手已送达 | 发件人或创建时绑定的收件人确认收货；超过 24 小时可由系统自动完成 |
 | `COMPLETED` | 已完成 | 终态 |
 | `CANCELLED` | 已取消 | 终态 |
 
@@ -187,8 +189,8 @@ WAITING_ACCEPTANCE -> ACCEPTED -> PICKED_UP -> DELIVERED -> COMPLETED
 2. 从共享地址簿选择地址，或填写取件和收件信息。
 3. 调用报价接口，展示服务端返回的路线和费用。
 4. 用户确认后调用创建订单接口。创建时服务端会重新计算路线和金额，最终以创建响应为准。
-5. 通过订单列表或详情刷新状态。当前闪送模块没有 App 实时推送接口。
-6. 在 `WAITING_ACCEPTANCE` 或 `ACCEPTED` 状态可取消；在 `DELIVERED` 状态可确认收货。
+5. 使用 `role=sender` 查看“我发的”，使用 `role=receiver` 查看“我收的”，并通过列表或详情刷新状态。当前闪送模块没有 App 实时推送接口。
+6. 仅发件人可在 `WAITING_ACCEPTANCE` 或 `ACCEPTED` 状态取消；发件人和创建时绑定的收件人都可在 `DELIVERED` 状态确认收货。
 
 ### 4.2 骑手端
 
@@ -355,7 +357,7 @@ App 完整详情使用以下订单字段，响应的 `data` 直接返回这些
 
 - `senderImageUrls`、`pickupImageUrls` 和 `deliveryImageUrls` 分别表示寄件、取件和送达图片数组。
 - App 详情不返回原始状态日志；页面使用 `status`、`acceptedAt`、`pickedUpAt`、`deliveredAt`、`completedAt` 和 `cancelledAt` 展示进度。
-- `deliveryPinCode` 只向订单所属用户返回，并且只在启用 PIN 时出现；骑手响应永不返回此字段。
+- `deliveryPinCode` 只向订单发件人和创建时绑定的收件人返回，并且只在启用 PIN 时出现；骑手响应永不返回此字段。
 - `rider` 只向用户返回。订单未接单时为 `null`。骑手对象不包含真实电话号码，联系入口使用 `imUserId` 打开 IM 会话，原型中的通话按钮没有接口支撑。
 - 骑手位置只在订单状态为 `ACCEPTED` 或 `PICKED_UP` 时向用户返回，其他状态下经纬度为 `null`。
 
@@ -518,6 +520,8 @@ GET /system/flashDelivery/orders?page=1&size=10&role=sender
 
 仅查询当前用户作为指定角色的订单，按创建时间倒序返回全部状态的订单摘要。接口不接受 `status`、`scene` 或 `serviceType`；响应 `data.records` 中每项为用户列表摘要对象。
 
+`role` 只接受 `sender` 或 `receiver`，不区分大小写；传空值按 `sender` 处理，传其他值返回业务错误。“我收的”完全依据订单创建时固化的收件账号，不会在查询时重新按手机号匹配。
+
 设计原型中的“待接单、配送中、已完成、已取消”筛选页签当前没有对应查询参数。第一版建议只展示“全部”列表；如需页签，只能基于当前页数据本地过滤，且不应依赖它得到准确的分页总数。
 
 ### 7.5 查询用户订单详情
@@ -560,7 +564,9 @@ POST /system/flashDelivery/orders/{id}/confirmReceipt
 
 所有接口均要求骑手登录 `token`，且账号 `userType` 必须为 `2`。
 
-接单使用共享 Redis 锁 `lock:delivery:rider:{riderId}` 串行执行跨外卖、闪送的资格检查和订单条件更新，并在事务完成后释放。`URGENT` 急送要求骑手没有任何进行中的外卖或闪送；骑手已有进行中的急送时，也不能再接普通闪送或外卖。Redis 不可用或 3 秒内未取得锁时，本次接单直接失败。
+接单使用共享 Redis 锁 `lock:delivery:rider:{riderId}` 串行执行跨外卖、闪送的资格检查和订单条件更新，并在事务完成后释放。该锁只覆盖接单事务，不会一直持有到配送完成；持续独占由每次接新单时查询骑手进行中的订单保证，Redis 锁用于防止两个并发接单请求同时绕过查询。
+
+`URGENT` 急送要求骑手没有任何进行中的外卖或闪送；骑手已有进行中的急送时，也不能再接普通闪送或外卖。普通闪送不会阻止骑手承接外卖，外卖也不会阻止骑手承接普通闪送。Redis 不可用或 3 秒内未取得锁时采用失败关闭策略，本次接单直接失败，不更新订单。
 
 ### 8.1 查询骑手订单列表
 
@@ -592,7 +598,7 @@ GET /system/flashDelivery/rider/orders?page=1&size=10&tab=newTask&longitude=121.
 
 `newTask` 的 `longitude` 和 `latitude` 仅用于附近范围筛选、计算取件点距离和排序；其他页签忽略坐标。列表按页签和骑手范围完成服务端过滤后再分页，不由 App 拉取完整集合后过滤。
 
-`newTask` 分页响应的 `data` 除 `records`、`total`、`current`、`size` 外，还返回 `nearbyTaskCount` 和 `highestOrderAmount`。不返回尖峰倍率或骑手收入字段。`amount` 是用户支付的订单金额，页面文案不得表述为“预估收益”或“收益”；`nearbyTaskCount` 是附近待抢订单数，不是上线骑手数。
+`newTask` 分页响应的 `data` 除 `records`、`total`、`current`、`size` 外，还返回 `nearbyTaskCount` 和 `highestOrderAmount`。不返回尖峰倍率或骑手收入字段。`amount` 是服务端计算的订单报价金额，当前不会发起支付或扣款，页面文案不得表述为“预估收益”或“收益”；`nearbyTaskCount` 是附近待抢订单数，不是上线骑手数。
 
 所有页签的 `data.records` 使用骑手列表摘要字段：
 
@@ -637,7 +643,7 @@ GET /system/flashDelivery/rider/orders/{id}
 POST /system/flashDelivery/rider/orders/{id}/accept
 ```
 
-无请求体。抢单成功后状态变为 `ACCEPTED`，响应 `data` 直接返回完整订单字段；订单已被其他骑手抢走时返回“订单已被其他骑手接走”。
+无请求体。骑手账号必须已开通闪送配送。抢单成功后状态变为 `ACCEPTED`，响应 `data` 直接返回完整订单字段；订单已被其他骑手抢走时返回“订单已被其他骑手接走”。违反急送独占规则时返回统一的独占冲突提示，App 应保留在列表页并刷新可接任务。
 
 ### 8.4 确认取件
 
@@ -772,6 +778,8 @@ POST /system/address/{id}/top
 | 配送距离不能超过 40 公里 | 服务端路线距离超限 | 提示当前路线不可下单 |
 | 预约取件时段无效 | 时间已过、超过三天或不是 30 分钟 | 重新选择预约时段 |
 | 订单已被其他骑手接走 | 并发抢单失败 | 刷新待抢列表 |
+| 骑手存在进行中的独占配送任务 | 当前订单或骑手已有急送冲突 | 保留当前页并刷新可接任务 |
+| 系统繁忙，请稍后重试 | Redis 不可用或 3 秒内未取得骑手锁 | 不重复提交，稍后刷新并重试 |
 | 当前订单状态不允许此操作 | 页面状态已过期或重复操作 | 重新拉取订单详情 |
 | 交付 PIN 不正确 | 骑手提交 PIN 错误 | 保留页面并重新输入 PIN |
 | 闪送订单不存在或无权访问 | ID 不存在或不属于当前账号 | 返回列表并刷新数据 |
@@ -787,11 +795,12 @@ POST /system/address/{id}/top
 - App 使用响应体 `code` 判断成功或失败。
 - 分页列表从 `data.records` 和 `data.total` 取值。
 - 图片先上传，再向闪送接口提交完整 HTTP(S) URL。
-- 用户只在待接单或已接单状态显示取消入口，只在已送达状态显示确认收货入口。
+- “我发的”只在待接单或已接单状态显示取消入口；“我发的”和“我收的”都只在已送达状态显示确认收货入口。
 - 骑手抢单前可展示完整文字地址但不使用坐标导航；抢单成功后再读取联系人、电话、精确坐标和履约图片。
 - 骑手严格按 `ACCEPTED -> PICKED_UP -> DELIVERED` 顺序操作。
 - 启用 PIN 时，骑手送达必须提交用户端详情显示的四位 PIN。
 - 对抢单冲突、状态变化和重复点击，均以刷新后的服务端订单状态为准。
 - 用户订单列表使用 `role=sender/receiver` 切换“我发的”和“我收的”；状态页签如需展示，仅基于当前页数据本地过滤。
+- “我收的”只展示创建时唯一匹配并固化到订单的账号；不在列表或详情查询时动态认领历史订单。
 - 发布成功页显示“发布后等待附近骑手接单”，不显示虚构的骑手数量或预计接单时长。
 - 骑手端金额文案统一为“订单金额”，不使用“收益”；联系骑手/用户通过 IM，不提供通话。