temp-history-api/api.md

# API - Ultimate History Map (Backend)

Tài liệu này mô tả backend API theo đúng hành vi hiện tại của code trong `BackEnd/index.js` và `BackEnd/routes/*`.

- Backend: Express
- Base URL local (hardcode): `http://localhost:3000`
- DB nghiệp vụ: SQLite `BackEnd/data/polygons.db`
- Tile data: MBTiles `BackEnd/data/map.mbtiles` (vector) và `BackEnd/data/raster.mbtiles` (raster)
- Auth/permission: chưa có
- CORS: mở toàn bộ (`cors()`)
- Update: 2026-04-21

## 1. Envelope Response (Rất Quan Trọng)

Mọi endpoint JSON được mount qua `envelopeResponses` sẽ trả về envelope:

```json
{
  "status": "success",
  "data": {},
  "message": "OK",
  "errors": []
}
```

Khi lỗi (`HTTP >= 400`), envelope:

```json
{
  "status": "error",
  "data": null,
  "message": "Some message",
  "errors": ["Some message"]
}
```

Quy tắc bọc envelope hiện tại:

- Nếu handler `res.json({ error: "..." })` thì `message/errors` sẽ lấy từ `error`.
- Nếu handler `res.json({ message: "..." })` thì `message/errors` sẽ lấy từ `message`.
- Nếu handler trả `res.json([...])` hoặc `res.json({ ...domain... })` thì payload nằm trong `data`.

Ngoại lệ KHÔNG envelope:

- `GET /` trả plain text.
- `GET /docs` trả Swagger UI (HTML).
- `GET /docs.json` trả raw OpenAPI JSON (không bọc envelope).
- Tile binary `GET /tiles/:z/:x/:y`, `GET /raster-tiles/:z/:x/:y` trả binary khi success (vì dùng `res.send`). Các lỗi tile (400/404) vẫn là JSON nên vẫn bị bọc envelope.

## 2. Actor (user_id) Và “anonymous”

Backend có cơ chế normalize actor:

- Đọc actor từ body/query/header tùy endpoint (`user_id`, `user`, `created_by`, `submitted_by`, `reviewed_by`, header `x-user-id`).
- Hiện tại `normalizeActor()` luôn fallback sang chuỗi `"anonymous"` nếu thiếu.

Hệ quả:

- Thực tế các field actor **không bắt buộc** (dù code có vài chỗ check `"… is required"` nhưng check đó gần như không bao giờ nổ do luôn fallback `"anonymous"`).
- Lock/ownership khi thiếu actor sẽ bị “dính” vào cùng một user `"anonymous"` (dễ gây va chạm).

Khuyến nghị cho FE/clients: luôn gửi một actor id ổn định (ví dụ user id) để lock và audit có ý nghĩa.

## 3. System API

### `GET /`

Health check.

- `200` (text): `GIS server running`

### `GET /docs`

Swagger UI.

### `GET /docs.json`

OpenAPI JSON (raw, không envelope).

## 4. Tile API (MBTiles)

### `GET /tiles/metadata/info`

Vector MBTiles metadata từ `map.mbtiles` (table `metadata`).

- `200` JSON envelope, trong `data` là object key/value metadata.

### `GET /tiles/:z/:x/:y`

Vector tile binary (XYZ -> TMS).

Luồng xử lý:

1. Parse `z/x/y` thành integer; sai -> `400`.
2. Convert `y` từ XYZ sang TMS: `tmsY = (1 << z) - 1 - y`.
3. Query `tiles` table theo `(zoom_level, tile_column, tile_row)`.
4. Không có row -> `404`.
5. Set header:
   - `Content-Type` dựa trên `metadata.format` (`pbf` -> `application/x-protobuf`).
   - Nếu format `pbf` thì set `Content-Encoding: gzip` (tile data trong MBTiles thường đã gzip sẵn).
6. `res.send(tile_data)` (binary).

### `GET /raster-tiles/metadata/info`

Raster MBTiles metadata từ `raster.mbtiles`.

- `200` JSON envelope, `data` là metadata object.

### `GET /raster-tiles/:z/:x/:y`

Raster tile binary (XYZ -> TMS).

Luồng xử lý tương tự `/tiles/:z/:x/:y`, khác ở `Content-Type`:

- `png` -> `image/png`
- `jpg|jpeg` -> `image/jpeg`
- `webp` -> `image/webp`
- khác -> `application/octet-stream`

## 5. Published Entity API (Read-only)

Published entities lấy từ table `entities` với filter `is_deleted = 0`.

