Panduan Pengembangan Aplikasi dengan Agentic AI¶

Project: Scola
Dokumen: Agentic AI App Development Guide
Tanggal: 2026-01-21
Versi: 1.0

1. Tujuan dan Ruang Lingkup¶

Panduan ini adalah pintu masuk untuk pengembangan aplikasi Scola menggunakan agentic AI. Fokusnya: - Konsistensi hasil kerja agent - Kualitas dan keamanan perubahan - Kejelasan alur kerja di server maupun lokal - Pencegahan pengulangan masalah yang sudah pernah terselesaikan

2. Dokumen Sumber (Wajib Dibaca)¶

Gunakan urutan ini sebelum mulai coding: 1. scola-fe-v2/docs/AI Guidelines/AI_AGENT_DEVELOPMENT_GUIDELINES.md - proses kerja, deliverables, testing 2. scola-fe-v2/docs/AI Guidelines/WORKSPACE-GOVERNANCE.md - permission matrix dan batasan repo 3. scola-fe-v2/docs/AI Guidelines/ARCHITECTURE-API.md - aturan same-origin proxy dan CORS 4. scola-fe-v2/docs/AI Guidelines/AI_AGENT_DEVELOPMENT_GUIDELINES_LOCAL.md - referensi tambahan

Aturan: - Jika ada konflik antar dokumen, berhenti dan tanya. - Jangan membuat asumsi tanpa membaca file terkait.

2.1 Pemilihan Dokumen Berdasarkan Mode¶

Pilih salah satu dokumen proses berikut, sesuai mode kerja: - Mode server deployment: scola-fe-v2/docs/AI Guidelines/AI_AGENT_DEVELOPMENT_GUIDELINES.md - Mode lokal: scola-fe-v2/docs/AI Guidelines/AI_AGENT_DEVELOPMENT_GUIDELINES_LOCAL.md

Wajib menyebut mode kerja di awal respon agent.

2.2 Konteks Workspace (Server vs Lokal)¶

Agent wajib memastikan root workspace sebelum bekerja: - Mode server (remote SSH): root biasanya /home/scola/odoo - Mode lokal: root mengikuti lokasi clone di mesin lokal

Aturan: - Jangan mengasumsikan path server saat bekerja di lokal. - Jika struktur repo berbeda dari ekspektasi, berhenti dan tanya. - Selalu sebutkan root workspace dan repo yang terdeteksi di output agent.

2.3 Deteksi Workspace (Wajib)¶

Sebelum membuat rencana atau perubahan, lakukan deteksi workspace:

pwd
ls

Gunakan hasilnya untuk memastikan root dan daftar repo yang tersedia.

3. Aturan Kepatuhan Dokumen (Anti-Regresi)¶

Wajib dilakukan di setiap task: - Baca dokumen sumber sebelum menulis kode. - Sebutkan dokumen yang dirujuk sebelum memberi rencana kerja. - Baca file yang akan diubah, jangan menebak struktur atau pola. - Jika menemukan aturan yang melarang perubahan, hentikan dan eskalasi. - Jika masalah sudah pernah diselesaikan, ikuti solusinya dan rujuk dokumentasi.

Checklist minimal untuk setiap respon agent:

Doc Compliance
- Mode kerja: server atau lokal
- Workspace root: [path]
- Repo yang terdeteksi: [daftar singkat]
- Deteksi workspace: [pwd, ls]
- Dokumen dibaca: [daftar]
- File yang akan diubah: [daftar]
- Risiko/ketidakpastian: [jika ada]

4. Mode Kerja: Server vs Lokal¶

4.1 Kapan Pakai Server¶

Gunakan mode server ketika: - Butuh testing cepat di environment yang sudah terkonfigurasi - Perlu akses ke data dan service Odoo di server - Perubahan bersifat integrasi dan butuh verifikasi end-to-end

4.2 Kapan Pakai Lokal¶

