foodie-server/specs/004-qr-table-order/spec.md

扫码桌号点餐需求文档

Feature Branch: 004-qr-table-order Created: 2026-04-30 Status: Draft Input: 用户扫码点餐，下单时订单关联餐桌码，商家根据桌号送餐

背景

餐桌码（table_qrcode）功能已实现（spec 002），包含码的创建、管理、扫码入口。本需求完成扫码到下单的最后一环：扫桌码后订单自动关联餐桌码，商家可看到桌号并送餐到对应餐桌。

用户场景与测试

用户故事 1 - 扫档口码点餐下单 (Priority: P1)

用户在摊位餐桌上扫描档口码，APP 进入该摊位菜单页，用户选商品下单，订单自动关联到该餐桌码，商家看到桌号后送餐。

Why this priority: 这是最核心的扫码点餐流程，覆盖最常见场景。

Independent Test: 创建一个档口码，扫码进入菜单，下单后检查订单是否包含正确的 tableId 和 tableNum。

Acceptance Scenarios:

1. Given 一个已启用的档口码（type=0）存在, When 用户扫码进入菜单并下单, Then 订单的 tableId 关联到该码，tableNum 为码记录中的桌号，订单 type=2（堂食）
2. Given 一个已停用的档口码, When 用户扫码后尝试下单, Then 系统拒绝并提示餐桌码已停用

---

用户故事 2 - 扫通用码点餐下单 (Priority: P2)

用户在夜市公共餐桌上扫描通用码，APP 显示该夜市所有摊位，用户选择摊位后进入菜单，下单时订单关联到该公共餐桌码。

Why this priority: 夜市公共餐桌场景，用户需要额外选择摊位步骤，是第二常见的流程。

Independent Test: 创建一个通用码（type=1），扫码进入摊位列表，选择摊位下单，检查订单包含正确的 tableId。

Acceptance Scenarios:

1. Given 一个已启用的通用码（type=1）存在, When 用户扫码、选择摊位、下单, Then 订单的 tableId 关联到该通用码，tableNum 为码记录中的桌号
2. Given 通用码关联的夜市下有多个摊位, When 用户选择不同摊位分别下单, Then 每个订单的 tableId 都指向同一个通用码

---

用户故事 3 - 商家查看堂食订单桌号 (Priority: P3)

商家在订单列表中看到堂食订单的桌号信息，据此送餐到对应餐桌。

Why this priority: 这是商家侧的必要展示，但实现简单（数据已有，只需前端展示）。

Independent Test: 创建一个带桌号的堂食订单，商家端查看该订单，确认桌号正确显示。

Acceptance Scenarios:

1. Given 存在一个带桌号的堂食订单, When 商家查看订单详情, Then 订单中显示桌号（如"A01"）
2. Given 存在一个非堂食订单（外送/自取）, When 商家查看订单详情, Then 订单中桌号字段为空，不显示桌号

---

Edge Cases

• 用户扫了一个已被删除的餐桌码的二维码：下单时应报错"餐桌码不存在"
• 用户扫码后中途退出 APP 再回来：前端丢失 tableId 参数，按普通下单处理（tableId 为空）
• 同一桌多人各自扫码下单：每次独立下单，各自订单都带同一个 tableId，不做合并或冲突检测

需求

功能需求

• FR-001: 下单接口 MUST 接受可选的 tableId 参数，关联到 table_qrcode 记录
• FR-002: 当 tableId 不为空时，系统 MUST 校验该码存在且未停用，不存在或已停用则拒绝下单
• FR-003: 当 tableId 不为空时，系统 MUST 以码记录中的 tableNo 作为订单的 tableNum，忽略前端传入值，确保数据一致性
• FR-004: 当 tableId 为空时，按现有流程正常下单，不做额外校验
• FR-005: 商家端订单详情 MUST 展示堂食订单的桌号信息

关键实体

• PosOrder（订单）: 新增 tableId 字段，关联餐桌码记录。已有 tableNum 字段存储桌号。
• OrderParent（父订单）: 同样新增 tableId 字段，与子订单保持一致。
• TableQrcode（餐桌码）: 已有实体，本需求不改动其结构。

成功标准

可衡量结果

• SC-001: 扫桌码下单后，订单的 tableId 和 tableNum 正确关联到对应餐桌码记录
• SC-002: 非扫码下单（tableId 为空）不受影响，现有流程正常运作
• SC-003: 传入无效或已停用的 tableId 时，系统在 1 秒内返回明确的错误提示
• SC-004: 商家端能正确显示堂食订单的桌号

假设

• 用户必须已下载 APP 并登录才能扫码点餐（不做 H5/游客模式）
• 前端负责在扫码后的整个点餐流程中携带 tableId，直到下单时传入
• 不做餐桌状态管理（不追踪占用/空闲）
• 不做多次加餐/拼单功能
• 不做按桌号分组查询，只在订单上显示桌号
• 现有下单接口（/system/userOrder/createOrder）已处理 tableNum，本需求新增 tableId

不在范围内

• 餐桌占用状态管理
• 多次加餐、拼单、合并订单
• 按桌号分组的订单视图
• 扫码频率限制
• C 端扫码页面开发（仅后端接口改动）