init

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 不复制通用规则全文
+- 通用规则变更必须记录影响范围
+
+先做到这些，就能避免大部分产品矩阵文档失控问题。