Thuộc Tài Liệu API — EP-05: Từ điển Dữ liệu & Hoạch định Tương lai

API Chi Tiết — EP-05: Từ Điển Dữ Liệu & Hoạch Định Tương Lai

Use Cases: UC-DICT-001, UC-DICT-002, UC-FUTURE-001 Module: module-dictionary

---

Tra Cứu Data Element

GET /api/v1/dictionary/search

Mục đích: Tìm kiếm Data Element đã quy hoạch bằng từ khóa. Full-text search hỗ trợ tiếng Việt.

Tham chiếu: UC-DICT-001, Feature EP-05-001

Phân quyền: Role: Staff, Data Owner, Manager, Approver (tất cả user có quyền)

Query Parameters:

Parameter	Kiểu	Bắt buộc	Mô tả
q	String	Có	Từ khóa tìm kiếm (tên, mô tả, synonym)
domainId	Long	Không	Lọc theo Domain
status	String	Không	Mặc định: PUBLISHED
page, size	—	Không	Phân trang (mặc định size=20)

Response 200:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 101,
        "code": "DE001-DM1.1",
        "name": "Số CCCD",
        "description": "Số căn cước công dân 12 số",
        "dataType": "VARCHAR(12)",
        "domain": "Con người",
        "subDomain": "Định danh",
        "owner": {
          "orgName": "Công an TP",
          "unitName": "Phòng CS QLHC về TTXH",
          "unitCode": "ID01.01.01"
        },
        "synonyms": ["so_cccd", "cccd_number", "citizen_id"],
        "status": "PUBLISHED",
        "searchScore": 0.95
      }
    ],
    "meta": { "page": 0, "size": 20, "totalElements": 3 }
  }
}

---

GET /api/v1/dictionary/data-elements/{id}

Mục đích: Xem chi tiết một Data Element (mô tả, kiểu dữ liệu, chủ quản, hệ thống chứa).

Tham chiếu: UC-DICT-001, Feature EP-05-001

Phân quyền: Role: Staff, Data Owner, Manager, Approver

Response 200:

{
  "success": true,
  "data": {
    "id": 101,
    "code": "DE001-DM1.1",
    "name": "Số CCCD",
    "description": "Số căn cước công dân 12 số, do Bộ Công an cấp",
    "dataType": "VARCHAR(12)",
    "domain": { "id": 1, "code": "DM1", "name": "Con người" },
    "subDomain": { "id": 11, "code": "DM1.1", "name": "Định danh" },
    "owner": {
      "orgId": 1,
      "orgName": "Công an TP",
      "unitId": 11,
      "unitName": "Phòng CS QLHC về TTXH",
      "unitCode": "ID01.01.01"
    },
    "storedAt": [
      { "orgId": 1, "orgName": "Công an TP" },
      { "orgId": 6, "orgName": "BHXH" },
      { "orgId": 5, "orgName": "Sở Y tế" }
    ],
    "synonyms": ["so_cccd", "cccd_number", "citizen_id", "cmnd"],
    "status": "PUBLISHED",
    "publishedAt": "2026-04-08T18:00:00+07:00"
  }
}

---

Tra Cứu Theo Domain & Cây Tổ Chức

GET /api/v1/dictionary/browse/domains

Mục đích: Duyệt Từ điển theo cấu trúc cây Domain → Sub Domain → Data Element.

Tham chiếu: UC-DICT-002, Feature EP-05-002

Phân quyền: Role: Staff, Data Owner, Manager, Approver

Query Parameters:

Parameter	Kiểu	Mô tả
domainId	Long	Xem chi tiết Domain cụ thể (nếu không truyền → xem tất cả)
expandLevel	Integer	Mức mở rộng cây: 1=Domain, 2=+SubDomain, 3=+DE (mặc định: 2)

Response 200:

{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "DM1",
      "name": "Con người",
      "type": "DOMAIN",
      "deCount": 120,
      "children": [
        {
          "id": 11,
          "code": "DM1.1",
          "name": "Định danh",
          "type": "SUB_DOMAIN",
          "deCount": 15,
          "children": []
        }
      ]
    }
  ]
}

---

GET /api/v1/dictionary/browse/org-tree

Mục đích: Duyệt Từ điển theo cây tổ chức — xem đơn vị nào quản lý Data Element nào.

Tham chiếu: UC-DICT-002, Feature EP-05-002

Phân quyền: Role: Staff, Data Owner, Manager, Approver

Query Parameters:

Parameter	Kiểu	Mô tả
orgId	Long	Xem Data Elements thuộc đơn vị cụ thể

Response 200:

{
  "success": true,
  "data": [
    {
      "org": { "id": 1, "code": "ID01.01", "name": "Công an TP" },
      "units": [
        {
          "unit": { "id": 11, "code": "ID01.01.01", "name": "Phòng CS QLHC về TTXH" },
          "ownedDataElements": [
            { "id": 101, "code": "DE001-DM1.1", "name": "Số CCCD" },
            { "id": 102, "code": "DE002-DM1.1", "name": "Họ và tên" }
          ],
          "ownedCount": 25
        }
      ],
      "totalOwned": 45
    }
  ]
}

---

Hoạch Định Dữ Liệu Tương Lai

POST /api/v1/future-planning/data-elements

Mục đích: Tạo Data Element tương lai — dữ liệu hoạch định thu thập trong tương lai nhưng hiện chưa có.

Tham chiếu: UC-FUTURE-001, Feature EP-05-003

Phân quyền: Role: Manager

Request Body:

{
  "subDomainId": 12,
  "name": "Chỉ số BMI",
  "description": "Chỉ số khối cơ thể, hoạch định thu thập từ hệ thống y tế thông minh",
  "dataType": "DECIMAL",
  "justification": "Phục vụ chương trình chăm sóc sức khỏe cộng đồng giai đoạn 2027-2030",
  "targetYear": 2027
}

Response 201: Data Element tương lai đã tạo, trạng thái PENDING.

---

GET /api/v1/future-planning/data-elements

Mục đích: Danh sách Data Element tương lai.

Phân quyền: Role: Manager, Approver

Query Parameters: domainId, status (PENDING/APPROVED/REJECTED), page, size

---

PUT /api/v1/future-planning/data-elements/{id}

Mục đích: Cập nhật Data Element tương lai.

Phân quyền: Role: Manager

---

PATCH /api/v1/future-planning/data-elements/{id}/approve

Mục đích: Approver phê duyệt hoạch định tương lai.

Phân quyền: Role: Approver

Request Body:

{
  "note": "Phê duyệt, ghi nhận vào kế hoạch thu thập dữ liệu 2027"
}

Response 200: Trạng thái chuyển sang APPROVED.

---

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