openharmonyinsight/oh-pdd-design-doc-generator

设计文档生成器

基于 PRD 文档自动生成鸿蒙系统（HarmonyOS/OpenHarmony）设计文档，包括架构设计文档和功能设计文档。

快速开始

提供 PRD 文档路径：

基于 {PRD文档} 生成设计文档

指定输出类型：

生成架构设计文档和功能设计文档，基于 {PRD文档路径}

OpenHarmony 代码分析

在生成设计文档前，需要分析 OpenHarmony 存量代码结构，确保新设计与现有架构兼容。

分析步骤

1. 发现代码结构

使用 Glob 工具快速发现目录结构和关键文件：

| 文件类型 | 搜索模式 | 说明 | |----------|----------|------| | 配置文件 | **/bundle.json, **/BUILD.gn, **/config.json | 部件定义、构建配置 | | 文档文件 | **/README.md, **/*.md | 模块说明、使用指南 | | 接口文件 | **/*.idl, **/include/*.h | IDL 接口、C++ 头文件 | | 元数据文件 | **/*.gn, **/*.gni | GN 构建脚本 | | SA 配置 | **/sa_profile/*.json, **/etc/profile/*.json | SA 配置文件 |

2. 搜索关键信息

使用 Grep 工具搜索关键字提取组件信息：

| 搜索目标 | 搜索关键字 | 提取信息 | |----------|------------|----------| | SA ID | "sa-id" | 已分配的 SA ID | | 子系统 | subsystem_name | 子系统组织 | | 依赖关系 | external_deps | 组件依赖 | | 接口定义 | interface | IDL 接口 | | 服务类 | class.*Service | 服务实现类 | | Provider | .*Provider | SA Provider 类 |

3. 读取关键配置

使用 Read 工具读取关键配置文件：

• bundle.json: 部件定义和子系统归属
• BUILD.gn: 构建依赖和编译选项
• sa_profile/*.json: SA 配置和启动参数
• README.md: 模块说明和使用指南
• *.idl: 接口定义和数据结构

4. 智能探索

使用 Task 工具启动 Explore 代理进行多轮探索：

• 发现相关模块的目录结构
• 查找相似功能的实现参考
• 提取接口设计和数据结构

命名模式推断

通过文件和目录命名推断功能：

| 命名模式 | 推断功能 | 示例 | |----------|----------|------| | *_service.cpp | 服务实现 | disk_info_service.cpp | | *_provider.h/cpp | SA Provider 实现 | disk_manager_provider.cpp | | *_listener.idl | 事件监听接口 | IDiskChangeListener.idl | | *_types.idl | 数据类型定义 | DiskInfoTypes.idl | | */kits/ | 对外 API 层 | kits/js/, kits/native/ | | */innerkits/ | 内部 API 层 | innerkits/native/ | | */sa_profile/ | SA 配置文件 | sa_profile/5001.json | | */test/ | 测试代码 | test/unittest/ | | */mock/ | 测试 Mock | test/mock/ |

分析输出

代码分析完成后生成：

1. 现有 SA 清单: 已分配的 SA ID 和服务名称
2. 子系统组织: 子系统和部件的层次结构
3. 依赖关系图: 组件间的依赖关系
4. 接口参考: 相似功能的接口设计参考
5. 代码风格参考: 命名规范、目录结构等

竞品方案分析章节要求

架构设计文档 第2章必须为竞品方案分析，位于需求背景之后、鸿蒙系统架构分析之前。

章节结构

2. 竞品方案分析

2.1 竞品识别

• 列出主要竞品（至少2-3个）
• 说明竞品选择理由
• 竞品类型：同类产品、技术方案、行业标准

2.2 竞品技术方案分析

对每个竞品分析：

• 核心技术架构
• 关键技术组件
• 通信机制
• 数据流程
• 关键流程图、时序图

2.3 技术对比表格

| 对比项 | 本方案 | 竞品A | 竞品B | |--------|--------|-------|-------| | 架构模式 | | | | | 核心技术 | | | | | 通信机制 | | | | | 进程模型 | | | | | 安全机制 | | | | | 跨语言支持 | | | |

