Tài Liệu API — GovData: Nền Tảng Quản Lý, Quản Trị Dữ Liệu Thành Phố¶

Phiên bản: 1.1 Ngày tạo: 2026-04-08 Trạng thái: Draft — Chờ Tech Lead xác nhận Nguồn: Phương Án Kỹ Thuật, Epics, Use Cases, Role Matrix

Mục Lục¶

...

1. Tổng Quan & Quy Ước API¶

Thông Tin Chung¶

2. Danh Sách API Tổng Hợp¶

EP-03: Khám Phá, Đối Chiếu & Ma Trận Hiện Trạng¶

#	Method	Endpoint	Mục đích	Vai trò	UC
...
49	GET	`/source-mappings/matrix`	Ma trận Source Mapping (DE × Đơn vị)	Manager, Approver	UC-MAP-003
50	GET	`/source-mappings/matrix/my-org`	Chỉ xem ma trận đơn vị mình (read-only)	Data Owner	UC-CONFIRM-001
51	PATCH	`/source-mappings/confirm-batch`	Data Owner xác nhận batch	Data Owner	UC-CONFIRM-002
52	PATCH	`/source-mappings/reject-batch`	Data Owner từ chối batch	Data Owner	UC-CONFIRM-002
53	PATCH	`/source-mappings/{id}/dispute`	Đánh dấu DISPUTED (lý do ≥ 20 ký tự)	Data Owner, Manager	UC-CONFIRM-003
54	GET	`/source-mappings/disputed`	Danh sách ô DISPUTED	Manager, Approver	UC-CONFIRM-003/004
55	PATCH	`/source-mappings/{id}/resolve`	Giải quyết DISPUTED (3 hướng)	Approver	UC-CONFIRM-004
56	POST	`/source-mapping-approval/approve`	Phê duyệt Ma trận Hiện trạng tổng thể	Approver	UC-CONFIRM-005
57	GET	`/source-mapping-approval/status`	Trạng thái phê duyệt (% xác nhận, số DISPUTED)	Manager, Approver	UC-CONFIRM-005
58	POST	`/source-mapping-approval/{id}/revoke`	Thu hồi bản phê duyệt hiện tại	Approver	UC-CONFIRM-005
59	GET	`/source-mapping-approval/history`	Lịch sử phê duyệt	Manager, Approver	UC-CONFIRM-005

Chi tiết: api-specs/ep-03-discovery-matching.md

4. Phân Loại Lỗi¶

Error Taxonomy¶

... | business_rule_error | 422/409 | Vi phạm quy tắc nghiệp vụ | DISPUTED note < 20 ký tự, phê duyệt khi còn DISPUTED | ...

Ví Dụ Error Response¶

Business Rule Error (409 Conflict):

{
  "success": false,
  "error": {
    "type": "BUSINESS_ERROR",
    "code": "SOURCE_MAPPING_APPROVAL_DISPUTED_REMAINING",
    "message": "Cannot approve source mapping: there are unresolved DISPUTED cells",
    "details": {
      "disputedCount": 3,
      "confirmedOrgsPercent": 85,
      "requiredPercent": 70
    }
  },
  "timestamp": "2026-04-19T14:30:00Z",
  "traceId": "abc-456"
}

Business Rule Error Codes Đặc Thù¶

Code	Mô tả	Endpoint liên quan
`DISPUTED_NOTE_TOO_SHORT`	Ghi chú tranh chấp < 20 ký tự	PATCH /source-mappings/{id}/dispute
`SOURCE_MAPPING_APPROVAL_DISPUTED_REMAINING`	Còn ô DISPUTED khi phê duyệt	POST /source-mapping-approval/approve
`SOURCE_MAPPING_APPROVAL_INSUFFICIENT_CONFIRMATION`	< 70% đơn vị xác nhận	POST /source-mapping-approval/approve
...

7. Idempotency & Reliability¶

Idempotency Guard Ví Dụ¶

Phê duyệt Ma Trận Hiện Trạng — Không phê duyệt 2 lần:

-- Guard: kiem tra trang thai truoc khi chuyen
INSERT INTO source_mapping_approval (...)
SELECT ... FROM source_mapping
WHERE NOT EXISTS (SELECT 1 FROM source_mapping_approval WHERE status = 'APPROVED');

Cập nhật lần cuối: 2026-04-19