文档模块化规范版本v2.0更新日期2026-07-19维护者WorkFlowPrj Team目的为技术方案文档、重构方案文档提供统一的编写规范确保结构清晰、内容完整、易于维护。适用范围技术方案、重构方案类文档目录文档模块化规范目录1. 三部分结构模板2. 格式规则速查3. 命名规范4. 组织原则与检查清单1. 三部分结构模板所有方案类文档应遵循三部分结构按是什么→怎么做→何时做的逻辑分层文档标题 ├── 文档头信息版本、日期、维护者、配套文档 │ ├── 第一部分背景与方案 │ ├── 1.1 现状与问题 │ ├── 1.2 方案总览 │ └── 1.3 目录索引 │ ├── 第二部分核心设计 │ ├── 2.1 数据结构与接口 │ ├── 2.2 核心流程 │ └── 2.3 通信与适配 │ ├── 第三部分实施步骤 │ ├── 3.1 阶段划分 │ ├── 3.2 优先级与顺序 │ └── 3.3 与现有系统的关系 │ └── 总结1.1 文档头模板# 文档标题 **版本** v1.0 **更新日期** YYYY-MM-DD **维护者** WorkFlowPrj Team **配套文档** [关联文档.md](关联文档.md)说明 ---字段必填说明版本是语义化版本号v1.0, v1.1更新日期是ISO 格式日期维护者是团队或负责人配套文档推荐关联文档链接与说明1.2 第一部分背景与方案第一部分背景与方案1.1 现状与问题模块介绍问题分析表现根因1.2 方案总览设计理念方案对比表架构图1.3 目录索引现有文件列表新增文件列表## 第一部分背景与方案 ### 1.1 现状与问题 模块功能描述。 | 问题 | 表现 | 根因 | |------|------|------| | 问题 1 | 表现 | 根因 | ### 1.2 方案总览 | 维度 | 当前方案 | 新方案 | |------|----------|--------| | 维度 1 | 当前 | 新 | mermaid graph TB A -- B -- C1.3 目录索引文件路径内容### 1.3 第二部分核心设计 mermaid mindmap root((第二部分核心设计)) 2.1 数据结构与接口 核心数据定义 接口契约 2.2 核心流程 执行顺序 关键代码片段 2.3 通信与适配 事件机制 桥接层设计## 第二部分核心设计 ### 2.1 数据结构与接口 csharp public interface IService { TaskResult ExecuteAsync(string input); }2.2 核心流程ABC2.3 通信与适配…### 1.4 第三部分实施步骤 mermaid mindmap root((第三部分实施步骤)) 3.1 阶段划分 并行运行 混合运行 完全迁移 3.2 优先级与顺序 任务优先级划分 推荐实现顺序 3.3 与现有系统的关系 集成方式 能力矩阵## 第三部分实施步骤 ### 3.1 阶段划分 - **阶段 1并行**新系统独立运行验证正确性 - **阶段 2混合**新功能用新系统旧功能逐步迁移 - **阶段 3迁移**移除旧系统清理桥接代码 ### 3.2 优先级与顺序 高优先级任务 A、任务 B 中优先级任务 C 低优先级任务 D ### 3.3 与现有系统的关系 | 现有模块 | 集成方式 | 说明 | |---------|---------|------|2. 格式规则速查2.1 标题层级层级格式用途H1#文档标题唯一H2##三大部分目录总结H3###章节X.YH4####子章节X.Y.Z规则禁止跳级H2 直接到 H42.2 表格| 左对齐 | 居中 | 右对齐 | |--------|:----:|-------:|规则表头与内容必须有分隔行文本左对齐数字右对齐状态居中表格前后空一行超过 6 列考虑拆分2.3 图表Mermaid类型用途graph架构图、流程图sequenceDiagram时序图graph LR依赖方向图graph TB分层架构图规则使用subgraph分组classDef定义样式--表示依赖-.-表示可选2.4 代码块语言 代码内容**规则** 必须指定语言标识符csharp、json、markdown、text代码块前后空一行关键部分添加注释长代码30行拆分为多个小代码块 ### 2.5 引用与注释 | 类型 | 格式 | |------|------| | 重要说明 | **说明** | | 警告 | **⚠️ 注意** | | 更新标记 | **★ YYYY-MM-DD** | | 引用来源 | 来源 | --- ## 3. 命名规范 ### 3.1 文件命名 **格式** 领域_模块_描述.md | 类型 | 示例 | |------|------| | 架构文档 | Architecture.md | | 重构方案 | ECS_Based_Control_Refactoring.md | | 实现文档 | Implementation.md | **规则** PascalCase下划线分隔避免缩写公认缩写如 ECS、IoC 除外 ### 3.2 章节编号 **格式** X.Y.Z | 层级 | 格式 | 示例 | |------|------|------| | 部分 | 第X部分标题 | 第一部分背景与方案 | | 章节 | X.Y 标题 | 1.1 现状与问题 | | 子章节 | X.Y.Z 标题 | 1.1.1 核心能力 | ### 3.3 标识符引用 | 类型 | 格式 | 示例 | |------|------|------| | 类名 | ClassName | EntityManager | | 方法名 | MethodName() | CreateEntity() | | 属性 | PropertyName | IsCreated | | 命名空间 | Namespace.Sub | Project.Module | | 文件路径 | Path/To/File.cs | Core/Service.cs | | 枚举值 | EnumType.Value | Status.Active | --- ## 4. 组织原则与检查清单 ### 4.1 核心原则 mermaid mindmap root((核心原则)) 模块化 每个模块独立成节 模块间关系通过图表展示 渐进式 从概览到细节逐步深入 每部分假设读者只读了前面内容 可追溯 文档间通过链接形成网络 关键决策标注日期和原因 职责分离 架构、实现、使用指南分开编写 不互相掺杂4.2 检查清单检查清单结构检查文档头完整配套文档已列出三部分结构完整目录链接正确内容检查问题分析有表现和根因方案对比使用表格架构图使用 Mermaid核心代码有语言标识实施步骤分阶段优先级有划分格式检查标题层级无跳级表格有分隔行代码块有语言标识引用格式统一文件路径使用正斜杠章节编号连续总结本规范为技术方案和重构方案文档提供统一的三部分结构模板、格式规则和组织原则。核心价值在于通过背景与方案→核心设计→实施步骤的分层逻辑让不同读者决策者、开发者、项目经理都能快速找到所需信息。