_Dokumen Perancangan Sistem Skala Enterprise & Smart Farming_

Sebagai analis sistem dan perancang arsitektur perangkat lunak, dokumen ini merumuskan desain end-to-end terpadu yang modern. Desain ini di-upgrade untuk mengakomodasi kebutuhan manajemen peternakan ayam masa kini, termasuk IoT (Internet of Things) untuk Smart Farming, analisis finansial yang lebih presisi, arsitektur PWA offline-first, dan notifikasi real-time via WhatsApp.

---

## 📐 1. ANALISIS SISTEM & MODUL UTAMA

### 1.1 Lingkup & Modul Inti

Sistem ini membagi fungsionalitas menjadi beberapa pilar utama:

1. **Manajemen Inti & SDM:** Autentikasi JWT, RBAC (Role-Based Access Control) multi-level (Admin Utama, Manajer Farm, Supervisor Kandang, Admin Gudang, Dokter Hewan, Pekerja Kandang).
2. **Manajemen Multi-Kandang & Master Data:** Pendataan blok farm, kandang (Open House/Closed House), tipe ayam (Broiler/Layer), dan standar target performa (FCR mingguan).
3. **Siklus Produksi (Batch Management):** Manajemen lifecycle (DOC masuk, masa brooding, rearing, prep, hingga panen/deplesi).
4. **Daily Recording & Smart Farming (IoT):** Pencatatan manual (pakan, minum, bobot sampel, mortalitas, dan hasil telur untuk Layer) serta berintegrasi dengan data sensor IoT (suhu, kelembaban, amonia, status kipas/heaters).
5. **Kesehatan & Biosecurity:** Jadwal vaksinasi otomatis, rekam medis pengobatan flock, pembersihan sanitasi, dan mitigasi wabah penyakit.
6. **Supply Chain & Inventory:** Dukungan logistik multi-gudang (gudang sentral perusahaan vs gudang stok kandang), mutasi stok, sistem sinkronisasi stok riil, serta alert _low-stock_.
7. **Keuangan & Akuntansi Costing:** Kalkulasi HPP (Harga Pokok Penjualan) secara dinamis per siklus/batch. Mencakup pembebanan langsung (Cost of Goods Sold: DOC, pakan, medikasi) dan perhitungan pembagian BOP (Biaya Overhead Pabrik: listrik, tenaga kerja).
8. **Panen & Penjualan (Sales):** Modul akhir masa rearing, input rekam tangkap panen (grading berat), penyesalan / persentase defisit, dan manajemen piutang pembeli.

### 1.2 Kebutuhan Non-Fungsional (NFR)

- **Aksesibilitas (PWA Offline First):** Sangat kritis. Karena sinyal seluler di dalam kandang area rural sering terputus, PWA dengan `Service Worker` + `IndexedDB` untuk caching draft input harian pekerja kandang (sinkronisasi akan dilakukan saat devicenya kembali online).
- **Performa & Responsibilitas API:** Skalabilitas untuk query dataset puluhan ribu record dari IoT sensor. Limitasi < 500ms respon API.
- **Notifikasi Push/WA:** Menggunakan WhatsApp API API (Fonnte/Wablas) untuk notifikasi bahaya (contoh: pemadam listrik di kandang tipe closed house, suhu drop, stok pakan kritis di akhir pekan).

---

## 🏗️ 2. ARSITEKTUR TINGKAT TINGGI

Sistem dirancang sebagai **Micro-Service Ready API (Modular Monolith)**.

```mermaid
graph TD
    A[Mobile App / PWA Pekerja] -->|REST API / Sync Queue| C(API Gateway / Load Balancer)
    B[Web Dashboard Admin] -->|HTTPS / REST API| C
    S[Sensor IoT ESP32 Kandang] -->|MQTT| M(Message Broker - Mosquitto/RabbitMQ)
    
    C --> D{Backend Service - PHP}
    M -->|Worker Daemon / Subs| D
    
    D -->|Read/Write Cepat| E[(MySQL / MariaDB)]
    D -->|Cache & Session| F[(Redis)]
    D -->|Kirim Alert| G[WhatsApp Gateway API]
```

- **Frontend Tampilan Client:** HTML5+Bootstrap terbaru dengan pola rendering Native PHP (Views).
- **Backend API & Core:** **PHP 8 Native (Skema MVC)**. Pola pemisahan logika `models/`, `views/`, dan `controllers/`.
- **Database Induk:** **MySQL 8.0+**.

---

## 🗃️ 3. DESAIN SKEMA DATABASE TERENHANCEMENT

Penggunaan tabel referensi agar tidak menggunakan tipe data enum:

### A. Tabel Referensi Master (Lookup Terpisah)

- `ref_roles`: id, name, slug (SuperAdmin, Manager, Supervisor, dll).
- `ref_user_statuses`: id, code, label.
- `ref_coop_types`: id, code, label (Open House, Closed House, Semi-Closed).
- `ref_coop_statuses`: id, code, label.
- `ref_batch_statuses`: id, code, label (Preparing, Active, Harvesting, Closed).
- `ref_item_categories`: id, code, label (Pakan, Vaksin, Obat, Alkes, OVK).
- `ref_transaction_types`: id, code, label (In-Purchase, Out-Consumption, Transfer, Adjustment).
- `ref_sales_types`: id, code, label.
- `ref_health_outcomes`: id, code, label.
- `ref_egg_grades`: id, code, label.

### B. Core Farm & Orgs

- `users`: id, name, username, email, password, ref_role_id, farm_id.
- `farms`: id, name, location_maps, pic.
- `coops`: id, farm_id, name, ref_coop_type_id, max_capacity, length_m, width_m.

### C. Siklus Budidaya & Record

