通用物联网平台提纲

以下是一份可直接作为 AI 提示词使用的通用物联网平台提纲。

定位是“简单但完整”：核心服务二选一，推荐 Node.js + Express（TypeScript），备选 Python + FastAPI；保留涂鸦平台/米家平台的核心逻辑（产品定义驱动接入、规则引擎打通数据与动作、多租户隔离），把静态文件管理系统 + 默认公共组件 + 厂家自定义单页 HTML作为应用层的一等公民；平台可作为通用物联网平台基座，驱动多行业（如智慧水产）的业务过程数据化，行业应用所需能力由通用平台统一提供。

总体架构：五层 + 一个静态文件子系统

设备 / 网关
    │  MQTT（一机一密，可选 HTTP/TCP）
    ▼
接入层    EMQX Broker（HTTP 认证回调 + 共享订阅消费 + HTTP Hook）
    │  共享订阅 / HTTP Hook
    ▼
核心层    Node.js+Express / FastAPI 应用（二选一，推荐 Node.js+Express）
          （物模型解析 · 设备生命周期 · 规则引擎 · 静态文件系统）
    │
    ├── 数据层    PostgreSQL（元数据）+ Redis（最新状态）+ TimescaleDB/MySQL 分区（历史）
    │
    ├── 静态文件子系统   默认组件库 · 厂家自定义 HTML · 租户隔离存储
    │
    ▼
应用层    多租户（厂家 + 一级租户 + 用户）/ 权限 / 产品管理 / 设备管理 / 可视化 / 日志审计

关键设计原则：配置与数据分离——产品定义、物模型、规则、权限存关系库；设备上报的属性值走时序或缓存，二者通过 product_key / device_id 关联，不混在一张表里。所有业务数据强制带 tenant_id 过滤，保证多租户隔离。

一、数据库设计（元数据与数据分离）

关系库用 PostgreSQL（JSONB 字段对动态物模型非常友好），起步可不引入额外时序库，用 Redis 存最新状态 + PostgreSQL 按月分区存短周期历史；数据量大时再引入 TimescaleDB / MySQL 分区 / Elasticsearch 做历史存储与时序检索。

核心表（最小集）设计如下，按“元数据与数据分离”组织：

设计说明： - 产品分组只做一级扁平：product_group 无 parent_id，不得建产品分类树；device_group 仍可保留 parent_id 用于空间/业务层级。 - 物模型整体以 JSONB 存储三要素（属性/服务/事件），前端定义完成后无需代码生成，由平台运行时直接解释校验，实现动态生效； - 设备上报的属性值单独走 device_state（最新状态）+ property_history（历史），与物模型定义（元数据）分表存储，通过 product_key / device_id 关联，不混在一张表里，保证性能与隔离； - 所有业务查询强制带 tenant_id 过滤，这是租户隔离的第一道防线；规则执行、设备查询、属性历史查询均不得出现跨租户 JOIN。

二、登录与权限（多租户 RBAC）

认证方式：采用 JWT 无状态令牌。普通用户走登录换取 JWT；开放 API 走 AccessKey；设备端走 MQTT 一机一密，三类凭据不混用同一套体系。账号层级遵循“用户 → 租户/家庭 → 设备”的归属关系。

权限模型：租户内 RBAC。角色至少分三级——平台管理员（跨租户管理）、租户管理员（管理本租户）、租户普通成员（使用本租户产品与设备）。权限粒度落到具体操作上，包括“产品创建 / 物模型编辑 / 设备绑定 / 设备分享 / 规则配置 / UI 模板上传”等，用 Casbin 或自研依赖注入做路由级检查。

数据隔离硬规则：Repository 层统一注入 tenant_id 条件；设备查询、属性历史查询、规则执行时均不得出现跨租户 JOIN。

三、MQTT 接入层（EMQX + 一机一密，协议可扩展）

Broker 选 EMQX 开源版，平台侧不实现 MQTT 协议栈，只做“认证回调 + 数据消费”。

认证机制：开启 EMQX 的 HTTP 认证。设备连接时携带 clientId / username / password，EMQX 回调平台 /internal/mqtt/auth 接口，平台用 product_key + device_name + device_secret 校验，返回 allow/deny。设备凭据在创建时生成，device_secret 只存哈希值，不落明文。

Topic 设计（上下行分离，便于规则引擎按租户分发）：

上行：/tenant/{tenant_id}/device/{device_id}/property/post
上行：/tenant/{tenant_id}/device/{device_id}/event/post
下行：/tenant/{tenant_id}/device/{device_id}/service/{identifier}/set

