oh-pdd-design-doc-generator

Design Document Generator

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

Quick Start

Provide the PRD document path:

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

Specify the output type:

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

OpenHarmony Code Analysis

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

Analysis Steps

1. Discover Code Structure

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

File Type	Search Pattern	Description
Configuration Files	`/bundle.json`, `/BUILD.gn`, `**/config.json`	Component definitions, build configurations
Documentation Files	`/README.md`, `/*.md`	Module descriptions, usage guides
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. Search for Key Information

Use the Grep tool to search for keywords and extract component information:

Search Target	Search Keyword	Extracted Information
SA ID	`"sa-id"`	Allocated SA IDs
Subsystem	`subsystem_name`	Subsystem organization
Dependencies	`external_deps`	Component dependencies
Interface Definitions	`interface`	IDL interfaces
Service Classes	`class.*Service`	Service implementation classes
Provider	`.*Provider`	SA Provider classes

3. Read Key Configurations

Use the Read tool to read key configuration files:

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

4. Intelligent Exploration

Use the Task tool to launch the Explore agent for multiple rounds of exploration:

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

Naming Pattern Inference

Infer functionality through file and directory naming:

Naming Pattern	Inferred Functionality	Example
`*_service.cpp`	Service implementation	`disk_info_service.cpp`
`*_provider.h/cpp`	SA Provider implementation	`disk_manager_provider.cpp`
`*_listener.idl`	Event listener interface	`IDiskChangeListener.idl`
`*_types.idl`	Data type definitions	`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

Generated after code analysis is complete:

Existing SA list: Allocated SA IDs and service names
Subsystem organization: Hierarchy of subsystems and components
Dependency graph: Dependencies between components
Interface reference: Interface design reference for similar functions
Code style reference: Naming conventions, directory structure, etc.

Competitor solution analysis chapter requirements

Architecture design document Chapter 2 must be competitor solution analysis, located after the requirements background and before the HarmonyOS system architecture analysis.

Chapter structure

2. Competitor solution analysis

2.1 Competitor identification

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

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 Technical comparison table

Comparison item	This solution	Competitor A	Competitor B
Architecture pattern
Core technology
Communication mechanism
Process model
Security mechanism
Cross-language support

2.4 Differentiated design

Innovation points of this solution compared with competitors
Competitor pain points addressed
Explanation of technical advantages
Reference and improvement

Output requirements

Use 4+1 views, flowcharts, and sequence diagrams to present competitor technical solutions
Include detailed analysis of at least 2 competitors
A technical comparison table is required
Differentiated design points must be clearly defined

Chapter order verification

When generating the architecture design document, verify the chapter order:

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

Verification rules：

✅ Chapter 1 must be "Requirements Background"
✅ Chapter 2 must be "Competitor Solution Analysis" (Required）
✅ Competitor solution analysis must be after the requirements background
✅ Competitor solution analysis must be before the architecture design
❌ If the order is incorrect, prompt the user to adjust

Verification logic：

Extract all level-1 headings in the document (starting with #)
Verify whether Chapter 1 is "Requirements Background"
Verify whether Chapter 2 is "Competitor Solution Analysis" or "Competitor Analysis"
If Chapter 2 is missing or the order is incorrect, return an error prompt

Generate content

Architecture design document (architecture_vX.md)

Contains the following standard chapters (in order):

Chapter	Content
1. Requirements background	Project background, business requirements, technical challenges
2. Competitor solution analysis	Competitor identification, technical solution comparison, differentiated design (Required）
3. HarmonyOS system architecture analysis	Existing 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. Requirements breakdown and code volume estimation	Requirements decomposition, code volume estimation
10. Appendix	Error codes, performance metrics

Functional Design Document (functiondesign_vX.md)

Contains the following standard chapters:

Chapter	Content
1. Overview	Document purpose, module list
2. Module definition	Responsibilities, inputs and outputs, and dependencies of each module
3. Interface definition	IDL interfaces, callback interfaces
4. State machine design	State enumeration, transition table, transition diagram
5. Process design	Main flowchart, sequence diagram, exception handling
6. Error handling	Error code definition, handling strategy

Architecture layers

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

SA division rules

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

Use the V11.0 state machine specification:

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

Sequence diagram example

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

Reference documents

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

Mapping relationship with the PRD

PRD chapter	Design document chapter	Mapping rule
Chapter 4: Competitive analysis	Chapter 2: Competitive solution analysis	The PRD's competitive analysis is expanded into a technical solution comparison
Chapter 2: Requirements background	Chapter 1: Requirements background	Direct mapping
Chapter 5: Requirements description	Chapter 4: Architecture design	Requirements are converted into architecture design
KEP definition	Module architecture + interface design	Each KEP corresponds to at least one service module
User story	Functional specification	User scenarios are converted into functional flows
Acceptance criteria	Interface return value definition	Acceptance conditions are converted into interface contracts
Non-functional requirements	Architecture selection + performance metrics	Technical constraints are reflected in the architecture design

Dependent service mapping

Service in the 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 capability

Output directory structure

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

Usage examples

Generate complete design document：

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

Generate architecture design only：

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

Specify SA ID：

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

Specify product name and version：

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

Specify output directory：

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

Naming conventions

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

Version change	Update content
PRD version change	Design document version increments in sync
Architecture adjustment	Add .1 sub-version (V1.0 → V1.1)
New feature	Increase minor version number (V1.0 → V2.0)

Diagram format

Use Mermaid syntax to draw diagrams. Supported diagram types:

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

Error handling

Error type	Handling method
PRD file does not exist	Indicate file path error
PRD lacks competitive analysis	Prompt to supplement Chapter 4 Competitive Analysis of the PRD, or generate based on existing information
Architecture document lacks Chapter 2 Competitive Solution Analysis	Return error: Chapter 2 must be Competitive Solution Analysis
Incorrect chapter order	Prompt: Chapter 2 must be Competitive Solution Analysis, located after Requirements Background
KEP parsing failed	List the missing KEP definitions
Format does not conform to specifications	Generate according to the default template
Output directory is not writable	Indicate permission issue