52 KiB

Raw Blame History

FischerX 文档管理规范

项目名称: FischerX 开发底座
文档版本: v1.0.0
创建日期: 2026-05-24
文档负责人: 技术负责人
文档状态: 正式发布
适用范围: FischerX项目全体开发人员、测试人员、运维人员、产品经理

一、文档管理概述

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 文档头部信息

每个文档开头必须包含以下元信息：

# 文档标题

> **文档版本**: v1.0.0  
> **创建日期**: YYYY-MM-DD  
> **最后更新**: YYYY-MM-DD  
> **文档作者**: 作者姓名  
> **文档审核**: 审核人姓名  
> **文档状态**: 草稿/评审中/已发布/已归档/已废弃  
> **适用范围**: 适用的人员或场景

4.1.2 文档目录

文档超过3个章节时，必须提供目录：

## 目录

- [一、章节一](#一章节一)
- [二、章节二](#二章节二)
- [三、章节三](#三章节三)

4.1.3 文档尾部信息

文档结尾应包含：

---

> **文档维护**: 本文档由[角色]维护，定期更新  
> **反馈渠道**: 如有问题，请提交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)`
图片	`![描述](路径)`	`![架构图](diagrams/architecture.png)`
表格	使用Markdown表格语法	见下方示例
列表	使用-或*无序，1.有序	见下方示例

4.3.2 代码块规范

```typescript
// 代码块必须指定语言
interface User {
  id: string;
  name: string;
  email: string;
}

# Shell命令示例
$ npm install
$ npm run dev

# 配置文件示例
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 列表规范

列表项应保持一致的缩进
列表项应简洁明了
复杂列表项可使用子列表

- 第一项
- 第二项
  - 子项1
  - 子项2
- 第三项

1. 第一项
2. 第二项
3. 第三项

4.3.5 引用规范

> 这是一段引用文本
> 可以跨多行

4.3.6 链接规范

内部链接使用相对路径
外部链接使用完整URL
链接文本应清晰表达目标

<!-- 内部链接 -->
[架构设计](../architecture/overview.md)

<!-- 外部链接 -->
[Next.js官方文档](https://nextjs.org/docs)

4.4 版本控制

4.4.1 Git管理

所有文档使用Git进行版本控制
文档与代码在同一仓库管理
文档变更通过Pull Request审核
文档提交信息遵循Conventional Commits规范

# 文档提交示例
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 变更日志

重要文档应维护变更日志：

## 变更日志

### 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/目录
图表应有标题和说明

```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 文档更新流程

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 文档审核流程

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模板中添加文档检查清单：

## 文档更新检查

- [ ] 已更新相关API文档
- [ ] 已更新数据库设计文档（如适用）
- [ ] 已更新开发文档（如适用）
- [ ] 已更新部署文档（如适用）
- [ ] 已更新用户文档（如适用）
- [ ] 已更新变更日志
- [ ] 文档链接有效
- [ ] 代码示例可运行

6.2.3 代码审查中的文档审核

代码审查时，审查人应同时审核：

审核项	说明
文档是否更新	相关文档是否同步更新
文档准确性	文档内容是否准确反映代码变更
示例代码	文档中的示例代码是否与变更一致
变更日志	是否更新相关文档的变更日志

6.3 CI/CD流程中集成文档检查

6.3.1 文档检查项

检查项	工具	说明
Markdown格式检查	markdownlint	检查Markdown格式规范
链接有效性检查	markdown-link-check	检查文档链接是否有效
拼写检查	cspell/vale	检查拼写错误
文档结构检查	自定义脚本	检查文档头部信息是否完整
代码示例检查	自定义脚本	检查代码示例是否可运行

6.3.2 CI配置示例

# .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 版本标记

在重要文档中使用版本标记：

> **适用版本**: 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配置示例:

// 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配置示例:

// typedoc.json
{
  "entryPoints": ["packages/core/src/index.ts"],
  "out": "docs/api/typedoc",
  "theme": "default",
  "excludePrivate": true,
  "excludeProtected": true
}

6.5.2 类型文档自动生成

使用TypeDoc自动生成类型定义文档：

# 生成类型文档
$ npx typedoc --out docs/api/types packages/types/src

# 在文档中链接生成的类型文档
[类型文档](api/types/index.html)

6.5.3 数据库文档自动生成

使用工具从Prisma Schema生成数据库文档：

# 使用prisma-docs生成数据库文档
$ npx prisma-docs --output docs/design/database/schema-docs

# 或使用dbdocs
$ dbdocs push prisma/schema.prisma

6.5.4 文档站点生成

使用Docusaurus或VitePress生成文档站点：

# 使用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配置示例:

// .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脚本

{
  "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钩子配置

// .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 审计报告模板

# 文档审计报告

> **审计周期**: 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 反馈处理流程

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 反馈模板

## 文档反馈

**文档路径**: 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 - 详细架构设计文档
FischerX开发计划.md - 详细开发计划
spec.md - 项目规格说明
Conventional Commits规范 - 提交信息规范
语义化版本规范2.0.0 - 版本号规范
Markdown语法指南 - Markdown语法参考

文档维护: 本文档由文档负责人维护，每季度审计更新
反馈渠道: 如有问题，请提交GitHub Issue或联系技术负责人
最后更新: 2026-05-24
文档状态: 正式发布

52 KiB Raw Blame History Unescape Escape

FischerX 文档管理规范

目录

一、文档管理概述

1.1 目的

1.2 适用范围

1.3 文档管理原则

1.4 角色与职责

二、文档目录结构设计

2.1 整体目录结构

2.2 目录说明

2.3 文档分类体系

2.3.1 按受众分类

2.3.2 按生命周期分类

2.3.3 按稳定性分类

三、文档分类和职责

3.1 架构文档

3.2 需求文档

3.3 设计文档

3.4 开发文档

3.5 API文档

3.6 测试文档

3.7 部署文档

3.8 运维文档

3.9 用户文档

四、文档编写规范

4.1 文档模板

4.1.1 文档头部信息

4.1.2 文档目录

4.1.3 文档尾部信息

4.2 命名规范

4.2.1 文件命名

4.2.2 目录命名

4.2.3 标题命名

4.3 格式规范

4.3.1 Markdown格式

4.3.2 代码块规范

4.3.4 列表规范

4.3.5 引用规范

4.3.6 链接规范

4.4 版本控制

4.4.1 Git管理

4.4.2 版本号规范

4.4.3 变更日志

4.5 图表规范

4.5.1 架构图

5.2 文档更新流程

5.3 文档审核流程

5.4 文档发布流程

5.5 文档归档流程

5.6 文档过期处理

六、文档与代码同步策略

6.1 同步原则

6.2 代码变更时同步更新文档

6.2.1 变更影响分析

6.2.2 PR模板中的文档检查

6.2.3 代码审查中的文档审核

6.3 CI/CD流程中集成文档检查

6.3.1 文档检查项

6.3.2 CI配置示例

6.4 文档版本与代码版本对应

6.4.1 版本对应策略

6.4.2 版本标记

6.4.3 版本分支管理

6.5 自动化文档生成

6.5.1 API文档自动生成

6.5.2 类型文档自动生成

6.5.3 数据库文档自动生成

6.5.4 文档站点生成

七、文档工具链

7.1 文档生成工具

7.2 文档检查工具

7.3 文档搜索工具

7.4 文档协作平台

7.5 工具配置示例

7.5.1 package.json脚本

7.5.2 Husky钩子配置

7.5.3 VS Code插件推荐

八、文档质量保障

8.1 文档审查清单

52 KiB

Raw Blame History