绝尘
a5d30684ed
- 拆分 FileSystem.vue 为模块化组件架构 - 新增 Markdown Mermaid 图表渲染支持 - 新增 180+ 编程语言代码高亮 - 修复编辑/预览模式切换渲染问题 - 优化亮色/暗色模式主题适配 - 新增 TypeScript 类型定义
175 lines
7.2 KiB
Markdown
175 lines
7.2 KiB
Markdown
# 文档结构说明
|
||
|
||
**创建日期**：2026-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. **参考规范**：始终参考 [知识库/规范/](./知识库/规范/) 中的约束
|
||
|