签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,120 @@
+# 模块开发实战概述
+
+本章以「案例管理（Example）」模块为完整案例，手把手演示从零开发一个业务模块的全流程。学完本章后，你将掌握项目中任意模块的开发方式。
+
+## 你将学到什么
+
+通过本章的实战演练，你将完整经历以下开发环节：
+
+| 步骤 | 文件 | 说明 |
+|:----|:----|:----|
+| 1. 数据模型 | `models.py` | 定义数据库表结构，继承 BaseModel |
+| 2. 表单验证 | `forms.py` | Django ModelForm 验证，中文错误提示 |
+| 3. 业务逻辑 | `services.py` | 实现增删改查、分页、状态管理 |
+| 4. 视图层 | `views.py` | 类视图，登录校验 + 权限控制 + 操作日志 |
+| 5. 路由注册 | `urls.py` | 模块路由 + 主路由注册 |
+| 6. 权限配置 | 菜单管理 | 配置权限节点 sys:module:action |
+| 7. 前端 API | `api/tool/example.ts` | 封装 HTTP 请求 |
+| 8. 前端页面 | `views/tool/example/` | 列表页 + 编辑弹窗 + 详情弹窗 |
+
+## 案例模块：案例管理
+
+选择「案例管理（Example）」作为案例的原因：
+
+1. **结构典型**：包含完整的 CRUD + 状态管理 + 批量删除，覆盖大多数业务场景
+2. **字段丰富**：涵盖字符串、整数、图片、状态枚举、排序等常见字段类型
+3. **代码规范**：由代码生成器生成，遵循项目统一的开发规范
+4. **前后端完整**：后端 5 个文件 + 前端 5 个文件，总计约 1500 行代码
+
+## 模块文件总览
+
+```
+后端（application/example/）
+├── models.py          # 数据模型（继承 BaseModel）
+├── forms.py           # 表单验证（Django ModelForm）
+├── services.py        # 业务逻辑层（CRUD 函数）
+├── views.py           # 视图层（类视图 + 装饰器）
+├── urls.py            # 路由配置
+├── apps.py            # 应用配置
+├── admin.py           # Django Admin 注册
+└── migrations/        # 数据库迁移文件
+
+前端（ui/src/）
+├── api/tool/
+│   └── example.ts     # API 请求封装
+└── views/tool/example/
+    ├── index.vue      # 主页面：搜索 + 表格 + 操作
+    ├── edit.vue       # 编辑弹窗：新增/编辑表单
+    ├── detail.vue     # 详情弹窗：查看记录详情
+    ├── columns.ts     # 表格列定义
+    └── querySchemas.ts # 搜索表单 Schema
+```
+
+## 数据库表结构
+
+案例表 `django_example` 结构如下：
+
+| 字段 | 类型 | 说明 |
+|:----|:----|:----|
+| id | int | 主键，自增 |
+| name | varchar(100) | 案例名称 |
+| avatar | varchar(255) | 案例图片 |
+| type | int | 案例类型：1-类型1 2-类型2 3-类型3 4-类型4 |
+| status | int | 案例状态：1-正常 2-禁用 |
+| sort | int | 排序权重 |
+| create_user | varchar(50) | 创建人 |
+| create_time | datetime | 创建时间 |
+| update_user | varchar(50) | 更新人 |
+| update_time | datetime | 更新时间 |
+| is_delete | tinyint | 软删除标记：0-正常 1-已删除 |
+
+其中 `id`、`create_user`、`create_time`、`update_user`、`update_time`、`is_delete` 由基类 `BaseModel` 自动提供，业务字段仅需定义 `name`、`avatar`、`type`、`status`、`sort`。
+
+## 开发顺序
+
+建议按以下顺序逐步开发，每完成一步即可验证：
+
+```
+1. models.py     → 建表，确认数据库中有 django_example 表
+2. forms.py      → 定义表单验证规则
+3. services.py   → 业务逻辑层（CRUD 函数）
+4. views.py      → API 视图（类视图 + 装饰器）
+5. urls.py       → 注册路由
+6. 权限配置       → 在菜单管理中添加权限节点
+7. 前端 API       → 封装 HTTP 请求
+8. 前端页面       → 列表页 + 编辑弹窗 + 详情弹窗
+```
+
+本章每一步都附有完整代码和详细注释。建议对照项目中 `application/example/` 目录下的实际源码一起阅读，加深理解。
+
+## 模块开发五步模式
+
+模块开发遵循固定的五步模式：
+
+```
+Model → Form → Service → View → URL
+```
+
+| 步骤 | 文件 | 职责 |
+|:----|:----|:----|
+| Model | `models.py` | 定义数据模型，继承 BaseModel，配置表名和字段 |
+| Form | `forms.py` | 定义表单验证，绑定模型，设置中文错误提示 |
+| Service | `services.py` | 实现业务逻辑，所有 CRUD 操作封装为独立函数 |
+| View | `views.py` | 定义 HTTP 视图，组合登录校验、权限控制、操作日志 |
+| URL | `urls.py` | 注册路由，将 URL 路径映射到视图类 |
+
+## 统一响应格式
+
+所有 API 接口使用 `utils/R.py` 提供的统一响应格式：
+
+```python
+# 成功响应
+{"code": 0, "data": {...}, "msg": "操作成功", "ok": true}
+
+# 失败响应
+{"code": 1, "data": null, "msg": "操作失败", "ok": false}
+```
+
+## 总结
+
+模块开发实战以案例管理（Example）为例，完整演示从 Model → Form → Service → View → URL → 权限配置 → 前端 API → 前端页面的全流程。每一步都附有完整代码和详细注释，建议对照实际源码一起阅读。