https://blog.cha.moe/article/fde2d9ef.html

开发环境与工具清单
主要模块划分
角色权限描述
关键问题（含分页、购物车）

To-Do List：开发文档内容规划

1. 开发环境与工具

[x] 后端：Python、Django、DRF、Celery、Redis、pymysql
[x] 前端：Node.js、Vue3、Pinia、Vite、Axios
[x] 数据库：MySQL 8.0
[x] 工具链：PyCharm/WebStorm、Navicat、Swagger、Git
[x] 本地部署：Windows 兼容，无容器依赖

2. 主要模块（Django Apps）

[x] core：基础组件（加密字段、审计日志、分页器）
[x] users：用户、商家、地址、认证
[x] books：图书、作者、分类树、ISBN 校验
[x] inventory：库存、预警
[x] orders：订单、支付适配器
[x] cart：购物车
[x] wishlist：收藏夹

3. 角色描述

[x] 用户（user）：浏览、购物车、下单、管理地址
[x] 商家（merchant）：管理图书/库存/订单，需审核激活
[x] 管理员（admin）：审核商家、全量管理、审计日志

4. 关键问题

[x] 分页：统一使用 DRF PageNumberPagination，URL 参数 ?page=N，默认 page=1
[x] 购物车：持久化模型（非前端内存），支持增删改查，下单后清空
[x] 数据一致性：订单与库存原子操作
[x] 权限隔离：三套 API 命名空间 + DRF 权限类
[x] 敏感数据：应用层 AES 加密，解密权限控制

5. 文档结构

[x] 1. 引言（目标、原则）
[x] 2. 开发环境与工具
[x] 3. 系统架构
[x] 4. 主要模块
[x] 5. 角色与权限
[x] 6. 关键问题解决方案
[x] 7. 部署与测试

Django + Vue + MySQL 本地图书销售系统

开发文档

1. 引言

1.1 项目目标

构建一个多角色、高一致性、本地可运行的在线图书销售系统，支持图书管理、库存控制、订单处理、会员体系等核心电商功能，适用于个人开发者在 Windows 环境下快速开发与验证。

1.2 设计原则

好品味：数据结构消除边界情况，无补丁式 if 分支
零破坏性：API 版本化、软删除、JWT 向后兼容
实用主义：仅实现明确需求，拒绝过度设计
简洁性：模块 ≤7，API ≤45，前端组件 ≤20

2. 开发环境与工具

类别	工具	版本要求	说明
操作系统	Windows	10/11	本地开发环境
后端语言	Python	≥3.9
后端框架	Django	5.0	+ DRF 3.14
数据库	MySQL	8.0	InnoDB 引擎
缓存/队列	Redis	7.0+	Celery 任务队列
前端语言	JavaScript	ES2020+
前端框架	Vue	3.4+	+ Pinia 2.1+, Vue Router 4.2+
包管理	npm / pip
IDE	PyCharm / WebStorm	-	或 VS Code
数据库工具	Navicat / MySQL Workbench	-	表结构管理
API 文档	drf-spectacular	-	自动生成 Swagger
版本控制	Git	-	每日 commit

依赖安装：

# 后端
pip install django djangorestframework django-treebeard celery redis pymysql

# 前端
npm install vue@^3 pinia vue-router axios

3. 系统架构

3.1 技术架构

前后端分离：Vue 前端（localhost:3000） ↔ Django 后端（localhost:8000）
认证：JWT（含 role/user_id/merchant_id）
数据流：用户操作 → Vue → API → Django → MySQL/Redis → 响应 → Vue 渲染
异步任务：库存预警通过 Celery + Redis 异步通知

3.2 部署架构（本地）

[浏览器] 
   │
   ├── Vue Dev Server (Vite) → http://localhost:3000
   │        └── 代理 /api → http://localhost:8000/api/v1/
   │
   └── Django Dev Server → http://localhost:8000
            ├── MySQL (3306)
            └── Redis (6379, Celery)

4. 主要模块

模块	功能	关键模型
`core`	基础设施	`EncryptedCharField`, `AuditLog`, `StandardPagination`
`users`	用户体系	`User`, `Merchant`, `UserAddress`
`books`	图书管理	`Book`, `Author`, `Category`
`inventory`	库存控制	`Inventory`
`orders`	订单与支付	`Order`, `OrderItem`
`cart`	购物车	`ShoppingCart`
`wishlist`	收藏夹	`Wishlist`

模块独立性：各 App 可单独测试、复用，无循环依赖。

5. 角色与权限

角色	权限范围	访问入口
用户 (user)	- 浏览图书 - 管理购物车/收藏夹 - 下单 - 管理个人地址	`/api/v1/user/`
商家 (merchant)	- 管理自有图书/库存 - 查看自有订单 - 需管理员审核激活	`/api/v1/merchant/`
管理员 (admin)	- 审核商家 - 全量图书/订单管理 - 查看审计日志	`/api/v1/admin/`

权限实现：

JWT payload 包含 role 和 merchant_id（商家）

DRF 权限类（IsAdmin, IsApprovedMerchant, IsOwner）

未认证请求 → 401；无权限 → 403；商家未审核 → 403

6. 关键问题解决方案

6.1 分页（Pagination）

实现方式：DRF PageNumberPagination
参数：URL 查询参数 ?page=N（默认 N=1）
响应格式：

  {
    "count": 100,
    "next": "http://...?page=2",
    "previous": null,
    "results": [ ... ]
  }

适用场景：图书列表、订单历史、评论（未来扩展）、审计日志
配置：全局分页大小 = 20（可前端覆盖）

6.2 购物车（Shopping Cart）

持久化：后端模型 ShoppingCart(user, book, quantity)，非前端内存
功能：
POST /cart/：添加商品
GET /cart/：获取当前用户购物车
PATCH /cart/{id}/：修改数量
DELETE /cart/{id}/：删除项
下单后：自动清空当前用户购物车
并发安全：数量修改使用 F() 表达式

6.3 数据一致性（订单与库存）

原子操作：Django transaction.atomic() + select_for_update()
流程：

锁定库存行
检查库存 ≥ 数量
扣减库存
创建订单（含价格快照）

失败：全回滚，无中间状态

6.4 敏感数据加密

字段：UserAddress.phone, UserAddress.address, Merchant.address
实现：自定义 EncryptedCharField（应用层 AES-256）
访问控制：仅本人或管理员可解密（Serializer 层控制）

6.5 图书删除与历史订单

软删除：Book.is_deleted = True，不物理删除
订单快照：OrderItem 存储书名、价格，无外键到 Book
结果：历史订单始终可读，不影响报表

7. 部署与测试

7.1 本地启动流程

# 1. 初始化数据库
python manage.py migrate

# 2. 启动后端
python manage.py runserver

# 3. 启动前端
npm run dev

7.2 必测场景

场景	验证点
并发下单	库存不超卖
商家隔离	商家 A 无法访问商家 B 数据
购物车持久化	刷新页面不丢失
分页	`?page=2` 返回正确数据
敏感字段	非授权角色无法解密