pdd-word/README.md

# IoT 产品定义文档分层体系

本文档用于记录一套面向 IoT 产品矩阵的产品文档组织方法。目标不是把单篇 PDD 写得更长，而是让产品定义可以被复用、引用、追踪和长期维护。

当设备数量增加后，如果每一款设备都独立维护完整 PDD，通用规则很容易出现重复、遗漏和互相矛盾。比如配网超时时间、指示灯含义、设备离线提示、数据采集口径等规则，一旦散落在多篇文档里，就很难保证所有产品同步更新。

因此，IoT 产品文档应当从“单篇文档写作”升级为“分层产品定义体系”。

## 核心原则

### 唯一事实来源

所有通用产品规则只在一个地方定义。其他文档通过链接引用，不复制粘贴。

例如：

- 配网失败反馈只在通用配网规则中定义
- 指示灯含义只在 HMI 交互字典中定义
- 数据采集口径只在全局数据规范中定义
- OTA 状态体验只在通用 OTA 规则中定义

这样，当通用规则发生变化时，只需要修改唯一来源，所有引用该规则的产品文档都能保持一致。

### 共性与差异分离

通用规则归入产品资产库，单品 PDD 只描述这款设备的独有部分。

单品文档不应重复解释全局规则，而应说明：

- 本产品引用了哪些通用规则
- 本产品在哪些地方有特殊约束
- 特殊约束为什么存在
- 特殊约束是否影响通用体验

### 产品语言优先

文档关注产品定义、用户体验、业务规则和跨团队协作，不展开技术实现方案。

可以描述“设备离线后 App 应提示用户检查电源与网络”，但不描述云端如何检测心跳、设备如何上报协议字段。

### 可追踪、可评审、可回溯

产品规则的变更要能被追踪。通过 Markdown + Git 管理文档，可以像管理产品资产一样管理文档版本。

每一次规则变更都应留下：

- 修改原因
- 影响范围
- 评审记录
- 生效版本

## 四层文档结构

### 1. 通用规则层

通用规则层是所有设备共同遵守的产品资产库，也是产品定义体系中的唯一事实来源。

这一层不针对某一款具体设备，而是沉淀跨设备复用的产品规则。

典型内容包括：

- HMI 全局交互字典
- 设备生命周期状态
- 通用配网体验规则
- 通用异常与告警规则
- App 通用提示规范
- OTA 体验规则
- 全局数据采集口径
- 权限、分享、绑定、解绑规则

示例：

```markdown
## 蓝灯慢闪

含义：设备正在进入配网状态。

适用范围：所有带蓝色指示灯的无屏设备。

用户感知：用户可通过 App 搜索并绑定设备。

引用编号：HMI-LIGHT-BLUE-SLOW
```

### 2. 单品定义层

单品定义层是具体设备的 PDD。它描述某一款设备的产品目标、用户场景、功能范围、物理约束和差异化规则。

这一层的重点是“拼装和微调”通用规则，而不是从零定义所有规则。

单品 PDD 应重点写：

- 产品定位
- 目标用户
- 使用场景
- 核心功能
- 设备形态
- 物理约束
- 续航、安装、环境要求
- 与通用规则的引用关系
- 本设备独有的业务逻辑
- 本设备对通用规则的例外说明

示例：

```markdown
## 配网失败反馈

本产品遵循 [通用配网体验规则](../domain/networking.md) 中的失败反馈规范。

由于本设备无屏幕，配网失败时仅通过蓝灯急闪 3 次和 App Toast 进行提示。

引用规则：

- HMI-LIGHT-BLUE-FAST-3
- NET-PAIRING-FAILED
```

### 3. 协作管理层

协作管理层定义文档如何被创建、引用、评审、修改和发布。

它不是某一款产品的内容，而是保证文档体系长期可维护的工作规则。

建议规则包括：

