Inicio Explorar Axuda
Iniciar sesión
fa88
/
foodie-server
1
0
Fork 0
Ficheiros Incidencias 0 Pull Requests 0 Wiki
Árbore: 6ed1ca9bc1
Ramas Etiquetas
foodie-server
/
specs
/
024-flash-delivery
/
spec.md

spec.md 51 KB
Histórico Raw

功能规格：闪送配送服务

功能标识：024-flash-delivery

创建日期：2026-08-31

状态：既有功能已验证；2026-09-07 设计稿费用与物品信息对齐增量已确认，待实施；2026-09-14 多取货点增量已确认，2026-09-15 按方式 2 修订取件顺序规则，待实施

输入：基于蓝湖“闪送”分组 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. 假如 用户填写物品类别、数量、四档重量范围和规格，当 报价或创建订单，那么 系统校验数量为正整数，并且重量范围属于设计稿规定的四个枚举之一。
  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：闪送与外卖共用字典 sys_googlemap_key；闪送接口和业务日志不得返回或写入该 Key，Google Cloud 必须限制其 API、来源和配额。
  • FR-009：创建订单时前端必须回传报价配置 ID、版本、基础配送费、距离费、加急费和总金额；服务端必须重新计算距离和价格并逐项精确校验，一致后才能保存地址、路线、金额和计价配置快照，不一致时不得创建订单并必须返回最新报价。
  • FR-010：系统必须使用客户端请求号保证同一用户的订单创建幂等。
  • FR-011：闪送订单不得复用餐饮订单或打车订单数据模型。
  • FR-012：订单必须保存包裹类别、正整数数量、用户选择的重量范围及可选体积/规格说明；重量范围必须为 UP_TO_5_KG、OVER_5_TO_10_KG、OVER_10_TO_15_KG、OVER_15_TO_20_KG 之一，并作为订单快照原样保存。
  • 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-103：预约订单仅能在预约开始时间（含）至结束时间（不含）之间被骑手接取；结束时仍未接单的订单必须由系统任务自动取消，列表和接单原子更新均不得允许过期订单继续接取。
  • 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-104：平台订单概况对预约订单必须直接展示预约取件开始及结束时间，不得只显示“预约配送”。
  • 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：baseDeliveryFee 仅表示起送价格，distanceFee 表示距离附加费；普通配送费仅在服务端按两者之和计算，不增加小计字段。普通配送的加急费为 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 的业务语义。
  • 不在本功能中实现用户端、骑手端或商家端页面；本轮前端增量仅实现平台管理端。

2026-09-09：待接单订单修改地址与追加小费

  • FR-073：仅订单创建人可在 WAITING_ACCEPTANCE 且 rider_id 为空时修改当前订单的发件和收件信息（联系人、电话、地址、详细地址、交接方式和坐标）；两端完整地址一并提交，允许只改变其中一端。共享地址簿不随订单修改。
  • FR-074：地址修改先获取专属报价，服务端沿用订单计价快照与已有小费重新计算路线、距离、预计时长及费用；报价不写订单。确认时回传订单版本、报价距离及各项费用，服务端复算，一致后才原子保存；变化时返回最新报价供再次确认。
  • FR-075：修改收件电话后重新匹配已注册收件人，未匹配时清空旧绑定；同步更新取送地址、路线与费用，保留订单编号、原计价配置、物品及预约信息。
  • FR-076：追加小费提交正整数 TWD additionalTipAmount 和 orderVersion；仅增加小费及总金额，不重算基础配送费、加急费或路线。溢出拒绝。
  • FR-077：保存地址和追加小费必须在单条 UPDATE 中同时校验创建人、待接单、无骑手及订单版本，成功后版本递增。被接走、被取消、并发编辑或重复提交不得覆盖或重复加小费。

  • 本次只新增以上能力；沿用现有取消规则、非支付边界。复用现有字段与 version，无数据库迁移。

  • FR-078（2026-09-09 入参调整）：确认修改地址与追加小费使用 POST /orders/address 和 POST /orders/tip；订单 ID 通过 JSON 请求体 orderId 传入，必须是有效正整数，token 仍放请求头。

    2026-09-14：闪送多取货点（多取一送，2026-09-15 修订）

