概述与目标

本章以「岗位管理（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-已删除

温馨提示

其中 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 → 页面 → 路由

温馨提示

本章每一步都附有完整代码和详细注释。建议对照项目中 src/modules/system/position/ 目录下的实际源码一起阅读，加深理解。

总结

模块开发实战以岗位管理（position）为例，完整演示从 Model → Schema → Repository → Service → Endpoint → 路由注册 → 权限配置 → 前端 API → 前端页面的全流程。每一步都附有完整代码和详细注释，建议对照实际源码一起阅读。