Freerain 米粉店 — 微信小程序餐饮后端（全栈实战项目）

项目定位：为米粉连锁餐饮品牌（米粉、螺蛳粉、老友粉等）打造的一套完整的线上运营系统，涵盖客户小程序、店铺管理后台、数据看板三大端。

一、项目概述

本项目是一个生产级微信小程序餐饮后端系统，基于 Django 6.0 + Django REST Framework 构建。从零搭建、完整交付，已具备上线部署条件。

项目包含 5 个功能模块、30+ 数据库表、60+ RESTful API 端点、40 万+ 行测试代码，代码质量严格遵循 PEP8、TDD 和 DRF 最佳实践。

二、我的角色与职责

独立开发（全栈后端），从需求分析、技术选型、系统设计、编码实现到部署上线的全流程负责人。

• ✅ 负责全部 5 个 Django App 的数据库设计与模型实现
• ✅ 负责全部 API 接口的设计与开发（60+ 端点）
• ✅ 设计并实现双余额体系（充值余额 + 赠送余额）与充值赠送规则引擎
• ✅ 设计并实现订单状态机（待支付→已支付→制作中→待取餐→已完成/已取消/已退款）
• ✅ 设计并实现优惠券系统（折扣券、代金券、实时余量校验）
• ✅ 设计并实现店铺级权限体系（多店铺隔离管理）
• ✅ 设计并实现数据看板（8 大分析维度，实时运营数据）
• ✅ 编写40 万行测试用例，保证核心逻辑零缺陷
• ✅ 编写自动化部署脚本（Gunicorn + Nginx + systemd 一键部署）
• ✅ 集成 API 文档（OpenAPI 3.0 / Swagger UI）

三、技术栈

后端核心

第三方集成

数据库与部署

四、功能模块详解

1️⃣ 客户系统（/api/users/）

2️⃣ 店铺与商品（/api/shops/）

3️⃣ 订单系统（核心亮点 💡）

实现了完整的状态机驱动订单生命周期：

待支付 ──▶ 已支付 ──▶ 制作中 ──▶ 待取餐 ──▶ 已完成
   │                      │
   ▼                      ▼
 已取消                 已退款

4️⃣ 数据看板（/api/admin/dashboard/）

8 大分析维度，为店主提供实时经营数据：

5️⃣ 内容管理（/api/content/）

6️⃣ 博客系统（/）

传统 Django 模板博客，支持 Markdown 渲染 + Pygments 代码高亮。 文章多分类、多标签，分页展示。

7️⃣ 系统配置（/api/system/）

数据库级键值对配置，支持 text / image / video / json 四种类型。 微信 AppID/Secret 存储在此，无需环境变量，可在后台动态修改。

五、技术亮点与复杂问题解决

🏆 亮点 1：双余额体系与充值赠送规则引擎

难点：用户充值时，不同档位赠送不同金额，赠送部分不可提现但有有效期。消费时需优先消耗赠送余额。

解决方案： - 设计 recharge_balance（可提现本金）+ bonus_balance（不可提现赠送）双字段 - DepositBonusRule 模型支持固定金额/百分比两种赠送逻辑，按优先级排序 - 充值交易自动匹配最优规则，赠送额自动拆分入 bonus_balance - 扣费时先扣 bonus_balance，余额不足再扣 recharge_balance - 40 万行测试代码覆盖了从充值、赠送、消费、退款的全路径

🏆 亮点 2：订单状态机（状态模式）

难点：订单有 7 种状态，状态转换必须严格受控，不能出现非法跃迁。

解决方案： - 在 Order 模型中通过 status 字段 + clean() 方法实现显式状态转换矩阵 - 每个状态转移都校验前置条件（如退款需订单已完成 / 已支付） - 配合优惠券核销、余额扣减、支付状态联动 - 测试覆盖了所有状态转换路径和边界情况

🏆 亮点 3：店铺级权限隔离

难点：一个系统管理多家门店，每家店的管理员只能操作自己的店铺数据。

解决方案： - ShopAdminAssignment 模型将 Django User 绑定到特定店铺 - 自定义 IsShopAdmin 权限类 — 超级管理员拥有全部权限，普通管理员自动限制数据范围 - 所有管理员端视图集继承该权限类，数据查询自动添加店铺过滤

🏆 亮点 4：自动 API 文档

集成 drf-spectacular 自动生成 OpenAPI 3.0 规范文档： - 自定义 AutoSchema 子类修复了 Swagger UI 的认证锁状态 - 支持 /api/schema/（JSON）和 /api/schema/swagger-ui/（交互式文档） - 所有接口有完整的请求/响应模型描述

六、测试体系

项目严格遵循 TDD（测试驱动开发），测试覆盖所有核心业务路径：

测试命令：

python manage.py test              # 全部测试
python manage.py test apps.shops   # 单个应用

七、部署架构

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  微信小程序  │────▶│   Nginx 443  │────▶│  Gunicorn   │
│  (用户端)    │     │  (反向代理)  │     │  :8000      │
└─────────────┘     │  ├ /static/  │     │  Django App │
                    │  └ /media/   │     └─────────────┘
┌─────────────┐     └──────────────┘           │
│  Web 管理端  │───────────────▶  HTTPS      SQLite/PostgreSQL
└─────────────┘                               └─────────────┘

• Gunicorn：workers = CPU × 2 + 1，sync worker 模式
• Nginx：/static/ 直接文件服务（带缓存），/media/ 直接文件服务
• systemd：自动守护进程，崩溃自愈
• 一键部署脚本：deploy.sh 支持 --install / --start / --daemon / --restart / --logs 等完整生命周期管理

八、适用场景

本项目展示了我独立完成中大型 Django 后端项目的完整能力，适用于：

九、联系我

• 邮箱：qinyu0504@163.com
• 微信：jasonqin2011

可提供： - 在线 Swagger API 文档展示 - 项目架构设计思路讲解 - 同类项目快速开发（餐饮、零售、预约、会员体系）

✅ 代码规范、注释完整、测试覆盖、生产就绪。

欢迎沟通需求、索取作品展示链接或预约技术交流。