Thuộc Tài Liệu API — EP-04: Quy hoạch & Ban hành

API Chi Tiết — EP-04: Quy Hoạch & Ban Hành

Use Cases: UC-PLAN-001, UC-PLAN-002 Module: module-planning

---

Chốt Chủ Quản (Bảng D)

GET /api/v1/planning/ownership-summary

Mục đích: Xem tổng hợp bản đồ hiện trạng cho phê duyệt — danh sách Data Element với đề xuất chủ quản.

Tham chiếu: UC-PLAN-001, Feature EP-04-001

Phân quyền: Role: Approver

Query Parameters:

Parameter	Kiểu	Mô tả
domainId	Long	Lọc theo Domain
ownerStatus	String	PROPOSED, FINALIZED, NO_OWNER
page, size, sort	—	Phân trang chuẩn

Response 200:

{
  "success": true,
  "data": {
    "items": [
      {
        "dataElement": {
          "id": 101,
          "code": "DE001-DM1.1",
          "name": "Số CCCD",
          "domain": "Con người",
          "subDomain": "Định danh"
        },
        "proposedOwner": {
          "orgId": 1,
          "orgName": "Công an TP",
          "unitId": 11,
          "unitName": "Phòng CS QLHC về TTXH",
          "unitCode": "ID01.01.01"
        },
        "overlapOrgs": [
          { "orgId": 1, "orgName": "Công an TP" },
          { "orgId": 6, "orgName": "BHXH" },
          { "orgId": 5, "orgName": "Sở Y tế" }
        ],
        "overlapCount": 3,
        "status": "PROPOSED"
      },
      {
        "dataElement": {
          "id": 301,
          "code": "DE001-DM3.1",
          "name": "Mã thửa đất"
        },
        "proposedOwner": null,
        "overlapOrgs": [],
        "overlapCount": 0,
        "status": "NO_OWNER"
      }
    ],
    "meta": { "page": 0, "size": 20, "totalElements": 500 },
    "summary": {
      "totalDe": 500,
      "proposed": 450,
      "finalized": 0,
      "noOwner": 50
    }
  }
}

---

POST /api/v1/planning/finalize-ownership

Mục đích: Approver chốt đơn vị chủ quản duy nhất cho mỗi Data Element (Bảng D). Gán đến cấp Phòng/Ban (mã IDxx.xx.xx).

Tham chiếu: UC-PLAN-001, Feature EP-04-001

Phân quyền: - Role: Approver - State Guard: Bảng C phải đã APPROVED

Request Body:

{
  "note": "Chốt chủ quản dựa trên bản đồ hiện trạng đã được xác nhận",
  "overrides": [
    {
      "dataElementId": 205,
      "ownerUnitId": 31,
      "reason": "Chuyển chủ quản từ Sở TC sang Cục Thuế theo đề xuất Ban QT DL"
    }
  ]
}

Business Rules: - Bảng C phải đã APPROVED → 422 nếu chưa - Mỗi DE chỉ có 1 chủ quản (quy tắc 1:1) - DE không có Sở nào lưu trữ → owner = NULL, đánh dấu "Dữ liệu cần xây dựng mới" - Trạng thái chuyển sang APPROVED

Response 200:

{
  "success": true,
  "data": {
    "status": "APPROVED",
    "totalDe": 500,
    "finalizedWithOwner": 450,
    "noOwner": 50,
    "overrideCount": 1,
    "approvedAt": "2026-04-08T17:00:00+07:00",
    "approvedBy": "uuid-approver"
  }
}

---

PATCH /api/v1/planning/reject-to-manager

Mục đích: Approver từ chối, trả về Manager để rà soát lại.

Phân quyền: Role: Approver

Request Body:

{
  "reason": "Cần rà soát lại chủ quản cho Domain Y tế — nhiều DE chưa rõ đơn vị"
}

Validation: reason bắt buộc.

Response 200: Trạng thái quay về IN_REVIEW.

---

Ban Hành Từ Điển

GET /api/v1/planning/publish-ready

Mục đích: Danh sách Data Element sẵn sàng ban hành (đã APPROVED, có chủ quản).

Tham chiếu: UC-PLAN-002, Feature EP-04-002

Phân quyền: Role: Approver

Response 200:

{
  "success": true,
  "data": {
    "readyCount": 450,
    "notReadyCount": 50,
    "notReadyReasons": {
      "noOwner": 50
    },
    "lastApprovedAt": "2026-04-08T17:00:00+07:00"
  }
}

---

POST /api/v1/planning/publish

Mục đích: Ban hành Từ điển Dữ liệu chính thức. Chuyển trạng thái APPROVED → PUBLISHED.

Phân quyền: - Role: Approver - State Guard: Phải đã APPROVED (Bảng D đã chốt)

Request Body:

{
  "note": "Ban hành Từ điển Dữ liệu Thành phố phiên bản 1.0"
}

Response 200:

{
  "success": true,
  "data": {
    "status": "PUBLISHED",
    "publishedCount": 450,
    "publishedAt": "2026-04-08T18:00:00+07:00",
    "publishedBy": "uuid-approver"
  }
}

Ghi chú: Sau khi PUBLISHED, Từ điển khả dụng cho tra cứu qua EP-05.

---

GET /api/v1/planning/publish-status

Mục đích: Trạng thái ban hành hiện tại.

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

Response 200:

{
  "success": true,
  "data": {
    "currentStatus": "PUBLISHED",
    "totalDe": 500,
    "publishedDe": 450,
    "draftDe": 50,
    "lastPublishedAt": "2026-04-08T18:00:00+07:00"
  }
}

---

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