补充闪送 App 文档与设计原型的差异说明

docs/flash-delivery-app-api.md

@@ -16,6 +16,8 @@
 
 当前不包含支付、退款、骑手收入、结算、代购垫付、自动派单和骑手放弃订单。
 
+设计原型中的支付方式选择、已付款状态、附近骑手上线数量、预计接单时间和骑手收益金额均为静态示意，接口不提供这些数据，App 不应展示或请求它们。
+
 ## 2. 通用约定
 
 ### 2.1 基础地址和请求头
@@ -354,7 +356,7 @@ App 完整详情使用以下订单字段，响应的 `data` 直接返回这些
 - `senderImageUrls`、`pickupImageUrls` 和 `deliveryImageUrls` 分别表示寄件、取件和送达图片数组。
 - App 详情不返回原始状态日志；页面使用 `status`、`acceptedAt`、`pickedUpAt`、`deliveredAt`、`completedAt` 和 `cancelledAt` 展示进度。
 - `deliveryPinCode` 只向订单所属用户返回，并且只在启用 PIN 时出现；骑手响应永不返回此字段。
-- `rider` 只向用户返回。订单未接单时为 `null`。
+- `rider` 只向用户返回。订单未接单时为 `null`。骑手对象不包含真实电话号码，联系入口使用 `imUserId` 打开 IM 会话，原型中的通话按钮没有接口支撑。
 - 骑手位置只在订单状态为 `ACCEPTED` 或 `PICKED_UP` 时向用户返回，其他状态下经纬度为 `null`。
 
 平台订单详情是审计专用契约，仍可返回 `{order,images,logs}`；App 不应依赖或解析该结构。
@@ -513,13 +515,15 @@ GET /system/flashDelivery/orders?page=1&size=10
 
 仅查询当前用户，按创建时间倒序返回全部状态的订单摘要。接口不接受 `status`、`scene` 或 `serviceType`；响应 `data.records` 中每项为用户列表摘要对象。
 
+设计原型中的“待接单、配送中、已完成、已取消”筛选页签当前没有对应查询参数。第一版建议只展示“全部”列表；如需页签，只能基于当前页数据本地过滤，且不应依赖它得到准确的分页总数。
+
 ### 7.5 查询用户订单详情
 
 ```http
 GET /system/flashDelivery/orders/{id}
 ```
 
-仅订单所属用户可访问。响应 `data` 直接为 App 完整订单字段，包括订单快照、三类图片数组、骑手摘要和可选的交付 PIN，不返回原始状态日志。
+仅订单所属用户可访问。响应 `data` 直接为 App 完整订单字段，包括订单快照、三类图片数组、骑手摘要和可选的交付 PIN，不返回原始状态日志。响应不包含支付状态或支付方式字段，详情页不要展示“已付款”等支付信息。
 
 ### 7.6 用户取消订单
 
@@ -538,6 +542,7 @@ POST /system/flashDelivery/orders/{id}/cancel
 - `reason` 必填，去除首尾空格后不能为空，最长 500 字符。
 - 仅 `WAITING_ACCEPTANCE` 和 `ACCEPTED` 状态允许用户取消。
 - `PICKED_UP` 之后需要平台介入，用户端不能直接取消。
+- 设计原型中“骑士接单前可免费取消”的文案比接口口径更严格：接口允许骑手已接单但尚未取件时取消，且当前没有支付，取消不产生任何费用；接入支付后取消规则需重新对齐。
 
 ### 7.7 用户确认收货
 
@@ -581,7 +586,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`。不返回尖峰倍率或骑手收入字段。
+`newTask` 分页响应的 `data` 除 `records`、`total`、`current`、`size` 外，还返回 `nearbyTaskCount` 和 `highestOrderAmount`。不返回尖峰倍率或骑手收入字段。`amount` 是用户支付的订单金额，页面文案不得表述为“预估收益”或“收益”；`nearbyTaskCount` 是附近待抢订单数，不是上线骑手数。
 
 所有页签的 `data.records` 使用骑手列表摘要字段：
 
@@ -618,7 +623,7 @@ GET /system/flashDelivery/rider/orders?page=1&size=10&tab=newTask&longitude=121.
 GET /system/flashDelivery/rider/orders/{id}
 ```
 
-响应 `data` 始终直接返回订单字段，顶层结构保持稳定，不使用 `{order,images,logs}` 包装，也不要求 App 判断 `data.order`。接单前隐藏联系人、电话、实际 PIN、精确坐标和履约图片；当前骑手接单后，详情接口才补齐其有权限查看的完整履约信息。
+响应 `data` 始终直接返回订单字段，顶层结构保持稳定，不使用 `{order,images,logs}` 包装，也不要求 App 判断 `data.order`。接单前隐藏联系人、电话、实际 PIN、精确坐标和履约图片；联系人姓名与电话一样都不返回，列表和详情不要按设计原型渲染“·联系人姓名”。当前骑手接单后，详情接口才补齐其有权限查看的完整履约信息。
 
 ### 8.3 抢单
 
@@ -781,3 +786,5 @@ POST /system/address/{id}/top
 - 骑手严格按 `ACCEPTED -> PICKED_UP -> DELIVERED` 顺序操作。
 - 启用 PIN 时，骑手送达必须提交用户端详情显示的四位 PIN。
 - 对抢单冲突、状态变化和重复点击，均以刷新后的服务端订单状态为准。
+- 用户订单列表第一版只展示“全部”；如实现状态页签，仅基于当前页数据本地过滤。
+- 骑手端金额文案统一为“订单金额”，不使用“收益”；联系骑手/用户通过 IM，不提供通话。