签入版本

2026-09-16 10:11:44 +08:00
parent bf08cf1248
commit 20d8a85989
205 changed files with 34363 additions and 0 deletions
@@ -0,0 +1,175 @@
+# 文档规范
+
+## 概述
+
+良好的文档是项目可维护性的基石。本文规范 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.elevue2.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 文档。