Entity、EntityState 与 Integration Key：深入理解 Home Information 数据模型的 3 个核心概念

Home Information 是一款自托管的智能家居信息管理平台，能把家里的设备、物品资料、传感器状态统一组织在一张可视化的"家庭地图"上。支撑这些功能的，是它精心设计的数据模型——而模型的核心只有 3 个概念：Entity（实体）、**EntityState（实体状态）**和Integration Key（集成键）。本文用通俗的语言带你一次看懂这 3 个概念，理解后你就能轻松读懂 Home Information 的物品管理、状态监控与外部系统对接。

一图看懂整体架构

Home Information 的数据模型刻意分成两层：核心模型描述"东西是什么、如何工作"（实体、状态、传感器、控制器），显示模型描述"东西在哪里、如何呈现"（位置、视图、坐标）。这种分离让同一台冰箱既能出现在厨房平面图上，也能被放进"电器"合集，而数据始终只有一个来源。

概念一：Entity，每件物品的"统一身份证"

Entity 是整个数据模型的基础构建块，代表家里任何物理或逻辑对象：冰箱、门锁、摄像头、空调，甚至是一个"后院区域"。

一个 Entity 最重要的 3 个特征：

Entity 有两种来源：手动在编辑模式下添加，或由集成（Integration）从外部系统同步创建。在物品信息面板里，你可以随时修改名称、类型并追加属性：

对应的模型定义在 src/hi/apps/entity/models.py，可以看到 Entity 同时混入了IntegrationDetailsModel（用于记录外部系统来源）和位置模型（用于在平面图上定位）。

概念二：EntityState，可感知可控制的"隐藏状态"

如果 Entity 是"东西本身"，那么 EntityState 就是这个东西内部可以变化、可以观察、可以控制的状态——比如灯的"开/关"、恒温器的"温度"、门窗的"开/关"。

之所以叫"隐藏"状态，是因为用户界面并不直接展示这个内部概念，用户看到的是传感器汇报的实时值和状态面板。一个 EntityState 由 3 部分共同驱动：

• 状态类型（EntityStateType）：定义值怎么存储和解释，例如 ON_OFF、TEMPERATURE、DISCRETE（离散值）；
• 值范围（value_range）：约束取值空间，比如调光灯的 min/max 亮度范围、风扇的档位列表；
• Sensor 与 Controller：Sensor 负责观察并汇报状态值（每个传感器只报告一个状态），Controller 负责改变状态值（如开关控制器）。

模型定义见 src/hi/apps/entity/models.py，完整的实体关系（Entity → EntityState → Sensor/Controller 的一对多关系）在官方文档中有 Mermaid 图示：docs/dev/shared/diagrams/core-model-diagram.md。

一个实用的细节：同一个实体可以有多个同类型状态，系统用Role（角色）来区分，比如恒温器的"当前温度"和"目标温度"都是 TEMPERATURE 类型，但角色不同，界面上因此能分开显示。

概念三：Integration Key，外部系统对接的"唯一护照"

当你把 Home Assistant、Frigate、ZoneMinder 等外部系统接入 Home Information 时，系统需要回答一个关键问题：外部系统的某个设备，对应我这里的哪个 Entity？

答案就是 Integration Key。它由两部分组成（定义在 src/hi/integrations/transient_models.py）：

• integration_id：集成类型标识，例如 HA 集成；
• integration_name：外部系统中该条目的唯一名称（在 Home Assistant 中就是 entity 的 id，如light.living_room）。

两者组合成全局唯一的键，并会被统一规范化为小写，避免大小写差异导致匹配失败。在集成连接界面填入服务地址和 API Token 后，每次同步都会依据这个键进行匹配：

Integration Key 在 3 个场景中发挥关键作用：

1. 去重：数据库对 Entity 的integration_id + integration_name设置了唯一约束（见 src/hi/apps/entity/models.py），同一外部设备无论同步多少次，都只会对应一个 Entity；
2. 断线重连：如果外部设备暂时消失又恢复，系统通过previous_integration_key字段把实体"重新接回"，而不是创建一个重复项；
3. 状态拆解：一个外部状态可以拆成多个 EntityState，子状态通过键名后缀区分（如light.x~hue、light.x~saturation），规则详见 docs/dev/integrations/integration-guidelines.md。

三个概念如何协作：一盏智能灯的旅程

把 3 个概念串起来，看一盏 Home Assistant 智能灯接入 Home Information 的过程：

1. Entity：同步创建名为 "Living Room Light" 的实体，类型 Light，获得图标和位置；
2. EntityState：同一实体下生成 on/off、亮度等隐藏状态，各自声明值范围与单位；
3. Integration Key：hass.light.living_room这样的键保证下次同步时精确对上，不产生重复。

之后，灯的状态由 Sensor 持续观察、由 Controller 远程控制，而用户只需要在界面上看到"客厅灯已开启"——背后的数据模型默默完成了所有关联。

延伸阅读

想进一步深入 Home Information 数据模型，推荐按以下顺序阅读官方文档：

• 数据模型总览：docs/dev/shared/data-model.md
• 核心模型关系图：docs/dev/shared/diagrams/core-model.plantuml
• 实体使用模式：docs/dev/domain/entity-patterns.md
• 集成开发规范（Integration Key 约定）：docs/dev/integrations/integration-guidelines.md

掌握 Entity、EntityState 与 Integration Key 这 3 个概念，你就拿到了理解 Home Information 全部功能的关键钥匙 🔑——无论是排查同步问题，还是理解状态面板为何变色，都能从这 3 个概念的协作中找到答案。