From 520e490dacbd69f79ae08246897b254be3a0f0e1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=A2=A8?= Date: Sun, 12 Apr 2026 13:49:15 +0000 Subject: [PATCH] =?UTF-8?q?fix(docs):=20=E5=8E=BB=E6=8E=89=20objects.exter?= =?UTF-8?q?nal=5Fid=EF=BC=8C=E5=A4=96=E9=83=A8=E6=A0=87=E8=AF=86=E9=80=9A?= =?UTF-8?q?=E8=BF=87=E4=BA=8B=E4=BB=B6=20payload=20=E8=AE=B0=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Based on 小橘 review on #214 提交: 小墨 🖊️（KUMA Team） --- docs/shared/ograph-object-model.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/shared/ograph-object-model.md b/docs/shared/ograph-object-model.md index 6279991..a099138 100644 --- a/docs/shared/ograph-object-model.md +++ b/docs/shared/ograph-object-model.md @@ -119,27 +119,24 @@ projection_def_names ( ### 3.1 Object -纯标识实体，`id + type + created_at`，可选 `external_id` 供外部系统引用。 +纯标识实体，`id + type + created_at`。 **数据表：** ```sql objects ( id INTEGER PRIMARY KEY AUTOINCREMENT, type TEXT NOT NULL, -- → object_defs.name - external_id TEXT, -- 可选，外部系统的可读标识（如 GitHub issue number） created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000) ); -CREATE UNIQUE INDEX idx_objects_ext ON objects(external_id) WHERE external_id IS NOT NULL; ``` **ID 策略：** - 内部 ID 使用 `INTEGER AUTOINCREMENT`，简单高效 -- `external_id` 可选，用于存储外部系统标识（GitHub issue、Gitee issue 等），便于 Adapter 层（#211）双向映射 -- `GET /objects/:id` 先查 `external_id`，再查 `id`，两种方式都可定位 +- 外部系统标识（GitHub issue number 等）不放在 Object 表上，而是通过事件 payload 记录（如 `external_id_linked` 事件），由 Adapter 层自行管理映射 **API：** -- `POST /objects { type, external_id? }` — 创建 Object 实例 -- `GET /objects/:id` — 查询 Object（支持 integer id 或 external_id） +- `POST /objects { type }` — 创建 Object 实例 +- `GET /objects/:id` — 查询 Object - `GET /objects?type=` — 按类型列出 Objects ### 3.2 Event @@ -355,7 +352,7 @@ SELECT projection_hash FROM projection_def_sources WHERE event_def_hash = ? | 实体 | ID 类型 | 理由 | |---|---|---| -| Object | INTEGER AUTOINCREMENT | 内部标识足够，外部引用走 `external_id` | +| Object | INTEGER AUTOINCREMENT | 内部标识足够，外部引用通过事件 payload 记录 | | Event | INTEGER AUTOINCREMENT | 严格递增，做增量边界，天然全序 | | Reaction | INTEGER AUTOINCREMENT | 纯内部实体 | | Def versions | content hash (TEXT) | 内容寻址，版本链语义需要 |