# 功能规格：闪送配送服务

**功能标识**：`024-flash-delivery`

**创建日期**：2026-08-31

**状态**：既有功能已验证；2026-09-07 设计稿费用与物品信息对齐增量已确认，待实施

**输入**：基于蓝湖“闪送”分组 7 个设计页面、2026-08-24 用户端/骑手端补充原型及 2026-09-03 更新的 19 张用户端设计稿，实现帮送/帮取业务场景、普通/1 对 1 加急配送、共享地址簿、路线报价、完整物品信息、立即/预约配送、费用明细与报价校验、可选 PIN 交付、创建订单、寄件人/收件人订单查询、骑手主动抢单、急送独占、取件、送达、用户签收、平台配置与介入的非支付业务闭环。

## 用户场景与测试

### 用户故事 1：用户获取报价并发布闪送订单（优先级：P1）

用户选择帮送或帮取、普通或 1 对 1 加急配送，填写取送地址、物品信息和可选骑手小费后获取服务端报价，并回传报价明细发布一笔等待骑手接单的闪送订单。

**优先级原因**：报价与发布订单是闪送服务成立的基础，没有该能力就无法形成可配送任务。

**独立测试**：为同一组取件和收件坐标分别选择帮送/帮取及普通/加急配送，验证两种业务场景共享运价，立即订单按当前时刻、预约订单按预约开始时刻匹配唯一运价时段；系统使用起送与里程规则计算普通配送费，以当前时段的加急比例和最低加急费计算加急费，再加入用户小费返回整数新台币明细；创建订单时前端回传报价，后端复算并逐项校验后保存物品、地址、路线和计价快照。

**验收场景**：

1. **假如** 立即订单的当前时刻或预约订单的预约开始时刻命中唯一运价时段，**当** 用户请求报价，**那么** 帮送与帮取均使用该时段的起送距离、起送价格、计价距离、计价金额、加急比例和最低加急费计算报价。
2. **假如** 路线距离超过起送距离不足 0.5 公里、达到 0.5 公里但不足 1 公里或超过 1 公里，**当** 用户请求报价，**那么** 系统分别按 0、1 公里或实际超出距离计算里程费用，并将新台币金额四舍五入为整数元。
3. **假如** 地图路线服务正常，**当** 用户请求报价，**那么** 系统使用路线距离并标记距离来源为路线服务。
4. **假如** 地图路线服务超时或失败，**当** 用户请求报价，**那么** 系统使用经纬度直线距离降级报价并明确标记距离来源。
5. **假如** 客户端创建订单时回传的配置版本、基础配送费、距离费、加急费或总金额与服务端最新复算结果不一致，**当** 系统校验报价，**那么** 系统不得创建订单，并返回报价已变化的业务结果及最新报价。
6. **假如** 同一用户以相同客户端请求号重复创建订单，**当** 请求被重复处理，**那么** 系统返回同一订单且不产生重复订单。
7. **假如** 用户选择预约配送，**当** 创建订单，**那么** 系统保存 30 分钟取件时段，预约开始前订单不进入骑手可抢列表。
8. **假如** 路线距离超过 40 公里，**当** 用户报价或创建订单，**那么** 系统拒绝请求。
9. **假如** 用户选择普通配送，**当** 系统报价，**那么** 加急费必须为 0；用户选择加急配送时，加急费必须为普通配送费乘当前时段加急比例并与最低加急费取较大值。
10. **假如** 用户填写物品类别、数量、总重量和规格，**当** 报价或创建订单，**那么** 系统校验数量为正整数、总重量大于 0 且不超过 20kg，并由总重量生成内部重量档。
11. **假如** 用户填写骑手小费，**当** 系统报价或创建订单，**那么** 小费作为独立非负整数 TWD 明细参与总金额，但不改变基础配送费或加急费。

---

### 用户故事 2：骑手从闪送列表主动抢单并完成配送（优先级：P1）

骑手通过与骑手外卖订单一致的单一分页列表和页签参数查看新任务、待取件、配送中、已完成及已取消任务，主动抢单后依次上传取件和送达图片，完成实际配送。

