需求分析与文档总览
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. 关键产品决策
- 第一阶段只闭环，不铺摊子：优先交付一条可测试路径——创建产品 → 注册设备 → 上报 → 用户绑定 → 查看 → 控制 → 审计。
- 物模型是产品级契约：产品定义能力；设备保存身份、归属和运行态，不把展示字段直接硬编码成协议。
- 设备影子不是历史库：影子保存当前期望值/上报值及版本；遥测历史进入时序数据存储。
- 绑定关系必须原子且可追溯：扫码只是输入方式，真正安全边界是绑定码状态、设备当前归属和用户身份。
- HTTP 成功不代表控制成功：生产环境以设备 ACK 更新最终状态，超时应明确显示。
- 多租户在开放前建设：任何客户自有设备、白标应用或 OpenAPI 都必须先具有 tenant_id 隔离。
3. 文档导航与权威性
| 文档 | 用途 | 状态 |
|---|---|---|
交付记录/MODIFIED_FILE.md | 从原文整理的产品/交付需求基线 | 当前范围权威来源 |
03.需求分析.md | 全量软硬件需求框架 | 与需求基线联合阅读 |
04.概要设计.md | Spring Boot 单体架构和模块划分 | 当前技术基线 |
05.详细设计.md | 生产目标的详细设计 | 当前代码映射见 05.1 |
05.1.关键系统设计.md | 状态机、鉴权、Kafka 消息和一致性 | 当前关键设计 |
06.测试方案.md | 测试策略 | 后端由 Maven、前端由 Vite 构建验证 |
07.部署与运维.md | 本地与生产部署、备份和观测 | 当前部署基线 |
08.用户手册.md | 管理后台与小程序操作 | 当前操作说明 |
09.验收方案.md | 阶段验收 | 以 AC-01～AC-10 作为一期门槛 |
10.MVP实现说明.md | 本次实现范围、运行和技术债 | 本次新增 |
11.API接口文档.md | 当前可执行 API 契约 | 本次新增 |
12.迭代路线图.md | 从 MVP 到生产一期及 SaaS 的演进 | 本次新增 |
若旧文档中的示例技术栈、接口路径或性能数字与当前实现冲突：当前代码以 11.API接口文档.md 为准，产品范围以 MODIFIED_FILE.md 为准，生产目标以概要/详细设计为准。
4. 本次实现覆盖矩阵
| 能力 | 管理后台 | 后端 | 小程序 | 自动验证 |
|---|---|---|---|---|
| 管理员/运维登录 | ✓ | ✓ | — | ✓ |
| 产品查看/创建 | ✓ | ✓ | — | ✓ |
| 设备查看/注册 | ✓ | ✓ | — | ✓ |
| 设备遥测与在线状态 | 展示 | ✓ | 展示 | ✓ |
| 用户设备绑定 | 查看 | ✓ | ✓ | ✓ |
| 设备指令 | ✓ | ✓ | ✓ | ✓ |
| 告警查看与处置 | ✓ | ✓ | — | ✓ |
| 用户与角色边界 | ✓ | ✓ | ✓ | ✓ |
| 审计日志 | ✓ | ✓ | — | ✓ |
| 真实 MQTT/ACK | — | 接口语义预留 | — | 后续 |
| 企业多租户/OpenAPI | — | — | — | 二/三期 |
5. 评审建议
产品评审先确认首期边界、绑定/解绑规则和离线控制体验；硬件评审确认设备身份烧录、绑定码标签和 ACK 格式；后端评审确认模块化单体边界、Kafka 消息幂等与未来拆分条件；测试评审直接以 AC-01～AC-10 转成环境化用例。收到中间件地址文档后，按现有环境变量完成 MySQL、Redis、Kafka 和 EMQX 双向链路联调。