# 餐桌码功能需求文档

## 概述

为夜市/摊位系统增加餐桌码（桌台二维码）功能。摊主和夜市管理员可以创建餐桌码，顾客扫码后进入点餐下单流程。

## 餐桌码类型

| 类型 | 创建者 | 绑定 | 扫码后展示 |
|------|--------|------|-----------|
| 摊位码 | 摊主(user_type=4) | 绑定摊位 | 该摊位的商品列表 → 点餐下单 |
| 公用码 | 夜市管理员(user_type=3) | 绑定夜市 | 所有摊位列表 → 选择摊位 → 该摊位商品 → 点餐下单 |

## 权限模型

- **摊主（user_type=4）**：创建/编辑/删除自己摊位下的餐桌码
- **夜市管理员（user_type=3）**：创建/编辑/删除公用餐桌码 + 查看管理夜市下所有摊位的餐桌码

## 数据库设计

### 新增表：`table_qrcode`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | 主键 |
| table_no | varchar(32) | 桌号（如 A01、B02） |
| type | tinyint | 类型：0=摊位码, 1=公用码 |
| store_id | bigint NULL | 关联摊位ID（摊位码必填，公用码为空） |
| night_market_id | bigint | 夜市ID |
| qr_code | varchar(255) NULL | 二维码内容/图片URL |
| status | tinyint | 启用状态：0=启用, 1=停用 |
| use_status | tinyint | 使用状态：0=空闲, 1=使用中 |
| create_by | varchar(64) | 创建者 |
| create_time | datetime | 创建时间 |
| update_by | varchar(64) | 更新者 |
| update_time | datetime | 更新时间 |
| remark | varchar(255) NULL | 备注 |

### 索引

- `idx_store_id` (store_id) — 按摊位查询
- `idx_night_market_id` (night_market_id) — 按夜市查询
- `idx_type` (type) — 按类型查询

## 后端 API

### 基础 CRUD

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /table-qrcode/add | 创建餐桌码 |
| GET | /table-qrcode/list | 获取餐桌码列表（支持分页、筛选） |
| GET | /table-qrcode/{id} | 获取餐桌码详情 |
| PUT | /table-qrcode/update | 更新餐桌码 |
| DELETE | /table-qrcode/delete/{id} | 删除餐桌码 |
| PUT | /table-qrcode/changeStatus | 启用/停用切换 |

### 二维码

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /table-qrcode/qrcode/{id} | 获取/生成餐桌二维码图片 |
| GET | /table-qrcode/scan | 扫码入口（C端，通过二维码中的参数跳转） |

### 接口参数

**创建餐桌码 POST /table-qrcode/add**

```json
{
  "tableNo": "A01",
  "type": 0,
  "storeId": 100
}
```

- type=0 时 storeId 必填
- type=1 时 storeId 为空，nightMarketId 从当前用户信息获取

**列表查询 GET /table-qrcode/list**

参数：storeId, type, status, useStatus, pageNum, pageSize

- 摊主只能查自己摊位的
- 夜市管理员可查所有（支持按摊位筛选）

### 扫码流程

> **TODO: 待确定** — 扫码后的跳转方案尚未最终确定，目前后端已预留 scan 接口，二维码内容格式后续根据 App 端方案调整。

**候选方案：**

1. **Deep Link（自定义协议）**：二维码内容为 `foodie://scan?type=0&storeId=100&tableId=1`，直接唤起 App 并跳转到对应页面
2. **Universal Link / App Link**：二维码内容为 `https://app.awayqtw.com/scan?tableId=1`，iOS/Android 自动识别并打开 App
3. **H5 中间页跳转**：扫码打开一个 H5 页面，检测是否安装 App，已安装则唤起，未安装则引导下载或直接 H5 浏览
4. **后端重定向**：二维码内容为后端 API 地址，后端 `/scan` 接口根据参数重定向到 App 对应页面

**当前实现：** 方案4（后端重定向），配置项为 `table-qrcode.base-url`

**扫码后行为：**
- type=0（摊位码）：打开该摊位的商品列表页，携带 tableId
- type=1（公用码）：打开摊位选择页（展示该夜市下所有摊位），选择后进入该摊位商品列表页，携带 tableId

订单创建时需携带 tableId，将订单关联到具体餐桌。

## 前端页面

### 商家端（foodie-store）

路径：`E:\QtwCode\foodie\foodie-store`

**新增页面：TableQRCode.vue（餐桌码管理）**

参考原型：https://www.axureshop.com/ys/1888500 的台桌管理模块（不需要预订设置）

页面结构：

1. **筛选区**
   - 摊位筛选下拉（夜市管理员可见）
   - 类型筛选（摊位码/公用码）
   - 启用状态筛选
   - 查询按钮

2. **数据列表**
   - 操作按钮：「新建餐桌码」
   - 表格列：桌号、类型（摊位码/公用码）、所属摊位、使用状态、启用状态、操作（查看二维码、编辑、删除）
   - 启用状态用开关切换

3. **新建/编辑弹窗**
   - 桌号输入
   - 类型选择（摊位码/公用码）
   - 所属摊位选择（摊位码时可选，公用码时隐藏）

4. **二维码查看弹窗**
   - 展示二维码图片
   - 下载按钮

**路由注册**：在 router/index.js 添加 `/table-qrcode` 路由

**API 模块**：新增 `src/api/tableQrcode.js`

## 不在范围内

- 预订设置功能
- C端（顾客端）点餐页面（仅后端提供扫码跳转入口）
- 桌型管理（4人桌、8人桌等）
- 桌位位置管理（大厅、包间等）