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

功能规格：闪送配送服务

功能标识：024-flash-delivery

创建日期：2026-08-31

状态：补充原型增量已实现并通过定向测试和模块构建；数据库迁移环境集成验证待执行

输入：基于蓝湖“闪送”分组 7 个设计页面及 2026-08-24 用户端/骑手端补充原型，实现帮送、帮取、加急送的完整非支付业务闭环，包括共享地址簿、路线报价、包裹信息、立即/预约配送、可选 PIN 交付、创建订单、骑手主动抢单、取件、送达、用户签收、平台配置与介入。

用户场景与测试

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

用户选择帮送、帮取或加急送，填写取件与收件地址后获取服务端报价，并发布一笔等待骑手接单的闪送订单。

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

独立测试：为同一组取件和收件坐标分别选择三种服务，验证系统按当前启用配置返回报价，并在创建订单时重新计算价格、保存地址与计价快照且进入待接单状态。

验收场景：

1. 假如 按起步价、实际超距、预计时长和尖峰倍率计算后的金额低于最低价，当 用户请求报价，那么 系统返回对应服务类型的最低价。
2. 假如 路线距离超过起步距离但不足下一个完整公里，当 用户请求报价，那么 超出部分按实际小数公里计价，不向上取整。
3. 假如 地图路线服务正常，当 用户请求报价，那么 系统使用路线距离并标记距离来源为路线服务。
4. 假如 地图路线服务超时或失败，当 用户请求报价，那么 系统使用经纬度直线距离降级报价并明确标记距离来源。
5. 假如 客户端提交伪造金额或距离，当 用户创建订单，那么 系统忽略客户端金额与距离并在服务端重新报价。
6. 假如 同一用户以相同客户端请求号重复创建订单，当 请求被重复处理，那么 系统返回同一订单且不产生重复订单。
7. 假如 用户选择预约配送，当 创建订单，那么 系统保存 30 分钟取件时段，预约开始前订单不进入骑手可抢列表。
8. 假如 路线距离超过 40 公里，当 用户报价或创建订单，那么 系统拒绝请求。

---

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

骑手在闪送待接单列表中查看可抢订单，主动抢单后依次上传取件和送达图片，完成实际配送。

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

独立测试：创建一笔待接单订单，由两个骑手并发抢单，验证只有一个骑手成功；成功骑手上传取件和送达图片后，订单依次进入已取件和已送达状态。

验收场景：

1. 假如 同时存在普通和加急待接订单，当 骑手查询闪送列表，那么 加急订单优先展示，其余订单按发布时间排序。
2. 假如 两名骑手同时抢同一订单，当 两个请求并发到达，那么 只有一名骑手成功，另一名收到订单已被接走的业务结果。
3. 假如 骑手尚未抢到订单，当 其尝试确认取件或送达，那么 系统拒绝操作且不泄露完整联系方式。
4. 假如 已接单骑手未提交取件图片，当 其确认取件，那么 系统拒绝状态变更。
5. 假如 已取件骑手未提交送达图片，当 其确认送达，那么 系统拒绝状态变更。
6. 假如 图片要求已满足，当 订单骑手按顺序确认取件和送达，那么 系统保存凭证、操作人和时间并完成对应状态变更。
7. 假如 订单启用 PIN 交付，当 骑手提交错误 PIN，那么 系统拒绝送达且不保存送达图片或改变状态。
8. 假如 订单启用 PIN 交付，当 骑手提交正确 PIN 和送达图片，那么 系统验证 PIN 后进入已送达状态。
9. 假如 骑手尚未接单，当 查看列表或详情，那么 仅返回包裹、时段、路线区域和报价等安全摘要，不返回完整门牌、联系人、电话、PIN 或内部字段。

---

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

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

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

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

验收场景：

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

---

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

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

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

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

验收场景：

1. 假如 订单处于待接单或已接单，当 订单用户取消，那么 订单进入已取消状态并记录原因。
2. 假如 订单已取件，当 订单用户尝试取消，那么 系统拒绝并要求平台介入。
3. 假如 骑手已确认送达，当 订单用户确认签收，那么 订单进入已完成状态。
4. 假如 骑手送达后用户 24 小时未确认，当 自动完成任务执行，那么 订单进入已完成状态并记录自动操作日志。
5. 假如 用户访问其他用户的订单，当 其查询详情、取消或签收，那么 系统拒绝访问。

---

用户故事 5：平台管理计价配置并介入异常订单（优先级：P2）

平台管理员维护三种闪送服务的计价配置，查询全部闪送订单，并在取件后的异常场景中取消或完成订单。

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

独立测试：管理员修改加急送配置后创建新报价，验证新报价使用新版本而历史订单保持原快照；随后对已取件订单执行平台取消并检查状态日志。

验收场景：

1. 假如 管理员修改某一服务类型的计价配置，当 新请求报价，那么 新报价使用新配置且已创建订单价格不变。
2. 假如 配置值为负数、零或服务类型非法，当 管理员提交修改，那么 系统拒绝保存。
3. 假如 普通用户或骑手调用平台配置或介入接口，当 权限校验执行，那么 系统拒绝操作。
4. 假如 订单已取件但发生异常，当 有权限的管理员取消订单，那么 系统允许取消并记录管理员、原因和时间。
5. 假如 订单已送达但用户无法确认，当 有权限的管理员确认完成，那么 系统完成订单并记录平台操作日志。

边界情况

