docs: add comprehensive project documentation and clean up snapshot-related files and components
This commit is contained in:
taDuc
@@ -0,0 +1,182 @@
|
||||
# UHM map styling - hệ thống layer và style
|
||||
|
||||
Tài liệu này mô tả styling thật đang được map editor dùng.
|
||||
|
||||
## 1. Hai nhóm style chính
|
||||
|
||||
Map hiện có hai nhóm style tách biệt:
|
||||
|
||||
- background/base map style
|
||||
- geotype style cho dữ liệu editor
|
||||
|
||||
### Background/base map
|
||||
|
||||
Định nghĩa trong `useMapLayers.ts` qua `getBaseMapStyle()`.
|
||||
|
||||
### Geotype style
|
||||
|
||||
Định nghĩa trong `src/uhm/lib/map/styles/`.
|
||||
|
||||
## 2. Background layers đang có
|
||||
|
||||
Danh sách layer toggle được expose ở `backgroundLayers.ts`:
|
||||
|
||||
- `raster-base-layer`
|
||||
- `graticules-line`
|
||||
- `land`
|
||||
- `bg-countries-fill`
|
||||
- `bg-country-borders-line`
|
||||
- `country-labels`
|
||||
- `regions-line`
|
||||
- `lakes-fill`
|
||||
- `rivers-line`
|
||||
- `geolines-line`
|
||||
|
||||
Lưu ý:
|
||||
|
||||
- không phải layer nào trong list cũng nhất thiết được add từ cùng một source path trong tương lai
|
||||
- `BackgroundLayersPanel` chỉ biết toggle theo `id`
|
||||
|
||||
Visibility mặc định:
|
||||
|
||||
- tất cả `true`
|
||||
- được persist bằng `uhm.backgroundLayerVisibility.v1`
|
||||
|
||||
## 3. Geotype registry
|
||||
|
||||
Geotype render hiện được tập trung ở `getAllGeotypeLayers(...)` trong `geotypeLayers.ts`.
|
||||
|
||||
Các type đang được register:
|
||||
|
||||
- `defense_line`
|
||||
- `attack_route`
|
||||
- `retreat_route`
|
||||
- `invasion_route`
|
||||
- `migration_route`
|
||||
- `refugee_route`
|
||||
- `trade_route`
|
||||
- `shipping_route`
|
||||
- `country`
|
||||
- `state`
|
||||
- `empire`
|
||||
- `kingdom`
|
||||
- `war`
|
||||
- `battle`
|
||||
- `civilization`
|
||||
- `rebellion_zone`
|
||||
- `person_deathplace`
|
||||
- `person_birthplace`
|
||||
- `person_activity`
|
||||
- `temple`
|
||||
- `capital`
|
||||
- `city`
|
||||
- `fortress`
|
||||
- `castle`
|
||||
- `ruin`
|
||||
- `port`
|
||||
- `bridge`
|
||||
|
||||
`GEOMETRY_TYPE_OPTIONS` trong `geometryTypeOptions.ts` phải khớp với tập geotype này nếu muốn user chọn được từ UI.
|
||||
|
||||
## 4. Type matching
|
||||
|
||||
Style matcher trung tâm là:
|
||||
|
||||
- `TYPE_MATCH_EXPR = ["coalesce", ["get", "type"], ["get", "entity_type_id"], ""]`
|
||||
|
||||
Điều này cho phép layer match theo:
|
||||
|
||||
- `feature.properties.type`
|
||||
- fallback sang `entity_type_id` nếu cần
|
||||
|
||||
Với editor hiện tại, `type` là field chính.
|
||||
|
||||
## 5. Point, line, polygon và label sources
|
||||
|
||||
Map không render mọi thứ từ một source duy nhất theo nghĩa trực tiếp.
|
||||
Pipeline hiện tại tách ra:
|
||||
|
||||
- `countries`
|
||||
- polygon và line-like feature data
|
||||
- `places`
|
||||
- point data
|
||||
- `PATH_ARROW_SOURCE_ID`
|
||||
- arrow shapes cho route/path
|
||||
- `POLYGON_LABEL_SOURCE_ID`
|
||||
- polygon labels
|
||||
|
||||
Label layer cho polygon/line đi qua:
|
||||
|
||||
- `getAllGeotypeLabelLayers(...)`
|
||||
- helper trong `shared/polygonLabels.ts`
|
||||
- helper trong `shared/lineLabels.ts`
|
||||
|
||||
## 6. Icon point
|
||||
|
||||
Point geotype dùng icon pipeline trong:
|
||||
|
||||
- `shared/pointStyle.ts`
|
||||
- `ensurePointGeotypeIcons(map)`
|
||||
|
||||
Điều này có nghĩa là khi thêm geotype point mới, chỉ thêm layer là chưa đủ; cần chắc icon/style builder cũng hiểu type mới đó.
|
||||
|
||||
## 7. Preview và edit styling
|
||||
|
||||
Ngoài style dữ liệu chính, map còn có style riêng cho:
|
||||
|
||||
### Draw preview
|
||||
|
||||
- `draw-preview-fill`
|
||||
- `draw-preview-line`
|
||||
- `draw-circle-preview-fill`
|
||||
- `draw-circle-preview-line`
|
||||
- `draw-line-preview-line`
|
||||
- `draw-path-preview-line`
|
||||
- `draw-path-preview-arrows`
|
||||
|
||||
### Editing overlay
|
||||
|
||||
- `edit-shape-line`
|
||||
- `edit-handles-circle`
|
||||
|
||||
### Focus/highlight
|
||||
|
||||
- `entity-focus-fill`
|
||||
- `entity-focus-line`
|
||||
- `entity-focus-points`
|
||||
|
||||
Các layer này không đi qua geotype registry.
|
||||
|
||||
## 8. Visibility filtering
|
||||
|
||||
Có ba lớp filter hiển thị trong runtime:
|
||||
|
||||
1. background layer visibility
|
||||
2. geometry visibility theo type key từ panel phải
|
||||
3. binding filter / replay filter / timeline filter ở phía data trước khi set source
|
||||
|
||||
Vì vậy khi một geometry "không hiện", có thể nguyên nhân nằm ở data filtering chứ không phải style layer.
|
||||
|
||||
## 9. Thêm geotype mới - checklist đúng với code hiện tại
|
||||
|
||||
Nếu thêm một geotype mới, nên đi theo checklist này:
|
||||
|
||||
1. Thêm mapping vào `geoTypeMap` nếu backend dùng numeric/type code.
|
||||
2. Thêm option vào `geometryTypeOptions.ts`.
|
||||
3. Tạo file style mới trong `styles/geotypes/`.
|
||||
4. Register nó trong `getAllGeotypeLayers(...)`.
|
||||
5. Nếu cần label riêng, cập nhật layer builder tương ứng.
|
||||
6. Nếu là point type, kiểm tra icon pipeline.
|
||||
7. Nếu muốn user tạo geometry mới với type đó mặc định từ tool nào đó, cập nhật `useMapInteraction.ts`.
|
||||
|
||||
## 10. Điều doc cũ mô tả chưa chính xác
|
||||
|
||||
Doc cũ nói tới filter thời gian ở từng layer như một biểu thức layer-level chuẩn.
|
||||
Implementation hiện tại không làm vậy.
|
||||
|
||||
Thay vào đó:
|
||||
|
||||
- timeline filter đang chạy phía data trong `page.tsx`
|
||||
- binding filter và geometry visibility cũng chủ yếu chạy trước khi set source
|
||||
|
||||
Tức là phần lớn filtering là `prepare data -> set source`, không phải `add layer filter expression per year`.
|
||||
Reference in New Issue
Block a user