概述与目标

本章以「岗位管理（Position）」模块为完整案例，手把手演示从零开发一个业务模块的全流程。学完本章后，你将掌握项目中任意模块的开发方式。

你将学到什么

通过本章的实战演练，你将完整经历以下开发环节：

环节	涉及文件	说明
数据模型	models.py	定义数据库表结构
请求校验	schema.py	WTForms 表单验证
数据访问	repository.py	封装数据库查询
业务逻辑	service.py	实现增删改查与业务规则
路由定义	router.py	定义 HTTP 接口
路由注册	v1.py	挂载路由到应用
权限配置	菜单管理	配置权限节点
前端对接	API + 页面 + 路由	前端完整开发

案例模块：岗位管理

选择「岗位管理」作为案例的原因：

1. 结构典型：包含完整的 CRUD + 状态管理 + 删除校验，覆盖大多数业务场景
2. 复杂度适中：字段少（name / status / sort），逻辑清晰，适合入门
3. 依赖简单：仅被 User 模块引用，无复杂关联关系
4. 代码精简：后端 5 个文件 + 前端 3 个文件，总计约 500 行代码

模块文件总览

后端（src/）
├── modules/system/position/
│   ├── models.py          # 数据模型
│   ├── schema.py          # 表单验证
│   ├── repository.py      # 数据访问层
│   ├── service.py         # 业务逻辑层
│   └── router.py          # 路由定义层

前端（ui/src/）
├── api/system/
│   └── position.ts        # API 请求封装
├── views/system/
│   └── position/
│       ├── index.vue      # 主页面：搜索 + 表格 + 操作
│       ├── edit.vue       # 编辑弹窗：新增/编辑表单
│       ├── columns.ts     # 表格列定义
│       └── querySchemas.ts # 搜索表单 Schema
└── router/routes/
    └── system.ts          # 路由配置（追加）

数据库表结构

岗位表 flask_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 由基类 BaseModel 自动提供，业务字段仅需定义 name、status、sort。

开发顺序

建议按以下顺序逐步开发，每完成一步即可验证：

1. models.py     → 建表，确认数据库中有 flask_position 表
2. schema.py     → 定义验证规则（无独立验证方式，后续路由调用时自动校验）
3. repository.py → 数据访问层（通常只需声明类，无需写代码）
4. service.py    → 业务逻辑层（声明差异点 + 自定义方法）
5. router.py     → 路由定义（声明路由 + 权限装饰器）
6. v1.py         → 注册路由（一行代码）
7. 权限配置       → 在菜单管理中添加权限节点
8. 前端对接       → API → 页面 → 路由

温馨提示

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

总结

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