# Pengumuman

Pengumuman perusahaan untuk karyawan. Admin HR membuat pengumuman di panel (**Pengumuman**), menentukan
masa tayang, dan dapat menyematkannya di urutan teratas. Aplikasi menampilkan pengumuman yang sedang
tayang dan menandainya dibaca saat dibuka. Konvensi umum ada di [README.md](README.md).

| Atribut | Nilai |
|---|---|
| Endpoint | `GET /announcements`, `GET /announcements/{announcement}` |
| Sumber kode | `AnnouncementController`, `AnnouncementResource`, `AnnouncementService`, model `Announcement` dan `AnnouncementRead`, panel `App\Filament\App\Resources\Announcements` |
| Saklar modul | `me/config` → `modules.module_announcement`. Server tidak memblokir endpoint berdasarkan saklar ini (README bagian 12) |
| Contoh direkam | 2026-11-15 21:12 WIB, HTTP kernel Laravel, basis data MySQL sekali pakai berisi dua perusahaan (`nusantara-logistik` WIB, `borneo-retail` WITA), `APP_LOCALE=id`. Pengumuman `Libur Bersama Akhir Tahun` dibuat lewat formulir panel (permintaan Livewire nyata) |

Seluruh endpoint di berkas ini wajib token (`Authorization: Bearer <token>`) dan melewati
`auth:sanctum` + `EnsureSubscriptionActive`.

---

## Masa Tayang

| Keadaan (panel) | Syarat | Tampil di API |
|---|---|---|
| Terjadwal | `published_at` di masa depan | tidak; detail dijawab 404 |
| Tayang | `published_at` sudah lewat dan `expires_at` kosong atau belum lewat | ya |
| Berakhir | `expires_at` sudah lewat | tidak; detail dijawab 404 |
| Dihapus | dihapus Admin HR di panel | tidak; detail dijawab 404 |

Pengumuman berlaku untuk **seluruh karyawan perusahaan**. Belum ada penargetan per departemen.

---

## Daftar pengumuman

**`GET /announcements`**

Deskripsi: pengumuman yang sedang tayang di perusahaan karyawan login. Urutan: disematkan lebih dulu,
lalu `published_at` terbaru, lalu `id` terbesar. Maksimal 50 item, tanpa pagination.

| Auth & Middleware | |
|---|---|
| Token | ya |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.announcements.index` |

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`

**Parameter:** tidak ada.

**Contoh Request**

```http
GET /api/v1/announcements HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`, 2026-11-15 21:12 WIB, karyawan Anton Satu, `nusantara-logistik`)

```json
{
  "success": true,
  "message": "Daftar pengumuman berhasil diambil.",
  "data": [
    {
      "id": 2,
      "title": "Libur Bersama Akhir Tahun",
      "body": "Kantor tutup 24-26 Desember 2026.\n\nPresensi dibuka kembali 28 Desember.",
      "is_pinned": true,
      "is_read": false,
      "published_at": "2026-11-15T13:00:00+00:00",
      "expires_at": "2026-12-31T16:59:00+00:00"
    },
    {
      "id": 4,
      "title": "Jadwal Pemeriksaan Kesehatan",
      "body": "Pemeriksaan kesehatan tahunan dilaksanakan 2 Desember 2026 di ruang serbaguna.\n\nBawa kartu BPJS Kesehatan.",
      "is_pinned": false,
      "is_read": false,
      "published_at": "2026-11-13T14:12:10+00:00",
      "expires_at": null
    }
  ]
}
```

Pada saat yang sama perusahaan ini juga punya satu pengumuman terjadwal (tayang besok) dan satu yang
sudah berakhir; keduanya tidak muncul. Karyawan `borneo-retail` hanya menerima pengumuman perusahaannya
sendiri.

Tanpa pengumuman tayang, `data` berupa array kosong `[]`.

**Field `data[]`**

| Field | Tipe | Null | Keterangan |
|---|---|---|---|
| `id` | integer | tidak | dipakai untuk `GET /announcements/{announcement}` |
| `title` | string | tidak | maksimal 150 karakter |
| `body` | string | tidak | teks polos, maksimal 5000 karakter, paragraf dipisah `\n\n`. Tampilkan apa adanya, bukan HTML/Markdown |
| `is_pinned` | boolean | tidak | disematkan Admin HR |
| `is_read` | boolean | tidak | karyawan login sudah pernah membuka detailnya |
| `published_at` | string ISO 8601 UTC | tidak | mulai tayang |
| `expires_at` | string ISO 8601 UTC | ya | akhir tayang; `null` = tanpa batas |

**Contoh Response Gagal:** `401` tanpa token, `402` langganan terkunci (README bagian 5.1).

---

## Detail pengumuman

**`GET /announcements/{announcement}`**

Deskripsi: satu pengumuman yang sedang tayang. **Memanggil endpoint ini menandai pengumuman dibaca**
oleh karyawan login. Pemanggilan berulang tidak mengubah waktu baca pertama.

| Auth & Middleware | |
|---|---|
| Token | ya |
| Middleware | `auth:sanctum`, `EnsureSubscriptionActive` |
| Route name | `api.v1.announcements.show` |

**Header:** `Accept: application/json`, `Authorization: Bearer <token>`

**Parameter**

| Nama | Lokasi | Tipe | Wajib | Aturan |
|---|---|---|---|---|
| `announcement` | path | integer | ya | `id` dari daftar |

**Contoh Request**

```http
GET /api/v1/announcements/2 HTTP/1.1
Accept: application/json
Authorization: Bearer <token>
```

**Contoh Response Sukses** (`200`, 2026-11-15 21:12 WIB)

```json
{
  "success": true,
  "message": "Detail pengumuman berhasil diambil.",
  "data": {
    "id": 2,
    "title": "Libur Bersama Akhir Tahun",
    "body": "Kantor tutup 24-26 Desember 2026.\n\nPresensi dibuka kembali 28 Desember.",
    "is_pinned": true,
    "is_read": true,
    "published_at": "2026-11-15T13:00:00+00:00",
    "expires_at": "2026-12-31T16:59:00+00:00"
  }
}
```

Field `data` sama dengan item daftar; `is_read` selalu `true`.

**Contoh Response Gagal**

Pengumuman terjadwal atau sudah berakhir (`404`):

```json
{
  "success": false,
  "message": "Pengumuman tidak ditemukan atau sudah tidak tayang.",
  "errors": {}
}
```

Pengumuman milik perusahaan lain, sudah dihapus, atau `id` tidak dikenal (`404`):

```json
{
  "success": false,
  "message": "Sumber daya tidak ditemukan.",
  "errors": {}
}
```

`401` dan `402` sama dengan daftar.

---

## Catatan untuk Client

- Lencana "belum dibaca" dihitung client dari jumlah item `is_read: false` di `GET /announcements`.
- Segarkan daftar saat aplikasi dibuka dan saat layar pengumuman ditampilkan. Belum ada notifikasi push
  saat pengumuman terbit (lihat [push-tokens.md](push-tokens.md)).
- Pengumuman yang terbuka di layar bisa berakhir atau dihapus sewaktu-waktu. Tangani 404 dengan menghapus
  item dari daftar lokal.