数据消费：平台侧用 MQTT 共享订阅（$share/platform/tenant/+/device/+/property/post）消费上行消息，多个 FastAPI worker 之间自动负载均衡，避免单点消费瓶颈。消费到消息后交给物模型解析器做校验和落库。设备上下线通过 EMQX HTTP Hook/Webhook 通知平台，更新设备状态与 last_seen。

协议扩展：MQTT 为必选接入；起步阶段可选 HTTP 直连上报，后续按需扩展 TCP/UDP/CoAP 接入与 Modbus/JT808/GB/T28181 等工业协议——参考开源物平台的协议包机制，私有协议封装为协议包热加载，不改主流程。

传输加密：生产环境启用 TLS（EMQX 8883 端口），平台侧做证书管理；设备端凭据全程不明文落库。

一型一密（动态注册）：除一机一密外，支持同型号设备预烧相同 product_secret，设备首连时调用平台动态注册接口换取一机一密凭据，便于批量量产，不必逐台预写密钥。

网关与子设备：子设备（如 RS485/Zigbee 传感器）经网关代理接入——网关维护子设备拓扑（添加/删除子设备、代理上报子设备上下线），子设备消息沿用统一 Topic 结构并复用物模型校验与规则引擎，无需单独接入链路。

四、物模型层（动态定义的核心抽象）

物模型保留标准三要素，存储形态为 JSONB，前端定义完成后无需“代码生成”，由核心服务（Node.js+Express 或 FastAPI）在运行时解释执行。

属性（Property）：定义字段包括 identifier、name、data_type（int / float / bool / enum / string）、access（r / rw / report_only）、unit、min/max 等。设备上报 JSON 时，物模型解析器逐字段校验类型与范围，通过后写最新状态和历史。

服务（Service）：定义 identifier、name、input_params、output_params。平台调用服务时，将参数打包下发到下行 Topic，并可选等待设备响应。

事件（Event）：定义 identifier、name、output_params（如故障码）。设备主动上报，平台校验后写入设备日志并交给规则引擎匹配。

动态生效的关键：物模型本身是数据，不是代码。设备上报 → 查 thing_model JSONB → 按定义校验 → 通过则落库。产品发布后物模型变更要走版本管理，避免已绑定设备上报格式与定义不一致。

五、设备管理（设备全生命周期）

• 注册与绑定：产品发布后，用户填入 device_name 获取 device_secret，设备一机一密接入；支持单个创建与批量导入；
• 生命周期状态：未激活 / 在线 / 离线 / 禁用，上下线事件由 EMQX Hook 通知平台更新 device.status 与 last_seen，支持禁用与删除；
• 设备影子（Shadow）：平台侧缓存设备最新属性值（device_state / Redis），设备离线时指令先落到影子，设备上线后同步下发，支撑离线控制；
• 实时状态与实时控制：查看设备当前属性值，直接下发服务调用控制设备，双向通信；
• 数据监测：按物模型属性查看实时曲线与历史数据（property_history）；
• 设备分组：按空间/业务维度分组管理（如鱼塘/车间/大棚），支持组级批量控制与按组下发；
• 网关与子设备：管理网关及其子设备拓扑，子设备经网关代理上下线与数据上报，拓扑关系可查；
• 设备定位：记录设备经纬度（longitude / latitude），支撑地图分布查看（可选）；
• 设备分享：租户内或跨用户授权访问设备（只读/可控），授权关系存 device_share，访问时校验；
• 设备日志：上下线、属性上报、服务下发、事件上报全记录，支撑问题追溯；
• 在线调试：提供模拟上报/下发工具，用户无需真实设备即可验证物模型定义是否正确。

六、产品管理（产品定义驱动接入）

产品结构：一级扁平，禁止分类树/父子分组。 产品少时直接用 product_a / product_b；product_group 只做组号/名称，仅用于检索归类。

• 产品创建与发布：创建产品 → 选模板或自定义 → 可视化编辑器添加属性/服务/事件（物模型）→ 发布产品 → 生成 product_key；产品是设备的配置模板，承载物模型；
• 产品分组：租户下一级扁平分组（product_group，组号/名称，无 parent_id、无树），仅用于检索与归类；
• 产品固件与 OTA（可选扩展）：固件上传、版本管理，按设备/分组批量升级；
• 设备授权：device_secret 的生成与重置，凭据只存哈希，支持授权码下发与作废；
• 物模型版本管理：产品发布后物模型变更走版本管理，保证已绑设备上报格式与定义一致。

七、规则引擎（条件 → 动作，自研轻量）

不引入 Flink 或复杂流处理。规则以结构化 JSON 存库，物模型数据流入时在应用进程内（Express/FastAPI）做内存匹配。

触发条件支持三类：

