# ARSITEKTUR.md — Fakta Teknis Aplikasi Stok (SPLD)

> **STATUS: ACUAN TEKNIS WAJIB untuk manusia dan AI.**
> Dokumen ini mencatat **kondisi nyata kode**, bukan rencana. Setiap perubahan
> besar wajib memperbarui dokumen ini. Kalau AI menemukan beda antara dokumen
> ini dan kode, **kode yang benar** — lalu perbaiki dokumennya.
>
> Untuk rencana dan keputusan yang belum diambil, lihat
> `docs/RENCANA-MULTI-AREA.md`. Untuk token visual (warna, font, radius),
> lihat `DESIGN.md` di root — itu berlaku untuk seluruh ekosistem ipnu.dev.

---

## 1. Stack nyata (jangan tertukar dengan DESIGN.md)

| Aspek | Kenyataan di proyek ini |
|---|---|
| Backend | Laravel (PHP 8.3), dijalankan lewat Docker |
| Database | **SQLite** di `database/database.sqlite`, tapi hampir semua data duduk di **satu tabel `kv(k, v, updated_at)`** sebagai JSON |
| Frontend | **SPA plain JavaScript** di `public/app.js` (~3.100 baris), bukan Blade |
| Halaman | `resources/spld/index.html` disajikan langsung (docroot `public/`) |
| CSS | **Tailwind v3** yang di-build ke `public/app.css` (`resources/css/input.css` → `npm run build:css`), bukan Tailwind v4 + Vite seperti di DESIGN.md |
| Ikon | Bundel sendiri `public/icons.js` (88 ikon lucide), di-build `npm run build:icons`; **bukan** paket lucide penuh |
| PWA | Service worker `public/sw.js`, konstanta `VERSI` harus dinaikkan setiap perubahan aset besar |
| Data | Portase 1:1 dari aplikasi Cloudflare Workers lama (`src/stock.js`, `src/store.js`) |

**Peringatan untuk AI:** `DESIGN.md` menyebut Tailwind v4, Blade component, dan
`laravel-vite-plugin`. Itu berlaku untuk situs hub ipnu.dev, **bukan** aplikasi
stok ini. Jangan "memigrasikan" aplikasi ini ke Vite/Blade hanya karena dokumen
itu.

---

## 2. Peta data (tabel `kv`)

Seluruh isi aplikasi adalah JSON di tabel `kv`. Kunci yang ada:

| Kunci | Isi | Cakupan |
|---|---|---|
| `spld:meta` | Versi skema (`schema`), jejak migrasi | global |
| `spld:gudang` | Daftar area/gudang: `[{id, name, code, archived}]` | global |
| `spld:items:{gudangId}` | Daftar item satu area, termasuk field `icon` | **per area** |
| `spld:ledger:{gudangId}:{periode}` | Buku besar satu area satu bulan (YYYY-MM) | **per area** |
| `spld:items:archive` | Arsip item lama hasil impor dari MySQL | global |
| `spld:inventory` | Salinan stok awal lama untuk bawa (`carry`) | global |
| `spld:moves` | Log perpindahan/merge antar gudang | global |
| `spld:opencode:key`, `spld:opencode:meta` | Kunci akses mode admin | global |

**Invarian data:**
- Struktur ledger **per periode bulanan**. Jangan diubah ke rentang bebas.
- `Stock::SCHEMA` = versi skema. Menambah migrasi = naikkan konstanta itu +
  tulis langkahnya di `Store::ensureSchema()`. Migrasi lama
  (`migrateLegacy`, `mergeGudangs`) bersifat **sekali jalan** — jangan
  dijalankan ulang atau dimodifikasi tanpa memahami jejaknya.
- `Stock.php` adalah portase 1:1 dari `src/stock.js`. Rumus (periode, matriks,
  validasi saldo, closing, CSV) **sengaja identik**. Kalau ada bug di rumus,
  perbaiki dengan sadar dan catat alasannya — jangan diam-diam menyimpang.

