History-admin/src/uhm/doc/editor_states.md

UHM Editor - state và vòng đời dữ liệu

Tài liệu này mô tả state thật đang được dùng bởi editor hiện tại. Entry point chính là useEditorSessionState() và useEditorState().

1. Hai lớp state chính

Editor đang tách làm hai khối:

• useEditorSessionState()
  • state UI, session, form, project, timeline, background, wiki
• useEditorState(baselineFeatureCollection, snapshotUndo)
  • state draft hình học, diff và undo

Nói ngắn gọn:

• session state quyết định editor đang nhìn cái gì và panel đang thao tác gì
• editor state quyết định geometry nào đang tồn tại trong draft và khác baseline ra sao

2. State geometry trung tâm

baselineFeatureCollection

• Nằm ở useEditorSessionState()
• Là FeatureCollection baseline được nạp vào editor khi mở project hoặc restore commit
• Khi thay đổi, useEditorState() sẽ reset toàn bộ draft và baseline tương ứng

mainDraft

• Nằm trong useEditorState()
• Là working copy geometry chính dùng cho edit/commit
• Mọi thao tác create/update/delete geometry đều đi qua đây

editor.draft

• Là draft đang active theo mode
• Ở mode thường trỏ tới mainDraft
• Ở mode replay trỏ tới replayDraft
• Panel metadata/selection đọc từ đây, không đọc từ mapRenderDraft

draftRef

• Ref nội bộ tương ứng với draft trong useEditorState()
• Được dùng để luôn đọc được state mới nhất mà không phải rebind callback liên tục
• Không nhầm với renderDraftRef trong Map.tsx, vốn là dữ liệu đang render/interact trên map

initialMapRef

• Map<featureId, Feature> tạo từ baselineFeatureCollection
• Là baseline để tính diff giữa draft hiện tại và dữ liệu gốc của session

changes

• Kết quả diffDraftToInitial(draft, initialMapRef.current)
• Map theo feature.properties.id
• Mỗi phần tử có thể là:
  • create
  • update
  • delete

Lưu ý: diff hiện chỉ là cơ chế nhận biết geometry nào đã thay đổi so với baseline. Snapshot commit thực tế vẫn được build từ toàn bộ draft cộng với các snapshot bảng phụ.

changeCount

• Số lượng geometry thay đổi hiện tại
• Được cộng thêm dirty state của wiki/entity/entity-wiki/replay để tạo pendingSaveCount

3. Undo state

Undo được quản lý bởi useUndoStack().

Kiểu action hiện có:

• create
• delete
• update
• properties
• snapshot_entities
• snapshot_wikis
• snapshot_entity_wiki
• replay
• replays
• replay_session
• group

Ý nghĩa:

• geometry create/delete/update/properties undo được trực tiếp trên draft
• snapshot entity/wiki/link undo được apply qua snapshotUndo API truyền vào useEditorState
• replay/replays undo các thay đổi script replay đã flush vào collection chính
• replay_session undo các thay đổi stage/step/action khi đang ở mode replay
• group dùng để gom nhiều thay đổi thành một thao tác undo logic

Editor hiện có undo, nhưng chưa có redo.

4. Session state theo nhóm

4.1. Mode và selection

• mode: EditorMode
• selectedFeatureIds
• selectedGeometryEntityIds

selectedFeatureIds là state gốc cho:

• panel metadata geometry
• bind entity
• bind geometry
• focus geometry từ search/binding panel

4.2. Form state

• entityForm
  • dùng cho form tạo entity local
• geometryMetaForm
  • type_key
  • time_start
  • time_end

Geometry-geometry bound state không nằm trong geometryMetaForm; GeometryBindingPanel chỉnh trực tiếp feature.properties.bound_with của geometry con.

4.3. Replay state

Replay state nằm trong useEditorState():

• replays
  • collection script đã flush vào state chính
• activeReplayDraft
  • BattleReplay đang sửa trong mode replay
