presensi/README.md

# SMAN 1 Garut – Backend Presensi Siswa

Backend presensi siswa berbasis **CodeIgniter 4** untuk:

- Presensi masuk/pulang & per‑mapel (QR).
- Zona lokasi (geofence) & pengaturan jam masuk/pulang.
- Akun mobile siswa (NISN + PIN).
- Portal orang tua & poin pelanggaran.
- Integrasi foto formal + verifikasi wajah (via service AI eksternal).

Backend ini biasanya dipakai bersama:
- Frontend mobile: folder `../mobile` (repo terpisah).
- Face embedding service: folder `../face-service` (FastAPI + InsightFace).

## 1. Kebutuhan Server

- PHP **8.2+** dengan ekstensi:
  - `intl`, `mbstring`, `json`, `curl`, `gd`, `mysqli`/`mysqlnd`.
- MySQL/MariaDB.
- Composer.

## 2. Setup Cepat (Development)

Di folder `backend`:

```bash
composer install
cp env .env   # atau copy manual
```

Edit `.env`:

```ini
app.baseURL = 'http://localhost/sman1/backend/public/'

database.default.hostname = localhost
database.default.database = absen_sman1
database.default.username = root
database.default.password = your_password

telegram.bot_token = your_telegram_bot_token
telegram_bot_token = your_telegram_bot_token

FACE_SERVICE_URL = 'http://localhost:5000'
FACE_EMBEDDING_DIM = 512
FACE_SIM_THRESHOLD = 0.85
FACE_MIN_SIZE = 80
FACE_MIN_BLUR = 30
FACE_MIN_BRIGHTNESS = 0.2
```

Jalankan migration & seeder yang diperlukan:

```bash
php spark migrate --all
php spark db:seed DeviceSeeder
php spark db:seed StudentMobileAccountsSeeder   # opsional untuk dummy data
```

Jalankan server dev:

```bash
php spark serve
```

Lalu akses:

- Dashboard: `http://localhost:8080` atau `http://localhost/sman1/backend/public` (sesuai web server).
- API mobile: `http://localhost/sman1/backend/public/api/mobile/...`.

## 3. Modul Utama

- `Modules/Academic` – kelas, mapel, guru, jadwal, siswa, Dapodik.
- `Modules/Attendance` – check‑in device, check‑in QR mapel, laporan, `student_faces` + verifikasi wajah.
- `Modules/Mobile` – API mobile (login NISN+PIN, registrasi PIN, checkin‑qr, checkin‑masuk‑pulang, status hari ini).
- `Modules/Devices` – device absen, autentikasi device (code + api_key).
- `Modules/Dashboard` – halaman dashboard + pengaturan presensi (zona + jam masuk/pulang).
- `Modules/Parent` – portal orang tua (riwayat presensi & pelanggaran).
- `Modules/Discipline` – kategori pelanggaran, poin, rekap siswa.
- `Modules/Notification` – integrasi Telegram.
- `Modules/Face` – penyimpanan embedding wajah (`student_faces`) + endpoint import/enroll.

Struktur detail endpoint dan flow presensi dijelaskan di:

- `docs/SETUP_PRESENSI.md` (jika ada).
- `docs/SYNC_FOTO_WAJAH.md` – cara sync foto formal dari Google Drive + face hash.

## 4. Integrasi Face Embedding Service

Backend **tidak menghitung embedding wajah sendiri**, tapi memanggil service eksternal (lihat folder `../face-service`):

- Service Python (`FACE_SERVICE_URL`) menyediakan endpoint:
  - `POST /embed` → menerima file gambar, mengembalikan:
    - `embedding` float[],
    - `faces_count`, `face_size`, `blur`, `brightness`, `quality_score`.
- `App\Modules\Face\Services\FaceService`:
  - `extractEmbeddingWithQuality()` → kirim gambar ke `/embed`, terapkan quality gate.
  - `cosineSimilarity()` → untuk matching saat verify‑face.

### Alur singkat

1. **Import foto formal** (admin):  
   `POST /api/face/import-formal` → ambil foto dari URL (Google Drive/hasil sync) → simpan embedding `source='formal'` ke `student_faces`.
2. **Enroll live** (siswa, 3–5 frame):  
   `POST /api/face/enroll-live` → simpan beberapa embedding `source='live'` + satu `live_avg`.
3. **Verifikasi saat presensi**:  
   `POST /api/attendance/verify-face` → bandingkan embedding probe dengan semua embedding siswa → kembalikan `similarity`, `matched_source`, `status (match/no_match)`.

## 5. Catatan Git & Deployment

- File yang **tidak** ikut repo (lihat `.gitignore`):
  - `.env`, `writable/*`, `vendor/`, direktori IDE, dll.
- Untuk produksi:
  - Pastikan PHP 8.2+, ekstensi lengkap, dan baseURL `.env` sudah sesuai domain sekolah.
  - Jalankan `php spark migrate --all` di server.
  - Jalankan face‑service Python di host/port yang sama dengan `FACE_SERVICE_URL` di `.env`.

---

Kalau develop bareng frontend mobile, lihat juga `../mobile/README.md` untuk cara run klien presensi di HP/device.