**优先级原因**：第一版明确采用骑手主动抢单，不实现自动派单；抢单与配送状态流转是业务闭环的核心。

**独立测试**：使用 `page、size、tab、longitude、latitude` 查询骑手闪送列表，验证五个页签的状态映射、本人订单边界、附近任务距离和接单前字段；再由两个骑手并发抢同一订单，验证只有一个骑手成功，成功骑手上传取件和送达图片后订单依次进入已取件和已送达状态。

**验收场景**：

1. **假如** 骑手传入 `tab=newTask` 和当前位置，**当** 查询闪送列表，**那么** 系统只返回当前可抢任务，并按与骑手外卖新任务列表一致的附近范围和距离规则处理。
2. **假如** 两名骑手同时抢同一订单，**当** 两个请求并发到达，**那么** 只有一名骑手成功，另一名收到订单已被接走的业务结果。
3. **假如** 骑手尚未抢到订单，**当** 其尝试确认取件或送达，**那么** 系统拒绝操作且不泄露完整联系方式。
4. **假如** 已接单骑手未提交取件图片，**当** 其确认取件，**那么** 系统拒绝状态变更。
5. **假如** 已取件骑手未提交送达图片，**当** 其确认送达，**那么** 系统拒绝状态变更。
6. **假如** 图片要求已满足，**当** 订单骑手按顺序确认取件和送达，**那么** 系统保存凭证、操作人和时间并完成对应状态变更。
7. **假如** 订单启用 PIN 交付，**当** 骑手提交错误 PIN，**那么** 系统拒绝送达且不保存送达图片或改变状态。
8. **假如** 订单启用 PIN 交付，**当** 骑手提交正确 PIN 和送达图片，**那么** 系统验证 PIN 后进入已送达状态。
9. **假如** 骑手尚未接单，**当** 查看列表或详情，**那么** 系统按原型返回完整取送文字地址、包裹、时段、路线、金额和是否需要 PIN 等接单判断信息，但不返回联系人、电话、实际 PIN、精确坐标或内部字段。
10. **假如** 骑手切换 `toPickup`、`delivering`、`completed` 或 `cancelled` 页签，**当** 查询列表，**那么** 系统只返回当前骑手本人且符合页签状态映射的任务。
11. **假如** 骑手查看列表顶部摘要，**当** 当前页签为 `newTask`，**那么** 系统返回附近任务总数和最高订单金额，不返回尖峰倍率或骑手收入字段。

---

### 用户故事 3：用户安全管理共享地址簿（优先级：P1）

用户在闪送与现有收货场景中共用同一个地址簿，可以搜索、新增、修改、查看、删除和置顶自己的地址。

**优先级原因**：蓝湖设计中的取件地址、收件地址和地址簿均依赖该能力，同时现有地址接口需要消除跨用户访问风险。

**独立测试**：准备用户 A 与用户 B 的地址，以用户 A 身份执行列表、详情、修改、删除和置顶操作，验证只能访问 A 的地址，所有针对 B 地址的请求均被拒绝。

**验收场景**：

1. **假如** 用户拥有多条地址，**当** 用户按姓名、电话或地址关键词搜索，**那么** 系统只返回该用户自己的匹配地址。
2. **假如** 用户置顶一条地址，**当** 再次查询地址列表，**那么** 该地址排在当前用户其他地址之前。
3. **假如** 用户提交其他用户的地址 ID，**当** 其尝试查看、修改、删除或置顶，**那么** 系统拒绝操作且不返回目标地址内容。
4. **假如** 客户端在新增或修改地址时提交 `userId`，**当** 系统保存地址，**那么** 系统忽略该字段并以登录用户身份确定归属。

---

### 用户故事 4：用户跟踪、取消和签收自己的订单（优先级：P1）

用户查看自己的闪送订单与履约进度，可以在允许阶段取消订单，并在骑手送达后确认签收。

**优先级原因**：用户需要了解履约进度，并对尚未实际取件的订单保留取消能力。

**独立测试**：分别创建处于待接单、已接单、已取件和已送达状态的订单，验证用户取消和签收权限符合状态机规则，并验证送达 24 小时后的自动完成。

