OrisumiGlossary
Core 术语的定义
Core 类型、Observer 和各种 Id 用英文名，其余概念用中文。Observation 的中文名是“观测”。写作时用哪个词，见 Conventions · 用词。
实体与版本
| 术语 | 定义 | 详见 |
|---|---|---|
| 实体（Entity） | 有稳定身份的一项数据，例如一个人、一个本机应用或一份推断。所有数据都是实体 | Entity |
| EntityId | 实体的身份，UUIDv7 | ENTITY-1 |
| 版本（Version） | 实体一次保存的完整内容，保存后不可改写 | Version |
| VersionId | 版本的身份，写入方生成的 UUIDv7，重试时沿用 | VERSION-12 |
| 版本链 | 一个实体的全部版本，每个版本指向前一版本 | VERSION-4 |
| 当前版本 | 实体最新保存的版本 | VERSION-5 |
| 已保存 | 版本已被后端保存，可以被引用 | ENTITY-6 |
| 提交 | 写入方把一个或多个版本交给后端保存的一次请求 | VERSION-13 |
| 引用 | 保存目标 VersionId 的位置，由 Core 或 Schema 版本声明 | ENTITY-4 |
| 引用方 | 保存引用的版本，以及它所属的实体 | ENTITY-8 |
| 关系实体 | 表达一种关系的业务实体，用于关系需要身份、时间或属性的情况 | ENTITY-9 |
类型
| 术语 | 定义 | 详见 |
|---|---|---|
| Core 类型 | Observation、EntitySchema 和 InputSet，结构由 Core 定义 | Core · Overview |
| 业务实体 | 类型由 EntitySchema 定义的实体 | EntitySchema |
| 业务版本 | 业务实体的一个版本，引用它所用的 Schema 版本 | VERSION-3 |
| 业务类型 | 一种业务数据，由一个 EntitySchema 定义 | SCHEMA-1 |
| EntitySchema | 定义业务类型的 Core 类型；它的每个版本是一版字段、约束和含义 | EntitySchema |
| SchemaId | EntitySchema 的 EntityId，也就是业务类型的身份 | SCHEMA-1 |
| Schema 版本 | EntitySchema 的一个版本，业务版本用 schemaVersionId 引用它 | SCHEMA-2 |
| 资源名 | EntitySchema 的 resourceName，同一业务类型的各 Schema 版本相同 | SCHEMA-5 |
| 业务规则 | 一种业务类型怎样记下事实：身份、粒度、事实时间、结束条件、原始材料，以及陈述冲突时以谁为准。写在 Observer 文档和 EntitySchema 的 description 中 | Overview · 谁决定什么 |
| Observation（观测） | Observer 形成的一份陈述，唯一保存事实时间的类型 | Observation |
| InputSet（输入集） | 一次处理实际用到的版本集合，可以被多份观测共用 | InputSet |
角色
| 术语 | 定义 | 详见 |
|---|---|---|
| Observer | 对一份观测负责的业务实体，被 observerVersionId 引用 | OBSERVER-1 |
| 观测内容 | 被 contentVersionId 引用的业务实体 | OBSERVATION-1 |
| 输入 | InputSet 的成员，一次处理用到的版本 | InputSet |
陈述与处理
| 术语 | 定义 | 详见 |
|---|---|---|
| 陈述 | Observation 表达的内容，由观测内容和事实时间组成 | OBSERVER-1 |
| 处理 | 读取已保存的版本、形成观测的一次过程，例如一次模型调用。一次处理可以形成多份 Observation | EVIDENCE-1 |
| 采集诊断 | 读取、解析或匹配失败的情况，作为诊断信息处理 | OBSERVER-8 |
参与方
| 术语 | 定义 | 详见 |
|---|---|---|
| 用户 | 拥有数据的人。在模型中是业务实体，可以作为 Observer | OBSERVER-6 |
| 程序实例 | 独立运行、有自己 EntityId 的程序，例如前台状态 Observer 或推断 Observer | OBSERVER-5 |
| SDK | 程序实例使用的提交组件，负责持久保存实例身份、本地保存，以及按依赖顺序发送 | Overview · 谁决定什么 |
| 写入方 | 向后端提交版本的软件：Observer 的业务代码、SDK 和用户使用的工具 | Conventions · 规则的格式 |
| 读取方 | 读取和追溯数据的软件，例如 Agent 和 Web 控制台 | Conventions · 规则的格式 |
| 后端 | 校验并保存版本的服务 | Overview · 谁决定什么 |
时间
| 术语 | 定义 | 详见 |
|---|---|---|
| 事实时间 | 事件发生或状态成立的时间，保存在 Observation 的 startAt 和 endAt 中 | Observation · 事实时间 |
| 时间点 | startAt 等于 endAt 的事实时间 | OBSERVATION-7 |
| 时段 | startAt 早于 endAt 的事实时间，左闭右开 | OBSERVATION-8 |
| 进行中 | 证据表明事实仍在持续 | TIME-4 |
| 保存时间 | 后端首次保存一个版本的时刻，即 recordedAt | VERSION-10 |
变化与历史
| 术语 | 定义 | 详见 |
|---|---|---|
| 更新 | 形成同一实体的新版本 | HISTORY-1 |
| 补全 | 随证据积累更新同一事实，例如延长时段 | HISTORY-2 |
| 纠正 | 用新版本修正错误的值 | HISTORY-2 |
| 删除 | 移除选中实体的全部版本，之后不再接受它的新版本 | HISTORY-6 |
| 原始材料 | 来源提供、尚未按业务规则解释的数据 | HISTORY-4 |
不再使用的术语
实现中用过、已从模型中删除的术语。pnpm docs:check 会报告文档中出现的这些词。从模型中删除这样的概念时，在这里加一行。
