# eSurat PPM — Panduan Update Terpadu
*Kategori Rekanan 9-standar + Alur Kontrak Manual Satu-Pintu*

## Jaminan keamanan data
Paket ini **tidak mengandung satu pun** `DROP`, `TRUNCATE`, atau `DELETE`
(teraudit per file). Migrasi hanya `ALTER TABLE ADD COLUMN` dan `UPDATE`
pada kolom baru. Tabel `surat_masuk`, `surat_keluar`, `disposisi`, dan
`pengguna` **tidak disentuh**. ZIP tidak memuat `includes/config.php`
maupun isi `uploads/` — kredensial database dan PDF produksi mustahil
tertimpa. `database.sql` HANYA untuk instalasi baru (ber-header
peringatan).

## Checklist pra-deploy (2 menit)
Jalankan di phpMyAdmin SEBELUM dan SESUDAH migrasi — lima angka wajib
identik:
```sql
SELECT
 (SELECT COUNT(*) FROM surat_keluar) AS surat_keluar,
 (SELECT COUNT(*) FROM surat_masuk)  AS surat_masuk,
 (SELECT COUNT(*) FROM kontrak)      AS kontrak,
 (SELECT COUNT(*) FROM rekanan)      AS rekanan,
 (SELECT COUNT(*) FROM jenis_surat)  AS jenis;
```

## Urutan pemasangan
1. **Backup berpasangan**: Export database (.sql) + arsip `uploads`
   (.7z) pada momen yang sama.
2. `migrate_rekanan_kategori.sql` *(lewati jika sudah pernah)*.
3. `migrate_alur_kontrak.sql` — **WAJIB**, fondasi tombol Catat Kontrak.
4. Ekstrak ZIP menimpa folder `esurat` (JANGAN hapus folder dulu).
5. Hard refresh browser (Ctrl+Shift+R).

## Alur kontrak — final
**Prinsip: kontrak dicatat SETELAH ditandatangani. Satu pintu, manual.**

1. **Rekam surat** perikatan (SPK/PKS/MoU) seperti surat biasa — boleh
   tanpa file dulu jika nomor dibutuhkan untuk dicetak di draf.
   Baris surat tanpa file punya tombol **"Unggah PDF"** untuk menyusulkan
   versi ber-ttd — otomatis di-stamp ID, di-hash, dan dicermin ke Vault.
2. Surat perikatan yang belum punya kontrak diberi penanda kuning
   **"Kontrak belum dicatat"** — pengingat yang tidak bisa diabaikan.
3. Setelah ttd: menu **Kontrak → "Catat Kontrak"** → ketik **nomor yang
   sama persis** dengan suratnya + masa berlaku. Sistem otomatis:
   menautkan ke surat (`surat_keluar_id`), mewarisi rekanan, mewarisi
   **PDF ber-stamp ID** dari arsip (tanpa unggah ulang), menandai
   sumber "keluar", dan menampilkan chip **"Dari surat"**.
4. Kontrak dari pihak luar / kontrak lama: form yang sama, pilih asal
   yang sesuai, unggah PDF-nya sendiri (file eksternal TIDAK di-stamp —
   menjaga keaslian dokumen pihak lain; identitas cukup di metadata).

## Keputusan desain yang disengaja
- **Stamp ID hanya untuk dokumen terbitan sendiri** (ISO 15489:
  authenticity — dokumen pihak luar tidak dimodifikasi).
- **Hash & Vault menyimpan versi FINAL ber-stamp** — self-healing
  memulihkan rekod resmi, bukan draf pra-stamp.
- **Relasi lunak** (ON DELETE SET NULL): menghapus surat/rekanan tidak
  ikut menghapus kontrak.
- **PDF susulan ke surat otomatis dipropagasi** ke kontrak tertaut yang
  belum berfile — satu dokumen, satu sumber kebenaran.

## File berubah
`migrate_alur_kontrak.sql` · `migrate_rekanan_kategori.sql` ·
`database.sql` · `api/index.php` · `includes/helpers.php` ·
`assets/js/api.js` · `assets/js/integration.js` · `index.html`