本节按 2026-09-15 用户确认的方式 2 更新：默认按用户顺序引导，取得下单人同意后允许调整实际取件顺序；替换此前无条件自由取件的规则，生产功能仍待实施。单笔订单包含 1 至 N 个取货点和 1 个收货点，每个取货点独立关联联系人和物品信息。用户填写顺序用于初始路线报价、展示和默认取件引导；调整实际取件顺序须遵守 FR-094 至 FR-098。按整条路线距离计价，不新增每取货点附加费；点间不设单独距离限制，整条报价路线仍不得超过 40 公里。

用户故事 8：用户发布多取货点订单并由骑手逐点取件（优先级：P1）

用户逐站填写联系人、地址和物品，填写唯一收货点后获取整条路线报价；骑手接单后默认按用户顺序前往未取货站点，需要调整时先与下单人沟通、取得同意并保存调整记录，再逐站确认取件并上传凭证，全部取货点完成后订单进入已取件，送达流程不变。

优先级原因：每站独立物品和凭证用于履约核对与纠纷定位。

独立测试：验证每站物品独立、按用户顺序报价和默认引导、沟通同意后调整并记录骑手声明、前往与取件分离、单点可省略 stopId、多点必传 stopId、重试不推进其他站点、取件与用户取消互斥，以及全部取货点完成时仅推进一次主状态。

