379 lines
11 KiB
Markdown
379 lines
11 KiB
Markdown
# Commit Snapshot (`commits.snapshot_json`) - Cấu Trúc Hiện Tại
|
|
|
|
Tài liệu này mô tả **commit snapshot** đang được lưu trong `BackEndGo.commits.snapshot_json` (JSONB) và được `FrontEndAdmin` tạo ra khi bấm **Commit** trong `/editor`.
|
|
|
|
Mục tiêu: nhìn vào đây là hiểu commit snapshot gồm những phần nào, ý nghĩa ra sao, và `source`/`operation` có vai trò gì.
|
|
|
|
Nguồn tham chiếu trong code:
|
|
|
|
- Type snapshot: `FrontEndAdmin/src/uhm/types/sections.ts` (`EditorSnapshot`)
|
|
- Build snapshot khi commit: `FrontEndAdmin/src/uhm/lib/editor/snapshot/editorSnapshot.ts` (`buildEditorSnapshot`)
|
|
|
|
## 1) Schema tổng quan (v1)
|
|
|
|
Hiện tại snapshot được ghi với `schema_version: 1`.
|
|
|
|
```ts
|
|
export type CommitSnapshotV1 = {
|
|
schema_version: 1;
|
|
|
|
// Project/section đang được edit (FE vẫn giữ tên "section" cho compatibility)
|
|
section: { id: string; title: string };
|
|
|
|
// GeoJSON draft để render map + làm nguồn dựng geometries/link_scopes
|
|
editor_feature_collection?: FeatureCollection;
|
|
|
|
// Operation-based rows
|
|
entities?: EntitySnapshot[];
|
|
geometries?: GeometrySnapshot[];
|
|
link_scopes?: LinkScopeSnapshot[];
|
|
|
|
// Wiki list (tiptap JSON hoặc reference)
|
|
wikis?: WikiSnapshot[];
|
|
|
|
// Join table inside snapshot: links between entities and wikis (project-level)
|
|
entity_wikis?: EntityWikiLinkSnapshot[];
|
|
};
|
|
```
|
|
|
|
## 2) `operation` có những giá trị nào?
|
|
|
|
Trong commit snapshot hiện tại có 4 nơi dùng `operation`:
|
|
|
|
1. `entities[].operation`:
|
|
|
|
- `create` | `update` | `delete` | `reference`
|
|
|
|
2. `geometries[].operation`:
|
|
|
|
- `create` | `update` | `delete` | `reference`
|
|
|
|
3. `link_scopes[].operation`:
|
|
|
|
- `reference`
|
|
|
|
4. `wikis[].operation`:
|
|
|
|
- `create` | `update` | `delete` | `reference`
|
|
|
|
Ghi chú về semantics:
|
|
|
|
- `create/update/delete`: bản ghi bị thay đổi trong commit này
|
|
- `reference`: bản ghi được đưa vào snapshot để làm đầu mối **nối (link)** (vd: geometry↔entity, entity↔wiki), không phải “không đổi”
|
|
|
|
Ngoài ra snapshot có `entity_wikis[]` để nối entity <-> wiki.
|
|
|
|
## 3) Sơ đồ trực quan (Mermaid)
|
|
|
|
```mermaid
|
|
classDiagram
|
|
class CommitSnapshotV1 {
|
|
+number schema_version
|
|
+SectionRef section
|
|
+FeatureCollection editor_feature_collection?
|
|
+EntitySnapshot[] entities?
|
|
+GeometrySnapshot[] geometries?
|
|
+LinkScopeSnapshot[] link_scopes?
|
|
+WikiSnapshot[] wikis?
|
|
+EntityWikiLinkSnapshot[] entity_wikis?
|
|
}
|
|
|
|
class SectionRef {
|
|
+string id
|
|
+string title
|
|
}
|
|
|
|
class FeatureCollection {
|
|
+string type // "FeatureCollection"
|
|
+Feature[] features
|
|
}
|
|
|
|
class Feature {
|
|
+string type // "Feature"
|
|
+FeatureProperties properties
|
|
+Geometry geometry
|
|
}
|
|
|
|
class FeatureProperties {
|
|
+string|number id
|
|
+string type?
|
|
+number time_start?
|
|
+number time_end?
|
|
+string[] binding?
|
|
+string entity_id?
|
|
+string[] entity_ids?
|
|
+string entity_name?
|
|
+string[] entity_names?
|
|
+string entity_type_id?
|
|
}
|
|
|
|
class EntitySnapshot {
|
|
+string id
|
|
+string source? // inline|ref
|
|
+Ref ref?
|
|
+string operation? // create|update|delete|reference
|
|
+string name?
|
|
+string slug?
|
|
+string description?
|
|
+string type_id?
|
|
+number status?
|
|
+number is_deleted?
|
|
+string base_updated_at?
|
|
+string base_hash?
|
|
}
|
|
|
|
class GeometrySnapshot {
|
|
+string id
|
|
+string source? // inline|ref
|
|
+Ref ref?
|
|
+string operation? // create|update|delete|reference
|
|
+string type?
|
|
+Geometry draw_geometry?
|
|
+string[] binding?
|
|
+number time_start?
|
|
+number time_end?
|
|
+BBox bbox?
|
|
+number is_deleted?
|
|
+string base_updated_at?
|
|
+string base_hash?
|
|
}
|
|
|
|
class BBox {
|
|
+number min_lng
|
|
+number min_lat
|
|
+number max_lng
|
|
+number max_lat
|
|
}
|
|
|
|
class LinkScopeSnapshot {
|
|
+string geometry_id
|
|
+string operation // reference
|
|
+string[] entity_ids
|
|
+string base_links_hash?
|
|
}
|
|
|
|
class WikiSnapshot {
|
|
+string id
|
|
+string source? // inline|ref
|
|
+Ref ref?
|
|
+string operation? // create|update|delete|reference
|
|
+string title
|
|
+any doc
|
|
+string updated_at?
|
|
+number is_deleted?
|
|
}
|
|
|
|
class EntityWikiLinkSnapshot {
|
|
+string entity_id
|
|
+string wiki_id
|
|
+string operation? // reference|delete
|
|
+number is_deleted?
|
|
}
|
|
|
|
class Ref {
|
|
+string id
|
|
}
|
|
|
|
CommitSnapshotV1 --> SectionRef
|
|
CommitSnapshotV1 --> FeatureCollection
|
|
FeatureCollection --> Feature
|
|
Feature --> FeatureProperties
|
|
CommitSnapshotV1 --> EntitySnapshot
|
|
CommitSnapshotV1 --> GeometrySnapshot
|
|
CommitSnapshotV1 --> LinkScopeSnapshot
|
|
CommitSnapshotV1 --> WikiSnapshot
|
|
CommitSnapshotV1 --> EntityWikiLinkSnapshot
|
|
```
|
|
|
|
## 4) Ý nghĩa từng phần
|
|
|
|
### 4.1 `section`
|
|
|
|
Chỉ là “ref” tối thiểu để biết commit này thuộc project nào:
|
|
|
|
- `section.id` = `project_id`
|
|
- `section.title` = title tại thời điểm commit (phục vụ UI)
|
|
|
|
### 4.2 `editor_feature_collection`
|
|
|
|
GeoJSON `FeatureCollection` là nguồn để:
|
|
|
|
- render map trong editor
|
|
- build `geometries[]` + `link_scopes[]` khi commit
|
|
|
|
Trong thực tế, nó là “bản đồ draft state” của commit.
|
|
|
|
### 4.3 `entities[]`
|
|
|
|
`entities[]` là tập các entity rows kèm `source`/`operation`. Trong `buildEditorSnapshot` hiện tại, nó được dựng từ:
|
|
|
|
1. `pending entities` tạo trong editor:
|
|
- `source: "inline"`, `operation: "create"`
|
|
2. `projectEntityRefs` (entity được user “pin” vào project từ thanh search):
|
|
- `source: "ref"`, `ref: {id}`, `operation: "reference"`
|
|
3. Các entity IDs đang được gắn vào geometries trong `editor_feature_collection` (nếu chưa có trong list):
|
|
- `source: "ref"`, `ref: {id}`, `operation: "reference"`
|
|
4. Các entity IDs xuất hiện trong `entity_wikis[]`:
|
|
- `source: "ref"`, `ref: {id}`, `operation: "reference"`
|
|
|
|
=> Nghĩa là: `entities[]` trong commit snapshot hiện tại hoạt động như một “danh sách entity liên quan tới project”, không nhất thiết phải gắn vào một geometry cụ thể.
|
|
|
|
### 4.4 `geometries[]`
|
|
|
|
Mỗi `Feature` trong `editor_feature_collection.features[]` sẽ sinh ra một `GeometrySnapshot` row:
|
|
|
|
- `id`: `String(feature.properties.id)`
|
|
- `draw_geometry`: lấy từ `feature.geometry`
|
|
- `type`: `feature.properties.type || getDefaultTypeIdForFeature(feature)`
|
|
- `binding`: normalize từ `feature.properties.binding`
|
|
- `time_start/time_end`
|
|
- `bbox`: tính từ geometry
|
|
- `is_deleted: 0`
|
|
|
|
`operation` được suy ra dựa vào `changes` + so sánh với snapshot trước:
|
|
|
|
- `create`: feature mới
|
|
- `update`: feature thay đổi
|
|
- (không có `operation`): feature không đổi (không delta trong commit)
|
|
- `delete`: feature bị xoá khỏi draft (FE sẽ thêm 1 row `{ id, operation:"delete", is_deleted:1 }`)
|
|
|
|
### 4.5 `link_scopes[]`
|
|
|
|
FE build link scopes từ GeoJSON features:
|
|
|
|
- `geometry_id = String(feature.properties.id)`
|
|
- `operation = "reference"`
|
|
- `entity_ids` lấy từ `feature.properties.entity_ids` hoặc `entity_id`
|
|
|
|
Chỉ add scope nếu `entity_ids.length > 0`.
|
|
|
|
### 4.6 `wikis[]`
|
|
|
|
`wikis[]` là danh sách wiki của project tại thời điểm commit.
|
|
|
|
Type hiện tại:
|
|
|
|
```ts
|
|
export type WikiSnapshot = {
|
|
id: string;
|
|
source?: "inline" | "ref";
|
|
ref?: { id: string };
|
|
operation?: "create" | "update" | "delete" | "reference";
|
|
title: string;
|
|
doc: unknown; // tiptap JSON doc (inline) hoặc null (reference)
|
|
updated_at?: string;
|
|
is_deleted?: number;
|
|
};
|
|
```
|
|
|
|
Quy ước FE đang dùng:
|
|
|
|
- Wiki tạo mới trong editor: `operation: "create"`, `doc` là tiptap JSON.
|
|
- Wiki sửa: `operation: "update"`, `doc` là tiptap JSON.
|
|
- Wiki không đổi so với snapshot trước: thường **không có** `operation` (không delta).
|
|
- Wiki add từ thanh search (wiki đã tồn tại trong DB): `source:"ref"`, `ref:{id}`, `operation:"reference"`, **`doc` có thể là `null`**.
|
|
|
|
Ghi chú quan trọng:
|
|
|
|
- Hiện tại FE **chưa generate “delete rows” cho wikis** (khác với geometries). Khi bạn remove một wiki khỏi list thì snapshot mới sẽ đơn giản là không còn wiki đó nữa.
|
|
|
|
### 4.7 `entity_wikis[]` (bảng nối Entity ↔ Wiki)
|
|
|
|
`entity_wikis[]` là bảng nối trong snapshot để thể hiện “wiki nào thuộc entity nào” ở mức project/commit.
|
|
|
|
```ts
|
|
export type EntityWikiLinkSnapshot = {
|
|
entity_id: string;
|
|
wiki_id: string;
|
|
operation?: "reference" | "delete";
|
|
is_deleted?: number;
|
|
};
|
|
```
|
|
|
|
FE hiện dùng panel “Entity ↔ Wiki” để toggle link:
|
|
|
|
- Tick checkbox => `{ operation:"reference", is_deleted:0 }`
|
|
- Untick checkbox => `{ operation:"delete", is_deleted:1 }`
|
|
|
|
## 5) Ví dụ JSON (rút gọn)
|
|
|
|
Ví dụ dưới đây thể hiện:
|
|
|
|
- 1 geometry gắn entity `e_1`
|
|
- 1 entity ref “pin” vào project (`e_2`) dù chưa gắn geometry
|
|
- 1 wiki inline và 1 wiki reference (search từ DB)
|
|
|
|
```json
|
|
{
|
|
"schema_version": 1,
|
|
"section": { "id": "019d...project", "title": "Project A" },
|
|
"editor_feature_collection": {
|
|
"type": "FeatureCollection",
|
|
"features": [
|
|
{
|
|
"type": "Feature",
|
|
"properties": {
|
|
"id": "g_1",
|
|
"type": "city",
|
|
"time_start": 1200,
|
|
"time_end": 1300,
|
|
"entity_ids": ["e_1"],
|
|
"entity_names": ["Ha Noi"]
|
|
},
|
|
"geometry": { "type": "Point", "coordinates": [105.8, 21.0] }
|
|
}
|
|
]
|
|
},
|
|
"entities": [
|
|
{ "id": "e_2", "operation": "reference", "name": "Pinned Entity", "is_deleted": 0 },
|
|
{ "id": "e_1", "operation": "reference", "name": "Ha Noi", "type_id": "city", "status": 1, "is_deleted": 0 }
|
|
],
|
|
"geometries": [
|
|
{
|
|
"id": "g_1",
|
|
"operation": "update",
|
|
"type": "city",
|
|
"draw_geometry": { "type": "Point", "coordinates": [105.8, 21.0] },
|
|
"binding": [],
|
|
"time_start": 1200,
|
|
"time_end": 1300,
|
|
"bbox": { "min_lng": 105.8, "min_lat": 21.0, "max_lng": 105.8, "max_lat": 21.0 },
|
|
"is_deleted": 0
|
|
}
|
|
],
|
|
"link_scopes": [{ "geometry_id": "g_1", "operation": "reference", "entity_ids": ["e_1"] }],
|
|
"wikis": [
|
|
{
|
|
"id": "w_inline_1",
|
|
"source": "inline",
|
|
"operation": "create",
|
|
"title": "Overview",
|
|
"doc": { "type": "doc", "content": [{ "type": "paragraph" }] }
|
|
},
|
|
{
|
|
"id": "019d...wiki_from_db",
|
|
"source": "ref",
|
|
"ref": { "id": "019d...wiki_from_db" },
|
|
"operation": "reference",
|
|
"title": "Existing Wiki (DB)",
|
|
"doc": null
|
|
}
|
|
],
|
|
"entity_wikis": [
|
|
{ "entity_id": "e_1", "wiki_id": "w_inline_1", "operation": "reference", "is_deleted": 0 }
|
|
]
|
|
}
|
|
```
|
|
|
|
## 6) Các điểm cần chốt khi muốn đi xa hơn với “ref”
|
|
|
|
Để `source:"ref"` thực sự “lấy từ bên ngoài snapshot”, cần thống nhất:
|
|
|
|
1. Wiki DB format:
|
|
- BackEndGo `wikis.content` hiện là `TEXT`, trong khi editor wiki dùng TipTap JSON (`doc`).
|
|
- Nếu muốn `ref` load content khi cần, phải chốt format lưu trữ (JSON string / HTML / Markdown).
|
|
|
|
2. Semantics `operation:"reference"`:
|
|
- `reference` được dùng theo nghĩa “đầu mối để nối (link)” và thường đi kèm `source:"ref"` (ref tới DB/global).
|
|
- Các bản ghi inline không thay đổi nên **không có `operation`** (không delta).
|