Thuộc Tài Liệu API — EP-06: Báo cáo & Thống kê

API Chi Tiết — EP-06: Báo Cáo & Thống Kê

Use Cases: UC-RPT-001, UC-RPT-002 Module: module-report

---

Báo Cáo Chồng Chéo & Phân Mảnh

GET /api/v1/reports/overlap

Mục đích: Báo cáo các Data Element đang bị lưu trùng tại nhiều đơn vị (chồng chéo).

Tham chiếu: UC-RPT-001, Feature EP-06-001

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

Query Parameters:

Parameter	Kiểu	Mô tả
domainId	Long	Lọc theo Domain
orgId	Long	Lọc theo đơn vị
minOverlap	Integer	Số đơn vị tối thiểu (mặc định: 2)
page, size, sort	—	Phân trang

Response 200:

{
  "success": true,
  "data": {
    "items": [
      {
        "dataElement": { "id": 101, "code": "DE001-DM1.1", "name": "Số CCCD" },
        "domain": "Con người",
        "overlapCount": 5,
        "organizations": [
          { "orgId": 1, "orgName": "Công an TP", "isOwner": true },
          { "orgId": 6, "orgName": "BHXH", "isOwner": false },
          { "orgId": 5, "orgName": "Sở Y tế", "isOwner": false },
          { "orgId": 2, "orgName": "Sở Tài chính", "isOwner": false },
          { "orgId": 3, "orgName": "Cục Thuế", "isOwner": false }
        ]
      }
    ],
    "meta": { "page": 0, "size": 20, "totalElements": 85 },
    "summary": {
      "totalOverlappedDe": 85,
      "avgOverlapCount": 3.2,
      "maxOverlapCount": 8
    }
  }
}

---

GET /api/v1/reports/fragmentation

Mục đích: Báo cáo các Data Element chỉ có ở một số ít đơn vị (phân mảnh).

Tham chiếu: UC-RPT-001, Feature EP-06-001

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

Query Parameters:

Parameter	Kiểu	Mô tả
domainId	Long	Lọc theo Domain
maxOrgCount	Integer	Số đơn vị tối đa (mặc định: 1 — chỉ ở 1 đơn vị)
page, size	—	Phân trang

Response 200:

{
  "success": true,
  "data": {
    "items": [
      {
        "dataElement": { "id": 203, "code": "DE003-DM1.2", "name": "Nhóm máu" },
        "domain": "Con người",
        "orgCount": 1,
        "organizations": [
          { "orgId": 5, "orgName": "Sở Y tế" }
        ]
      }
    ],
    "meta": { "page": 0, "size": 20, "totalElements": 42 },
    "summary": {
      "totalFragmentedDe": 42,
      "singleOrgCount": 30,
      "twoOrgCount": 12
    }
  }
}

---

Báo Cáo Tiến Độ

GET /api/v1/reports/progress/by-org

Mục đích: Tiến độ quy hoạch theo đơn vị: tỉ lệ DE đã mapping, đã chốt chủ quản, đã ban hành.

Tham chiếu: UC-RPT-001, Feature EP-06-002

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

Query Parameters: domainId (lọc), page, size, sort

Response 200:

{
  "success": true,
  "data": {
    "items": [
      {
        "org": { "id": 1, "name": "Công an TP", "code": "ID01.01" },
        "totalDe": 120,
        "mappedDe": 110,
        "confirmedDe": 100,
        "publishedDe": 95,
        "mappedPercent": 91.7,
        "confirmedPercent": 83.3,
        "publishedPercent": 79.2
      }
    ],
    "meta": { "page": 0, "size": 20, "totalElements": 40 }
  }
}

---

GET /api/v1/reports/progress/by-domain

Mục đích: Tiến độ quy hoạch theo Domain.

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

Response 200: Tương tự by-org nhưng nhóm theo Domain thay vì đơn vị.

---

Dashboard Maturity Score

GET /api/v1/reports/maturity-score

Mục đích: Heatmap mức độ trưởng thành chuẩn hoá dữ liệu theo ma trận Sở ngành (hàng) × Domain (cột).

Tham chiếu: UC-RPT-002, Feature EP-06-003

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

Response 200:

{
  "success": true,
  "data": {
    "domains": [
      { "id": 1, "code": "DM1", "name": "Con người" },
      { "id": 2, "code": "DM2", "name": "Tổ chức" },
      { "id": 3, "code": "DM3", "name": "Đất đai" }
    ],
    "organizations": [
      { "id": 1, "name": "Công an TP" },
      { "id": 5, "name": "Sở Y tế" }
    ],
    "matrix": [
      {
        "orgId": 1,
        "scores": [
          { "domainId": 1, "score": 4.2, "level": "HIGH" },
          { "domainId": 2, "score": 3.1, "level": "MEDIUM" },
          { "domainId": 3, "score": 0.5, "level": "LOW" }
        ],
        "avgScore": 2.6
      },
      {
        "orgId": 5,
        "scores": [
          { "domainId": 1, "score": 3.8, "level": "HIGH" },
          { "domainId": 2, "score": 1.2, "level": "LOW" },
          { "domainId": 3, "score": 0.0, "level": "NONE" }
        ],
        "avgScore": 1.7
      }
    ],
    "scoreLevels": {
      "NONE": "0.0 — Chưa có dữ liệu",
      "LOW": "0.1–2.0 — Dưới chuẩn",
      "MEDIUM": "2.1–3.5 — Đang phát triển",
      "HIGH": "3.6–5.0 — Trưởng thành"
    }
  }
}

Ghi chú: Score tính dựa trên: % DE đã có chủ quản, đã có định nghĩa đầy đủ, đã PUBLISHED.

---

GET /api/v1/reports/maturity-score/drill-down

Mục đích: Drill-down theo Domain hoặc đơn vị để xem chi tiết.

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

Query Parameters:

Parameter	Kiểu	Bắt buộc	Mô tả
orgId	Long	Có (1 trong 2)	Drill-down theo đơn vị
domainId	Long	Có (1 trong 2)	Drill-down theo Domain

Response 200:

{
  "success": true,
  "data": {
    "org": { "id": 1, "name": "Công an TP" },
    "domain": { "id": 1, "code": "DM1", "name": "Con người" },
    "score": 4.2,
    "breakdown": {
      "totalDe": 120,
      "withOwner": 115,
      "withDefinition": 110,
      "published": 100,
      "ownerPercent": 95.8,
      "definitionPercent": 91.7,
      "publishedPercent": 83.3
    },
    "dataElements": [
      {
        "id": 101,
        "code": "DE001-DM1.1",
        "name": "Số CCCD",
        "hasOwner": true,
        "hasDefinition": true,
        "isPublished": true
      }
    ]
  }
}

---

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