# 文档规范标准

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