**验收场景**：

1. **假如** 订单处于待接单或已接单，**当** 订单用户取消，**那么** 订单进入已取消状态并记录原因。
2. **假如** 订单已取件，**当** 订单用户尝试取消，**那么** 系统拒绝并要求平台介入。
3. **假如** 骑手已确认送达，**当** 订单用户确认签收，**那么** 订单进入已完成状态。
4. **假如** 骑手送达后用户 24 小时未确认，**当** 自动完成任务执行，**那么** 订单进入已完成状态并记录自动操作日志。
5. **假如** 用户既不是订单创建人也不是已绑定收件人，**当** 其查询详情、取消或签收，**那么** 系统拒绝访问。
6. **假如** 用户查询订单列表，**当** 提交 `role=sender` 或省略 `role`，**那么** 系统按创建时间倒序返回本人创建的各状态订单轻量摘要，不要求客户端提交 `scene`、`status` 或 `serviceType`。
7. **假如** 创建订单时收件手机号唯一匹配一名当时已注册的普通用户，**当** 该用户提交 `role=receiver` 查询列表或查询订单详情，**那么** 系统返回该用户作为收件人的订单并允许读取收件码和配送进度。
8. **假如** 创建订单时收件手机号没有匹配账号或匹配结果不唯一，**当** 手机号对应用户以后注册或发生换绑，**那么** 历史订单不自动认领或改变收件账号归属。
9. **假如** 匹配收件人查询订单，**当** 尝试取消订单，**那么** 系统拒绝操作；寄件人仍是唯一有权主动取消订单的用户。
10. **假如** 寄件人或匹配收件人确认已收货，**当** 订单处于已送达状态，**那么** 系统以原子状态转换完成订单。

---

### 用户故事 5：平台管理时段运价并介入异常订单（优先级：P2）

平台管理员维护一套供帮送和帮取共享的分时段运价，查询全部闪送订单，并在取件后的异常场景中取消或完成订单。

**优先级原因**：价格必须可运营调整，取件后的订单又必须具备受控的人工处置入口。

**独立测试**：管理员新增、修改和删除统一运价时段，验证重叠时段被拒绝、保存后立即生效，普通报价使用基础配送规则，加急报价额外使用该时段的加急比例和最低加急费；随后对已取件订单执行平台取消并检查状态日志。

**验收场景**：

1. **假如** 管理员新增或修改统一运价时段，**当** 帮送或帮取的新请求命中该时段，**那么** 新报价立即使用新配置且已创建订单价格不变。
2. **假如** 时间范围重叠、起止时间非法、距离或金额不是正数、金额不是整数、加急比例为负数或最低加急费为负数，**当** 管理员提交配置，**那么** 系统拒绝保存。
3. **假如** 普通用户或骑手调用平台配置或介入接口，**当** 权限校验执行，**那么** 系统拒绝操作。
4. **假如** 订单已取件但发生异常，**当** 有权限的管理员取消订单，**那么** 系统允许取消并记录管理员、原因和时间。
5. **假如** 订单已送达但用户无法确认，**当** 有权限的管理员确认完成，**那么** 系统完成订单并记录平台操作日志。

---

### 用户故事 6：平台在管理后台配置价格并处理闪送订单（优先级：P2）

平台管理员从“闪送管理”菜单进入价格配置或订单管理页面，无需直接调用接口即可维护统一分时段运价、筛选订单、查看完整履约资料并执行受权限控制的平台介入。

**优先级原因**：后端接口已具备，但缺少平台可操作入口会导致计价只能通过接口工具维护，异常订单也无法进入日常运营流程。

**独立测试**：以拥有完整闪送权限的管理员登录后台，完成统一分时段运价读取与修改、订单组合筛选、详情查看、异常取消和已送达订单完成；再以缺少对应权限的账号验证菜单与操作按钮不可用。

**验收场景**：

