# Pengumuman (Announcements)


## Ringkasan

**Pengumuman** adalah siaran pesan internal yang ditujukan ke seluruh anggota tim (agent, supervisor, admin) di dalam aplikasi OmniStream — **bukan** pesan ke pelanggan. Gunakan fitur ini untuk menyampaikan kebijakan baru, perubahan jadwal, pembaruan proses, atau informasi darurat yang perlu diketahui semua orang segera.

Pengumuman tersimpan di tabel `announcements` di PostgreSQL dan dapat diakses siapa saja yang sudah login melalui halaman `/announcements`.

:::info
**Siapa yang dapat membuat pengumuman?** Endpoint `POST /api/announcements` hanya memerlukan JWT yang valid — tidak ada pembatasan peran di level middleware. Secara praktis, pembuatan dan pengelolaan pengumuman dilakukan oleh **admin** atau **supervisor**. Author dicatat otomatis dari JWT (`author_id = claims.sub`).
:::

## Atribut pengumuman

| Field | Tipe | Keterangan |
|---|---|---|
| **Title** | teks | Judul singkat, wajib diisi |
| **Body** | teks panjang | Isi pengumuman; mendukung baris baru (`whitespace-pre-wrap`) |
| **Priority** | `low` / `normal` / `urgent` | Level urgensi (default: `normal`) |
| **Is Pinned** | boolean | Jika diaktifkan, pengumuman selalu muncul di atas daftar |
| **Expires At** | datetime (opsional) | Setelah waktu ini, pengumuman tidak lagi ditampilkan |
| **Published At** | datetime (otomatis) | Waktu pembuatan, di-set oleh database |

Nilai `priority` divalidasi langsung di level database dengan `CHECK (priority IN ('urgent','normal','low'))`.

## Cara membuat pengumuman

1. Buka halaman **Announcements** (`/announcements`).
2. Klik tombol **+ New Announcement** di pojok kanan atas.
3. Isi form:
   - **Title** (wajib)
   - **Body** — tulis isi pengumuman (wajib)
   - **Priority** — pilih `Low`, `Normal`, atau `Urgent`
   - **Expires at** — opsional; pengumuman otomatis tersembunyi setelah tanggal/jam ini
   - **Pin to top** — centang jika pengumuman ini harus selalu terlihat di bagian atas
4. Klik **Publish**. Backend memanggil `POST /api/announcements`.

:::tip
Gunakan **Urgent** untuk informasi yang membutuhkan tindakan segera (misalnya downtime, perubahan SLA darurat). Gunakan **Pin to top** agar pengumuman tetap terlihat meski ada pengumuman baru yang masuk.
:::

## Cara mengubah pengumuman

1. Di daftar pengumuman, klik ikon **pensil** pada baris yang ingin diubah.
2. Form akan terisi dengan data saat ini.
3. Lakukan perubahan, lalu klik **Update**. Backend memanggil `PUT /api/announcements/{id}`.

:::warning
Mengubah pengumuman menimpa semua field sekaligus — termasuk `expires_at`. Pastikan field **Expires at** tetap terisi jika pengumuman sebelumnya memiliki tanggal kedaluwarsa.
:::

## Cara menghapus pengumuman

Klik ikon **trash** pada baris pengumuman → pengumuman langsung dihapus (`DELETE /api/announcements/{id}`). Penghapusan bersifat permanen; tidak ada mekanisme soft-delete.

## Tampilan untuk agent

Semua agent yang sudah login dapat mengakses halaman `/announcements` dan melihat daftar pengumuman yang masih aktif (belum kedaluwarsa). Urutan tampilan:

1. **Pengumuman yang di-pin** (`is_pinned = true`) muncul paling atas.
2. Di antara pengumuman dengan status pin yang sama, urutan berdasarkan `published_at DESC` (terbaru dahulu).
3. Maksimum **100 pengumuman** ditampilkan dalam satu permintaan.

Pengumuman yang sudah melewati `expires_at` secara otomatis tidak muncul — query backend menyaring dengan `WHERE expires_at IS NULL OR expires_at > now()`.

Badge prioritas ditampilkan dengan warna berbeda:

| Priority | Tampilan |
|---|---|
| `urgent` | Merah |
| `normal` | Biru |
| `low` | Abu-abu |

:::note
Fitur ini belum memiliki status **read/acknowledge** per-agent. Semua pengumuman aktif ditampilkan ke seluruh tim tanpa pelacakan siapa yang sudah membaca.
:::

## Audiens dan targeting

Saat ini pengumuman bersifat **broadcast ke seluruh tim** — tidak ada filter per-divisi, per-peran, atau per-agent. Semua pengguna yang login di workspace yang sama akan melihat pengumuman yang sama.

## Endpoint (tag **Announcements**)

| Aksi | Endpoint |
|---|---|
| List pengumuman aktif | `GET /api/announcements` |
| Buat pengumuman | `POST /api/announcements` |
| Update pengumuman | `PUT /api/announcements/{id}` |
| Hapus pengumuman | `DELETE /api/announcements/{id}` |

Skema lengkap tersedia di [API Reference](/api).

## Praktik terbaik

- **Tetapkan `expires_at`** untuk pengumuman yang bersifat sementara (jadwal piket, info event) agar tidak menumpuk di daftar.
- **Batasi penggunaan prioritas `urgent`** — jika terlalu sering dipakai, agent akan mengabaikannya.
- **Gunakan pin** hanya untuk pengumuman yang benar-benar perlu terlihat setiap hari, lalu lepas pin setelah tidak relevan.
- **Hapus pengumuman lama** secara berkala agar halaman tetap bersih dan relevan.

## Rute terkait

- [Manajemen Pengguna](/panduan/admin/manajemen-pengguna) — kelola agent dan akses
- [Manajemen Divisi](/panduan/admin/divisi) — pengelompokan tim
- [Activity Logs](/panduan/admin/activity-logs) — audit aktivitas admin