# Implementation Plan: Table QR Code (餐桌码)

**Branch**: `master` | **Date**: 2026-04-29 | **Spec**: `specs/002-table-qrcode/spec.md`

## Summary

为夜市/摊位系统增加餐桌码功能，支持两种类型的二维码：摊位码（绑定摊位，扫码展示该摊位商品）和公用码（绑定夜市，扫码展示所有摊位）。后端基于 Spring Boot + MyBatis Plus，前端基于 Vue 2 + Element UI。

## Technical Context

**Language/Version**: Java 21
**Primary Dependencies**: Spring Boot 2.x, MyBatis Plus 3.0.3, ZXing 3.5.2 (新增)
**Storage**: MySQL 8.2.0
**Testing**: 手动测试 (项目无自动化测试框架)
**Target Platform**: Linux server
**Project Type**: Web service (后端) + Web app (前端商家端)
**Performance Goals**: 常规 REST API 性能
**Constraints**: 遵循现有 RuoYi 框架模式
**Scale/Scope**: 夜市场景，预计每个摊位 1-20 张餐桌，每个夜市 10-100 个摊位

## Constitution Check

Constitution 文件为模板状态（无实际 gates），跳过 gate 检查。

## Project Structure

### Documentation (this feature)

```text
specs/002-table-qrcode/
├── spec.md              # 需求文档
├── plan.md              # 本文件 - 实现计划
├── research.md          # 技术调研
├── data-model.md        # 数据模型
├── quickstart.md        # 快速开始
└── contracts/
    └── api.md           # API 接口契约
```

### Source Code (backend - foodie_server)

```text
ruoyi-system/src/main/java/com/ruoyi/system/
├── domain/
│   └── TableQrcode.java                    # 实体类
├── mapper/
│   └── TableQrcodeMapper.java              # Mapper 接口
└── service/
    ├── ITableQrcodeService.java            # Service 接口
    └── impl/
        └── TableQrcodeServiceImpl.java     # Service 实现

ruoyi-system/src/main/resources/mapper/chanting/
└── TableQrcodeMapper.xml                   # Mapper XML

ruoyi-admin/src/main/java/com/ruoyi/app/
└── tableqrcode/
    └── TableQrcodeController.java          # Controller

ruoyi-admin/pom.xml                         # 添加 ZXing 依赖
```

### Source Code (frontend - foodie-store)

```text
foodie-store/src/
├── api/
│   └── tableQrcode.js                      # API 模块
├── views/
│   └── TableQRCode.vue                     # 餐桌码管理页面
└── router/
    └── index.js                            # 添加路由
```

**Structure Decision**: 遵循现有项目结构，后端实体/mapper/service 放在 ruoyi-system 模块，Controller 放在 ruoyi-admin 模块的 app 包下，前端在 foodie-store 项目中新增页面。

## Implementation Phases

### Phase 1: Database & Backend Foundation
1. 创建数据库表 `table_qrcode`
2. 创建实体类 `TableQrcode`
3. 创建 Mapper 接口和 XML
4. 创建 Service 接口和实现

### Phase 2: Backend API
5. 添加 ZXing 依赖到 pom.xml
6. 创建 Controller（CRUD + 二维码生成）
7. 权限控制（摊主 vs 夜市管理员）

### Phase 3: Frontend
8. 创建 API 模块 `tableQrcode.js`
9. 创建管理页面 `TableQRCode.vue`
10. 注册路由

### 增量修正：列表返回 storeName（2026-08-24）

`TableQrcode` 已有非数据库字段 `storeName`，但 Controller 当前通过 MyBatis-Plus 通用 `list` 查询，未执行 `TableQrcodeMapper.xml` 中的门店关联查询，导致列表字段为空。为保持普通商家多门店 `IN` 权限条件及现有筛选逻辑不变，继续使用当前餐桌码查询；查询完成后汇总非空 `storeId`，通过 `IPosStoreService.listByIds` 一次取得门店，再按 ID 回填 `storeName`。公用码无 `storeId` 时不回填。

验证采用 Controller 单元测试：构造多个餐桌码及门店，断言响应中的门店码含正确 `storeName`、公用码为 `null`，并确认门店采用单次批量查询。
