1550 lines
52 KiB
Markdown
1550 lines
52 KiB
Markdown
# FischerX 文档管理规范
|
||
|
||
> **项目名称**: FischerX 开发底座
|
||
> **文档版本**: v1.0.0
|
||
> **创建日期**: 2026-05-24
|
||
> **文档负责人**: 技术负责人
|
||
> **文档状态**: 正式发布
|
||
> **适用范围**: FischerX项目全体开发人员、测试人员、运维人员、产品经理
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [一、文档管理概述](#一文档管理概述)
|
||
- [1.1 目的](#11-目的)
|
||
- [1.2 适用范围](#12-适用范围)
|
||
- [1.3 文档管理原则](#13-文档管理原则)
|
||
- [1.4 角色与职责](#14-角色与职责)
|
||
- [二、文档目录结构设计](#二文档目录结构设计)
|
||
- [2.1 整体目录结构](#21-整体目录结构)
|
||
- [2.2 目录说明](#22-目录说明)
|
||
- [2.3 文档分类体系](#23-文档分类体系)
|
||
- [三、文档分类和职责](#三文档分类和职责)
|
||
- [3.1 架构文档](#31-架构文档)
|
||
- [3.2 需求文档](#32-需求文档)
|
||
- [3.3 设计文档](#33-设计文档)
|
||
- [3.4 开发文档](#34-开发文档)
|
||
- [3.5 API文档](#35-api文档)
|
||
- [3.6 测试文档](#36-测试文档)
|
||
- [3.7 部署文档](#37-部署文档)
|
||
- [3.8 运维文档](#38-运维文档)
|
||
- [3.9 用户文档](#39-用户文档)
|
||
- [四、文档编写规范](#四文档编写规范)
|
||
- [4.1 文档模板](#41-文档模板)
|
||
- [4.2 命名规范](#42-命名规范)
|
||
- [4.3 格式规范](#43-格式规范)
|
||
- [4.4 版本控制](#44-版本控制)
|
||
- [4.5 图表规范](#45-图表规范)
|
||
- [五、文档维护流程](#五文档维护流程)
|
||
- [5.1 文档创建流程](#51-文档创建流程)
|
||
- [5.2 文档更新流程](#52-文档更新流程)
|
||
- [5.3 文档审核流程](#53-文档审核流程)
|
||
- [5.4 文档发布流程](#54-文档发布流程)
|
||
- [5.5 文档归档流程](#55-文档归档流程)
|
||
- [5.6 文档过期处理](#56-文档过期处理)
|
||
- [六、文档与代码同步策略](#六文档与代码同步策略)
|
||
- [6.1 同步原则](#61-同步原则)
|
||
- [6.2 代码变更时同步更新文档](#62-代码变更时同步更新文档)
|
||
- [6.3 CI/CD流程中集成文档检查](#63-cicd流程中集成文档检查)
|
||
- [6.4 文档版本与代码版本对应](#64-文档版本与代码版本对应)
|
||
- [6.5 自动化文档生成](#65-自动化文档生成)
|
||
- [七、文档工具链](#七文档工具链)
|
||
- [7.1 文档生成工具](#71-文档生成工具)
|
||
- [7.2 文档检查工具](#72-文档检查工具)
|
||
- [7.3 文档搜索工具](#73-文档搜索工具)
|
||
- [7.4 文档协作平台](#74-文档协作平台)
|
||
- [7.5 工具配置示例](#75-工具配置示例)
|
||
- [八、文档质量保障](#八文档质量保障)
|
||
- [8.1 文档审查清单](#81-文档审查清单)
|
||
- [8.2 文档质量指标](#82-文档质量指标)
|
||
- [8.3 定期文档审计](#83-定期文档审计)
|
||
- [8.4 文档反馈机制](#84-文档反馈机制)
|
||
- [九、附录](#九附录)
|
||
- [9.1 文档状态说明](#91-文档状态说明)
|
||
- [9.2 版本号规范](#92-版本号规范)
|
||
- [9.3 术语表](#93-术语表)
|
||
- [9.4 参考文档](#94-参考文档)
|
||
|
||
---
|
||
|
||
## 一、文档管理概述
|
||
|
||
### 1.1 目的
|
||
|
||
建立FischerX项目文档管理体系，确保文档的完整性、准确性、一致性和可维护性，实现文档与代码同步更新，提升团队协作效率和项目可维护性。
|
||
|
||
### 1.2 适用范围
|
||
|
||
本规范适用于FischerX项目的所有文档，包括但不限于：
|
||
- 架构设计文档
|
||
- 需求规格文档
|
||
- 技术设计文档
|
||
- 开发指南文档
|
||
- API接口文档
|
||
- 测试文档
|
||
- 部署运维文档
|
||
- 用户使用文档
|
||
|
||
### 1.3 文档管理原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| **文档即代码** | 文档与代码同等重要，使用Git进行版本管理 |
|
||
| **单一数据源** | 每个信息只在一个地方维护，避免信息不一致 |
|
||
| **及时更新** | 代码变更时同步更新相关文档 |
|
||
| **清晰易懂** | 文档结构清晰，语言简洁，示例完整 |
|
||
| **可追溯性** | 文档变更可追溯，版本可回溯 |
|
||
| **自动化优先** | 尽可能使用工具自动生成文档 |
|
||
|
||
### 1.4 角色与职责
|
||
|
||
| 角色 | 职责 | 权限 |
|
||
|------|------|------|
|
||
| **文档负责人** | 制定文档规范，审核重要文档，组织文档审计 | 文档规范制定、文档审核、文档归档 |
|
||
| **技术负责人** | 审核架构文档、设计文档、API文档 | 技术文档审核、技术决策记录 |
|
||
| **开发人员** | 编写和更新开发文档、API文档、设计文档 | 编写、更新自己负责的文档 |
|
||
| **测试人员** | 编写和更新测试文档 | 测试文档编写和更新 |
|
||
| **运维人员** | 编写和更新部署文档、运维文档 | 部署运维文档编写和更新 |
|
||
| **产品经理** | 编写和更新需求文档、用户文档 | 需求文档编写和更新 |
|
||
| **全体团队成员** | 阅读文档，反馈文档问题 | 文档反馈、文档建议 |
|
||
|
||
---
|
||
|
||
## 二、文档目录结构设计
|
||
|
||
### 2.1 整体目录结构
|
||
|
||
```
|
||
FischerX/
|
||
├── docs/ # 文档根目录
|
||
│ ├── architecture/ # 架构文档
|
||
│ │ ├── overview.md # 整体架构概述
|
||
│ │ ├── technology-selection.md # 技术选型文档
|
||
│ │ ├── module-design.md # 模块划分设计
|
||
│ │ ├── design-decisions/ # 架构决策记录（ADR）
|
||
│ │ │ ├── ADR-001-monorepo-structure.md
|
||
│ │ │ ├── ADR-002-nestjs-framework.md
|
||
│ │ │ └── ADR-003-postgresql-database.md
|
||
│ │ └── diagrams/ # 架构图
|
||
│ │ ├── system-architecture.png
|
||
│ │ └── module-dependency.png
|
||
│ │
|
||
│ ├── requirements/ # 需求文档
|
||
│ │ ├── product/ # 产品需求
|
||
│ │ │ ├── prd-v1.0.md # 产品需求文档
|
||
│ │ │ └── user-stories/ # 用户故事
|
||
│ │ │ ├── auth-user-stories.md
|
||
│ │ │ └── payment-user-stories.md
|
||
│ │ ├── features/ # 功能规格
|
||
│ │ │ ├── auth-spec.md # 认证功能规格
|
||
│ │ │ ├── payment-spec.md # 支付功能规格
|
||
│ │ │ └── permission-spec.md # 权限功能规格
|
||
│ │ └── changelog/ # 需求变更记录
|
||
│ │ └── requirements-changelog.md
|
||
│ │
|
||
│ ├── design/ # 设计文档
|
||
│ │ ├── database/ # 数据库设计
|
||
│ │ │ ├── schema-design.md # 数据库Schema设计
|
||
│ │ │ ├── migration-guide.md # 数据库迁移指南
|
||
│ │ │ └── er-diagrams/ # ER图
|
||
│ │ ├── api/ # API设计
|
||
│ │ │ ├── api-design-guidelines.md
|
||
│ │ │ └── restful-conventions.md
|
||
│ │ ├── ui/ # UI设计
|
||
│ │ │ ├── design-system.md # 设计系统
|
||
│ │ │ ├── component-library.md # 组件库设计
|
||
│ │ │ └── assets/ # UI设计资源
|
||
│ │ └── integration/ # 集成设计
|
||
│ │ ├── wechat-integration.md
|
||
│ │ └── alipay-integration.md
|
||
│ │
|
||
│ ├── development/ # 开发文档
|
||
│ │ ├── quick-start.md # 快速开始指南
|
||
│ │ ├── standards/ # 开发规范
|
||
│ │ │ ├── coding-standards.md # 编码规范
|
||
│ │ │ ├── git-workflow.md # Git工作流
|
||
│ │ │ ├── commit-conventions.md # 提交规范
|
||
│ │ │ └── code-review-guide.md # 代码审查指南
|
||
│ │ ├── best-practices/ # 最佳实践
|
||
│ │ │ ├── react-best-practices.md
|
||
│ │ │ ├── nestjs-best-practices.md
|
||
│ │ │ └── database-best-practices.md
|
||
│ │ ├── guides/ # 开发指南
|
||
│ │ │ ├── adding-new-module.md # 如何添加新模块
|
||
│ │ │ ├── adding-new-api.md # 如何添加新API
|
||
│ │ │ └── debugging-guide.md # 调试指南
|
||
│ │ └── faq.md # 常见问题解答
|
||
│ │
|
||
│ ├── api/ # API文档
|
||
│ │ ├── README.md # API文档索引
|
||
│ │ ├── authentication/ # 认证相关API
|
||
│ │ │ ├── login.md
|
||
│ │ │ ├── register.md
|
||
│ │ │ └── token-refresh.md
|
||
│ │ ├── user/ # 用户相关API
|
||
│ │ │ ├── get-user.md
|
||
│ │ │ ├── update-user.md
|
||
│ │ │ └── delete-user.md
|
||
│ │ ├── payment/ # 支付相关API
|
||
│ │ │ ├── create-order.md
|
||
│ │ │ ├── query-order.md
|
||
│ │ │ └── refund.md
|
||
│ │ ├── error-codes.md # 错误码说明
|
||
│ │ └── sdk/ # SDK文档
|
||
│ │ ├── javascript-sdk.md
|
||
│ │ └── typescript-sdk.md
|
||
│ │
|
||
│ ├── testing/ # 测试文档
|
||
│ │ ├── test-plan.md # 测试计划
|
||
│ │ ├── test-strategy.md # 测试策略
|
||
│ │ ├── test-cases/ # 测试用例
|
||
│ │ │ ├── auth-test-cases.md
|
||
│ │ │ ├── payment-test-cases.md
|
||
│ │ │ └── permission-test-cases.md
|
||
│ │ ├── test-reports/ # 测试报告
|
||
│ │ │ ├── test-report-v1.0.md
|
||
│ │ │ └── performance-test-report.md
|
||
│ │ └── coverage-report.md # 覆盖率报告
|
||
│ │
|
||
│ ├── deployment/ # 部署文档
|
||
│ │ ├── environment-setup.md # 环境配置
|
||
│ │ ├── docker-guide.md # Docker部署指南
|
||
│ │ ├── kubernetes-guide.md # Kubernetes部署指南
|
||
│ │ ├── aliyun-guide.md # 阿里云部署指南
|
||
│ │ ├── ci-cd-pipeline.md # CI/CD流程
|
||
│ │ └── migration-guide.md # 数据迁移指南
|
||
│ │
|
||
│ ├── operations/ # 运维文档
|
||
│ │ ├── monitoring/ # 监控告警
|
||
│ │ │ ├── monitoring-setup.md # 监控配置
|
||
│ │ │ ├── alert-rules.md # 告警规则
|
||
│ │ │ └── dashboard-guide.md # 仪表盘配置
|
||
│ │ ├── logging/ # 日志管理
|
||
│ │ │ ├── log-collection.md # 日志收集
|
||
│ │ │ ├── log-analysis.md # 日志分析
|
||
│ │ │ └── log-retention.md # 日志留存策略
|
||
│ │ ├── troubleshooting/ # 故障处理
|
||
│ │ │ ├── common-issues.md # 常见问题排查
|
||
│ │ │ ├── emergency-response.md # 应急响应流程
|
||
│ │ │ └── incident-reports/ # 故障报告
|
||
│ │ └── backup-restore/ # 备份恢复
|
||
│ │ ├── backup-strategy.md # 备份策略
|
||
│ │ └── restore-guide.md # 恢复指南
|
||
│ │
|
||
│ ├── user/ # 用户文档
|
||
│ │ ├── getting-started.md # 入门指南
|
||
│ │ ├── user-manual.md # 用户手册
|
||
│ │ ├── usage-guide/ # 使用指南
|
||
│ │ │ ├── monorepo-usage.md # Monorepo模式使用
|
||
│ │ │ ├── standalone-usage.md # 独立项目模式使用
|
||
│ │ │ └── api-service-usage.md # API服务模式使用
|
||
│ │ ├── cli-guide.md # CLI工具使用指南
|
||
│ │ └── faq.md # 用户常见问题
|
||
│ │
|
||
│ ├── templates/ # 文档模板
|
||
│ │ ├── architecture-template.md # 架构文档模板
|
||
│ │ ├── design-template.md # 设计文档模板
|
||
│ │ ├── api-template.md # API文档模板
|
||
│ │ ├── test-case-template.md # 测试用例模板
|
||
│ │ └── adr-template.md # 架构决策记录模板
|
||
│ │
|
||
│ └── README.md # 文档索引和导航
|
||
│
|
||
├── apps/ # 应用层
|
||
├── packages/ # 共享包
|
||
├── services/ # 后端服务
|
||
├── infra/ # 基础设施
|
||
├── tools/ # 开发工具
|
||
└── package.json # Monorepo配置
|
||
```
|
||
|
||
### 2.2 目录说明
|
||
|
||
| 目录 | 用途 | 负责人 | 更新频率 |
|
||
|------|------|--------|---------|
|
||
| `docs/architecture/` | 架构设计、技术选型、模块划分、架构决策 | 技术负责人 | 重大变更时 |
|
||
| `docs/requirements/` | 产品需求、功能规格、用户故事、需求变更 | 产品经理 | 迭代周期 |
|
||
| `docs/design/` | 数据库设计、API设计、UI设计、集成设计 | 开发人员 | 功能开发时 |
|
||
| `docs/development/` | 开发规范、快速开始、最佳实践、FAQ | 全体开发 | 持续更新 |
|
||
| `docs/api/` | API接口文档、SDK文档、错误码说明 | 后端开发 | API变更时 |
|
||
| `docs/testing/` | 测试计划、测试用例、测试报告、覆盖率报告 | 测试人员 | 测试周期 |
|
||
| `docs/deployment/` | 部署指南、环境配置、CI/CD流程、数据迁移 | DevOps | 部署变更时 |
|
||
| `docs/operations/` | 监控告警、日志管理、故障处理、备份恢复 | 运维人员 | 运维变更时 |
|
||
| `docs/user/` | 用户手册、使用指南、CLI工具指南、FAQ | 产品经理+开发 | 功能发布时 |
|
||
| `docs/templates/` | 各类文档模板 | 文档负责人 | 按需更新 |
|
||
|
||
### 2.3 文档分类体系
|
||
|
||
文档按以下维度分类：
|
||
|
||
#### 2.3.1 按受众分类
|
||
|
||
| 分类 | 目标受众 | 文档类型 |
|
||
|------|---------|---------|
|
||
| **技术文档** | 开发人员、架构师 | 架构、设计、开发、API文档 |
|
||
| **测试文档** | 测试人员、开发人员 | 测试计划、测试用例、测试报告 |
|
||
| **运维文档** | 运维人员、DevOps | 部署、监控、故障处理文档 |
|
||
| **业务文档** | 产品经理、业务人员 | 需求文档、用户故事 |
|
||
| **用户文档** | 最终用户、使用者 | 用户手册、使用指南、FAQ |
|
||
|
||
#### 2.3.2 按生命周期分类
|
||
|
||
| 阶段 | 文档类型 | 示例 |
|
||
|------|---------|------|
|
||
| **规划阶段** | 需求文档、架构文档 | PRD、架构设计、技术选型 |
|
||
| **设计阶段** | 设计文档 | 数据库设计、API设计、UI设计 |
|
||
| **开发阶段** | 开发文档、API文档 | 开发规范、API接口文档 |
|
||
| **测试阶段** | 测试文档 | 测试计划、测试用例、测试报告 |
|
||
| **部署阶段** | 部署文档 | 部署指南、CI/CD流程 |
|
||
| **运维阶段** | 运维文档 | 监控配置、故障处理、备份恢复 |
|
||
| **使用阶段** | 用户文档 | 用户手册、使用指南、FAQ |
|
||
|
||
#### 2.3.3 按稳定性分类
|
||
|
||
| 分类 | 说明 | 更新频率 | 示例 |
|
||
|------|------|---------|------|
|
||
| **稳定文档** | 内容相对稳定，变更较少 | 季度/半年 | 架构概述、开发规范 |
|
||
| **活跃文档** | 内容频繁更新 | 每周/每月 | API文档、FAQ |
|
||
| **临时文档** | 一次性或短期使用 | 按需 | 故障报告、测试报告 |
|
||
|
||
---
|
||
|
||
## 三、文档分类和职责
|
||
|
||
### 3.1 架构文档
|
||
|
||
**目录**: `docs/architecture/`
|
||
|
||
**职责**: 记录系统整体架构设计、技术选型决策、模块划分和架构演进。
|
||
|
||
**文档清单**:
|
||
|
||
| 文档 | 说明 | 负责人 | 更新时机 |
|
||
|------|------|--------|---------|
|
||
| `overview.md` | 整体架构概述，包含架构图、层次结构、技术栈 | 技术负责人 | 架构重大变更 |
|
||
| `technology-selection.md` | 技术选型对比和决策依据 | 技术负责人 | 技术栈变更 |
|
||
| `module-design.md` | 模块划分、模块职责、模块依赖关系 | 技术负责人 | 模块结构调整 |
|
||
| `design-decisions/` | 架构决策记录（ADR），记录重要技术决策 | 技术负责人 | 每次重要决策 |
|
||
|
||
**架构决策记录（ADR）规范**:
|
||
|
||
每个ADR文件应包含：
|
||
- **标题**: ADR-XXX-简短描述
|
||
- **状态**: 提议/接受/废弃/替代
|
||
- **上下文**: 决策背景和问题描述
|
||
- **决策**: 具体决策内容
|
||
- **后果**: 决策带来的正面和负面影响
|
||
- **替代方案**: 考虑过的其他方案
|
||
|
||
### 3.2 需求文档
|
||
|
||
**目录**: `docs/requirements/`
|
||
|
||
**职责**: 记录产品需求、功能规格、用户故事和需求变更。
|
||
|
||
**文档清单**:
|
||
|
||
| 文档 | 说明 | 负责人 | 更新时机 |
|
||
|------|------|--------|---------|
|
||
| `product/prd-v*.md` | 产品需求文档，包含产品愿景、目标、功能列表 | 产品经理 | 版本发布 |
|
||
| `product/user-stories/` | 用户故事，按模块分类 | 产品经理 | 迭代规划 |
|
||
| `features/*-spec.md` | 功能规格说明，详细描述功能需求 | 产品经理+开发 | 功能开发前 |
|
||
| `changelog/` | 需求变更记录，跟踪需求变更历史 | 产品经理 | 需求变更 |
|
||
|
||
**需求文档规范**:
|
||
|
||
每个需求文档应包含：
|
||
- **需求背景**: 为什么需要这个功能
|
||
- **用户故事**: 作为[角色]，我希望[功能]，以便[价值]
|
||
- **功能描述**: 详细的功能说明
|
||
- **验收标准**: 功能完成的判断标准
|
||
- **优先级**: P0/P1/P2
|
||
- **依赖关系**: 与其他功能的依赖
|
||
- **非功能需求**: 性能、安全、兼容性要求
|
||
|
||
### 3.3 设计文档
|
||
|
||
**目录**: `docs/design/`
|
||
|
||
**职责**: 记录数据库设计、API设计、UI设计和第三方集成设计。
|
||
|
||
**文档清单**:
|
||
|
||
| 文档 | 说明 | 负责人 | 更新时机 |
|
||
|------|------|--------|---------|
|
||
| `database/schema-design.md` | 数据库Schema设计，包含表结构、索引、关系 | 后端开发 | 数据库变更 |
|
||
| `database/migration-guide.md` | 数据库迁移指南，包含迁移步骤和回滚方案 | 后端开发 | 数据库迁移 |
|
||
| `api/api-design-guidelines.md` | API设计指南，包含RESTful规范、命名规范 | 后端开发 | API规范变更 |
|
||
| `ui/design-system.md` | 设计系统，包含颜色、字体、间距、组件规范 | 前端开发+UI | 设计系统更新 |
|
||
| `integration/*-integration.md` | 第三方服务集成设计 | 后端开发 | 集成新服务 |
|
||
|
||
**数据库设计规范**:
|
||
|
||
每个数据库设计文档应包含：
|
||
- **ER图**: 实体关系图
|
||
- **表结构**: 表名、字段、类型、约束、索引
|
||
- **关系说明**: 表之间的关系和关联方式
|
||
- **设计决策**: 为什么这样设计
|
||
- **性能考虑**: 索引策略、查询优化
|
||
- **迁移方案**: 如何从旧版本迁移
|
||
|
||
### 3.4 开发文档
|
||
|
||
**目录**: `docs/development/`
|
||
|
||
**职责**: 提供开发规范、快速开始指南、最佳实践和常见问题解答。
|
||
|
||
**文档清单**:
|
||
|
||
| 文档 | 说明 | 负责人 | 更新时机 |
|
||
|------|------|--------|---------|
|
||
| `quick-start.md` | 快速开始指南，包含环境搭建、项目运行 | 全体开发 | 环境变更 |
|
||
| `standards/` | 开发规范，包含编码规范、Git工作流、提交规范 | 技术负责人 | 规范变更 |
|
||
| `best-practices/` | 最佳实践，按技术栈分类 | 资深开发 | 经验积累 |
|
||
| `guides/` | 开发指南，包含常见开发任务步骤 | 全体开发 | 新任务类型 |
|
||
| `faq.md` | 常见问题解答 | 全体开发 | 问题积累 |
|
||
|
||
**快速开始指南规范**:
|
||
|
||
快速开始指南应包含：
|
||
- **前置条件**: 需要的软件和环境
|
||
- **环境搭建**: 详细的安装和配置步骤
|
||
- **项目克隆**: 如何获取代码
|
||
- **依赖安装**: 如何安装依赖
|
||
- **项目运行**: 如何启动项目
|
||
- **验证步骤**: 如何验证环境正确
|
||
- **常见问题**: 环境搭建常见问题
|
||
|
||
### 3.5 API文档
|
||
|
||
**目录**: `docs/api/`
|
||
|
||
**职责**: 提供API接口文档、SDK文档和错误码说明。
|
||
|
||
**文档清单**:
|
||
|
||
| 文档 | 说明 | 负责人 | 更新时机 |
|
||
|------|------|--------|---------|
|
||
| `README.md` | API文档索引，包含API概览和导航 | 后端开发 | API结构调整 |
|
||
| `*/` | 按模块分类的API接口文档 | 后端开发 | API变更 |
|
||
| `error-codes.md` | 错误码说明，包含错误码、含义、解决方案 | 后端开发 | 新增错误码 |
|
||
| `sdk/` | SDK使用文档，包含安装、配置、示例 | 后端开发 | SDK更新 |
|
||
|
||
**API文档规范**:
|
||
|
||
每个API接口文档应包含：
|
||
- **接口路径**: HTTP方法和URL
|
||
- **接口描述**: 接口功能说明
|
||
- **请求参数**: 路径参数、查询参数、请求体
|
||
- **响应格式**: 响应体结构、状态码
|
||
- **请求示例**: curl或代码示例
|
||
- **响应示例**: 成功和失败响应示例
|
||
- **错误码**: 可能返回的错误码
|
||
- **权限要求**: 需要的认证和权限
|
||
- **限流策略**: 接口限流说明
|
||
|
||
### 3.6 测试文档
|
||
|
||
**目录**: `docs/testing/`
|
||
|
||
**职责**: 提供测试计划、测试用例、测试报告和覆盖率报告。
|
||
|
||
**文档清单**:
|
||
|
||
| 文档 | 说明 | 负责人 | 更新时机 |
|
||
|------|------|--------|---------|
|
||
| `test-plan.md` | 测试计划，包含测试范围、策略、资源、进度 | 测试人员 | 测试周期开始 |
|
||
| `test-strategy.md` | 测试策略，包含测试层级、工具、覆盖率要求 | 测试人员 | 测试策略变更 |
|
||
| `test-cases/` | 测试用例，按模块分类 | 测试人员 | 功能开发完成 |
|
||
| `test-reports/` | 测试报告，按版本分类 | 测试人员 | 测试完成 |
|
||
| `coverage-report.md` | 测试覆盖率报告 | 测试人员 | 每次测试执行 |
|
||
|
||
**测试用例规范**:
|
||
|
||
每个测试用例应包含：
|
||
- **用例ID**: 唯一标识
|
||
- **用例名称**: 简洁描述
|
||
- **前置条件**: 执行用例的前提
|
||
- **测试步骤**: 详细的操作步骤
|
||
- **预期结果**: 期望的结果
|
||
- **实际结果**: 实际执行结果（执行时填写）
|
||
- **优先级**: P0/P1/P2
|
||
- **自动化状态**: 手动/自动化
|
||
|
||
### 3.7 部署文档
|
||
|
||
**目录**: `docs/deployment/`
|
||
|
||
**职责**: 提供部署指南、环境配置、CI/CD流程和数据迁移指南。
|
||
|
||
**文档清单**:
|
||
|
||
| 文档 | 说明 | 负责人 | 更新时机 |
|
||
|------|------|--------|---------|
|
||
| `environment-setup.md` | 环境配置，包含开发、测试、生产环境配置 | DevOps | 环境变更 |
|
||
| `docker-guide.md` | Docker部署指南 | DevOps | Docker配置变更 |
|
||
| `kubernetes-guide.md` | Kubernetes部署指南 | DevOps | K8s配置变更 |
|
||
| `aliyun-guide.md` | 阿里云部署指南 | DevOps | 云资源变更 |
|
||
| `ci-cd-pipeline.md` | CI/CD流程配置 | DevOps | 流水线变更 |
|
||
| `migration-guide.md` | 数据迁移指南 | 后端开发+DevOps | 数据迁移 |
|
||
|
||
**部署文档规范**:
|
||
|
||
部署文档应包含：
|
||
- **环境要求**: 硬件、软件、网络要求
|
||
- **部署步骤**: 详细的部署操作流程
|
||
- **配置说明**: 环境变量、配置文件说明
|
||
- **验证步骤**: 如何验证部署成功
|
||
- **回滚方案**: 部署失败如何回滚
|
||
- **常见问题**: 部署常见问题和解决方案
|
||
|
||
### 3.8 运维文档
|
||
|
||
**目录**: `docs/operations/`
|
||
|
||
**职责**: 提供监控告警、日志管理、故障处理和备份恢复指南。
|
||
|
||
**文档清单**:
|
||
|
||
| 文档 | 说明 | 负责人 | 更新时机 |
|
||
|------|------|--------|---------|
|
||
| `monitoring/` | 监控告警配置、告警规则、仪表盘配置 | 运维人员 | 监控变更 |
|
||
| `logging/` | 日志收集、分析、留存策略 | 运维人员 | 日志策略变更 |
|
||
| `troubleshooting/` | 故障处理指南、应急响应流程、故障报告 | 运维人员 | 故障发生 |
|
||
| `backup-restore/` | 备份策略、恢复指南 | 运维人员 | 备份策略变更 |
|
||
|
||
**故障处理文档规范**:
|
||
|
||
故障处理文档应包含：
|
||
- **故障现象**: 故障的表现和影响范围
|
||
- **排查步骤**: 逐步排查指南
|
||
- **解决方案**: 具体的解决步骤
|
||
- **预防措施**: 如何避免类似故障
|
||
- **升级路径**: 无法解决时的升级流程
|
||
|
||
### 3.9 用户文档
|
||
|
||
**目录**: `docs/user/`
|
||
|
||
**职责**: 提供用户手册、使用指南、CLI工具指南和常见问题解答。
|
||
|
||
**文档清单**:
|
||
|
||
| 文档 | 说明 | 负责人 | 更新时机 |
|
||
|------|------|--------|---------|
|
||
| `getting-started.md` | 入门指南，快速上手 | 产品经理+开发 | 功能变更 |
|
||
| `user-manual.md` | 用户手册，详细功能说明 | 产品经理 | 版本发布 |
|
||
| `usage-guide/` | 使用指南，按使用模式分类 | 产品经理+开发 | 使用模式变更 |
|
||
| `cli-guide.md` | CLI工具使用指南 | 后端开发 | CLI更新 |
|
||
| `faq.md` | 用户常见问题 | 产品经理+开发 | 问题积累 |
|
||
|
||
**用户文档规范**:
|
||
|
||
用户文档应包含：
|
||
- **目标用户**: 文档面向的用户群体
|
||
- **前置知识**: 使用产品需要的背景知识
|
||
- **操作步骤**: 图文并茂的操作指南
|
||
- **示例场景**: 实际使用场景示例
|
||
- **常见问题**: 使用过程中常见问题
|
||
- **获取帮助**: 如何获取技术支持
|
||
|
||
---
|
||
|
||
## 四、文档编写规范
|
||
|
||
### 4.1 文档模板
|
||
|
||
#### 4.1.1 文档头部信息
|
||
|
||
每个文档开头必须包含以下元信息：
|
||
|
||
```markdown
|
||
# 文档标题
|
||
|
||
> **文档版本**: v1.0.0
|
||
> **创建日期**: YYYY-MM-DD
|
||
> **最后更新**: YYYY-MM-DD
|
||
> **文档作者**: 作者姓名
|
||
> **文档审核**: 审核人姓名
|
||
> **文档状态**: 草稿/评审中/已发布/已归档/已废弃
|
||
> **适用范围**: 适用的人员或场景
|
||
```
|
||
|
||
#### 4.1.2 文档目录
|
||
|
||
文档超过3个章节时，必须提供目录：
|
||
|
||
```markdown
|
||
## 目录
|
||
|
||
- [一、章节一](#一章节一)
|
||
- [二、章节二](#二章节二)
|
||
- [三、章节三](#三章节三)
|
||
```
|
||
|
||
#### 4.1.3 文档尾部信息
|
||
|
||
文档结尾应包含：
|
||
|
||
```markdown
|
||
---
|
||
|
||
> **文档维护**: 本文档由[角色]维护，定期更新
|
||
> **反馈渠道**: 如有问题，请提交Issue或联系[联系方式]
|
||
> **最后更新**: YYYY-MM-DD
|
||
> **文档状态**: 当前状态
|
||
```
|
||
|
||
### 4.2 命名规范
|
||
|
||
#### 4.2.1 文件命名
|
||
|
||
| 规则 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| **使用kebab-case** | 小写字母，单词间用连字符连接 | `quick-start.md` |
|
||
| **语义化命名** | 文件名应清晰表达内容 | `technology-selection.md` |
|
||
| **避免特殊字符** | 只使用小写字母、数字、连字符 | `ci-cd-pipeline.md` |
|
||
| **版本号文件** | 使用v前缀和语义化版本号 | `prd-v1.0.md` |
|
||
| **ADR文件** | 使用ADR-序号-描述格式 | `ADR-001-monorepo-structure.md` |
|
||
|
||
#### 4.2.2 目录命名
|
||
|
||
| 规则 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| **使用kebab-case** | 小写字母，单词间用连字符 | `design-decisions/` |
|
||
| **复数形式** | 集合目录使用复数形式 | `test-cases/`, `test-reports/` |
|
||
| **语义化命名** | 目录名应清晰表达内容分类 | `best-practices/` |
|
||
|
||
#### 4.2.3 标题命名
|
||
|
||
| 规则 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| **使用中文数字** | 一级标题使用一、二、三 | `## 一、文档管理概述` |
|
||
| **层级清晰** | 使用##、###、####表示层级 | `## 1.1 目的` |
|
||
| **简洁明了** | 标题应简洁表达内容 | `### 4.1 文档模板` |
|
||
|
||
### 4.3 格式规范
|
||
|
||
#### 4.3.1 Markdown格式
|
||
|
||
| 元素 | 格式 | 示例 |
|
||
|------|------|------|
|
||
| **一级标题** | `# 标题` | `# FischerX 文档管理规范` |
|
||
| **二级标题** | `## 标题` | `## 一、文档管理概述` |
|
||
| **三级标题** | `### 标题` | `### 1.1 目的` |
|
||
| **粗体** | `**文本**` | `**重要**` |
|
||
| **斜体** | `*文本*` | `*说明*` |
|
||
| **代码** | `` `代码` `` | `` `npm install` `` |
|
||
| **代码块** | ` ```语言\n代码\n``` ` | 见下方示例 |
|
||
| **链接** | `[文本](URL)` | `[架构设计](docs/architecture/overview.md)` |
|
||
| **图片** | `` | `` |
|
||
| **表格** | 使用Markdown表格语法 | 见下方示例 |
|
||
| **列表** | 使用-或*无序，1.有序 | 见下方示例 |
|
||
|
||
#### 4.3.2 代码块规范
|
||
|
||
```markdown
|
||
```typescript
|
||
// 代码块必须指定语言
|
||
interface User {
|
||
id: string;
|
||
name: string;
|
||
email: string;
|
||
}
|
||
```
|
||
|
||
```bash
|
||
# Shell命令示例
|
||
$ npm install
|
||
$ npm run dev
|
||
```
|
||
|
||
```yaml
|
||
# 配置文件示例
|
||
version: '3.8'
|
||
services:
|
||
api:
|
||
image: fischerx-api:latest
|
||
```
|
||
```
|
||
|
||
#### 4.3.3 表格规范
|
||
|
||
- 表格必须有表头
|
||
- 表格列应对齐
|
||
- 表格内容应简洁明了
|
||
- 复杂表格可拆分为多个表格
|
||
|
||
```markdown
|
||
| 列1 | 列2 | 列3 |
|
||
|------|------|------|
|
||
| 内容1 | 内容2 | 内容3 |
|
||
| 内容4 | 内容5 | 内容6 |
|
||
```
|
||
|
||
#### 4.3.4 列表规范
|
||
|
||
- 列表项应保持一致的缩进
|
||
- 列表项应简洁明了
|
||
- 复杂列表项可使用子列表
|
||
|
||
```markdown
|
||
- 第一项
|
||
- 第二项
|
||
- 子项1
|
||
- 子项2
|
||
- 第三项
|
||
|
||
1. 第一项
|
||
2. 第二项
|
||
3. 第三项
|
||
```
|
||
|
||
#### 4.3.5 引用规范
|
||
|
||
```markdown
|
||
> 这是一段引用文本
|
||
> 可以跨多行
|
||
```
|
||
|
||
#### 4.3.6 链接规范
|
||
|
||
- 内部链接使用相对路径
|
||
- 外部链接使用完整URL
|
||
- 链接文本应清晰表达目标
|
||
|
||
```markdown
|
||
<!-- 内部链接 -->
|
||
[架构设计](../architecture/overview.md)
|
||
|
||
<!-- 外部链接 -->
|
||
[Next.js官方文档](https://nextjs.org/docs)
|
||
```
|
||
|
||
### 4.4 版本控制
|
||
|
||
#### 4.4.1 Git管理
|
||
|
||
- 所有文档使用Git进行版本控制
|
||
- 文档与代码在同一仓库管理
|
||
- 文档变更通过Pull Request审核
|
||
- 文档提交信息遵循Conventional Commits规范
|
||
|
||
```bash
|
||
# 文档提交示例
|
||
docs(architecture): update system architecture diagram
|
||
docs(api): add payment API documentation
|
||
docs(development): update quick start guide
|
||
```
|
||
|
||
#### 4.4.2 版本号规范
|
||
|
||
文档版本号遵循语义化版本规范（SemVer）：
|
||
|
||
| 版本类型 | 说明 | 示例 |
|
||
|---------|------|------|
|
||
| **主版本号** | 重大变更，不兼容的修改 | v1.0.0 → v2.0.0 |
|
||
| **次版本号** | 新增功能，向后兼容 | v1.0.0 → v1.1.0 |
|
||
| **修订号** | 修复错误，向后兼容 | v1.0.0 → v1.0.1 |
|
||
|
||
#### 4.4.3 变更日志
|
||
|
||
重要文档应维护变更日志：
|
||
|
||
```markdown
|
||
## 变更日志
|
||
|
||
### v1.1.0 (2026-06-01)
|
||
- 新增：添加支付模块架构设计
|
||
- 更新：完善数据库设计文档
|
||
- 修复：修正API文档中的错误示例
|
||
|
||
### v1.0.0 (2026-05-24)
|
||
- 初始版本发布
|
||
```
|
||
|
||
### 4.5 图表规范
|
||
|
||
#### 4.5.1 架构图
|
||
|
||
- 使用Mermaid或PlantUML绘制（优先使用Mermaid，支持Markdown内渲染）
|
||
- 复杂图表可使用PNG/SVG格式存储在`diagrams/`目录
|
||
- 图表应有标题和说明
|
||
|
||
```markdown
|
||
```mermaid
|
||
graph TD
|
||
A[前端应用] --> B[API网关]
|
||
B --> C[认证服务]
|
||
B --> D[业务服务]
|
||
C --> E[(数据库)]
|
||
D --> E
|
||
D --> F[(缓存)]
|
||
```
|
||
|
||
*图1: 系统架构概览*
|
||
```
|
||
|
||
#### 4.5.2 流程图
|
||
|
||
```markdown
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant U as 用户
|
||
participant F as 前端
|
||
participant A as API
|
||
participant D as 数据库
|
||
|
||
U->>F: 提交登录请求
|
||
F->>A: 发送认证请求
|
||
A->>D: 查询用户信息
|
||
D-->>A: 返回用户数据
|
||
A-->>F: 返回认证结果
|
||
F-->>U: 显示登录结果
|
||
```
|
||
|
||
*图2: 用户登录流程*
|
||
```
|
||
|
||
#### 4.5.3 ER图
|
||
|
||
```markdown
|
||
```mermaid
|
||
erDiagram
|
||
USER ||--o{ ORDER : places
|
||
USER {
|
||
string id
|
||
string name
|
||
string email
|
||
}
|
||
ORDER ||--|{ ORDER_ITEM : contains
|
||
ORDER {
|
||
string id
|
||
date created_at
|
||
float total
|
||
}
|
||
```
|
||
|
||
*图3: 用户订单ER图*
|
||
```
|
||
|
||
#### 4.5.4 图片资源管理
|
||
|
||
- 图片资源存储在对应文档目录的`assets/`或`diagrams/`子目录
|
||
- 图片命名使用kebab-case
|
||
- 图片格式优先使用SVG（矢量图）或PNG（位图）
|
||
- 图片大小应优化，避免过大
|
||
|
||
---
|
||
|
||
## 五、文档维护流程
|
||
|
||
### 5.1 文档创建流程
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[识别文档需求] --> B[选择文档模板]
|
||
B --> C[创建文档草稿]
|
||
C --> D[编写文档内容]
|
||
D --> E[自我审查]
|
||
E --> F[提交PR审核]
|
||
F --> G[团队审查]
|
||
G --> H{审查通过?}
|
||
H -->|是| I[合并并发布]
|
||
H -->|否| J[修改文档]
|
||
J --> F
|
||
I --> K[更新文档索引]
|
||
```
|
||
|
||
**详细步骤**:
|
||
|
||
| 步骤 | 操作 | 负责人 | 输出 |
|
||
|------|------|--------|------|
|
||
| 1 | 识别文档需求，确定文档类型和位置 | 需求提出者 | 文档需求说明 |
|
||
| 2 | 从`docs/templates/`选择合适模板 | 文档作者 | 文档草稿 |
|
||
| 3 | 编写文档内容，遵循文档规范 | 文档作者 | 文档初稿 |
|
||
| 4 | 自我审查，检查格式、内容、链接 | 文档作者 | 审查后的文档 |
|
||
| 5 | 提交Pull Request，指定审核人 | 文档作者 | PR |
|
||
| 6 | 团队审查，提出修改意见 | 审核人 | 审查意见 |
|
||
| 7 | 根据审查意见修改文档 | 文档作者 | 修改后的文档 |
|
||
| 8 | 审查通过，合并到主分支 | 技术负责人 | 已发布的文档 |
|
||
| 9 | 更新`docs/README.md`文档索引 | 文档作者 | 更新的索引 |
|
||
|
||
### 5.2 文档更新流程
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[识别更新需求] --> B{更新类型}
|
||
B -->|内容修正| C[直接修改]
|
||
B -->|内容新增| D[新增章节]
|
||
B -->|结构变更| E[调整目录结构]
|
||
C --> F[提交PR]
|
||
D --> F
|
||
E --> F
|
||
F --> G[审核]
|
||
G --> H{审核通过?}
|
||
H -->|是| I[合并并更新版本号]
|
||
H -->|否| J[修改]
|
||
J --> F
|
||
I --> K[更新变更日志]
|
||
```
|
||
|
||
**更新触发条件**:
|
||
|
||
| 触发条件 | 更新类型 | 更新范围 |
|
||
|---------|---------|---------|
|
||
| 代码功能变更 | 内容修正/新增 | 相关API文档、开发文档 |
|
||
| 架构调整 | 结构变更 | 架构文档、设计文档 |
|
||
| 规范变更 | 内容修正 | 开发规范文档 |
|
||
| 发现问题 | 内容修正 | 相关文档 |
|
||
| 用户反馈 | 内容新增/修正 | 用户文档、FAQ |
|
||
| 定期审计 | 全面检查 | 所有文档 |
|
||
|
||
**更新流程**:
|
||
|
||
| 步骤 | 操作 | 负责人 | 输出 |
|
||
|------|------|--------|------|
|
||
| 1 | 识别更新需求，确定更新范围 | 任何人 | 更新需求说明 |
|
||
| 2 | 修改文档内容 | 文档负责人 | 修改后的文档 |
|
||
| 3 | 更新文档版本号和最后更新日期 | 文档作者 | 更新的元信息 |
|
||
| 4 | 更新变更日志 | 文档作者 | 更新的变更日志 |
|
||
| 5 | 提交PR审核 | 文档作者 | PR |
|
||
| 6 | 审核通过，合并 | 审核人 | 已更新的文档 |
|
||
|
||
### 5.3 文档审核流程
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[提交PR] --> B[自动化检查]
|
||
B --> C{检查通过?}
|
||
C -->|否| D[修复问题]
|
||
D --> B
|
||
C -->|是| E[人工审核]
|
||
E --> F{审核标准}
|
||
F -->|内容准确性| G[技术审核]
|
||
F -->|格式规范性| H[格式审核]
|
||
F -->|完整性| I[完整性审核]
|
||
G --> J{审核通过?}
|
||
H --> J
|
||
I --> J
|
||
J -->|是| K[合并]
|
||
J -->|否| L[修改]
|
||
L --> E
|
||
```
|
||
|
||
**审核清单**:
|
||
|
||
| 审核项 | 说明 | 优先级 |
|
||
|--------|------|--------|
|
||
| **内容准确性** | 技术内容是否正确 | 高 |
|
||
| **完整性** | 是否覆盖所有必要内容 | 高 |
|
||
| **格式规范** | 是否遵循文档规范 | 高 |
|
||
| **链接有效性** | 内部和外部链接是否有效 | 中 |
|
||
| **图表清晰度** | 图表是否清晰易懂 | 中 |
|
||
| **示例可用性** | 代码示例是否可运行 | 高 |
|
||
| **版本一致性** | 文档版本与代码版本是否一致 | 高 |
|
||
| **语言流畅性** | 语言是否流畅、无错别字 | 中 |
|
||
|
||
### 5.4 文档发布流程
|
||
|
||
| 步骤 | 操作 | 负责人 | 输出 |
|
||
|------|------|--------|------|
|
||
| 1 | 文档审核通过 | 审核人 | 审核通过的PR |
|
||
| 2 | 合并到主分支 | 技术负责人 | 已合并的文档 |
|
||
| 3 | 更新文档索引（docs/README.md） | 文档作者 | 更新的索引 |
|
||
| 4 | 发布通知（如重要文档） | 文档负责人 | 发布通知 |
|
||
| 5 | 更新文档状态为"已发布" | 文档作者 | 已发布的文档 |
|
||
|
||
### 5.5 文档归档流程
|
||
|
||
**归档条件**:
|
||
|
||
| 条件 | 说明 |
|
||
|------|------|
|
||
| **功能废弃** | 相关功能已废弃，文档不再适用 |
|
||
| **版本过期** | 文档对应的版本已不再支持 |
|
||
| **内容替代** | 文档内容已被新文档替代 |
|
||
| **长期未更新** | 文档超过1年未更新且确认过时 |
|
||
|
||
**归档流程**:
|
||
|
||
| 步骤 | 操作 | 负责人 | 输出 |
|
||
|------|------|--------|------|
|
||
| 1 | 识别归档需求 | 任何人 | 归档需求说明 |
|
||
| 2 | 确认归档条件 | 文档负责人 | 归档确认 |
|
||
| 3 | 移动文档到`docs/archive/`目录 | 文档作者 | 归档的文档 |
|
||
| 4 | 更新文档状态为"已归档" | 文档作者 | 更新的元信息 |
|
||
| 5 | 更新文档索引，移除归档文档 | 文档作者 | 更新的索引 |
|
||
| 6 | 提交PR审核合并 | 文档作者 | 已归档的文档 |
|
||
|
||
### 5.6 文档过期处理
|
||
|
||
**过期预警机制**:
|
||
|
||
| 文档类型 | 检查周期 | 过期条件 |
|
||
|---------|---------|---------|
|
||
| **架构文档** | 每季度 | 超过6个月未更新 |
|
||
| **API文档** | 每月 | 超过1个月未更新 |
|
||
| **开发文档** | 每季度 | 超过3个月未更新 |
|
||
| **部署文档** | 每季度 | 超过3个月未更新 |
|
||
| **用户文档** | 每季度 | 超过3个月未更新 |
|
||
|
||
**过期处理流程**:
|
||
|
||
| 步骤 | 操作 | 负责人 | 输出 |
|
||
|------|------|--------|------|
|
||
| 1 | 定期检查文档更新时间 | 文档负责人/自动化脚本 | 过期文档列表 |
|
||
| 2 | 通知文档负责人 | 文档负责人 | 通知 |
|
||
| 3 | 评估文档是否仍适用 | 文档负责人 | 评估结果 |
|
||
| 4a | 如适用：更新文档 | 文档负责人 | 更新的文档 |
|
||
| 4b | 如不适用：标记为过期或归档 | 文档负责人 | 标记/归档的文档 |
|
||
| 5 | 记录处理结果 | 文档负责人 | 处理记录 |
|
||
|
||
---
|
||
|
||
## 六、文档与代码同步策略
|
||
|
||
### 6.1 同步原则
|
||
|
||
| 原则 | 说明 |
|
||
|------|------|
|
||
| **代码变更，文档先行** | 代码变更前先更新相关文档 |
|
||
| **文档即代码** | 文档变更与代码变更同等重要 |
|
||
| **自动化优先** | 尽可能使用工具自动生成文档 |
|
||
| **同步审核** | 代码审核时同步审核相关文档 |
|
||
| **版本对应** | 文档版本与代码版本严格对应 |
|
||
|
||
### 6.2 代码变更时同步更新文档
|
||
|
||
#### 6.2.1 变更影响分析
|
||
|
||
代码变更时，开发者应分析对相关文档的影响：
|
||
|
||
| 代码变更类型 | 影响的文档 | 更新要求 |
|
||
|-------------|-----------|---------|
|
||
| **新增API接口** | API文档、错误码文档 | 必须更新 |
|
||
| **修改API接口** | API文档、错误码文档 | 必须更新 |
|
||
| **删除API接口** | API文档 | 必须更新 |
|
||
| **数据库Schema变更** | 数据库设计文档、迁移指南 | 必须更新 |
|
||
| **架构调整** | 架构文档、模块设计文档 | 必须更新 |
|
||
| **新增功能模块** | 开发文档、用户文档 | 必须更新 |
|
||
| **修改开发规范** | 开发规范文档 | 必须更新 |
|
||
| **部署配置变更** | 部署文档、运维文档 | 必须更新 |
|
||
| **Bug修复** | FAQ、故障处理文档 | 建议更新 |
|
||
|
||
#### 6.2.2 PR模板中的文档检查
|
||
|
||
在Pull Request模板中添加文档检查清单：
|
||
|
||
```markdown
|
||
## 文档更新检查
|
||
|
||
- [ ] 已更新相关API文档
|
||
- [ ] 已更新数据库设计文档（如适用）
|
||
- [ ] 已更新开发文档（如适用）
|
||
- [ ] 已更新部署文档（如适用）
|
||
- [ ] 已更新用户文档（如适用）
|
||
- [ ] 已更新变更日志
|
||
- [ ] 文档链接有效
|
||
- [ ] 代码示例可运行
|
||
```
|
||
|
||
#### 6.2.3 代码审查中的文档审核
|
||
|
||
代码审查时，审查人应同时审核：
|
||
|
||
| 审核项 | 说明 |
|
||
|--------|------|
|
||
| **文档是否更新** | 相关文档是否同步更新 |
|
||
| **文档准确性** | 文档内容是否准确反映代码变更 |
|
||
| **示例代码** | 文档中的示例代码是否与变更一致 |
|
||
| **变更日志** | 是否更新相关文档的变更日志 |
|
||
|
||
### 6.3 CI/CD流程中集成文档检查
|
||
|
||
#### 6.3.1 文档检查项
|
||
|
||
| 检查项 | 工具 | 说明 |
|
||
|--------|------|------|
|
||
| **Markdown格式检查** | markdownlint | 检查Markdown格式规范 |
|
||
| **链接有效性检查** | markdown-link-check | 检查文档链接是否有效 |
|
||
| **拼写检查** | cspell/vale | 检查拼写错误 |
|
||
| **文档结构检查** | 自定义脚本 | 检查文档头部信息是否完整 |
|
||
| **代码示例检查** | 自定义脚本 | 检查代码示例是否可运行 |
|
||
|
||
#### 6.3.2 CI配置示例
|
||
|
||
```yaml
|
||
# .github/workflows/docs-check.yml
|
||
name: Documentation Check
|
||
|
||
on:
|
||
push:
|
||
paths:
|
||
- 'docs/**'
|
||
- '**/*.md'
|
||
pull_request:
|
||
paths:
|
||
- 'docs/**'
|
||
- '**/*.md'
|
||
|
||
jobs:
|
||
docs-check:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: Markdown Lint
|
||
uses: DavidAnson/markdownlint-cli2-action@v15
|
||
with:
|
||
globs: 'docs/**/*.md'
|
||
|
||
- name: Link Check
|
||
uses: gaurav-nelson/github-action-markdown-link-check@v1
|
||
with:
|
||
use-quiet-mode: 'yes'
|
||
config-file: '.markdown-link-check.json'
|
||
|
||
- name: Spell Check
|
||
uses: streetsidesoftware/cspell-action@v6
|
||
with:
|
||
files: 'docs/**/*.md'
|
||
|
||
- name: Check Document Headers
|
||
run: |
|
||
# 自定义脚本检查文档头部信息
|
||
node scripts/check-doc-headers.js
|
||
```
|
||
|
||
### 6.4 文档版本与代码版本对应
|
||
|
||
#### 6.4.1 版本对应策略
|
||
|
||
| 代码版本 | 文档版本 | 说明 |
|
||
|---------|---------|------|
|
||
| v1.0.0 | v1.0.0 | 初始版本 |
|
||
| v1.1.0 | v1.1.0 | 功能更新 |
|
||
| v1.0.1 | v1.0.1 | 修复更新 |
|
||
| v2.0.0 | v2.0.0 | 重大变更 |
|
||
|
||
#### 6.4.2 版本标记
|
||
|
||
在重要文档中使用版本标记：
|
||
|
||
```markdown
|
||
> **适用版本**: v1.0.0+
|
||
> **最后更新**: 2026-05-24
|
||
> **对应代码版本**: v1.0.0
|
||
```
|
||
|
||
#### 6.4.3 版本分支管理
|
||
|
||
| 分支 | 文档版本 | 说明 |
|
||
|------|---------|------|
|
||
| `main` | 最新稳定版 | 生产环境对应文档 |
|
||
| `develop` | 开发版 | 开发环境对应文档 |
|
||
| `release/*` | 发布候选版 | 预发布环境对应文档 |
|
||
| `docs/*` | 文档专项分支 | 文档重构等专项工作 |
|
||
|
||
### 6.5 自动化文档生成
|
||
|
||
#### 6.5.1 API文档自动生成
|
||
|
||
使用工具从代码注释自动生成API文档：
|
||
|
||
| 工具 | 适用场景 | 配置 |
|
||
|------|---------|------|
|
||
| **Swagger/OpenAPI** | RESTful API文档 | 从代码注释生成OpenAPI规范 |
|
||
| **TypeDoc** | TypeScript类型文档 | 从TypeScript代码生成类型文档 |
|
||
| **JSDoc** | JavaScript函数文档 | 从JSDoc注释生成函数文档 |
|
||
|
||
**Swagger配置示例**:
|
||
|
||
```typescript
|
||
// services/api/src/controllers/user.controller.ts
|
||
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
|
||
|
||
@ApiTags('user')
|
||
@Controller('user')
|
||
export class UserController {
|
||
@ApiOperation({ summary: '获取用户信息' })
|
||
@ApiResponse({ status: 200, description: '成功返回用户信息' })
|
||
@ApiResponse({ status: 404, description: '用户不存在' })
|
||
@Get(':id')
|
||
async getUser(@Param('id') id: string) {
|
||
// ...
|
||
}
|
||
}
|
||
```
|
||
|
||
**TypeDoc配置示例**:
|
||
|
||
```json
|
||
// typedoc.json
|
||
{
|
||
"entryPoints": ["packages/core/src/index.ts"],
|
||
"out": "docs/api/typedoc",
|
||
"theme": "default",
|
||
"excludePrivate": true,
|
||
"excludeProtected": true
|
||
}
|
||
```
|
||
|
||
#### 6.5.2 类型文档自动生成
|
||
|
||
使用TypeDoc自动生成类型定义文档：
|
||
|
||
```bash
|
||
# 生成类型文档
|
||
$ npx typedoc --out docs/api/types packages/types/src
|
||
|
||
# 在文档中链接生成的类型文档
|
||
[类型文档](api/types/index.html)
|
||
```
|
||
|
||
#### 6.5.3 数据库文档自动生成
|
||
|
||
使用工具从Prisma Schema生成数据库文档：
|
||
|
||
```bash
|
||
# 使用prisma-docs生成数据库文档
|
||
$ npx prisma-docs --output docs/design/database/schema-docs
|
||
|
||
# 或使用dbdocs
|
||
$ dbdocs push prisma/schema.prisma
|
||
```
|
||
|
||
#### 6.5.4 文档站点生成
|
||
|
||
使用Docusaurus或VitePress生成文档站点：
|
||
|
||
```bash
|
||
# 使用Docusaurus初始化文档站点
|
||
$ npx create-docusaurus@latest docs-site classic
|
||
|
||
# 使用VitePress初始化文档站点
|
||
$ npx create-vitepress@latest docs-site
|
||
```
|
||
|
||
---
|
||
|
||
## 七、文档工具链
|
||
|
||
### 7.1 文档生成工具
|
||
|
||
| 工具 | 用途 | 配置难度 | 推荐场景 |
|
||
|------|------|---------|---------|
|
||
| **TypeDoc** | TypeScript类型文档生成 | 低 | 类型定义文档 |
|
||
| **Swagger UI** | API文档展示 | 中 | RESTful API文档 |
|
||
| **Docusaurus** | 文档站点生成 | 中 | 完整文档站点 |
|
||
| **VitePress** | 轻量文档站点 | 低 | 快速文档站点 |
|
||
| **Mermaid** | Markdown内图表 | 低 | 架构图、流程图 |
|
||
| **PlantUML** | UML图生成 | 中 | 复杂UML图 |
|
||
| **dbdocs** | 数据库文档生成 | 低 | 数据库Schema文档 |
|
||
|
||
### 7.2 文档检查工具
|
||
|
||
| 工具 | 用途 | 配置难度 | 检查项 |
|
||
|------|------|---------|--------|
|
||
| **markdownlint** | Markdown格式检查 | 低 | 格式规范 |
|
||
| **markdown-link-check** | 链接有效性检查 | 低 | 内部/外部链接 |
|
||
| **cspell** | 拼写检查 | 中 | 拼写错误 |
|
||
| **vale** | 风格检查 | 中 | 写作风格、术语 |
|
||
| **textlint** | 文本检查 | 中 | 语法、风格 |
|
||
|
||
**markdownlint配置示例**:
|
||
|
||
```json
|
||
// .markdownlint.json
|
||
{
|
||
"default": true,
|
||
"MD013": false,
|
||
"MD024": { "siblings_only": true },
|
||
"MD033": false,
|
||
"MD041": false
|
||
}
|
||
```
|
||
|
||
### 7.3 文档搜索工具
|
||
|
||
| 工具 | 用途 | 配置难度 | 特点 |
|
||
|------|------|---------|------|
|
||
| **Algolia DocSearch** | 文档搜索 | 中 | 免费、快速、准确 |
|
||
| **FlexSearch** | 客户端搜索 | 低 | 轻量、快速 |
|
||
| **Lunr.js** | 客户端搜索 | 低 | 支持多语言 |
|
||
|
||
### 7.4 文档协作平台
|
||
|
||
| 平台 | 用途 | 适用场景 |
|
||
|------|------|---------|
|
||
| **飞书文档** | 文档协作、评审 | 团队内部文档协作 |
|
||
| **语雀** | 知识库管理 | 团队知识库 |
|
||
| **GitHub Wiki** | 项目文档 | 开源项目文档 |
|
||
| **Confluence** | 企业Wiki | 企业级文档管理 |
|
||
|
||
### 7.5 工具配置示例
|
||
|
||
#### 7.5.1 package.json脚本
|
||
|
||
```json
|
||
{
|
||
"scripts": {
|
||
"docs:lint": "markdownlint-cli2 'docs/**/*.md'",
|
||
"docs:lint:fix": "markdownlint-cli2 'docs/**/*.md' --fix",
|
||
"docs:links": "markdown-link-check docs/**/*.md",
|
||
"docs:spell": "cspell 'docs/**/*.md'",
|
||
"docs:check": "npm run docs:lint && npm run docs:links && npm run docs:spell",
|
||
"docs:dev": "docusaurus start docs-site",
|
||
"docs:build": "docusaurus build docs-site",
|
||
"docs:typedoc": "typedoc --out docs/api/types packages/types/src",
|
||
"docs:api": "swagger-cli bundle services/api/src/openapi.yaml -o docs/api/openapi.yaml",
|
||
"docs:all": "npm run docs:typedoc && npm run docs:api && npm run docs:build"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 7.5.2 Husky钩子配置
|
||
|
||
```json
|
||
// .husky/pre-commit
|
||
#!/bin/sh
|
||
npm run docs:lint
|
||
```
|
||
|
||
#### 7.5.3 VS Code插件推荐
|
||
|
||
| 插件 | 用途 |
|
||
|------|------|
|
||
| **Markdown All in One** | Markdown编辑增强 |
|
||
| **Markdown Preview Enhanced** | Markdown预览增强 |
|
||
| **markdownlint** | Markdown格式检查 |
|
||
| **Mermaid Preview** | Mermaid图表预览 |
|
||
| **PlantUML** | PlantUML图表支持 |
|
||
| **Code Spell Checker** | 拼写检查 |
|
||
|
||
---
|
||
|
||
## 八、文档质量保障
|
||
|
||
### 8.1 文档审查清单
|
||
|
||
#### 8.1.1 内容审查
|
||
|
||
| 检查项 | 说明 | 是否通过 |
|
||
|--------|------|---------|
|
||
| **准确性** | 技术内容是否准确无误 | □ |
|
||
| **完整性** | 是否覆盖所有必要内容 | □ |
|
||
| **一致性** | 与其他文档是否一致 | □ |
|
||
| **时效性** | 内容是否最新 | □ |
|
||
| **实用性** | 内容是否对读者有用 | □ |
|
||
|
||
#### 8.1.2 格式审查
|
||
|
||
| 检查项 | 说明 | 是否通过 |
|
||
|--------|------|---------|
|
||
| **头部信息** | 文档头部元信息是否完整 | □ |
|
||
| **目录结构** | 目录是否清晰完整 | □ |
|
||
| **标题层级** | 标题层级是否正确 | □ |
|
||
| **代码格式** | 代码块是否指定语言 | □ |
|
||
| **表格格式** | 表格是否规范 | □ |
|
||
| **链接有效性** | 所有链接是否有效 | □ |
|
||
| **图片显示** | 图片是否正常显示 | □ |
|
||
| **拼写语法** | 是否有拼写和语法错误 | □ |
|
||
|
||
#### 8.1.3 示例审查
|
||
|
||
| 检查项 | 说明 | 是否通过 |
|
||
|--------|------|---------|
|
||
| **代码示例** | 代码示例是否可运行 | □ |
|
||
| **配置示例** | 配置示例是否完整 | □ |
|
||
| **命令示例** | 命令示例是否可执行 | □ |
|
||
| **输出示例** | 输出示例是否准确 | □ |
|
||
|
||
### 8.2 文档质量指标
|
||
|
||
| 指标 | 目标值 | 测量方法 |
|
||
|------|--------|---------|
|
||
| **文档覆盖率** | > 90% | 功能数/文档数比例 |
|
||
| **文档更新及时率** | > 95% | 代码变更后7天内文档更新比例 |
|
||
| **文档准确率** | > 98% | 文档审查通过率 |
|
||
| **文档可读性** | > 80分 | 读者评分 |
|
||
| **文档搜索成功率** | > 90% | 搜索后找到目标文档比例 |
|
||
| **文档反馈响应时间** | < 3天 | 反馈到处理时间 |
|
||
|
||
### 8.3 定期文档审计
|
||
|
||
#### 8.3.1 审计周期
|
||
|
||
| 文档类型 | 审计周期 | 负责人 |
|
||
|---------|---------|--------|
|
||
| **架构文档** | 每季度 | 技术负责人 |
|
||
| **API文档** | 每月 | 后端开发负责人 |
|
||
| **开发文档** | 每季度 | 开发负责人 |
|
||
| **部署文档** | 每季度 | DevOps负责人 |
|
||
| **用户文档** | 每季度 | 产品负责人 |
|
||
| **全部文档** | 每半年 | 文档负责人 |
|
||
|
||
#### 8.3.2 审计流程
|
||
|
||
| 步骤 | 操作 | 输出 |
|
||
|------|------|------|
|
||
| 1 | 制定审计计划 | 审计计划 |
|
||
| 2 | 收集文档列表 | 文档清单 |
|
||
| 3 | 逐文档审查 | 审查记录 |
|
||
| 4 | 识别问题文档 | 问题文档列表 |
|
||
| 5 | 制定修复计划 | 修复计划 |
|
||
| 6 | 执行修复 | 修复后的文档 |
|
||
| 7 | 审计总结 | 审计报告 |
|
||
|
||
#### 8.3.3 审计报告模板
|
||
|
||
```markdown
|
||
# 文档审计报告
|
||
|
||
> **审计周期**: YYYY-MM-DD 至 YYYY-MM-DD
|
||
> **审计人**: 审计人姓名
|
||
> **审计日期**: YYYY-MM-DD
|
||
|
||
## 审计范围
|
||
|
||
- 审计文档数量: XX篇
|
||
- 审计文档类型: 架构、API、开发、部署、用户
|
||
|
||
## 审计结果
|
||
|
||
| 指标 | 目标值 | 实际值 | 是否达标 |
|
||
|------|--------|--------|---------|
|
||
| 文档覆盖率 | > 90% | XX% | □ |
|
||
| 文档更新及时率 | > 95% | XX% | □ |
|
||
| 文档准确率 | > 98% | XX% | □ |
|
||
|
||
## 问题文档
|
||
|
||
| 文档 | 问题 | 优先级 | 修复计划 |
|
||
|------|------|--------|---------|
|
||
| 文档1 | 问题描述 | P0/P1/P2 | 修复日期 |
|
||
| 文档2 | 问题描述 | P0/P1/P2 | 修复日期 |
|
||
|
||
## 改进建议
|
||
|
||
1. 建议1
|
||
2. 建议2
|
||
3. 建议3
|
||
|
||
## 总结
|
||
|
||
审计总结和下一步行动计划
|
||
```
|
||
|
||
### 8.4 文档反馈机制
|
||
|
||
#### 8.4.1 反馈渠道
|
||
|
||
| 渠道 | 适用场景 | 响应时间 |
|
||
|------|---------|---------|
|
||
| **GitHub Issues** | 文档错误、缺失、建议 | 3个工作日内 |
|
||
| **飞书群** | 紧急文档问题 | 1个工作日内 |
|
||
| **邮件** | 正式文档反馈 | 3个工作日内 |
|
||
| **文档评论** | 具体章节反馈 | 3个工作日内 |
|
||
|
||
#### 8.4.2 反馈处理流程
|
||
|
||
```mermaid
|
||
graph LR
|
||
A[收到反馈] --> B[分类反馈]
|
||
B --> C{反馈类型}
|
||
C -->|文档错误| D[修复文档]
|
||
C -->|内容缺失| E[补充内容]
|
||
C -->|改进建议| F[评估建议]
|
||
F --> G{是否采纳}
|
||
G -->|是| H[实施改进]
|
||
G -->|否| I[反馈原因]
|
||
D --> J[验证修复]
|
||
E --> J
|
||
H --> J
|
||
J --> K[关闭反馈]
|
||
I --> K
|
||
```
|
||
|
||
#### 8.4.3 反馈模板
|
||
|
||
```markdown
|
||
## 文档反馈
|
||
|
||
**文档路径**: docs/xxx/xxx.md
|
||
**反馈类型**: 错误/缺失/建议
|
||
**优先级**: P0/P1/P2
|
||
|
||
### 问题描述
|
||
|
||
详细描述问题或建议
|
||
|
||
### 期望结果
|
||
|
||
期望的文档内容或格式
|
||
|
||
### 截图（可选）
|
||
|
||
如有必要，提供截图说明
|
||
```
|
||
|
||
---
|
||
|
||
## 九、附录
|
||
|
||
### 9.1 文档状态说明
|
||
|
||
| 状态 | 说明 | 颜色标记 |
|
||
|------|------|---------|
|
||
| **草稿** | 文档正在编写中，未完成 | 🟡 黄色 |
|
||
| **评审中** | 文档已完成，正在评审 | 🔵 蓝色 |
|
||
| **已发布** | 文档已审核发布 | 🟢 绿色 |
|
||
| **已归档** | 文档已归档，不再维护 | ⚪ 灰色 |
|
||
| **已废弃** | 文档已废弃，仅供参考 | 🔴 红色 |
|
||
|
||
### 9.2 版本号规范
|
||
|
||
文档版本号遵循语义化版本规范（SemVer）：
|
||
|
||
```
|
||
主版本号.次版本号.修订号
|
||
|
||
示例: v1.0.0
|
||
|
||
- 主版本号: 重大变更，不兼容的修改
|
||
- 次版本号: 新增功能，向后兼容
|
||
- 修订号: 修复错误，向后兼容
|
||
```
|
||
|
||
### 9.3 术语表
|
||
|
||
| 术语 | 说明 |
|
||
|------|------|
|
||
| **ADR** | Architecture Decision Record，架构决策记录 |
|
||
| **PRD** | Product Requirements Document，产品需求文档 |
|
||
| **SemVer** | Semantic Versioning，语义化版本规范 |
|
||
| **CI/CD** | Continuous Integration/Continuous Deployment，持续集成/持续部署 |
|
||
| **PR** | Pull Request，拉取请求 |
|
||
| **Monorepo** | 单一代码仓库管理多个项目或包 |
|
||
| **Markdown** | 轻量级标记语言 |
|
||
| **Mermaid** | 基于JavaScript的图表生成工具 |
|
||
| **TypeDoc** | TypeScript文档生成工具 |
|
||
| **Swagger** | API文档生成工具 |
|
||
|
||
### 9.4 参考文档
|
||
|
||
- [FischerX架构设计方案.md](file:///Users/Chiguyong/Code/FischerX/FischerX架构设计方案.md) - 详细架构设计文档
|
||
- [FischerX开发计划.md](file:///Users/Chiguyong/Code/FischerX/FischerX开发计划.md) - 详细开发计划
|
||
- [spec.md](file:///Users/Chiguyong/Code/FischerX/.trae/specs/initialize-fischerx-foundation/spec.md) - 项目规格说明
|
||
- [Conventional Commits规范](https://www.conventionalcommits.org/) - 提交信息规范
|
||
- [语义化版本规范2.0.0](https://semver.org/lang/zh-CN/) - 版本号规范
|
||
- [Markdown语法指南](https://markdown.com.cn/) - Markdown语法参考
|
||
|
||
---
|
||
|
||
> **文档维护**: 本文档由文档负责人维护，每季度审计更新
|
||
> **反馈渠道**: 如有问题，请提交GitHub Issue或联系技术负责人
|
||
> **最后更新**: 2026-05-24
|
||
> **文档状态**: 正式发布
|