oh-pdd-design-doc-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

设计文档生成器

Design Document Generator

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

Automatically generate HarmonyOS/OpenHarmony design documents including architecture design documents and functional design documents based on PRD documents.

快速开始

Quick Start

提供 PRD 文档路径：

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

指定输出类型：

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

Provide PRD document path:

Generate design documents based on {PRD Document}

Specify output type:

Generate architecture design document and functional design document based on {PRD Document Path}

OpenHarmony 代码分析

OpenHarmony Code Analysis

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

Before generating design documents, it is necessary to analyze the existing code structure of OpenHarmony to ensure that the new design is compatible with the current architecture.

分析步骤

Analysis Steps

1. 发现代码结构

1. Discover Code Structure

使用 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 配置文件

Use Glob tool to quickly discover directory structure and key files:

File Type	Search Pattern	Description
Configuration Files	`/bundle.json` , `/BUILD.gn` , `**/config.json`	Component definition, build configuration
Document Files	`/README.md` , `/*.md`	Module description, usage guide
Interface Files	`*/.idl` , `*/include/.h`	IDL interfaces, C++ header files
Metadata Files	`*/.gn` , `*/.gni`	GN build scripts
SA Configuration	`*/sa_profile/.json` , `*/etc/profile/.json`	SA configuration files

2. 搜索关键信息

2. Search for Key Information

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

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

Use Grep tool to search keywords and extract component information:

Search Target	Search Keywords	Extracted Information
SA ID	`"sa-id"`	Assigned SA IDs
Subsystem	`subsystem_name`	Subsystem organization
Dependencies	`external_deps`	Component dependencies
Interface Definition	`interface`	IDL interfaces
Service Class	`class.*Service`	Service implementation classes
Provider	`.*Provider`	SA Provider classes

3. 读取关键配置

3. Read Key Configurations

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

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

Use Read tool to read key configuration files:

```
bundle.json
```
: Component definition and subsystem affiliation
```
BUILD.gn
```
: Build dependencies and compilation options
```
sa_profile/*.json
```
: SA configuration and startup parameters
```
README.md
```
: Module description and usage guide
```
*.idl
```
: Interface definitions and data structures

4. 智能探索

4. Intelligent Exploration

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

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

Use Task tool to start Explore agent for multi-round exploration:

Discover directory structure of related modules
Find implementation references for similar functions
Extract interface design and data structures

命名模式推断

Naming Pattern Inference

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

命名模式	推断功能	示例
`*_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/`

Infer functions through file and directory naming:

Naming Pattern	Inferred Function	Example
`*_service.cpp`	Service implementation	`disk_info_service.cpp`
`*_provider.h/cpp`	SA Provider implementation	`disk_manager_provider.cpp`
`*_listener.idl`	Event listening interface	`IDiskChangeListener.idl`
`*_types.idl`	Data type definition	`DiskInfoTypes.idl`
`*/kits/`	External API layer	`kits/js/` , `kits/native/`
`*/innerkits/`	Internal API layer	`innerkits/native/`
`*/sa_profile/`	SA configuration files	`sa_profile/5001.json`
`*/test/`	Test code	`test/unittest/`
`*/mock/`	Test Mock	`test/mock/`

分析输出

Analysis Output

代码分析完成后生成：

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

After code analysis, generate:

Existing SA List: Assigned SA IDs and service names
Subsystem Organization: Hierarchy of subsystems and components
Dependency Graph: Dependencies between components
Interface Reference: Interface design references for similar functions
Code Style Reference: Naming conventions, directory structure, etc.

竞品方案分析章节要求

Competitor Solution Analysis Chapter Requirements

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

Chapter 2 of the architecture design document must be Competitor Solution Analysis, which should be placed after Requirement Background and before HarmonyOS Architecture Analysis.

章节结构

Chapter Structure

2. 竞品方案分析

2. Competitor Solution Analysis

2.1 竞品识别

2.1 Competitor Identification

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

List main competitors (at least 2-3)
Explain reasons for competitor selection
Competitor types: similar products, technical solutions, industry standards

2.2 竞品技术方案分析

2.2 Competitor Technical Solution Analysis

对每个竞品分析：

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

For each competitor, analyze:

Core technical architecture
Key technical components
Communication mechanism
Data flow
Key flowcharts, sequence diagrams

2.3 技术对比表格

2.3 Technical Comparison Table

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

