Entity 先给数据办护照，Backend 再给它分酒店房间。
1. 动机
应用需要一份持久描述，说明每行数据代表什么。 HeavenBase Entity 让这份逻辑契约独立于物理存储，因此同一个 schema 可以路由到不同 Backend。2. 定义逻辑形状
继承hb.Entity 并声明类型化字段。
当字段需要元数据、默认值、放置规则或计算 Hook 时，请使用 hb.field(...)。
document，并在缺失时注入必需的 object_id 字段。
schema() 返回已编译的 EntitySchema；to_dict() 与 to_str() 分别提供兼容 JSON 和 Agent 可读的视图。
3. 选择逻辑类型
逻辑类型描述含义。 Backend 决定物理表示。
时刻请使用
Timestamp，日历日期请使用 Date。
HeavenBase 尚未公开独立的 Datetime 或 Interval 逻辑类型。
4. 保持身份
每个 Entity 行都有一个面向用户的object_id。
若省略它，HeavenBase 会根据行的 name 推导确定性 id。
object_id。
计算 Hook 可以根据其他字段推导这个键。
5. 添加计算 Hook
写入时计算 Hook 会推导存储值。 查询计算 Hook 会在路由前规范化查询值，例如把文本转换成向量。6. 从 JSON 构建
Agent 与外部客户端可以从兼容 JSON 的映射创建同一份逻辑 schema。hb.Entity 子类行为一致。
同一份定义也可以随工作区清单一起移动。
总结
- Entity 定义逻辑含义与稳定身份。
- 字段携带类型、元数据、默认值、放置规则与计算 Hook。
- 物理存储仍是路由问题。
- Python 与 JSON 定义会编译成同一份 schema 契约。