# 🤖 AI CONTEXT & DEVELOPMENT GUIDELINES
### **Sistem Absensi Fingerprint Terintegrasi (SMK Negeri 1 Gunung Agung)**

> **PENTING UNTUK AI CODING ASSISTANT:**  
> Dokumen ini adalah **Petunjuk Utama & Aturan Mutlak (Single Source of Truth Rules)** dalam menginisiasi, mengubah, merefactor, atau menambah kode pada repositori ini. Seluruh AI Assistant **WAJIB** membaca dan mematuhi seluruh aturan di bawah ini sebelum membuat atau memodifikasi kode apapun.

---

## 📌 1. Ringkasan Project
- **Nama Aplikasi**: Sistem Absensi Fingerprint Terintegrasi SMKN 1 Gunung Agung.
- **Tujuan Utama**: Otomatisasi penarikan log biometrik dari 6 mesin fingerprint (Fingerspot Revo W-230N) via TCP Socket Port 4370 (ZK Protocol), mengolahnya secara otomatis menjadi status kehadiran (`Hadir`, `Terlambat`, `Izin`, `Sakit`, `Alpha`), dan menyajikan dashboard real-time serta laporan siap cetak ber-Kop Surat Resmi.
- **Tech Stack**: PHP 8.2+, Laravel 11, Livewire 3, Vanilla Tailwind CSS 3, MySQL / MariaDB, cPanel Cron Job.
- **Target Hosting**: Shared Web Hosting / cPanel On-Premise Sekolah (Tanpa Root Access, Tanpa Supervisor, Tanpa Docker, Tanpa CLI `mysqldump`).

---

## 📐 2. Business Rules
1. **Aturan Shift Default**:
   - Shift Guru: 07:00 – 15:30 WIB (Dispensasi Keterlambatan: 07:01 WIB).
   - Shift Siswa: 07:00 – 14:30 WIB.
2. **Aturan Pengecualian Hari Libur**:
   - `AttendanceProcessorService` **DILARANG** generate status `Alpha` pada hari Minggu, hari libur nasional (`school_holidays`), atau agenda libur sekolah (`academic_events`).
3. **Aturan Pengajuan Izin & Sakit**:
   - Pengajuan izin/sakit yang disetujui (`status = 'approved'`) secara otomatis menimpa/memperbarui `attendance_records` tanggal terkait menjadi `Izin` atau `Sakit`.
4. **Wajib Ganti Password**:
   - Pengguna dengan `force_password_change = true` diblokir oleh `EnsurePasswordIsChanged` middleware dan wajib mengubah kata sandi default sebelum dapat membuka modul aplikasi lainnya.

---

## 💻 3. Coding Rules
1. **SOLID Principles**: Wajib menerapkan Single Responsibility Principle (SRP) dan Dependency Inversion Principle (DIP).
2. **Strict Type Hinting**: Seluruh parameter fungsi, return type, dan property DTO wajib diberi *type-hinting* eksplisit.
3. **No Magic Numbers / Strings**: Gunakan Enum (`AttendanceStatusEnum`, `LeaveStatusEnum`, `LeaveTypeEnum`) alih-alih hardcoded string.
4. **Clean Code Comments**: Pertahankan komentar docstring kelas/metode yang relevan.

---

## 📁 4. Folder Rules
- `app/Actions/`: Action Class dengan 1 metode utama `execute()`.
- `app/Contracts/`: Interface untuk Repositori dan Channels.
- `app/DTO/`: Data Transfer Objects immutable.
- `app/Enums/`: Enumerasi PHP 8.2+.
- `app/Helpers/`: Custom Helper Functions & Utilities.
- `app/Livewire/`: Livewire 3 Components terelokasi per modul (`Auth`, `Users`, `Shifts`, `Personnel`, `Machines`, `Sync`, `Reports`, `Permissions`, `Academic`, `Leave`, `Monitoring`, `Backup`, `Notifications`).
- `app/Repositories/`: Implementasi kueri Eloquent terisolasi.
- `app/Services/`: Domain Logika Bisnis & Hardward Socket Driver.

---

## 🗄️ 5. Database Rules
1. **Decoupling Raw Logs vs Records**: `attendance_logs` (log mentah biometrik) strictly terpisah dari `attendance_records` (rekord olahan harian).
2. **Indexing Mandatory**: Seluruh foreign key, `date`, `timestamp`, `status`, `is_processed`, `deleted_at` wajib diberi indeks database.
3. **Soft Deletes**: Master data (`users`, `shifts`, `fingerprint_machines`, `backups`) menggunakan Trait `SoftDeletes`.
4. **Foreign Key Integrity**: Gunakan `constrained()->cascadeOnDelete()` atau `nullOnDelete()` secara jelas.

---

## 🏷️ 6. Naming Convention
- **Models**: PascalCase, tunggal (`User`, `AttendanceRecord`, `FingerprintMachine`).
- **Tables**: snake_case, jamak (`users`, `attendance_records`, `fingerprint_machines`).
- **Columns**: snake_case (`ip_address`, `force_password_change`, `created_by`).
- **Interfaces**: PascalCase diakhiri `Interface` (`UserRepositoryInterface`).
- **Livewire Components**: PascalCase (`UserIndex`, `HeaderGlobalSearch`).
- **Blade Views**: kebab-case (`user-index.blade.php`, `header-global-search.blade.php`).
- **Routes**: kebab-case untuk URL (`/backup-restore`), camelCase / dot-notation untuk Name (`backup-restore.index`).

---