- `batches`: id, coop_id, ref_bird_breed_id, start_date, initial_poultry_count, current_poultry_count, ref_batch_status_id.
- `daily_records`: id, batch_id, record_date, feed_used_kg, water_used_liter, mortality, culling, sample_weight_gram, actual_fcr. (_Catatan: bedakan antara ayam mati alami dengan culling/afkir_).

### D. Internet of Things (Sensor Ingestion)

- `sensor_logs`: id, coop_id, timestamp, temp_celsius, humidity_pct, ammonia_ppm, fan_voltage_status. _(Direkomendasikan partisi tabel per bulan)_.

### E. Inventory Management & Costing

- `warehouses`: id, farm_id, name, is_main_warehouse (bool).
- `items`: id, sku, item_name, ref_item_category_id, unit_of_measurement.
- `inventory_stocks`: warehouse_id, item_id, current_qty.
- `inventory_movements`: id, item_id, source_warehouse_id, dest_warehouse_id (nullable for consumption), batch_id(nullable), ref_movement_type_id, qty, unit_price_at_timestamp.

### F. Kesehatan, Finansial & Panen

- `health_treatments`: id, batch_id, diagnosis, medicine_item_id, dosage_given, application_method, admin_id.
- `harvest_records`: id, batch_id, harvest_date, total_birds, total_weight_kg, dead_on_arrival, buyer_name, total_invoice_amount.
- `financial_ledgers` (Jurnal Buku Besar): id, batch_id, ref_financial_trx_type_id, category, nominal, date.

---

## 🔌 4. SPESIFIKASI STANDAR API & KONTRAK

- Desain respons API distandarisasi untuk klien berbasis frontend modern: `{"status": bool, "message": string, "data": object|array, "meta": {"pagination": {}} }`.

|HTTP Method|Endpoint Path|Deskripsi & Autorisasi|
|---|---|---|
|`POST`|`/api/v1/auth/login`|Return format Bearer Auth Token.|
|`GET`|`/api/v1/dashboard/metrics`|Kalkulasi FCR kumulatif regional, mortality alert. (RBAC: Manager+)|
|`POST`|`/api/v1/batches/{uuid}/daily-records`|Worker men-submit RH. API otomatis akan mengurangi stok pakan `inventory_stocks` menggunakan relasi gudang kandang terkait.|
|`POST`|`/api/v1/inventory/transfers`|Mutasi pakan/DOC antar Gudang Induk ke Kandang spesifik.|
|`POST`|`/api/webhook/iot-sensors`|(NO JWT, But API KEY). Menerima stream JSON real-time hardware ESP32 dari kandang.|
|`GET`|`/api/v1/reports/hpp-calculation/{batch_uuid}`|Endpoint berat: menghitung kumulatif konsumsi barang * harga pada titik waktu itu + overhead cost per batch.|

**Contoh Payload IoT Ingestion (Dari Kandang IoT ESP32):**

```json
{
  "coop_id": "CP-BLOK-AA01",
  "api_key": "sec_8291038xsnw_hw",
  "payload": {
    "temperature": 32.5,
    "humidity": 68.2,
    "ammonia_level": 15,
    "fans_active": 4
  },
  "timestamp": "2024-05-20T14:30:00Z"
}
```

---

## 🛡️ 5. SECURITY, KONSISTENSI, & BEST PRACTICES MODERN

1. **Database Transaction Terawasi:** Aktivitas yang berujung ke lebih dari 1 tabel, seperti pengisian catatan harian (memotong saldo inventori, menambah Opex finansial, dan update deplesi batch), harus **wajib** dikerjakan dalam `BEGIN TRANSACTION / COMMIT`. Jika salah satu gagal, DB di `ROLLBACK`.
2. **Locking Optimistik (Optimistic Versioning):** Pada sistem tabel `inventory_stocks`, jika admin gudang dan manajer sistem melakukan penyesuaian pakan bersamaan, dihindari balapan data (race condition).
3. **Queue Processing (Background Task):** Kalkulasi analitik report tahunan yang memakan waktu (lebih dari 10 detik) dilempar ke Jobs Queue, bukan ditahan di HTTP Loading State. User akan mendapat notifikasi ketika laporan berhasil dibentuk menjadi PDF atau XLS.
4. **Push WA Event Listeners:** Event seperti mortalitas fluktuasi harian melebihi baseline (misal > 1.5% dalam 2 hari) secara sinkron ditangkap oleh *Cron Job / Webhook script* dan memanggil library Broadcast WhatsApp ke Manager Operasional Farm, menjadikan manajemen resiko yang reaktif dan lincah.

---

## 🚀 6. ROADMAP DEPLOYMENT REKOMENDASI (SPRINTS)

Bagi pengembang (Development Team), pecahlah pembuatan aplikasi ini ke pengerjaan Agile:

1. **Milestone 1 (Master Core & Farm Lifecycles):** Pembuatan fondasi PHP dan Database, Authentication, Modul Setup Master Kandang, Role, dan Siklus Buka-Tutup Batch Kandang.
2. **Milestone 2 (Daily Oprations & Inventory):** Interaksi aplikasi untuk modul Gudang, mutasi barang, input daily report karyawan dengan fungsional filter kalender. Integrasi pemotong logistik.
3. **Milestone 3 (Finance & HPP Analyst):** Fitur Panen, Invoice Modul, Laporan FCR & perhitungan akuntansi riil di ujung siklus peternakan. Ekspor Excel.
4. **Milestone 4 (Smart IoT Add-ons & Offline Modes):** Integrasi service worker frontend untuk mode offline, pembuatan endpoint webhook IoT, penyelarasan data IoT dengan dashboard chart realtime. Integrasi engine Fonnte/WhatsApp.