Integration Guide

事实复制章节链接

先写清一份观测声称的事实是什么。事实有三种：一次事件，例如消息被编辑；某一刻读到的状态，例如当前的文件内容；一段持续的事实，例如应用处于前台。

然后定粒度：什么时候延续同一份观测，什么时候形成新的观测。用业务例子检验，一次读取多半是在补全已有的观测，见 IDENTITY-4。

结论写进 Observer 页的开头和实体页的“粒度”。

Observer复制章节链接

确定谁根据证据形成观测、对判断负责。内部模块只提供证据时，负责的是使用它的 Observer；模块独立形成观测时，它是自己的 Observer；只转发已有的观测时，Observer 保持原样。完整的划分见 OBSERVER-6。

再说明程序实例的身份怎样保存、重启后怎样沿用，以及什么情况算独立的实例。结论写进 Observer 页的“程序实例”。

实体复制章节链接

列出需要独立身份的业务对象、观测内容和关系实体，说明每个实体是否作为观测内容，以及它引用谁。

例如同一封邮件被两个 Observer 读到：邮件保持一个身份，两份 Observation 各自引用它。正文从 A 改成 B 时，形成邮件的新版本，A 留在旧版本中，见 HISTORY-3。

关系需要自己的身份、时间或属性时，定义为关系实体，见 ENTITY-9。指向另一个实体时用 reference 字段；写在普通字符串里的标识只是属性。

EntitySchema复制章节链接

为每种业务类型写一个 EntitySchema。每个字段写明 type、required 和 nullable；对象声明成员，数组声明元素；引用可以出现在任何层级，名字以 VersionId 结尾，见 SCHEMA-8。外部系统的标识保存为普通属性。完整的规则见 EntitySchema · 字段约束。

为业务类型选择稳定的 SchemaId 和唯一的资源名。结构或约束变化时，形成同一 EntitySchema 的新版本；业务含义变化时，新建一个 EntitySchema，见 SCHEMA-15 和 SCHEMA-16。

一种业务类型的含义、粒度、身份、时间、EntitySchema 和示例，集中写在同一个实体页。

身份复制章节链接

说明来源标识在哪个范围内有效，例如一个账号、一台设备、一个仓库或一个日历，以及来源标识到 EntityId 的映射保存在哪里。范围不同的同名标识属于不同的实体，见 IDENTITY-7。

来源没有稳定标识时，写明能用哪些证据识别、怎样识别。证据不足的字段保持未知。

最后区分三种情况：重试或重放沿用原来的 VersionId；补全同一件事实，形成原实体的新版本；新的独立观测使用新的 EntityId。两份内容相同，只说明内容相同；是不是同一次发生，要靠证据判断，见 IDENTITY-3。

时间复制章节链接

说明事实时间取自哪些来源字段，时间点、时段和未知边界各怎样表示，见 Observation · 事实时间。未知的时间保持 null，见 TIME-1。

只有读取时刻可用时，先确认业务表达的是“这一刻读到的状态”，再用读取时刻作为事实时间，见 TIME-3。来源只有本地日期、不带时区的本地时间或相对计数时，在观测内容中保留原值，取得可靠的换算依据后再填写边界，见 TIME-5。来源的精度高于微秒，或者边界有特殊含义时，同样保留原值，并说明怎样换算。

暂停、取消和抑制这类状态用业务字段表达。最后写明“进行中”的证据和结束条件：endAt 有值只说明有一个已知边界，事实是否结束按 TIME-4 判断。

历史复制章节链接

确定业务要保留什么：原始材料、当前状态，还是每一次变化。原始材料的保存方式写进 EntitySchema，见 HISTORY-4。

当前状态通过同一实体的新版本更新，旧版本自动保留。例如本机应用保持一个身份，不同时段的观测各自引用当时读到的那一版，见 ENTITY-4。

每个版本保存完整内容：新版本中省略的字段，在这一版中就不存在，见 VERSION-1 和 SCHEMA-13。

提交复制章节链接

接入时，把程序实例的身份和所需的 EntitySchema 交给所在运行环境的 SDK，第一份观测形成前就提交。按业务类型选择及时提交或结束后提交，并说明业务代码何时通知更新、何时通知结束。

在 Observer 页写明用的是哪个 SDK、哪种策略，并链接 Submission。SDK 负责本地保存、发送、确认和恢复；事实判断、身份和历史保留由 Observer 的业务代码负责。

读回复制章节链接

提交实体页的示例，再用 GET /versions/{versionId} 逐个读回（API · 接口），检查保存和读取是否一致：

• 业务版本的 schemaVersionId 指向它所用的 Schema 版本。观测内容的类型由内容版本自己的 schemaVersionId 给出。
• 每个版本都带有后端赋值的 recordedAt，提交时不带它。
• 省略的字段和值为 null 的字段，读回后仍能区分。
• 引用的目标在提交前已保存，见 ENTITY-6。