foodie-server/specs/028-flash-delivery-push/spec.md

Feature Specification: 闪送订单状态变更消息推送

Feature Branch: 028-flash-delivery-push

Created: 2026-09-17

Status: Draft

Input: User description: "闪送订单状态变更消息推送：骑手抢单、已取件、已送达推送给用户端；用户/平台取消推送给骑手端。2026-09-18 追加：立即闪送单创建后通知骑手；预约闪送单创建时不通知，进入可抢单时间窗口后再开放展示并通知；外卖和闪送使用不同的新单文案。加小费不推送。"

User Scenarios & Testing (mandatory)

User Story 1 - 寄件用户收到骑手接单通知 (Priority: P1)

寄件用户下单后处于等待状态，骑手抢单成功的瞬间，用户收到一条推送，告知订单已被骑手接单、骑手正在前来取件。

Why this priority: 用户下单后最焦虑的时段是"有没有人接单"；接单通知是整个推送体系里价值最高的单条消息，没有它用户只能反复刷新订单页。

Independent Test: 创建一笔待接单的闪送订单，骑手账号执行抢单，验证寄件用户收到"骑手已接单"推送。

Acceptance Scenarios:

1. Given 订单状态为 WAITING_ACCEPTANCE，When 骑手抢单成功（状态转为 ACCEPTED），Then 寄件用户在短时间内收到推送，内容表明骑手已接单并包含订单标识。
2. Given 抢单因并发失败（订单已被他人抢走或已取消），When 抢单请求落空，Then 不产生任何推送。

---

User Story 2 - 寄件用户收到取件与送达通知 (Priority: P1)

履约中段，骑手确认取件、确认送达两个节点，寄件用户分别收到推送，掌握物品在途与签收进度。

Why this priority: 与接单通知共同构成完整的履约进度感知；送达通知同时提示用户可去确认收货。

Independent Test: 对一笔已接单订单依次执行取件（附凭证）、送达（附凭证），验证寄件用户先后收到两条对应推送。

Acceptance Scenarios:

1. Given 订单状态为 ACCEPTED，When 骑手确认取件成功（状态转为 PICKED_UP），Then 寄件用户收到"骑手已取件"推送。
2. Given 订单状态为 PICKED_UP，When 骑手确认送达成功（状态转为 DELIVERED），Then 寄件用户收到"已送达"推送。
3. Given 取件或送达操作因校验失败未改变订单状态，When 操作报错返回，Then 不产生推送。

---

User Story 3 - 骑手收到订单取消通知 (Priority: P2)

订单被取消时，已接单的骑手收到推送，及时停止履约，避免白跑。

Why this priority: 取消是低频事件，但漏通知会导致骑手空跑、产生纠纷；相比履约进度通知优先级略低。

Independent Test: 对一笔已接单订单分别走用户取消、平台取消两条路径，验证骑手收到取消推送；对未接单订单执行取消，验证不产生骑手推送。

Acceptance Scenarios:

1. Given 订单已被骑手接单（ACCEPTED/PICKED_UP），When 寄件用户取消订单成功（状态转为 CANCELLED），Then 该骑手收到"订单已取消"推送，内容含订单标识。
2. Given 订单已被骑手接单，When 平台取消订单成功，Then 该骑手收到取消推送。
3. Given 订单尚未被任何骑手接单（WAITING_ACCEPTANCE，含过期预约单自动取消），When 订单被取消，Then 不产生骑手推送（无推送对象）。
4. Given 用户取消请求因状态校验失败，When 取消未生效，Then 不产生推送。

---

User Story 4 - 骑手及时收到可抢闪送新单通知 (Priority: P1)

符合配送资格且在线的骑手在闪送订单真正可抢时收到新单推送。立即单创建后直接开放；预约单创建时隐藏，进入预约取件时间窗后再开放并推送。

Why this priority: 新单通知决定骑手是否能及时发现任务；预约单必须保证“列表可见”和“推送触发”使用同一个原子开放动作，避免骑手先看到订单、稍后才收到推送。

Independent Test: 分别创建立即单和预约单，验证立即单 isDisplay=true 且创建后推送；预约单初始 isDisplay=false 且不推送，在时间窗内由任务原子切为 true 后只推送一次。

Acceptance Scenarios:

1. Given 创建一笔立即闪送单，When 订单保存事务提交，Then 订单立即可见，并向符合配送类型、车型、距离和接单互斥规则的在线骑手发送“有新的闪送订单”。
2. Given 创建一笔尚未进入时间窗的预约闪送单，When 创建事务提交，Then isDisplay=false，骑手列表不可见且不产生新单推送。
3. Given 预约单进入 scheduledPickupStartAt <= 当前时间 < scheduledPickupEndAt，When 独立任务执行，Then 以条件更新原子切换 isDisplay=false -> true，同一次成功切换后发送新单推送。
4. Given 多个任务实例或连续执行同时处理同一预约单，When 竞争开放资格，Then 只有条件更新成功的一次触发推送，其他执行不重复发送。
5. Given 外卖单与闪送单分别发布，When 骑手收到新单推送，Then 文案分别为“有新的外卖订单”和“有新的闪送订单”。

Edge Cases