Comparison Item	Our Solution	Competitor A	Competitor B
Architecture Pattern
Core Technology
Communication Mechanism
Process Model
Security Mechanism
Cross-language Support

2.4 差异化设计

2.4 Differentiated Design

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

Innovations of our solution compared to competitors
Pain points of competitors solved by our solution
Technical advantage explanation
Reference and improvement

输出要求

Output Requirements

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

Present competitor technical solutions using 4+1 view, flowcharts, sequence diagrams
Include detailed analysis of at least 2 competitors
Must have a technical comparison table
Must clarify differentiated design points

章节顺序验证

Chapter Order Verification

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

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

验证规则：

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

验证逻辑：

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

Verify chapter order when generating architecture design documents:

Standard order: Requirement Background → Competitor Solution Analysis → HarmonyOS Architecture Analysis → Architecture Design...

Verification Rules:

✅ Chapter 1 must be "Requirement Background"
✅ Chapter 2 must be "Competitor Solution Analysis" (Required)
✅ Competitor Solution Analysis must be after Requirement Background
✅ Competitor Solution Analysis must be before Architecture Design
❌ If the order is wrong, prompt the user to adjust

Verification Logic:

Extract all level 1 headings (starting with #)
Verify if Chapter 1 is "Requirement Background"
Verify if Chapter 2 is "Competitor Solution Analysis" or "Competitor Analysis"
If Chapter 2 is missing or the order is wrong, return an error prompt

生成内容

Generated Content

架构设计文档 (architecture_vX.md)

Architecture Design Document (architecture_vX.md)

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

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

Includes the following standard chapters (in order):

Chapter	Content
1. Requirement Background	Project background, business requirements, technical challenges
2. Competitor Solution Analysis	Competitor identification, technical solution comparison, differentiated design (Required)
3. HarmonyOS Architecture Analysis	Current architecture, reusable components
4. Architecture Design	Overall architecture, technology selection, module division
5. Data Model	Core data structures, database design
6. Interface Design	IDL interfaces, NAPI interfaces
7. Deployment Architecture	Process model, startup dependencies
8. Security, Resilience, Privacy and Reliability Analysis	Security design, resilience design, privacy protection, reliability
9. Requirement Decomposition and Code Volume Evaluation	Requirement splitting, code volume estimation
10. Appendix	Error codes, performance indicators

功能设计文档 (functiondesign_vX.md)

Functional Design Document (functiondesign_vX.md)

包含以下标准章节：

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

Includes the following standard chapters:

Chapter	Content
1. Overview	Document purpose, module list
2. Module Definition	Responsibilities of each module, input/output, dependencies
3. Interface Definition	IDL interfaces, callback interfaces
4. State Machine Design	State enumeration, transition table, transition diagram
5. Process Design	Main flowcharts, sequence diagrams, exception handling
6. Error Handling	Error code definition, handling strategies

架构层次

Architecture Layers

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

┌─────────────────────────────────────────┐
│              Application Layer         │
│         Settings App | File Manager | Disk Tool      │
└─────────────────────────────────────────┘
                    ↓ NAPI/IPC
┌─────────────────────────────────────────┐
│               Service Layer            │
│      DiskManagement SA (5001)            │
│  DiskInfo | Format | Repair | Status     │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│               Tools Layer              │
│    FormatTool | FsckTool | PartedTool    │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│              System Layer              │
│  Storage SA | OsAccount SA | HiSysEvent   │
└─────────────────────────────────────────┘

SA 划分规则

SA Division Rules

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

SA Name	SA ID Range	Example
Basic Services	1000-1999	OsAccount (4101)
Data Storage	4000-4999
File Management	5000-5999	DiskManagement (5001), StorageManager (5003)

状态机设计

State Machine Design

使用 V11.0 状态机规范：

mermaid

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

Use V11.0 state machine specification:

mermaid

stateDiagram-v2
    [*] --> UNKNOWN
    UNKNOWN --> NORMAL: Detection successful
    UNKNOWN --> ABNORMAL: Detection failed
    NORMAL --> CHECKING: Start detection
    CHECKING --> NORMAL: Detection completed
    CHECKING --> REPAIRING: Need repair
    CHECKING --> ABNORMAL: Detection failed
    REPAIRING --> NORMAL: Repair successful
    REPAIRING --> ABNORMAL: Repair failed
    ABNORMAL --> CHECKING: Retest

时序图示例

Sequence Diagram Example

mermaid

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

mermaid

sequenceDiagram
    participant App as Application
    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: Permission verification
    SA->>SA: State verification
    SA->>Tool: executeFormat()
    Tool-->>SA: onProgress(percent)
    SA-->>Kit: onFormatProgress()
    Kit-->>App: progress callback
    Tool-->>SA: result
    SA-->>Kit: result
    Kit-->>App: format result

参考文档

Reference Documents

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

Architecture Design Template: references/architecture_template.md
Functional Design Template: references/functional_template.md
State Machine Specification: references/state_machine_spec.md
Interface Design Guide: references/interface_guide.md

与 PRD 的映射关系

Mapping with PRD

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

PRD Chapter	Design Document Chapter	Mapping Rules
Chapter 4: Competitor Analysis	Chapter 2: Competitor Solution Analysis	Expand PRD's competitor analysis into technical solution comparison
Chapter 2: Requirement Background	Chapter 1: Requirement Background	Direct mapping
Chapter 5: Requirement Description	Chapter 4: Architecture Design	Convert requirements into architecture design
KEP Definition	Module Architecture + Interface Design	Each KEP corresponds to at least one service module
User Story	Functional Specification	Convert user scenarios into functional processes
Acceptance Criteria	Interface Return Value Definition	Convert acceptance conditions into interface contracts
Non-functional Requirements	Technology Selection + Performance Indicators	Technical constraints are reflected in architecture design

依赖服务映射

Dependent Service Mapping

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

Service in Design Document	Corresponding OpenHarmony SA	Description
Permission Verification Service	OsAccount SA (4101)	Reuse account system capabilities
Storage Service	StorageManager SA (5003)	External storage management
Encryption Service	Crypto SA	Disk encryption capabilities

输出目录结构

Output Directory Structure

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

output/
├── architecture_v1.md      # Architecture design document
├── functiondesign_v1.md     # Functional design document
├── code_paths_v1.md        # Code path document
└── diagrams/               # Generated diagram files
    ├── architecture.png
    ├── state_machine.png
    └── sequence.png

使用示例

Usage Examples

生成完整设计文档：

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

仅生成架构设计：

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

指定 SA ID：

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

指定产品名称和版本：

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

指定输出目录：

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

Generate complete design documents:

Generate architecture and functional design documents based on {PRD Document}

Generate only architecture design:

Generate only architecture design document based on {PRD Document}

Specify SA ID:

Generate design documents using {SA_ID} as SA ID, based on {PRD Document}

Specify product name and version:

Generate design documents for {Product Name} {Version}, document version {Document Version}, based on {PRD Document}

Specify output directory:

Generate design documents to ./design_docs directory, based on {PRD Document}

命名规范

Naming Conventions

文档类型	命名格式	示例
架构设计	`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

Document Type	Naming Format	Example
Architecture Design	`architecture_v{major}.md`	architecture_v1.md
Functional Design	`functiondesign_v{major}.md`	functiondesign_v1.md
Code Path	`code_paths_v{major}.md`	code_paths_v1.md
PRD Reference	`prd_v{version}.md`	prd_v17.md

版本管理规则

Version Management Rules

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

Version Change	Update Content
PRD version change	Increment design document version synchronously
Architecture adjustment	Add .1 sub-version (V1.0 → V1.1)
New function added	Increment minor version number (V1.0 → V2.0)

图表格式

Chart Format

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

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

Use Mermaid syntax to draw charts. Supported chart types:

Flowchart:
```
graph TD
```
or
```
flowchart TD
```
State Diagram:
```
stateDiagram-v2
```
Sequence Diagram:
```
sequenceDiagram
```
Class Diagram:
```
classDiagram
```
Component Diagram:
```
graph LR
```

错误处理

Error Handling

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

Error Type	Handling Method
PRD file does not exist	Prompt for wrong file path
PRD lacks competitor analysis	Prompt to supplement Chapter 4 of PRD with competitor analysis, or generate based on existing information
Architecture document lacks Chapter 2: Competitor Solution Analysis	Return error: Chapter 2 must be Competitor Solution Analysis
Chapter order is wrong	Prompt: Chapter 2 must be Competitor Solution Analysis, placed after Requirement Background
KEP parsing failed	List missing KEP definitions
Format does not meet specifications	Generate according to default template
Output directory is not writable	Prompt for permission issues