签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,157 @@
+# 第四章 架构设计 - 系统架构总览
+
+## 4.1 整体架构
+
+项目采用前后端分离的 B/S 架构，后端基于 Django 6.0.3 提供 RESTful API，前端基于 Vue3 + ElementPlus 构建单页应用。系统通过 Nginx 反向代理统一入口，实现静态资源托管与 API 转发。
+
+### 架构图
+
+```
+浏览器 (Vue3 + ElementPlus)
+    |
+    v
+Nginx (反向代理)
+    |
+    v
+Django Application
+    |
+    +-- Middleware Chain
+    |   +-- CORS (django-cors-headers)
+    |   +-- check_login (JWT认证)
+    |   +-- PermissionRequired (RBAC鉴权)
+    |
+    +-- URL Router (application/urls.py)
+    |   +-- include() -> 各模块urls.py
+    |
+    +-- View Layer (views.py)
+    |   +-- Class-based Views + decorators
+    |
+    +-- Service Layer (services.py)
+    |   +-- 业务逻辑 + Django ORM
+    |
+    +-- Model Layer (models.py)
+        +-- BaseModel -> 业务模型
+    |
+    v
+MySQL + Redis
+```
+
+## 4.2 核心分层
+
+系统采用经典的分层架构设计，各层职责明确：
+
+| 层级 | 职责 | 典型文件 |
+|------|------|----------|
+| **视图层 (View)** | 接收HTTP请求、参数校验、调用Service、返回响应 | `views.py` |
+| **服务层 (Service)** | 业务逻辑处理、数据组装、事务控制 | `services.py` |
+| **表单层 (Form)** | 数据验证、类型转换、错误信息生成 | `forms.py` |
+| **模型层 (Model)** | 数据库表定义、字段约束、关联关系 | `models.py` |
+| **路由层 (URL)** | URL到视图的映射注册 | `urls.py` |
+
+## 4.3 请求处理流程
+
+一个典型的 API 请求经过以下处理链路：
+
+```
+1. 浏览器发起请求 (携带 Authorization: Bearer <token>)
+2. CORS中间件 - 处理跨域预检请求
+3. check_login - 验证JWT token有效性
+4. URL路由匹配 - 分发到对应视图类
+5. PermissionRequired - 验证用户权限节点
+6. View.get/post/put/delete - 处理请求
+7. Service函数 - 执行业务逻辑
+8. R.ok()/R.failed() - 构造统一响应
+9. JsonResponse - 返回JSON数据
+```
+
+## 4.4 模块化设计
+
+每个业务模块（如 example、user、role 等）遵循统一的文件结构：
+
+```
+application/<module>/
+    __init__.py      # 包初始化
+    apps.py          # Django应用配置
+    models.py        # 数据模型
+    forms.py         # 表单验证
+    services.py      # 业务逻辑
+    views.py         # 视图处理
+    urls.py          # 路由配置
+    admin.py         # Admin后台注册
+    migrations/      # 数据库迁移文件
+```
+
+## 4.5 关键设计决策
+
+### 前后端分离
+
+- 后端仅提供 JSON API，不渲染模板
+- 前端通过 Vite 开发服务器代理请求到 Django
+- 生产环境由 Nginx 统一处理静态资源和 API 转发
+
+### JWT 认证替代 Session
+
+- 无状态认证，适合分布式部署
+- Token 通过 Authorization 请求头传递
+- 支持 Token 黑名单机制（Redis 存储）
+
+### 软删除策略
+
+- 所有业务表包含 `is_delete` 字段
+- 删除操作仅标记 `is_delete=True`，不物理删除
+- 所有查询自动过滤 `is_delete=False`
+
+### 代码生成器
+
+- 通过数据库表定义自动生成完整模块
+- 包含后端 Model/Form/Service/View/URL
+- 包含前端 Vue 页面和 API 模块
+- 自动注册菜单和权限节点
+
+## 4.6 技术栈概览
+
+| 类别 | 技术选型 | 版本 |
+|------|----------|------|
+| 后端框架 | Django | 6.0.3 |
+| 数据库 | MySQL | 8.0+ |
+| 缓存 | Redis | 6.0+ |
+| 认证 | JWT (PyJWT) | - |
+| 前端框架 | Vue3 | 3.x |
+| UI组件库 | ElementPlus | - |
+| 构建工具 | Vite | - |
+| 状态管理 | Pinia | - |
+
+## 4.7 目录结构
+
+```
+DjangoAdmin_Django_EleVue/
+-- application/           # Django后端应用
+|   +-- settings.py        # 项目配置
+|   +-- urls.py            # 主路由
+|   +-- models.py          # BaseModel定义
+|   +-- <module>/          # 业务模块
+-- middleware/             # 中间件
+|   +-- login_middleware.py # JWT认证
+|   +-- permission_middleware.py # 权限控制
+-- utils/                  # 工具函数
+|   +-- R.py               # 统一响应
+|   +-- jwt.py             # JWT工具
+|   +-- security.py        # 安全工具
+-- config/                 # 配置文件
+|   +-- env.py             # 环境变量
+-- ui/                     # Vue前端
+    +-- src/
+        +-- views/         # 页面组件
+        +-- api/           # API接口
+        +-- components/    # 公共组件
+```
+
+## 4.8 扩展性设计
+
+系统通过以下机制保证良好的扩展性：
+
+1. **Django App 机制**：每个模块独立为一个 Django App，可独立开发和部署
+2. **代码生成器**：新模块通过数据库表定义自动生成，减少重复开发
+3. **模板定制**：代码生成器使用 Jinja2 模板，可根据项目需求定制生成规则
+4. **中间件扩展**：通过 Django 中间件机制可灵活添加请求/响应处理逻辑
+5. **权限节点**：基于 `sys:<module>:<action>` 的权限标识，支持细粒度权限控制