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: "闪送订单状态变更消息推送：骑手抢单、已取件、已送达推送给用户端；用户/平台取消推送给骑手端。新任务发布（待抢单）不推送，加小费不推送。"

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 不产生推送。

Edge Cases

• 接收方没有有效的设备推送标识（未登录过 App / 标识为空）时：跳过云端推送，但消息记录仍正常生成，且不影响订单操作结果。
• 推送服务调用失败或超时：只记录日志，不重试阻断，订单状态流转结果不受影响。
• 接收方语言设置为越南语/繁中/英语/简中之外或未设置：按平台默认语言回落（与现有订单推送行为一致）。
• 骑手抢单与用户取消并发（一方成功另一方必然失败）：只对实际改变了订单状态的一方产生推送。
• 平台连续取消多笔订单：每笔独立推送，互不影响。

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 仅在对应状态变更实际成功后触发；操作失败或未改变状态时不得产生推送。

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: 推送服务整体不可用时，抢单/取件/送达/取消接口的成功率与推送上线前持平（推送故障零传导）。

Assumptions

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