# ADR 001: 文档体系重构

> **状态**: 已实施  
> **日期**: 2026-01-18  
> **决策者**: AI Agent + 用户  
> **影响范围**: 全项目文档管理

## 背景

原有文档分类体系存在以下问题：

1. **分类模糊**：
   - "方案"和"修复"界限不清（修复也需要方案设计）
   - "示例"定位模糊（是教程还是 API 文档？）
   - "计划"文档生命周期管理缺失

2. **缺少关键文档类型**：
   - 无架构决策记录（ADR）
   - 无变更日志（Changelog）
   - 缺少"为什么"的记录

3. **目录结构扁平**：
   - 所有文档混在一起
   - 无法按模块（client/admin/server）区分
   - 不利于大规模项目管理

4. **文档过度创建**：
   - 每次执行都创建文档
   - 临时计划文档未归档
   - 文档冗余严重

## 决策

采用 **RFC + ADR + Guides** 三层文档体系，配合模块化目录结构。

### 新目录结构

```
docs/
├── client/              # 前端文档
│   ├── rfcs/           # 技术提案（RFC）
│   ├── adrs/           # 架构决策记录（ADR）
│   ├── guides/         # 使用指南
│   └── changelogs/     # 变更日志
├── admin/              # 管理后台文档
│   ├── rfcs/
│   ├── adrs/
│   ├── guides/
│   └── changelogs/
├── server/             # 后端文档
│   ├── rfcs/
│   ├── adrs/
│   ├── guides/
│   └── changelogs/
├── requirements/       # 全局需求文档
├── architecture/       # 跨模块架构文档
└── .archive/           # 归档目录
    ├── client/
    ├── admin/
    └── server/
```

### 文档类型定义

| 类型           | 用途         | 何时创建                     | 编号规则                     |
| -------------- | ------------ | ---------------------------- | ---------------------------- |
| **RFC**        | 技术方案设计 | 新功能、重构、重大 Bug 修复  | 新功能 001-099，修复 101-199 |
| **ADR**        | 架构决策记录 | 技术选型、框架选择、架构模式 | 001, 002, 003...             |
| **Guides**     | 使用指南     | API 文档、部署流程、最佳实践 | 主题命名                     |
| **Changelogs** | 版本变更     | 每次发布                     | 版本号                       |

### 文件命名规范

```
rfcs/[编号]-[标题].md
例：001-google-oauth-implementation.md
    101-fix-dialog-footer.md

adrs/[编号]-[决策标题].md
例：001-选择-fastapi-框架.md

guides/[主题]-[子主题].md
例：user-service-testing.md
```

## 理由

### 为什么选择 RFC/ADR？

1. **业界标准**：RFC 和 ADR 是经过验证的工程实践
2. **可追溯性**：ADR 记录每个重大决策的上下文和权衡
3. **知识传承**：新成员可以快速了解历史决策
4. **避免重复讨论**：决策一旦记录，不会反复争论

### 为什么模块化？

1. **清晰的边界**：前后端文档分离，职责明确
2. **便于协作**：团队成员只需关注自己的模块
3. **可扩展性**：未来增加新模块（如 mobile）无需重构

### 为什么归档计划文档？

1. **生命周期管理**：计划文档是临时的，执行后应归档
2. **减少噪音**：活跃文档目录保持简洁
3. **历史可查**：归档文档仍可追溯

## 迁移映射

### 原有文档 → 新位置

| 原路径       | 新路径                    | 说明                  |
| ------------ | ------------------------- | --------------------- |
| `docs/方案/` | `docs/{module}/rfcs/`     | 按模块分类            |
| `docs/修复/` | `docs/{module}/rfcs/`     | 合并到 RFC，编号 101+ |
| `docs/示例/` | `docs/{module}/guides/`   | 重命名为 Guides       |
| `docs/计划/` | `docs/.archive/{module}/` | 归档                  |
| `docs/需求/` | `docs/requirements/`      | 保持不变              |

### 迁移统计

- **RFC 文档**: 23 个方案 + 19 个修复 = 42 个
- **Guides 文档**: 3 个示例 + 2 个 Demo = 5 个
- **归档文档**: 22 个计划文档
- **需求文档**: 保持原有结构

## 影响

### 正面影响

✅ **标准化**：符合业界最佳实践  
✅ **可维护性**：清晰的文档分类和生命周期  
✅ **可追溯性**：ADR 记录决策上下文  
✅ **团队协作**：模块化便于分工  
✅ **AI Agent 友好**：结构化文档便于学习和推理

### 负面影响

⚠️ **学习成本**：团队需要学习 RFC/ADR 规范  
⚠️ **迁移成本**：需要迁移现有文档（已完成）

### 风险缓解

- 提供详细的文档模板和示例
- 在 `master-workflow.md` 中明确文档创建规则
- 保留归档文档，确保历史可追溯

## 文档创建规则

### 必须创建（✅）

- 新功能开发
- 重大重构
- 架构决策
- 重要 Bug 修复

### 可选创建（⚠️）

- 简单代码调整
- 样式修改
- 配置微调

### 不需创建（❌）

- 依赖升级（无 Breaking Changes）
- 文案更新
- 注释修改

## 后续优化

1. **文档模板**：为 RFC/ADR/Guides 创建标准模板
2. **自动化**：编写脚本自动生成文档编号
3. **索引生成**：自动生成文档索引和目录
4. **搜索优化**：集成文档搜索工具

## 参考资料

- [RFC 2119 - Key words for use in RFCs](https://www.ietf.org/rfc/rfc2119.txt)
- [Architecture Decision Records (ADR)](https://adr.github.io/)
- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)

## 相关文件

- `.kiro/steering/master-workflow.md` - 更新了文档创建规则
- `docs/` - 新目录结构
- 迁移脚本：`/tmp/migrate_*.sh`

## 总结

通过采用 RFC + ADR + Guides 的三层文档体系，配合模块化目录结构，我们建立了一个标准化、可维护、可追溯的文档管理系统。

这个系统不仅解决了当前的文档混乱问题，还为未来的团队协作和知识传承打下了坚实的基础。

---

**这是一个长期、专业的解决方案。**