# Integrasi Neo Feeder PDDikti

## Tujuan dan batas
Kesesuaian data SIAKAD dengan Neo Feeder adalah prioritas utama produk. Integrasi mendukung kebutuhan impor dan ekspor yang disetujui kampus, dengan mapping eksplisit, validasi, antrean/riwayat, dan rekonsiliasi agar perbedaan data dapat ditemukan dan ditangani. Arah pertukaran setiap jenis data (satu arah atau dua arah) harus ditetapkan per entitas dan mengikuti kewenangan sumber data. Selain contoh `GetToken` yang didukung panduan publik dan uji koneksi sandbox, payload dan field operasi lain tetap harus divalidasi sebelum digunakan.

## Feeder Bridge kampus
Jika server Feeder hanya dapat diakses dari jaringan privat kampus, jalankan bridge kecil di jaringan tersebut. Aplikasi cPanel mengirim pekerjaan keluar melalui kanal aman yang disetujui; bridge mengambil pekerjaan, berkomunikasi dengan Feeder lokal, lalu mengirim hasil. Jangan membuka port Feeder ke internet. Protokol, autentikasi, jaringan, dan kepemilikan bridge harus disepakati tim kampus.

**Gerbang transport:** URL Web Service yang pernah diberikan pengguna memakai HTTP tanpa TLS. Jangan kirim username/password `GetToken`, token, atau data mahasiswa melalui URL tersebut melintasi internet/jaringan yang tidak dipercaya. Integrasi langsung memerlukan HTTPS dengan sertifikat tervalidasi; jika instalasi hanya tersedia melalui HTTP privat, lalu lintas harus tetap di jaringan kampus yang dibatasi atau lewat VPN/tunnel terautentikasi sesuai persetujuan kampus. Bridge tidak boleh meneruskan kredensial melalui kanal publik tanpa enkripsi.

## Alur sinkronisasi
Pilih arah (impor/ekspor), data, dan periode → validasi lokal dan mapping → operator meninjau preview serta konflik → proses batch → simpan referensi/hasil respons sesuai izin → rekonsiliasi kedua sisi → tangani konflik/kegagalan dengan keputusan sumber data yang tercatat. Jangan menimpa perubahan tanpa aturan resolusi konflik yang disahkan. Idempotensi dan retry hanya diaktifkan sesuai kemampuan resmi API.

## Pengamanan operasional
Kredensial hanya pada secret store/environment yang sesuai; akses minimum, TLS/VPN atau kanal aman, rotasi, redaksi log, pembatasan request, dan audit. Jangan catat password, token, atau data pribadi lengkap. Batasi retry dan cegah duplikasi; sediakan dry-run jika didukung proses. Sandbox lokal boleh mengaktifkan `NEO_FEEDER_ALLOW_INSECURE_HTTP=true` untuk endpoint kampus yang hanya menyediakan HTTP; ini hanya berlaku non-production dan mengekspos kredensial pada jaringan, sehingga batasi ke jaringan terpercaya dan akun sandbox. Production tetap menolak HTTP.

## Validasi bertahap
1. Gunakan koleksi Postman dan panduan publik sebagai kontrak kerja awal; catat URL/tanggal sumber dan tandai contoh yang belum dikonfirmasi.
2. Uji autentikasi dan operasi baca yang diperlukan di sandbox kampus. Jangan mengirim operasi tulis ke live saat tahap ini.
3. Konfirmasi respons, field, dictionary, pagination, dan error terhadap sandbox; perbaiki konfigurasi token path bila perlu.
4. Buat mapping serta aturan transformasi dan arah data yang disetujui operator PDDikti kampus.
5. Aktifkan operasi tulis per entitas setelah preview/review, lalu uji rekonsiliasi, retry, dan pemulihan sebelum produksi.

Versi aplikasi `3.1.0` / DB `3.55` tetap dicatat untuk sasaran kompatibilitas, tetapi ketidakcocokan label versi pada dokumentasi publik bukan penghalang untuk mulai uji sandbox baca-saja. Hasil sandbox menjadi bukti kompatibilitas yang lebih baik untuk instalasi kampus tersebut.

