智慧点单系统 (Smart Order System)

基于 Django + Vue 3 的在线点单与门店运营系统，面向校园食堂、咖啡店、轻餐门店、活动摊位和小型自取业务。系统把顾客点单、优惠券、内部余额、订单追踪、取餐确认、用户反馈、商家履约、商品库存、运营指标、定时发券和 AI 辅助运营串成一个可部署、可试运营、可二次开发的完整闭环。

当前版本的充值、买券和余额支付采用内部余额/试运营记账模式，不接入真实支付网关，不处理真实资金清结算；接入商用支付、发票和对账能力时需要按当地法规和支付机构规范扩展。

公网入口

入口	地址	说明
公网顾客端	http://124.223.3.214:20707/customer/	顾客点单、看评价、领券、订单取餐
公网商家端	http://124.223.3.214:20707/merchant/	商家接单、发号、维护本店商品
健康检查	http://124.223.3.214:20707/api/health	无需登录

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

项目价值

目标	说明
降低点单等待	顾客提前选规格、加购物车、用券下单，减少现场排队和人工沟通。
提升履约透明度	订单从等待接单、制作中、待取走到已完成都有状态、取餐号和预计时间。
支持门店运营	商家可看订单指标、维护商品库存、处理反馈、创建并发放优惠券。
沉淀迭代依据	用户反馈可关联具体订单，商家端按待处理/处理中/已解决流转。
具备 AI 辅助	顾客端智能推荐，商家端 AI 运营洞察，可继续扩展库存预测、反馈摘要和营销策略。
可二次开发	可改造成校园预约、社团活动售卖、轻量电商、门店 CRM 或多门店运营工具。

详细说明见 docs/product-value.md。

核心功能

顾客端

注册登录、门店选择、菜单分类筛选、标签检索、关键词搜索、价格排序、规格选择和购物车。
多门店隔离：用户选择门店后只看到该门店商品、推荐和历史评价；购物车禁止跨店混装。
智能推荐：优先使用 deepseek-v4-flash，结合偏好、库存、价格和品类多样性推荐商品；未配置或异常时规则推荐兜底。
优惠券中心：领取免费券、用内部余额购买营销券、下单时抵扣。
内部余额：充值内部余额，查看充值、订单支付、退款、买券流水。
订单中心：每笔订单展示商品明细、优惠券、原价、优惠、实付、取餐号和状态进度；待取餐时由顾客输入商家发出的取餐号确认完成。
门店历史评价：下单前可查看当前门店评分和近期评价，辅助选择商家。
订单反馈：可对具体订单提交评分和建议，也可提交一般产品反馈。

商家端

运营看板：今日订单、营收、待接单、待取餐、平均评分、待处理反馈。
订单履约：接单、制作完成、发送取餐号；顾客在订单中输入取餐号确认取餐，完成后自动累计积分。
商品库存：新增商品、编辑名称/分类/价格/库存/检索标签、上下架、上传图片；商家只能维护自己门店的商品，保存时会明确提示库存、售价、标签或上下架变更。
反馈工单：查看每条反馈、关联订单、联系方式和处理状态。
优惠券运营：创建免费券或模拟购买券，配置库存、门槛、优惠额、定时发放标记，并可批量发放。
AI 运营助手：聚合订单队列、热销商品、低库存、优惠券使用和用户反馈，生成门店运营建议；DeepSeek 不可用时自动使用规则建议。

检索与标签体系

一级分类保留”饮品 / 套餐 / 小食”，用于快速切换大类。
商品标签按”口味、场景、特性、其他”自动聚合，支持多标签组合筛选。
菜单接口支持 q、tags、minPrice、maxPrice、sort 参数，便于前端、移动端或第三方系统复用。
商家端创建和编辑商品时可维护标签，标签会同步影响顾客端检索和商品卡片展示。

预设标签分组：

分组	标签
口味	甜口、清爽、微辣、香辣、黑椒、芝士、果香、咖啡
场景	早餐、午餐、晚餐、下午茶、加班、多人分享、轻食
特性	热销、新品、低脂、高蛋白、低糖、冰饮、热饮、补能、实惠

不在上表中的标签会自动归入”其他”分组；商家可自由输入自定义标签（单个标签最长 20 字符，每个商品最多 12 个标签）。

AI 能力与拓展方向