Gunakan mode lokal ketika: - Butuh eksperimen atau refactor besar tanpa mengganggu server - Koneksi server terbatas atau sedang maintenance - Ingin menjalankan tooling lokal (lint, unit test) dengan setup pribadi

4.3 Quick Start Mode Server (SSH + Deploy Langsung)¶

Karakteristik: Developer bekerja via SSH langsung di server. Deployment terjadi LANGSUNG di server setelah QC lulus.

Batasan path (lihat WORKSPACE-GOVERNANCE.md): - Editable: scola-fe-v2/, custom_addons_scola/gcgscola/ - Read-only: odoo/, addons/, custom_addons/openeducat_*

Workflow lengkap Mode Server:

# 1. Edit kode di server (via SSH)
cd /home/scola/odoo/scola-fe-v2  # atau custom_addons_scola/gcgscola

# 2. Jalankan QC gates
npm run lint && npm run type-check
npx vitest run --changed HEAD~1
npm run test:contract
npm run build  # Build produksi

# 3. Deploy langsung ke production
# Frontend: Copy dist/ ke nginx docroot atau restart Vite service
# Backend: ./odoo-bin -c config/odoo-devscola.conf -d scoladev -u MODULE --stop-after-init

# 4. Commit dengan [skip ci] (deployment sudah selesai di server)
git add .
git commit -m "feat(xxx): deskripsi [skip ci]"
git push origin develop

Perintah dev (untuk testing):

# Backend (Odoo)
cd /home/scola/odoo
./odoo-bin -c config/scola-dev.conf

# Frontend dev server (Vite)
cd /home/scola/odoo/scola-fe-v2
npm run dev

4.4 Quick Start Mode Lokal (GitHub Actions Deployment)¶

Karakteristik: Developer bekerja di local machine. Deployment terjadi via GitHub Actions CI/CD setelah push.

Gunakan .env.local untuk override lokal (file ini di-ignore git):

# contoh isi .env.local
VITE_API_URL="http://localhost:8069"

Workflow lengkap Mode Remote/Local:

# 1. Edit kode di local machine
cd <local-path>/scola-fe-v2  # atau custom_addons_scola/gcgscola

# 2. Testing lokal (opsional tapi direkomendasikan)
npm run lint
npm run type-check
npm run dev  # Test di localhost

# 3. Commit (TANPA [skip ci] — biarkan CI/CD berjalan)
git add .
git commit -m "feat(xxx): deskripsi"

# 4. Push ke remote (trigger GitHub Actions CI/CD)
git push origin develop

# 5. Verifikasi deployment via GitHub Actions log atau cek server

Perintah utama development:

# Backend (Odoo lokal)
cd <local-path>/odoo
./odoo-bin -c config/scola-dev.conf

# Frontend
cd <local-path>/scola-fe-v2
npm install
npm run dev

Perbedaan dengan Mode Server: - JANGAN gunakan [skip ci] — biarkan GitHub Actions trigger deployment - Deployment otomatis via workflow, bukan manual di server - Build terjadi di GitHub runner, bukan di server target

Catatan penting: - Jangan mengubah .env.production. - Pastikan scola-fe-v2/vite.config.js sesuai dengan mode yang dipakai.

4.5 Pindah Mode¶

Sebelum berpindah mode: - Bersihkan override lokal (.env.local atau env vars sementara) - Verifikasi target backend (local atau remote) - Pastikan tidak ada perubahan lingkungan yang ikut ter-commit

5. Arsitektur API (Same-Origin)¶

Ringkasannya: - Produksi wajib same-origin melalui /api. - VITE_API_URL di produksi harus kosong (commented). - Untuk dev lokal, boleh pakai VITE_API_URL atau Vite proxy.

Jika menemukan error CORS, cek: - .env.production tidak mengaktifkan VITE_API_URL - Output build memakai baseURL: "/api"

6. Alur Kerja Agentic AI (Ringkas)¶

Understand: baca issue dan konteks, identifikasi file terkait
Plan: pecah task, urutkan langkah, definisikan test
Implement: ubah kode sesuai pola yang ada, hindari asumsi
Verify: lint, test, manual check jika UI
Document: update docs dan changelog jika perlu
Complete: rangkum perubahan dan siap review