- 通用规则必须有唯一编号
- 单品 PDD 引用通用规则时必须使用 Markdown 链接
- 不允许在单品 PDD 中复制粘贴整段通用规则
- 修改通用规则时必须说明影响哪些设备
- 重大规则变更需要产品、设计、硬件、研发共同确认
- 废弃规则不得直接删除，应标记为已废弃并说明替代规则
- 每个单品 PDD 应记录引用的通用规则清单

### 4. 交付视图层

交付视图层用于让不同角色快速看到自己关心的内容。

它不是重新写多份文档，而是基于同一套产品定义，整理面向不同团队的阅读入口。

常见视图包括：

- 硬件视图：物理形态、安装方式、环境约束、功耗、指示灯、按键
- 设计视图：HMI、App 页面状态、异常提示、用户路径
- 研发视图：状态定义、边界规则、数据口径、异常条件
- 运营视图：卖点、用户场景、告警解释、售后处理口径
- 管理视图：产品范围、版本变化、风险点、上线状态

## 推荐目录结构

建议使用 Markdown 文件组织产品文档，并通过 Git 管理版本。

```text
docs/
  domain/
    README.md
    hmi-dictionary.md
    device-lifecycle.md
    networking.md
    alerts.md
    data-collection.md
    ota.md

  products/
    sensor-a/
      README.md
      pdd.md
      references.md
    gateway-a/
      README.md
      pdd.md
      references.md

  views/
    hardware.md
    design.md
    product.md
    operations.md

  governance/
    document-rules.md
    change-log.md
    review-process.md
```

目录说明：

- `docs/domain/` 存放通用规则，是产品定义的资产库
- `docs/products/` 存放具体单品 PDD
- `docs/views/` 存放按角色组织的阅读入口
- `docs/governance/` 存放文档协作与维护规则

## Markdown 引用与跳转规则

### 使用相对链接

文档之间统一使用相对路径跳转，便于在 Git 仓库、代码编辑器和文档平台中迁移。

示例：

```markdown
[HMI 全局交互字典](../domain/hmi-dictionary.md)
[通用配网体验规则](../domain/networking.md)
[设备生命周期状态](../domain/device-lifecycle.md)
```

### 使用标题锚点

当需要跳转到具体章节时，可以使用 Markdown 标题锚点。

示例：

```markdown
[蓝灯慢闪](../domain/hmi-dictionary.md#蓝灯慢闪)
[配网失败](../domain/networking.md#配网失败)
```

标题命名应稳定，避免频繁改名。重要规则建议同时提供规则编号，降低标题变化带来的影响。

### 使用规则编号

每条通用规则建议拥有唯一编号。

编号示例：

- `HMI-LIGHT-BLUE-SLOW`
- `HMI-LIGHT-BLUE-FAST-3`
- `NET-PAIRING-TIMEOUT`
- `DEVICE-OFFLINE-PROTECTION`
- `DATA-BATTERY-THRESHOLD`

单品 PDD 中引用规则时，应同时写 Markdown 链接和规则编号。

示例：

```markdown
本产品配网超时规则遵循 [通用配网体验规则](../domain/networking.md#配网超时)。

引用规则：NET-PAIRING-TIMEOUT
```

### 避免复制粘贴通用规则

单品 PDD 中只保留必要说明和差异化解释，不复制通用规则全文。

推荐写法：

```markdown
本产品遵循 [HMI 全局交互字典](../domain/hmi-dictionary.md#蓝灯慢闪) 中的蓝灯慢闪规则。

差异说明：本产品指示灯位于设备底部，安装后可能不可见，因此 App 端需同步展示配网中状态。
```

不推荐写法：

```markdown
蓝灯慢闪表示设备正在进入配网状态，用户可通过 App 搜索并绑定设备……
```

如果这段内容已经在通用规则层存在，就不应在单品 PDD 中重复维护。

## Git 管理方式

### 分支管理

建议不同类型的文档修改使用不同分支。

示例：

```text
docs/domain-networking-update
docs/product-sensor-a-pdd
docs/hmi-dictionary-review
```

