# 文档规范

## 概述

良好的文档是项目可维护性的基石。本文规范 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.naivevue.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 文档。