## Temuan dokumentasi publik (ditinjau 2026-11-05)
Panduan Neo Feeder 2.4.0 yang dipublikasikan LLDIKTI III merangkum pelaporan awal semester (antara lain mahasiswa baru, mata kuliah/kurikulum, kelas, pengajar, KRS, AKM) dan akhir semester (antara lain skala/nilai, pembaruan AKM, aktivitas/prestasi, status lulus/DO). Panduan yang sama menyatakan dokumentasi Web Service dirujuk dari instalasi Feeder (`/ws/postman`) dan buku panduan tersedia di PDDikti Admin. Ini menunjukkan model harus mendukung tahapan/checkpoint dan perubahan data transaksi, bukan satu tombol sinkronisasi tanpa status.

**Versi kampus yang dikonfirmasi pengguna:** Aplikasi Neo Feeder `3.1.0`; database `3.55`. Versi tersebut dicatat sebagai target kompatibilitas, tetapi tidak menghalangi uji sandbox bertahap memakai dokumentasi publik. Perbedaan versi tetap perlu diperiksa sebelum operasi tulis atau produksi.

Pencarian sumber publik pada 2026-11-05 menemukan halaman login Neo Feeder yang menampilkan `3.1.0` dan database `3.55`, sesuai versi yang dilaporkan pengguna. Halaman tersebut hanya membuktikan teks versi pada instalasi yang dipublikasikan; halaman itu tidak memuat dokumentasi metode atau skema request/response. Panduan Web Service publik dari LLDIKTI III yang dapat dibaca berlabel `2.4.0`, sehingga tidak dapat dipakai sebagai kontrak `3.1.0`.