验收场景：

  1. 假如 多地点开关开启，当 用户报价或创建多点订单，那么 各站分别校验联系人和物品，按用户填写顺序计算整条路线距离、时长和费用。
  2. 假如 数量超过字典有效上限，当 报价、创建或修改取货点，那么 返回国际化错误；字典缺失或非法时有效上限为 1。
  3. 假如 多地点开关关闭，当 报价、创建或编辑提交多于一个取货点，那么 拒绝；既有订单履约及仅追加小费不受开关和上限调整影响。
  4. 假如 订单只有一个取货点，当 骑手不传 stopId，那么 定位唯一取货点；多点订单未传 stopId 必须拒绝，不自动选择未取货站点。
  5. 假如 用户顺序为 A → B → C 且均未取件，当 骑手查看订单，那么 默认突出显示前往 A；骑手取得下单人同意、填写原因并声明已取得同意，保存先前往 B 的调整记录后，可以实际到 B 取货并上传凭证确认；主状态保持 ACCEPTED，全部取货点完成后才进入 PICKED_UP。
  6. 假如 请求指定非本单站点、收货站点或他人订单站点，当 取件确认，那么 拒绝；同一骑手重试已确认站点只返回已确认结果，不重复写凭证、时间、日志或推进其他站点。
  7. 假如 任意站点已经取货，当 用户自助取消，那么 拒绝并要求平台介入；与取件并发时，取件先成功则用户取消失败，取消先成功则取件失败。
  8. 假如 用户选择加急和多个取货点，当 报价或创建，那么 允许并沿用整条路线计价及骑手独占规则。
  9. 假如 待接单订单修改地址或调整站点顺序，当 报价或确认保存，那么 使用完整站点序列和原运价快照重算整线，经用户确认新报价后保存；接单后骑手仅调整实际取件先后不重算金额；仅追加小费时只增加小费和总金额，不请求路线或重算其他费用。
  10. 假如 整线超过 40 公里或地图服务失败，当 报价、创建或地址编辑重报价，那么 按整线执行距离上限和逐段直线降级；点数超限在地图调用前拒绝。
  11. 假如 旧单点请求提交 pickup 与订单级物品字段，当 报价或创建，那么 适配为一个含独立物品的取货点；pickup 与 pickups 同时提交时拒绝。

  12. 假如 多点地址保存与抢单或其他编辑并发，当 保存，那么 站点、摘要、收件人绑定、路线和金额必须同一事务提交或回滚，不出现两套地址或报价。

  13. 假如 用户下单前调整站点顺序，当 确认报价，那么 按最终顺序计算并展示路线和费用，提示默认按此顺序取件、骑手如需调整将先沟通。

  14. 假如 骑手选择非默认未取站，当 缺少调整原因或未声明已取得下单人同意，那么 不保存调整，也不能通过直接调用取件确认绕过所需记录；首期不要求用户在 App 内点击批准。

  15. 假如 已保存先前往 B 的调整，当 打开或退出导航，那么 B 仍为待取件，不生成取件凭证、不增加已取数量、不推进主状态；实际交接并提交有效图片后才可确认已取。

  16. 假如 用户顺序为 A → B → C，当 B 已取且 A/C 待取，那么 保留原始顺序和报价，展示已取 1/3 站及各站状态，默认下一站回到 A，用户自助取消不可用。

  17. 假如 平台核对调整，当 查看记录，那么 展示调整前后目标站、原因、骑手、操作时间和骑手声明，不显示为用户已在 App 审批；订单聊天可作为沟通依据。

  18. 假如 某站暂未备好，当 沟通同意后先去其他站，那么 原站继续待取；最终无法取货时联系平台处理，不能删除站点、虚假取件或直接完成整单。平台记录已取物品去向和交接凭证后再关闭异常订单。

  19. 假如 调整请求重试或与取件、取消并发，当 保存，那么 不重复追加同一次记录，不以过期状态覆盖目标；取消后禁止新调整，已取站不能作为新目标。

  • FR-079：通用站点表 flash_delivery_orderstop 保存订单 ID、类型（PICKUP/DELIVERY）、用户填写顺序、快照和履约信息，作为新订单站点数据唯一真相；所有新订单（含单点）统一写入取货和收货站点。订单表 pickup* 维护首取货点摘要，新增 pickup_stop_count。当前为测试阶段，不做历史订单迁移、无站点履约回退或历史详情适配，不自动清理测试数据。
  • FR-080：每个取货点独立保存联系人、电话、地址、详细地址、市/区、交接方式、经纬度和物品字段 packageType、quantity、weightRange、specification；逐站按既有物品规则校验并供骑手核对。唯一收货点保存收件信息，收件账号绑定和交付 PIN 维持订单级一套。既有订单级物品字段仅保留首取货点兼容摘要，不代表多点订单全部物品，不作为站点物品来源。
  • FR-081：数据字典 flash_pickup_stop_limit 配置取货点上限，不含收货点；仅接受 1 至 26 的整数，缺失、空值或非法配置时有效上限为 1。报价、创建、修改取货点均校验非空且不超过有效上限，超限返回国际化错误；首页下发有效 pickupStopLimit。26 个取货点对应 25 个中途点，超点数在地图调用前拒绝，不作为地图故障降级。
  • FR-082：flash_show_multi_pickup 控制多点能力；关闭时多于一个取货点的报价、创建和地址编辑均拒绝。开关或上限调整不影响已创建订单取件、送达及仅追加小费。
  • FR-083：flash_show_urgent_option 经首页配置下发，仅控制 App 加急选项展示；后端仍按 deliveryType 执行既有校验，不受该展示开关影响。
  • FR-084：初始及地址编辑报价按用户填写顺序计算：首取货点为起点，其余取货点为中途点，收货点为终点，不自动优化顺序；地图失败逐段直线距离求和，40 公里上限按整线执行。stop_order 用于报价、展示及默认取件引导；骑手按 FR-095 改变实际取件顺序不重排用户站点、不重算订单金额。
  • FR-085：沿用 FR-004 至 FR-006、FR-070 至 FR-072 的运价、报价回传校验和整数 TWD 取整，以整线距离替代原单段距离，不新增站点附加费或按物品计价项；保留 FR-076 小费只增加小费及总金额，不重算路线、基础配送费或加急费。
  • FR-086：deliveryType=URGENT 允许多个取货点，FR-065、FR-066 骑手独占规则不变。
  • FR-087：骑手默认按用户顺序取件，按 FR-095 保存沟通同意后的调整记录后可以先取其他未取站；每站实际取到货后至少上传一张取件图片。保留 POST /system/flashDelivery/rider/orders/{id}/pickup，请求 DTO 增加可选 stopId；单点可省略，多点必传。另提供 POST /system/flashDelivery/rider/orders/{id}/stops/{stopId}/pickup，路径 ID 为操作目标，同时传请求体 stopId 时必须一致。缺失必需 ID、站点不属本单或不是 PICKUP、骑手不是接单人时拒绝；同一骑手重试已确认站点幂等返回，不重复写凭证、日志或确认时间。新取件按 FR-096 校验当前目标及必要的调整记录；保存每站状态、时间和凭证；全部取货点完成才进入 PICKED_UP，pickedUpAt 记录最后一个实际完成取件的站点时间，不按 stop_order 判断末站。
  • FR-088：任意取货点已确认即禁止用户自助取消，不限定用户排序第一站；全部未取时维持现有取消规则，平台保留介入能力。取件与用户/平台取消共用订单行级并发保护：同一事务先锁订单行，再读取最新订单及站点状态并校验、更新。站点状态、凭证、主状态、版本和日志一并提交或回滚，不能只在取消前单独查询一次。取消成功后禁止新增取件；任一站取件成功后用户取消必须失败。
  • FR-089：列表保留现有字段和首取货点地址/物品摘要，新增 pickupStopCount；用户、骑手及平台详情新增 stops，包含站点 ID、类型、用户顺序、联系人、电话、地址、交接方式、坐标、独立物品、状态、确认时间及凭证。凭证按站关联，既有 pickupImageUrls 可聚合展示，不能用聚合列表覆盖各站凭证。骑手接单前逐站隐藏联系人、电话、精确坐标、PIN 及凭证图片，保留文字地址及履约判断所需物品信息。
  • FR-090：客户端按 FR-094 至 FR-096 确定的当前目标站拼装 Google Maps URL，默认指向用户顺序中最早的未取站，保存沟通同意后的调整后指向选定站，全部取完后导航到唯一收货点。选择前往、打开导航与确认已取货是独立操作。使用 api=1、travelmode=two-wheeler、dir_action=navigate，正确编码参数，起点默认设备当前位置；不依赖携带全部途经点的 URL 履约。后端按 FR-029 权限返回坐标，不生成导航 URL，不新增用于生成导航 URL 的接口；调整记录保存属于履约操作，不能仅保存在客户端。
  • FR-091：站点表、订单表加列、站点凭证关联所需变更及三个字典项 SQL 只记录在 updatesql/sql.md，不直接执行数据库操作。
  • FR-092：报价和创建新增 pickups 数组，每项含完整取货地址及 FR-080 物品字段；保留旧 pickup 与订单级物品作为单点输入，统一适配后校验。pickup 与 pickups 不得同时提交；使用 pickups 时不允许同时提交旧订单级物品字段，冲突返回国际化错误。AddressChange/Confirm DTO 同步支持完整 pickups 与唯一 delivery；旧 pickup 编辑仅适用于单点并保留该站物品，多点编辑缺少完整 pickups 必须拒绝，不能丢弃其余站点。

  • FR-093：地址编辑沿用 FR-073 至 FR-075、FR-077 的权限、状态、版本及原运价快照，重算整线；订单原子条件更新成功后，在同一事务保存完整站点、首点摘要、数量、收件人绑定及费用，失败全部回滚。完整站点输入保留并校验逐站物品，不因编辑联系人或地址清空物品。

  • FR-094：下单前用户可调整取货点顺序，按最终顺序报价并确认；待接单订单调整顺序沿用 FR-093 重报价及确认流程。下单页提示“默认按此顺序取件，骑手如需调整将先与您沟通”，用户可见文案按现有国际化要求实现。骑手接单后可以查看全部站点，默认突出显示用户顺序中最早的未取站为下一站。

  • FR-095：骑手需要先去其他未取站时，须先联系下单人并取得同意，再选择“先前往该站”，填写调整原因并声明“已取得下单人同意”。服务端保存订单、调整前目标站、调整后目标站、原因、骑手身份、操作时间及同意声明。首期不要求用户在 App 内点击批准；骑手勾选只证明其作出了声明，不证明下单人实际同意，平台不得标记为用户审批通过。订单聊天可作为沟通依据；未取得同意不能自行调整，无法联系下单人时联系平台处理。

  • FR-096：选择前往与确认已取货分开：前者只确定目标并记录必要的调整，不能修改站点取件状态、取件时间、凭证或主状态；后者必须实际交接并提交有效取件图片。新取件确认以当前目标为准；选择非默认站须先保存 FR-095 记录，不能通过直接提交 stopId 绕过。已确认站点的重试仍按 FR-087 幂等处理，不受目标已变化影响。选定目标在取件前保持；再次改变目标时记录调整。目标站取件后回到用户顺序中最早的未取站，全部取完后转为收货点。调整操作校验接单骑手、订单状态和本单未取站，保存须防重复并与取件、取消使用一致的订单并发保护。

  • FR-097：保留用户原始站点顺序及报价，按每站实际确认时间和状态展示履约进度；用户、骑手及平台显示已取数量/总数量（如“已取 1/3 站”）。部分取件主状态仍为 ACCEPTED，取消入口按是否任意站已取判断，不能仅依据主状态显示可取消。平台详情可查看 FR-095 调整记录；调整声明和取件凭证分别展示，不相互替代。

  • FR-098：骑手仅能调整本单未取货地点的访问先后，不能新增或删除地点、修改地址或物品，也不能漏取。某站暂时无法取货可以沟通后先去其他站，该站继续保留待取件；最终无法取货、缺件或拒收须联系平台处理，不能虚假确认取件、擅自部分履约或直接完成整单。平台介入时记录问题站、处理结果及已取物品去向和交接凭证，再关闭异常订单；沿用既有介入权限，本次不新增支付退款功能。

