History-user/src/uhm/doc/developer_guide.md

# UHM Editor - developer guide thực dụng

Tài liệu này dành cho người sửa editor hiện tại, không phải mô tả kiến trúc lý tưởng.

## 1. Entry points quan trọng

- `src/app/editor/[id]/page.tsx`
  - orchestration chính của project editor
- `src/uhm/components/Map.tsx`
  - container cho map và các hook map
- `src/uhm/lib/editor/state/useEditorState.ts`
  - draft geometry + diff + undo
- `src/uhm/lib/editor/state/useEditorSessionState.ts`
  - session/UI/project/wiki/entity state
- `src/uhm/lib/editor/snapshot/editorSnapshot.ts`
  - normalize snapshot từ backend và build snapshot gửi ngược lại backend

Nếu chưa đọc 5 file này, chưa nên sửa behavior lớn của editor.

Docs nên đọc trước khi sửa editor:

- `src/uhm/doc/editor_operations.md`
- `src/uhm/doc/editor_data_roles.md`
- `src/uhm/doc/editor_snapshot_contract.md`
- `src/uhm/doc/editor_manual_test_checklist.md`
- `src/uhm/doc/editor_replay_actions.md`

## 2. Cấu trúc thư mục nên ưu tiên hiểu

- `src/uhm/components/editor/`
  - panel UI bên trái/phải
- `src/uhm/components/wiki/`
  - wiki editor và wiki viewer/sidebar
- `src/uhm/components/map/`
  - hooks tích hợp MapLibre
- `src/uhm/lib/map/engines/`
  - logic interaction theo mode
- `src/uhm/lib/editor/session/`
  - các nhóm session state
- `src/uhm/lib/editor/draft/`
  - draft diff và undo
- `src/uhm/lib/editor/snapshot/`
  - schema conversion / snapshot semantics

## 3. Cách editor thật sự vận hành

Editor có 3 tầng dữ liệu:

1. `baselineSnapshot`
   - snapshot gốc của session
2. `baselineFeatureCollection`
   - `FeatureCollection` rehydrate từ snapshot đó
   - seed/reset cho `useEditorState()`
3. `mainDraft`
   - working copy để user sửa trên map

Map không render trực tiếp `mainDraft` mọi lúc. Page tạo `mapRenderDraft` từ `mainDraft`/`replayDraft`/preview draft sau khi áp timeline/replay filter, rồi truyền xuống `Map` dưới prop `renderDraft`. `labelContextDraft` chỉ dùng để lookup label, không được dùng để quyết định geometry nào hiện trên map.

Khi commit:

- geometry đi từ `mainDraft`
- entity/wiki/link đi từ snapshot collections
- `buildEditorSnapshot()` quyết định operation nào là `reference`, `binding`, `update`, `delete`

Đừng tự build payload ở component nếu chưa hiểu file `editorSnapshot.ts`.

## 4. Khi thêm mode/tool mới

Checklist an toàn:

1. Thêm mode vào `sessionTypes.ts`.
2. Thêm button vào `ToolsPanel.tsx`.
3. Nếu mode cần preview source/layer mới, thêm vào `setupMapLayers()`.
4. Nối mode với engine trong `useMapInteraction.ts`.
5. Nếu tool tạo geometry mới, chọn default:
   - `type`
   - `geometry_preset`
   - `entity_ids`
   - `bound_with`
6. Kiểm tra interaction cleanup khi chuyển mode.

Nếu mode chưa được cleanup đúng, map rất dễ giữ preview cũ hoặc event listener cũ.

## 5. Khi thêm geotype mới

Checklist ngắn:

1. Cập nhật `geoTypeMap` nếu cần mapping backend code <-> key.
2. Cập nhật `geometryTypeOptions.ts`.
3. Tạo style file trong `styles/geotypes/`.
4. Register ở `geotypeLayers.ts`.
5. Kiểm tra point icon hoặc label pipeline nếu type mới là point/route/polygon label.

Nếu chỉ sửa `geometryTypeOptions.ts` mà quên style registry, UI sẽ cho chọn type nhưng map không render đúng.

## 6. Khi sửa snapshot semantics

File quan trọng nhất là `editorSnapshot.ts`.

Ở đó đang có hai hướng xử lý khác nhau:

- `normalizeEditorSnapshot(raw)`
  - đọc payload từ backend
  - rehydrate fields UI như `entity_ids`, `entity_name`, `bound_with`, `time_start`, `time_end`
- `buildEditorSnapshot(options)`
  - strip các field generate-only khỏi `editor_feature_collection`
  - build `geometry_entity[]` và `entity_wiki[]`
  - tính operation phù hợp

Nguyên tắc:

- feature trong editor có thể mang field denormalized để UI dễ dùng
- payload gửi backend thì không nên mang những field denormalized đó

## 7. Khi sửa wiki editor

Wiki project editor hiện là Quill, không phải Tiptap.

Các file nên đọc trước:

- `WikiSidebarPanel.tsx`
- `PublicWikiSidebar.tsx`

Các điểm dễ làm hỏng:

- sanitize link của Quill
- compatibility với doc dạng HTML/plain text
- slug links nội bộ
- sentinel `__missing__`

Nếu thay storage format, phải sửa cả editor lẫn viewer compatibility path.

## 8. Những key localStorage thật sự đang dùng

- `uhm.backgroundLayerVisibility.v1`
- `uhm:mapProjection`

Hiện không có local draft autosave toàn editor.
Đừng dựa vào doc cũ hoặc giả định rằng F5 sẽ hồi lại draft geometry/wiki/entity.

## 9. Restore commit hiện là FE-only

`CommitHistoryPanel -> Restore`:

- load snapshot từ commit cũ
- reset editor state ở frontend
- không đổi head commit trên backend

Nếu muốn restore server-side thật, cần dùng endpoint backend riêng và sửa cả UI wording.

## 10. Pending submission lock là rule thật

`openSectionEditor()` chủ động chặn project có `PENDING` submission.

Nghĩa là:

- không nên "lách" UI để cho sửa tiếp
- nếu đổi behavior này, phải thống nhất với backend contract

## 11. Performance và state hygiene

Một số nguyên tắc nên giữ:

- dùng `renderDraftRef`/refs trong map engines để tránh rebind handler vô ích
- giữ component panel càng dumb càng tốt, logic patch state đặt ở page/hooks
- khi cần undo cho entity/wiki/link, đi qua `editor.setSnapshot*()` để undo stack biết
- khi cần undo cho replay script, đi qua `editor.mutateActiveReplay()` hoặc replay collection helper hiện có
- hạn chế thêm `JSON.stringify` compare ở chỗ nóng nếu chưa đo hiệu năng

## 12. Chỗ dễ gây hiểu nhầm khi debug

### Geometry biến mất

Có thể do:

- timeline filter
- geometry visibility theo type
- bound_with filter

Không phải lúc nào cũng là bug render layer.

### Commit count lạ

`Commit (N)` là `pendingSaveCount`, không phải số mutation backend.

### Selection mất

Selection hiện bám theo `editor.draft`, không theo `mapRenderDraft`. Vì vậy geometry đang chọn có thể bị timeline filter ẩn khỏi map nhưng panel metadata vẫn đọc được draft gốc.

## 13. Nên test gì sau khi sửa

Ít nhất nên test thủ công:

1. mở project có commit cũ
2. tạo geometry mới bằng mode liên quan
3. sửa metadata geometry
4. bind entity và geometry
5. tạo/sửa wiki
6. link entity-wiki
7. commit
8. restore từ commit cũ
9. mở project có pending submission nếu đang debug flow đó