2.4 差异化设计

• 本方案相对于竞品的创新点
• 解决的竞品痛点
• 技术优势说明
• 借鉴与改进

输出要求

• 使用4+1视图、流程图、时序图呈现竞品技术方案
• 至少包含2个竞品的详细分析
• 必须有技术对比表格
• 必须明确差异化设计点

章节顺序验证

生成架构设计文档时，验证章节顺序：

标准顺序：需求背景 → 竞品方案分析 → 鸿蒙系统架构分析 → 架构设计...

验证规则：

• ✅ 第1章必须是"需求背景"
• ✅ 第2章必须是"竞品方案分析"（必需）
• ✅ 竞品方案分析必须在需求背景之后
• ✅ 竞品方案分析必须在架构设计之前
• ❌ 如顺序错误，提示用户调整

验证逻辑：

1. 提取文档中所有一级标题（# 开头）
2. 验证第1章是否为"需求背景"
3. 验证第2章是否为"竞品方案分析"或"竞品分析"
4. 如缺失第2章或顺序错误，返回错误提示

生成内容

架构设计文档 (architecture_vX.md)

包含以下标准章节（按顺序）：

| 章节 | 内容 | |------|------| | 1. 需求背景 | 项目背景、业务需求、技术挑战 | | 2. 竞品方案分析 | 竞品识别、技术方案对比、差异化设计（必需） | | 3. 鸿蒙系统架构分析 | 现有架构、可复用组件 | | 4. 架构设计 | 整体架构、技术选型、模块划分 | | 5. 数据模型 | 核心数据结构、数据库设计 | | 6. 接口设计 | IDL接口、NAPI接口 | | 7. 部署架构 | 进程模型、启动依赖 | | 8. 安全韧性隐私可靠性分析 | 安全设计、韧性设计、隐私保护、可靠性 | | 9. 需求分解与代码量评估 | 需求拆分、代码量估算 | | 10. 附录 | 错误码、性能指标 |

功能设计文档 (functiondesign_vX.md)

包含以下标准章节：

| 章节 | 内容 | |------|------| | 1. 概述 | 文档目的、模块清单 | | 2. 模块定义 | 各模块职责、输入输出、依赖关系 | | 3. 接口定义 | IDL接口、回调接口 | | 4. 状态机设计 | 状态枚举、转换表、转换图 | | 5. 流程设计 | 主流程图、时序图、异常处理 | | 6. 错误处理 | 错误码定义、处理策略 |

架构层次

┌─────────────────────────────────────────┐
│              应用层 (Application)         │
│         设置应用 | 文件管理 | 磁盘工具      │
└─────────────────────────────────────────┘
                    ↓ NAPI/IPC
┌─────────────────────────────────────────┐
│               服务层 (Service)            │
│      DiskManagement SA (5001)            │
│  DiskInfo | Format | Repair | Status     │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│               工具层 (Tools)              │
│    FormatTool | FsckTool | PartedTool    │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│              系统层 (System)              │
│  Storage SA | OsAccount SA | HiSysEvent   │
└─────────────────────────────────────────┘

SA 划分规则

| SA 名称 | SA ID 范围 | 示例 | |---------|-----------|------| | 基础服务 | 1000-1999 | OsAccount (4101) | | 数据存储 | 4000-4999 | | | 文件管理 | 5000-5999 | DiskManagement (5001), StorageManager (5003) |

状态机设计

使用 V11.0 状态机规范：

stateDiagram-v2
    [*] --> UNKNOWN
    UNKNOWN --> NORMAL: 检测成功
    UNKNOWN --> ABNORMAL: 检测失败
    NORMAL --> CHECKING: 开始检测
    CHECKING --> NORMAL: 检测完成
    CHECKING --> REPAIRING: 需要修复
    CHECKING --> ABNORMAL: 检测失败
    REPAIRING --> NORMAL: 修复成功
    REPAIRING --> ABNORMAL: 修复失败
    ABNORMAL --> CHECKING: 重新检测

时序图示例