方案来源：上述为本项目 2026-09-15 已确认的方式 2。Lalamove 的业务规范仅作为讨论背景；骑手声明、调整记录及具体 App 操作是本项目设计，不标注为已核实的 Lalamove 操作流程。

地图约束依据：Google Routes 中途点限制、Google Maps URL 参数及平台途经点限制。

2026-09-16 确认、2026-09-17 实施：按配送车型计价

  • 用户报价与创建闪送订单均传 vehicleType：1=机车、2=轿车；服务端拒绝缺失或其他数值。
  • 闪送运价按“车型 + 时段”分别配置；报价、创建及待接单改址均以订单车型命中运价，订单保存车型与既有价格快照，后续调价不改变历史订单。
  • 报价、创建及待接单改址调用 Google Routes 时同样传订单车型：机车使用 TWO_WHEELER，轿车使用 DRIVE；返回的路线距离和预计时长随订单保存。地图失败时降级为直线距离并标记 STRAIGHT_LINE，预计时长按机车 25 km/h、轿车 30 km/h 保守估算，向上取整且最少 60 秒；该展示估算不参与计价。
  • 骑手沿用既有 info_user.vehicle_type（1=机车、2=轿车）；待抢列表、待抢详情和接单均要求与订单车型一致。历史骑手、运价和订单均默认机车，保证迁移后既有行为不变。
  • 重量范围与体积/规格说明改为选填；未传时保存 NULL，不参与本期运费计算。物品类别、数量、小费及地址校验保持必填规则。
  • 本期不修改用户 App 界面；后续 App 仅需在报价和创建请求都传相同的 vehicleType。