# 文档结构说明

**创建日期**：2025-01-28  
**目的**：说明文档结构如何支持现代化AI人机协同模式

---

## 🎯 设计目标

### 核心原则
1. **详细与抽象分离**：设计文档描述"做什么"和"为什么"，实现细节在代码中
2. **问题与知识分离**：待讨论问题单独管理，已确定知识进入知识库
3. **确定性先行**：优先明确约束和规则，再讨论具体实现
4. **全程可控**：每个步骤都有明确的检查点和验证标准
5. **异步有序**：通过文档结构支持异步协作，减少同步沟通成本

---

## 📁 文档结构

```
GO-DESK-2.数据库客户端/
├── README.md                    # 模块总览和快速导航
├── 任务规划.md                  # 紧凑版任务规划（引用详细文档）
├── 文档结构说明.md              # 本文件
│
├── 决策记录/                    # 架构决策记录（ADR）
│   ├── README.md                # ADR说明和模板
│   └── ADR-*.md                 # 具体决策记录
│
├── 知识库/                      # 已确定的知识
│   ├── README.md                # 知识库说明
│   ├── 规范/                    # 约束和规则
│   │   ├── 编码规范.md
│   │   ├── 架构规范.md
│   │   ├── 文档编写规范.md
│   │   └── AI协作检查清单.md
│   ├── 参考/                    # 技术参考
│   │   └── 技术栈.md
│   └── 最佳实践/                # 已验证的最佳实践
│
├── 问题追踪/                    # 待解决问题
│   ├── README.md                # 问题追踪说明
│   ├── 待讨论/                  # 需要讨论的问题
│   ├── 待实现/                  # 已确定但未实现的功能
│   └── 技术债务/                # 技术债务
│
├── 设计文档/                    # 功能设计和架构设计
│   ├── README.md                # 设计文档说明
│   ├── 需求设计/                # 功能需求
│   ├── 架构设计/                # 系统架构
│   └── 功能设计/                # 具体功能设计
│
├── 核对报告/                    # 各种检查报告
│   └── *.md                     # 检查报告文档
│
└── 测试用例/                    # 测试用例和测试检查
    └── README.md                # 测试用例说明
```

---

## 🔄 协作流程

### 对于开发者

#### 开始新功能
1. **读取约束**：查看 [知识库/规范/](./知识库/规范/) 了解编码规范、架构规范
2. **检查决策**：查看 [决策记录/](./决策记录/) 中相关决策
3. **检查问题**：查看 [问题追踪/](./问题追踪/) 中相关问题
4. **参考设计**：查看 [设计文档/](./设计文档/) 中相关设计

#### 遇到问题
1. **查找问题**：在 [问题追踪/](./问题追踪/) 中查找是否已有相关问题
2. **创建问题**：如果没有，创建新问题（待讨论/待实现/技术债务）
3. **讨论问题**：在问题文档中记录讨论过程
4. **记录决策**：如果做出决策，创建ADR记录

#### 做决策
1. **创建ADR**：在 [决策记录/](./决策记录/) 中创建决策记录
2. **记录选项**：列出考虑的选项和理由
3. **记录后果**：记录决策的正面和负面影响
4. **更新文档**：更新相关的设计文档和问题追踪

#### 实现功能
1. **遵循约束**：严格按照 [知识库/规范/](./知识库/规范/) 中的约束
2. **参考设计**：参考 [设计文档/](./设计文档/) 中的设计
3. **检查清单**：使用 [AI协作检查清单](./知识库/规范/AI协作检查清单.md) 检查
4. **更新状态**：更新问题追踪中的状态

---

### 对于AI助手

#### 开始任务
1. **读取约束**：**必须**优先读取 [知识库/规范/](./知识库/规范/) 中的约束
   - [编码规范.md](./知识库/规范/编码规范.md) - 代码编写约束
   - [架构规范.md](./知识库/规范/架构规范.md) - 架构约束
   - [AI协作检查清单.md](./知识库/规范/AI协作检查清单.md) - 协作检查清单
2. **检查决策**：在 [决策记录/](./决策记录/) 中查找相关决策
3. **检查问题**：在 [问题追踪/](./问题追踪/) 中查找待解决问题
4. **参考设计**：在 [设计文档/](./设计文档/) 中查找设计文档

#### 执行任务
1. **遵循约束**：严格按照知识库中的约束执行
2. **记录决策**：如果做出新决策，创建ADR
3. **更新问题**：如果解决问题，更新问题状态
4. **引用规范**：在代码和文档中引用相关规范

#### 完成任务
1. **检查清单**：使用 [AI协作检查清单](./知识库/规范/AI协作检查清单.md) 检查
2. **更新文档**：更新相关的设计文档、问题追踪、决策记录
3. **创建报告**：在 [核对报告/](./核对报告/) 中创建检查报告

---

## 🎯 关键特性

### 1. 确定性先行
- **约束明确**：所有约束都在 [知识库/规范/](./知识库/规范/) 中明确记录
- **决策可查**：所有决策都在 [决策记录/](./决策记录/) 中记录
- **问题分离**：待解决问题在 [问题追踪/](./问题追踪/) 中管理

### 2. 抽象与实现分离
- **设计文档**：只描述"做什么"和"为什么"，不描述"怎么做"
- **实现细节**：在代码中体现，不在设计文档中详细描述
- **知识库**：存储已确定的知识，不存储实现细节

### 3. 问题与知识分离
- **问题**：待讨论、待解决的问题 → [问题追踪/](./问题追踪/)
- **知识**：已确定、已验证的知识 → [知识库/](./知识库/)
- **决策**：已做出的决策 → [决策记录/](./决策记录/)

### 4. 全程可控
- **检查清单**：[AI协作检查清单](./知识库/规范/AI协作检查清单.md) 确保每个步骤都有检查点
- **约束明确**：所有约束都在知识库中明确记录
- **状态追踪**：问题状态明确，可追溯

### 5. 异步有序
- **文档结构**：通过清晰的文档结构支持异步协作
- **引用关系**：通过引用关系建立文档间的关联
- **状态管理**：通过状态管理追踪问题进展

---

## 📊 文档统计

- **总文档数**：39个
- **决策记录**：2个
- **知识库规范**：4个
- **问题追踪**：2个
- **设计文档**：7个
- **核对报告**：14个

---

## 🔗 快速链接

- [README.md](./README.md) - 模块总览
- [任务规划.md](./任务规划.md) - 任务规划
- [知识库/规范/AI协作检查清单.md](./知识库/规范/AI协作检查清单.md) - AI协作检查清单
- [知识库/规范/编码规范.md](./知识库/规范/编码规范.md) - 编码规范
- [知识库/规范/架构规范.md](./知识库/规范/架构规范.md) - 架构规范

---

## 💡 使用建议

1. **首次使用**：先阅读 [README.md](./README.md) 和本文件
2. **开始任务**：使用 [AI协作检查清单](./知识库/规范/AI协作检查清单.md) 作为检查清单
3. **遇到问题**：在 [问题追踪/](./问题追踪/) 中查找或创建问题
4. **做决策**：在 [决策记录/](./决策记录/) 中记录决策
5. **参考规范**：始终参考 [知识库/规范/](./知识库/规范/) 中的约束