### Entity Object (trong envelope `data`)

```json
{
  "id": "entity-id",
  "name": "Vietnam",
  "slug": "vietnam",
  "description": null,
  "type_id": "country",
  "status": 1,
  "created_at": "2026-04-17T10:00:00.000Z",
  "updated_at": "2026-04-17T10:00:00.000Z",
  "geometry_count": 3
}
```

### `GET /entities?q=...`

List entities, optional search theo `name` hoặc `slug` bằng `LIKE`.

Luồng xử lý:

1. `q` được trim; nếu rỗng thì list toàn bộ.
2. Query `entities` + LEFT JOIN `entity_geometries` để tính `geometry_count`.
3. Sort theo `name COLLATE NOCASE ASC`.

### `GET /entities/search?name=...&limit=...`

Search entity theo `name` bằng `LIKE`.

Luồng xử lý:

1. `name` rỗng -> trả `[]`.
2. `limit` default `25`, max `100`.
3. Query `entities` + LEFT JOIN `entity_geometries` để tính `geometry_count`.

### `GET /entities/:id`

Luồng xử lý:

1. Query entity theo `id` và `is_deleted = 0`.
2. Không tồn tại -> `404` (`error: "Entity not found"`).

## 6. Published Geometry API (Read-only)

Published geometries lấy từ table `geometries` với filter `is_deleted = 0`.

### `GET /geometries`

Query geometries theo bbox/time/entity.

Query params:

| Field | Bắt buộc | Type | Ghi chú |
| --- | ---: | --- | --- |
| `minLng` | Có | number | bbox min longitude |
| `minLat` | Có | number | bbox min latitude |
| `maxLng` | Có | number | bbox max longitude |
| `maxLat` | Có | number | bbox max latitude |
| `time` | Không | number | parse int; filter temporal range |
| `entity_id` | Không | string | lọc geometry có link entity này |

Luồng xử lý:

1. Validate bbox là số hữu hạn; fail -> `400` (`Missing/invalid bbox`).
2. Nếu có `time` (không rỗng) thì parse số; fail -> `400` (`Invalid time`).
3. Query geometries theo:
   - bbox intersects
   - nếu có `time` thì pass khi:
     - `time_start` null hoặc `time_start <= time`
     - `time_end` null hoặc `time_end >= time`
   - nếu có `entity_id` thì dùng `EXISTS` trên `entity_geometries` + `entities.is_deleted = 0`
4. Load links entity cho các geometry id trả về, giữ thứ tự theo `entity_geometries.rowid ASC`.
5. Build GeoJSON FeatureCollection:
   - `feature.geometry` parse từ `geometries.draw_geometry` (JSON string).
   - `properties.binding` được parse/normalize từ `geometries.binding` (JSON string hoặc fallback).
   - `properties.entity_ids/entity_names/...` dựa trên link table.
   - `properties.type`:
     - ưu tiên `geometries.type` nếu khác null và không phải legacy `line|path`
     - nếu legacy `line|path` thì fallback sang `entities.type_id` của primary entity.

### Geometry Feature (trong envelope `data`)

```json
{
  "type": "Feature",
  "properties": {
    "id": "geometry-id",
    "type": "country",
    "time_start": 1802,
    "time_end": 1884,
    "binding": [],
    "entity_id": "entity-id",
    "entity_ids": ["entity-id"],
    "entity_name": "Vietnam",
    "entity_names": ["Vietnam"],
    "entity_type_id": "country"
  },
  "geometry": { "type": "Polygon", "coordinates": [] }
}
```

## 7. Section Workflow API (Write path chính)

Không có API mutate trực tiếp published `entities/geometries`. Mọi thay đổi đi qua section workflow:

1. Editor mở section (`GET /sections/:id/editor`) để lấy snapshot và lock.
2. Editor commit snapshot (`POST /sections/:id/commits` hoặc `/restore`).
3. Editor submit head (`POST /sections/:id/submit`) -> tạo submission pending.
4. Reviewer approve/reject (`POST /submissions/:id/...`).
5. Chỉ approve mới apply snapshot vào published tables.

### 7.1. Data Model (khái niệm)

- `sections`: metadata của draft space.
- `section_states`: trạng thái và lock, version, head commit.
- `section_commits`: lịch sử snapshot (không apply).
- `section_submissions`: snapshot pending/review.

Status:

- `section_states.status`: `editing | submitted | approved | rejected`
- `section_submissions.status`: `pending | approved | rejected | conflicted`

Lock:

