智慧点单系统 (Smart Order System)

基于 Django 4.x + Vue 3 的前后端分离在线点单与订单管理平台，面向小型餐饮门店。支持顾客线上下单、余额支付、订单实时追踪，以及商家端的订单处理与菜品管理。

功能特性

顾客端：注册登录、浏览菜单（按分类筛选）、管理购物车、提交订单、余额支付、订单追踪、取消订单、余额充值、提交用户反馈
商家端：商家登录、订单接单 / 标记制作完成 / 确认取走、订单筛选、菜品管理（增删改查、上传图片）、上下架管理、查看用户反馈台账
技术特性：Token 认证、并发安全（订单下单行级锁）、订单号 / 取餐号自动生成、积分累计、CI/CD、DeepSeek 自动代码审查

项目截图

以下截图待补充，可替换为实际运行截图。

页面	说明
`docs/screenshots/01_login.png`	用户登录页
`docs/screenshots/02_menu.png`	顾客端菜单浏览
`docs/screenshots/03_cart.png`	购物车页面
`docs/screenshots/04_order.png`	订单详情 / 追踪
`docs/screenshots/05_merchant_dashboard.png`	商家端订单管理

课程实践交付物

本项目已按 2026 开源软件课程实践评分标准补充工程化材料：

文档	说明
`docs/project-rubric-checklist.md`	评分项对照和答辩前自查
`docs/sdd-harness.md`	SDD / Harness 工程实践说明
`docs/ai-engineering-log.md`	AI 工具应用实践记录
`docs/community-operation.md`	2 周社区运营与用户反馈计划
`docs/team-collaboration.md`	团队分工与贡献记录模板
`docs/defense-outline.md`	5 分钟答辩提纲和 Demo 脚本
`docs/ci-cd.md`	CI/CD、DeepSeek 审查和部署说明

技术栈

层级	技术	版本
后端框架	Django	>=4.2
API 框架	Django REST Framework	>=3.14
跨域	django-cors-headers	>=4.0
图片处理	Pillow	>=10.0
数据库	SQLite（默认，可切换 PostgreSQL/MySQL）	—
前端框架	Vue 3 (Composition API)	^3.5
状态管理	Pinia	^3.0
路由	Vue Router	^5.1
HTTP 客户端	Axios	^1.18
构建工具	Vite	^8.0

项目结构

order_system/
├── backend/                    # Django 后端
│   ├── config/                 # Django 配置（settings, urls, wsgi）
│   │   ├── settings.py         # 数据库、CORS、DRF、静态文件
│   │   └── urls.py             # 根路由 + 静态文件映射
│   ├── orders/                 # 核心应用
│   │   ├── models.py           # 7 个数据模型
│   │   ├── serializers.py      # DRF 序列化器
│   │   ├── views.py            # 23 个 API 端点
│   │   ├── urls.py             # API 路由
│   │   ├── utils.py            # 工具函数
│   │   └── management/commands/seed_data.py  # 种子数据
│   ├── media/uploads/          # 菜品图片上传目录（gitignore）
│   ├── static/                 # 前端构建产物（gitignore）
│   ├── manage.py
│   ├── requirements.txt
│   └── .env                   # 环境变量（不提交，见 .env.example）
├── frontend/                   # Vue 3 前端
│   ├── src/
│   │   ├── api/index.js        # Axios 实例 + 拦截器 + 所有 API
│   │   ├── stores/             # Pinia stores (user/menu/cart/merchant)
│   │   ├── components/         # 8 个组件
│   │   ├── views/              # 用户端 + 商家端页面
│   │   ├── App.vue             # 用户端根组件
│   │   ├── MerchantApp.vue     # 商家端根组件
│   │   ├── main.js             # 用户端入口
│   │   └── merchant.js         # 商家端入口
│   ├── index.html              # 用户端 HTML 模板
│   ├── merchant.html           # 商家端 HTML 模板
│   ├── vite.config.js          # Vite 多入口配置
│   └── package.json
├── data/                       # 示例数据 (JSON)
├── docs/                       # 文档
│   ├── 编码实现报告.md
│   └── screenshots/
├── .gitignore
├── .env.example                # 环境变量示例
├── LICENSE                     # MIT 开源协议
└── README.md                   # 本文件

archive/ 目录包含旧版 C++/cpp-httplib 实现，仅供归档参考。

快速开始

前置条件

Python >= 3.10
Node.js >= 18
npm >= 9

后端安装

cd backend

# 1. 创建虚拟环境（推荐）
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

# 2. 配置环境变量（可选，使用默认值可跳过）
cp .env.example .env
# 编辑 .env，修改 SECRET_KEY 等配置

# 3. 安装依赖
pip install -r requirements.txt

# 4. 数据库迁移
python manage.py migrate

# 5. 初始化种子数据（测试账号 + 菜品）
python manage.py seed_data

# 6. 启动开发服务器
python manage.py runserver 0.0.0.0:8080 --noreload

前端开发

cd frontend