## 🏗️ 7. Repository Rules
1. **DILARANG** melakukan kueri Eloquent kompleks langsung di dalam Livewire Component / Controller. Wajib melalui Repository Interface.
2. Setiap metode repository wajib mengembalikan tipe data spesifik (`Model`, `Collection`, `LengthAwarePaginator`, atau `bool`).
3. Seluruh Repository Interface wajib terdaftar binding-nya di `AppServiceProvider.php`.

---

## ⚙️ 8. Service Rules
1. **Tanggung Jawab Domain**: Service Layer tempat bersemayamnya Business Logic, perhitungan jam, kompresi ZIP, parsing socket, dan penanganan exception.
2. **Socket Driver Safety**: Penggunaan `fsockopen` / `socket_connect` wajib diisolasi dalam `ZKTecoService` dengan `timeout` maksimal 2 detik.
3. **Audit Trail Logging**: Panggil `AuditLogService` setiap kali Service melakukan perubahan data sensitif.

---

## 📦 9. DTO Rules
1. DTO digunakan untuk membungkus data kompleks yang ditransfer antara UI Layer -> Service Layer.
2. Property DTO bersifat `readonly` atau diakses via getter.
3. Wajib menyediakan static factory method `fromRequest()` atau `fromArray()`.

---

## 🛡️ 10. Policy Rules
1. Seluruh otorisasi aksi di Livewire (`$this->authorize()`) wajib memeriksa Policy Class terkait.
2. Policy Naming mematuhi pasangan nama model (`User` -> `UserPolicy`, `Backup` -> `BackupPolicy`).
3. Otorisasi memanfaatkan Permission Matrix (`$user->hasPermissionTo('permission.name')`) atau Super Admin Override (`$user->isSuperAdmin()`).

---

## ⚡ 11. Livewire Rules
1. Livewire 3 Component bertindak sebagai Controller tipis (Thin Presenter).
2. Wajib menggunakan Trait `WithPagination`, `AuthorizesRequests`, dan `WithFileUploads` yang relevan.
3. Komponen wajib menangani state `wire:loading` pada setiap tombol aksi untuk mencegah double-click.
4. Gunakan `wire:confirm` pada aksi destruktif (Hapus, Restore DB).

---

## 🎨 12. UI Rules (Desain Aesthetics)
1. **Desain Premium Dark Theme**: Palette Slate-900 (`bg-slate-900`, `border-slate-800`, `text-slate-300`).
2. **Strict UI Compliance**:
   - Header Page wajib menyertakan Breadcrumbs & Title jelas.
   - Status Badges wajib menggunakan pill rounded-full dengan background opacity (`bg-emerald-500/10 text-emerald-400 border border-emerald-500/20`).
3. **Interactive Visuals**: Loading spinner, hover transitions, dan Toast Notifications.

---

## 🧪 13. Testing Rules
1. **Unit & Feature Tests Wajib Pass 100%**: Jalankan `./vendor/bin/phpunit` sebelum menyatakan tugas selesai.
2. Setiap fitur baru/modifikasi wajib menyertakan file test terkait di `tests/Unit/` atau `tests/Feature/`.
3. Pengujian menggunakan `RefreshDatabase` Trait dan `DatabaseSeeder`.

---

## 🐙 14. Git Rules
1. Commit message menggunakan format Conventional Commits:
   - `feat: [nama fitur]` (Penambahan fitur baru)
   - `fix: [deskripsi bug]` (Perbaikan bug)
   - `refactor: [deskripsi refactor]` (Pengubahan struktur tanpa ubah logika)
   - `test: [deskripsi test]` (Penambahan unit test)

---

## 🐘 15. Laravel Rules
1. Gunakan Laravel 11 anonymous migrations.
2. Gunakan `casts()` method pada Eloquent Models alih-alih `$casts` property.
3. Hindari `N+1 Query` dengan memanggil Eager Loading (`with(['role', 'shift'])`).
4. Gunakan Helper `defer()` atau Event-Listener untuk pengiriman notifikasi agar tidak memblokir respon HTTP.

---

## 🚫 16. Hal yang Dilarang (STRICT PROHIBITION)
- ❌ **DILARANG** menggunakan `exec()`, `shell_exec()`, `system()`, atau `mysqldump` CLI (Tidak ramah shared hosting!).
- ❌ **DILARANG** menulis kueri Eloquent mentah di Blade Views / Livewire Component.
- ❌ **DILARANG** menghapus fitur existing atau mengubah skema PRD tanpa persetujuan user.
- ❌ **DILARANG** mematikan/menghapus unit test yang failing demi meluluskan pengujian.
- ❌ **DILARANG** membuat halaman UI yang polos/sederhana tanpa mematuhi UI Rules Dark Theme.

---

## 📝 17. Checklist Sebelum Coding
- [ ] Baca dan pahami PRD & Knowledge Items terkait.
- [ ] Periksa tabel database & migration existing.
- [ ] Tentukan Service, Repository, dan Policy yang akan digunakan.
- [ ] Buat plan di `implementation_plan.md` (jika perubahan kompleks).

---

## 📝 18. Checklist Sebelum Commit
- [ ] Jalankan `./vendor/bin/phpunit` (Pastikan seluruh test PASS 100%).
- [ ] Pastikan tidak ada sintaks error / undefined variable.
- [ ] Pastikan file `task.md` telah diperbarui progresnya.
- [ ] Format kode rapi sesuai PSR-12.

---

## 📝 19. Checklist Sebelum Release
- [ ] Jalankan `php artisan db:seed` untuk memastikan seeding bersih.
- [ ] Verifikasi halaman `/system-monitoring` (Database OK, Socket OK, Cron OK).
- [ ] Perbarui `walkthrough.md` dengan ringkasan perubahan dan cara pengujian.
- [ ] Pastikan aplikasi 100% siap di-deploy ke Shared Hosting Sekolah.
