| name | oh-pdd-design-doc-generator |
| description | 基于 PRD 文档自动生成鸿蒙系统设计文档，包括架构设计文档和功能设计文档。生成前会分析 OpenHarmony 存量代码结构，确保与现有架构兼容。架构设计文档第2章必须为竞品方案分析，位于需求背景之后。适用于用户请求：(1) 生成架构设计文档, (2) 生成功能设计文档, (3) 从 PRD 生成设计文档, (4) 创建系统架构设计, (5) 编写功能规格说明, (6) 分析 OH 代码结构。关键词：architecture design, functional design, design doc, 竞品方案分析, OpenHarmony code analysis, 架构设计, 功能设计, 设计文档生成, OH代码分析, analyze codebase, competitor analysis |
设计文档生成器
基于 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/ |
分析输出
代码分析完成后生成：
- 现有 SA 清单: 已分配的 SA ID 和服务名称
- 子系统组织: 子系统和部件的层次结构
- 依赖关系图: 组件间的依赖关系
- 接口参考: 相似功能的接口设计参考
- 代码风格参考: 命名规范、目录结构等
竞品方案分析章节要求
架构设计文档 第2章必须为竞品方案分析，位于需求背景之后、鸿蒙系统架构分析之前。
章节结构
2. 竞品方案分析
2.1 竞品识别
- 列出主要竞品（至少2-3个）
- 说明竞品选择理由
- 竞品类型：同类产品、技术方案、行业标准
2.2 竞品技术方案分析
对每个竞品分析：
- 核心技术架构
- 关键技术组件
- 通信机制
- 数据流程
- 关键流程图、时序图
2.3 技术对比表格
| 对比项 | 本方案 | 竞品A | 竞品B |
|---|
| 架构模式 | | | |
| 核心技术 | | | |
| 通信机制 | | | |
| 进程模型 | | | |
| 安全机制 | | | |
| 跨语言支持 | | | |
2.4 差异化设计
- 本方案相对于竞品的创新点
- 解决的竞品痛点
- 技术优势说明
- 借鉴与改进
输出要求
- 使用4+1视图、流程图、时序图呈现竞品技术方案
- 至少包含2个竞品的详细分析
- 必须有技术对比表格
- 必须明确差异化设计点
章节顺序验证
生成架构设计文档时，验证章节顺序：
标准顺序：需求背景 → 竞品方案分析 → 鸿蒙系统架构分析 → 架构设计...
验证规则：
- ✅ 第1章必须是"需求背景"
- ✅ 第2章必须是"竞品方案分析"（必需）
- ✅ 竞品方案分析必须在需求背景之后
- ✅ 竞品方案分析必须在架构设计之前
- ❌ 如顺序错误，提示用户调整
验证逻辑：
- 提取文档中所有一级标题（# 开头）
- 验证第1章是否为"需求背景"
- 验证第2章是否为"竞品方案分析"或"竞品分析"
- 如缺失第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
参考文档
与 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 定义 |
| 格式不符合规范 | 按默认模板生成 |
| 输出目录不可写 | 提示权限问题 |
