# 纯瘾大 · 酒吧点单小程序 — 提审文档 v2.4

> **日期**: 2026-06-08 | **版本**: v2.8 (R19修复版)
> **用途**: 测试组验收 / 运维组部署审核
> **项目位置**: `/Users/mac/work/mnmp/code/`

---

## 一、项目概述

| 项 | 内容 |
|----|------|
| 项目名称 | 纯瘾大 · 酒吧点单小程序 |
| 品牌标识 | 🍸 纯瘾大 |
| 业务场景 | 酒吧顾客扫码点单 + 调酒师接单管理 + 双向聊天 |
| 角色 | 顾客端（小程序） / 员工端（后台） |

---

## 二、技术栈

| 层 | 技术 | 版本 |
|----|------|------|
| 前端框架 | uni-app (Vue 3) | HBuilderX / CLI |
| 编译目标 | 微信小程序 (mp-weixin) | - |
| 后端框架 | ThinkPHP | 8.1 |
| PHP | PHP | 8.2 |
| 数据库 | MariaDB | 10.4.12 @ 47.94.89.42:3306 |
| 数据库名 | drink | 账号 drink_app |
| 实时通信 | HTTP 轮询 (5s/10s/15s) | - |
| UI 设计 | 深色酒吧主题 | 黑底金橙配色 |

---

## 三、工程结构

```
code/
├── server/                          # ThinkPHP 8 后端
│   ├── app/
│   │   ├── controller/              # Card / Menu / Order / Message / Staff
│   │   ├── model/                   # Product / Order / OrderItem / Message / Staff
│   │   ├── service/                 # CardService / OrderService
│   │   └── middleware/              # StaffAuth (HMAC-SHA256 Token)
│   ├── config/                      # database / app / middleware
│   ├── route/app.php                # 16条API路由
│   └── .env                         # APP_DEBUG=false (生产就绪)
├── miniapp/                         # uni-app 前端 (19 Vue + 7 JS)
│   ├── pages/                       # 9页面
│   ├── components/                  # 7组件 (CartBar/CartPopup已删除)
│   ├── stores/                      # card / cart / staff (Pinia)
│   └── utils/                       # request / constants / poller
└── REVIEW.md                        # 本文档
```

---

## 四、页面清单 (9页)

| # | 页面 | 路由 | 关键交互 |
|---|------|------|---------|
| 1 | 落地页+号码牌 | `pages/index/index` | 按钮触发弹窗，1997→员工登录，底部「🔐 员工入口」 |
| 2 | 点单主页 | `pages/menu/menu` | Banner+分类Tab+单列商品+出餐铃+购物车弹层(点击遮罩关闭) |
| 3 | 确认下单 | `pages/confirm/confirm` | 清单+预设标签+备注+摇铃下单 |
| 4 | 我的订单 | `pages/orders/orders` | 催单(传cardNo)+聊天入口(未读红点徽章)+15s轮询 |
| 5 | 顾客聊天 | `pages/chat/chat` | 气泡+5s轮询+未读计数(viewer=customer) |
| 6 | 员工登录 | `pages/staff/login` | type=password，无硬编码凭证，reLaunch进看板 |
| 7 | 订单看板 | `pages/staff/board` | 3Tab(含计数徽章)+拒单+详情+聊天+10s轮询 |
| 8 | 订单详情 | `pages/staff/detail` | 路由传参id，订单信息+完整配方 |
| 9 | 员工聊天 | `pages/staff/chat` | 气泡+5s轮询+未读计数(viewer=staff) |

---

## 五、数据库 (5表)

| 表 | 说明 | 连接 |
|----|------|------|
| products | 20款酒水，6分类，含完整配方 | 47.94.89.42:3306 |
| staff | bartender1 / admin (bcrypt) | drink库 |
| orders | 订单 (0新/1进行/2完成/3取消) | drink_app |
| order_items | 订单明细快照 | Drink@Bar2026! |
| messages | 聊天消息 | - |

---

## 六、API 接口 (16个)

### 6.1 顾客端 (10个)

| # | 方法 | 路径 | 说明 |
|---|------|------|------|
| 1 | POST | `api/card/generate` | 生成[A-Z]NNN号码牌 |
| 2 | GET | `api/card/check` | 校验号码牌格式 |
| 3 | GET | `api/menu/categories` | 6分类列表 |
| 4 | GET | `api/menu/products` | 按分类获取商品(无recipe) |
| 5 | GET | `api/menu/product` | 商品详情 |
| 6 | POST | `api/order/submit` | 下单(qty1-99+事务) |
| 7 | GET | `api/order/list` | 我的订单 |
| 8 | POST | `api/order/remind` | 催单(归属+30s冷却+5次上限) |
| 9 | GET | `api/message/list` | 聊天记录(since增量) |
| 10 | POST | `api/message/send` | 发消息(枚举+500字+Vue模板转义) |

### 6.2 员工端 (6个，需Token)