• 接收方没有有效的设备推送标识（未登录过 App / 标识为空）时：跳过云端推送，但消息记录仍正常生成，且不影响订单操作结果。
• 推送服务调用失败或超时：只记录日志，不重试阻断，订单状态流转结果不受影响。
• 接收方语言设置为越南语/繁中/英语/简中之外或未设置：按平台默认语言回落（与现有订单推送行为一致）。
• 骑手抢单与用户取消并发（一方成功另一方必然失败）：只对实际改变了订单状态的一方产生推送。
• 平台连续取消多笔订单：每笔独立推送，互不影响。
• 预约单进入窗口后的任务存在亚秒级调度延迟：在 isDisplay 原子切换前订单保持不可见，因此不会出现先看到订单、后收到推送的一分钟级错位。

Requirements (mandatory)

Functional Requirements

• FR-001: 骑手抢单成功（WAITING_ACCEPTANCE → ACCEPTED）后，系统 MUST 向寄件用户发送"骑手已接单"推送通知。
• FR-002: 骑手确认取件成功（ACCEPTED → PICKED_UP）后，系统 MUST 向寄件用户发送"骑手已取件"推送通知。
• FR-003: 骑手确认送达成功（PICKED_UP → DELIVERED）后，系统 MUST 向寄件用户发送"已送达"推送通知。
• FR-004: 寄件用户取消订单成功（状态转为 CANCELLED）且订单已有接单骑手时，系统 MUST 向该骑手发送"订单已取消"推送通知。
• FR-005: 平台取消订单成功且订单已有接单骑手时，系统 MUST 向该骑手发送"订单已取消"推送通知。
• FR-006: 所有推送文案 MUST 支持四种语言（vi、zh、tw、en），按接收方用户的语言设置呈现。
• FR-007: 每条推送内容 MUST 包含订单标识（订单号），使接收方无需打开 App 搜索即可定位订单。
• FR-008: 每条推送 MUST 同步生成消息记录（复用现有消息中心机制），用户/骑手可在消息列表中回看。
• FR-009: 推送环节的任何失败（无设备标识、推送服务异常）MUST NOT 影响订单状态流转本身，也 MUST NOT 向操作方返回错误。
• FR-010: 以下事件明确不推送：加小费不产生推送；超时自动完成（DELIVERED → COMPLETED）不推送；过期预约单自动取消不推送；预约单创建时不推送。
• FR-011: 推送 MUST 仅在对应状态变更实际成功后触发；操作失败或未改变状态时不得产生推送。
• FR-012: 立即闪送单创建时 isDisplay MUST 为 true，并在事务提交后触发一次骑手新单通知。
• FR-013: 预约闪送单创建时 isDisplay MUST 为 false，且在开放前不得出现在骑手可抢列表、详情或抢单接口中。
• FR-014: 预约单 MUST 仅在 scheduledPickupStartAt <= 当前时间 < scheduledPickupEndAt 时通过条件更新原子切换 isDisplay=false -> true；仅更新成功者有资格发送通知。
• FR-015: 预约开放任务 MUST 使用独立任务类每秒执行，不与自动完成或预约过期取消任务耦合。
• FR-016: 新单候选骑手 MUST 在线、具备 FLASH 配送类型、车型匹配、位于配置距离内，并遵守普通/加急闪送现有接单互斥规则。
• FR-017: 外卖和闪送的新单推送 MUST 使用不同文案，分别为 no.message.push.new.food.order 与 no.message.push.new.flash.order。

Key Entities (include if feature involves data)

• 推送通知（Push Notification）: 一次状态变更事件产生的一条通知，属性包括接收方（寄件用户或接单骑手）、事件类型（接单/取件/送达/取消）、标题与正文（按语言）、关联订单标识；复用现有消息记录实体落地，不新增独立数据模型。

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 任一在推送范围内的事件（抢单、取件、送达、取消）成功发生后，接收方在 10 秒内收到推送（推送服务正常的前提下）。
• SC-002: 四种语言设置的用户各抽检一批推送，文案语言与用户设置一致的比例为 100%。
• SC-003: 抽检的全部推送均含订单号，接收方可凭推送内容直接定位订单，达标率 100%。
• SC-004: 推送服务整体不可用时，抢单/取件/送达/取消接口的成功率与推送上线前持平（推送故障零传导）。
• SC-005: 预约单进入可抢窗口后 2 秒内开放展示并开始异步推送，且同一订单开放通知最多触发一次。

Assumptions

• 复用项目现有推送通道（App 端云函数推送 + 消息入库），不新建推送基础设施，不新增 Android 通道。
• 推送在订单状态变更成功后异步触发，不放在订单操作的事务内。
• 平台取消按需求仅推送骑手端；寄件用户通过订单列表感知取消结果，如需同时通知用户可后续追加需求。
• 超时自动完成、过期预约单自动取消、预约单创建和加小费均不推送（FR-010）；立即单创建和预约单开放属于新单通知触发点。
• 推送点击后的客户端跳转（payload 路由到闪送订单详情页）由客户端处理；服务端只保证推送携带订单标识与业务类型。
• 报文文案沿用现有订单推送的文案风格（简短状态描述 + 订单号后缀）。