# 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)。