# 模块开发实战概述

本章以「案例管理（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 → 前端页面的全流程。每一步都附有完整代码和详细注释，建议对照实际源码一起阅读。