96 lines
3.9 KiB
Markdown
96 lines
3.9 KiB
Markdown
# 概述与目标
|
||
|
||
本章以「岗位管理（Position）」模块为完整案例，手把手演示从零开发一个业务模块的全流程。学完本章后，你将掌握项目中任意模块的开发方式。
|
||
|
||
## 你将学到什么
|
||
|
||
通过本章的实战演练，你将完整经历以下开发环节：
|
||
|
||
| 环节 | 涉及文件 | 说明 |
|
||
|:----|:----|:----|
|
||
| 数据模型 | `models.py` | 定义数据库表结构 |
|
||
| 请求校验 | `schemas.py` | Pydantic 表单验证 |
|
||
| 数据访问 | `repository.py` | 封装数据库查询 |
|
||
| 业务逻辑 | `service.py` | 实现增删改查与业务规则 |
|
||
| API 端点 | `endpoints/position.py` | 定义 HTTP 接口 |
|
||
| 路由注册 | `router.py` | 挂载路由到应用 |
|
||
| 权限配置 | 菜单管理 | 配置权限节点 |
|
||
| 前端对接 | API + 页面 + 路由 | 前端完整开发 |
|
||
|
||
## 案例模块：岗位管理
|
||
|
||
选择「岗位管理」作为案例的原因：
|
||
|
||
1. **结构典型**：包含完整的 CRUD + 状态管理 + 删除校验，覆盖大多数业务场景
|
||
2. **复杂度适中**：字段少（name / status / sort），逻辑清晰，适合入门
|
||
3. **依赖简单**：仅被 User 模块引用，无复杂关联关系
|
||
4. **代码精简**：后端 4 个文件 + 前端 3 个文件，总计约 500 行代码
|
||
|
||
## 模块文件总览
|
||
|
||
```
|
||
后端（src/）
|
||
├── modules/system/position/
|
||
│ ├── models.py # 数据模型
|
||
│ ├── schemas.py # 表单验证
|
||
│ ├── repository.py # 数据访问层
|
||
│ └── service.py # 业务逻辑层
|
||
└── api/v1/endpoints/
|
||
└── position.py # API 端点层
|
||
|
||
前端（ui/src/）
|
||
├── api/system/
|
||
│ └── position.ts # API 请求封装
|
||
├── views/system/
|
||
│ └── position/
|
||
│ ├── index.vue # 主页面：搜索 + 表格 + 操作
|
||
│ ├── edit.vue # 编辑弹窗：新增/编辑表单
|
||
│ ├── columns.ts # 表格列定义
|
||
│ └── querySchemas.ts # 搜索表单 Schema
|
||
└── router/routes/
|
||
└── system.ts # 路由配置（追加）
|
||
```
|
||
|
||
## 数据库表结构
|
||
|
||
岗位表 `fastapi_position` 结构如下：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|:----|:----|:----|
|
||
| id | int | 主键，自增 |
|
||
| name | varchar(255) | 岗位名称 |
|
||
| status | int | 状态：1-在用 2-停用 |
|
||
| sort | int | 排序号 |
|
||
| create_user | varchar(255) | 创建人 |
|
||
| create_time | datetime | 创建时间 |
|
||
| update_user | varchar(255) | 更新人 |
|
||
| update_time | datetime | 更新时间 |
|
||
| is_delete | int | 软删除标记：0-正常 1-已删除 |
|
||
|
||
:::tip 温馨提示
|
||
其中 `id`、`create_user`、`create_time`、`update_user`、`update_time`、`is_delete` 由基类 `base_model` 自动提供，业务字段仅需定义 `name`、`status`、`sort`。
|
||
:::
|
||
|
||
## 开发顺序
|
||
|
||
建议按以下顺序逐步开发，每完成一步即可验证：
|
||
|
||
```
|
||
1. models.py → 建表，确认数据库中有 fastapi_position 表
|
||
2. schemas.py → 定义验证规则（无独立验证方式，后续端点调用时自动校验）
|
||
3. repository.py → 数据访问层（通常只需声明类，无需写代码）
|
||
4. service.py → 业务逻辑层（声明差异点 + 自定义方法）
|
||
5. endpoint.py → API 端点（声明路由 + 权限装饰器）
|
||
6. router.py → 注册路由（一行代码）
|
||
7. 权限配置 → 在菜单管理中添加权限节点
|
||
8. 前端对接 → API → 页面 → 路由
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
本章每一步都附有完整代码和详细注释。建议对照项目中 `src/modules/system/position/` 目录下的实际源码一起阅读，加深理解。
|
||
:::
|
||
|
||
## 总结
|
||
|
||
模块开发实战以岗位管理（position）为例，完整演示从 Model → Schema → Repository → Service → Endpoint → 路由注册 → 权限配置 → 前端 API → 前端页面的全流程。每一步都附有完整代码和详细注释，建议对照实际源码一起阅读。
|