447 lines
11 KiB
Markdown
447 lines
11 KiB
Markdown
# 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)。
|