| # | 方法 | 路径 | 说明 |
|---|------|------|------|
| 11 | POST | `api/staff/login` | 登录(HMAC-SHA256 Token/24h) |
| 12 | GET | `api/staff/orders` | 看板列表(?include_cancel=1含取消) |
| 13 | GET | `api/staff/order` | 详情(含完整recipe) |
| 14 | POST | `api/staff/order/confirm` | 接单(status:0→1) |
| 15 | POST | `api/staff/order/done` | 结单(status:1→2+号码释放) |
| 16 | POST | `api/staff/order/cancel` | 拒单(status:0→3) |

---

## 七、完整修复记录

### R1→R2 (后端安全)

| Bug | 说明 | 状态 |
|-----|------|------|
| BUG-01 | 催单增加cardNo归属+30s冷却+5次上限 | ✅ |
| BUG-02 | confirm/done/cancel状态机前置校验 | ✅ |
| BUG-03 | 消息发送长度/枚举/XSS三重校验 | ✅ |
| BUG-04 | 下单qty正整数1-99校验 | ✅ |

### R2→R3 (前端+配置)

| Bug | 说明 | 状态 |
|-----|------|------|
| BUG-05 | APP_DEBUG=false | ✅ |
| R3-01 | CartPopup去除所有¥价格 | ✅ |
| R3-02 | 员工详情页id路由传参 | ✅ |
| R3-03 | 员工登录页去硬编码凭证 | ✅ |
| R3-04 | 聊天气泡方向viewer=staff修正 | ✅ |
| R3-06 | CardModal死代码删除 | ✅ |
| R3-07 | request.js移除X-Card-No | ✅ |

### R4 (死代码清理)

| 改动 | 说明 | 状态 |
|------|------|------|
| CartBar.vue | 未使用组件删除 | ✅ |
| CartPopup.vue | 未使用组件删除 | ✅ |
| cart.js | 移除totalAmount(price冗余逻辑) | ✅ |

### R5 (功能/UI深度修复)

| Bug | 说明 | 状态 |
|-----|------|------|
| R5-01 | navigationStyle:custom 关闭系统导航栏 | ✅ |
| R5-02 | uni.scss 全局 box-sizing:border-box | ✅ |
| R5-03 | Message.php 移除htmlspecialchars(防双重转义) | ✅ |
| R5-04 | index.vue clearTimeout防双重跳转 | ✅ |
| R5-05 | board.vue 增加拒单按钮+API | ✅ |
| R5-06 | 时间格式改为Y-m-d H:i:s | ✅ |
| R5-07 | 聊天轮询未读计数+徽章显示 | ✅ |
| R5-08 | ProductCard改为单列横向布局 | ✅ |
| R5-09 | 号码牌弹窗padding+white-space优化 | ✅ |
| R5-10 | 消息列表返回原始文本 | ✅ |

### R5 事后修复

| 问题 | 说明 | 状态 |
|------|------|------|
| WXSS * 通配符报错 | 改用具体元素列表 | ✅ |
| 页头顶天 | page级padding-top:44px适配状态栏 | ✅ |
| 登录input类型 | password→type="password" | ✅ |
| 拒单显示 | Staff.php include_cancel逻辑 | ✅ |
| 已完成计数 | 3个Tab均显示计数徽章 | ✅ |
| 员工看板健壮性 | Promise.all并行+空值兜底 | ✅ |

---

## 八、部署指南

### 后端
```bash
cd code/server
# .env: DB_HOST=47.94.89.42 DB_NAME=drink APP_DEBUG=false
php think run -p 8080
```

### 前端
```bash
cd code/miniapp
npm install
npm run build:mp-weixin
# 微信开发者工具打开 dist/build/mp-weixin
```

### 关键配置

| 配置 | 文件 | 值 |
|------|------|-----|
| API Base | `miniapp/utils/constants.js` | `http://127.0.0.1:8080` |
| Token密钥 | `server/config/app.php` | `app_secret` |
| 轮询间隔 | `miniapp/utils/poller.js` | 聊天5s / 看板10s / 订单15s |
| 导航栏 | `pages.json` | `navigationStyle:custom` + page padding |

---

## 九、验收检查清单

- [x] 16个API全部通过
- [x] 员工Token拦截 (401)
- [x] 顾客product不含recipe，staff/order含recipe
- [x] 催单归属+冷却+上限
- [x] 状态机非法转换拒绝
- [x] 消息存储原始文本，Vue模板转义防XSS
- [x] 全局无¥价格符号
- [x] APP_DEBUG=false
- [x] 员工登录无硬编码凭证
- [x] 详情页路由传参
- [x] 聊天气泡方向(viewer)正确
- [x] 拒单后订单显示在已完成Tab(含状态标签)
- [x] 3个Tab均含计数徽章
- [x] 商品卡片单列横向布局
- [x] 购物车点击遮罩关闭
- [x] 出餐铃动画完整
- [x] 时间格式Y-m-d H:i:s
- [x] 聊天未读徽章显示
- [x] 页面顶部状态栏适配
- [ ] uni-app微信小程序编译
- [ ] 真机兼容性测试

---

*文档版本 v2.4 | 2026-06-08 | R5修复版*