GET tanpa autentikasi ke endpoint dokumentasi kampus [`/ws/postman`](http://103.186.0.144:8100/ws/postman) berhasil diikuti hingga halaman dokumentasi Postman publik dengan identitas `17711570/Uyr7Gdrx`, berjudul **Restful Neo Feeder**. Ini mengonfirmasi endpoint tersebut membuka dokumentasi Postman, tetapi tidak memastikan versinya. [Koleksi Restful Neo Feeder](https://documenter.getpostman.com/view/17711570/Uyr7Gdrx) yang diberikan pengguna memuat 244 request. Pemeriksaan struktur tanpa membaca/menampilkan nilai contoh menemukan 17 ketidakcocokan antara label request dan nilai `act` pada body, selain beberapa sampel ganda. URL request dominan `http://localhost:3003/ws/live2.php`; sebagian sampel memakai host berbeda. Contoh `GetToken` memakai kunci `act`, `username`, `password`; `getDictionary` memakai `token`, `act`, `fungsi`; query contoh memakai `filter`, `order`, `limit`, `offset`. Karena variasi ini dan tidak ada penanda versi, koleksi ini bahan verifikasi, bukan kontrak yang aman untuk operasi tulis.

Contoh request `GetToken` pada materi resmi LLDIKTI VI 2023 memakai JSON `act`, `username`, `password`; contoh respons menampilkan `error_code`, `error_desc`, dan token pada `data.token` ([materi web service PDDikti-Admin x Neo Feeder](https://lldikti6.id/wp-content/uploads/2024/03/PDDIKTI-2023-Gasal-Ghufron.pdf)). Fondasi uji sandbox memakai path `data.token` sebagai default yang dapat diubah lewat `NEO_FEEDER_TOKEN_PATH`. Ini contoh publik untuk memulai, bukan jaminan kesesuaian semua versi.

Uji koneksi memanggil `GetToken`, memeriksa `error_code = 0` dan token pada path terkonfigurasi, lalu membuang token tanpa menyimpan atau menampilkannya. Katalog internal menyimpan 131 operasi baca yang ditemukan pada koleksi Postman; halaman operator menampilkan kelompok data berbahasa pengguna dalam bentuk checklist, bukan nama operasi API. Setiap jenis data dipetakan ke satu operasi baca yang tercantum pada koleksi. Operator dapat mencentang beberapa jenis sekaligus; aplikasi memproses tiga jenis per tahap dan menampilkan maksimal 20 baris per jenis. Navigasi halaman dan jenis data berikutnya tidak memerlukan pengisian offset. Respons ditampilkan sebagai tabel dinamis berdasarkan kolom yang diterima; nilai bertingkat diringkas sebagai teks. Token hanya berada di memori dan respons pratinjau tidak disimpan ke database. Hasil meliputi data kampus/referensi, mahasiswa, dosen, perkuliahan, kemahasiswaan, dan rekap yang tersedia pada checklist. Import/staging, ekspor, dan sinkronisasi belum tersedia. Tinjau respons sandbox sebelum menetapkan mapping field.

Koleksi Postman publik yang diperiksa ulang pada 2026-11-05 juga tidak menyebut versi `3.1.0`; halaman versi login pada instalasi Feeder hanya mengonfirmasi pasangan aplikasi/database dan tidak mengikat koleksi tersebut pada versinya. Selain validasi kontrak, skema transport wajib diperiksa: URL HTTP yang diberikan bukan kanal aman untuk kredensial di internet.

Panduan tersebut juga mencatat fitur dan perubahan di versi 2.3/2.4. Karena sumber publik yang ditemukan belum membuktikan bahwa 2.4.0 adalah versi terkini, temuan ini hanya menjadi petunjuk desain. Dokumentasi resmi yang menyertai versi Feeder kampus tetap menjadi kontrak implementasi. Lihat [catatan keputusan](15-catatan-keputusan.md).

## Implikasi rancangan database dan API lokal
- Pertahankan ID internal SIAKAD sebagai primary key; `external_record_mappings` memisahkan ID eksternal, jenis entitas, sistem, verifier, dan versi kontrak. Unique constraint mencegah satu ID eksternal terhubung ke dua record lokal untuk entitas/sistem yang sama. Jangan mengganti primary key lokal dengan ID Feeder.
- Simpan snapshot/versi kontrak integrasi (versi Feeder, versi mapping, tanggal validasi) dan hasil request/response yang telah disanitasi, sesuai retensi.
- Fondasi `integration_batches`/`integration_batch_items` sudah menyimpan arah, entitas, periode, status, idempotency key, versi kontrak/mapping, fingerprint, hasil per item, dan error teredaksi. Retry/correlation ID dan eksekusi belum dibuat karena kontrak belum diverifikasi.
- Pisahkan antrean ekspor dari proses impor; impor masuk ke staging/preview agar operator memvalidasi dan menyelesaikan konflik sebelum mengubah data akademik kanonis.
- Jangan berasumsi semua entitas dapat diedit kapan saja. Simpan hasil validasi dan alasan penolakan; alur koreksi dapat bergantung pada pembukaan periode atau prosedur administrasi.
- Skema lokal mengikuti kebutuhan domain kampus; payload Feeder dibangun pada adapter/versioned mapper. Hindari menyalin seluruh skema eksternal ke tabel inti atau membuat kolom berdasarkan sampel API lama.
- Pertukaran data tidak otomatis berarti Feeder selalu sumber kebenaran. Tetapkan kepemilikan per field/entitas, aturan konflik, dan approval sebelum sinkronisasi dua arah.

## Sumber dan status
- Panduan publik [Neo Feeder 2.4.0 — LLDIKTI III](https://lldikti3.kemdikbud.go.id/wp-content/uploads/2024/08/PDDikti-NeoFeeder-2.4.0.pdf) memuat ringkasan pelaporan dan menunjuk ke dokumentasi Web Service pada instalasi serta PDDikti Admin.
- Halaman login publik yang menampilkan [Neo Feeder 3.1.0 / database 3.55](https://neofeeder.unma.ac.id/) cocok dengan target versi yang dilaporkan, tetapi bukan dokumentasi Web Service dan tidak memvalidasi method/field.
- Materi [Bimbingan Teknis Neo Feeder 2022 — LLDIKTI VI](https://lldikti6.id/wp-content/uploads/2022/11/Materi-NEO-FEEDER.pdf) adalah materi lama; berguna untuk memahami pola umum Web Service, bukan kontrak API terkini.
- Versi aplikasi/database kampus: **dikonfirmasi pengguna** sebagai 3.1.0 / 3.55. Dokumentasi Web Service yang persis sesuai versi tersebut: **belum diverifikasi**. Minta ekspor/akses dokumentasi resmi dari PDDikti Admin atau endpoint dokumentasi pada instalasi kampus sebelum merancang payload atau migrasi final.

## Pemetaan Otomatis (Auto-Mapping)
Untuk mengatasi kendala input ratusan UUID Feeder secara manual, `NeoFeederAutoMapper` menyediakan pencocokan otomatis antara data lokal SIAKAD dengan data Neo Feeder:
- **Program Studi**: Pencocokan via `kode_program_studi` (`GetProdi`).
- **Periode Akademik**: Pencocokan via format kode semester PDDikti (misal `20261` untuk 2026/2027 Ganjil) melalui `GetSemester`.
- **Mata Kuliah**: Pencocokan via `kode_mata_kuliah` lokal (`GetMataKuliah`).
- **Dosen**: Pencocokan via `nidn` / NUPN (`GetDosen`).
- **Mahasiswa / Riwayat Pendidikan**: Pencocokan via `nim` (`GetRiwayatPendidikanMahasiswa`).

Hasil pemetaan otomatis dicatat ke `external_record_mappings` dengan label kontrak `Neo Feeder 3.1.0 / DB 3.55`, mencatat verifier operator dan waktu verifikasi, serta diaudit tanpa membocorkan identifier mentah.

## Ekspor Tulis ke Neo Feeder (Push Pipeline)
Operasi tulis yang telah diizinkan pada allowlist `config/neo_feeder.php` dieksekusi melalui `NeoFeederPushExporter` menggunakan method `executeWrite` pada `NeoFeederClient`:
- **Kelas Kuliah** (`InsertKelasKuliah`): Mengirim data penawaran kelas semester aktif yang telah memiliki pemetaan Prodi, Periode, dan Mata Kuliah. Hasil balasan `id_kelas_kuliah` otomatis disimpan ke `external_record_mappings`.
- **Dosen Pengajar Kelas Kuliah** (`InsertDosenPengajarKelasKuliah`): Mengirim penugasan dosen pengajar kelas dengan bobot SKS ajar, rencana tatap muka (16x), dan realisasi sesi presensi aktual.
- **Peserta Kelas Kuliah** (`InsertPesertaKelasKuliah`): Mengirim data mahasiswa yang memiliki KRS berstatus Disetujui (`status = approved`) pada kelas yang sudah terpetakan, menghubungkan `id_kelas_kuliah` dengan `id_registrasi_mahasiswa`.
- **Nilai Akhir Perkuliahan** (`UpdateNilaiPerkuliahanKelas`): Mengirim nilai akhir (nilai angka, huruf, dan indeks) yang telah berstatus Disetujui (`submitted_for_approval = false` & grade terbit) untuk kelas dan peserta terkait.
- **Aktivitas Kuliah Mahasiswa / AKM** (`InsertPerkuliahanMahasiswa` / `UpdatePerkuliahanMahasiswa`): Mengirim rekap semesteran status mahasiswa (Aktif/Cuti), total SKS semester, total SKS kumulatif, IPS, dan IPK untuk keperluan pelaporan berkala PDDikti.
- **Mahasiswa Lulus / Keluar** (`InsertMahasiswaLulusDO` / `UpdateMahasiswaLulusDO`): Mengirim data mahasiswa yang disahkan pada sidang/yudisium kelulusan (SK Yudisium, Tanggal Kelulusan, Nomor Ijazah/PIN, dan IPK kelulusan).

Setiap batch ekspor dicatat secara terperinci ke `integration_batches` dan `integration_batch_items` dengan penghitungan item berhasil/gagal, audit log operator, dan penanganan error tanpa crash.

## Kriteria penerimaan
Layar operator dapat mencatat pemetaan manual ID SIAKAD–Feeder dan mencegah ID eksternal ganda; audit menyimpan aksi tanpa nilai ID. Tombol uji sandbox melakukan autentikasi `GetToken` saja dan tidak menyimpan token. Pratinjau memakai checklist kelompok data yang dipetakan ke operasi baca allowlist; operator dapat mencentang beberapa jenis, diproses bertahap tiga jenis per request, maksimal 20 baris per jenis, ditampilkan sebagai tabel, menyediakan navigasi baris/jenis, tidak menulis ke database, menyembunyikan kunci rahasia pada respons, serta hanya dapat dijalankan dengan permission integrasi. Tabel batch/item tersedia, tetapi impor/staging, ekspor, koneksi Bridge, rekonsiliasi, dan retry belum diaktifkan. Tahap berikutnya adalah memeriksa respons sandbox, menyetujui mapping, lalu membangun staging/preview sebelum impor terkontrol.