History-client/EDITOR_LOCAL_STORAGE.md

Editor (/editor) - Local Store & Snapshot Conversion

Tài liệu này mô tả chi tiết các nơi lưu trữ state (store) ở phía FrontEndUser trong /editor/[id], ý nghĩa từng biến state, state nào là “single source of truth”, state nào chỉ là cache/UI, và cách chuyển đổi qua lại giữa:

1. Local session state (React state trong phiên làm việc)
2. Commit snapshot (commits.snapshot_json)
3. Reload trang (mất state local, load lại từ commit snapshot)

Mục tiêu: dễ debug, nhất quán dữ liệu, tránh sai semantics "reference"/"binding".

---

0) 5 Dataset Quan Trọng Nhất (GEO/ENT/WIKI/ENT_WIKI/GEO_ENT)

Trong /editor, 5 nhóm dữ liệu quan trọng nhất tương ứng trực tiếp với snapshot:

1. GEO: snapshot_json.geometries[] + snapshot_json.editor_feature_collection
2. ENT: snapshot_json.entities[]
3. WIKI: snapshot_json.wikis[]
4. ENT_WIKI (entity ↔ wiki): snapshot_json.entity_wiki[]
5. GEO_ENT (geometry ↔ entity): snapshot_json.geometry_entity[]

Điểm quan trọng về “store”:

• ENT/WIKI/ENT_WIKI có store snapshot riêng trong React session:

  • snapshotEntities -> entities[]
  • snapshotWikis -> wikis[]
  • snapshotEntityWikiLinks -> entity_wiki[]

• GEO/GEO_ENT không có store snapshot riêng theo kiểu snapshotGeometries / snapshotGeometryEntity.

  • Trong session, GEO sống ở editor.draft (GeoJSON FeatureCollection).
  • Khi commit, FE build ra:
    • geometries[] từ editor.draft + editor.changes + baselineSnapshot.geometries
    • geometry_entity[] từ editor.draft.features[].properties.entity_ids

Vì vậy, nếu bạn “tìm store của geo trong React state” thì bạn sẽ thấy nó nằm ở useEditorState() chứ không nằm trong useEditorSessionState().

---

1) Nguyên tắc chung

1.1 Single source of truth theo lớp

• Geometry (map/editor): useEditorState(initialData) là state trung tâm cho draft/changes/undo.
• Snapshot stores (phần sẽ đi vào commit snapshot):
  • snapshotEntities -> snapshot_json.entities
  • snapshotWikis -> snapshot_json.wikis
  • snapshotEntityWikiLinks -> snapshot_json.entity_wiki
• Catalog/cache để tìm kiếm & hiển thị:
  • entityCatalog là danh sách entity “global” trong RAM (fetch + search merge). Không phải snapshot.

1.2 “reference” vs “binding”

• "reference" (entities/wikis/geometries.operation) nghĩa là không sửa record trong commit đó.
• "binding" (chỉ áp dụng cho entity_wiki.operation) nghĩa là link entity ↔ wiki đang tồn tại trong snapshot.
• "delete" nghĩa là xóa record (entities/wikis/geometries) hoặc unlink (entity_wiki).

Khi mở 1 phiên editor mới từ commit, mọi operation local đều bị “reset về baseline”:

• entities[].operation và wikis[].operation trong session -> "reference"
• entity_wiki[].operation trong session -> "binding" (nếu link còn active)

---

2) Local state: danh sách đầy đủ và ý nghĩa

Các state này được tạo từ useEditorSessionState() và useEditorState() trong:

• FrontEndUser/src/app/editor/[id]/page.tsx
• FrontEndUser/src/uhm/lib/useEditorSessionState.ts
• FrontEndUser/src/uhm/lib/useEditorState.ts

2.1 Geometry editor state (core)

Nguồn: const editor = useEditorState(initialData)

• initialData: FeatureCollection

  • Là baseline của session hiện tại để render Map ban đầu.
  • Được set khi:
    • mở project (load snapshot head),
    • restore FE-only từ 1 commit,
    • hoặc import/replace dữ liệu session.

• editor.draft: FeatureCollection

  • Single source of truth cho geometry đang hiển thị + chỉnh sửa.
  • Map render trực tiếp từ draft (hoặc bản “visibleDraft” đã filter theo timeline/binding).
  • Đây chính là store runtime của GEO trong session.

• editor.changes: Map<id, Change>

  • Diff giữa draft và baseline map nội bộ (initialMapRef).
  • Dùng để tính pendingSaveCount và để build snapshot geometries/update/delete.

• editor.undoStack

  • Danh sách thao tác gần nhất (create/update/properties/delete).

