foodie-server/specs/024-flash-delivery/quickstart.md

闪送 API 联调快速开始

1. 开发者人工执行 updatesql/sql.md 中既有闪送迁移及 2026-09-07 统一运价增量，核对每个时段的加急比例和最低加急费；闪送与外卖共用字典 sys_googlemap_key，该 Key 必须启用 Google Routes API，并在 Google Cloud 配置 API 限制、来源限制和配额。
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 契约。

待接单编辑冒烟（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 的接口冒烟需在开发联调环境执行，自动化测试使用模拟外部依赖，不代替实际联调。

多取货点验收（2026-09-15）

1. 开发者手动执行多站点 SQL，确认上限默认 1；完成所需客户端适配后，手动开启 flash_show_multi_pickup 并将 flash_pickup_stop_limit 设置为测试值。单点新订单同样必须有取送站点。
2. 创建 A → B → C → 收货点订单，每站提供不同物品。检查顺序、整线距离和金额，逐站资料独立；26 个取货点可配置，27 个取货点应在地图调用前拒绝。关闭开关及非法上限回退 1 后，多点报价/创建/改址拒绝。
3. 待接单编辑完整数组，调整顺序后先报价再确认；故意保留旧报价应拒绝保存。收件人绑定、首点摘要、物品、站点数及费用同事务变更；骑手抢单或用户取消竞争时不得部分保存。
4. 未接单骑手查看详情，逐站联系人、电话、坐标和凭证均不可见；原始交付 PIN 始终不能对骑手返回。接单后详情默认目标为 A。
5. 上传 B 的图片直接确认取件应拒绝；先向下单人沟通，再以原因、声明、版本和幂等号选择 B。重复目标请求只保留一条记录；缺少原因/声明、过期版本或外单站点拒绝。
6. 打开/退出导航后 B 仍待取。实际取到货上传图片确认 B，订单显示已取 1/3 且主状态仍 ACCEPTED，下一站回 A，金额及原顺序不变；用户取消拒绝。重试 B 不重复凭证、不改变确认时间或推进 A。
7. 依次确认 A/C，只有最后一次实际取件才进入 PICKED_UP；按原 PIN 和整单送达凭证完成。平台不能在缺少取件时绕过履约直接完成。
8. B 无法取货或收货人拒收：平台取消须选择问题站、填写处理结果；已有已取物品时，填写去向并上传交接凭证后关闭，详情可查证据。界面明确标记骑手声明，不能显示为用户审批。
9. 在独立联调环境并发请求取件/用户取消、取件/平台取消、最后两站取件、重复目标及目标/取件竞争；核对单次推进、日志凭证幂等及异常全量回滚。单元测试不替代真实 MySQL 事务验证。
10. 自建地图已完成的多点路由封装与本服务切换为不同步骤；当前路由按 Google 提供器执行，真实地图及 App 骑手导航仍须联调。