• replayDraft
  • FeatureCollection hydrate từ mainDraft + activeReplayDraft.target_geometry_ids
• effectiveReplays
  • replays cộng overlay của activeReplayDraft nếu session hiện tại đã đổi nhưng chưa flush

Undo của replay session dùng stack riêng khi mode === "replay". replay_preview là session preview trong page, dùng previewSession/useReplayPreview() và không persist. Khi thoát các chế độ preview, editor sẽ dọn dẹp hoàn toàn các map effects, highlight, và khôi phục camera view state & projection (Globe/Flat) ban đầu trước khi vào preview.

4.4. Project/session task state

useProjectSessionState() gom các cờ async vào một state machine nhỏ:

• sectionTask: "idle" | "saving" | "submitting" | "opening-project"

Từ đó sinh ra:

• isSaving
• isSubmitting
• isOpeningSection

Ngoài ra còn có:

• activeSection
• projectState
• sectionCommits
• baselineSnapshot
• commitTitle

4.5. Timeline state

useTimelineState() giữ:

• timelineYear
• timelineDraftYear
• isTimelineLoading
• timelineStatus

Trong page hiện tại, timeline filter đang dùng timelineDraftYear. Không có fetch dữ liệu project theo timelineYear; timeline đang là client-side visibility filter.

4.6. Background/session UI

useBackgroundSessionState() giữ:

• backgroundVisibility
• isBackgroundVisibilityReady

Giá trị thật được load từ localStorage key uhm.backgroundLayerVisibility.v1.

4.7. Wiki/session state

useWikiSessionState() giữ:

• snapshotWikis
• snapshotEntityWikiLinks

Đây là single source of truth cho phần wiki trong snapshot commit.

4.8. Preview session states và refs (Viewer / Replay Preview)

Các states và refs điều khiển preview được khai báo trực tiếp trong page.tsx:

• previewSession: ReplayPreviewSession | null
  • Đóng băng toàn bộ snapshot collections (replays, draft, entities, wikis, links) cùng timeline, filter và camera view state khi chạy preview.
• previewAutoplayMode: "start" | "selection" | null
  • Trạng thái autoplay (bắt đầu từ đầu hay từ step được chọn) của Replay Preview.
• previewWikiCache, previewWikiError, isPreviewWikiLoading
  • Cache và status để hiển thị nội dung Wiki tương tác trong sidebar preview.
• previewFeaturePopupAnchor: MapFeaturePayload | null
  • Neo tọa độ/payload của popup hiển thị thông tin geometry khi click trên map ở preview mode.
• previewActiveEntityId, isPreviewEntitySidebarOpen
  • Sidebar hiển thị chi tiết entity được chọn trong preview.
• previewLinkEntityPopup: PreviewLinkEntityPopupState | null
  • Trạng thái popup điều hướng sang entity khác khi click vào link wiki trong preview.
• editorOriginalMapViewStateRef: ReturnType<MapHandle["getViewState"]> | null
  • Ref lưu giữ camera view state và projection (Globe/Flat) ban đầu của editor trước khi bắt đầu preview, phục vụ việc khôi phục hoàn toàn bản đồ khi exit.
• replayPreviewReturnRef: { mode: "replay" | "preview"; session: ReplayPreviewSession | null }
  • Ref ghi nhận session và mode trước đó khi chuyển tiếp từ Viewer Preview sang Replay Preview, cho phép quay trở lại đúng Viewer Preview khi click thoát Replay Preview.

5. Snapshot state

Editor đang làm việc với các snapshot collection chính ngoài geometry:

• snapshotEntityRows
• snapshotWikis
• snapshotEntityWikiLinks
• replays / effectiveReplays

Chúng đại diện cho "current session snapshot", không phải danh sách delta thô.

Ví dụ:

• entity ref được giữ bằng operation: "reference"
• entity/wiki local mới tạo có thể mang operation: "create"
• link entity-wiki mới tạo dùng operation: "binding"

