智慧点单系统 (Smart Order System)

基于 Django 4.x + Vue 3 的前后端分离在线点单与订单管理平台，面向校园、小型餐饮门店和课程实践团队。项目不只提供顾客下单和商家履约，还把用户反馈、Issue 管理、自动化测试、CI/CD 和开源复用文档串成一个可持续迭代的样板工程。

项目价值

目标	说明
降低排队成本	顾客提前浏览菜单、加入购物车并提交订单，减少现场人工点单压力。
提升履约透明度	订单从等待接单、制作中、待取走到已完成都有明确状态和取餐号。
沉淀真实反馈	顾客可提交评分和建议，商家端可查看并标记处理状态，形成运营闭环。
支撑课程实践	提供 SDD/Harness、CI/CD、DeepSeek 代码审查、License 说明、Issue/PR 模板和答辩脚本。
方便二次开发	可改造成预约系统、活动售卖、小型电商原型或校园服务项目。

详细价值分析见 docs/product-value.md。

功能特性

顾客端：注册登录、浏览菜单（按分类筛选）、管理购物车、提交订单、余额支付、订单追踪、预计取餐时间、取消订单、余额充值、提交用户反馈
商家端：商家登录、订单接单 / 标记制作完成 / 确认取走、订单筛选、菜品管理（增删改查、上传图片）、上下架管理、查看并处理用户反馈台账
技术特性：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/product-value.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/live-demo.md`	Live Demo 启动、演示路线和问题处理
`docs/ci-cd.md`	CI/CD、DeepSeek 审查和部署说明
`docs/pipeline-evaluation.md`	流水线价值、覆盖风险和不足评估
`docs/license-rationale.md`	MIT License 选择原因、约束和边界
`CHANGELOG.md`	发布版本说明

技术栈

层级	技术	版本
后端框架	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           # 8 个数据模型
│   │   ├── serializers.py      # DRF 序列化器
│   │   ├── views.py            # 顾客端、商家端和反馈 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/                       # 文档
│   ├── product-value.md
│   ├── sdd-harness.md
│   ├── live-demo.md
│   └── license-rationale.md
├── scripts/                    # Harness、代码审查和 Demo 脚本
├── .gitignore
├── .env.example                # 环境变量示例
├── LICENSE                     # MIT 开源协议
└── README.md                   # 本文件

快速开始

前置条件

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/。

一键 Harness 验证

python scripts/run_harness.py

该脚本会依次运行 Django 系统检查、迁移漂移检查、后端测试和前端生产构建。答辩前、提交 PR 前和 CI/CD 都应以它作为质量门槛。

Live Demo

完整演示路线见 docs/live-demo.md。推荐流程：

顾客端登录 demo / demo123。
浏览菜单、加入购物车并提交订单。
商家端登录 merchant1 / 123456，接单、制作完成、确认取走。
顾客提交反馈，商家端将反馈标记为处理中或已解决。
展示 python scripts/run_harness.py、CI/CD 和 License 说明。

Windows 可使用一键演示脚本：

powershell -ExecutionPolicy Bypass -File scripts\start_demo.ps1

访问地址

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

测试账号

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

角色	用户名	密码	说明
顾客	`demo`	`demo123`	余额 ¥200
商家	`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/feedback`	POST	Token
商家	`/api/merchant/login`	POST	无
商家	`/api/merchant/orders`	GET	Token
商家	`/api/merchant/feedback`	GET	Token
商家	`/api/merchant/feedback/:id/status`	POST	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/sdd-harness.md。

数据模型

8 张核心表：

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

架构说明

认证：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。
静态文件 Cache-Control：Django 开发服务器未对静态文件设置缓存头，浏览器可能缓存旧版 JS。部署时建议通过 Nginx 反向代理并配置缓存策略。
Vite 构建产物路径：多入口构建产物路径与 Django 路由映射需手动对齐，修改 vite.config.js 后需同步更新 backend/config/urls.py 中的静态文件路由。

开发历程

本项目最初从轻量点单原型演进而来，当前主线已重构为 Django + Vue 3 全栈架构，并补齐 SDD/Harness、CI/CD、自动代码审查、License 说明和开源协作模板。详细工程实践见 docs/sdd-harness.md 和 docs/ai-engineering-log.md。

贡献指南

欢迎提交 Issue 和 Pull Request！完整说明见 CONTRIBUTING.md。

先查看或创建 Issue，说明 Bug、功能诉求或复用场景。
Fork 本仓库。
创建特性分支 (git checkout -b feature/xxx)。
实现改动，并运行 python scripts/run_harness.py。
提交更改 (git commit -m 'Add xxx')。
推送到分支 (git push origin feature/xxx)。
提交 Pull Request，并按模板填写验证结果。

Issue 模板位于 .github/ISSUE_TEMPLATE/，PR 模板位于 .github/PULL_REQUEST_TEMPLATE.md。

许可证

最后更新：2026-06-24