• editor.changeCount

  • Số lượng changes (để chặn commit khi không đổi gì).

• editor.hasPersistedFeature(id)

  • true nếu feature đã tồn tại trong baseline map nội bộ.
  • Dùng cho timeline filter: feature mới tạo trong session vẫn luôn visible.

2.2 Snapshot stores (persisted on commit)

Các state này là “source of truth” cho những phần non-geometry trong commit snapshot.

a) snapshotEntities: EntitySnapshot[]

• Dùng để build snapshot_json.entities.
• Bao gồm:
  • entity “pin” vào project (source:"ref", operation:"reference"),
  • entity tạo mới local (source:"inline", operation:"create"),
  • entity bị xóa (nếu có) (operation:"delete").

Lưu ý quan trọng:

• snapshotEntities là nơi “giữ entity” qua các commit, kể cả entity tạo mới chưa bind geometry.
• buildEditorSnapshot() có logic carry-forward inline entity từ previousSnapshot để tránh mất entity sau commit/reload.

b) snapshotWikis: WikiSnapshot[]

• Dùng để build snapshot_json.wikis.
• Wiki hiện lưu doc là string (HTML) (Quill) hoặc null với ref wiki.
• Tiptap JSON cũ: được normalize sang HTML để hiển thị.

c) snapshotEntityWikiLinks: EntityWikiLinkSnapshot[]

• Dùng để build snapshot_json.entity_wiki.
• operation:
  • "binding": link đang tồn tại
  • "delete": unlink trong snapshot
  • (compat) "reference" từ snapshot cũ được normalize thành "binding" khi load.

2.3 Catalog/cache state (không persist)

entityCatalog: Entity[]

Đây là RAM cache để:

• hiển thị tên/description/status của entity,
• merge kết quả fetch + search,
• giảm tình trạng UI “cùng 1 entity nhưng 2 object khác nhau”.

Không ghi thẳng vào snapshot. Snapshot vẫn lấy từ snapshotEntities.

Trong page, danh sách entities dùng cho UI được merge:

entities = mergeEntitySearchResults(entityCatalog, snapshotEntitiesAsEntities)

Nghĩa là: snapshot entities (local) luôn được ưu tiên hiển thị trong UI.

2.4 UI-only state (không persist)

Các state sau chỉ phục vụ UX, mất khi reload:

• mode (idle/select/add-*)
• selectedFeatureId
• selectedGeometryEntityIds (list bind tạm thời cho UI, map patch sẽ sync vào feature properties)
• geometryMetaForm
• entityForm (tạo entity mới)
• entityFormStatus (toast/status 3s)
• searchKind, searchQuery
• entitySearchResults, wikiSearchResults, geoSearchResults
• timelineDraftYear, timelineFilterEnabled
• panel widths (leftPanelWidth, rightPanelWidth)

2.5 LocalStorage (trên browser)

Hiện tại chỉ có 1 thứ persist sang LocalStorage:

• backgroundVisibility (ẩn/hiện layer nền)

Các snapshot stores (snapshotEntities, snapshotWikis, snapshotEntityWikiLinks, draft) không lưu LocalStorage; chúng được persist qua commit snapshot (backend).

---

3) Chuyển đổi giữa local session ↔ snapshot

3.1 Load snapshot -> mở session

Luồng: openSectionEditor() -> normalizeEditorSnapshot() -> toEditorSessionSnapshot()

Khi mở session mới:

1. baselineSnapshot = toEditorSessionSnapshot(snapshot)
2. initialData = baselineSnapshot.editor_feature_collection || EMPTY_FEATURE_COLLECTION
3. snapshotEntities = baselineSnapshot.entities || []
4. snapshotWikis = baselineSnapshot.wikis || []
5. snapshotEntityWikiLinks = baselineSnapshot.entity_wiki || []

Riêng về GEO/GEO_ENT khi load:

• baselineSnapshot.editor_feature_collection là dữ liệu map gốc đưa vào initialData.
• normalizeEditorSnapshot() sẽ rehydrate feature.properties.entity_ids/entity_id từ snapshot.geometry_entity[] (hoặc legacy link_scopes) để UI bind entity hoạt động.
  • Lưu ý: đây là rehydrate phục vụ editor UX, không phải dữ liệu persist chính thức trên feature.properties trong snapshot.

Điểm mấu chốt: toEditorSessionSnapshot() reset operation để snapshot trở thành “baseline state”:

• entities/wikis -> "reference"
• entity_wiki active -> "binding"

3.2 Commit session -> snapshot_json