1. **假如** 管理员进入价格配置页面，**当** 页面加载，**那么** 系统按开始时间展示全部统一运价时段、起送规则、普通超距规则、加急比例、最低加急费及配置版本。
2. **假如** 管理员新增、修改或删除合法时段，**当** 操作成功，**那么** 页面刷新服务端配置；非法值、重叠时段或并发冲突必须保留编辑内容并展示错误。
3. **假如** 管理员进入订单页面，**当** 按状态、服务类型、订单号、用户 ID 或骑手 ID 查询，**那么** 表格按服务端分页结果展示并可重置条件。
4. **假如** 管理员查看订单详情，**当** 详情加载，**那么** 页面分区展示订单概况、取送地址、费用明细、预约与 PIN、骑手、图片凭证和状态日志。
5. **假如** 订单处于非终态，**当** 具有取消权限的管理员填写原因并二次确认，**那么** 页面调用平台取消接口并刷新列表与详情。
6. **假如** 订单处于已送达状态，**当** 具有完成权限的管理员二次确认，**那么** 页面调用平台完成接口并刷新订单状态。

---

### 用户故事 7：收件人查看订单且急送骑手保持独占（优先级：P1）

已注册普通用户在他人创建订单时通过收件手机号被安全绑定为收件人，可在“我收的”查看订单详情和配送进度；骑手承接 `deliveryType=URGENT` 的 1 对 1 急送后，在订单送达或取消前不得承接其他外卖或闪送任务。

**独立测试**：使用已注册、未注册、重复手机号和换绑手机号创建订单，验证收件账号只在创建时唯一匹配并固化；并发发起急送与其他任务抢单，验证同一骑手只能进入一个互斥的有效接单结果。

**验收场景**：

1. **假如** 收件手机号唯一匹配一名已注册普通用户，**当** 创建订单，**那么** 系统将该用户 ID 固化为 `receiverUserId`，后续手机号变化不改写历史订单。
2. **假如** 收件手机号没有匹配或匹配到多名用户，**当** 创建订单，**那么** 订单照常创建但 `receiverUserId` 为空，不向任何账号开放“我收的”权限。
3. **假如** 骑手已有未送达的外卖或有效闪送任务，**当** 抢 1 对 1 急送订单，**那么** 系统拒绝接单。
4. **假如** 骑手已承接 1 对 1 急送且订单仍处于已接单或已取件，**当** 再抢外卖、普通闪送或另一笔急送，**那么** 系统拒绝接单。
5. **假如** 急送订单已送达、完成或取消，**当** 骑手再次抢单，**那么** 独占限制解除。
6. **假如** 急送与其他任务并发抢单，**当** 请求针对同一骑手到达，**那么** 所有相关接单入口使用同一骑手级 Redis 分布式锁串行检查，不能绕过独占规则。

## 边界情况

- 取件地址和收件地址相同或坐标相同，不允许创建订单。
- 地址缺少联系人、联系电话、完整地址或有效经纬度时，不允许用于报价和创建订单。
- 经纬度超出合法范围时拒绝请求，不调用地图服务。
- 立即订单在当前时刻、预约订单在预约开始时刻没有匹配的运价时段时，不允许报价或创建订单，并返回“对应取件时段暂无可用运价”。
- 地图路线结果缺少有效距离时按路线失败处理并降级为直线距离。
- 创建订单时当前配置或路线结果与先前报价不同，拒绝创建并返回最新报价，不得静默使用新金额创建订单。
- 待接单列表仅返回待接单订单；已取消或已被抢走的订单不得继续出现在新查询结果中。
- 待抢订单列表按原型显示完整取送文字地址，但隐藏联系人、电话、实际 PIN、精确坐标和内部字段；抢单成功后订单骑手才能读取履约所需的完整联系方式与坐标。
- 骑手第一版不能自行放弃已抢订单，需要平台介入处理。
- 已完成和已取消为终态，不允许再次变更。
- 自动完成任务与用户确认、平台完成并发时，只允许一个状态变更成功且不得重复写入完成副作用。
- 价格接口暂时无数据时，价格页面必须显示空状态，不得使用前端默认价格冒充服务端配置。
- 订单详情加载失败时不得保留上一笔订单资料；取消或完成失败时不得提前修改本地状态。
- 图片凭证为空时显示明确空状态；图片加载失败不得阻塞其他订单资料展示。

## 需求

### 功能需求

