From e9a512919ba62c8918f1e4d4398c00018b330aea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=A2=A8?= Date: Sun, 12 Apr 2026 12:41:29 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=96=B0=E5=A2=9E=20OGraph=20=E5=AF=B9?= =?UTF-8?q?=E8=B1=A1=E6=A8=A1=E5=9E=8B=E4=B8=8E=20API=20Protocol=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 完整覆盖 OGraph v2.4+ 三层架构 - Definition Layer: Object/Event/Projection 定义 - Instance Layer: 实例创建与事件发射 - Reaction Layer: 响应机制与触发链路 - 包含完整的表结构、API 速查表、Bindings/Expression 详解 - 为小墨和小橘之间的系统对接提供技术规范参考 --- docs/shared/ograph-object-model.md | 335 +++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 336 insertions(+) create mode 100644 docs/shared/ograph-object-model.md diff --git a/docs/shared/ograph-object-model.md b/docs/shared/ograph-object-model.md new file mode 100644 index 0000000..dbbb429 --- /dev/null +++ b/docs/shared/ograph-object-model.md @@ -0,0 +1,335 @@ +# OGraph 对象模型与 API Protocol + +> OGraph v2.4+ 系统架构与 API 接口规范文档 + +## 概述 + +OGraph v2.4+ 采用三层架构设计： + +``` +Definition Layer (定义层) + ↓ +Instance Layer (实例层) + ↓ +Reaction Layer (响应层) +``` + +### 核心原则 + +- **事实不可变，解读可进化** — 原始事件永不修改，Projection 可以升级 +- **名字是指针，hash 是锚点** — 名字在 API 入口解析，系统内部全用 content hash + +## Definition Layer（定义层） + +### 2.1 Object Def + +最简单的定义，纯名字标识，无版本控制。 + +**数据表：** +```sql +object_defs ( + name TEXT PRIMARY KEY +) +``` + +**API：** +- `POST /object-defs { name }` — 注册 Object 类型 +- `GET /object-defs` — 列出所有 Object 类型 + +### 2.2 Event Def（版本链） + +定义事件的 schema 结构，支持版本演进。 + +**PropertyDef 类型：** +- `ref` — 引用 Object，可带 `object_type` 实现多态 +- `string` — 字符串 +- `number` — 数值 +- `boolean` — 布尔值 + +**版本链机制：** +- Content hash 做 ID，确保内容唯一性 +- `parent_hash` 串联形成版本链 +- 名字是可变指针，指向当前版本的 hash + +**数据表：** +```sql +event_def_versions ( + hash TEXT PRIMARY KEY, + name TEXT, + parent_hash TEXT, + schema TEXT, -- JSON + created_at INTEGER +) + +event_def_names ( + name TEXT PRIMARY KEY, + current_hash TEXT -- → event_def_versions.hash +) +``` + +**API：** +- `POST /event-defs { name, schema: { properties: {...} } }` — 注册/更新 Event 类型（upsert） +- `GET /event-defs` — 列出所有 Event 类型 + +**特性：** +- `ref` 类型的属性会自动提取到 `event_refs` 表 +- 名字只在 API 入口解析，进入系统后全走 hash + +### 2.3 Projection Def（版本链 + 多态 Sources） + +定义如何将事件流聚合成状态视图。 + +**核心组件：** +- **params** — 声明投影参数（通常是 ref 类型） +- **sources** — 事件源数组，每个 source 绑定一种 event def hash： + - **bindings** — 结构化查询条件，`$param` 引用 params，裸字符串是字面量 + - **expression** — JSONata reducer，签名 `(state, event, params) → new_state` +- **value_schema** + **initial_value**（NOT NULL） + +**数据表：** +```sql +projection_def_versions ( + hash TEXT PRIMARY KEY, + name TEXT, + parent_hash TEXT, + params TEXT, -- JSON + value_schema TEXT, -- JSON + initial_value TEXT, -- JSON + created_at INTEGER +) + +projection_def_sources ( + projection_hash TEXT, + event_def_hash TEXT, + bindings TEXT, -- JSON + expression TEXT -- JSONata +) + +projection_def_names ( + name TEXT PRIMARY KEY, + current_hash TEXT -- → projection_def_versions.hash +) +``` + +**API：** +- `POST /projection-defs { name, sources: [{ event_def, bindings, expression }], params, value_schema, initial_value }` — 注册/更新 Projection（upsert） +- `GET /projection-defs` — 列出所有 Projection 定义 + +## Instance Layer（实例层） + +### 3.1 Object + +纯标识实体，`id + type + created_at`。 + +**数据表：** +```sql +objects ( + id TEXT PRIMARY KEY, + type TEXT, -- → object_defs.name + created_at INTEGER +) +``` + +**API：** +- `POST /objects { type, id? }` — 创建 Object 实例（id 可自定义或自动生成 OID） +- `GET /objects/:id` — 查询 Object +- `GET /objects?type=` — 按类型列出 Objects + +### 3.2 Event + +不可变事件记录，`id + type_hash + payload + created_at`。 + +**数据表：** +```sql +events ( + id TEXT PRIMARY KEY, + type_hash TEXT, -- → event_def_versions.hash + payload TEXT, -- JSON + created_at INTEGER +) + +event_refs ( + event_id TEXT, + property TEXT, + ref_id TEXT -- → objects.id +) +``` + +**发射流程：** +1. 名字解析为 hash +2. Schema 校验 +3. 写入 `events` + `event_refs` +4. 触发 reaction chain + +**API：** +- `POST /events { type, payload }` — 发射事件 +- `GET /events/:id` — 查询事件 +- `GET /events?ref=` — 按 Object 查相关事件 + +### 3.3 Projection（缓存） + +`(def_hash, params_hash) → value` 的 lazy 增量计算缓存。 + +**数据表：** +```sql +projections ( + def_hash TEXT, + params_hash TEXT, + value TEXT, -- JSON + updated_at INTEGER, + PRIMARY KEY (def_hash, params_hash) +) +``` + +**计算流程：** +1. 查缓存，取 `value` + `updated_at` +2. 对每个 source，用 bindings 查 `updated_at` 之后的增量事件 +3. 所有 source 的增量事件按 `(created_at, id)` 排序 +4. 逐条 dispatch 到对应 source 的 expression +5. 更新缓存 + +无缓存时从 `initial_value` + 全量事件计算。 + +**API：** +- `GET /projections/:name?param1=val1¶m2=val2` — 查询 Projection 值 + +## Reaction Layer（响应层） + +### 4.1 Reaction + +订阅 projection 变化并执行响应动作。 + +**Action 类型：** +- **webhook** — POST 到 `webhook_url`，payload 包含 `old_value`, `new_value`, `params`, `event` +- **emit_event** — 发射新事件到 OGraph（事件衍生/扇出），支持 payload template（JSONata） + +**数据表：** +```sql +reactions ( + id TEXT PRIMARY KEY, + projection_def_hash TEXT, + params_hash TEXT, + action TEXT, -- 'webhook' | 'emit_event' + webhook_url TEXT, + emit_event_type TEXT, + emit_payload_template TEXT, -- JSONata + created_at INTEGER +) +``` + +**触发链路：** +``` +Event 发生 +→ 查 projection_def_sources 找到受影响的 projection +→ 查 reactions +→ 对有 reaction 的执行 bindings 匹配 +→ 重算 projection +→ diff(old, new) +→ 触发 action +``` + +**API：** +- `POST /reactions { projection_def, params, action?, webhook_url?, emit_event_type?, emit_payload_template? }` — 创建 Reaction +- `GET /reactions` — 列出所有 Reactions +- `DELETE /reactions/:id` — 删除 Reaction + +## 表结构总览 + +| 分类 | 表 | 可变性 | +|---|---|---| +| 定义（无版本） | `object_defs` | append-only | +| 定义版本 | `event_def_versions`, `projection_def_versions` | immutable | +| 定义 sources | `projection_def_sources` | immutable（随版本） | +| 名字指针 | `event_def_names`, `projection_def_names` | mutable（UPDATE current_hash） | +| 实例 | `objects`, `events` | append-only | +| 关联 | `event_refs` | append-only | +| 缓存 | `projections` | mutable（缓存刷新） | +| 响应 | `reactions` | CRUD | + +## API 速查表 + +``` +POST /object-defs 注册 Object 类型 +GET /object-defs 列出所有 Object 类型 +POST /objects 创建 Object 实例 +GET /objects/:id 查询 Object +GET /objects?type= 按类型列出 Objects +POST /event-defs 注册/更新 Event 类型（upsert，版本链） +GET /event-defs 列出所有 Event 类型 +POST /events 发射事件 +GET /events/:id 查询事件 +GET /events?ref= 按 Object 查相关事件 +POST /projection-defs 注册/更新 Projection（upsert，版本链） +GET /projection-defs 列出所有 Projection 定义 +GET /projections/:name?params 查询 Projection 值 +POST /reactions 创建 Reaction +GET /reactions 列出所有 Reactions +DELETE /reactions/:id 删除 Reaction +GET /health 健康检查 +GET /ui 管理界面 +``` + +## Bindings 详解 + +**语法规则：** +- `$param` — `$` 开头引用 params 值 +- 裸字符串 — 字面量 + +**SQL 翻译：** +每个 binding 变成 `JOIN event_refs ON property = ? AND ref_id = ?` + +**特殊情况：** +空 bindings = 拉该类型全部事件（reducer 自行过滤） + +## Expression 详解 + +**JSONata 表达式特性：** +- **输入变量：** + - `state` — 当前值 + - `event` — 单条事件 context + - `params` — 投影参数 +- **Event context 包含：** + - `id`, `type` (hash), `timestamp` + - payload 展开的所有字段 +- **执行方式：** 逐条 dispatch，不是批量 + +## Reaction 触发链路详解 + +完整流程： + +``` +POST /events { type: "assigned", payload: {...} } + ↓ +解析名字 → hash + ↓ +校验 schema + ↓ +INSERT events + event_refs + ↓ +SELECT projection_hash FROM projection_def_sources WHERE event_def_hash = ? + ↓ +对每个匹配的 projection： + ↓ + SELECT reactions WHERE projection_def_hash = ? + ↓ + 对每个 reaction： + ↓ + bindings 匹配（params → event_refs 查询） + ↓ + 重算 projection（lazy incremental reduce） + ↓ + diff(old_value, new_value) + ↓ + 如果有变化： + ↓ + webhook: POST webhook_url { old_value, new_value, params, event } + 或 + emit_event: POST /events { + type: emit_event_type, + payload: template(old, new, params, event) + } +``` + +--- + +*本文档作为 OGraph v2.4+ 的技术规范，供系统集成和 API 调用参考。* \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 8c97160..caba108 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -114,6 +114,7 @@ nav: - Sigil Backend 与 LRU 调度: shared/sigil-backend-lru.md - Widget → Capability 集成修复实录: shared/widget-capability-integration-fix.md - OGraph 响应式计算模型: shared/ograph-reactive-patterns.md + - OGraph 对象模型与 API Protocol: shared/ograph-object-model.md - 基础设施: - Bootstrap 新设备: shared/bootstrap-onboarding.md - Onboarding Checklist: shared/onboarding-checklist.md