# Update Kategori Rekanan — eSurat PPM

## ⚠️ ATURAN DEPLOY

**JANGAN hapus folder `esurat` sebelum ekstrak.** Ekstrak menimpa saja.
Folder `uploads/` dan `storage/` tidak boleh tersentuh.

---

## File yang berubah

| File | Perubahan |
|---|---|
| `includes/helpers.php` | **+** fungsi taksonomi & deteksi otomatis |
| `api/index.php` | **+** endpoint `rekanan/meta`, kategori masuk create/update/list |
| `assets/js/api.js` | **+** `API.Rekanan.meta()`, filter kategori di `list()` |
| `index.html` | Combobox penerima, modal, tabel, CSS |
| `migrate_rekanan_kategori.sql` | **BARU** — migrasi database |

---

## Urutan pemasangan

### 1. Backup dulu
cPanel → phpMyAdmin → pilih database → Export → Go.
Simpan file `.sql` sebelum lanjut.

### 2. Jalankan migrasi database
phpMyAdmin → tab **SQL** → tempel seluruh isi
`migrate_rekanan_kategori.sql` → **Go**.

Migrasi ini aman diulang. Kalau muncul error 1060
(*Duplicate column name*), berarti kolom sudah ada — lompati bagian 1,
lanjut ke bagian 2.

### 3. Upload file aplikasi
Ekstrak ZIP ke folder `esurat` (timpa file lama).

### 4. Periksa hasil
Buka menu **Rekanan**. Kolom Kategori harus sudah terisi chip berwarna.

---

## Sisa pekerjaan manual

Bagian akhir file SQL berisi tiga query pemeriksaan:

1. **Rekap per kategori** — melihat sebaran hasil klasifikasi
2. **Daftar `LAINNYA`** — yang perlu dikategorikan manual lewat tombol Edit
3. **Deteksi duplikat** — mis. *Badan Nasional Pengelola Perbatasan* tercatat dua kali

Duplikat **tidak dihapus otomatis**. Sebelum menghapus salah satunya,
pastikan tidak ada surat yang terlanjur memakai kode rekanan tersebut:

```sql
SELECT nomor, tanggal, perihal FROM surat_keluar WHERE rekanan_id = 'ID_YANG_MAU_DIHAPUS';
```

Kalau ada, pindahkan dulu surat itu ke ID yang dipertahankan:

```sql
UPDATE surat_keluar SET rekanan_id = 'ID_DIPERTAHANKAN' WHERE rekanan_id = 'ID_DIHAPUS';
```

---

## Taksonomi

Kategori mengacu **SNA 2008** (sektor institusi, dipakai BPS) dengan
penajaman **OECD Frascati Manual** di sektor pengetahuan.
Bentuk badan hukum mengacu **ISO 20275 — Entity Legal Forms**.

| Kode | Kategori | Rujukan |
|---|---|---|
| `KL` | Pemerintah & lembaga negara | SNA S.13 |
| `BUMN` | BUMN, Perum & BUMD | SNA S.11 (publik) |
| `FINANSIAL` | Lembaga pembiayaan & penjaminan | SNA S.12 |
| `SWASTA` | Perusahaan swasta | SNA S.11 |
| `KOPERASI` | Koperasi & badan usaha bersama | SNA S.11 / ISO 20275 |
| `AKADEMIK` | Perguruan tinggi | Frascati HES |
| `RISET` | Lembaga riset & think tank nirlaba | Frascati PNP |
| `MASYARAKAT` | Organisasi & lembaga masyarakat | SNA S.15 (LNPRT) |
| `LAINNYA` | Belum terklasifikasi | — |

**Catatan penempatan yang disengaja:**

- **BRIN masuk `KL`, bukan `AKADEMIK`.** Secara Frascati, BRIN sektor
  GOV (lembaga pemerintah), bukan HES (perguruan tinggi).
- **PT SMI & PT PII masuk `FINANSIAL`, bukan `BUMN`.** Keduanya memang
  BUMN, tapi peran persuratannya soal penjaminan dan *financial close*.
- **Semua kampus masuk `AKADEMIK`** tanpa peduli negeri/swasta. Yang
  dibutuhkan saat memilih penerima adalah "ini kampus", bukan status
  badan hukumnya — itu disimpan terpisah di `bentuk_badan`.
- **Koperasi terpisah dari organisasi masyarakat.** Koperasi adalah
  badan usaha; LMDH dan sejenisnya adalah lembaga nirlaba.

---

## Aturan deteksi otomatis

Pola diperiksa **berurutan** — yang paling spesifik menang duluan:

```
AKADEMIK → KOPERASI → KL → FINANSIAL → BUMN → RISET → MASYARAKAT → SWASTA
```

Urutan ini menyelesaikan tabrakan kata:

| Nama | Hasil | Kenapa |
|---|---|---|
| Yayasan Universitas Trisakti | `AKADEMIK` | AKADEMIK diperiksa sebelum MASYARAKAT |
| Koperasi Pegawai Kementerian | `KOPERASI` | pola KOPERASI terikat di awal nama |
| Kementerian Koperasi dan UKM | `KL` | tidak diawali kata "Koperasi" |
| PT Bank BRI (Persero) Tbk | `FINANSIAL` | FINANSIAL sebelum BUMN dan SWASTA |
| Badan Riset dan Inovasi Nasional | `KL` | KL sebelum RISET |

Aturan ini **satu sumber**: didefinisikan di `helpers.php`, dikirim ke
browser lewat `rekanan/meta`. Front-end punya salinan cadangan yang
hanya dipakai kalau endpoint gagal dihubungi.

Deteksi otomatis hanya **mengisi**, tidak mengunci. Begitu kamu ubah
manual, tebakan berhenti menimpa.

---

## Yang sengaja TIDAK diubah

**Tab "Pemerintah Daerah" dibiarkan apa adanya.** Tab itu memakai teks
bebas (`pemda_kota`) yang langsung masuk ke nomor surat. Memindahkannya
ke tabel rekanan akan mengubah format penomoran dan memutus kontinuitas
surat yang sudah terbit. Ini utang teknis yang disadari, bukan
kelalaian.

**Format nomor surat tidak berubah.** Kategori murni metadata untuk
penyaringan dan pengelompokan — `PPM-{kode}` tetap seperti semula.