- **FR-001**：系统必须将业务场景与配送等级分离：`serviceType` 只接受 `HELP_SEND`（帮送）和 `HELP_PICKUP`（帮取），`deliveryType` 只接受 `NORMAL`（普通配送）和 `URGENT`（1 对 1 加急配送）。
- **FR-002**：帮取只承担取件配送，不包含代购、垫付或商品金额。
- **FR-003**：帮送、帮取、普通配送和加急配送必须使用同一订单履约状态机；`deliveryType=URGENT` 额外启用骑手独占规则和加急计价。
- **FR-004**：系统必须维护一套供帮送和帮取共享的多个运价时段；每个时段保存开始时间、结束时间、起送距离、起送价格、计价距离、计价金额、加急比例、最低加急费、配置版本与修改记录，配置保存即生效且不设置启停状态。
- **FR-005**：立即订单必须按报价时刻匹配唯一运价时段，预约订单必须按 `scheduledPickupStartAt` 匹配唯一运价时段；全部时间段之间不得重叠，没有匹配时段时必须拒绝报价和创建订单。
- **FR-006**：计价必须与现有外卖订单一致：起送距离内只收起送价格；超出不足 0.5 公里不加价，超出 0.5 公里但不足 1 公里按 1 公里计，超出至少 1 公里按实际超出距离计；里程费用四舍五入到整数元后与起送价格相加，所有 TWD 金额均为整数且不再按百位或千位特殊取整。
- **FR-007**：系统必须优先使用地图路线距离，地图失败时使用经纬度直线距离并向客户端返回距离来源。
- **FR-008**：地图密钥必须从服务端配置读取，不得返回客户端或写入业务日志。
- **FR-009**：创建订单时前端必须回传报价配置 ID、版本、基础配送费、距离费、加急费和总金额；服务端必须重新计算距离和价格并逐项精确校验，一致后才能保存地址、路线、金额和计价配置快照，不一致时不得创建订单并必须返回最新报价。
- **FR-010**：系统必须使用客户端请求号保证同一用户的订单创建幂等。
- **FR-011**：闪送订单不得复用餐饮订单或打车订单数据模型。
- **FR-012**：订单必须保存包裹类别、正整数数量、大于 0 且不超过 20kg 的总重量及可选体积/规格说明；内部重量档由总重量生成：不超过 5kg 为 `SMALL`，超过 5kg 且不超过 12kg 为 `MEDIUM`，超过 12kg 且不超过 20kg 为 `LARGE`，不得由客户端直接指定。
- **FR-013**：订单必须支持用户备注，但备注不参与计价。
- **FR-014**：骑手必须通过统一闪送订单列表的 `newTask` 页签主动抢单，第一阶段不实现自动派单。
- **FR-015**：骑手闪送列表必须复用骑手外卖订单列表的查询参数名称和分页习惯：`page`、`size`、`tab`、`longitude`、`latitude`；不得再拆分为 `available`、`mine` 或叠加 `scene`、`status`、`serviceType` 筛选。
- **FR-016**：骑手抢单必须使用原子条件更新，确保同一订单最多由一名骑手抢到。
- **FR-017**：订单状态必须包括待接单、已接单、已取件、已送达、已完成和已取消。
- **FR-018**：只有抢到订单的骑手能够确认取件和送达。
- **FR-019**：确认取件必须至少提供一张取件图片；确认送达必须至少提供一张送达图片。
- **FR-020**：系统必须保存取件和送达图片 URL、凭证类型、操作骑手和操作时间。
- **FR-021**：用户只能在待接单或已接单状态取消自己的订单。
- **FR-022**：订单已取件后，用户和骑手均不能自行取消，只有有权限的平台管理员能够介入取消。
- **FR-023**：骑手确认送达后，用户可以确认签收并完成订单。
- **FR-024**：送达后 24 小时未确认的订单必须自动完成，并留下可审计日志。
- **FR-025**：平台管理员能够查询全部闪送订单及日志，并在允许状态执行取消或完成操作。
- **FR-026**：每次有效状态变更必须记录变更前状态、变更后状态、操作人类型、操作人 ID、原因和时间。
- **FR-027**：所有状态变更必须校验当前状态、业务归属和操作角色，并防止并发覆盖。
- **FR-028**：用户只能查询、取消和签收自己的闪送订单。
- **FR-029**：骑手在抢单前可查看完整取送文字地址及履约判断所需的订单摘要，但不得获得联系人、电话、实际 PIN、精确坐标或内部字段；抢单成功后才能查看完整联系方式和坐标。
- **FR-030**：闪送必须与现有收货场景共用 `info_address` 地址数据。
- **FR-031**：统一地址接口必须要求登录身份，并对详情、修改、删除和置顶执行地址所有权校验。
- **FR-032**：地址列表必须支持按当前用户的姓名、电话和地址关键词搜索，并支持置顶排序。
- **FR-033**：地址保存接口必须忽略客户端提供的用户 ID，以当前登录用户确定地址归属。
- **FR-034**：所有用户端和骑手端接口必须直接读取请求头 token；不得接受客户端提交的用户或骑手身份。
- **FR-035**：所有平台接口必须使用后台权限校验，并为配置查询、配置修改、订单查询和订单介入设置明确权限。
- **FR-036**：所有请求必须使用明确 DTO 或显式查询参数，Controller 不得使用 Map 接收请求。
- **FR-037**：所有业务校验错误必须通过项目国际化消息机制返回，不得硬编码单一语言错误。
- **FR-038**：系统必须复用现有上传能力；闪送接口仅接收上传完成后的图片 URL。
- **FR-039**：本功能的数据库变更只能记录在 `updatesql/sql.md`，不得直接执行。
- **FR-040**：订单必须支持 `NOW` 和 `SCHEDULED` 两种配送方式；预约时段固定为 30 分钟且不得晚于创建时间后三天。
- **FR-041**：预约订单在预约开始时间前不得出现在可抢列表，也不得被骑手通过订单 ID 提前抢取。
- **FR-042**：用户可选择是否启用 4 位数字交付 PIN；启用后骑手必须同时提交正确 PIN 和至少一张送达图片。
- **FR-043**：PIN 只对订单用户和有权限的平台管理员可见，不得返回给待接单或已接单骑手，也不得写入业务日志。
- **FR-044**：创建订单可提交 1 至 9 张可选寄件图片；凭证类型扩展为 `SENDER`、`PICKUP`、`DELIVERY` 并记录操作人类型。
- **FR-045**：用户订单列表必须只接收 `page` 和 `size`，按创建时间倒序返回本人全部状态的轻量摘要；骑手订单列表必须按 `tab` 在服务端映射底层状态并完成分页，禁止先分页后由客户端过滤。
- **FR-046**：用户列表、骑手列表和角色详情必须分别使用专用响应视图。App 详情响应的 `data` 必须直接是订单详情，不得再套 `order`、`images` 或 `logs`；照片使用 `senderImageUrls`、`pickupImageUrls`、`deliveryImageUrls` 等明确字段，原始状态日志只允许平台审计详情返回。
- **FR-047**：骑手接单后，用户可读取骑手昵称、头像和评分等公开摘要；实时位置只在配送进行状态向订单用户返回。
- **FR-048**：路线距离不得超过 40 公里；超过限制时报价和创建均拒绝。
- **FR-049**：平台管理前端必须提供“闪送管理”父菜单，并提供“价格配置”和“闪送订单”两个子页面。
- **FR-050**：平台前端必须通过现有六个 `flash:*` 权限分别控制页面访问、价格修改、订单查看、取消和完成操作，不得仅依赖按钮隐藏代替后端鉴权。
- **FR-051**：价格配置页面必须按开始时间展示统一运价时段，并支持新增、修改和删除；表单字段为 `startTime`、`endTime`、`startingDistance`、`startingFare`、`distance`、`freight`、`urgentRate` 和 `minimumUrgentFee`，同时展示只读配置版本与更新时间。
- **FR-052**：价格表单必须校验时间范围有效、全部时段互不重叠、距离为正数、起送价格和计价金额为正整数、加急比例和最低加急费为非负数；配置保存即生效，删除后立即不可用于报价，操作成功后必须重新读取服务端列表。
- **FR-053**：订单页面必须按服务端分页，并支持状态、服务类型、订单号、用户 ID 和骑手 ID 组合筛选及一键重置。
- **FR-054**：平台订单详情必须展示订单概况、取送地址、路线与费用、预约与 PIN、骑手 ID 与履约时间、三类图片凭证及状态日志；不得要求管理员从列表字段拼接详情。
- **FR-055**：平台取消必须要求非空原因和二次确认；平台完成必须二次确认。操作成功后刷新服务端数据，操作失败时保留当前页面并显示后端错误。
- **FR-056**：平台前端新增的全部用户可见文本必须通过 Vue i18n 提供简体中文、繁体中文、英文和越南文，不得硬编码单一语言文本。
- **FR-057**：平台前端必须沿用现有 Vue 2、Element UI、若依请求封装、动态菜单和 `v-hasPermi` 体系，不新增重复的状态管理或 UI 框架。
- **FR-058**：骑手列表 `tab` 只接受 `newTask`、`toPickup`、`delivering`、`completed` 和 `cancelled`，分别映射待接单、已接单、已取件、已送达/已完成和已取消；闪送不提供外卖退款页签。
- **FR-059**：骑手 `newTask` 列表必须返回取件点距离、路线距离、预计时长、基础配送费、加急费、小费、订单总金额、业务场景、配送等级、包裹类别、数量、总重量、规格、重量档、配送方式、预约时段、完整取送文字地址和是否需要 PIN，并返回附近任务总数与最高订单金额；不得返回内部加急比例、最低加急费或尚未实现的骑手收入。
- **FR-060**：用户创建订单、用户详情、骑手详情和骑手接单成功响应必须使用直接且稳定的 App 订单详情结构；权限差异只影响敏感字段是否返回，不得改变 `data` 的顶层形状，也不得要求 App 通过 `data.order` 是否存在判断响应类型。
- **FR-061**：订单新增可空 `receiver_user_id`；创建订单时将收件手机号去除首尾/内部空白、`+`、`-` 和圆括号但不改写国家码，再以剩余数字唯一匹配当时已注册且 `userType=0` 的普通用户并固化匹配结果，不执行历史订单追溯认领。
- **FR-062**：手机号无匹配或存在多个普通用户匹配时不得绑定收件账号；订单仍可创建，且不得选择任意一名用户作为收件人。
- **FR-063**：用户订单列表新增 `role` 参数，只接受 `sender` 和 `receiver`，省略时兼容为 `sender`；筛选必须在数据库分页前完成。
- **FR-064**：订单创建人和已绑定收件人均可查询订单详情并确认签收；只有订单创建人可以主动取消订单。交付 PIN 对两类参与者可见。
- **FR-065**：`deliveryType=URGENT` 表示 1 对 1 独占配送。骑手已有未送达外卖、`ACCEPTED` 或 `PICKED_UP` 闪送时不得接急送；骑手存在 `ACCEPTED` 或 `PICKED_UP` 急送时不得再接任何外卖或闪送。
- **FR-066**：所有有效骑手接单入口必须使用同一 Redisson 锁键 `lock:delivery:rider:{riderId}`，在持锁期间检查跨外卖和闪送订单的独占条件并执行接单；锁必须在数据库事务完成后释放，获取超时或 Redis 异常时按失败关闭原则拒绝接单。
- **FR-067**：闪送继续保持非支付业务，创建成功直接进入 `WAITING_ACCEPTANCE`，不增加待支付状态、支付倒计时、支付接口或退款流程。
- **FR-068**：所有闪送金额继续使用整数 TWD；蓝湖稿中的小数金额仅为视觉占位，不改变接口和数据库金额类型。
- **FR-069**：用户端不得展示固定或伪造的附近骑手人数及预计接单分钟数，统一使用“发布后等待附近骑手接单”；本期不增加实时骑手数量或接单预测接口。
- **FR-070**：普通配送费等于起送价格与距离费之和；普通配送的加急费为 0，加急配送的加急费等于“普通配送费 × 当前时段加急比例”四舍五入到整数 TWD 后与最低加急费取较大值。
- **FR-071**：骑手小费由用户提交，为独立的非负整数 TWD；订单总金额等于普通配送费、加急费和骑手小费之和，小费不得参与加急费计算。
- **FR-072**：报价和订单响应必须分别返回 `baseDeliveryFee`、`distanceFee`、`urgentFee`、`tipAmount` 和 `amount`；加急报价还必须返回命中的 `urgentRate` 和 `minimumUrgentFee`，费用名称不得混用。