• 属性触发：device.property.identifier operator threshold（如 temperature > 30）；
• 事件触发：指定 event.identifier 出现即触发；
• 定时触发：cron 表达式，由 APScheduler 或独立调度器触发。

执行动作支持三类：

• 下发服务：向目标设备发布下行 Topic，调用物模型定义的 service；
• 通知：站内信 / Webhook / 短信 / 邮件（渠道可配置）；
• 置位虚拟属性：在平台侧直接更新某设备的某个属性状态，不依赖真实设备；
• 数据转发：把设备数据推送给第三方系统——HTTP 推送 / Kafka / MQTT 转发 / 数据库直写，作为独立"数据目的"配置，支撑数据开放与外部系统集成。

告警中心：规则触发生成告警记录（含级别：提示/警告/严重、触发设备、触发值、时间），支持告警确认/处理/恢复闭环，告警记录可查、可导出；通知渠道作为告警动作触发，避免"规则跑了但无告警痕迹"。

场景联动：多条"触发条件 → 执行动作"可编排为场景（支持串行/并行动作），规则通过界面配置即时生效、无需发版——参考开源物平台 LiteFlow 编排思路，本框架用内存匹配实现同等语义。

执行保障：规则先写入 rule 表；数据流入时按 product_key + identifier 索引快速匹配，匹配成功则异步执行动作并记入执行日志，规则执行失败不阻塞数据落库。

八、应用层：静态文件显示系统（默认组件 + 自定义 HTML）

这是让平台“像涂鸦/米家”的关键模块。

设计目标：每个产品在“设备详情/控制页”上有一套显示模板。平台先保证默认公共组件让任何合法物模型都能正常显示数据；厂家（或高级用户）可以上传自定义单页 HTML 来替换默认显示，实现更专业、更形象的交互。

两级模板策略：

存储结构建议：

static/
└── ui/
    └── {tenant_id}/
        └── {product_key}/
            ├── current/          # 当前生效版本
            │   ├── index.html
            │   └── assets/
            └── versions/
                └── {timestamp}/  # 历史版本，支持回滚

安全与隔离：自定义 HTML 上传必须做文件类型白名单（仅 .html / .css / .js / 图片），禁止 .git、.env 等敏感文件。上传目录独立于应用代码目录，生产中由 Nginx 直接服务静态文件，FastAPI 只负责上传和元数据管理。自定义 HTML 在 <iframe sandbox> 或受限环境中加载，避免其窃取其他租户的 JWT 或直接调用管理 API。平台向自定义页面暴露的能力通过 postMessage 桥接 或短期设备 token 控制，不直接赋予平台内部 API 权限。

默认公共组件的回退逻辑：设备详情页优先查找 product_ui.template_type = custom 且状态有效的模板；若不存在或加载失败，回退到默认组件按物模型生成显示。这样厂家不上传 HTML 时平台依然完整可用，上传后则获得更专业的呈现。

九、日志、可视化与监控

日志分两类：

• 操作日志：谁在什么时候修改了物模型、规则、UI 模板、权限，写 audit_log，供租户管理员和平台管理员审计；
• 设备日志：上下线、属性上报、服务下发、事件上报。量小存 PostgreSQL 分区表，量大再迁 TimescaleDB 或 Elasticsearch。

可视化分三级：

• 设备详情/控制页：由静态文件系统提供（默认公共组件 + 自定义 HTML，见第八章）；
• 轻量看板：用户选择产品 → 选择物模型属性 → 拖拽生成折线图 / 仪表盘 / 开关卡片。看板配置存 JSON，前端按配置渲染。公共组件与看板组件共享同一套“属性 → 组件”映射逻辑，确保默认显示和自定义看板的数据通路一致；
• 数据大屏/组态（可选扩展）：拖拽组件生成行业监控大屏（如水产养殖监控大屏），配置存 JSON 渲染；配套报表管理与系统运行监控（连接数、消息吞吐、worker 负载）。

十、行业应用与通用能力（参考行业设计指南）

本框架定位为通用物联网平台基座，不局限于单一行业，可驱动多行业将业务过程数据化。以智慧水产为典型场景：通过数据赋能水产行业，设计数据集、功能点与行业标准，实现行业全流程数据化，降低行业成本、提升人均效率与人均产出。

通用物联网平台基本能力（基座必备）：

• 动态物模型定义产品：无需为每个行业写死代码，通过物模型灵活定义产品能力；
• 物模型属性联动：所有物模型的属性之间均能相互联动，支撑衍生业务逻辑；
• 统一规则引擎：用统一的“条件 → 动作”规则打通数据与动作，让平台数据灵活适应具体行业应用，解决具体间题；
• 登录与账号体系：提供必备的登录与账号能力，支撑用户与权限管理；
• 通信接入层：提供设备/网关稳定接入，保障数据进出安全与可靠；
• 存储性能优化：元数据、时序数据、最新状态分层存储，适配海量设备数据访问；
• 第三方接口开放：提供开放 API（AccessKey 鉴权）与数据转发（HTTP 推送 / Kafka / MQTT 转发），便于第三方应用接入平台能力与数据。