7. Quality Gates Minimum¶

Backend:

python -m py_compile path/to/file.py
./odoo-bin -c config/scola-dev.conf -u MODULE_NAME --stop-after-init

Frontend:

npm run lint
npm run test:unit
npm run build

8. Update Dokumentasi Setelah Fix¶

Jika masalah sudah teratasi: - Update dokumentasi yang relevan (misalnya ARCHITECTURE-API.md) - Tambahkan catatan penyebab dan solusi singkat - Catat perubahan di CHANGELOG jika ada

Tujuan: mencegah error yang sama terulang di task berikutnya.

8.1 Lesson Learned: Domain API, RBAC, dan Observability¶

Untuk fitur bisnis yang punya workflow dan pembatasan akses, gunakan aturan berikut: - Frontend wajib konsumsi endpoint domain yang eksplisit seperti /api/portal/... dan /api/manage/..., bukan menjadikan /web/dataset/call_kw sebagai kontrak utama fitur. - Jangan pertahankan dua jalur akses untuk feature yang sama. Jika endpoint backend resmi sudah tersedia, hapus fallback ORM atau fallback legacy di frontend. - Capability di route, menu, atau komponen frontend hanya alat UX. Otoritas final tetap ACL, record rule, dan sinkronisasi group di backend. - Jika halaman admin berperilaku seperti portal, audit backend security lebih dulu. Jangan menambal list/filter frontend sebelum membuktikan respons backend memang salah. - Untuk endpoint sensitif, tambahkan log terstruktur di backend minimal untuk: user context, group flags penting, domain request, visible count, dan sudo count. - Jika modul memakai group, model, atau helper dari modul lain, dependency harus eksplisit di __manifest__.py. - Perubahan pada ACL, record rule, atau sinkronisasi group harus disertai migration atau upgrade step agar user lama ikut terkoreksi. - Untuk debugging visibility data, selalu pisahkan tiga kemungkinan: record tidak tersimpan, record tersimpan tetapi tidak terlihat karena rule, atau frontend memanggil endpoint yang salah. - Definisikan kontrak portal dan manage sejak awal. Contoh: portal hanya published, sedangkan admin/manage harus melihat seluruh lifecycle draft -> submitted -> approved -> published -> archived/rejected.

8.2 Lesson Learned: Pengujian Lokal FE ke Backend Dev Server¶

Untuk repo scola-fe-v2, baseline yang sudah terbukti untuk pengujian end-to-end lokal adalah: - Frontend dijalankan dari http://localhost:5173 - Backend dev yang dipakai adalah https://be-dev.gcgscola.id - Database dev yang dipakai adalah scoladev - Kredensial QA role dibaca dari .env.e2e.local

Aturan kerja: - Jangan menebak host backend. devscola.gcgscola.id pernah gagal resolve; yang terbukti merespons adalah https://dev.gcgscola.id dan https://be-dev.gcgscola.id. - Untuk E2E lokal, override backend melalui env var E2E_ODOO_URL=https://be-dev.gcgscola.id. vite.config.js memang sudah membaca env ini untuk proxy /api. - Untuk Playwright yang menarget backend remote/non-local, jangan mengandalkan Vite yang kebetulan sudah hidup. Mulai 17 Maret 2026, playwright.config.ts default ke reuseExistingServer=false untuk target seperti https://be-dev.gcgscola.id agar tidak diam-diam me-reuse server stale yang masih mem-proxy ke 127.0.0.1:8069. - Jika memang sengaja ingin memakai Vite yang sudah hidup, set E2E_REUSE_EXISTING_SERVER=true dan pastikan proxy target-nya benar. Jika port 5173 sedang dipakai server yang salah target, Playwright sekarang akan fail fast karena menjalankan Vite dengan --strictPort. - Mulai dari test auth setup dulu untuk membuktikan sesi role valid sebelum menjalankan smoke suite lain. - Jika setup-auth gagal dengan HTTP 200 tetapi payload login berisi top-level JSON-RPC error, perlakukan itu sebagai outage/kerusakan backend auth, bukan regresi FE. Pada 17 Maret 2026 be-dev pernah mengembalikan psycopg2.errors.InFailedSqlTransaction dari /api/auth/login untuk role teacher, student, parent, dan admin. - Saat backend auth sedang rusak tetapi file .auth/*.json lokal masih valid, untuk diagnosis FE yang tidak butuh fresh login gunakan npx playwright test --project=chromium --no-deps ... agar Playwright tidak memaksa menjalankan project setup. - Jika target adalah validasi paket Starter/Tier 1, gunakan smoke Starter. Jangan memasukkan CBT ke smoke Starter karena CBT adalah paket di atasnya. - Untuk smoke SPMB yang butuh applicant nyata, sediakan seed env E2E_SPMB_APPLICATION_NUMBER dan E2E_SPMB_ADMISSION_ID agar test tidak perlu menunggu lookup /api/SPMB/my/admissions pada server dev yang masih cold.