顾客个性化推荐：结合历史订单、品类偏好、价格带、库存和时间段推荐商品。
商家运营洞察：分析待接单、待取餐、热销品、低库存、优惠券使用和反馈状态，给出行动建议。
库存预测：根据历史销量、工作日/周末、天气和活动日预测补货量。
智能定价与优惠券策略：识别高转化商品、滞销商品和客单价区间，建议满减券、组合券或限时券。
反馈摘要与工单分级：自动归纳用户反馈，识别菜品质量、取餐效率、界面体验、退款争议等问题类型。
异常订单检测：识别重复取消、长时间未取餐、库存异常扣减、频繁退款等风险。
商家问答助手：让店员用自然语言查询“今天哪些商品卖得最好”“哪些反馈还没处理”。
多门店运营分析：对比不同门店销量、评分、库存周转和活动效果，辅助区域运营决策。

工程化

后端事务保证：下单时库存扣减、余额扣减、优惠券核销在同一事务中完成。
取消订单会回退库存、余额和优惠券状态。
python scripts/run_harness.py 一键执行 Django 检查、迁移漂移检查、API 测试和前端构建。
.gitlab-ci.yml 支持 GitLink/GitLab 风格 CI，包含 DeepSeek 自动代码审查入口。
python backend/manage.py issue_coupons 支持定时发券，可由服务器 cron 或流水线定时调用。

技术栈

层级	技术
后端	Django, Django REST Framework, TokenAuthentication
数据库	SQLite 默认开发；生产支持 MySQL/PostgreSQL 环境变量切换
前端	Vue 3, Pinia, Vue Router, Axios, Vite
工程	Harness, GitLab/GitLink CI, DeepSeek 自动代码审查, MIT License

项目目录结构

.
├── backend/
│   ├── config/                 # Django 项目配置（settings、urls、wsgi）
│   ├── orders/
│   │   ├── views.py            # API 视图（菜单、购物车、订单、商家等）
│   │   ├── models.py           # 数据模型（Store、User、MenuItem、Order 等）
│   │   ├── serializers.py      # DRF 序列化器
│   │   ├── urls.py             # 路由注册
│   │   ├── recommendations.py  # AI 推荐引擎（DeepSeek + 规则兜底）
│   │   ├── ai_ops.py           # 商家 AI 运营洞察
│   │   ├── utils.py            # 工具函数（api_response、订单号生成）
│   │   ├── tests.py            # API 流程测试
│   │   ├── admin.py            # Django Admin 配置
│   │   ├── management/commands/
│   │   │   ├── seed_data.py    # 种子数据（门店、商品、用户、反馈）
│   │   │   ├── seed_history.py # 历史订单数据
│   │   │   ├── issue_coupons.py# 定时发券
│   │   │   └── generate_recharge_cards.py  # 生成充值卡密
│   │   └── migrations/         # 数据库迁移文件
│   └── manage.py               # Django 管理入口
├── frontend/
│   ├── index.html              # 顾客端入口
│   ├── merchant.html           # 商家端入口
│   └── src/
│       ├── api/index.js        # Axios 封装、所有 API 函数
│       ├── stores/             # Pinia 状态管理
│       │   ├── menu.js         # 菜单、筛选、标签状态
│       │   ├── cart.js         # 购物车状态
│       │   ├── user.js         # 用户认证状态
│       │   └── merchant.js     # 商家状态
│       ├── components/         # 可复用组件
│       │   ├── CartSidebar.vue # 购物车侧边栏
│       │   ├── MenuCard.vue    # 商品卡片
│       │   ├── StorePicker.vue # 门店选择器
│       │   ├── SpecModal.vue   # 规格选择弹窗
│       │   ├── OrderCard.vue   # 订单卡片
│       │   ├── NavBar.vue      # 导航栏
│       │   └── Toast.vue       # 消息提示
│       ├── views/
│       │   ├── customer/       # 顾客端页面（HomeView、LoginView）
│       │   └── merchant/       # 商家端页面（DashboardView、LoginView）
│       └── assets/style.css    # 全局样式
├── docs/                       # 工程文档（见下方文档索引）
├── scripts/                    # Harness、DeepSeek 审查等脚本
├── .github/workflows/          # GitHub Actions CI
├── .devops/                    # GitLink DevOps 流水线
└── data/                       # 预置 JSON 数据文件

快速开始

后端

cd backend
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/macOS
source venv/bin/activate

pip install -r requirements.txt
python manage.py migrate
python manage.py seed_data
python manage.py runserver 0.0.0.0:8080 --noreload

前端

cd frontend
npm install
npm run build

开发模式：

cd frontend
npm run dev

一键质量验证

python scripts/run_harness.py

仅验证后端：

python scripts/run_harness.py --skip-frontend

