签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,181 @@
+# 文档规范
+
+## 概述
+
+良好的文档是项目可维护性的基石。本文规范 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 文档。