需求分析与文档总览

1. 对《本司设备联网管理》的分析结论

原始文档已经明确了正确的产品主线：自有设备先行 → 用户设备控制 → 开放客户设备 → 企业 SaaS 与 OpenAPI。其价值不是单纯“做一个 MQTT 管理页面”，而是建立设备产品化、交付和持续服务能力。

已明确的内容

  • 管理对象包含 MQTT 透传设备、网关、智能开关等多类本司硬件。
  • 第一阶段优先做设备录入、注册、接入、功能配置、指令下发、用户和设备绑定。
  • 终端用户通过小程序或 App 扫码/输入唯一编号绑定并控制设备。
  • 后续允许客户按平台协议接入自有设备，并提供企业 SaaS、定制 OpenAPI 和现场安装管理。
  • 第二阶段的应用个性化和第三阶段的企业服务可以部分并行。

原文需要补齐的关键点

缺口直接风险本次处理
“录入、注册、接入、绑定”边界不清数据状态混乱、设备容易重复归属定义产品、设备身份、联网鉴权、用户绑定四个不同过程
设备控制只有“下发”没有 ACK 状态机页面显示成功但设备未执行定义 pending/sent/succeeded/failed/timeout 状态机
未定义个人、运维、平台、企业角色越权访问其他用户或企业设备建立 RBAC + 设备归属 + 后续 tenant_id 边界
物模型和设备影子没有落到业务每类硬件都写一套页面和协议以属性、服务、事件统一表达能力，以影子承载期望/上报状态
第二/三阶段范围过大首期同时建设低代码、ERP、SaaS 导致失焦以纵向 MVP 验证首期闭环，再按能力门槛迭代
安全、幂等和密钥生命周期未描述重放、冒用、重复指令和数据泄漏补充设备密钥、Token、幂等键、审计与生产门禁
指标缺少测量口径无法验收增加 AC-01～AC-10 和非功能基线

2. 关键产品决策

  1. 第一阶段只闭环，不铺摊子：优先交付一条可测试路径——创建产品 → 注册设备 → 上报 → 用户绑定 → 查看 → 控制 → 审计。
  2. 物模型是产品级契约：产品定义能力；设备保存身份、归属和运行态，不把展示字段直接硬编码成协议。
  3. 设备影子不是历史库：影子保存当前期望值/上报值及版本；遥测历史进入时序数据存储。
  4. 绑定关系必须原子且可追溯：扫码只是输入方式，真正安全边界是绑定码状态、设备当前归属和用户身份。
  5. HTTP 成功不代表控制成功：生产环境以设备 ACK 更新最终状态，超时应明确显示。
  6. 多租户在开放前建设：任何客户自有设备、白标应用或 OpenAPI 都必须先具有 tenant_id 隔离。

3. 文档导航与权威性

文档用途状态
交付记录/MODIFIED_FILE.md从原文整理的产品/交付需求基线当前范围权威来源
3需求分析.md全量软硬件需求框架已有；与需求基线联合阅读
4概要设计.md目标架构和模块划分已有；MVP 取舍见实现说明
5系统设计.md生产目标的详细设计已有；当前代码映射见 5-1
5-1系统设计-一些细节.md状态机、鉴权、数据一致性和实现映射本次完善
6.测试文档.md测试策略已有；自动验证由 npm test 执行
7.部署与运维.md本地与生产部署、备份和观测本次完善
8.用户手册.md管理后台与小程序操作本次完善
9验收文档.md阶段验收已有；以 AC-01～AC-10 作为 MVP 门槛
10.MVP实现说明.md本次实现范围、运行和技术债本次新增
11.API接口文档.md当前可执行 API 契约本次新增
12.迭代路线图.md从 MVP 到生产一期及 SaaS 的演进本次新增

若旧文档中的示例技术栈、接口路径或性能数字与当前实现冲突：当前代码以 11.API接口文档.md 为准，产品范围以 MODIFIED_FILE.md 为准，生产目标以概要/详细设计为准。

4. 本次实现覆盖矩阵

能力管理后台后端小程序自动验证
管理员/运维登录✓✓—✓
产品查看/创建✓✓—✓
设备查看/注册✓✓—✓
设备遥测与在线状态展示✓展示✓
用户设备绑定查看✓✓✓
设备指令✓✓✓✓
告警查看与处置✓✓—✓
用户与角色边界✓✓✓✓
审计日志✓✓—✓
真实 MQTT/ACK—接口语义预留—后续
企业多租户/OpenAPI———二/三期

5. 评审建议

产品评审先确认首期边界、绑定/解绑规则和离线控制体验；硬件评审确认设备身份烧录、绑定码标签和 ACK 格式；后端评审确认多租户迁移策略和消息幂等；测试评审直接以 AC-01～AC-10 转成环境化用例。完成这四项后再进入真实 EMQX 与数据库开发，可显著减少返工。