# Requirements Document

## Introduction

Fitur ini menambahkan 3 enhancement pada halaman Prison di USMS (localhost:3001/prison):

1. **Dashboard Statistik** — Menampilkan ringkasan statistik criminal cases dari DOJ API di halaman prison index, meliputi total kasus aktif vs closed, distribusi per status, trend per bulan, dan top hakim/jaksa.

2. **Detail View per Tahanan** — Ketika nama tahanan di halaman prison show diklik, menampilkan detail lengkap criminal case dari DOJ API (status, tanggal sidang, putusan, hakim, jaksa, dll) menggunakan method `DojCriminalCaseService::show()` yang sudah ada.

3. **Pagination untuk Criminal Cases** — Tabel DOJ Criminal Cases di halaman prison index saat ini menampilkan semua data sekaligus (78+ record). Ditambahkan pagination (15 per halaman) agar lebih manageable, dengan dukungan parameter pagination di DOJ API.

Kedua aplikasi yang terlibat:
- USMS app: `e:\_Code\satu_mimpi\usms\` (localhost:3001)
- DOJ app: `e:\_Code\satu_mimpi\DOJ\` (localhost:8001)

## Glossary

- **DOJ_API**: API endpoint yang disediakan oleh aplikasi DOJ (Department of Justice) di localhost:8001 untuk menerima dan menyediakan data criminal cases
- **USMS_Client**: Service di aplikasi USMS (localhost:3001) yang mengirim HTTP request ke DOJ_API, diimplementasikan sebagai `DojCriminalCaseService`
- **Prison_Index_Page**: Halaman daftar penjara di USMS (`/prison`) yang menampilkan tabel Prison Records dan tabel Criminal Cases dari DOJ
- **Prison_Show_Page**: Halaman detail penjara di USMS (`/prison/{id}`) yang menampilkan informasi CID, briefing, daftar tahanan, dan criminal cases terkait
- **Criminal_Case**: Record di tabel `criminal_cases` DOJ yang menyimpan data kasus pidana termasuk accused_name, cid_no, bail_amount, status, judge_name, prosecutor_name, decision, dan date_of_hearing
- **Dashboard_Statistik**: Komponen UI berupa card-card ringkasan yang menampilkan agregasi data criminal cases (total, per status, per bulan, top hakim/jaksa)
- **Detail_Modal**: Modal atau panel yang menampilkan informasi lengkap satu criminal case ketika nama tahanan diklik
- **Pagination_Component**: Komponen navigasi halaman (previous, next, nomor halaman) untuk membagi data criminal cases menjadi beberapa halaman

## Requirements

### Requirement 1: DOJ API Menyediakan Endpoint Statistik Criminal Cases

**User Story:** Sebagai sistem USMS, saya ingin mengambil data statistik agregasi criminal cases dari DOJ API, sehingga saya dapat menampilkan dashboard ringkasan di halaman prison.

#### Acceptance Criteria

1. WHEN USMS_Client mengirim GET request ke `/api/criminal-cases/statistics` dengan header `X-API-Key` yang valid, THE DOJ_API SHALL mengembalikan response JSON berisi data statistik agregasi criminal cases dengan format `{"success": true, "message": "...", "data": {...}}`
2. THE DOJ_API SHALL menyertakan field `total_active` (jumlah criminal cases dengan status `active`) dan `total_closed` (jumlah criminal cases dengan status `closed`) dalam response statistik
3. THE DOJ_API SHALL menyertakan field `by_status` berupa objek key-value yang berisi jumlah criminal cases untuk setiap status: `active`, `closed`, `arraignment`, `trial`, `sentence`, `search warrant`, `arrest warrant`, `withdrawn`
4. THE DOJ_API SHALL menyertakan field `by_month` berupa array objek dengan format `[{"month": "YYYY-MM", "count": N}, ...]` yang berisi jumlah criminal cases per bulan berdasarkan field `created_at`, diurutkan dari bulan terlama ke terbaru, untuk 12 bulan terakhir
5. THE DOJ_API SHALL menyertakan field `top_judges` berupa array maksimal 5 objek dengan format `[{"name": "...", "count": N}, ...]` yang berisi hakim dengan jumlah kasus terbanyak, diurutkan descending berdasarkan count, dengan mengecualikan record yang field `judge_name`-nya null atau string kosong
6. THE DOJ_API SHALL menyertakan field `top_prosecutors` berupa array maksimal 5 objek dengan format `[{"name": "...", "count": N}, ...]` yang berisi jaksa dengan jumlah kasus terbanyak, diurutkan descending berdasarkan count, dengan mengecualikan record yang field `prosecutor_name`-nya null atau string kosong
7. IF request tidak menyertakan header autentikasi yang valid, THEN THE DOJ_API SHALL mengembalikan response `{"success": false, "message": "Unauthorized"}` dengan HTTP status 401

### Requirement 2: USMS Menampilkan Dashboard Statistik di Halaman Prison Index

**User Story:** Sebagai officer USMS, saya ingin melihat ringkasan statistik criminal cases di halaman prison, sehingga saya dapat memantau kondisi kasus secara keseluruhan tanpa harus menghitung manual.

#### Acceptance Criteria

1. WHEN officer membuka Prison_Index_Page, THE USMS_Client SHALL memanggil endpoint statistik DOJ_API dan menampilkan Dashboard_Statistik di bagian atas halaman sebelum tabel Criminal Cases
2. THE Dashboard_Statistik SHALL menampilkan card ringkasan berisi total kasus aktif dan total kasus closed dalam format angka yang mudah dibaca
3. THE Dashboard_Statistik SHALL menampilkan distribusi kasus per status dalam bentuk badge atau label berwarna dengan jumlah masing-masing status
4. THE Dashboard_Statistik SHALL menampilkan trend kasus per bulan untuk 12 bulan terakhir dalam bentuk tabel atau chart sederhana yang menunjukkan bulan dan jumlah kasus
5. THE Dashboard_Statistik SHALL menampilkan daftar top 5 hakim dan top 5 jaksa dengan jumlah kasus masing-masing
6. IF DOJ_API tidak dapat dihubungi atau mengembalikan error, THEN THE USMS_Client SHALL tetap menampilkan Prison_Index_Page tanpa Dashboard_Statistik dan mencatat error ke log

### Requirement 3: USMS Menampilkan Detail Criminal Case per Tahanan

**User Story:** Sebagai officer USMS, saya ingin melihat detail lengkap criminal case ketika mengklik nama tahanan di halaman prison show, sehingga saya dapat mengetahui status sidang, putusan, dan informasi hakim/jaksa tanpa harus membuka sistem DOJ secara terpisah.

#### Acceptance Criteria

1. WHEN officer mengklik nama tahanan (accused_name) pada tabel Criminal Cases di Prison_Show_Page, THE USMS_Client SHALL memanggil `DojCriminalCaseService::show()` dengan parameter ID criminal case yang diklik
2. WHEN data criminal case berhasil diambil dari DOJ_API, THE Detail_Modal SHALL menampilkan informasi lengkap meliputi: nomor perkara (application_no), nama terdakwa (accused_name), CID (cid_no), status kasus, tanggal sidang (date_of_hearing), putusan (decision), plea terdakwa (accused_plea), nama hakim (judge_name), nama jaksa (prosecutor_name), nama pembela (public_defender_name), jumlah bail (bail_amount), dan status bail (bail_status)
3. WHILE data criminal case sedang dimuat dari DOJ_API, THE Detail_Modal SHALL menampilkan indikator loading kepada officer
4. IF DOJ_API mengembalikan HTTP status 404 untuk criminal case yang diminta, THEN THE Detail_Modal SHALL menampilkan pesan "Data criminal case tidak ditemukan" kepada officer
5. IF DOJ_API tidak dapat dihubungi atau mengembalikan error selain 404, THEN THE Detail_Modal SHALL menampilkan pesan error yang informatif dan mencatat detail error ke log
6. THE Detail_Modal SHALL menyediakan tombol atau mekanisme untuk menutup modal dan kembali ke tampilan Prison_Show_Page

### Requirement 4: DOJ API Mendukung Pagination pada Endpoint Criminal Cases Index

**User Story:** Sebagai sistem USMS, saya ingin mengambil data criminal cases secara bertahap (per halaman), sehingga halaman prison tidak perlu memuat semua 78+ record sekaligus.

#### Acceptance Criteria

1. WHEN USMS_Client mengirim GET request ke `/api/criminal-cases` dengan query parameter `page` dan `per_page`, THE DOJ_API SHALL mengembalikan data criminal cases sesuai halaman yang diminta dengan jumlah record per halaman sesuai parameter `per_page`
2. THE DOJ_API SHALL menggunakan nilai default `page=1` dan `per_page=15` apabila parameter pagination tidak disertakan dalam request
3. THE DOJ_API SHALL menyertakan metadata pagination dalam response dengan format `{"success": true, "message": "...", "data": [...], "meta": {"current_page": N, "per_page": N, "total": N, "last_page": N}}` sehingga USMS_Client dapat menampilkan navigasi halaman
4. WHEN parameter `per_page` bernilai lebih dari 100, THE DOJ_API SHALL membatasi jumlah record per halaman menjadi maksimal 100
5. WHEN parameter `page` bernilai lebih besar dari `last_page`, THE DOJ_API SHALL mengembalikan response dengan array `data` kosong dan metadata pagination yang valid
6. THE DOJ_API SHALL tetap mendukung filter `cid_no`, `accused_name`, dan `status` bersamaan dengan parameter pagination, dengan pagination diterapkan setelah filter

### Requirement 5: USMS Menampilkan Pagination pada Tabel Criminal Cases di Prison Index

**User Story:** Sebagai officer USMS, saya ingin tabel Criminal Cases di halaman prison menampilkan data per halaman (15 record), sehingga halaman tidak terlalu panjang dan lebih mudah dinavigasi.

#### Acceptance Criteria

1. WHEN officer membuka Prison_Index_Page, THE USMS_Client SHALL meminta data criminal cases dari DOJ_API dengan parameter `per_page=15` dan `page` sesuai halaman yang sedang aktif
2. THE Pagination_Component SHALL menampilkan navigasi halaman di bawah tabel Criminal Cases yang meliputi: tombol Previous, tombol Next, dan indikator halaman saat ini dari total halaman
3. WHEN officer mengklik tombol Next pada Pagination_Component, THE USMS_Client SHALL memuat data criminal cases halaman berikutnya dari DOJ_API dan memperbarui tabel
4. WHEN officer mengklik tombol Previous pada Pagination_Component, THE USMS_Client SHALL memuat data criminal cases halaman sebelumnya dari DOJ_API dan memperbarui tabel
5. WHILE officer berada di halaman pertama, THE Pagination_Component SHALL menonaktifkan (disable) tombol Previous
6. WHILE officer berada di halaman terakhir, THE Pagination_Component SHALL menonaktifkan (disable) tombol Next
7. THE Pagination_Component SHALL menampilkan informasi "Menampilkan X - Y dari Z data" di samping navigasi halaman
8. WHEN officer menerapkan filter (doj_search atau doj_status) bersamaan dengan pagination, THE USMS_Client SHALL mengirim parameter filter dan pagination secara bersamaan ke DOJ_API dan mereset halaman ke halaman pertama

### Requirement 6: USMS Service Class Mendukung Method Statistik dan Parameter Pagination

**User Story:** Sebagai developer, saya ingin DojCriminalCaseService memiliki method untuk mengambil statistik dan mendukung parameter pagination, sehingga controller dapat menggunakan service yang sudah ada tanpa membuat HTTP call langsung.

#### Acceptance Criteria

1. THE USMS_Client SHALL menambahkan method `statistics()` pada class `DojCriminalCaseService` yang mengirim GET request ke `/api/criminal-cases/statistics` dan mengembalikan array response dari DOJ_API
2. THE USMS_Client SHALL memodifikasi method `index()` pada class `DojCriminalCaseService` untuk menerima parameter pagination (`page` dan `per_page`) sebagai bagian dari array `$filters` dan meneruskannya sebagai query parameter ke DOJ_API
3. IF DOJ_API mengembalikan HTTP status selain 2xx pada method `statistics()`, THEN THE USMS_Client SHALL melempar exception yang berisi HTTP status code dan response body
4. IF DOJ_API tidak dapat dihubungi dalam waktu 10 detik pada method `statistics()`, THEN THE USMS_Client SHALL melempar exception yang berisi informasi timeout