172 lines
6.0 KiB
Markdown
172 lines
6.0 KiB
Markdown
# 文档规范
|
||
|
||
## 概述
|
||
|
||
良好的文档是项目可维护性的基石。本文规范 API 文档、WTForms 文档、代码注释等文档的编写标准。
|
||
|
||
:::tip 文档原则
|
||
- 文档与代码同步更新
|
||
- 使用中文编写（项目约定）
|
||
- 示例代码可直接运行
|
||
:::
|
||
|
||
## API 接口文档
|
||
|
||
建议使用 Postman 或 Apifox 等工具维护 API 文档。
|
||
|
||
### Router 文档注释
|
||
|
||
```python
|
||
@position_blue.route('/add', methods=['POST'])
|
||
@check_permission('sys:position:add')
|
||
def add():
|
||
"""
|
||
新增岗位
|
||
|
||
请求参数:
|
||
- name: 岗位名称（必填，1-150字符）
|
||
- status: 岗位状态（必填，1-在用 2-停用）
|
||
- sort: 岗位排序（必填，0-99999）
|
||
|
||
:return: 添加结果响应
|
||
"""
|
||
from src.modules.system.position.service import add_position
|
||
from src.modules.system.position.schema import PositionForm
|
||
data = parse_request_body(request, PositionForm)
|
||
return add_position(data)
|
||
```
|
||
|
||
:::tip 文档层级
|
||
- 函数名：简短标题
|
||
- docstring：详细描述（请求参数、返回值）
|
||
- WTForms 字段：字段级描述
|
||
:::
|
||
|
||
## WTForms 文档
|
||
|
||
WTForms 表单通过字段的 label 参数和 validator 的 message 参数提供文档信息：
|
||
|
||
```python
|
||
class PositionForm(BaseForm):
|
||
"""岗位创建/编辑表单"""
|
||
|
||
name = StringField('岗位名称', validators=[
|
||
DataRequired(message='岗位名称不能为空'),
|
||
Length(min=1, max=150, message='岗位名称长度必须在1-150个字符之间')
|
||
])
|
||
status = IntegerField('岗位状态', validators=[
|
||
DataRequired(message='岗位状态不能为空'),
|
||
NumberRange(min=1, max=2, message='岗位状态必须是1或2')
|
||
])
|
||
sort = IntegerField('岗位排序', validators=[
|
||
DataRequired(message='岗位排序不能为空'),
|
||
NumberRange(min=0, max=99999, message='岗位排序必须在0-99999之间')
|
||
])
|
||
```
|
||
|
||
:::tip 文档规范
|
||
- label：字段中文名，用于前端显示
|
||
- message：校验失败提示，用于返回给用户
|
||
- 枚举值说明使用 `值-含义` 格式（如 `1-在用 2-停用`）
|
||
- 有约束条件时在 message 中说明（如 `1-150字符`）
|
||
:::
|
||
|
||
## 代码注释规范
|
||
|
||
### 文件头注释
|
||
|
||
```python
|
||
# +======================================================================
|
||
# | 模块: 岗位业务逻辑层
|
||
# | 说明: 岗位的增删改查、唯一性校验、状态管理等业务处理
|
||
# +======================================================================
|
||
```
|
||
|
||
### 类注释
|
||
|
||
```python
|
||
class PositionService(BaseService):
|
||
"""岗位业务服务类，继承基础服务获得通用 CRUD 能力"""
|
||
```
|
||
|
||
### 方法注释
|
||
|
||
```python
|
||
@classmethod
|
||
def before_delete(cls, ids):
|
||
"""
|
||
删除前校验：存在用户引用该岗位时禁止删除
|
||
|
||
Args:
|
||
ids: 待删除的岗位ID列表
|
||
|
||
Raises:
|
||
BizError: 岗位被用户引用时抛出
|
||
"""
|
||
for pid in ids:
|
||
if UserRepository.count_by({'position_id': pid}) > 0:
|
||
raise BizError(f"岗位ID {pid} 已被用户引用，无法删除")
|
||
```
|
||
|
||
### 行内注释
|
||
|
||
```python
|
||
# 自动软删过滤，调用方无需关心 is_delete
|
||
query = query.filter(cls.model.is_delete == 0)
|
||
```
|
||
|
||
:::tip 注释原则
|
||
- 解释"为什么"而非"是什么"
|
||
- 复杂逻辑必须注释
|
||
- 简单代码无需注释
|
||
- 注释与代码同步更新
|
||
:::
|
||
|
||
## 文档目录结构
|
||
|
||
```
|
||
document/ # 补充文档
|
||
├── 数据库迁移_runbook.md # 数据库迁移操作手册
|
||
└── djangoadmin.flask.elevue.sql # 数据库结构 SQL
|
||
|
||
wiki/ # VitePress 文档站
|
||
├── zh/ # 中文文档
|
||
│ ├── 1. 了解项目/ # why.md, struct.md, course.md
|
||
│ ├── 2. 快速入门/ # volume1/（环境、启动、数据库、Docker）
|
||
│ ├── 3. 模块开发实战/ # volume2/（Model→Schema→Repo→Service→Router→前端）
|
||
│ ├── 4. 架构设计/ # volume3/（分层、基类、缓存、安全）
|
||
│ ├── 5. 开发指南/ # volume4/
|
||
│ │ ├── 5.1 后端核心功能/ # core/（JWT、RBAC、字典、日志、限流、事务）
|
||
│ │ ├── 5.2 后端业务模块/ # business/（用户、角色、菜单、文章、任务）
|
||
│ │ ├── 5.3 后端通用工具/ # tools/（上传、Excel、IP/UA、密码、富文本）
|
||
│ │ ├── 5.4 前端开发/ # frontend/（组件、路由、Store、构建）
|
||
│ │ └── 5.5 前后端联调/ # integration/（代理、权限、上传、字典）
|
||
│ ├── 6. 代码生成器/ # volume5/（CLI、Web UI、模板）
|
||
│ ├── 7. 运维部署/ # volume6/（Docker、Nginx、Supervisor、监控）
|
||
│ └── 8. 规范标准/ # volume7/（API 响应、分页、Git、测试、文档）
|
||
```
|
||
|
||
## 前端文档结构
|
||
|
||
前端相关文档分布在以下位置：
|
||
|
||
| 文档 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| 前端页面规范 | `volume7/fe-component.md` | 页面结构、组件使用、命名规范 |
|
||
| 前端 API 规范 | `volume7/fe-api.md` | API 文件组织、函数命名、请求规范 |
|
||
| 公共组件库 | `volume4/frontend/components.md` | 组件列表、Props、Events、用法 |
|
||
| 前端构建 | `volume4/frontend/build.md` | Vite 配置、环境变量、Nginx 部署 |
|
||
| API 层开发 | `volume4/frontend/api.md` | API 层开发指南 |
|
||
| 页面视图开发 | `volume4/frontend/view.md` | 页面视图开发指南 |
|
||
|
||
## 文档更新检查清单
|
||
|
||
- [ ] 新增/修改 API 接口时，同步更新 Router 注释
|
||
- [ ] 新增/修改 WTForms 字段时，填写 label 和 message
|
||
- [ ] 复杂逻辑添加代码注释
|
||
- [ ] 重大变更更新 wiki 文档
|
||
|
||
## 总结
|
||
|
||
文档规范覆盖 API 文档（Router 注释）、WTForms 文档（字段 label 和 message）、代码注释（文件头/类/方法/行内）。核心原则：文档与代码同步更新，使用中文编写，示例可直接运行。重大变更同步更新 wiki 文档。
|