# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Apa ini

Arsip Dokumen (PTCMP Group): arsip PDF hasil scan invoice (NP…/RNP…) dan surat jalan (SJ…) untuk dua perusahaan (CMP, KAL), dicocokkan dengan ekspor Excel Odoo, plus penagihan/piutang, mutasi bank, ekspedisi, dan pengiriman Email/WhatsApp. PHP 8 + MySQL, vanilla JS, Bootstrap 5.3 lokal (`public/bootstrap/`), tanpa Composer/npm dan tanpa langkah build. Dipasang di hosting cPanel; `tools/storage_api.php` berjalan terpisah di server IIS kantor. Bukan repo git, dan folder induk `PROYEK\` berisi proyek lain (Renamer, ptcmp-erp, dll.) yang tidak berhubungan. Bahasa kode, komentar, UI, dan komunikasi dengan pemilik proyek: Indonesia.

Panduan pemasangan/operasi ada di `PANDUAN.md`; spesifikasi dan tiket migrasi UI di `docs/spec-ui-bootstrap.md` dan `docs/tickets-ui-bootstrap.md`; katalog komponen UI di `docs/PTCMP_UI_COMPONENTS.md`.

## Perintah

Tidak ada PHP di PATH pada mesin pengembangan Windows. PHP portabel ada di scratchpad sesi (`...\scratchpad\php82n\php.exe`); selfcheck memanggil `php` dari PATH, jadi tambahkan folder itu ke PATH dulu (tanpa itu ~110 kegagalan palsu).

```bash
php tools/selfcheck.php --nodb          # pemeriksaan sintaks/struktur tanpa DB (juga menjalankan tools/uji_*.php)
php tools/uji_pt026.php                 # satu uji statis; semua uji = php tools/uji_<nama>.php, exit 1 bila gagal
for f in tools/uji_*.php; do php "$f" | tail -1; done
node --check public/js/ui.js            # sintaks JS (lakukan untuk tiap public/js/*.js yang diubah)
php tools/migrate.php                   # pasang/perbarui skema DB (idempoten, hanya CLI)
python tools/paket/buatzip.py           # bangun update_vX.zip + arsip_vX.zip ke D:/arsip (lihat Rilis)
```

Uji dengan peramban memakai server `php -S` dengan router sesi buatan + MariaDB lokal (tidak ada skrip di repo; dibuat per sesi di scratchpad). Hanya memuat `public/` memakai sesi palsu; API sebenarnya butuh DB.

## Arsitektur

**Backend.** `public/api/*.php` = satu endpoint per area; semuanya `require _boot.php` (sesi, koneksi `$conn`, `jawab()/gagal()/jalankan()`, `paginasi()`, otorisasi). Parameter lewat `?action=`; balasan JSON `{success, ...}` atau `{success:false, error}`. Logika bisnis ada di `src/classes/*.php` (statik, mis. `Penagihan`, `Pelunasan`, `Importer`, `Pindai`, `Akses`). `Akses` memegang hak per peran (SUPER ADMIN / SUPERVISOR / USER × divisi SALES_SUPPORT / FINANCE / SALES), menu yang boleh dibuka, dan `kodeSales` (akun SALES dibatasi ke kode sales sendiri, dipaksa di server, bukan di browser). Operasi mengubah data dapat memicu otorisasi supervisor (`perlu_otorisasi` → popup di `api()`).

**Gagal-aman (5.084, PT-REV-002).** Pemeriksa hak/sesi tidak boleh menelan galat. Query hak di `Akses` lewat `ambilBaris()`; kegagalan apa pun (prepare/execute/get_result false, exception, JSON pengaturan rusak) dilempar sebagai `LayananTakTersedia` (`src/classes/TakTersedia.php`) dan berakhir HTTP 503 `{kode:'tak_tersedia'}` lewat `jalankan()`/`jawab()`/penangan global di `_boot.php`; `Auth::check()` memakai `Auth::takTersedia()` (sesi tidak dihancurkan, `cek_keamanan` tidak diperbarui). Jangan menambah `catch` yang mengembalikan `null`/`[]`/bawaan di jalur hak. 401 = sesi tidak sah, 403 = tidak berhak, 503 = pemeriksa tak jalan. Cache hak berisi `[id akun => nilai]` dan hanya hasil berhasil. Layar Setting memakai `matriksDivisi($conn, true)` / `crudTersimpan($conn, true)` (toleran) supaya isi rusak tetap bisa diperbaiki.

**Secret terenkripsi (5.086, PT-REV-004).** Secret integrasi (`wablas_secret`, `wablas_token`, `wa_token`, `mail_password`, `http_key` di `app_settings`; `wa_device.token`) disimpan sebagai `enc:v1:<versi>:<nonce>:<ct>:<tag>` (AES-256-GCM, AAD = konteks lokasi) lewat `src/classes/Rahasia.php`; kunci di berkas di LUAR folder aplikasi (`../ptcmp-secret/master.key` atau env `ARSIP_KUNCI_RAHASIA`), tidak pernah di DB/ZIP. Baca/tulis secret HARUS lewat `Setting::ambil/simpan`, `WaGateway::setting`, `WaAgen::device*`, `Rahasia::bukaToken/tutupToken`; dekripsi dilakukan di LUAR blok `try` yang menelan `Throwable` (galat = `LayananTakTersedia`, 503). Jangan menambah pembaca `app_settings`/`wa_device.token` langsung. Berkas kunci belum ada = plaintext (transisi); `tools/rahasia.php` (migrasi, validasi, ketat, rotasi, balik-plaintext) mengurus siklusnya; runbook `docs/rahasia-kunci-v5.086.md`.

**Guard metode + CSRF (5.087, PT-REV-005).** `_boot.php` memanggil `Csrf::jagaApi(endpoint, $aksi)` sesudah login dan sebelum kode aksi: GET/HEAD hanya untuk aksi yang tercantum di `Csrf::BACA` (daftar baca per endpoint; selain itu 405), POST wajib token sesi (header `X-CSRF-Token` / kolom `csrf_token`; 403 `kode:csrf`). **Aksi atau endpoint baru yang membaca HARUS ditambahkan ke `Csrf::BACA` dan ke `docs/csrf-inventaris-v5.087.md`** (uji statis memeriksa keduanya); yang tidak terdaftar otomatis wajib POST. Jalur bawaan tanpa `action` yang membaca (mis. `lacak.php?nomor=`) didaftarkan sebagai `''`; `tools/uji_ptrev005.php` mencocokkan SETIAP GET dari `public/js/*.js` dengan BACA, jadi pemanggilan GET baru di JS yang belum terdaftar membuat uji gagal (sebelum ini lolos ke hosting dan menghasilkan "Metode GET tidak diizinkan"). Endpoint yang tidak lewat `_boot.php` harus memanggil `Csrf::jagaApi()` sendiri (`passkey`, `profile`, `login_log`). Form halaman memakai `Csrf::jagaForm()` + `Csrf::field()`; JS memakai `api()` (menambah header sendiri) atau `csrfToken()` untuk `fetch`/form manual. Token tidak pernah di URL. Pengecualian terdaftar: webhook, `share.php`, `pengkinian.php`, `passkey_masuk.php`, `health.php`.

**OTP login (5.089, PT-REV-007).** Kode OTP adalah challenge di tabel `otp_challenge` (hanya hash; status aktif/terpakai/kedaluwarsa/dicabut), dikelola `src/classes/OtpChallenge.php`; `Keamanan::kirimOtp/verifikasiOtp` hanya meneruskan. Terbit dan verifikasi atomik: transaksi yang mengunci baris `users` akun (`FOR UPDATE`), waktu dari `NOW()` database. Batas: 5 salah/kode (dicabut), 10 salah/akun per 15 menit (jeda 15 menit di `users.otp_jeda_sampai`, berakhir sendiri), jarak kirim 60 dtk, 5 kode/jam. **Jangan** menulis ke `users.otp_kode` lagi, jangan menghitung waktu di PHP, dan jangan memverifikasi/menerbitkan kode di luar `OtpChallenge`. Migrasi `php tools/migrate.php` wajib sesudah memasang; alat `php tools/otp.php status|lepas-jeda <email>`. Kontrak: `docs/otp-challenge-v5.089.md`.

**Inbox webhook (5.092, PT-REV-010).** `public/wablas_menu.php` (menu WhatsApp `/nota`) menyimpan pesan yang lolos pemeriksaan ke tabel `wa_inbox` (`WaInbox::terima`, satu INSERT, kunci unik provider+device+event) SEBELUM menjawab 200 kosong; gagal simpan = 503 kosong; duplikat = 200 kosong tanpa pekerjaan. Pemrosesan lewat `WaInbox::olah` (klaim atomik `WHERE status = 'accepted'`) dan worker `php tools/wa_inbox.php jalankan` (cron cPanel setiap menit disarankan; webhook berikutnya memulihkan secara oportunistik). Status `accepted -> processing -> succeeded|failed|unknown`; `processing` yang lease-nya habis menjadi `unknown` dan **tidak pernah diulang** (efek kirim bisa ganda). **Jangan** memproses pesan di dalam endpoint atau mengembalikan `processing` ke `accepted`; jangan menyimpan token di tabel/log. Nomor HP dan teks hanya selama belum selesai; baris dihapus sesudah 14 hari. Kontrak: `docs/webhook-inbox-v5.092.md`.

**Outbox pengiriman WhatsApp (5.093, PT-REV-011).** Pesan WA yang dimulai aplikasi (balasan bot `/nota` dan tombol Kirim WA di `kirim.php` aksi `wa`) dicatat di tabel `wa_outbox` dengan KUNCI OPERASI unik (bot: `bot:<id inbox>:<urutan>`; manual: `op_key` dari browser + indeks) SEBELUM menyentuh Wablas, lewat `WaOutbox::kirim($conn, $opsi, $fn)` / `WaOutboxBot` / `kirimWaSatu`; `$fn` adalah satu-satunya tempat yang memanggil `WaGateway::kirim*`. `WaGateway::kirim*` mengembalikan `kelas` (`pasti-gagal` = tidak sampai/ditolak tegas, `tidak-pasti` = timeout/putus sesudah koneksi, 5xx, bukan JSON), `sebagian`, `msg_id`. Status `queued|processing|accepted|failed|unknown`; `accepted` = DITERIMA PENYEDIA (bukan sampai ke ponsel); `sent`/`delivered` tidak dipakai (belum ada kontrak webhook status). Hasil tidak pasti (dan `processing` yang lease-nya habis) = `unknown` dan **tidak pernah diulang otomatis**; keluar hanya lewat `php tools/outbox.php selesai <id> diterima|belum "alasan"`. Retry otomatis hanya bot, hanya teks, hanya gagal pasti, 3x (jeda 60/300/900 dtk), dibatalkan bila ada pesan lebih baru ke penerima yang sama; kirim manual tidak pernah diulang otomatis. Nomor penuh dan teks hanya selama belum final; baris final dihapus sesudah 90 hari (`unknown` yang belum diputuskan tidak). Worker ikut `wa_inbox.php jalankan` (tanpa cron baru). **Jangan** mengirim WA baru tanpa outbox, mengembalikan `unknown` ke `queued`, atau mengklaim "terkirim/sampai" tanpa bukti penyedia. Jalur WA lain (Penagihan, Pengkinian, Tim, Sistem) dan email belum memakai outbox. Kontrak: `docs/outbox-v5.093.md`.

**Panel Operasi WA (5.094, PT-REV-012).** Tab "Operasi WhatsApp" di halaman Kirim Dokumen (`kirim.php` aksi `operasi` GET dan `operasi_putuskan` POST; logika di `src/classes/OperasiWa.php`) = tampilan BACA atas `wa_outbox` (bot + manual; manual disambung ke `kirim_log` lewat `outbox_id`, satu baris outbox = satu baris tampil). Hak lihat: Super Admin dan Supervisor semua dalam lingkup perusahaannya; akun lain HANYA kirim manual miliknya; akun dibatasi perusahaan tidak melihat baris tanpa perusahaan. Penerima SELALU tersamar; teks/token/isi PDF tidak pernah dibaca. Satu-satunya aksi tulis: memutuskan `unknown` (Super Admin/Supervisor, alasan wajib, `WaOutbox::putuskan` + Audit `kirim_putuskan`); **tidak ada kirim ulang** dari layar. `wa_outbox` kini punya `kode_perusahaan/nomor/dokumen_id/user_id` (diisi bot PDF dan kirim manual; PDF bot juga mencatat Aktivitas `kirim_bot`); event lama tidak dimigrasikan. **Jangan** menambah jalur kirim di `OperasiWa`, mengembalikan `teks`/`tujuan` mentah, atau membuat sumber status baru. Kontrak: `docs/operasi-wa-v5.094.md`.

**Kebijakan URL keluar (5.095, PT-REV-013).** Semua URL yang diambil/diteruskan menu WA mode kartu (halaman link, gambar jpg/png DAN format lain, link kartu) lewat `src/classes/UrlAman.php`: hanya http/https, tanpa userinfo, port 80/443, host nama DNS bertitik atau IP literal (bentuk ambigu 127.1/2130706433/0x7f.1/localhost ditolak), SEMUA catatan A+AAAA harus publik menurut tabel CIDR eksplisit (bukan FILTER_FLAG), koneksi DIIKAT ke alamat tervalidasi (`CURLOPT_RESOLVE`) + peer diperiksa ulang + tanpa proksi, redirect manual maks 3 dengan validasi ulang tiap tujuan dan larangan turun https->http. Origin publik gambar hasil konversi = `app_settings.mail_app_url` (`WaMenu::basisAplikasi`), **bukan** `HTTP_HOST`; kosong/tidak sah = konversi nonaktif, kartu jatuh ke pesan biasa. Daftar host izin opsional `wamenu_host_izin` (kosong = semua host publik). `ARSIP_UJI_KARTU_LOKAL` hanya dihormati di CLI/cli-server; hook uji `UrlAman::$resolver/$portIzin/$sematUji` jangan dipakai kode aplikasi. **Jangan** memanggil cURL/`file_get_contents` ke URL dari data tanpa `UrlAman::ambil/periksa`, atau membentuk URL publik dari `$_SERVER['HTTP_HOST']`. Kontrak: `docs/kebijakan-url-v5.095.md`.

**Gambar kartu (5.096, PT-REV-014).** Konversi gambar og: dan cache `public/kartu` hanya lewat `src/classes/KartuGambar.php` (dipanggil `WaMenu::siapkanGambar`). Budget diperiksa SEBELUM decode (`getimagesizefromstring`: tipe JPEG/PNG/GIF/WEBP, sisi <= 6000, piksel <= `kartu_maks_mp` (12 MP), rasio <= 6, perkiraan memori vs `memory_limit`); keluaran dibatasi lebar DAN tinggi 1280, divalidasi (FFD8..FFD9, tipe, dimensi), disimpan ATOMIK (`.tmp` + rename). Kesegaran isi 24 jam terpisah dari retensi berkas (`kartu_retensi_hari` 3, min 2); berkas < 48 jam TIDAK PERNAH dihapus; batas 300 berkas / 150 MB menghapus yang tertua di luar jaminan, bila masih penuh konversi baru ditolak (`cache-penuh`, kartu jatuh ke pesan biasa). Pembersihan hanya menyentuh `<32 heks>.jpg` dan `.tmp` basi; dry-run kecuali `--ya`: `php tools/kartu.php status|bersih|bersih-lama|atur`. **Jangan** memanggil `imagecreatefromstring`/`imagejpeg` pada gambar dari URL tanpa `KartuGambar::konversi`, atau menulis ke `public/kartu` tanpa `KartuGambar::simpan`. Kontrak: `docs/kartu-cache-v5.096.md`.

**Matriks hak akses (5.097, PT-REV-015).** Baseline hak (role x divisi x perusahaan x menu x CRUD x kode sales x status) dan keputusan terbuka D1..D8 ada di `docs/akses-matriks-v5.097.md` (tabel probe 247 aksi x akun dihasilkan dari stage; ulangi bila menambah aksi API). **Jangan mengubah hak bisnis tanpa keputusan tertulis pemilik** (AC-01). Akun tanpa divisi: kebijakan `app_settings.akses_divisi_kosong` (`semua` = bawaan/perilaku v2.6, `minimum` = hanya Dashboard), dibaca lewat `Akses::kebijakanDivisiKosong` (gagal baca = 503, nilai tak dikenal = minimum), diubah Super Admin di Setting > Permission atau `php tools/akses.php kebijakan ...`, tercatat di Aktivitas. Fitur yang disembunyikan UI dari Sales harus ditolak juga di server: `Akses::wajibBukanSales($conn, 'nama fitur')` (kini Mutasi Bank). Peran, Super Admin, dan divisi di sesi disamakan dengan database oleh `Auth::periksaSesi` tiap 20 detik; jangan membaca `$_SESSION['role']`/`is_super_admin` sebagai sumber hak jangka panjang tanpa melalui siklus itu. Perubahan matriks menu/hak CRUD wajib mencatat selisih di Audit (`Akses::selisihMatriks/selisihCrud`).

**Identitas pelanggan (5.098, PT-REV-016).** `kode_pelanggan` adalah identitas GLOBAL (tidak pernah sama antar perusahaan; Importer menolak kode milik perusahaan lain), sehingga `partner_kontak` berkunci kode saja dan `WaMenu::aksesNomor` boleh join tanpa perusahaan. Pencocokan nomor selalu PERSIS lewat `Identitas::kandidatNomor` (62xxxx dan data lama 0xxxx): jangan memakai LIKE, awalan, atau akhiran. Akses bot dihitung ulang di setiap pesan; invoice/PDF dicek ulang pada perusahaan sesi + kode pelanggan hak kontak + status Open. Bila invarian rusak, kebijakan `app_settings.identitas_kode_kembar` (`semua` = bawaan/perilaku lama, `tolak` = kode ambigu tidak memberi akses; tak dikenal/rusak = tolak; gagal baca = pengecualian) lewat `Identitas::sqlHanyaKodeTunggal`; ubah dengan `php tools/identitas.php kebijakan ...`. Perubahan kepemilikan nomor (kontak baru, nomor diganti, dipindah, dinonaktifkan, dihapus, pengkinian, normalisasi) dicatat sebagai `kontak_nomor` dengan nomor disamarkan. Normalisasi massal nomor hanya lewat `php tools/identitas.php normalisasi` (dry-run bawaan, `--ya` menerapkan yang aman saja; tidak menggabung kontak). **Jangan** membuat pemetaan kontak→perusahaan atau memigrasi data tanpa profil `status` dan persetujuan. Kontrak: `docs/identitas-pelanggan-v5.098.md`.

**Buku Ekspedisi (5.099, PT-REV-017).** Catatan `ekspedisi` punya `versi` (INT, naik 1 tiap penulisan). `Ekspedisi::simpan` = SATU transaksi (induk dikunci `FOR UPDATE` + `UPDATE ... WHERE id = ? AND versi = ?` + baris `ekspedisi_promosi`), pembanding `$isi['versi']` (0 untuk nota yang belum dicatat); tidak cocok/hilang = `KonflikEkspedisi` -> endpoint menjawab HTTP 409 `kode: konflik` (tidak ada yang ditulis, catatan terbaru ikut dikirim, izin edit dipertahankan, Audit "konflik simpan"). Deadlock/lock wait (1213/1205) diulang maks 3x. Kegagalan menulis anak membatalkan induk. Field sisi SS/Finance dan kunci izin dihitung dari baris TERKUNCI. **Jangan** menulis ke `ekspedisi`/`ekspedisi_promosi` di luar `Ekspedisi::simpan`, menghapus pembanding versi, atau menggabung field otomatis tanpa aturan tertulis. UI (`ekSimpan`) mengirim `versi` dan menampilkan panel perbandingan saat 409. Kontrak: `docs/ekspedisi-konflik-v5.099.md`.

**Koneksi server kantor (5.100, PT-REV-018).** Semua panggilan ke `storage_api.php` (IIS kantor) lewat `HttpStorage::curl`, yang memakai `src/classes/StorageTls.php`: alamat divalidasi SEBELUM `curl_init` dan sebelum Kunci API dipakai (`https`, tanpa userinfo, host DNS sah atau IP literal, bentuk IP ambigu ditolak, port 443/8443 + `storage_port_izin`), verifikasi sertifikat WAJIB (rantai, masa berlaku, nama host), redirect tidak pernah diikuti (3xx = galat). Perbaikan yang sah hanya pin kunci publik (`http_pin`, `sha256//..`) atau CA kantor (`http_ca`, berkas PEM di `config/`) lewat `php tools/storage.php status|periksa|pin|ca|port-izin|cabut-transisi` (CLI, DRY-RUN kecuali `--ya`, tercatat di Aktivitas); layar web TIDAK dapat melonggarkan kebijakan dan tidak dapat lagi menyalakan "abaikan sertifikat" (`http_insecure`). Konfigurasi lama yang abaikan-sertifikat/`http://` hidup 14 hari (`storage_insecure_batas`, dicap `migrate.php` sekali), tanpa cap = tidak dihormati. Kunci tersimpan hanya dikirim ke alamat (skema+host+port) yang sama; alamat berubah membuang kunci dan pin lama. Pesan ke pengguna = kategori aman (`StorageTls::pesan`); **pesan galat bisnis tidak boleh memuat `.php`, `https://` (`s:/` cocok pola drive-letter), `curl` dll.** karena `GalatAman::bisnis` menggantinya dengan "kode referensi". **Jangan** memanggil cURL ke server kantor di luar `HttpStorage::curl`, mengirim `$e->getMessage()` cURL mentah, atau menambah jalur yang mematikan `CURLOPT_SSL_VERIFYPEER`. Kontrak dan runbook pemulihan: `docs/storage-tls-v5.100.md`.

**IP klien dan skema HTTPS (5.101, PT-REV-019).** SATU resolver: `Jaringan::ip($conn)` dan `Jaringan::https()` (`src/classes/Jaringan.php`); whitelist, log login, `Audit::catat`, `Otorisasi`, `share.php`, `Pengkinian`, cookie sesi/perangkat/"Ingatkan Saya", HSTS, dan origin passkey memakainya. **Jangan** membaca `HTTP_X_FORWARDED_FOR`, `HTTP_X_FORWARDED_PROTO`, `HTTP_CF_CONNECTING_IP`, `HTTP_X_REAL_IP` di tempat lain (uji `uji_ptrev019` memindai seluruh pohon) dan jangan memakai `REMOTE_ADDR` mentah untuk log/akses (kecuali daftar kecuali di uji). Header proxy dibaca HANYA bila `app_settings.ip_proxy = 1`, konfigurasi sah, dan peer langsung ada di `ip_proxy_peers` (IP/CIDR; diatur lewat `php tools/proxy.php peers|header|aktifkan|matikan|uji|status`, CLI, DRY-RUN kecuali `--ya`, bukan layar web); satu sumber `ip_proxy_header` (`xff` bawaan | `cf` | `real`); `X-Forwarded-For` dibaca dari kanan melewati hop tepercaya; rantai rusak = IP peer; konfigurasi rusak (`ip_proxy = 1` tanpa peer, `/0`, header tak dikenal) = header DIABAIKAN + terlihat di layar Akses IP dan preflight. `X-Forwarded-Proto` hanya dari peer tepercaya, elemen pertama, hanya menaikkan ke HTTPS (tidak pernah menurunkan). Kontrak, cara pasang, dan pemulihan: `docs/proxy-jaringan-v5.101.md`.

**Penerapan web (5.102, PT-REV-020).** Header dasar (X-Frame-Options, nosniff, Referrer-Policy, Permissions-Policy, HSTS bila HTTPS) dikirim PALING AWAL lewat `Keamanan::headerDasar()` (tanpa DB, tanpa syarat) di `Auth::boot` (sekali per permintaan, sebelum gerbang IP/DB) dan di halaman publik tanpa sesi (`share.php`, `pengkinian.php`, `health.php`, stub `setup.php`); halaman publik baru yang tidak memanggil `Auth::boot` WAJIB memanggilnya. `Keamanan::header($conn)` menambahkan HSTS menurut resolver proxy dan CSP; `sec_header = 0` (Setting > Keamanan) menarik header, kegagalan membaca konfigurasi tidak. CSP (`Keamanan::CSP`) bawaan **Report-Only** (`sec_csp = report`), HANYA untuk dokumen HTML (TIDAK dikirim pada `/api/` karena PDF inline/unduhan), `'unsafe-inline'` tetap ada karena >200 atribut `on*=` dan >150 `style=` di `index.php`; laporan masuk ke `public/csp_laporan.php` (tanpa sesi/DB, 204 selalu, batas laju/ukuran, log tersanitasi di `src/log/csp-*.log`); enforce hanya lewat `php tools/web.php csp enforce --ya` (ditolak bila ada laporan 7 hari). **Installer web dinonaktifkan**: `public/setup.php` = stub 410; `tools/migrate.php` hanya CLI; pemasangan lewat `php tools/migrate.php` dan `php tools/buat_superadmin.php`. Pengerasan web root: `.htaccess` "deny all" di `docs/` dan folder non-publik (`config`, `src`, `tools`, `database`, `vendor`); **JANGAN memberi `.htaccess` tolak-semua di AKAR aplikasi**: LiteSpeed (hosting ini) membaca `.htaccess` di folder di atas document root, sehingga seluruh situs 403 (kejadian nyata 5.102 awal; `tools/web.php periksa` dan preflight menandai GAGAL); blok `ARSIP-PENGERASAN` di `public/.htaccess` dipasang oleh `php tools/web.php htaccess --ya --url=https://domain` (paket update TIDAK menimpa `public/.htaccess` hosting yang berisi blok cPanel; alat menguji dan memulihkan otomatis). Verifikasi hosting: `php tools/web.php periksa --url=https://domain`. **Jangan** menambah pembaca `Content-Security-Policy` per halaman atau mengirim CSP pada respons `/api/`. Kontrak dan runbook: `docs/penerapan-web-v5.102.md`.

**Penyisipan script inline (5.120, PT-AUD-002).** `src/classes/SkripAman.php` (kontrak `docs/xss-inline-skrip-v5.120.md`; tanpa migrasi). Setiap nilai PHP yang masuk ke blok `<script>` inline WAJIB lewat `SkripAman::json()` (flag `JSON_HEX_TAG|AMP|APOS|QUOT`); parameter URL pemuat (`?go=`, `?kode=`) WAJIB lewat `SkripAman::rute()` (allowlist: go `[a-z0-9-]{1,40}`, kode `[A-Z0-9_-]{1,10}`; selainnya kosong). **Jangan** menulis `json_encode` polos di dalam `<script>` atau membaca `$_GET['go']`/`$_GET['kode']` langsung di halaman. Catatan audit: klaim "`</script>` menutup tag" TIDAK terbukti (json_encode default meng-escape garis miring); celah nyata adalah `<!--`/`<script` yang tetap mentah. Uji: `tools/uji_ptaud002.php` dan kasus `XSS-01` (HTTP sungguhan, termasuk nama pengguna dari database dengan kontrol positif).

**Higiene rahasia (5.119, PT-AUD-001).** `src/classes/Higiene.php` + `tools/higiene.php` (CLI; kontrak dan runbook rotasi `docs/higiene-rahasia-v5.119.md`; tanpa migrasi). Audit 29-10-2026 menemukan ZIP FOLDER HOSTING (bukan paket rilis) berisi kredensial DB, sesi, PDF sementara, log; paket rilis sudah berpagar (`rilis_lib.py`), jadi alatnya untuk folder hosting: `periksa` (config lama dengan `die()`: paket update memakai `-x 'config/*'` sehingga config hosting TIDAK ikut diperbarui; kredensial literal; sesi/PDF/log tertinggal; zip/sql/bak, di `public/` = GAGAL; kunci di pohon; hasilnya ikut `preflight_rilis.php`), `sesi-cabut [--ya] [--semua]` (bawaan hanya sesi basi > 12 jam), `temp-bersih` (PDF > 3 hari), `izin` (chmod 640 config + `public/kartu/.htaccess`), `config-pindah` (kredensial ke `../ptcmp-secret/database.php` izin 600, uji koneksi, pulih otomatis), dan `ekspor <zip>` (ALLOWLIST positif + pemindai isi dengan aturan yang sama dengan `rilis_lib.py`; tujuan di luar folder aplikasi, tidak menimpa). Semua DRY-RUN kecuali `--ya`; nilai rahasia tidak pernah dicetak (hanya jalur:baris dan aturan). Template `config/database.contoh.php` membaca kredensial berurutan: `ARSIP_DB_*` > berkas luar > literal; galat koneksi generik. **Jangan** menaruh kredensial nyata di `config/` atau repo, men-zip folder hosting untuk dibagikan, atau menambah jalur ekspor tanpa allowlist. Uji: `tools/uji_ptaud001.php` (pohon sementara + uji kepekaan lewat `ARSIP_UJI_HIGIENE_KELAS`).

**Laporan Operasional Terjadwal (5.118, PT-REV-036).** `src/classes/LaporanTerjadwal.php` + `public/api/laporan.php` + `public/js/laporan.js` + `tools/laporan.php` + empat tabel `laporan_jadwal/_penerima/_run/_kirim` (WAJIB `php tools/migrate.php`; kontrak `docs/laporan-terjadwal-v5.118.md`). Ringkasan harian (hanya ANGKA: Perlu Tindakan Saya per kategori + terlambat, Kualitas Data bagi Supervisor/Super Admin) lewat EMAIL ke akun yang dipilih Super Admin per jadwal, dikirim dari putaran dasar `tools/monitor.php` (tanpa cron baru, tanpa daemon). Satu jadwal + satu periode (tanggal WIB) = satu `laporan_run` (kunci unik + `INSERT IGNORE` = klaim atomik): cron paralel/restart tidak mengirim ganda. Isi dihitung per penerima SAAT kirim dari akun di database (bukan sesi) memakai kelas sumber yang sama dengan Dashboard (`Worklist::ringkasan`) dan Kualitas Data; akun nonaktif/kehilangan akses/divisi Sales dilewati (`dilewati`). Waktu selalu WIB. Terlambat <= 6 jam = dikirim sekali bertanda terlambat, lebih dari itu `dilewati` (tidak ada banjir). Jejak kirim gaya outbox (`diproses -> diterima | gagal | tak_pasti | dilewati`): **tidak ada pengulangan otomatis**, `tak_pasti` (proses terhenti > 15 menit) TIDAK PERNAH diulang, kirim ulang hanya eksplisit Super Admin (alasan wajib, hanya `gagal`, maks 3). Uji kirim hanya ke email Super Admin yang menekan tombol; tidak ada jalur ke pelanggan. Jadwal baru nonaktif; tidak ada hapus jadwal; riwayat 12 bulan (`bersihkan`). **Jangan** menambah jalur kirim di kelas selain `kirimSatu` (satu `->send(`), mengirim ulang otomatis, memakai `$_SESSION` di kelas, atau memuat nomor dokumen/nama pelanggan/lampiran ke email. `--sekarang` di `tools/laporan.php` hanya dihormati bila `ARSIP_REGRESI=ya`. Suite: LAP-01..05 (90 kasus), 10 RUSAK `laporan_*`; uji statis `tools/uji_ptrev036.php`. Catatan suite: server A = staging (memblokir email), server B = non-staging dengan SMTP tiruan: aksi HTTP yang mengirim email memakai `L.akun(nama, 'b')`.

**Saved Views (5.117, PT-REV-035).** `src/classes/TampilanSimpan.php` + `public/api/tampilan.php` + `public/js/tampilan.js` + tabel `tampilan_simpan` (WAJIB `php tools/migrate.php`; kontrak `docs/saved-views-v5.117.md`). Tombol Tampilan di kepala sembilan halaman daftar kerja (`TampilanSimpan::HALAMAN`; Keamanan/Setting/Dashboard TIDAK). Tampilan = pengisi filter PRIBADI (akun + perusahaan; tidak ada shared) berisi `{f, m}` TANPA halaman/gulir/tab; ia tidak memperluas hak karena data tetap diminta lewat API biasa yang memaksa hak, perusahaan, dan kode sales. Validasi otoritatif di server (`TampilanSimpan::aturan/validasi`): allowlist kunci per halaman + tipe nilai + penolakan teks bernada SQL/token; halaman harus lolos `Akses::menu`; SEMUA query memakai `user_id` dan `kode_perusahaan` (id milik orang lain = "Tampilan tidak ditemukan." seragam, juga untuk Super Admin). Status `baik|usang|rusak` dihitung saat dibaca; hanya yang `baik` dikirim isinya, dapat dipakai, dan dapat jadi default (satu per ruang lewat kunci unik `bawaan_kunci`). Menerapkan tampilan = menulis konteks sesi (`konteks.js` `terapkanTampilan`) lalu `showPage(h, {pulih:true})`, jadi nilai tak sah dibuang validator konteks; default (`K.setBawaan`) dipakai `pulihkan` HANYA bila tidak ada konteks sesi. **Halaman daftar baru yang perlu tampilan tersimpan**: tambahkan ke `TampilanSimpan::HALAMAN` + `aturan()` + `TP_HALAMAN` di tampilan.js + `HALAMAN_KONTEKS`/`ADAPTER` di konteks.js; **jangan** menyimpan token, isi PDF, atau SQL di isi tampilan, dan jangan menyentuh URL dari tampilan.js. Suite: TPL-01..05 (85 kasus), 10 RUSAK `tampilan_*`; uji statis `tools/uji_ptrev035.php`, perilaku konteks `node tools/uji_ptrev035.js`.

**Pusat Kualitas Data (5.116, PT-REV-034).** `src/classes/KualitasData.php` + `public/api/kualitas.php` + `public/js/kualitas.js` + halaman `page-kualitas` (sidebar Admin; peran Supervisor/Super Admin, BUKAN matriks menu) + tabel `kualitas_plan` / `kualitas_plan_item` / `kualitas_tinjau` (WAJIB `php tools/migrate.php`; kontrak `docs/kualitas-data-v5.116.md`). Lima kategori dengan SATU definisi (`KualitasData::daftar`; ringkasan memakai total daftar yang sama, `invoice_tanpa_pdf` = kondisi `Worklist`). Perbaikan HANYA lewat dry-run (`rapikan_kontak`, `cocokkan_ulang`, `tandai_ditinjau`) dan hanya pada data milik aplikasi: **jangan** menyentuh `partner`/`invoice`/`surat_jalan` (cerminan Odoo: muat ulang lewat Import) dan **jangan** menghapus duplikat (satu-satunya tindakan = "ditinjau"). `buatPlan` hanya menulis tabel `kualitas_*` (dijaga checksum di KUA-02); `komit` (Super Admin saja) menolak SEBELUM efek bila plan bukan milik perusahaan, kedaluwarsa (24 jam), atau sidik sumber berubah (`basi`); diproses per batch 50, status item = checkpoint, klaim atomik (`berjalan`, klaim basi 10 menit dapat dilanjutkan), tiap item divalidasi ulang terhadap `sebelum` dalam transaksi batch. Kompensasi `kembalikanPlan` (kontak, tinjau); riwayat 12 bulan dibersihkan `KualitasData::bersihkan` (monitor.php). Nomor telepon di tampilan plan tersamar. Suite: KUA-01..05 (80 kasus), 10 RUSAK `kualitas_*`; uji statis `tools/uji_ptrev034.php`.

**Meja Koreksi OCR (5.115, PT-REV-033).** `src/classes/Koreksi.php` + `public/api/koreksi.php` + `public/js/koreksi.js` + panel `sp-pindai-koreksi` (WAJIB `php tools/migrate.php`: kolom `dokumen.versi`, tabel `dokumen_koreksi`; kontrak `docs/koreksi-ocr-v5.115.md`). Hanya nomor + jenis yang dikoreksi; pelanggan/tanggal/sales SELALU dari data Odoo (`Pindai::dataNomor`) sehingga koreksi tak bisa menghubungkan dokumen ke perusahaan/pelanggan lain; nomor tanpa data, berprefiks perusahaan lain, atau bentrok dengan arsip lain ditolak (tidak pernah menimpa / `_diganti`). Isi berkas (sha256) tidak berubah; berkas diganti nama dan dikembalikan sendiri bila langkah sesudahnya gagal. Antrean (hak Ubah Pindai Scan) dijaga sidik berkas `snap` + klaim; arsip tersimpan (Supervisor/Super Admin) dijaga `dokumen.versi` + nomor sebelumnya; salinan basi = HTTP 409 `konflik`. Setiap koreksi menulis `dokumen_koreksi` (sebelum/sesudah, alasan 5-300, pelaku, versi); Kembalikan = baris baru (`kembali_dari`, unik), riwayat tidak pernah diubah/dibuang; hanya koreksi terbaru, dan asal-antrean ditolak bila dokumen sudah pernah dikirim. Tanpa angka confidence. Suite: KOR-01..05 (80 kasus), 10 RUSAK `koreksi_*`.

**Janji bayar dan pengecualian pengingat (5.114, PT-REV-032).** `src/classes/Janji.php` + tabel `janji_bayar` / `janji_log` / `tagih_kecuali_log` (WAJIB `php tools/migrate.php`; kontrak `docs/janji-bayar-v5.114.md`; aksi `janji_*` dan `kecuali_*` di `public/api/penagihan.php`, tab di `public/js/janji.js`). Janji = CATATAN tindak lanjut, **bukan pembayaran**: tidak ada jalur yang menulis `invoice`, `pelunasan_nota`, atau status lunas; sumber keuangan hanya `invoice.status` ('Paid') dan `pelunasan_nota` jenis bayar+potongan (sama dengan `Pelunasan::terbayarLain`). Kondisi (menunggu/sebagian/terpenuhi/terlewat/ditutup) DIHITUNG (`Janji::kondisi`, uang masuk sejak `terbayar_awal`), tidak disimpan dan tidak menutup janji sendiri; predikat terlewat satu SQL (`Janji::sqlTerlewat`) untuk daftar dan Worklist (`janji_terlewat`, tidak untuk divisi Sales). Satu janji AKTIF per nota (kunci unik `aktif_nomor`, NULL sesudah ditutup); yang mengubah hanya Finance/Supervisor/Super Admin, Sales hanya melihat (pembatas kode sales di server); dua editor dijaga `versi` (`KonflikJanji` -> HTTP 409); jumlah/tanggal wajib beralasan; semua tercatat di `janji_log`. Janji aktif menunda pengingat untuk NOTA itu sampai tanggal + 1 hari (`Penagihan::terbuka` `janji_sampai`, dilewati di `antrean`). Pengecualian pengingat (`tagih_kecuali`) lewat `Janji::kecualiSimpan/Hapus`: alasan 5-120 dan tanggal berakhir WAJIB (maks 30 hari), tercatat di `tagih_kecuali_log`; yang lama tanpa tanggal ditandai 'data lama' dan tetap berlaku. **Jangan** menulis `tagih_kecuali` di luar `Janji`, menambah jalur yang mengubah saldo/status dari janji, atau membuat pengecualian tanpa batas. Riwayat punya sumber `janji` (PRIO 120, jenis 'janji'). Uji: `tools/uji_ptrev032.php` dan kasus JNJ-01..05.

**SLA serah terima SS -> Finance (5.113, PT-REV-031).** `src/classes/Sla.php` + tabel `ekspedisi_sla` / `sla_log` / `sla_libur` (WAJIB `php tools/migrate.php`; kontrak `docs/sla-serah-terima-v5.113.md`). SLA hanya MENGHITUNG, MENAMPILKAN, dan MENGINGATKAN: selesai = `ekspedisi.approve_at` (tabel SLA tidak punya status selesai; jangan menambahkannya) dan **tidak ada jalur SLA yang menulis ekspedisi** selain kait `Sla::mulai` di dalam transaksi `Ekspedisi::simpanSekali` saat catatan BARU dibuat. Tenggat = 2 hari kerja (18 jam kerja, Sen-Jum 08-17 WIB, minus `sla_libur`) dari `input_at`, **disimpan** bersama `versi_kalender`: mengubah libur/parameter menaikkan versi tetapi TIDAK menggeser item berjalan; menghitung ulang hanya lewat `sla_hitung_ulang` / `php tools/sla.php hitung-ulang --ya` (Super Admin, tercatat per item, melewati item yang pernah ditunda). PIC (Finance) dan tunda (alasan wajib, maks 5 hari kerja dari hari ini, maks 3 kali kecuali Super Admin) tercatat di `sla_log`; semua perubahan memeriksa status sumber di DALAM kunci baris. Eskalasi (`Sla::eskalasi`, dipanggil putaran dasar `tools/monitor.php`, tanpa cron baru): email ringkasan ke Super Admin + Supervisor ber-menu Buku Ekspedisi, tingkat 1 dan 2 masing-masing SEKALI, klaim atomik (`UPDATE ... WHERE eskalasi_level < ?`) sebelum kirim, klaim DIKEMBALIKAN bila email gagal (jangan dibuang), `sebelum_sla = 1` tidak pernah dieskalasi. Perlu Tindakan Saya (kategori menunggu_finance) memakai `tenggat_at` untuk Terlambat (kolom `tenggat/pic/sebelum_sla/tunda_kali` ada di SEMUA cabang UNION); Riwayat punya sumber `sla` (PRIO 110) yang TIDAK ditampilkan ke akun Sales (`$tanpaSla`). Uji: `tools/uji_ptrev031.php` dan kasus SLA-01..05.

**Riwayat kejadian terpadu (5.112, PT-REV-030).** Bagian "Riwayat kejadian" di Lacak Dokumen (di bawah garis waktu nota dan daftar nota pelanggan; `public/js/riwayat.js`, `lacak.php?action=riwayat`, logika dan SQL di `src/classes/Riwayat.php`) = proyeksi BACA atas jejak modul sumber: **tanpa tabel/kolom/pencatatan baru** dan garis waktu 6 tahap lama TIDAK diubah. Sepuluh sumber dengan kunci `sumber:id` dan prioritas tetap (`Riwayat::PRIO`): satu kejadian = satu baris (pengiriman manual = `kirim_log` + `wa_outbox` tersambung lewat `outbox_id`, tampil SEKALI; `wa_outbox` hanya yang belum tersambung; `aktivitas_log` hanya DAFTAR PUTIH jenis tanpa sumber lain, jangan memasukkan `lihat`/`download`/`kirim_bot`), urutan `waktu DESC, prioritas DESC, id DESC`. Bukti jujur: `accepted` = "diterima penyedia, belum ada bukti sampai ke ponsel" (tidak ada status delivered di sistem: jangan mengklaimnya), email = diterima server email; data lama diberi label, tidak dikarang. Hak = hak Lacak (menu + perusahaan + kode sales; `Riwayat::periksaNota/periksaPelanggan` menyalin aturan `lacak.php`, dijaga RWY-04: ubah keduanya bersama); penerima tersamar kecuali Supervisor/Super Admin. Sumber baru (mis. tindak lanjut PT-REV-032) = cabang di `Riwayat::cabang` + `PRIO` + kasus RWY + `docs/riwayat-v5.112.md`. Uji: `tools/uji_ptrev030.php` dan kasus RWY-01..05.

**Perlu Tindakan Saya (5.111, PT-REV-029).** Bagian Dashboard (`#dashWorklist`, `public/js/worklist.js`, `dashboard.php?action=worklist`, logika dan SQL di `src/classes/Worklist.php`) = proyeksi BACA atas status modul sumber: **tidak ada tabel, kolom, cache, atau penugasan per orang** (jangan menambahkannya; "selesai" = status sumber berubah, bukan penanda sendiri). Empat kategori (`Worklist::KATEGORI`: scan gagal dan invoice tanpa PDF = Sales Support; menunggu Finance = Finance; pengiriman WA gagal/belum pasti = pengirim + Supervisor) dengan batas terlambat 3/7/3/1 hari; keputusan pemilik di `docs/worklist-v5.111.md`. Aturan: tiap kategori adalah SATU potongan SELECT (`Worklist::cabang`) yang dipakai untuk COUNT dan daftar (UNION ALL; teks dibungkus `CONVERT(... USING utf8mb4) COLLATE ...`), SQL-nya HARUS sama dengan modul sumber (kartu Dashboard, `Ekspedisi::kondisiDaftar`, `OperasiWa::lingkup`); hak = menu sumber + CRUD lihat + perusahaan + kode sales + MASA dipaksa di SQL; sumber yang gagal dibaca = `tersedia = false` (BUKAN 0) dan `LayananTakTersedia` tidak pernah ditelan; tautan hanya `showPage` + `subTabKe`, tanpa filter/token/nomor di URL. Kategori baru = entri `KATEGORI` + cabang SQL + kasus WLS di `skenario.py` (+ kerusakan terkendali bila ada penjaga baru) + `docs/worklist-v5.111.md`. Nama fungsi JS berawalan `wk` (`wl*` milik Master Wilayah). Uji: `tools/uji_ptrev029.php` (statis) dan kasus WLS-01..05.

**Suite regresi bisnis dan inventaris dependensi (5.110, PT-REV-028).** `tools/regresi/` (`jalankan.py` pelari, `pustaka.py` klien/SMTP tiruan/pembuat xlsx dan PDF/lingkungan, `skenario.py` 90 kasus + `RUSAK`, `fixture.php` pengelola DB uji) menjalankan aplikasi SUNGGUHAN (`php -S` dua instance: staging dan produksi dengan SMTP tiruan) di atas salinan pohon dan database `arsip_regresi_<acak>`, lalu memeriksa HASIL bisnis (DB, respons, sha256 berkas, surel): `ARSIP_UJI_PHP=<php.exe> ARSIP_UJI_DB=127.0.0.1:33306 python tools/regresi/jalankan.py [--tulis-hasil|--hanya=KRM|--rusak=semua|--daftar]` (TANPA `-I`; kode keluar 0 lulus, 1 ada GAGAL, 3 prasyarat tidak terpenuhi = BELUM dijalankan, bukan lulus). LNG-03 (kasus terakhir) menggagalkan suite bila log server uji memuat Warning/Notice/Deprecated/Fatal PHP atau galat internal: Warning tidak mengubah respons, jadi tanpa itu bug seperti `$supervisor` yang hilang dari `use` closure `kirim.php` (5.094) lolos dari 48 kasus. Aturan: ekspektasi kasus diturunkan dari fixture dan aturan TERTULIS (`Akses::DIVISI_BAWAAN`, `docs/akses-matriks-v5.097.md`), bukan disalin dari keluaran; kasus yang gagal diperiksa ke kode/dokumen dulu, jangan mengubah ekspektasi agar lulus. Suite tidak pernah menyentuh `config/` asli, DB selain `arsip_regresi_*`, server DB non-loopback (kecuali `ARSIP_UJI_DB_IZIN_JAUH=1`), atau alat destruktif aplikasi (hanya `migrate.php` dan `fixture.php`; `uji_ptrev028.php` memeriksanya). Fitur atau aturan bisnis baru yang menyentuh import/pindai/kirim/Ekspedisi/hak akses WAJIB menambah kasus di `skenario.py` (ID berurutan per alur; kasus dependen memakai `butuh()`), dan kerusakan terkendali di `RUSAK` bila ada penjaga baru (uji kepekaan: kerusakan harus membuat kasus sasaran GAGAL; perlindungan berlapis seperti `Ekspedisi::simpan` perlu semua lapis dicabut). Sebelum membangun paket: jalankan suite dengan `--tulis-hasil`; `buatzip.py` membatalkan paket bila hasil mencatat GAGAL dan mencetak PERINGATAN bila hasil tidak ada/usang (sidik kode runtime berubah) atau ada yang dilewati (`ARSIP_WAJIB_REGRESI=1` membuatnya memblokir). `tools/regresi/hasil_terakhir.json` ikut paket sebagai bukti. Inventaris pustaka, versi, lisensi, sidik pohon, dan advisori bertanggal: `docs/dependensi-v5.110.md`; sidik dikunci di `tools/uji_ptrev028.php`, jadi mengganti isi `vendor/*`, `public/bootstrap`, atau `public/fonts` berarti memperbarui dokumen DAN kunci itu. PHP minimum 8.1 (qrdecoder memakai `readonly`); teruji hanya 8.2.34. Cakupan dan yang belum dicakup: `docs/regresi-v5.110.md`.

**Batas beban API (5.109, PT-REV-027).** `src/classes/BatasBeban.php` memegang angka batas dan pembaca halaman: `paginasi()` di `_boot.php` hanya membungkus `BatasBeban::halaman`, yang MENOLAK nilai tak sah (`limit` 1-1000 atau `all`, `page` 1-999999999; regex berpenanda `D` karena `$` PHP cocok sebelum baris baru) dan tidak lagi memotong diam-diam. `limit=all` = `SEMUA_MAKS` (5.000) baris per halaman; `jawab()` menambah `terpotong` + `batas_semua` lewat `BatasBeban::tandai` dan `api()` di `app.js` menampilkan toast. **Jangan** menaikkan angka itu tanpa mengukur memori (dulu 100.000 = HTTP 500 pada 40-70 ribu baris), menulis pembaca limit/page sendiri di endpoint baru (uji: `function paginasi(` hanya didefinisikan sekali), memotong hasil diam-diam (tandai atau tolak), atau `fetch_all` atas tabel yang tumbuh dengan data tanpa batas: pola yang benar = hitung dulu lalu ambil id halaman dan muat kolom lengkap hanya untuk id itu (`lacak.php` belum_kirim), atau tulis per potongan (`mutasi.php` unduh; maks `EKSPOR_MAKS` 50.000, lebih dari itu DITOLAK). `COUNT` daftar tanpa JOIN kecuali saringan memakainya (`$perluJoin` di `dokumen.php`): JOIN yang tidak dipakai membuat pengoptimal membaca baris penuh (4,6 dtk vs 0,26 dtk pada 70 ribu dokumen). Jalur lama ekspedisi (tanpa limit/offset) ditandai dan dicatat (`src/log/jalur-lama-*.log`), TIDAK dimatikan; keputusannya milik pemilik. `monitor.php --import --pindai` memegang kunci putaran (`putaran-olah.lock`) dan anggaran 600 dtk; ringkasan di `app_settings.beban_olah_terakhir`. Dua indeks aditif `dokumen` (`ix_dok_nomor_aktif`, `ix_dok_belum_kirim`) dibuat `migrate.php` karena pengukuran membenarkannya (EXISTS dokumen menjadi semi-join yang membaca baris penuh). Angka stage hanya sebaik data sintetisnya (satu angka 19,9 dtk ternyata artefak data yang kosong): ukur di hosting dengan `php tools/beban.php status|ukur` (hanya baca). Angka, keputusan, dan yang belum terbukti: `docs/beban-api-v5.109.md`.

**Backup konsisten dan restore drill (5.108, PT-REV-026).** Backup database = `Backup::jalankanDb` (via `php tools/backup.php db`, cron malam `monitor.php --backup`): dump PHP murni (`BackupDb`, tanpa mysqldump) di dalam SATU snapshot (`START TRANSACTION WITH CONSISTENT SNAPSHOT`), gzip, enkripsi AES-256-GCM berbingkai (`BackupSandi`: bingkai ditukar/dipotong/diubah/kunci lain = ditolak tanpa keluaran sebagian), dibaca ulang dan dicocokkan sebelum dianggap sukses, manifest, salinan kedua opsional, retensi 7/4/6 (`pilihHapus`, hanya berkas bernama `arsip-db-*.sql.gz.ars`). Kunci backup di `../ptcmp-secret/backup.key` (env `ARSIP_KUNCI_BACKUP`), folder `../ptcmp-backup` (env `ARSIP_BACKUP_DIR`; **ditolak bila di dalam `public/`**). Riwayat di tabel `backup_run` (jenis db|file|bundel|pulih); `Backup::status` menghitung usang/gagal/hilang/kunci hilang (KRITIS) dan `periksaUsang` mengirim surel sekali per 24 jam per rangkaian masalah, hanya bila backup sudah disiapkan. **Bundel pemulihan** (`bundel-buat`: kunci rahasia + kunci backup + `config/*` + `public/.htaccess`, PBKDF2-SHA256 600.000 + AES-GCM) disimpan OFFLINE; `bundel-uji` membuktikan kuncinya membuka nilai terenkripsi di DB; `bundel-ekstrak` untuk pemulihan total. **Pulihkan** (`pulihkan`, drill) hanya ke database KOSONG yang BERBEDA dari database aktif, kecuali pemulihan total eksplisit (`--tanpa-staging --saya-mengerti` ke database aktif kosong); mode staging menetralkan WA/notifikasi/secret/server kantor (`netralkanStaging`); bukti kunci→ciphertext diambil SEBELUM netralisasi. **Staging tidak mengirim apa pun**: `Lingkungan` (env `ARSIP_LINGKUNGAN` atau `config/lingkungan.flag`; nilai selain `produksi` = staging) memblokir `Mailer::send`, `WaGateway::http`, dan memaksa `Storage::driver` ke lokal; penanda sengaja di LUAR database. **Jangan** menambah jalur kirim email/WA/HTTP ke server kantor di luar tiga titik itu, jangan mencetak kunci/kata sandi/isi bundel, jangan menaruh `lingkungan.flag` di produksi. Uji: `tools/uji_ptrev026.php` (tanpa DB), `ARSIP_UJI_DB=host:port php tools/uji_backup_db.php` (data sulit, snapshot dengan penulis lain, alur lengkap, deteksi usang); runbook, RPO/RTO, dan batas yang belum terbukti di `docs/backup-restore-v5.108.md`.

**Peta CSS dan kontrak adapter daftar (5.107, PT-REV-025).** Yang dimuat aplikasi hanya `bootstrap.min.css` -> `tokens.css` -> `ptcmp.css` (705.724 byte mentah / 110.264 gzip-6); `ptcmp.css` berurutan S (sisa `style.css`) -> A (sisa `arsip.css`) -> P (blok PT-0xx dst.) dan menang lewat URUTAN/kekhususan. Anggaran dijaga `tools/uji_ptrev025.php` (`ptcmp.css` <= 465.000 byte; total dimuat <= 112.000 gzip-6): melampauinya harus disengaja. **Jangan menghapus CSS secara borongan**: `python tools/css_peta.py` memetakan aturan (dipakai / perlu diperiksa manual = kelas dirangkai di JS / tidak dipakai), `--buang S|A|P` membuang HANYA aturan yang SEMUA selektornya tidak ada di kode, satu kelompok per langkah, dengan verifikasi otomatis (aturan sisa, @keyframes, @font-face, variabel, kurung) dan harus dibuktikan A/B gaya hitung pada DOM yang sama lewat `tools/css_runtime.js` (cabut aturan lewat CSSOM, bandingkan ~70 properti semua elemen, muat ulang tiap lebar). Pemindai membuang komentar sumber secara konservatif karena `/*` literal di teks HTML (`.../*</code>`) pernah menelan markup dan membuat `.zona-bahaya` tampak mati: periksa kandidat dengan grep mentah. Salinan beku `style/arsip/auth.css.legacy` ada di `docs/css-legacy/` (BUKAN `public/`). Kontrak urutan muat, pembagian `ui.js` (komponen) / `daftar.js` (adapter resmi `mdLaman`) / modul / `tabelKlien` (daftar lama, sengaja belum dimigrasi) di `docs/kontrak-adapter-daftar-v5.107.md`; peta dan bukti di `docs/peta-css-v5.107.md`.

**UAT tema, responsif, dan fokus (5.106, PT-REV-024).** Cacat tampilan diukur, bukan dinilai mata: `tools/uat_audit.js` (alat pengembang, hanya membaca DOM, TIDAK dimuat aplikasi) disuntikkan ke halaman login pada stage; ukur per halaman x lebar x tema kontras WCAG 1.4.3, isi meluber, target sentuh < 24 px (< 992 px) dan cincin fokus. Aturan yang menentukan sahnya hasil: **muat ulang halaman pada tiap lebar** (renderer tabel/kartu memilih lewat `matchMedia` saat dimuat), **matikan transisi** sebelum mengukur warna, dan **tekan satu tombol keyboard** sebelum mengukur `:focus-visible`. Perbaikan hanya lewat SATU blok `UAT tema dan responsif (5.106, PT-REV-024)` di `ptcmp.css` (di atas PT-029, hanya `var(--app-*)`, tanpa `!important`): halaman legacy yang belum memakai komponen bersama (Kirim, Tim, Import, Data Odoo, About, Aktivitas, Sec-Jam, Setting Permission) mendapat warna teks sekunder/utama dari token, kartu baris tabel gelap <= 768 px, dan cincin fokus `select`/`.limit-select`; aturan legacy (`outline: none`, warna tetap) TIDAK dihapus, kalah lewat kekhususan. Halaman legacy atau kontrol `select` baru WAJIB ditambahkan ke daftar `:is(...)` blok itu atau dimigrasi ke komponen bersama. `tools/uji_ptrev024.php` memeriksa kontras pasangan token di dua tema, aturan blok, dan rilis. Dokumen: `docs/uat-ui-v5.106.md` (metode, matriks, cacat), `docs/hasil-uji-pt-rev-024.md`.

**Menu WhatsApp hanya /nota (5.105, PT-REV-023).** Satu-satunya yang dibalas bot WhatsApp: `/nota` (membuka menu) dan balasan di dalam sesi menu (angka, `/lanjut`, `/kembali`, `/batal`); chat biasa, `/menu`, `MULAI`, label tombol lama, dan angka tanpa sesi TIDAK PERNAH dibalas (`WaMenu::proses`: `$mulai = $cmd === '/nota'`, selain itu `abaikan:bukan-menu`/`abaikan:tanpa-sesi` diam total), dan isi respons webhook (`public/wablas_menu.php`) SELALU kosong. Kode pesan pembuka/sapaan (dibatalkan sejak 5.078) sudah DIHAPUS di 5.105: jangan menambah kembali `pembuka()`, isian `pembuka_*`/`tombol_label`, `$balas`, atau aksi `menu_sapaan_reset`; formulir Template pesan menu hanya memuat isian aktif (`WaMenu::BIDANG` + `link_mode`). Template lama tetap terbaca (kunci tak dikenal diabaikan; kunci lama didaftarkan di `WaMenu::KUNCI_LAMA`), isian lama dari klien lama diabaikan tanpa galat, dan isi lama disalin SEKALI ke arsip `app_settings.wamenu_templat_lama` oleh `simpanTemplat`/`resetTemplat` (tidak pernah dibaca kode). `WaMenu::pilihanDaftar` dipertahankan (item daftar interaktif Wablas berjudul `/nota`). Uji: `tools/uji_ptrev023.php` (perilaku DB palsu), kontrak: `docs/menu-wa-hanya-nota-v5.105.md`.

**Rute URL, konteks kerja, dan scope dialog (5.104, PT-REV-022).** `public/js/konteks.js` (dimuat `index.php` sebelum `tema.js`) memegang tiga hal. (1) Rute: halaman/tab di hash `#/halaman[/tab]` (allowlist: `page-*` yang ada di DOM dan lolos `menuBoleh`; tab dari Penagihan/`SUB_TAB`; hash asing diabaikan); satu navigasi = satu `pushState`, pencatatan tab selama `showPage` ditahan (`mulaiShowPage/selesaiShowPage`), Back/Forward lewat `popstate` memanggil `showPage(h, {pulih:true, dariUrl:true})`; **jangan** memasukkan token, filter, nomor dokumen, atau kode perusahaan ke URL. (2) Konteks: `showPage(name, opsi)` (opsi `pulih`, `reset`, `tab`, `dariUrl`) menyimpan konteks halaman yang ditinggalkan dan memulihkannya SESUDAH `resetFilter` dan SEBELUM pemuat membaca isian; hanya navigasi pengguna yang memakai `pulih:true` (sidebar, tab halaman, Back/Forward, refresh, ganti perusahaan), klik menu yang sudah aktif = `reset:true`, panggilan program lain tetap membuka bawaan. Kunci `sessionStorage` `ptcmp:k1:<akun>:<perusahaan>:<halaman>` (8 jam, berversi, divalidasi saat dipulihkan); modul baru yang daftarnya perlu konteks: tambahkan ke `HALAMAN_KONTEKS` + `ADAPTER` di konteks.js dan pastikan pemuatnya memakai `hal` hasil restore; halaman pengaturan/sensitif TIDAK boleh masuk. (3) Dialog: `bukaModal` membekukan `mdlState.kode` untuk halaman terikat perusahaan (`HALAMAN_PERUSAHAAN`) dan menampilkan lencana; `gantiPerusahaan` menutup dialog terbuka (konfirmasi bila kotor); `api()` menolak penulisan bila kode beku tidak sama dengan `kodeAktif`; server tetap memeriksa hak atas `kode` sendiri. Uji perilaku tanpa peramban: `node tools/uji_ptrev022.js` (DOM palsu); kontrak: `docs/navigasi-konteks-v5.104.md`.

**Passkey dan origin kanonis (5.103, PT-REV-021).** rpId dan origin WebAuthn berasal dari `app_settings.passkey_origin` (alamat resmi; diatur HANYA lewat `php tools/passkey.php origin https://domain --ya`, CLI, DRY-RUN bawaan), bukan dari header Host: bila diatur, `Passkey::rp($conn)` mengembalikan nilai itu apa pun Host-nya; rusak = masuk sidik jari ditolak (gagal-aman); belum diatur = host permintaan (perilaku lama, PERINGATAN di `tools/passkey.php status` dan preflight `--db`). `HTTP_HOST` dibaca di SATU tempat (`Passkey::hostPermintaan`); jangan membentuk origin passkey dari tempat lain, dan semua pemanggil `rp()`/`opsiMasuk()` wajib membawa `$conn`. Verifier tetap buatan sendiri (ES256/RS256, attestation none) dengan batas: clientData maks 4096 byte/JSON kedalaman 8, `crossOrigin` hanya `false`, `topOrigin` ditolak, CBOR kedalaman 8 tanpa kunci ganda/sisa, authData maks 4096, BS tanpa BE ditolak, RSA >= 2048 bit dengan e >= 65537, penghitung `UPDATE ... WHERE sign_count < ?` atomik. **Jangan** melonggarkan salah satunya tanpa menambah fixture negatif di `tools/uji_ptrev021.php`. Reset password dan pendaftaran sidik jari belum mencabut/meminta password ulang (keputusan terbuka). Kontrak dan hasil review: `docs/passkey-origin-v5.103.md`.

**Validator unggahan (5.091, PT-REV-009).** `api/dokumen.php?action=unggah` memanggil `UnggahValidator::periksa()` SEBELUM `Storage::driver`, konversi gambar, atau OCR: galat unggah PHP, ekstensi putih (pdf/jpg/jpeg/png), ukuran, tanda tangan isi cocok ekstensi, PDF tidak terpotong/bersandi dan halaman <= batas, megapiksel dari kepala berkas (tanpa decode). Batas di `app_settings` `unggah_maks_pdf_mb` 30 / `unggah_maks_halaman` 60 / `unggah_maks_gambar_mb` 15 / `unggah_maks_piksel_mp` 50 (plafon keras di `UnggahValidator::BATAS_ATAS`); ukur dengan `php tools/unggah.php profil`. Simpan lewat `Storage::putBaru()` (nama sama tidak pernah menimpa; lokal memesan nama atomik). **Jangan** menambah jalur unggah dokumen yang menyimpan tanpa lewat validator itu, dan jangan memakai `tempnam()` + ekstensi tambahan (meninggalkan berkas yatim). Kontrak: `docs/unggah-batas-v5.091.md`.

**Kuota tautan share (5.090, PT-REV-008).** `public/share.php` (tanpa login) mengonsumsi kuota dengan SATU `UPDATE share_links ... WHERE dicabut = 0 AND (kedaluwarsa IS NULL OR kedaluwarsa > NOW()) AND (? <= 0 OR dibuka < ?)` SEBELUM isi disajikan (kalah = ditolak, tanpa isi). Unit kuota: setiap penyajian isi PDF (Lihat dan Unduh) = 1; halaman keterangan, HEAD, dan penolakan tidak menghitung; Range tidak didukung (satu GET = satu hitungan). Penolakan berstatus HTTP (404/410/405) dan semua jawaban `no-store` + `no-referrer` + `noindex`. **Jangan** menambah jalur yang menyajikan isi tanpa lewat UPDATE itu, dan jangan menaruh token di `aktivitas_log`. Kontrak: `docs/share-kuota-v5.090.md`.

**Tema gelap halaman legacy (5.089).** Halaman yang belum memakai komponen bersama (Kirim, Tim & WA, Import, Data Odoo, About, Aktivitas, Penagihan > Mutasi/Laporan) diberi blok `Perbaikan tema gelap (5.089)` di `ptcmp.css` (di ATAS blok PT-029, di luar daerah blok yang dibekukan ujinya; hanya `[data-bs-theme="dark"] :is(...)`, token `--app-*`). Halaman legacy baru wajib ditambahkan ke daftar `:is(...)` itu (uji `uji_ptrev007` memeriksa lingkupnya) atau dimigrasi ke komponen bersama.

**Kontrak galat aman (5.088, PT-REV-006).** Klien tidak boleh menerima SQL/tabel/jalur/secret/pesan mentah penyedia. Validasi bisnis = `throw new Exception('pesan untuk pengguna')` (Exception polos; dijawab 200 `kode:validasi`); kelas lain (`RuntimeException`, `Error`, `mysqli_sql_exception`) = internal (500 `galat_internal` + kode referensi, detail ke `src/log/galat-YYYY-MM.log`, retensi 12 bulan, baca dengan `php tools/galat.php <kode>`). **Jangan** mengirim `$e->getMessage()` atau `$st->error` ke klien: pakai `GalatAman::pesan($e)`, `GalatAman::dbGagal($st)` / `dbPesan($st)` (uji statis memeriksanya). Setiap API punya `X-Request-ID` buatan server; `jawab()` menyaring teks galat bocor. `Audit::catat` menyimpan `request_id` + `sumber` (endpoint:action dari server; parameter `menu` klien hanya konteks yang divalidasi hak akses); audit gagal ditulis = aksi tetap selesai + `audit_gagal` di respons + baris `kritis`/`audit_gagal` di log server. Detail: `docs/kontrak-galat-v5.088.md`.

**Skema DB.** Didefinisikan di `tools/migrate.php` (CREATE/ALTER idempoten) dan `database/*.sql`; `migrate.php` dijalankan ulang setiap rilis yang menambah skema.

**Frontend.** SPA tanpa framework: `public/index.php` merender seluruh halaman/menu (kondisi per peran lewat PHP) dan memuat JS dalam urutan tetap: `ui.js` → `app.js` → modul (`penagihan.js`, `master.js`, `ekspedisi.js`, `setting.js`, `keamanan.js`, `tim.js`) → `tema.js`. Global bersama dari `app.js`: `api()`, `escapeHtml/escapeAttr`, `fmtRp`, `showPage`, `tabelKlien()` (tabel dengan sort/halaman di memori, keadaan di `tkState`), `bukaModal`. `public/js/ui.js` = namespace `window.PTCMP.ui`: toast, confirm, Offcanvas global (satu instans), `state.empty/error/loading` (skeleton muncul setelah 300 ms), `responsiveRenderer` (matchMedia 992 px), dan komponen bakuan hasil Tagihan (pillTabs, searchBar, filterChip, filterOffcanvas, dataTable, businessCard, pagination, statusPill, progressDots, overflowMenu). Komponen hanya menggambar dan memanggil callback; tidak boleh memuat endpoint, nama kolom domain, atau hak akses.

**Pola modul Tagihan (rujukan untuk modul lain).** Satu pengambil data → satu bentuk data kanonik → dua renderer dipilih matchMedia: tabel ≥ 992 px, kartu < 992 px. `penagihan.js` hanya konfigurasi (`tgQuery`, kolom, aksi + hak akses, debounce 300 ms → `tgMuatDaftar` → `api('penagihan.php?…')`) dan memanggil `PTCMP.ui.*`; paging server-side (limit 25/50/100 + offset), sort hanya mengurutkan baris halaman itu.

**CSS.** Urutan muat wajib: bootstrap → `tokens.css` → `ptcmp.css` terakhir. Sejak 5.082 (PT-039) sisa legacy (`style.css` + `arsip.css`, sudah dipangkas PT-038) berada apa adanya di AWAL `ptcmp.css` (di antara penanda `PT-039 · LEGACY DIPINDAH`), jadi urutan kaskadenya sama; `tools/pindah_css_legacy.py` memindahkannya, salinan beku sebelum pangkas ada di `public/css/*.css.legacy`. Halaman berdiri sendiri (login dll., share, unggah) memuat `ptcmp.css` yang sama, maka ada blok kecil `PT-039 · Penetral` agar mereka tidak ikut aturan legacy. `ptcmp.css` menang lewat urutan, bukan kekhususan: hanya kelas `.ptcmp-*`, warna dari token `--app-*`, tanpa `!important`/`html body`/`overflow-x:hidden` global, tanpa menimpa `.card/.table/.nav/.active/.badge/.dropdown-menu/.pagination/.modal/.offcanvas`. Tema Light/Dark/System lewat atribut `data-bs-theme` (`tema.js`, kunci `ptcmp-tema`); mode gelap Tagihan terlingkup `[data-bs-theme="dark"] #page-penagihan`. Aturan baru disisipkan sebelum blok "PT-013 · Toast dan Modal konfirmasi", bukan ditempel di akhir (beberapa uji memotong berkas dari blok mereka).

## Alur kerja tiket (migrasi UI Bootstrap, PT-001…)

IMPLEMENT → VERIFY → REVIEW → APPROVED → NEXT. Tiket berikutnya baru dikerjakan setelah ada `/implement PT-0xx` eksplisit dan tiket sebelumnya APPROVED. Jangan menjalankan `/review` sendiri. Satu tiket = satu versi di `VERSION` + satu entri `updates.json` (`versi`, `tiket`, `paket`, `tanggal`, `perubahan`, baris ROLLBACK) + satu paket. Perubahan kecil di luar tiket tetap di versi berjalan kecuali pemilik meminta bump. Jangan memindahkan posisi/lapisan UI yang sudah dikenal pengguna tanpa bertanya, dan tandai keputusan yang Anda ambil sendiri di laporan.

## Uji dan kunci hash

`tools/uji_*.php` adalah uji statis (membaca berkas, tanpa DB). Banyak yang mengunci hash 20 karakter `substr(sha256, 0, 20)` atas `ui.js`, `penagihan.js`, `ptcmp.css`, `app.js`, `index.php`, API/kelas penagihan, dan memeriksa struktur lewat regex pada isi berkas. Mengubah berkas terkunci berarti memperbarui kunci/regex di uji terkait secara sengaja (tinggalkan komentar "sebelumnya <hash>"), lalu jalankan seluruh suite. `tools/uji_pt014.php` melarang pemanggil menyentuh internal `mdlState`/`mdl*` modal.

## Rilis / paket

`tools/paket/buatzip.py` menurunkan nama paket dari `VERSION` + kolom `tiket` di `updates.json`, lalu menulis ke `D:/arsip`. Daftar berkas paket update (`update`) ditulis tangan: berkas BARU wajib ditambahkan ke sana, kalau tidak tidak ikut `update_*.zip`. Instruksi pemasangan di cPanel (zip diunggah ke folder aplikasi lebih dulu):

Perintah cPanel SELALU dua blok, masing-masing satu baris (zip diunggah ke folder aplikasi lebih dulu):

1. Pemasangan:
```bash
cd /home/bikinev2/ptcmp-group.id && unzip -o update_v5_XXX_NAMA.zip && php tools/preflight_rilis.php
```
   Bila tiket memuat migrasi, sisipkan `php tools/migrate.php` di antara `unzip` dan `preflight`.

2. Setelah approved:
```bash
cd /home/bikinev2/ptcmp-group.id && rm -f update_v5_XXX_NAMA.zip update_v5_XXX_NAMA.zip.sha256 && php tools/preflight_rilis.php
```

Paket update TIDAK memuat `config/`, jadi jangan memakai `-x 'config/*'` di sana: pola yang tidak cocok bisa membuat `unzip` menganggap gagal, sehingga `&&` berikutnya (preflight) tidak jalan. Paket penuh tetap memakai `-x 'config/*'`.

Sejak 5.083 (PT-REV-001) paket dibangun BERPAGAR (`tools/paket/rilis_lib.py`): jalur runtime/sesi/log/ZIP/kunci/konfigurasi nyata ditolak, isi dipindai (nilai rahasia TIDAK pernah dicetak; pelanggaran = paket dibatalkan), zip jadi diverifikasi ulang, dan `docs/rilis/{MANIFEST.json,README_DEPLOY.md,DILINDUNGI.txt}` + `*.zip.sha256` ikut dibuat. `config/database.php` dan `mailer.php` TIDAK ikut paket (hanya `*.contoh.php`). Uji perilakunya: `python tools/paket/uji_paket.py` (set `ARSIP_UJI_PHP`, `ARSIP_UJI_DB=host:port`, `ARSIP_UJI_MYSQL` untuk kasus pasang-staging); `php tools/preflight_rilis.php [--manifest] [--db]` memeriksa pohon terpasang. Fixture rahasia di uji harus DIRANGKAI saat jalan (bukan literal) agar pemindai tidak menandai berkas uji.

Setiap penyerahan paket memuat tiga bagian: nama ZIP (update, penuh, rollback = paket versi sebelumnya), perintah cPanel dua blok (pemasangan, lalu setelah approved), dan langkah uji konkret di hosting.

## Jebakan

- Hook GateGuard di lingkungan ini menolak edit/tulis pertama per berkas dan `rm -rf`: sebutkan fakta lalu ulangi; pakai folder baru, jangan hapus rekursif.
- Perintah Bash/Python lewat heredoc dapat merusak backslash; untuk kode ber-regex pakai Edit/Write.
- Pane browser tersembunyi membekukan transisi CSS dan tidak mengirim event `matchMedia` nyata; matikan transisi sebelum mengukur warna dan jangan menyimpulkan perilaku `change` dari sana.
- Windows tidak peka huruf: `Penagihan.php` dan `penagihan.php` saling menimpa bila disalin ke satu folder.
- SQL baru belum tentu pernah dijalankan di MySQL sungguhan; uji di MariaDB lokal bila menyentuh query.