Catatan CI/CD: E2E Starter Smoke tidak lagi dijalankan otomatis pada push/PR/deploy karena instalasi browser Playwright di runner GitHub sering menjadi bottleneck. Jalankan gate ini langsung di server saat perubahan menyentuh auth, routing, atau flow utama. Jika perlu bukti remote, gunakan manual workflow_dispatch dengan input run_e2e_smoke=true.

Urutan perintah yang direkomendasikan:

# 1. Verifikasi login/session semua role QA
E2E_ODOO_URL=https://be-dev.gcgscola.id npx playwright test tests/e2e/setup-auth.spec.ts --project=setup --workers=1

# 2. Verifikasi baseline Starter
E2E_ODOO_URL=https://be-dev.gcgscola.id npm run test:e2e:smoke:starter

# 3. Verifikasi smoke SPMB dengan seed applicant nyata jika perlu
E2E_ODOO_URL=https://be-dev.gcgscola.id E2E_SPMB_APPLICATION_NUMBER=SPMB-2026-0005 E2E_SPMB_ADMISSION_ID=5 npx playwright test tests/e2e/smoke/spmb_smoke.spec.ts --workers=1

# 4. Jika memang ingin me-reuse Vite yang sudah hidup
E2E_REUSE_EXISTING_SERVER=true E2E_ODOO_URL=https://be-dev.gcgscola.id npm run test:e2e:smoke:starter

# 5. Jika mengaudit paket Professional/Tier 2
E2E_ODOO_URL=https://be-dev.gcgscola.id npm run test:e2e:smoke:professional

Hasil yang sudah pernah terbukti: - setup-auth lulus untuk teacher, student, parent, admin, dan admin_staff - Smoke lokal via localhost:5173 ke backend scoladev lulus untuk baseline Starter - Smoke SPMB lokal lulus stabil jika applicant seed yang sama dipakai, saat ini SPMB-2026-0005 dengan admission id 5

Implikasi: - Untuk task berikutnya, agent tidak perlu lagi menebak apakah pengujian harus ke 127.0.0.1:8069 atau host lain. - Default verifikasi lokal untuk FE adalah localhost:5173 dengan E2E_ODOO_URL=https://be-dev.gcgscola.id, kecuali user secara eksplisit meminta environment berbeda.

Catatan implementasi packaging/tiering: - Auth payload FE sekarang mendukung platform_tier dari top-level maupun nested container seperti entitlements, tier_entitlements, dan subscription.plan. - Entitlement modul bisa dikirim backend sebagai map (feature_flags, module_flags) atau allowlist/blocklist (enabled_features, disabled_features, dst). Saat menerima allowlist, FE akan fail-closed untuk modul premium yang tidak disebut. - Runtime featureFlags harus dianggap state per sesi. Saat mengaudit login/logout/load session, verifikasi bahwa flag di-reset dulu sebelum entitlement tenant baru diterapkan.