• 取件地址和收件地址相同或坐标相同，不允许创建订单。
• 地址缺少联系人、联系电话、完整地址或有效经纬度时，不允许用于报价和创建订单。
• 经纬度超出合法范围时拒绝请求，不调用地图服务。
• 对应服务类型没有启用计价配置时，不允许报价或创建订单。
• 地图路线结果缺少有效距离时按路线失败处理并降级为直线距离。
• 创建订单时当前配置与先前报价时不同，以创建时服务端重新计算结果为准。
• 待接单列表仅返回待接单订单；已取消或已被抢走的订单不得继续出现在新查询结果中。
• 待抢订单列表隐藏完整电话和门牌信息；骑手抢单成功后才能读取配送所需的完整快照。
• 骑手第一版不能自行放弃已抢订单，需要平台介入处理。
• 已完成和已取消为终态，不允许再次变更。
• 自动完成任务与用户确认、平台完成并发时，只允许一个状态变更成功且不得重复写入完成副作用。

需求

功能需求

• FR-001：系统必须提供帮送、帮取和加急送三种服务类型。
• FR-002：帮取只承担取件配送，不包含代购、垫付或商品金额。
• FR-003：三种服务必须使用同一订单履约状态机；加急送仅在排序和计价上体现优先级。
• FR-004：系统必须按服务类型维护基础价、最低价、包含距离、每公里价格、每分钟价格和尖峰倍率，并保存配置版本与修改记录。
• FR-005：报价必须按“基础价 + 超出包含距离的实际公里费用 + 时长费用”计算小计，再应用尖峰倍率并保证结果不低于最低价。
• FR-006：距离、时长、尖峰和总金额必须返回可展示的费用明细，所有金额最终保留两位小数。
• FR-007：系统必须优先使用地图路线距离，地图失败时使用经纬度直线距离并向客户端返回距离来源。
• FR-008：地图密钥必须从服务端配置读取，不得返回客户端或写入业务日志。
• FR-009：创建订单时必须由服务端重新计算距离和价格，并保存地址、路线、金额和计价配置快照。
• FR-010：系统必须使用客户端请求号保证同一用户的订单创建幂等。
• FR-011：闪送订单不得复用餐饮订单或打车订单数据模型。
• FR-012：订单必须保存包裹类别和机车可载重量档，重量档为 SMALL（不超过 5kg）、MEDIUM（不超过 12kg）或 LARGE（不超过 20kg）；不保存精确重量或件数。
• FR-013：订单必须支持用户备注，但备注不参与计价。
• FR-014：骑手必须通过独立闪送待接单列表主动抢单，第一阶段不实现自动派单。
• FR-015：待接单列表必须按加急优先、创建时间次优先的顺序返回。
• 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：骑手在抢单前只能看到履约判断所需的脱敏信息，抢单成功后才能查看完整联系方式和门牌信息。
• 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：用户和骑手列表必须支持页面状态分组并在服务端完成分页，禁止先分页后由客户端过滤多个底层状态。
• FR-046：用户和骑手详情必须使用角色专用响应视图，不得直接序列化订单实体、客户端幂等号、内部用户 ID 或计价审计字段。
• FR-047：骑手接单后，用户可读取骑手昵称、头像和评分等公开摘要；实时位置只在配送进行状态向订单用户返回。
• FR-048：路线距离不得超过 40 公里；超过限制时报价和创建均拒绝。

关键实体

• 闪送订单：用户发布的取件配送任务，持有地址、路线、价格、服务类型、履约状态和关键时间快照。
• 计价配置：某一服务类型当前启用的起步价、最低价、起步距离、每公里价格、每分钟价格、尖峰倍率及版本信息。
• 配送凭证：用户下单时的可选寄件图片，以及骑手取件或送达时提交的必填图片记录。
• 订单状态日志：记录订单每次有效状态变化的操作审计信息。
• 共享地址：属于单一用户、可供闪送和现有收货业务共同使用的联系人与地点信息。

成功标准

• SC-001：三种服务的最低价、实际超距小数公里、路线时长、尖峰倍率和加急配置报价测试全部通过。
• SC-002：地图路线成功和失败降级场景均能在一次请求内返回可用报价，并准确标记距离来源。
• SC-003：至少 20 个并发抢单请求针对同一订单时，数据库中恰好只有一名骑手成功绑定。
• SC-004：跨用户地址和订单的详情、修改、删除、置顶、取消及签收测试拦截率达到 100%。
• SC-005：缺少取件或送达图片的状态变更请求拦截率达到 100%。
• SC-006：所有允许和禁止的状态流转均有自动化测试覆盖，终态订单不能再次改变状态。
• SC-007：送达超过 24 小时的订单能够自动完成，且并发确认不会产生重复状态日志或重复副作用。
• SC-008：修改计价配置后，新订单使用新版本，历史订单保存的价格与配置快照保持不变。
• SC-009：所有新增用户可见业务错误均能通过项目支持的语言资源解析，不出现硬编码单一语言结果。

假设

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

非目标

• 不接入支付网关、付款、退款、取消费、退回费、结算或骑手收入分账。
• 不实现代购、垫付款、商品金额、精确重量、件数或禁寄品电子确认；禁运品、货值和尺寸限制由前端展示规则说明，后端只校验本期明确的重量档和最大路线距离。
• 不实现自动派单、抢单推送筛选、骑手在线状态计算或接单时间预测。
• 不修改餐饮订单 pos_order 或打车订单 taxi_order 的业务语义。
• 不在本功能中实现前端页面；本轮交付后端 API、数据库 SQL、自动化测试和 spec-kit 文档。