153 lines
3.6 KiB
Markdown
153 lines
3.6 KiB
Markdown
|
# 文档规范标准
|
|||
|
|
|
|||
|
|
## 1. 目录命名规范
|
|||
|
|
|
|||
|
|
### 1.1 目录命名规则
|
|||
|
|
|
|||
|
|
| 类别 | 格式 | 示例 | 说明 |
|
|||
|
|
|------|------|------|------|
|
|||
|
|
| 主目录 | 中文或英文 | `docs/Business/` | 业务线/域 |
|
|||
|
|
| 子目录 | 数字前缀+英文 | `docs/Business/01_Product/` | 模块序号 |
|
|||
|
|
| 归档目录 | `ARCHIVE/` | `docs/ARCHIVE/` | 历史文档 |
|
|||
|
|
|
|||
|
|
### 1.2 目录大小写规则
|
|||
|
|
|
|||
|
|
- **全部使用小写**：所有目录名必须使用小写字母
|
|||
|
|
- **分隔符**：使用 `-` 或 `_`，保持一致
|
|||
|
|
- **示例**：
|
|||
|
|
- ✅ `docs/business/`, `docs/architecture/`
|
|||
|
|
- ❌ `docs/Business/`, `docs/ARCHIVE/`
|
|||
|
|
|
|||
|
|
### 1.3 主目录结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
docs/
|
|||
|
|
├── business/ # 业务文档
|
|||
|
|
├── architecture/ # 架构文档
|
|||
|
|
├── api/ # API文档
|
|||
|
|
├── rules/ # 规范文档
|
|||
|
|
├── tasks/ # 任务文档
|
|||
|
|
├── loops/ # 业务闭环文档
|
|||
|
|
└── services/ # 服务文档
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 2. 文件命名规范
|
|||
|
|
|
|||
|
|
### 2.1 命名规则
|
|||
|
|
|
|||
|
|
| 类别 | 格式 | 示例 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| 索引文件 | `index.md` | `business/index.md` |
|
|||
|
|
| 模块文档 | `NN_Name.md` | `01_Product.md` |
|
|||
|
|
| 规范文档 | `kebab-case.md` | `code-quality-rules.md` |
|
|||
|
|
| 报告文档 | `YYYY-MM-DD_Name.md` | `2026-03-20_Code_Review.md` |
|
|||
|
|
|
|||
|
|
### 2.2 文件后缀
|
|||
|
|
|
|||
|
|
- 统一使用 `.md` 后缀
|
|||
|
|
- 禁止使用 `.md_txt`、`.markdown` 等变体
|
|||
|
|
|
|||
|
|
### 2.3 命名大小写
|
|||
|
|
|
|||
|
|
- **目录**: 全部小写
|
|||
|
|
- **文件**: 首字母大写，驼峰命名（除非是 `index.md`）
|
|||
|
|
|
|||
|
|
## 3. 索引文件规范
|
|||
|
|
|
|||
|
|
### 3.1 索引文件命名
|
|||
|
|
|
|||
|
|
- **标准索引**: `index.md`
|
|||
|
|
- **禁止**: `_index.md`、`00_Index.md`、`INDEX.md`
|
|||
|
|
|
|||
|
|
### 3.2 索引文件位置
|
|||
|
|
|
|||
|
|
- 每个目录必须有 `index.md` 作为入口
|
|||
|
|
- 索引文件必须包含该目录内容的概览和链接
|
|||
|
|
|
|||
|
|
### 3.3 索引文件格式
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# 模块名称
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
- [子模块1](01_SubModule/) - 简短描述
|
|||
|
|
- [子模块2](02_SubModule/) - 简短描述
|
|||
|
|
|
|||
|
|
## 内容概览
|
|||
|
|
|
|||
|
|
...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 4. 文档格式规范
|
|||
|
|
|
|||
|
|
### 4.1 标题层级
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# 一级标题 (页面标题)
|
|||
|
|
## 二级标题 (主要章节)
|
|||
|
|
### 三级标题 (子章节)
|
|||
|
|
#### 四级标题 (细节内容)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4.2 代码块
|
|||
|
|
|
|||
|
|
````markdown
|
|||
|
|
```typescript
|
|||
|
|
// 代码内容
|
|||
|
|
const example = 'code';
|
|||
|
|
```
|
|||
|
|
````
|
|||
|
|
|
|||
|
|
### 4.3 表格格式
|
|||
|
|
|
|||
|
|
````markdown
|
|||
|
|
| 列1 | 列2 | 列3 |
|
|||
|
|
|-----|-----|-----|
|
|||
|
|
| 内容 | 内容 | 内容 |
|
|||
|
|
````
|
|||
|
|
|
|||
|
|
## 5. 常见错误
|
|||
|
|
|
|||
|
|
### 5.1 已识别的格式错误
|
|||
|
|
|
|||
|
|
| 错误类型 | 错误示例 | 正确示例 |
|
|||
|
|
|----------|----------|----------|
|
|||
|
|
| 大小写错误 | `ARCHIVE/00_Business/` | `archive/00_business/` |
|
|||
|
|
| 索引文件命名 | `_index.md` | `index.md` |
|
|||
|
|
| 文件后缀 | `document.md_txt` | `document.md` |
|
|||
|
|
| 中文目录 | `文档/` | `documents/` |
|
|||
|
|
|
|||
|
|
### 5.2 需要修复的目录
|
|||
|
|
|
|||
|
|
| 当前路径 | 建议路径 |
|
|||
|
|
|----------|----------|
|
|||
|
|
| `docs/ARCHIVE/` | `docs/archive/` |
|
|||
|
|
| `docs/LOOPS/` | `docs/loops/` |
|
|||
|
|
| `docs/SERVICES/` | `docs/services/` |
|
|||
|
|
| `docs/TASKS/` | `docs/tasks/` |
|
|||
|
|
| `docs/RULES/` | `docs/rules/` |
|
|||
|
|
| `docs/API_Documentations/` | `docs/api/` |
|
|||
|
|
|
|||
|
|
## 6. 迁移计划
|
|||
|
|
|
|||
|
|
### 阶段1：创建规范文件
|
|||
|
|
- [x] 创建 `docs/rules/documentation.md`
|
|||
|
|
|
|||
|
|
### 阶段2：识别需要迁移的目录
|
|||
|
|
- [x] 识别所有大小写不一致的目录
|
|||
|
|
- [x] 识别所有命名不规范的目录
|
|||
|
|
|
|||
|
|
### 阶段3：执行迁移（2026-03-26）
|
|||
|
|
- [x] 重命名目录为小写（archive, api, loops, rules, services, tasks）
|
|||
|
|
- [x] 更新所有相关引用
|
|||
|
|
|
|||
|
|
### 阶段4：验证
|
|||
|
|
- [x] 检查所有链接是否有效
|
|||
|
|
- [x] 验证文档结构完整性
|
|||
|
|
|
|||
|
|
## 7. 参考
|
|||
|
|
|
|||
|
|
- 项目术语表: [TERMINOLOGY.md](../rules/TERMINOLOGY.md)
|
|||
|
|
- 业务闭环: [loops/_index.md](../loops/_index.md)
|