# 1. 安装依赖
npm install

# 2. 启动开发服务器（Vite dev server 代理 API 到 :8080）
npm run dev

前端生产构建

cd frontend
npm run build
# 构建产物输出到 backend/static/，由 Django 直接服务

构建后访问 http://127.0.0.1:8080/customer/ 和 /merchant/。

访问地址

端	地址	说明
用户端	`http://127.0.0.1:8080/customer/`	菜单浏览、下单、订单追踪
商家端	`http://127.0.0.1:8080/merchant/`	订单管理、菜品管理

测试账号

运行 python manage.py seed_data 后自动创建。

角色	用户名	密码	说明
顾客	`demo`	`123456`	余额 ¥1000
商家	`merchant1`	`123456`	中关村店

API 概览

所有接口遵循统一响应格式 {code: int, message: string, data: any}。

模块	端点	方法	认证
用户	`/api/user/register`	POST	无
用户	`/api/user/login`	POST	无
用户	`/api/user/profile`	GET	Token
用户	`/api/user/recharge`	POST	Token
菜单	`/api/menu`	GET	无
菜单	`/api/menu/categories`	GET	无
购物车	`/api/cart`	GET	Token
购物车	`/api/cart/add`	POST	Token
购物车	`/api/cart/update`	POST	Token
购物车	`/api/cart/remove`	POST	Token
购物车	`/api/cart/clear`	POST	Token
订单	`/api/order`	GET	Token
订单	`/api/order/submit`	POST	Token
订单	`/api/order/:id/cancel`	POST	Token
门店	`/api/store/list`	GET	无
商家	`/api/merchant/login`	POST	无
商家	`/api/merchant/orders`	GET	Token
商家	`/api/merchant/order/:id/accept`	POST	Token
商家	`/api/merchant/order/:id/ready`	POST	Token
商家	`/api/merchant/order/:id/complete`	POST	Token
商家	`/api/merchant/menu`	GET	Token
商家	`/api/merchant/menu/:id`	PUT	Token
商家	`/api/merchant/menu/:id/image`	POST	Token

详细接口文档见 docs/编码实现报告.md。

数据模型

7 张核心表：

模型	说明
Store	门店（名称、地址、营业状态）
User	用户（customer/merchant 角色、余额、积分）
MenuItem	菜品（名称、分类、价格、库存、规格、图片、上下架）
Spec	菜品规格选项（如杯型: 中杯/大杯）
Cart	购物车（一对多 CartItem）
CartItem	购物车项（菜品、数量、选中规格快照）
Order	订单（五态流转: WAITING → MAKING → READY → COMPLETED/CANCELLED）

架构说明

认证：DRF TokenAuthentication 为主通道，兼容旧版 X-User-Id / X-Merchant-Id header
并发安全：下单接口使用 @transaction.atomic + select_for_update() 行级锁防止超卖
订单号：格式 YYYYMMDDNNN（日期 + 3 位序号）
取餐号：格式 YYYYMMDD-NNN
积分规则：消费金额 = 积分数，取餐时累加

已知问题

Token 混用风险：同一浏览器同时打开用户端和商家端时，若两端都登录，Axios 拦截器可能选错 token。当前通过 URL 感知的智能 token 选择器缓解，但极端场景下仍可能 401。建议：开发测试时使用不同浏览器或无痕窗口分别打开两端。
图片上传路径遗留：backend/media/uploads/uploads/ 目录下存在历史双层嵌套的上传文件（已修复，旧文件未清理）。新上传的图片路径正常。
SQLite 并发限制：SQLite 不支持高并发写入，仅适合开发和小规模部署。生产环境建议切换为 PostgreSQL 或 MySQL。
无 WebSocket 实时推送：商家端订单更新依赖 10 秒轮询，非实时推送。未来可考虑 Django Channels。
前端无路由守卫：未登录用户可直接访问需要认证的页面（API 层面有 401 保护，但 UI 不会自动跳转登录页，需手动访问）。
静态文件 Cache-Control：Django 开发服务器未对静态文件设置缓存头，浏览器可能缓存旧版 JS。部署时建议通过 Nginx 反向代理并配置缓存策略。
Vite 构建产物路径：多入口构建产物路径与 Django 路由映射需手动对齐，修改 vite.config.js 后需同步更新 backend/config/urls.py 中的静态文件路由。

开发历程

本项目最初为 C++/cpp-httplib 实现的单文件后端 + 原生 HTML 前端。后通过 Vibe Coding（AI 辅助对话式开发）重构为 Django + Vue 3 全栈架构。详细的开发过程、问题修复记录及功能与需求的对应关系，请参阅 docs/编码实现报告.md。

贡献指南

欢迎提交 Issue 和 Pull Request！

Fork 本仓库
创建特性分支 (git checkout -b feature/xxx)
提交更改 (git commit -m 'Add xxx')
推送到分支 (git push origin feature/xxx)
提交 Pull Request

许可证

本项目采用 MIT 许可证。

最后更新：2026-06-22