sequenceDiagram
    participant App as 应用
    participant Kit as DiskManagementKit
    participant SA as DiskManagement SA
    participant Tool as FormatTool

    App->>Kit: formatDisk(diskId, fsType)
    Kit->>SA: format(diskId, fsType)
    SA->>SA: 权限校验
    SA->>SA: 状态验证
    SA->>Tool: executeFormat()
    Tool-->>SA: onProgress(percent)
    SA-->>Kit: onFormatProgress()
    Kit-->>App: progress callback
    Tool-->>SA: result
    SA-->>Kit: result
    Kit-->>App: format result

参考文档

• 架构设计模板: references/architecture_template.md
• 功能设计模板: references/functional_template.md
• 状态机规范: references/state_machine_spec.md
• 接口设计指南: references/interface_guide.md

与 PRD 的映射关系

| PRD 章节 | 设计文档章节 | 映射规则 | |----------|--------------|----------| | 第4章：竞品分析 | 第2章：竞品方案分析 | PRD的竞品分析扩展为技术方案对比 | | 第2章：需求背景 | 第1章：需求背景 | 直接映射 | | 第5章：需求描述 | 第4章：架构设计 | 需求转换为架构设计 | | KEP 定义 | 模块架构 + 接口设计 | 每个 KEP 对应至少一个服务模块 | | 用户故事 | 功能规格 | 用户场景转换为功能流程 | | 验收标准 | 接口返回值定义 | 验收条件转为接口契约 | | 非功能需求 | 架构选型 + 性能指标 | 技术约束体现在架构设计中 |

依赖服务映射

| 设计文档中的服务 | 对应的 OpenHarmony SA | 说明 | |------------------|---------------------|------| | 权限校验服务 | OsAccount SA (4101) | 复用账户系统能力 | | 存储服务 | StorageManager SA (5003) | 外接存储管理 | | 加密服务 | Crypto SA | 磁盘加密能力 |

输出目录结构

output/
├── architecture_v1.md      # 架构设计文档
├── functiondesign_v1.md     # 功能设计文档
├── code_paths_v1.md        # 代码路径文档
└── diagrams/               # 生成的图表文件
    ├── architecture.png
    ├── state_machine.png
    └── sequence.png

使用示例

生成完整设计文档：

基于 {PRD文档} 生成架构和功能设计文档

仅生成架构设计：

只生成架构设计文档，基于 {PRD文档}

指定 SA ID：

生成设计文档，SA ID 使用 {SA_ID}，基于 {PRD文档}

指定产品名称和版本：

为 {产品名} {版本} 生成设计文档，版本 {文档版本}，基于 {PRD文档}

指定输出目录：

生成设计文档到 ./design_docs 目录，基于 {PRD文档}

命名规范

| 文档类型 | 命名格式 | 示例 | |----------|----------|------| | 架构设计 | architecture_v{major}.md | architecture_v1.md | | 功能设计 | functiondesign_v{major}.md | functiondesign_v1.md | | 代码路径 | code_paths_v{major}.md | code_paths_v1.md | | PRD 引用 | prd_v{version}.md | prd_v17.md |

版本管理规则

| 版本变化 | 更新内容 | |----------|----------| | PRD 版本变更 | 设计文档版本同步递增 | | 架构调整 | 增加 .1 子版本（V1.0 → V1.1） | | 新增功能 | 增加次版本号（V1.0 → V2.0） |

图表格式

使用 Mermaid 语法绘制图表。支持的图表类型：

• 流程图: graph TD 或 flowchart TD
• 状态图: stateDiagram-v2
• 时序图: sequenceDiagram
• 类图: classDiagram
• 组件图: graph LR

错误处理

| 错误类型 | 处理方式 | |----------|----------| | PRD 文件不存在 | 提示文件路径错误 | | PRD 缺少竞品分析 | 提示补充PRD第4章竞品分析，或基于现有信息生成 | | 架构文档缺少第2章竞品方案分析 | 返回错误：第2章必须为竞品方案分析 | | 章节顺序错误 | 提示：第2章必须为竞品方案分析，位于需求背景之后 | | KEP 解析失败 | 列出缺失的 KEP 定义 | | 格式不符合规范 | 按默认模板生成 | | 输出目录不可写 | 提示权限问题 |