---

## 3. Kontrak API

Daftar lengkap ada di `routes/api.php`. Pola yang perlu diingat:

- Semua endpoint data menerima `?gudang=` dari klien. **Client SPA sudah
  mengirimnya di semua panggilan** (lihat `public/app.js`: `/items`,
  `/ledger`, `/ledger/grid`, `/ledger/opening`, dst).
- **Server saat ini MENGABAikan parameter itu.** `ApiController::resolveGudang()`
  selalu mengembalikan `Stock::GUDANG_SEED[0]['id']` = `'pantry'`. Inilah
  jembatan tunggal yang harus dilewati untuk mendukung banyak area.
- Endpoint yang butuh PIN dikelompokkan di grup `auth:surat`; GET data stok
  bisa diakses tanpa PIN (mode tamu, read-only).
- Penulis data selalu mencatat `created_by`/`updated_by` = konstanta
  `ApiController::USER` (**hardcode `'admin'`** — belum ada model user sungguhan).

---

## 4. Kenyataan multi-area saat ini

Yang **sudah siap**:
- Struktur kunci `kv` sudah per-area sejak awal (`items:{gudang}`,
  `ledger:{gudang}:{periode}`).
- Klien sudah menyimpan `gudangList` + `gudangId` dan menyertainya di semua
  request.
- `/pos` sudah mengembalikan `Store::getGudang()` (daftar area dari database).
- Cetak/PNG/laporan memakai `namaGudang()` sehingga nama area sudah muncul di
  berkas hasil.

Yang **belum siap** (urutan ini = urutan kerja):
1. `resolveGudang()` masih hardcode → semua tulisan menimpa area yang sama.
2. UI tidak punya pemilih area. `app.js` selalu memakai `gudangList[0]` dan
   tidak pernah menyimpan pilihan pengguna.
3. Pilihan area tidak masuk URL (`?gudang=`), jadi tidak bisa dibagikan atau
   di-bookmark.
4. Tidak ada endpoint CRUD area (tambah/edit/arsip area).
5. Tidak ada model user: siapa pun yang lolos PIN bisa mengubah semua area,
   dan identitas penulis selalu `'admin'`.
6. Arsip legacy (`spld:items:archive`, `spld:inventory`) bersifat global —
   belum jelas milik area mana untuk 10+ area ke depan.

---

## 5. Aturan kerja (manusia maupun AI)

1. **Verifikasi setelah setiap perubahan** — perintah yang sama setiap kali:
   ```
   node --check public/app.js
   npm run build:css && npm run check:css
   npm run build:icons
   ```
   `php` tidak tersedia di mesin ini; PHP hanya bisa diperiksa lewat situs
   produksi yang menyajikan direktori ini langsung.
2. **Uji dengan browser sungguhan** tersedia: `node_modules` berisi `playwright`
   + chromium. Data produksi boleh dibaca (GET) untuk mock, tapi **jangan
   menulis data produksi** saat menguji.
3. **Satu perubahan besar = satu fase.** Jangan mencampur migrasi database,
   perubahan API, dan perubahan UI dalam satu langkah besar yang tak
   terbedah.
4. **Dokumen ikut berubah.** Setiap perubahan kontrak (data/API/invarian)
   memperbarui `ARSITEKTUR.md` ini.

---

## 6. Jalur deploy

- Direktori ini disajikan langsung oleh server produksi
  (`https://stok.ipnu.dev`), jadi **setiap perubahan file langsung aktif**.
- HTML/CSS distempel `?v=<mtime>` oleh `PageController`, jadi perubahan aset
  langsung terbawa setelah refresh.
- Service worker menyimpan `icons.js` cache-first; naikkan `VERSI` di
  `public/sw.js` kalau bundel ikon berubah supaya PWA yang sudah terpasang
  cepat memperbarui.