- TTL 15 phút (`LOCK_TTL_MS = 15 * 60 * 1000`).
- Lock được check theo `locked_by` và `lock_expires_at`.

Optimistic concurrency:

- Client có thể gửi `expected_version` và/hoặc `expected_head_commit_id` khi commit/restore.
- Sai -> `409` (`Section version changed` / `Section head commit changed`).

### 7.2. `GET /sections`

List sections + state (LEFT JOIN). Sort `sections.updated_at DESC`.

### 7.3. `POST /sections`

Tạo section và tạo luôn state (status `editing`, version `0`).

Luồng xử lý:

1. Validate `title` là string non-empty (trim). Sai -> `400` (`title is required`).
2. `id` nếu thiếu thì server tự sinh UUID.
3. Insert vào `sections`.
4. `ensureSectionState(section_id)` (insert `section_states` nếu chưa có).
5. SQLite constraint (trùng id) -> `409` (`Section id already exists`).

### 7.4. `GET /sections/:sectionId/editor`

Mở editor và (có side-effect) acquire lock.

Actor lấy từ query/header:

- `?user_id=...` hoặc `?user=...`
- header `x-user-id`

Luồng xử lý (transaction):

1. Load section; không có -> `404` (`Section not found`).
2. `ensureSectionState`.
3. `assertLockAvailable(state, actor, now)`:
   - OK nếu chưa lock, hoặc lock bởi chính actor, hoặc lock đã expire.
   - Fail -> `409` (`Section is locked by another user`).
4. Acquire/refresh lock cho actor (set `locked_by/locked_at/lock_expires_at`).
5. Nếu có `head_commit_id` thì load commit đó.
6. Response:
   - `section`: object normalized
   - `state`: object normalized
   - `commit`: normalized commit (không include snapshot)
   - `snapshot`:
     - nếu có head commit: parse `snapshot_json`
     - nếu chưa có commit: trả empty snapshot `{ schema_version, section, entities:[], geometries:[], link_scopes:[] }`

Ghi chú: vì actor fallback `"anonymous"`, gọi endpoint này mà không gửi user id vẫn tạo lock (locked_by = `"anonymous"`).

### 7.5. `POST /sections/:sectionId/lock`

Acquire/refresh lock (tách riêng, không trả snapshot).

Luồng xử lý:

1. Load section; không có -> `404`.
2. `ensureSectionState`.
3. `assertLockAvailable`.
4. Acquire lock và trả `state`.

### 7.6. `POST /sections/:sectionId/unlock`

Release lock.

Luồng xử lý:

1. Load section; không có -> `404`.
2. `ensureSectionState`.
3. Nếu `state.locked_by` tồn tại và khác actor hiện tại -> `409` (`Section is locked by another user`).
4. Clear lock fields.

### 7.7. `GET /sections/:sectionId/commits?include_snapshot=1`

List commit history (sort `commit_no DESC`).

- `include_snapshot=1|true` -> mỗi commit có thêm `snapshot` (parsed JSON).

### 7.8. `POST /sections/:sectionId/commits`

Tạo commit mới từ snapshot editor.

Body:

- `snapshot` (object) hoặc `snapshot_json` (string JSON) là bắt buộc.
- Actor thường gửi qua `created_by` hoặc `user_id` hoặc header `x-user-id`.
- Optional:
  - `expected_version`
  - `expected_head_commit_id`
  - `title`, `note`

Luồng xử lý (transaction):

1. Load section; không có -> `404`.
2. Normalize snapshot input:
   - `snapshot_json` không parse được -> `400` (`snapshot_json must be valid JSON`)
   - thiếu snapshot -> `400` (`snapshot is required`)
3. `ensureSectionState`.
4. `assertCanEdit`:
   - status phải là `editing` hoặc `rejected`, không thì `409` (`Section is not editable`)
   - lock phải available, không thì `409` (`Section is locked by another user`)
5. `assertExpectedState` nếu client có gửi expected fields.
6. `validateSnapshot`:
   - contract level (bắt buộc có `snapshot.section.id/title`, entity/geometry ids, link_scope shape)
   - rule bổ sung: name required (trừ delete/reference), slug không trùng (case-insensitive), time range hợp lệ, bbox nếu có phải hợp lệ, binding không chứa self id, link_scope entity_ids không rỗng.
7. Insert `section_commits`:
   - `parent_commit_id = state.head_commit_id`
   - `commit_no` auto tăng
   - `snapshot_hash = sha256(JSON)`
8. Update `section_states`:
   - `status = 'editing'`
   - `head_commit_id = newCommitId`
   - `version = version + 1`
