# 文档规范

## 概述

良好的文档是项目可维护性的基石。本文规范 API 文档、Pydantic 文档、代码注释等文档的编写标准。

:::tip 文档原则
- 文档与代码同步更新
- 使用中文编写（项目约定）
- 示例代码可直接运行
:::

## API 接口文档

Tornado 自动生成 Swagger 文档，访问地址：

```
http://127.0.0.1:8041/docs        # Swagger UI
http://127.0.0.1:8041/redoc       # ReDoc
http://127.0.0.1:8041/openapi.json # OpenAPI JSON
```

### Handler 文档注释

```python
class PositionAddHandler(BaseHandler):
    @permission_required("sys:position:add")
    @check_demo
    @operation_log("岗位管理", "添加")
    async def post(self):
        """新增岗位

        - **name**: 岗位名称（必填，1-150字符）
        - **status**: 岗位状态（必填，1-在用 2-停用）
        - **sort**: 岗位排序（必填，0-99999）
        """
        return await position_service.add(self)
    """
    return await position_service.add(request, data)
```

:::tip 文档层级
- `summary`：简短标题（显示在接口列表）
- docstring：详细描述（显示在接口详情）
- Pydantic `Field(description=...)`：字段级描述
:::

## Pydantic 文档

Pydantic 模型通过 `Field` 的 `description` 参数自动生成字段文档：

```python
class PositionForm(BaseSchema):
    """岗位创建/编辑表单"""

    name: str = Field(
        ...,
        min_length=1,
        max_length=150,
        description="岗位名称"
    )
    status: int = Field(
        ...,
        ge=1,
        le=2,
        description="岗位状态：1-在用 2-停用"
    )
    sort: int = Field(
        ...,
        ge=0,
        le=99999,
        description="岗位排序"
    )
```

:::tip description 规范
- 必须填写 `description`，用于 Swagger 文档展示
- 枚举值说明使用 `值-含义` 格式（如 `1-在用 2-停用`）
- 有约束条件时在描述中说明（如 `1-150字符`）
:::

## 代码注释规范

### 文件头注释

```python
# +======================================================================
# | 模块: 岗位业务逻辑层
# | 说明: 岗位的增删改查、唯一性校验、状态管理等业务处理
# +======================================================================
```

### 类注释

```python
class PositionService(BaseService(Position]):
    """岗位业务服务类，继承基础服务获得通用 CRUD 能力"""
```

### 方法注释

```python
def _before_delete(self, ids) -> Optional[str]:
    """删除前校验：存在用户引用该岗位时禁止删除，避免用户岗位悬空

    Args:
        ids: 逗号分隔的ID字符串

    Returns:
        None: 放行删除
        str: 拦截删除，返回错误提示
    """
```

### 行内注释

```python
# 自动软删过滤，调用方无需关心 is_delete
query = query.filter(self._soft_col() == 0)
```

:::tip 注释原则
- 解释"为什么"而非"是什么"
- 复杂逻辑必须注释
- 简单代码无需注释
- 注释与代码同步更新
:::

## 文档目录结构

```
document/                           # 补充文档
├── 数据库迁移_runbook.md           # 数据库迁移操作手册
└── djangoadmin.tornado.elevue.sql  # 数据库结构 SQL

wiki/                               # VitePress 文档站
├── zh/                             # 中文文档
│   ├── 1. 了解项目/                # why.md, struct.md, course.md
│   ├── 2. 快速入门/                # volume1/（环境、启动、数据库、Docker）
│   ├── 3. 模块开发实战/            # volume2/
│   ├── 4. 架构设计/                # volume3/
│   ├── 5. 开发指南/                # volume4/
│   │   ├── 5.1 后端核心功能/       #   core/
│   │   ├── 5.2 后端业务模块/       #   business/
│   │   ├── 5.3 后端通用工具/       #   tools/
│   │   ├── 5.4 前端开发/           #   frontend/
│   │   └── 5.5 前后端联调/         #   integration/
│   ├── 6. 代码生成器/              # volume5/
│   ├── 7. 运维部署/                # volume6/
│   └── 8. 规范标准/                # volume7/
```

## 前端文档结构

前端相关文档分布在以下位置：

| 文档 | 路径 | 说明 |
|------|------|------|
| 前端页面规范 | `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 接口时，同步更新 Swagger 注释
- [ ] 新增/修改 Pydantic 字段时，填写 `description`
- [ ] 复杂逻辑添加代码注释
- [ ] 重大变更更新 wiki 文档

## 总结

文档规范覆盖 API 文档（Swagger 自动注释）、Pydantic 文档（Field description）、代码注释（文件头/类/方法/行内）。核心原则：文档与代码同步更新，使用中文编写，示例可直接运行。重大变更同步更新 wiki 文档。