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

UHM Editor - project workflow hiện tại

Tài liệu này mô tả đúng luồng project editor đang chạy ở frontend hiện tại.

1. Mở project

Editor vào từ route /editor/[id].

Luồng mở project:

1. fetchCurrentUser() để chắc phiên đăng nhập còn hợp lệ.
2. openSectionEditor(projectId):
   • gọi API project detail
   • gọi API commit list
   • lấy latest_commit_id
   • load snapshot_json của head commit nếu có
3. normalizeEditorSnapshot() để đưa snapshot về shape editor hiện tại.
4. toEditorSessionSnapshot() để chuyển snapshot thành session state:
   • entities
   • wikis
   • entity-wiki
   • feature collection đã rehydrate entity ids / names / metadata

Nếu project chưa có commit, editor mở với EMPTY_FEATURE_COLLECTION.

2. Rule khóa editor khi có pending submission

Backend mới chặn chỉnh sửa nếu project có submission PENDING.

Frontend xử lý như sau:

• openSectionEditor() ném ApiError(409) kèm pending_submission_id
• page editor bắt lỗi đó
• hiển thị màn hình lock riêng
• cho phép xóa submission pending để mở khóa

Trong trạng thái này:

• không vào map editor
• không commit
• không submit mới

3. Trạng thái project mà editor thực sự dùng

ProjectState đang được FE dùng gồm:

• status
• head_commit_id
• locked_by

Editor page không tự dựng đầy đủ workflow Approved/Rejected ở UI. Phần nó thật sự quan tâm là:

• project có mở được không
• có head_commit_id để submit không
• có pending submission đang khóa project không

4. Vòng đời một phiên chỉnh sửa

Bước 1: load baseline

• baselineSnapshot lấy từ head commit hoặc commit được restore
• baselineFeatureCollection lấy từ baselineSnapshot.editor_feature_collection
• useEditorState() reset draft và undo

Bước 2: chỉnh sửa cục bộ

User có thể sửa:

• geometry
• entity snapshot
• wiki snapshot
• entity-wiki snapshot
• replay script

Tất cả thay đổi lúc này mới chỉ ở memory của frontend.

Bước 3: commit

commitSection() chỉ chạy khi:

• đã mở được project
• pendingSaveCount > 0
• không còn orphan geometry

Luồng commit:

1. build geometry diff từ editor.buildPayload()
2. build snapshot đầy đủ bằng buildEditorSnapshot(...)
3. kiểm tra kích thước payload trước khi gửi
4. gọi createProjectCommit(projectId, { snapshot, edit_summary })
5. nếu thành công:
   • refresh projectState
   • refresh sectionCommits
   • cập nhật baselineSnapshot
   • set baselineFeatureCollection = editor.mainDraft
   • editor.clearChanges()
   • clear commitTitle

Bước 4: submit

submitCurrentSection(content) chỉ chạy khi:

• project đang mở
• có head_commit_id
• pendingSaveCount === 0
• không còn orphan geometry

Frontend sẽ lấy latest commit từ project hiện tại rồi tạo submission mới.

5. Restore commit

Nút Restore trong CommitHistoryPanel hiện là restore phía frontend:

• chỉ chạy khi pendingSaveCount === 0
• tải commit list mới nhất
• lấy snapshot của commit được chọn
• normalize snapshot
• nạp lại vào editor state

Restore này:

• không gọi endpoint đổi head commit
• không thay đổi head trên backend
• chủ yếu để user tiếp tục edit từ snapshot cũ

Nói cách khác, đây là load snapshot into editor, không phải server-side restore.

6. Snapshot commit được build như thế nào

buildEditorSnapshot() nhận:

• draft
• changes
• snapshotEntityRows
• snapshotWikis
• snapshotEntityWikiLinks
• effectiveReplays
• previousSnapshot

và sinh ra:

• editor_feature_collection
• entities
• geometries
• geometry_entity
• wikis
• entity_wiki
• replays

Các điểm quan trọng:

• geometry many-to-many với entity được persist ở geometry_entity[]
• denormalized fields trên feature như entity_ids, entity_name, binding, time_start sẽ bị strip khỏi editor_feature_collection trước khi gửi API
• wiki/entity/link được chuẩn hóa lại thành reference, binding, delete, create, update tùy baseline
• replay script được persist ở replays[]; replayDraft không được gửi

7. Dirty state mà user nhìn thấy

Số ở nút Commit là pendingSaveCount.

Nó gồm:

• số geometry change thật
• cộng thêm 1 nếu entity dirty
• cộng thêm 1 nếu wiki dirty
• cộng thêm 1 nếu entity-wiki dirty
• cộng thêm 1 nếu replay dirty

Vì vậy:

• Commit (3) không có nghĩa là backend sẽ nhận đúng 3 record thay đổi
• nó là chỉ báo "có bao nhiêu nhóm thay đổi cần commit"

8. Những gì workflow hiện chưa làm

Editor hiện chưa có các behavior sau:

• autosave local draft toàn project
• collaborative locking nhiều user ở FE
• review UI cho Approved/Rejected
• restore head commit trên backend từ trang editor
• branch/merge nhiều phiên edit song song