1. 系统概述
1.1 产品定位
基于微信生态的轻量化餐饮点餐工具，通过"扫桌码即点餐"的模式，替代传统纸质菜单和人工点单，提升门店运营效率，降低人力成本，沉淀用户数据。
1.2 核心目标
- **效率提升**：单桌点餐到下单时间缩短至2分钟内
- **成本降低**：减少每店至少1名点单服务员
- **体验优化**：避免漏单、错单，支持菜品图片直观展示
- **数据沉淀**：获取用户消费数据，为精准营销提供依据
1.3 使用场景
| 场景 | 流程 |
|------|------|
| 堂食 | 入座 → 扫码 → 授权登录 → 浏览菜单 → 加购 → 支付 → 等候上菜 |
| 自提 | 扫码/搜一搜 → 切换自提模式 → 选规格下单 → 到店取餐 |
| 外卖(可选) | LBS定位 → 选择门店 → 下单 → 同城配送 |
2. 架构设计
2.1 整体架构
```
┌─────────────────────────────────────────────────────────────────┐
│ 微信小程序前端 (C端) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 首页/菜单 │ │ 购物车 │ │ 订单管理 │ │
│ │ 扫码点餐 │ │ 结算支付 │ │ 个人中心 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└──────────────────────┬──────────────────────────────────────────┘
│ HTTPS
▼
┌─────────────────────────────────────────────────────────────────┐
│ 后端服务层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ API网关 │ │ 业务逻辑 │ │ 数据访问 │ │
│ │ FastAPI │ │ Service │ │ SQLAlchemy│ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└──────────────────────┬──────────────────────────────────────────┘
│ SQLite/MySQL
▼
┌─────────────────────────────────────────────────────────────────┐
│ 数据存储层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 菜品数据 │ │ 订单数据 │ │ 用户数据 │ │
│ │ 分类数据 │ │ 桌台数据 │ │ 优惠券 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
2.2 技术选型
| 分类 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 语言 | Python | 3.11+ | 后端开发语言 |
| 框架 | FastAPI | 0.100+ | 异步Web框架，高性能 |
| ORM | SQLAlchemy | 2.0+ | 数据库ORM框架 |
| 数据库 | SQLite | 3.40+ | 轻量级嵌入式数据库 |
| 前端 | 微信小程序 | - | 微信生态前端 |
| 认证 | 微信OAuth2 | - | 用户身份认证 |
| 支付 | 微信支付 | - | 订单支付 |
2.3 关键设计
2.3.1 模块划分
| 模块 | 职责 | 状态 |
|------|------|------|
| **menu** | 菜品分类、菜品管理、菜单展示 | ✅ |
| **cart** | 购物车管理、商品加减、库存检查 | ✅ |
| **orders** | 订单创建、支付、状态流转 | ✅ |
| **tables** | 桌台管理、二维码生成、状态管理 | ✅ |
| **admin** | 商家后台、统计数据、订单管理 | ✅ |
| **members** | 会员管理、积分、优惠券 | ✅ |
2.3.2 核心流程图
```mermaid
sequenceDiagram
participant User as 用户
participant App as 微信小程序
participant API as 后端API
participant DB as 数据库
User->>App: 扫描桌码
App->>API: GET /tables/qr-code/{table_no}
API->>DB: 查询桌台信息
DB-->>API: 返回桌台数据
API-->>App: 返回桌台信息
User->>App: 浏览菜单
App->>API: GET /menu/dishes
API->>DB: 查询菜品列表
DB-->>API: 返回菜品数据
API-->>App: 返回菜品列表
User->>App: 选择菜品加入购物车
App->>API: POST /cart
API->>DB: 创建购物车项
DB-->>API: 保存成功
API-->>App: 返回购物车项
User->>App: 点击结算
App->>API: POST /orders
API->>DB: 创建订单，扣减库存
DB-->>API: 保存成功
API-->>App: 返回订单信息
User->>App: 确认支付
App->>API: PUT /orders/{id}/pay
API->>DB: 更新订单状态
DB-->>API: 更新成功
API-->>App: 返回支付结果
```
3. 数据库设计
3.1 实体关系图
```mermaid
erDiagram
CATEGORIES ||--o{ DISHES : contains
DISHES ||--o{ DISH_SPECIFICATIONS : has
DISHES ||--o{ CART_ITEMS : in
DISHES ||--o{ ORDER_ITEMS : in
TABLES ||--o{ ORDERS : places
ORDERS ||--|{ ORDER_ITEMS : contains
COUPONS ||--o{ USER_COUPONS : issued_to
MEMBERS ||--o{ USER_COUPONS : owns
MEMBERS ||--o{ ORDERS : places
```
3.2 核心表结构
3.2.1 dishes（菜品表）
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | INTEGER | PRIMARY KEY | 主键 |
| name | VARCHAR(200) | NOT NULL | 菜品名称 |
| description | TEXT | NULL | 菜品描述 |
| image_url | VARCHAR(500) | NULL | 菜品图片URL |
| original_price | FLOAT | NOT NULL | 原价 |
| price | FLOAT | NOT NULL | 售价 |
| stock | INTEGER | DEFAULT 0 | 库存 |
| monthly_sales | INTEGER | DEFAULT 0 | 月售量 |
| tags | VARCHAR(200) | NULL | 标签 |
| category_id | INTEGER | FOREIGN KEY | 分类ID |
| status | VARCHAR(20) | DEFAULT active | 状态 |
| created_at | DATETIME | DEFAULT now() | 创建时间 |
| updated_at | DATETIME | DEFAULT now() | 更新时间 |
3.2.2 orders（订单表）
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | INTEGER | PRIMARY KEY | 主键 |
| order_no | VARCHAR(50) | UNIQUE | 订单号 |
| openid | VARCHAR(100) | NOT NULL | 用户OpenID |
| table_id | INTEGER | FOREIGN KEY | 桌台ID |
| mode | VARCHAR(20) | NOT NULL | 就餐模式 |
| total_amount | FLOAT | NOT NULL | 总金额 |
| discount_amount | FLOAT | DEFAULT 0 | 优惠金额 |
| actual_amount | FLOAT | NOT NULL | 实付金额 |
| status | VARCHAR(20) | DEFAULT pending_payment | 状态 |
| remark | TEXT | NULL | 备注 |
| paid_at | DATETIME | NULL | 支付时间 |
| completed_at | DATETIME | NULL | 完成时间 |
| created_at | DATETIME | DEFAULT now() | 创建时间 |
3.2.3 tables（桌台表）
| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | INTEGER | PRIMARY KEY | 主键 |
| table_no | VARCHAR(20) | UNIQUE | 桌号 |
| capacity | INTEGER | DEFAULT 2 | 座位数 |
| area | VARCHAR(50) | NULL | 区域 |
| status | VARCHAR(20) | DEFAULT empty | 状态 |
| qr_code_url | VARCHAR(500) | NULL | 二维码URL |
| created_at | DATETIME | DEFAULT now() | 创建时间 |
4. API接口设计
4.1 接口分类
| 模块 | 接口数量 | 说明 |
|------|----------|------|
| menu | 3 | 分类管理、菜品管理 |
| cart | 4 | 购物车增删改查 |
| orders | 4 | 订单CRUD、支付 |
| tables | 6 | 桌台CRUD、状态管理 |
| admin | 6 | 分类、菜品、订单管理 |
4.2 核心接口列表
| API路径 | 方法 | 所属模块 | 说明 |
|---------|------|----------|------|
| `/menu/categories` | GET | menu | 获取分类列表 |
| `/menu/dishes` | GET | menu | 获取菜品列表 |
| `/menu/dishes/{id}` | GET | menu | 获取菜品详情 |
| `/cart` | GET | cart | 获取购物车 |
| `/cart` | POST | cart | 添加到购物车 |
| `/cart/{id}` | PUT | cart | 更新购物车数量 |
| `/orders` | POST | orders | 创建订单 |
| `/orders/{id}` | GET | orders | 获取订单详情 |
| `/orders/{id}/pay` | PUT | orders | 支付订单 |
| `/tables` | POST | tables | 创建桌台 |
| `/tables/{id}/status` | PUT | tables | 更新桌台状态 |
| `/admin/statistics` | GET | admin | 获取统计数据 |
5. 安全性设计
5.1 安全措施
| 措施 | 说明 |
|------|------|
| **参数校验** | 使用Pydantic进行严格的参数校验 |
| **异常处理** | 全局异常处理，统一错误响应格式 |
| **日志记录** | 记录所有请求日志，便于追踪 |
| **库存锁** | 使用数据库事务保证库存一致性 |
| **超时控制** | 订单超时自动取消，释放库存 |
| **CORS配置** | 限制允许的来源域名 |
5.2 订单状态流转
```mermaid
stateDiagram-v2
[*] --> pending_payment : 创建订单
pending_payment --> accepted : 支付成功
pending_payment --> cancelled : 超时/取消
accepted --> preparing : 商家接单
preparing --> ready : 制作完成
ready --> completed : 用户取餐
completed --> [*]
cancelled --> [*]
```
6. 部署与运维
6.1 依赖环境
| 依赖 | 版本 |
|------|------|
| Python | 3.11+ |
| uvicorn | 0.23+ |
| fastapi | 0.100+ |
| sqlalchemy | 2.0+ |
| pydantic-settings | 2.0+ |
| aiosqlite | 0.19+ |
6.2 启动方式
```bash
# 开发环境
cd backend
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
# 生产环境
pip install -r requirements.txt
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```
