# 千匠问天项目文档体系

## 文档结构说明

本项目采用系统化的文档管理结构，将文档分为以下几个主要类别：

### 目录结构

```
docs/
├── 00-overview/           # 项目概述
│   ├── README.md         # 项目简介
│   ├── product-vision.md # 产品愿景
│   └── roadmap.md        # 产品路线图
│
├── 01-architecture/      # 架构设计
│   ├── system-design.md  # 系统架构设计
│   ├── tech-stack.md     # 技术栈说明
│   └── data-flow.md      # 数据流设计
│
├── 02-development/       # 开发指南
│   ├── getting-started.md # 开发环境搭建
│   ├── coding-standards.md # 编码规范
│   └── testing-guide.md  # 测试指南
│
├── 03-api/              # API文档
│   ├── gateway-api.md   # Gateway API
│   ├── electron-api.md  # Electron API
│   └── runtime-api.md   # Runtime API
│
├── 04-deployment/       # 部署运维
│   ├── installation.md  # 安装部署
│   ├── configuration.md # 配置管理
│   └── monitoring.md    # 监控维护
│
├── 05-project-memory/   # 项目记忆
│   ├── decisions/       # 技术决策记录
│   ├── history/         # 项目历史记录
│   ├── lessons/         # 经验教训总结
│   └── meeting-notes/   # 会议记录
│
├── 06-plans/            # 项目计划
│   ├── sprint-plans/    # 迭代计划
│   ├── feature-plans/   # 功能计划
│   └── milestone/       # 里程碑
│
├── 07-specs/            # 技术规范
│   ├── api-specs/       # API规范
│   ├── ui-specs/        # UI规范
│   └── data-specs/      # 数据规范
│
└── 08-references/       # 参考资料
    ├── tools.md         # 工具参考
    ├── resources.md     # 学习资源
    └── glossary.md      # 术语表
```

### 各目录详细说明

#### 00-overview/ - 项目概述
- **目的**：为新成员提供项目整体认知
- **内容**：项目背景、目标、范围、产品愿景等
- **目标读者**：所有项目相关人员

#### 01-architecture/ - 架构设计
- **目的**：记录系统架构和技术决策
- **内容**：系统架构图、组件设计、技术选型理由
- **目标读者**：开发人员、架构师

#### 02-development/ - 开发指南
- **目的**：指导开发工作流程
- **内容**：环境搭建、开发流程、代码规范、测试方法
- **目标读者**：开发人员

#### 03-api/ - API文档
- **目的**：记录所有API接口
- **内容**：API端点、参数、返回值、使用示例
- **目标读者**：前后端开发人员

#### 04-deployment/ - 部署运维
- **目的**：指导部署和运维工作
- **内容**：部署步骤、配置管理、监控告警、故障处理
- **目标读者**：运维人员、开发人员

#### 05-project-memory/ - 项目记忆
- **目的**：沉淀项目知识和经验
- **内容**：技术决策记录、项目历史、经验教训、会议记录
- **目标读者**：所有项目成员
- **特别说明**：这是项目的"知识库"，记录为什么做出某些决策，以及从经验中学到了什么

#### 06-plans/ - 项目计划
- **目的**：记录项目计划和进度
- **内容**：迭代计划、功能规划、里程碑
- **目标读者**：项目经理、开发人员

#### 07-specs/ - 技术规范
- **目的**：定义技术标准和规范
- **内容**：API规范、UI设计规范、数据格式规范
- **目标读者**：开发人员、设计师

#### 08-references/ - 参考资料
- **目的**：收集相关参考资料
- **内容**：工具使用指南、学习资源、术语解释
- **目标读者**：所有项目成员

### 文档编写规范

1. **命名规范**：
   - 使用英文小写和连字符，如：`getting-started.md`
   - 中文文档可以保留中文名，但建议有对应的英文名

2. **格式要求**：
   - 使用Markdown格式
   - 包含必要的元信息（创建时间、作者、更新记录）
   - 保持结构清晰，使用适当的标题层级

3. **更新机制**：
   - 文档随代码变更而更新
   - 重要决策需要及时记录到项目记忆中
   - 定期回顾和整理文档

### 迁移计划

现有文档将按以下规则迁移到新结构：

1. **第一阶段**：创建新目录结构，建立索引文档
2. **第二阶段**：分类迁移现有文档
3. **第三阶段**：补充缺失的文档内容
4. **第四阶段**：建立文档维护流程

### 贡献指南

1. 新文档应放置在合适的目录中
2. 更新现有文档时，保持结构和格式一致
3. 重要变更需要记录变更原因
4. 定期参与文档评审和维护

---

*最后更新：2026-05-28*
*文档版本：v1.0*