行业应用价值（以智慧水产为例）：

• 用数据赋能水产行业全流程：设计数据集、功能点、定行业标准，实现业务过程全数据化；
• 行业基座本质为通用物联网平台驱动，本框架的物模型、规则引擎、接入层可直接作为行业应用底座，把行业需求转化为可落地的平台能力；
• 通过平台实现行业成本降低、人均效率与人均产出提升。

参考：智慧水产解决方案网站（虾/鱼/蟹等多品类养殖方案与知识库）、鱼塘智能化平台、开源物模型物联网平台（如 FastBee），可复用其行业功能、数据与能力设计。

十一、技术选型与存储架构参考（参考开源物平台实现）

本框架核心为轻量实现，可在此基础上按扩展需求选择技术栈与存储架构。参考开源物平台（如 FastBee）实现，形成以下参考与对照。

11.1 技术选型参考（轻量起步 + 按需扩展）

后端语言二选一：Node.js + Express（TypeScript，推荐） 或 Python + FastAPI（备选）。推荐 Express 的原因：单人/小团队上手快、前后端同栈、现有 Node 基础、I/O 与 WebSocket 够用；FastAPI 适合 Python 团队、AI/数据分析或物模型 Schema 极复杂的场景。同一项目只选一套，本文其余部分与语言无关。

集群扩展：单机起步即可闭环；设备规模增长后可参考集群版思路（消息队列 + 分布式 Broker + 多 worker），支撑海量设备接入。

11.2 存储架构参考（多库分工）

参考开源物平台的多库分层，匹配不同数据访问模式，可在轻量单库基础上扩展为多库：

本框架轻量阶段可先用单库（PostgreSQL JSONB + Redis），数据量增长后按上述分层扩展，不改变现有“配置与数据分离”的核心设计。

11.3 物模型设计路线对照

结论：本框架保留 JSONB 文档物模型路线，侧重跨厂家联动、语义防漂移、免代码生成、免运维；开源物平台的表驱动物模型、多库分工与若依权限体系可作为扩展参考，两者物模型语义一致，可按需搭配或二选一。

十二、基本物联网平台标准速览清单

十三、最小闭环与 AI 提示词分块建议

先跑通这个闭环，再扩展：

用户创建“开关”产品 → 定义 switch 布尔属性（读写）→ MQTT 模拟设备用一机一密连接并上报 {"switch": true} → 平台校验落库，默认公共组件显示为“开” → 厂家上传一个自定义 HTML 显示页 → 设备详情页切换为自定义显示 → 配一条规则“switch 变为 true 时发送站内信通知” → 通知触达，操作日志和设备日志可查。

建议在向 AI 投喂时把提示词拆成以下块，每块独立可迭代：

1. 数据模型块：给出核心表 DDL 和 thing_model JSON 示例，让 AI 生成 SQLAlchemy 模型和 Pydantic schema；
2. MQTT 接入块：描述 EMQX HTTP 认证回调 + HTTP Hook + 共享订阅消费逻辑，让 AI 生成 /internal/mqtt/auth 和共享订阅消费者代码；
3. 物模型解析块：给出属性/服务/事件的 JSON 结构，让 AI 生成校验器和落库管道；
4. 设备与产品管理块：描述产品发布流程、设备注册/影子/分组/分享/日志，让 AI 生成设备生命周期与产品管理 API；
5. 规则引擎块：给出 trigger/action 的 JSON schema，让 AI 生成内存匹配器和动作执行器；
6. 静态文件系统块：描述租户隔离目录、上传白名单、默认组件映射表、自定义 HTML 的 postMessage 桥接约定，让 AI 生成上传 API、静态文件挂载和前端回退逻辑；
7. 最小可运行工程块：明确 Node.js+Express 或 FastAPI 目录结构（Express：modules / common / mqtt / thing-model / rule-engine / static-ui / workers；FastAPI：routers / services / repositories / mqtt / thing_model / rule_engine / static_ui），让 AI 按层生成。

一句话总结：设备走 MQTT 一机一密进来，物模型定义“设备是什么”，规则引擎在数据流入时判断“该做什么”，静态文件系统决定“用户看到什么”——默认组件保证完整可用，自定义 HTML 让厂家做专业呈现，多租户从数据库到静态目录全程隔离，框架作为通用物联网平台基座驱动多行业应用。