# 概述与目标

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