Khi commit, buildEditorSnapshot() sẽ so với baselineSnapshot để chuyển các collection này thành snapshot đúng semantic cho backend.

6. Baseline snapshot là gì

baselineSnapshot là snapshot đang được xem như gốc của session hiện tại.

Nó được cập nhật khi:

• mở project
• commit thành công
• restore từ một commit

baselineSnapshot được dùng để:

• biết link nào là reference, link nào là binding, link nào là delete
• biết wiki/entity nào là thay đổi thực sự so với snapshot trước
• giữ lại inline entity/wiki từ snapshot trước nếu user chưa xóa chúng

7. Derived state quan trọng trong page

mapRenderDraft

• là FeatureCollection duy nhất trong page quyết định geometry nào được truyền xuống map
• nguồn có thể là mainDraft, replayDraft, hoặc preview draft tùy mode
• đã qua filter timeline nếu timelineFilterEnabled = true
• đã qua replay preview hidden ids nếu đang preview
• geometry mới tạo trong session cũng bị timeline filter xử lý như geometry baseline

labelContextBaseDraft và mapLabelContextDraft

• chỉ dùng để enrich/lookup label entity cho map
• có thể chứa geometry bị mapRenderDraft lọc ra
• không được dùng để quyết định geometry nào render trên map

geometryChoices

• nguồn dữ liệu cho GeometryBindingPanel
• thêm trạng thái derived như orphan entity, time completeness, timeline visibility, hidden/bound/new
• ID geometry không phải label chính của row, nhưng vẫn nằm trong tooltip/title

snapshotEntityRowsVisible

• loại bỏ các row delete
• dedupe theo id

selectedFeatures

• map từ selectedFeatureIds sang feature thật trong editor.draft.features

isMultiEditValid

• chỉ true khi tất cả geometry đang chọn cùng geometry.type
• một số thao tác bind sẽ chặn nếu giá trị này là false

pendingSaveCount

Được tính như sau:

• editor.changeCount
• +1 nếu wiki dirty
• +1 nếu entities dirty
• +1 nếu entity-wiki dirty
• +1 nếu replay dirty

Đây là con số dùng trong UI commit, không phải số record backend chắc chắn sẽ thay đổi.

8. Dirty detection

Dirty check của:

• snapshotWikis
• snapshotEntityRows
• snapshotEntityWikiLinks
• editor.effectiveReplays

đều đang làm bằng cách normalize trước rồi so JSON.stringify.

Điều này đủ thực dụng cho snapshot cỡ vừa, nhưng cần lưu ý:

• không tối ưu cho dữ liệu rất lớn
• phụ thuộc vào tính ổn định của thứ tự mảng sau normalize

9. State được persist vào localStorage

Hiện editor chỉ persist hai nhóm nhỏ:

• background layer visibility
  • key: uhm.backgroundLayerVisibility.v1
• map projection
  • key: uhm:mapProjection

Editor hiện không persist toàn bộ draft/project snapshot vào localStorage. Nếu cần autosave local draft, đó là tính năng phải làm thêm, không phải behavior hiện tại.

10. Khi nào state bị reset

Reset toàn phần

Xảy ra khi:

• mở project khác
• mở lại project
• restore commit

Hiệu ứng:

• baselineFeatureCollection đổi
• useEditorState() reset draft
• undoStack bị clear
• baseline map được build lại

Reset cục bộ

• đổi selection có thể reset geometryMetaForm
• đóng/mở wiki modal không reset snapshot wiki, chỉ reset form local của modal

11. Một số giới hạn hiện tại cần nhớ khi đọc code

• có undo, chưa có redo
• timeline state có timelineYear, nhưng page hiện dùng timelineDraftYear cho filtering
• dirty count của commit không tương ứng một-một với số mutation backend
• map selection, bound_with filter và timeline filter đều là state client-side
• trạng thái orphan/time/timeline trong GeometryBindingPanel là derived từ draft + visibility, không phải field persist riêng