9. Update `sections.updated_at`.

Response `201`: `{ commit, state }` (commit có `snapshot`).

### 7.9. `POST /sections/:sectionId/restore`

Restore một commit cũ bằng cách tạo commit mới `kind = "restore"`.

Luồng xử lý giống `/commits` nhưng snapshot lấy từ commit nguồn:

1. Validate `commit_id`/`restore_commit_id`; thiếu -> `400` (`commit_id is required`).
2. Check commit nguồn thuộc section; không có -> `404` (`Commit not found`).
3. Insert commit mới với `restored_from_commit_id = source.id`.
4. Update head commit + bump version.

### 7.10. `POST /sections/:sectionId/submit`

Submit head commit hiện tại -> tạo submission pending, set state `submitted`, release lock.

Luồng xử lý (transaction):

1. Load section; không có -> `404`.
2. `ensureSectionState`.
3. `assertLockAvailable` (chỉ check không bị user khác lock).
4. status phải là `editing`, không thì `409` (`Section is not editable`).
5. `head_commit_id` phải có, không thì `400` (`Section has no head commit to submit`).
6. Load commit head; không có -> `404` (`Commit not found`).
7. Insert `section_submissions` (status `pending`) copy snapshot từ commit head.
8. Update `section_states`:
   - `status = 'submitted'`
   - clear lock fields.

Response `201`: `SectionSubmission` (có `snapshot`).

### 7.11. `GET /sections/:sectionId/submissions?include_snapshot=1`

List submission history của section (sort `submitted_at DESC`).

## 8. Review API (`/submissions`)

Review endpoints được mount “public” qua `/submissions` nhưng implementation nằm trong `BackEnd/routes/sections.js`:

- `POST /submissions/:submissionId/approve`
- `POST /submissions/:submissionId/reject`

### 8.1. `POST /submissions/:submissionId/reject`

Luồng xử lý (transaction):

1. Load submission; không có -> `404` (`Submission not found`).
2. Submission phải `pending`, không thì `409` (`Submission is not pending`).
3. Update submission:
   - `status = rejected`
   - set `reviewed_by/reviewed_at/review_note`
4. Update `section_states.status = rejected`.
5. Không apply published tables.

Response `200`: `SectionSubmission` (có `snapshot`).

### 8.2. `POST /submissions/:submissionId/approve`

Luồng xử lý (transaction):

1. Load submission; không có -> `404`.
2. Submission phải `pending`, không thì `409`.
3. Verify snapshot hash:
   - nếu `submission.snapshot_hash` tồn tại và khác `sha256(submission.snapshot_json)` -> `409` (`Submission snapshot hash mismatch`).
4. Parse snapshot JSON.
5. `applySnapshotToPublished(snapshot, now)` theo thứ tự:
   - apply `entities`
   - apply `geometries`
   - apply `link_scopes` (replace links)
6. Update submission:
   - `status = approved`
   - set `reviewed_by/reviewed_at/review_note`
7. Update `section_states.status = approved`.

Conflict handling đặc biệt:

- Nếu trong lúc apply snapshot phát hiện conflict (409) thì backend:
  - (best-effort) update `section_submissions.status = conflicted` và set `review_note = <conflict message>` nếu submission vẫn còn `pending`.
  - trả `409` cho client.

## 9. Snapshot Format Và Apply Semantics

Commit/submission snapshot là full JSON object. Backend quan tâm các mảng:

- `entities[]`
- `geometries[]`
- `link_scopes[]`

Ngoài ra FE có thể kèm `editor_feature_collection` để preview (backend chỉ normalize, không apply vào DB).

### 9.1. Snapshot Shape (rút gọn)

```json
{
  "schema_version": 1,
  "section": { "id": "section-id", "title": "Section title" },
  "editor_feature_collection": { "type": "FeatureCollection", "features": [] },
  "entities": [],
  "geometries": [],
  "link_scopes": []
}
```

Operations (case-insensitive):

- `create | update | delete | reference | replace`
- `replace` được normalize thành `update` cho entity/geometry.

### 9.2. Validate Snapshot (400)

Backend validate ở `/commits` và trước khi approve:

- `snapshot.section.id` và `snapshot.section.title` bắt buộc.
- Mỗi entity/geometry trong snapshot bắt buộc có `id` và `operation` hợp lệ.
- Entity:
  - `name` bắt buộc nếu không phải `delete|reference`
  - `slug` (nếu có) không được trùng trong cùng snapshot (case-insensitive)