Luồng: commitSection() -> buildEditorSnapshot({ draft, changes, snapshotEntities, snapshotWikis, snapshotEntityWikiLinks, previousSnapshot: baselineSnapshot })

buildEditorSnapshot() sẽ tạo:

• editor_feature_collection (draft đã strip các field denormalized)
• geometries[] (create/update/delete dựa trên changes + previousSnapshot)
• geometry_entity[] (join table từ feature.properties.entity_ids)
• entities[] (từ snapshotEntities + carry-forward inline + ensure entities referenced by joins)
• wikis[] (từ snapshotWikis, tương tự)
• entity_wiki[] (từ snapshotEntityWikiLinks, đã dedupe/sort)

Sau khi commit thành công:

• baselineSnapshot cập nhật = toEditorSessionSnapshot(snapshot) của commit mới
• snapshot stores cập nhật theo baseline mới (operation reset về "reference"/"binding")

3.3 Reload trang -> mất local state

Khi reload:

• Toàn bộ React state reset
• App sẽ load lại snapshot từ backend (head commit)
• Các thứ bạn “tạo/sửa” chỉ còn lại nếu đã nằm trong commit snapshot

Vì vậy:

• Entity/Wiki/Link/Geometry muốn “không mất” phải đi qua Commit.
• Các state UI (selected geo, search results, form đang nhập) sẽ mất.

---

4) GEO Search (/geometries/entity) và tác động lên local store

Search GEO gọi:

GET /geometries/entity?name=<keyword>&limit=<n>

Khi bấm Import một geometry từ kết quả search:

1. Tắt timelineFilterEnabled để geometry luôn nhìn thấy (không bị filter theo năm).
2. Add entity tương ứng vào:
   • snapshotEntities (source:"ref", operation:"reference")
   • entityCatalog (để UI có name/description)
3. Nếu geometry chưa có trong editor.draft:
   • tạo Feature mới với id = geometry.id
   • set properties.type từ geo_type (map qua geoTypeCodeToTypeKey)
   • set time_start/time_end/binding
   • set denormalized entity_id/entity_ids/entity_name/entity_names để UI/joins hoạt động
4. editor.createFeature(feature) và auto select feature đó.

Lưu ý: Import geo tạo ra “create change” trong editor session, nên sẽ đi vào commit snapshot.

---

4.1 Nhìn nhanh “5 dataset nằm ở đâu” trong session

• GEO:

  • Runtime store: editor.draft.features[]
  • Persisted on commit: snapshot_json.geometries[] (build khi commit)

• ENT:

  • Runtime store (snapshot): snapshotEntities
  • Persisted on commit: snapshot_json.entities[]

• WIKI:

  • Runtime store (snapshot): snapshotWikis
  • Persisted on commit: snapshot_json.wikis[]

• ENT_WIKI:

  • Runtime store (snapshot): snapshotEntityWikiLinks
  • Persisted on commit: snapshot_json.entity_wiki[]

• GEO_ENT:

  • Runtime store: denormalized tạm thời trên editor.draft.features[].properties.entity_ids (để UI chạy)
  • Persisted on commit: snapshot_json.geometry_entity[] (build khi commit)

---

5) Checklist khi debug “mất dữ liệu”

1. Dữ liệu có nằm trong snapshotEntities/snapshotWikis/snapshotEntityWikiLinks/editor.draft không?
2. Có bấm Commit chưa?
3. pendingSaveCount có > 0 không (Commit button có enable không)?
4. Khi reload, snapshot head commit load lên có chứa các rows đó không?
5. Nếu entity tạo mới bị mất:

• kiểm tra commit snapshot có entities[].source:"inline" không
• nếu có mà reload vẫn mất, kiểm tra normalizeEditorSnapshot() có parse đúng không

---

6) File/entrypoints liên quan

• Session stores:

  • FrontEndUser/src/uhm/lib/useEditorSessionState.ts
  • FrontEndUser/src/uhm/lib/editor/session/useEntitySessionState.ts
  • FrontEndUser/src/uhm/lib/editor/session/useWikiSessionState.ts
  • FrontEndUser/src/uhm/lib/editor/session/useSectionSessionState.ts

• Geometry editor core:

  • FrontEndUser/src/uhm/lib/useEditorState.ts

• Snapshot normalization + build snapshot:

  • FrontEndUser/src/uhm/lib/editor/snapshot/editorSnapshot.ts

• Open/commit/restore commands:

  • FrontEndUser/src/uhm/lib/editor/section/useSectionCommands.ts

• Page wiring / UI state:

  • FrontEndUser/src/app/editor/[id]/page.tsx