10. Server-First Deployment Flow¶

Berlaku saat pengembangan dilakukan langsung di server (/home/scola/odoo) dan semua pengujian sudah dijalankan di server sebelum push.

Kapan Menggunakan `[skip ci]`¶

Gunakan tag [skip ci] di commit message jika semua kondisi berikut terpenuhi:

Perubahan dikembangkan dan diverifikasi langsung di server dev (/home/scola/odoo)
Semua quality gates di bawah sudah lulus di server
Push bukan ke staging (staging selalu harus melalui CI penuh)

Jika salah satu kondisi di atas tidak terpenuhi, jangan gunakan [skip ci] — biarkan CI berjalan normal.

QC Checklist Wajib Sebelum Push `[skip ci]`¶

Checklist ini mencerminkan semua step yang dijalankan oleh GitHub Actions workflow. Tujuannya adalah memberikan jaminan setara tanpa harus menunggu CI remote.

Frontend (`scola-fe-v2`)¶

cd /home/scola/odoo/scola-fe-v2

# 1. Lint (diff-aware, sama persis dengan CI)
LINT_BASE=$(git rev-parse HEAD~1) LINT_HEAD=$(git rev-parse HEAD) npm run lint:diff
# Fallback jika diff tidak tersedia:
# npm run lint

# 2. Capability registry diff check (wajib jika ada perubahan menu/RBAC/route)
npm run check:capability-diff

# 3. Datetime/timezone legacy guard
npm run check:datetime-timezone

# 4. Type check
npm run type-check

# 5. Unit tests (changed) + contract tests (always)
npx vitest run --changed HEAD~1 --reporter=verbose --passWithNoTests
npm run test:contract

# 6. Build produksi
npm run build

# 7. E2E smoke manual server gate (wajib jika perubahan menyentuh auth, routing, atau flow utama)
E2E_ODOO_URL=https://be-dev.gcgscola.id npm run test:e2e:smoke:starter
# GitHub Actions default tidak menjalankan gate ini agar CI/CD tidak menunggu install browser Playwright.
# Jika butuh bukti remote, trigger workflow_dispatch dengan run_e2e_smoke=true.

Semua step di atas harus exit 0 sebelum push.

Backend (`custom_addons_scola/gcgscola`)¶

cd /home/scola/odoo/custom_addons_scola/gcgscola

# 1. Python syntax check semua file yang diubah
python3 -m py_compile path/to/changed_file.py
# Atau batch check seluruh modul yang berubah:
find scola_MODUL_DIUBAH -name '*.py' -print0 | xargs -0 python3 -m py_compile

# 2. Modular unit test suites (pure Python, tidak butuh Odoo running)
python3 scola_core/tests/test_auth_capabilities_unit.py
python3 scola_core/tests/test_feature_access_unit.py
python3 scola_core/tests/test_ir_http_contract_unit.py
python3 scola_core/tests/test_modular_topology_unit.py
python3 scola_core/tests/test_modular_support_unit.py
python3 scola_core/tests/test_addon_catalog_unit.py
python3 scola_cbt/tests/test_runner_admission_unit.py

# 3. Modular boundary checks
python3 scripts/modular/dep_graph_check.py
python3 scripts/modular/sudo_budget_check.py --strict
python3 scripts/modular/controller_route_budget_check.py
python3 scripts/modular/csrf_audit_check.py
python3 scripts/modular/init_import_check.py

# 4. Package support tooling smoke
python3 -m py_compile scripts/modular/package_support.py
python3 scripts/modular/package_support.py transition
python3 scripts/modular/package_support.py diagnose --feature-flag scola_accounting

# 5. Odoo module upgrade di server dev
/home/scola/odoo/odoo-bin -c /home/scola/odoo/odoo-devscola.conf \
  -d scoladev -u MODULE_YANG_DIUBAH --stop-after-init

# 6. Health check
curl -sf http://localhost:8074/web/login > /dev/null && echo 'OK'