# 闪送 API 联调快速开始

1. 开发者人工执行 `updatesql/sql.md` 中既有闪送迁移及 2026-09-07 统一运价增量，核对每个时段的加急比例和最低加急费；并在字典 `sys_google_routes_key` 配置仅供后端使用、已启用 Google Routes API 的独立密钥，不得复用匿名接口可读取的 `sys_googlemap_key`。
2. 启动 `ruoyi-admin`；用户和骑手请求携带现有 `token` 请求头，平台请求使用后台权限。
3. 调用 `/system/flashDelivery/home`、`/quote`、`/orders`；报价提交帮送/帮取业务场景、普通/加急配送等级、立即/预约取件时段、完整物品信息和骑手小费。创建时回传报价 ID、版本及各项金额，服务端复算不一致时返回最新报价且不创建订单；收件账号匹配结果固化在新订单中，不追溯历史订单。
4. 用户通过 `/system/flashDelivery/orders?role=sender` 查看“我发的”，通过 `role=receiver` 查看“我收的”；省略 `role` 时默认 `sender`。发件人与固化收件人均可查看详情和确认收货，只有发件人可以取消。
5. 骑手从 `/system/flashDelivery/rider/orders?page=1&size=10&tab=newTask&longitude=121.5&latitude=25.0` 拉取待抢任务并调用 `/accept`；五个页签分别为 `newTask`（待接单）、`toPickup`（已接单）、`delivering`（已取件）、`completed`（已送达/已完成）和 `cancelled`（已取消）。`newTask` 的经纬度仅用于附近范围、取件点距离和排序，闪送没有 `refund` 页签。接单前只展示完整文字地址，隐藏联系人、电话、实际 PIN、精确坐标和履约图片；图片先走现有上传接口，再把 URL 传给 `/pickup` 和 `/deliver`。
6. `deliveryType=URGENT` 的急送接单与外卖、普通闪送共用骑手级 Redis 锁；急送进行期间骑手不能承接其他配送，接急送前骑手也不能有任何进行中配送。
7. 发布成功页使用静态文案“发布后等待附近骑手接单”，不展示动态附近骑手数或承诺接单时间。闪送不接入支付，金额保持整数 TWD。
8. 用户 `/confirmReceipt` 完成；送达满 24 小时未操作则自动完成。
9. 完整字段见 [API 契约](contracts/api.md)。

## 待接单编辑冒烟（2026-09-09）

1. 以创建人 token 获取一笔待接单订单详情及 orderVersion；修改发件或收件地址，调用 POST /system/flashDelivery/orders/{id}/address/quote。核对新路线距离与费用，重新查询订单确认尚未改动。
2. 在请求体提交 orderId，回传相同地址、orderVersion 和报价距离/费用到 POST /system/flashDelivery/orders/address；核对两端信息、收件账号归属、路线和总额同步更新，版本加一；清空可选详细地址时数据库也应为空。
3. 故意篡改 quotedAmount 或 quotedDistanceMeters，确认返回最新报价且订单无修改；用户再次确认后按最新值保存。
4. 用详情最新版本调用 POST /system/flashDelivery/orders/tip，请求体提交 orderId 和 additionalTipAmount=20；核对小费及总金额均增加 20，基础/加急费不变；原请求重放不得再次增加。
5. 在地址报价后由另一请求追加小费，再提交旧地址确认；验证版本冲突，不覆盖新小费。
6. 分别让骑手抢单、用户取消发生在编辑前或报价与保存之间；验证地址保存与追加小费均不能更新已接单/已取消订单。并发请求压测确认数据库条件更新仅按可用版本生效。
7. 收件人及无关用户请求三个端点均应被拒绝；缺失版本、非法地址、同址、超 40 公里、零/负小费及超大金额均应拒绝。
8. 后台调价后编辑既有订单，核对使用原订单运价快照；预约时间已到但仍待接单的订单也可编辑。

以上涉及真实数据库、地图与 App 的接口冒烟需在开发联调环境执行，自动化测试使用模拟外部依赖，不代替实际联调。