本司设备联网管理平台产品与交付基线（完善版）
来源：
本司设备联网管理.md。原文件保持不变，本文件将原始构想整理为可设计、可开发、可测试的需求基线。
1. 产品目标
建设统一的设备联网管理平台，先完成本司设备从产品定义、出厂录入、设备注册、联网鉴权、状态监测、用户绑定到远程控制的业务闭环，再扩展客户自有设备接入、企业多租户 SaaS、OpenAPI 和低代码小程序。
首期交付同时包含三类使用端：
- 平台管理后台：供平台管理员、运维人员管理产品、设备、用户、告警和指令。
- 平台后端：提供用户、设备和管理 API，并承接 MQTT/HTTP/TCP 接入层的领域能力。
- 用户小程序：供个人用户登录、扫码或输入绑定码、查看状态、控制本人设备。
2. 角色与权限
| 角色 | 核心权限 | 数据边界 |
|---|---|---|
| 平台管理员 | 产品与物模型、设备、用户、告警、指令、审计、系统参数 | 平台全部数据 |
| 平台运维 | 设备注册与诊断、状态、指令、告警处置 | 平台授权数据；不能修改高危系统配置 |
| 个人用户 | 登录、绑定、解绑申请、查看遥测、控制设备 | 仅本人绑定设备 |
| 企业管理员（二/三期） | 成员、设备、应用、接口凭证、工单 | 本企业租户 |
| 设备身份 | 鉴权、上报属性/事件、接收指令并返回 ACK | 仅设备自身 Topic/接口 |
3. 第一期：本司设备管理闭环（当前实现目标）
3.1 产品与物模型
- 管理产品名称、ProductKey、品类、默认接入协议和物模型版本。
- 同一产品下的设备共享属性、服务、事件定义；设备只保存运行值和差异化配置。
- MVP 内置智能开关、RS485 网关和温湿度传感器三个演示产品。
3.2 设备注册和接入
- 支持后台逐台注册；批量导入列入一期增强项。
- 每台设备生成不可重复的设备 ID、设备密钥和一次性交付语义的绑定码。
- 设备以
deviceId + deviceSecret鉴权；生产环境密钥只在创建时展示，服务端仅保存加密或哈希值。 - 首期协议以 MQTT 为主，HTTP 遥测接口用于联调；TCP 通过独立适配器后续接入。
- 平台记录在线/离线、最后活跃时间、固件版本、当前属性和遥测历史。
3.3 用户绑定
- 小程序用户完成微信登录后，可扫码或手工输入绑定码。
- 绑定必须原子执行：无效码失败；已经归属其他用户的设备禁止再次绑定；重复绑定给同一用户可幂等成功。
- 所有小程序设备查询和控制必须同时校验登录身份与设备归属，不能仅凭设备 ID 操作。
- 解绑、分享家庭成员、所有权转移列入一期增强项，并要求二次确认和审计。
3.4 设备控制
- 管理后台和设备所有者可下发物模型服务或属性设置指令。
- 完整状态机为
pending → sent → succeeded | failed | timeout | canceled。 - 每条指令保留指令 ID、设备、操作人、参数、创建时间、完成时间、重试次数和失败原因。
- 生产控制链路必须以设备 ACK 为最终结果，HTTP 请求成功不能等同于设备执行成功。
- MVP 对在线设备同步模拟成功、离线设备保留为等待中，用于验证交互闭环。
3.5 告警与审计
- 告警覆盖设备离线、遥测越限、设备故障事件、指令失败和平台链路异常。
- 告警状态为待处理、处理中、已恢复；支持处理人、处理备注和通知策略扩展。
- 登录、注册设备、修改设备、绑定设备、下发指令和处置告警等关键动作必须写审计日志。
3.6 首期验收场景
| 编号 | 场景 | 验收结果 |
|---|---|---|
| AC-01 | 管理员登录并查看总览 | 返回设备总数、在线数、用户数、待处理告警和当日指令 |
| AC-02 | 创建产品并注册设备 | ProductKey、序列号保持唯一，设备初始为未绑定/离线 |
| AC-03 | 合法设备上报遥测 | 保存遥测、合并设备影子、刷新在线和最后活跃时间 |
| AC-04 | 非法密钥上报 | 返回 401，不保存数据、不改变设备状态 |
| AC-05 | 用户输入有效绑定码 | 设备归属当前用户，小程序列表立即可见 |
| AC-06 | 用户访问他人设备 | 返回 404/403，不泄露设备详情 |
| AC-07 | 用户控制在线设备 | 创建指令，收到 ACK 后状态成功且影子值更新 |
| AC-08 | 控制离线设备 | 指令进入等待/超时路径，不伪报成功 |
| AC-09 | 运维访问管理员审计接口 | 返回 403 |
| AC-10 | 管理员处置告警 | 告警转为已恢复并形成审计记录 |
4. 第二阶段：开放设备与应用能力
- 发布设备接入规范、主题规范、签名算法、SDK 和自助联调工具。
- 允许客户创建产品、定义物模型、接入自有设备，但所有数据必须进入租户隔离边界。
- 提供应用配置能力：先以模板和主题变量实现白标小程序，再逐步演进到受约束的低代码页面编排。
- 低代码配置采用版本化 DSL、组件白名单、预览/发布审批和回滚机制，避免直接执行用户脚本。
5. 第三阶段：企业 SaaS 与服务履约
- 引入企业、部门、成员、角色、项目、站点和设备组等租户实体。
- 支持企业管理员批量注册/绑定设备、创建服务账号、配置 Webhook 和 OpenAPI 凭证。
- 现场安装服务以工单建模：派单、接单、签到、安装清单、现场图片、工时、验收和费用。
- 对接 OEM/ERP 时提供租户级 API、限流、签名、幂等键、回调重试、调用日志和数据授权。
- 第二阶段与第三阶段可并行，但租户隔离和 API 权限必须先于客户开放。
6. 非功能基线
| 维度 | MVP | 生产一期目标 |
|---|---|---|
| API 可用性 | 单实例可运行 | ≥99.9%，无状态多实例 |
| 管理 API | 本地数据下 P95 < 500ms | P95 < 300ms（不含设备 ACK） |
| 消息链路 | HTTP 模拟、JSON 文件 | EMQX + Kafka，至少一次投递，业务幂等 |
| 设备规模 | 3 个演示设备 | 1,000 台同时在线，可水平扩展至 10,000+ |
| 数据安全 | HMAC 令牌、PBKDF2 密码 | TLS、KMS、密钥轮换、字段加密、最小权限 |
| 可观测性 | 健康接口、审计记录 | 指标、日志、追踪、SLO 和分级告警 |
| 数据恢复 | 可复制 JSON 数据文件 | PostgreSQL PITR；RPO≤15min，RTO≤60min |
7. 明确边界
- MVP 不直接模拟真实微信
code2Session、MQTT Broker、短信通知和支付。 - JSON 文件仅用于单机需求验证，不用于多实例或生产数据。
- 首期不承诺通用低代码平台、跨企业数据共享、任意脚本运行和全协议一次性交付。
- 生产前必须完成企业租户隔离、密钥托管、真实设备 ACK、幂等、限流、备份恢复和安全测试。
8. 当前可运行交付
实现位于 物联网项目文档/iot-platform-mvp。执行 npm test 验证 API、角色边界、设备上报、绑定控制和三端静态完整性；执行 npm start 后访问 /admin/ 使用管理后台。小程序工程位于 mini-program，可直接导入微信开发者工具。