# 文档规范

## 概述

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

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

## API 接口文档

Django 项目通过代码注释和文档站点提供 API 文档。所有接口定义在各模块的 `urls.py` 中，视图类的 docstring 描述接口用途。

### View 文档注释

```python
@method_decorator(check_login, name="post")
class ExampleAddView(PermissionRequired, View):
    """
    添加案例视图

    处理POST请求，创建新的案例记录。

    URL: /example/add
    请求方法: POST
    权限要求：sys:example:add

    请求参数（JSON Body）：
    - name: 案例名称（必填，1-100字符）
    - avatar: 案例图片（可选）
    - type: 案例类型（必填，1-4）
    - status: 案例状态（必填，1-正常 2-禁用）
    - sort: 排序权重（必填）
    """
    permission_required = ("sys:example:add",)

    @operation_log(title="案例管理-添加记录", log_type=LogType.ADD)
    def post(self, request):
        result = services.add_example(request)
        return result
```

:::tip 文档层级
- 类 docstring：接口说明（URL、方法、权限、参数）
- 方法 docstring：处理流程说明
- 行内注释：关键逻辑说明
:::

## Form 文档

Django ModelForm 通过 `error_messages` 参数定义中文错误提示，通过 `help_text` 和 `verbose_name` 提供字段说明：

```python
class ExampleForm(forms.ModelForm):
    """案例表单验证类"""

    # 案例名称（必填，1-100字符）
    name = forms.CharField(
        required=True,
        max_length=100,
        error_messages={
            'required': '案例名称不能为空',
            'max_length': '案例名称长度不得超过100个字符',
        }
    )

    # 案例类型（1-类型1 2-类型2 3-类型3 4-类型4）
    type = forms.IntegerField(
        required=True,
        min_value=1,
        max_value=4,
        error_messages={
            'required': '案例类型不能为空',
            'min_value': '案例类型值不能小于1',
            'max_value': '案例类型值不能大于4',
        }
    )

    class Meta:
        model = models.Example
        fields = ['name', 'avatar', 'type', 'status', 'sort']
```

:::tip error_messages 规范
- 必须填写所有验证规则的中文错误提示
- 枚举值说明使用 `值-含义` 格式（如 `1-正常 2-禁用`）
- 有约束条件时在描述中说明（如 `1-100字符`）
:::

## 代码注释规范

### 模块注释

```python
"""
案例管理服务模块
=============================================================

该模块实现了案例管理相关的所有业务逻辑。
包括案例的分页查询、详情查询、添加、更新、删除等功能。
"""
```

### 方法注释

```python
def get_example_page(request):
    """
    查询案例分页数据

    Args:
        request: HttpRequest对象，包含查询参数
            - pageNo: 当前页码（可选，默认为1）
            - pageSize: 每页记录数（可选，默认为PAGE_SIZE）
            - name: 案例名称（可选，模糊查询）

    Returns:
        R: 包含分页数据的JSON响应
    """
```

### 行内注释

```python
# 构建基础查询（只查询未删除的记录）
query = Example.objects.filter(is_delete=False)
```

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

## 文档目录结构

```
wiki/                               # VitePress 文档站
├── zh/                             # 中文文档
│   ├── 1. 了解项目/                # introduction.md, why.md, struct.md, course.md
│   ├── 2. 快速入门/                # volume1/（环境、启动、数据库、Docker）
│   ├── 3. 模块开发实战/            # volume2/（Model→Form→Service→View→URL→前端）
│   ├── 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 接口时，同步更新 View 类的 docstring
- [ ] 新增/修改 Form 字段时，填写 `error_messages` 中文提示
- [ ] 复杂逻辑添加代码注释
- [ ] 重大变更更新 wiki 文档

## 总结

文档规范覆盖 API 文档（View docstring）、Form 文档（error_messages）、代码注释（文件头/模块/方法/行内）。核心原则：文档与代码同步更新，使用中文编写，示例可直接运行。重大变更同步更新 wiki 文档。