定时发券

cd backend
python manage.py issue_coupons

建议在服务器 cron 中配置每天 08:00 和 16:00 运行一次；CI/CD 也可把它作为计划任务的一部分。该命令只发放 auto_issue=True 且仍在有效期内的优惠券。

试用账号

运行 python manage.py seed_data 后自动创建演示数据。登录页不展示这些账号密码；需要本地试用时可查看本节。

角色	用户名	密码	说明
顾客	`demo`	`demo123`	默认试用用户，含余额和优惠券
顾客	`student`	`student123`	体验用户
顾客	`tester`	`tester123`	复用测试用户
商家	`merchant1`	`123456`	中关村店
商家	`merchant2`	`123456`	五道口店
商家	`merchant3`	`123456`	西二旗店

此外会创建 user01 到 user27 共 27 个顾客账号，默认密码为 user123456，用于多用户订单、评价和运营数据演示。

API 概览

所有接口统一返回 {code, message, data}。

模块	端点
系统	`GET /api/health`
用户	`POST /api/user/register`, `POST /api/user/login`, `GET /api/user/profile`
钱包	`POST /api/user/recharge`, `GET /api/user/wallet`
菜单	`GET /api/menu?storeId=`, `GET /api/menu/categories?storeId=`, `GET /api/recommendations?storeId=`, `GET /api/today-pick?storeId=`
门店评价	`GET /api/store/:id/feedback`
优惠券	`GET /api/coupons`, `GET /api/user/coupons`, `POST /api/coupons/claim`, `POST /api/coupons/purchase`
购物车	`GET /api/cart`, `POST /api/cart/add`, `POST /api/cart/update`, `POST /api/cart/remove`, `POST /api/cart/clear`
订单	`GET /api/order`, `POST /api/order/submit`, `POST /api/order/:id/cancel`, `POST /api/order/:id/pickup-confirm`
反馈	`POST /api/feedback`
商家	`POST /api/merchant/login`, `GET /api/merchant/stats`, `GET /api/merchant/ai-insights`, `GET /api/merchant/orders`
商家商品	`GET/POST /api/merchant/menu`, `PUT/DELETE /api/merchant/menu/:id`, `POST /api/merchant/menu/:id/image`
商家反馈	`GET /api/merchant/feedback`, `POST /api/merchant/feedback/:id/status`
商家优惠券	`GET/POST /api/merchant/coupons`, `POST /api/merchant/coupons/:id/issue`

更多验收映射见 docs/sdd-harness.md。

核心数据模型

模型	说明
Store	门店
User	顾客/商家、余额、积分
WalletTransaction	模拟钱包流水
MenuItem / Spec	门店商品和规格
Cart / CartItem	购物车
CouponTemplate / UserCoupon	优惠券模板和用户持券
Order	订单、原价、优惠、实付、优惠券快照、状态
Feedback	用户反馈，可关联订单

工程与文档

文档	说明
`docs/project-rubric-checklist.md`	项目自查清单
`docs/product-value.md`	项目创意、目标用户和复用价值
`docs/ai-engineering-log.md`	AI 工具应用实践与具体贡献说明
`docs/sdd-harness.md`	SDD / Harness 工程实践
`docs/ci-cd.md`	CI/CD、DeepSeek 审查和部署说明
`docs/live-demo.md`	公网体验路线
`docs/license-rationale.md`	MIT License 选择原因和边界
`docs/pipeline-evaluation.md`	流水线价值评估
`docs/team-collaboration.md`	团队分工、协作流程和 30+ 体验用户说明
`CHANGELOG.md`	版本记录

配置说明

生产环境通过环境变量注入，不建议把真实密钥提交到仓库：

SECRET_KEY=
DEBUG=False
ALLOWED_HOSTS=124.223.3.214,localhost,127.0.0.1
DATABASE_URL=mysql://user:password@host:3306/database
DEEPSEEK_API_KEY=
DEEPSEEK_MODEL=deepseek-v4-flash

仓库可以提交 .env.example 这类模板；真实数据库密码、面板账号、API Key 建议只放服务器环境变量或 CI/CD Secret。

已知边界

内部余额不接入真实支付，不提供真实清结算、发票或支付牌照能力。
默认 SQLite 适合开发和本地试用；公网部署建议使用 MySQL 或 PostgreSQL。
商家端订单刷新采用轮询，后续可升级 WebSocket 或 SSE。
前端当前已有生产构建验证，但还没有 Playwright 自动 UI 测试。

License

最后更新：2026-06-25