### 关键实体

- **闪送订单**：用户发布的取件配送任务，持有业务场景、配送等级、物品、地址、路线、费用、履约状态和关键时间快照。
- **计价配置**：供帮送和帮取共享、在一个时间范围内立即生效的起送距离、起送价格、计价距离、计价金额、加急比例、最低加急费及版本信息。
- **配送凭证**：用户下单时的可选寄件图片，以及骑手取件或送达时提交的必填图片记录。
- **订单状态日志**：记录订单每次有效状态变化的操作审计信息。
- **共享地址**：属于单一用户、可供闪送和现有收货业务共同使用的联系人与地点信息。

## 成功标准

- **SC-001**：帮送/帮取共享运价、立即/预约时段匹配、起送距离、0.5 公里边界、实际超出距离、整数新台币取整、比例加急费、最低加急费和小费报价测试全部通过。
- **SC-002**：地图路线成功和失败降级场景均能在一次请求内返回可用报价，并准确标记距离来源。
- **SC-003**：至少 20 个并发抢单请求针对同一订单时，数据库中恰好只有一名骑手成功绑定。
- **SC-004**：跨用户地址和订单的详情、修改、删除、置顶、取消及签收测试拦截率达到 100%。
- **SC-005**：缺少取件或送达图片的状态变更请求拦截率达到 100%。
- **SC-006**：所有允许和禁止的状态流转均有自动化测试覆盖，终态订单不能再次改变状态。
- **SC-007**：送达超过 24 小时的订单能够自动完成，且并发确认不会产生重复状态日志或重复副作用。
- **SC-008**：修改计价配置后，新订单使用新版本，历史订单保存的价格与配置快照保持不变。
- **SC-009**：所有新增用户可见业务错误均能通过项目支持的语言资源解析，不出现硬编码单一语言结果。
- **SC-010**：拥有对应权限的管理员能够只通过平台页面完成统一分时段运价维护和订单查询、详情、取消及完成操作，核心流程无需 Postman 或数据库操作。
- **SC-011**：价格和订单页面的接口路径、请求方法、查询参数及权限字符串契约测试全部通过，四个前端语言文件的 `flashDelivery` key 集合完全一致。
- **SC-012**：平台前端生产构建通过，新增页面在 1280px 及以上后台常用宽度无横向页面溢出，表格窄屏时仅在表格区域滚动。

## 假设

- 继续使用现有用户、骑手、token、骑手位置、图片上传和站内消息/推送基础设施。
- 地图路线服务的具体供应商与密钥沿用项目现有配置能力；计划阶段确定现有配置键和 HTTP 调用位置。
- 币种为新台币，接口使用稳定币种代码 `TWD`。
- 第一阶段不根据有效骑手数量阻止下单，也不实现自动匹配、自动派单或定向派单。
- 蓝湖页面中的附近骑手数量与预计接单时间不作为动态业务承诺，用户端统一显示“发布后等待附近骑手接单”。
- 骑手第一阶段不能自行放弃已抢订单，由平台管理员介入处理异常订单。

## 非目标

- 不接入支付网关、付款、退款、取消费、退回费、结算或骑手收入分账。
- 不实现代购、垫付款、商品金额或禁寄品电子确认；禁运品和货值限制由前端展示规则说明，后端校验本期明确的物品数量、总重量、规格长度和最大路线距离。
- 不实现自动派单、抢单推送筛选、骑手在线状态计算或接单时间预测。
- 不修改餐饮订单 `pos_order` 或打车订单 `taxi_order` 的业务语义。
- 不在本功能中实现用户端、骑手端或商家端页面；本轮前端增量仅实现平台管理端。
