init

README.md

@@ -0,0 +1,446 @@
+# 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)。

docs/governance/document-rules.md

@@ -0,0 +1,380 @@
+# 产品文档写作约束
+
+本文档定义 IoT 产品定义文档的写作边界。它回答三个问题：
+
+- 每一层应该写什么
+- 每一层不应该写什么
+- 文档之间应该如何引用、继承和维护
+
+这套约束适用于通用规则、单品 PDD、角色视图和文档协作规范。
+
+## 总体写作原则
+
+### 只写产品定义，不写技术实现
+
+产品文档描述用户体验、产品规则、业务边界、异常处理和跨团队协作口径。
+
+产品文档不展开具体技术实现方案。
+
+推荐写法：
+
+```markdown
+设备离线后，App 应在设备卡片展示离线状态，并提示用户检查电源与网络。
+```
+
+不推荐写法：
+
+```markdown
+设备端每 30 秒上报一次心跳，云端超过 90 秒未收到 MQTT 消息后将设备标记为离线。
+```
+
+如果某条规则必须依赖技术条件，也只描述产品侧可感知的条件和结果。
+
+### 一个事实只写一次
+
+通用规则只允许在通用规则层定义。单品 PDD、角色视图和其他文档只能引用，不应复制全文。
+
+推荐写法：
+
+```markdown
+本产品配网超时体验遵循 [通用配网体验规则](../domain/networking.md#配网超时)。
+
+引用规则：NET-PAIRING-TIMEOUT
+```
+
+不推荐写法：
+
+```markdown
+配网超时为 90 秒。超时后 App 提示用户检查 Wi-Fi 密码、网络环境和设备状态。
+```
+
+如果这段内容已经属于通用规则，就不应在单品 PDD 中重复维护。
+
+### 先判断归属，再写内容
+
+写任何规则前，先判断它属于哪一层。
+
+- 多个设备都会用到：写入通用规则层
+- 只属于某一款设备：写入单品定义层
+- 只是给某个角色阅读：写入交付视图层
+- 是文档维护方式：写入协作管理层
+
+不要因为某个内容当前只被一个设备使用，就立即写进单品 PDD。如果它未来大概率会复用，应优先放入通用规则层。
+
+### 允许差异，但必须说明原因
+
+单品可以偏离通用规则，但必须说明差异原因。
+
+差异原因通常来自：
+
+- 硬件形态限制
+- 安装环境限制
+- 目标用户差异
+- 使用场景差异
+- 法规或认证要求
+- 成本、续航、体积等产品约束
+
+推荐写法：
+
+```markdown
+本产品不使用声音告警。
+
+差异原因：设备主要安装在卧室，声音告警可能打扰用户休息。
+
+替代体验：通过 App 推送和红灯慢闪提示异常。
+```
+
+## 一、通用规则层
+
+### 应该写什么
+
+通用规则层写跨设备复用的产品规则，是产品定义体系的唯一事实来源。
+
+应该写：
+
+- 设备生命周期状态
+- HMI 指示灯、按键、蜂鸣器等交互语言
+- 通用配网流程和异常体验
+- 绑定、解绑、分享、迁移规则
+- 通用告警分级和提示口径
+- App 通用状态展示规则
+- OTA 体验规则
+- 数据采集口径
+- 权限和安全相关的产品规则
+- 跨设备复用的术语定义
+
+### 不应该写什么
+
+通用规则层不写单个设备的专属定义。
+
+不应该写：
+
+- 某一款设备的产品定位
+- 某一款设备的目标用户画像
+- 某一款设备的外观、尺寸、材质
+- 某一款设备的独有安装方式
+- 某一款设备的独有卖点
+- 某一款设备的项目排期
+- 某一款设备的研发实现方案
+- 某一款设备的临时决策过程
+
+### 写作要求
+
+每条通用规则应包含：
+
+- 规则名称
+- 规则编号
+- 适用范围
+- 产品定义
+- 用户感知
+- 触发条件
+- 例外情况
+- 被引用产品
+- 版本记录
+
+建议结构：
+
+```markdown
+### 配网超时
+
+规则编号：NET-PAIRING-TIMEOUT
+
+适用范围：所有需要 App 配网的设备。
+
+产品定义：设备进入配网流程后，如果在规定时间内未完成绑定，系统应判定为配网超时。
+
+用户感知：App 展示配网失败，并提供重新配网入口。
+
+触发条件：用户发起配网后，设备未在规定时间内完成绑定。
+
+例外情况：无 App 配网能力的设备不适用。
+
+被引用产品：
+
+- sensor-a
+- gateway-a
+```
+
+## 二、单品定义层
+
+### 应该写什么
+
+单品定义层写具体设备的 PDD，描述这款产品本身。
+
+应该写：
+
+- 产品定位
+- 目标用户
+- 核心场景
+- 产品价值
+- 功能范围
+- 不做什么
+- 设备形态
+- 安装方式
+- 供电方式
+- 续航目标
+- 环境约束
+- 与通用规则的引用关系
+- 本产品独有规则
+- 本产品对通用规则的差异说明
+- 异常体验和边界条件
+- 版本记录
+
+### 不应该写什么
+
+单品定义层不重复写通用规则，不展开技术方案。
+
+不应该写：
+
+- 已在通用规则层定义过的完整规则
+- 其他设备的产品定义
+- 技术协议字段
+- 数据库表结构
+- 接口请求和响应
+- 固件任务拆分
+- 研发排期细节
+- 测试用例全文
+- 运营话术全文
+
+### 写作要求
+
+单品 PDD 应明确区分三类内容：
+
+- 引用规则：来自通用规则层
+- 本品规则：只属于当前设备
+- 差异规则：对通用规则的例外或微调
+
+建议结构：
+
+```markdown
+## 引用的通用规则
+
+- [HMI 全局交互字典](../../domain/hmi-dictionary.md)
+- [通用配网体验规则](../../domain/networking.md)
+- [设备生命周期状态](../../domain/device-lifecycle.md)
+
+## 本产品独有规则
+
+本产品支持磁吸安装，用户可在金属表面直接固定设备。
+
+## 通用规则差异
+
+通用规则：HMI-LIGHT-RED-FAST
+
+差异说明：本产品无红色指示灯，致命故障改为 App 强提醒 + 蜂鸣器连续 3 声。
+
+差异原因：设备仅配置单色白灯，无法表达红灯状态。
+```
+
+## 三、协作管理层
+
+### 应该写什么
+
+协作管理层写文档体系如何被维护。
+
+应该写：
+
+- 文档命名规则
+- 目录结构规则
+- Markdown 引用规则
+- 规则编号规则
+- Git 分支规则
+- 提交信息规则
+- PR 评审要求
+- 版本标签规则
+- 变更记录格式
+- 废弃规则处理方式
+- 文档责任人机制
+
+### 不应该写什么
+
+协作管理层不写具体产品内容。
+
+不应该写：
+
+- 单个设备的功能定义
+- 单个设备的用户场景
+- 单个设备的物理约束
+- 某条具体 HMI 规则的完整定义
+- 某条具体告警规则的完整定义
+- 项目会议纪要全文
+
+### 写作要求
+
+协作管理层应写成可执行的规则，而不是泛泛建议。
+
+推荐写法：
+
+```markdown
+单品 PDD 引用通用规则时，必须同时包含 Markdown 链接和规则编号。
+```
+
+不推荐写法：
+
+```markdown
+建议大家尽量保持文档引用清晰。
+```
+
+## 四、交付视图层
+
+### 应该写什么
+
+交付视图层写不同角色的阅读入口。它从已有文档中组织信息，而不是创造新的产品事实。
+
+应该写：
+
+- 硬件团队关注的产品约束入口
+- 设计团队关注的交互规则入口
+- 研发团队关注的状态和边界规则入口
+- 运营团队关注的用户场景和告警解释入口
+- 管理团队关注的范围、风险和版本入口
+
+### 不应该写什么
+
+交付视图层不应成为新的事实来源。
+
+不应该写：
+
+- 未在通用规则层或单品定义层出现的新规则
+- 与原始文档不一致的改写
+- 为了阅读方便而复制大段原文
+- 绕过 PDD 的临时口径
+- 只存在于视图层的产品承诺
+
+### 写作要求
+
+交付视图层应以链接和摘要为主。
+
+推荐写法：
+
+```markdown
+## 设计团队入口
+
+- 配网流程：[通用配网体验规则](../domain/networking.md)
+- 指示灯语言：[HMI 全局交互字典](../domain/hmi-dictionary.md)
+- sensor-a 差异规则：[sensor-a PDD](../products/sensor-a/pdd.md#通用规则差异)
+```
+
+不推荐写法：
+
+```markdown
+## 设计团队入口
+
+这里重新完整描述一遍配网流程、指示灯规则和 sensor-a 的所有差异。
+```
+
+## 内容归属判断表
+
+| 内容 | 应放层级 | 原因 |
+| --- | --- | --- |
+| 蓝灯慢闪代表配网中 | 通用规则层 | 多设备复用的 HMI 语言 |
+| 某设备没有蓝灯 | 单品定义层 | 单品硬件差异 |
+| 配网超时时间 | 通用规则层 | 跨设备一致体验 |
+| 某设备配网超时后只震动不亮灯 | 单品定义层 | 单品差异 |
+| 文档必须使用相对链接 | 协作管理层 | 文档维护规则 |
+| 给设计团队的阅读入口 | 交付视图层 | 面向角色的信息组织 |
+| 产品卖点介绍 | 单品定义层 | 单个产品的市场与用户价值 |
+| 告警分级标准 | 通用规则层 | 跨设备复用规则 |
+| 某设备不支持 OTA | 单品定义层 | 单品能力限制 |
+| Git tag 命名方式 | 协作管理层 | 版本管理规则 |
+
+## 文档写作检查清单
+
+提交任何产品文档前，应检查：
+
+- 是否写的是产品定义，而不是技术实现
+- 是否存在重复定义通用规则
+- 是否明确了内容所属层级
+- 是否为通用规则提供了规则编号
+- 是否使用了相对链接
+- 是否说明了单品差异原因
+- 是否避免在视图层创造新规则
+- 是否记录了重要变更
+- 是否能让对应团队直接理解并执行
+
+## 禁止事项
+
+以下行为会破坏产品文档体系，应避免：
+
+- 把同一条规则复制到多个 PDD 中
+- 在角色视图中偷偷新增产品规则
+- 在单品 PDD 中写大量接口、协议、数据库、固件任务内容
+- 修改通用规则但不说明影响范围
+- 删除规则但不说明替代方案
+- 使用无法迁移的本地绝对路径作为文档链接
+- 使用“见群聊”“见会议纪要”作为规则来源
+- 用口头约定替代文档规则
+
+## 最小落地约束
+
+如果团队刚开始执行，至少遵守以下规则：
+
+- 所有通用规则放在 `docs/domain/`
+- 所有单品 PDD 放在 `docs/products/`
+- 所有文档使用 Markdown
+- 所有跨文档引用使用相对链接
+- 所有通用规则必须有规则编号
+- 单品 PDD 不复制通用规则全文
+- 通用规则变更必须记录影响范围
+
+先做到这些，就能避免大部分产品矩阵文档失控问题。