# imx6ull点菜系统 **Repository Path**: wj0921/imx6ull-ordering-system ## Basic Information - **Project Name**: imx6ull点菜系统 - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-07-06 - **Last Updated**: 2026-07-08 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # i.MX6ULL 点餐终端系统 > **AI 辅助开发提示**：使用 Claude Code 等 AI 工具参与本项目开发时，必须遵循 [CLAUDE.md](CLAUDE.md) 中定义的架构、接口契约、编码规范和 Git 提交规范。AI 生成的代码需经过人工 review 后再提交。基于 i.MX6ULL 开发板的嵌入式点餐终端，采用 Qt 图形界面 + Flask 后台 API + MySQL 数据库的三层架构。 ## 系统架构 ``` ┌──────────────┐ HTTP JSON ┌──────────────┐ MySQL ┌──────────────┐ │ Qt 终端 │ ──────────────────→ │ Flask 后台 │ ───────────────→ │ MySQL 数据库 │ │ (i.MX6ULL) │ ←────────────────── │ API │ ←─────────────── │ (InnoDB) │ └──────────────┘ └──────────────┘ └──────────────┘ ``` Qt 端不直接连接数据库，所有业务操作通过后台 API 完成。 ## 技术栈 | 层级 | 技术 | |------|------| | 前端 | Qt5 Widgets / QNetworkAccessManager / QJsonDocument | | 后端 | Python 3 / Flask / PyMySQL / flask-cors | | 数据库 | MySQL 5.7+ (InnoDB) / 事务 + 行级锁 (`SELECT ... FOR UPDATE`) | | 硬件 | i.MX6ULL 开发板 / Linux / 触摸屏 | ## 项目结构 ``` imx6ull-ordering-system/ ├── README.md # 项目说明（本文件） ├── .gitignore ├── 统一接口文档.md # API 接口规范（所有人必读） │ ├── 吴浩宇Qt界面负责人.md # 任务书：Qt 界面 ├── 胡航后台API负责人.md # 任务书：后台 API ├── 周铭阳数据库与防超卖负责人.md # 任务书：数据库与防超卖 ├── 王可嘉开发板运行与联调负责人.md # 任务书：开发板联调 │ ├── server/ # 后台 API（胡航） │ ├── app.py # Flask 入口 │ ├── config.py # 数据库连接配置 │ ├── db.py # 数据库连接工具函数 │ ├── requirements.txt # ✓ 已创建 │ ├── routes/ │ │ ├── dishes.py # GET /api/dishes, /search, /stock │ │ └── orders.py # POST /api/orders, GET /api/orders/ │ └── services/ │ └── order_service.py # 下单事务（调用 db.py 中的锁逻辑） │ ├── database/ # 数据库脚本（周铭阳） │ ├── schema.sql # ✓ 已创建 — 建表 SQL │ ├── seed.sql # ✓ 已创建 — 初始菜品数据 │ └── test_concurrent.py # 并发测试脚本 │ ├── client/ # Qt 前端（吴浩宇） │ ├── CMakeLists.txt # Qt 项目文件 │ ├── src/ │ │ ├── main.cpp # 程序入口 │ │ ├── mainwindow.h / .cpp # 主窗口 │ │ ├── dishwidget.h / .cpp # 菜品展示组件 │ │ ├── cartwidget.h / .cpp # 购物车组件 │ │ ├── searchwidget.h / .cpp # 搜索组件 │ │ ├── apimanager.h / .cpp # HTTP API 调用封装 │ │ └── models/ │ │ ├── dish.h / .cpp # 菜品数据模型 │ │ └── cartitem.h / .cpp # 购物车项模型 │ └── resources/ │ └── fonts/ # 中文字体 │ ├── docs/ # 文档 │ ├── deploy.md # 部署说明 │ ├── board-setup.md # 开发板环境配置（王可嘉） │ └── troubleshooting.md # 常见问题排查 │ └── scripts/ # 辅助脚本 ├── init_db.sh # ✓ 已创建 └── start_server.sh # ✓ 已创建 ``` > `✓ 已创建` 表示文件已存在于仓库中；其余文件由各负责人按任务书创建。 ## 数据库设计三张表，全部使用 InnoDB 引擎以支持事务和行级锁： ``` dishes (菜品表) ├── id INT PK ├── name VARCHAR(64) 菜品名称 ├── pinyin VARCHAR(128) 拼音（用于搜索） ├── category VARCHAR(32) 分类（热菜/主食/饮品） ├── price DECIMAL(10,2) 单价 ├── stock INT 库存数量 └── status TINYINT 1=在售 0=下架 orders (订单表) ├── id INT PK ├── table_no VARCHAR(16) 桌号/终端编号 ├── total_price DECIMAL(10,2) 订单总价（后端计算） ├── status VARCHAR(16) 默认 "confirmed" └── created_at DATETIME 下单时间 order_items (订单明细表) ├── id INT PK ├── order_id INT FK→orders.id ├── dish_id INT 菜品 ID ├── dish_name VARCHAR(64) 菜品名称（冗余存储） ├── quantity INT 数量 └── unit_price DECIMAL(10,2) 下单时单价 ``` **防超卖核心逻辑**：提交订单时开启事务，使用 `SELECT ... FOR UPDATE` 锁定菜品行，检查库存充足后才扣减并写入订单；任意菜品库存不足则整单回滚。建表和初始数据见 `database/schema.sql` 和 `database/seed.sql`。 ## 团队分工 | 成员 | 职责 | 负责目录/文件 | |------|------|--------------| | 吴浩宇 | Qt 界面 — 菜品展示、搜索、购物车、下单 | `client/` | | 胡航 | 后台 API — Flask 接口、参数校验、统一返回 | `server/` | | 周铭阳 | 数据库 — 建表、事务下单、并发测试 | `database/` | | 王可嘉 | 开发板 — 环境配置、网络联调、最终演示 | `docs/board-setup.md`、联调 | 各成员的任务书见根目录对应的 `.md` 文件，开发前务必先阅读自己的任务书和 `统一接口文档.md`。 ## 环境要求 **开发电脑：** - Python 3.x + pip - MySQL 5.7+ / 8.0+ - Qt 5.x + Qt Creator（电脑端调试） - 交叉编译工具链（编译开发板版本） **开发板：** - i.MX6ULL + Linux 系统 - Qt 运行时动态库 - 中文字体（如 WenQuanYi） - 以太网或 WiFi ## 快速启动 ### 1. 初始化数据库 ```bash mysql -u root -p < database/schema.sql mysql -u root -p order_system < database/seed.sql ``` 或使用一键脚本： ```bash bash scripts/init_db.sh ``` ### 2. 启动后台服务 ```bash cd server pip install -r requirements.txt flask run --host=0.0.0.0 --port=5000 ``` ### 3. 验证后台 ```bash curl http://127.0.0.1:5000/api/health # 期望: {"success": true, "message": "server ok"} ``` ### 4. 编译运行 Qt 客户端 ```bash cd client mkdir build && cd build cmake .. make ./ordering-client ``` ## API 接口概览 | 方法 | 路径 | 说明 | |------|------|------| | GET | `/api/health` | 健康检查 | | GET | `/api/dishes` | 获取全部在售菜品（status=1，按 id 升序） | | GET | `/api/dishes/search?q=关键词` | 搜索菜品（中文名 LIKE 或拼音前缀匹配） | | GET | `/api/dishes//stock` | 查询指定菜品库存 | | POST | `/api/orders` | 提交订单（事务 + 防超卖，后端计算价格） | | GET | `/api/orders/` | 查询订单详情（含明细） | **通用返回格式：** ```json // 成功 { "success": true, "message": "操作成功", "data": { ... } } // 失败 { "success": false, "message": "错误原因" } ``` 完整接口规范见 [统一接口文档.md](统一接口文档.md)。 ## 开发流程 1. 每位成员先阅读自己的**任务书**和**统一接口文档.md** 2. 各成员在自己负责的目录下开发，互不干扰 3. 接口字段名必须与统一接口文档一致（小写字母+下划线） 4. 金额由后端数据库决定，Qt 端不能提交 price 5. 库存以后端数据库为准，Qt 显示的库存只是参考 6. 开发板访问后台时必须使用电脑局域网 IP，不能用 localhost ## 联调顺序 ``` 1. MySQL 启动 → 建表、灌数据 2. Flask 后台启动 → curl 验证 /api/health 3. 电脑端 Qt 运行 → 加载菜单、下单 4. 开发板网络测试 → curl 访问 /api/health 5. 开发板运行 Qt → 完整演示 6. 并发测试 → 证明不会超卖 ``` ## 验收标准 **Qt 前端（吴浩宇）：** - [ ] 打开程序加载真实菜单 - [ ] 搜索菜品（中文/拼音） - [ ] 分类筛选 - [ ] 购物车增删改、计算总价 - [ ] 提交订单成功时弹窗显示订单号 - [ ] 库存不足时弹窗显示后台错误信息 **后台 API（胡航）：** - [ ] 所有 6 个接口返回正确 JSON - [ ] 错误时返回 `success: false` + 清晰 message - [ ] 订单总价由后端计算，不信任前端 - [ ] 监听 `0.0.0.0` 允许局域网访问 **数据库与防超卖（周铭阳）：** - [ ] 正常下单扣库存 - [ ] 库存不足整单失败，不插入订单 - [ ] 并发 10 个请求同时扣 5 库存 → 成功 5 个、失败 5 个 - [ ] `stock` 永远不小于 0 **开发板联调（王可嘉）：** - [ ] 开发板 Linux 正常启动，触摸屏可用 - [ ] 开发板能 curl 访问后台 API - [ ] Qt 程序在开发板上正常运行 - [ ] 完整流程：加载菜单 → 下单 → 库存扣减 → 并发验证