- Geometry:
  - nếu `create|update|replace` thì bắt buộc có `draw_geometry` hoặc `geometry`
  - nếu có cả `time_start/time_end` thì `time_start <= time_end`
  - `bbox` nếu gửi thì phải hợp lệ; nếu không gửi, approve sẽ tự tính bbox từ geometry
  - `binding` không được chứa chính `geometry.id`
- Link scope:
  - `geometry_id` bắt buộc, `entity_ids` phải là array
  - `entity_ids` sau normalize không được rỗng

### 9.3. Apply Snapshot (Approve)

#### Entities

- `create`: INSERT `entities` (type_id default `"country"` nếu thiếu), `created_at/updated_at = now`.
- `update|replace`: UPDATE toàn bộ fields; có thể check conflict bằng `base_updated_at` và/hoặc `base_hash` (nếu snapshot item gửi).
- `delete`: set `entities.is_deleted = 1`, xóa mọi link trong `entity_geometries`.
- `reference`: bỏ qua.

#### Geometries

- `create`: INSERT `geometries`:
  - `draw_geometry` được stringify JSON
  - `bbox`: nếu snapshot có `bbox` hợp lệ thì dùng, nếu không thì compute bằng `getBBox(draw_geometry)`
  - `binding`: normalize array id và tự loại self id
- `update|replace`: UPDATE toàn bộ fields tương tự create (có check conflict bằng base fields).
- `delete`:
  - set `geometries.is_deleted = 1`
  - delete links trong `entity_geometries` theo `geometry_id`
  - remove mọi reference tới geometry đó trong `binding` của các geometry khác.
- `reference`: bỏ qua.

#### Link scopes (replace entity links theo geometry)

- Geometry phải tồn tại và `is_deleted = 0`, nếu không -> conflict (409).
- `entity_ids` không rỗng, và mọi entity id phải tồn tại + `is_deleted = 0`, nếu không -> `400`.
- Nếu snapshot gửi `base_links_hash`:
  - backend hash current links (sorted by entity_id) và so sánh; mismatch -> conflict (409).
- Apply bằng cách:
  - `DELETE FROM entity_geometries WHERE geometry_id = ?`
  - rồi `INSERT` lại toàn bộ link theo thứ tự `entity_ids` gửi lên.

### 9.4. Conflict Semantics (409)

Nhóm lỗi conflict (status 409, `err.isConflict = true`) xảy ra khi approve apply:

- Update/delete entity/geometry nhưng record không tồn tại.
- `base_updated_at` mismatch hoặc `base_hash` mismatch.
- Link scope geometry không tồn tại/đã deleted.
- `base_links_hash` mismatch.

## 10. Status Code Summary

| Status | Khi nào |
| --- | --- |
| `200` | OK (read/review) |
| `201` | Created (section/commit/restore/submit) |
| `400` | Query/body/snapshot không hợp lệ |
| `404` | Resource không tồn tại |
| `409` | Lock conflict, stale version/head, state không editable, conflict khi apply, hoặc DB constraint |
| `500` | Lỗi server |

## 11. Luồng Tham Chiếu (End-to-End)

### 11.1. Editor Flow

1. List section: `GET /sections`.
2. Open editor (và lock): `GET /sections/:sectionId/editor?user_id=<actor>`.
3. User edit local -> tạo snapshot.
4. Commit: `POST /sections/:sectionId/commits` (khuyến nghị gửi `expected_version` + `expected_head_commit_id` từ state).
5. (Optional) Restore: `POST /sections/:sectionId/restore`.
6. Submit: `POST /sections/:sectionId/submit`.

### 11.2. Reviewer Flow

1. List sections: `GET /sections`.
2. Với từng section: `GET /sections/:sectionId/submissions?include_snapshot=1`.
3. Approve/reject:
   - `POST /submissions/:submissionId/approve`
   - `POST /submissions/:submissionId/reject`

## 12. Giới Hạn / “Gotchas” Hiện Tại

- Không có auth/permission.
- Actor fallback `"anonymous"` làm “required actor” không thực sự enforced; lock và audit dễ sai nếu client không gửi user id.
- `GET /sections/:id/editor` luôn acquire lock (side-effect). Nếu bạn chỉ muốn đọc snapshot mà không lock, hiện chưa có endpoint riêng.
- Không có pagination cho list sections/commits/submissions.
- Reviewer UI nếu cần list submissions toàn cục: hiện chưa có endpoint `GET /submissions` (phải gom theo section).
- Conflict protection (`base_hash/base_updated_at/base_links_hash`) chỉ hiệu quả nếu FE gửi các field này.