文档规范

概述

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

文档原则

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

API 接口文档

建议使用 Postman 或 Apifox 等工具维护 API 文档。

Router 文档注释

@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)

文档层级

• 函数名：简短标题
• docstring：详细描述（请求参数、返回值）
• WTForms 字段：字段级描述

WTForms 文档

WTForms 表单通过字段的 label 参数和 validator 的 message 参数提供文档信息：

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之间')
    ])

文档规范

• label：字段中文名，用于前端显示
• message：校验失败提示，用于返回给用户
• 枚举值说明使用 值-含义 格式（如 1-在用 2-停用）
• 有约束条件时在 message 中说明（如 1-150字符）

代码注释规范

文件头注释

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

类注释

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

方法注释

@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} 已被用户引用，无法删除")

行内注释

# 自动软删过滤，调用方无需关心 is_delete
query = query.filter(cls.model.is_delete == 0)

注释原则

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

文档目录结构

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 文档。