### 提交信息

提交信息应说明修改对象和修改目的。

示例：

```text
docs(domain): update pairing timeout rule
docs(product): add sensor-a PDD references
docs(governance): define review process
```

如果团队全部使用中文，也可以使用中文提交信息。

示例：

```text
docs(domain): 调整配网超时规则
docs(product): 新增 sensor-a 产品定义
docs(governance): 补充文档评审流程
```

### Pull Request 评审

涉及通用规则层的修改，应通过 Pull Request 或等价评审流程确认。

PR 描述建议包含：

- 修改了什么
- 为什么修改
- 影响哪些产品
- 是否需要同步设计、硬件、研发、运营
- 是否存在历史版本兼容问题

### 变更记录

重要规则变更应记录在 `docs/governance/change-log.md` 中。

建议格式：

```markdown
## 2026-06-09

### NET-PAIRING-TIMEOUT

变更：配网超时时间从 60 秒调整为 90 秒。

原因：降低弱网环境下的配网失败率。

影响范围：

- sensor-a
- gateway-a

确认人：产品、设计、研发
```

### 标签与版本

当某一批产品文档进入稳定交付状态时，可以使用 Git tag 标记版本。

示例：

```text
product-docs-v1.0
sensor-a-pdd-v1.0
domain-rules-v1.0
```

版本标签用于回溯某个时间点的产品定义，尤其适合硬件量产、测试冻结、上线发布等场景。

## 单品 PDD 建议模板

```markdown
# 产品名称 PDD

## 产品定位

说明产品面向的用户、场景和核心价值。

## 用户场景

说明用户在什么情况下使用该产品，以及产品解决什么问题。

## 功能范围

列出本产品包含和不包含的能力。

## 物理形态与约束

说明外观、安装方式、防水等级、供电方式、续航、环境要求等。

## 引用的通用规则

- [HMI 全局交互字典](../../domain/hmi-dictionary.md)
- [设备生命周期状态](../../domain/device-lifecycle.md)
- [通用配网体验规则](../../domain/networking.md)
- [通用异常与告警规则](../../domain/alerts.md)
- [全局数据采集口径](../../domain/data-collection.md)

## 本产品差异化规则

说明本产品相对于通用规则的差异。

## 边界与异常

说明用户可能遇到的异常状态，以及产品侧如何定义体验。

## 版本记录

记录本 PDD 的关键变更。
```

## 通用规则文档建议模板

```markdown
# 通用规则名称

## 适用范围

说明该规则适用于哪些产品、设备形态或用户场景。

## 规则列表

### 规则名称

规则编号：RULE-ID

规则说明：说明产品表现、用户感知和业务含义。

适用条件：说明什么时候触发该规则。

例外情况：说明哪些产品或场景不适用。

## 被引用产品

列出当前引用该规则的产品文档。

## 版本记录

记录规则变更历史。
```

## 落地建议

第一阶段先建立最小可用的产品资产库：

- HMI 全局交互字典
- 设备生命周期状态
- 通用配网体验规则
- 单品 PDD 模板

第二阶段再补充跨设备共用规则：

- 告警规则
- 数据采集口径
- OTA 体验规则
- 绑定、解绑、分享规则

第三阶段建立协作机制：

- 文档评审流程
- 变更记录
- 版本标签
- 角色视图

这套体系的价值不在于文档数量更多，而在于让产品规则从分散文本变成可复用、可引用、可追踪的产品资产。

## 文档约束

每一层应该写什么、不应该写什么，以及文档之间如何引用和维护，见 [产品文档写作约束](docs/governance/document-rules.md)。

## 示例文档

第一份完整示例为 [智能小夜灯 Mini PDD](docs/products/smart-lamp-mini/pdd.md)。

该示例包含：

- [通用规则层](docs/domain/README.md)
- [引用规则清单](docs/products/smart-lamp-mini/references.md)
- [角色视图](docs/views/smart-lamp-mini-role-view.md)