AI Agent Master Guide (SSOT)¶

Single Source of Truth untuk semua AI Agents yang bekerja di codebase Scola

Versi: 2.0
Last Updated: 2026-06-09
Status: PRODUCTION

🎯 Tujuan Dokumen Ini¶

Dokumen ini adalah SATU-SATUNYA rujukan utama yang harus dibaca dan dipatuhi oleh semua AI Agents. Dokumen lain (development-guide.md, workspace-governance.md, dll) adalah suplemen yang mendetailkan bagian tertentu.

Aturan Keemasan: - Jika ada konflik antara dokumen lain dengan Master Guide ini, Master Guide menang. - Selalu cek versi terbaru dokumen ini sebelum memulai task. - Jika menemukan ketidakkonsistenan, laporkan untuk update Master Guide.

📋 Pre-Flight Checklist (Wajib Setiap Task)¶

Sebelum mulai coding, agent HARUS melakukan:

## Doc Compliance Checklist
- [ ] Baca Master Guide ini (minimal: Quick Rules & Mode Kerja)
- [ ] Deteksi workspace: `pwd` + `ls` untuk konfirmasi root
- [ ] Identifikasi mode kerja: Server (SSH) atau Remote (Local)
- [ ] Cek permission matrix untuk path yang akan diedit
- [ ] Baca dokumen spesifik terkait task (API, Testing, dsb)
- [ ] Verifikasi tidak ada larangan perubahan pada file target

⚡ Quick Rules (Hafalkan)¶

1. Mode Kerja (PILIH SALAH SATU)¶

Mode	Karakteristik	Deploy
Server	SSH langsung ke `/home/scola/odoo`	LANGSUNG di server setelah QC
Remote	Local machine atau GitHub web	Via GitHub Actions CI/CD

JANGAN campuradukkan kedua mode dalam satu workflow.

2. Deployment Workflow¶

Mode Server:

Edit → QC di server → Deploy langsung (build/restart) → Commit [skip ci] → Push

- [skip ci] WAJIB karena deployment sudah selesai di server - QC lengkap dijalankan di server sebelum deploy

Mode Remote:

Edit → Commit → Push (tanpa [skip ci]) → GitHub Actions CI/CD → Deploy

- [skip ci] DILARANG — biarkan CI/CD handle deployment - Build terjadi di GitHub runner

3. Permission Matrix (Jangan Langgar!)¶

Path	Permission	Catatan
`scola-fe-v2/`	✅ EDITABLE	Frontend Vue.js
`custom_addons_scola/gcgscola/`	✅ EDITABLE	Backend Scola modules
`config/nginx/`	✅ EDITABLE	Konfigurasi nginx server (di root `/home/scola/odoo/config/`)
`custom_addons/openeducat_*`	⚠️ REFERENCE ONLY	Extend via `_inherit`
`odoo/`, `addons/`	❌ READ-ONLY	Jangan diubah

3.1 Branch & Repository (WAJIB)¶

Repo / path	Branch kerja	Branch PR target	Jangan commit ke
`scola-fe-v2/` (frontend, docs portal, mkdocs)	`develop`	`develop`	`main`
`custom_addons_scola/gcgscola/` (backend Odoo)	`main` atau feature branch dari `main`	`main`	—
Dokumentasi end-user (MkDocs)	sama dengan FE → `develop`	`develop`	`main`
Modul README backend (`gcgscola/docs/modules/`)	sama dengan BE → `main`	`main`	—

Pre-flight wajib sebelum edit:

cd /home/scola/odoo/scola-fe-v2 && git branch --show-current   # harus: develop
cd /home/scola/odoo/custom_addons_scola/gcgscola && git branch --show-current  # harus: main (atau feature/* dari main)

Dokumentasi publik: https://docs.gcgscola.id — deploy dari scola-fe-v2 dengan ./scripts/build-docs.sh --install (lihat docs/operations/docs-site-deployment.md).

4. Same-Origin API Rule¶

JANGAN set VITE_API_URL di production
Gunakan relative /api untuk semua API calls
Frontend di dev.gcgscola.id → proxy ke Odoo backend

5. QC Gates (Wajib Lulus Sebelum Deploy/Push)¶

Frontend:

npm run lint          # ESLint validation
npm run type-check    # TypeScript check
npx vitest run        # Unit tests
npm run test:contract # Contract tests
npm run build         # Production build

Backend:

python3 -m py_compile <file.py>           # Syntax check
python3 scripts/modular/csrf_audit_check.py
python3 scripts/modular/controller_route_budget_check.py
odoo-bin -c conf -d db -u module --stop-after-init  # Module upgrade

📚 Referensi Dokumen Detail¶

Master Guide ini adalah ringkasan. Untuk detail spesifik, rujuk:

Topik	Dokumen
Workflow lengkap	`development-guide.md` §4, §10
Permission matrix	`workspace-governance.md`
API & CORS	`architecture-api.md`
Testing/E2E	`../qa/testing-guidelines.md`
Dokumentasi	`DOCUMENTATION_GOVERNANCE.md`
DateTime	`datetime-timezone.md`
Menu/RBAC	`menu-architecture.md`
UI Patterns	`ui-design-pattern.md`

🔧 Mode Server: Detail Operasional¶

Kapan Dipakai¶

Develop langsung via SSH di server production/staging
Butuh testing cepat dengan environment terkonfigurasi
Perubahan integrasi butuh verifikasi end-to-end

Server Paths¶

/home/scola/odoo/
├── scola-fe-v2/                    # Frontend (EDITABLE)
├── custom_addons_scola/gcgscola/   # Backend (EDITABLE)
├── custom_addons/                  # OpenEduCat (REFERENCE)
├── odoo/                           # Core (READ-ONLY)
└── config/                         # Configs

Workflow Server Lengkap¶

# 1. Edit kode di server
vim /home/scola/odoo/scola-fe-v2/src/...

# 2. Jalankan QC gates (frontend)
cd /home/scola/odoo/scola-fe-v2
npm run lint
npm run type-check
npx vitest run --changed HEAD~1
npm run test:contract
npm run build

# 3. Deploy langsung di server
# Frontend:
sudo cp -r dist/* /var/www/html/scola/
# atau restart service:
sudo systemctl restart scola-frontend

# Backend:
cd /home/scola/odoo
./odoo-bin -c config/odoo-devscola.conf \
  -d scoladev -u MODULE_NAME --stop-after-init

# 4. Commit dengan [skip ci]
git add .
git commit -m "feat(scope): deskripsi [skip ci]

Server QC:
- lint ✓
- type-check ✓
- vitest ✓
- contract tests ✓
- build ✓
- deploy ✓"

# 5. Push (deployment sudah selesai di server)
git push origin develop

💻 Mode Remote: Detail Operasional¶

Kapan Dipakai¶

Develop di local machine
Eksperimen/refactor besar tanpa ganggu server
Koneksi server terbatas

Workflow Remote Lengkap¶

# 1. Setup local
cd <local-path>/scola-fe-v2
cp .env.development.local.example .env.local
# Edit .env.local: VITE_API_URL="http://localhost:8069"

# 2. Edit kode
vim src/...

# 3. Test lokal (opsional tapi direkomendasikan)
npm run lint
npm run type-check
npm run dev  # Test di localhost:5173

# 4. Commit TANPA [skip ci]
git add .
git commit -m "feat(scope): deskripsi"

# 5. Push (trigger GitHub Actions CI/CD)
git push origin develop

# 6. Verifikasi deployment via GitHub Actions log
gh run list --workflow=qa-p0.yml

Catatan Penting: - JANGAN pakai [skip ci] — ini akan membuat CI/CD tidak berjalan - Build terjadi di GitHub runner, bukan di server target - Deployment ke server dilakukan oleh workflow GitHub Actions

⚠️ Larangan Mutlak¶

Larangan	Sanksi
Edit `odoo/` atau `addons/`	⛔ Dilarang keras
Edit `custom_addons/openeducat_*` langsung	⛔ Dilarang, extend via `_inherit`
Push ke `staging` dengan `[skip ci]`	⛔ Staging WAJIB CI penuh
Deploy tanpa QC	⛔ Error/rollback
Buat file .md baru di root `docs/`	⚠️ Akan diarsipkan
Set `VITE_API_URL` di production	⚠️ CORS issues

🧠 Domain Knowledge Penting¶

Rombel vs Classroom vs Batch¶

Konsep	Model	Contoh
Rombel	`op.batch`	"7A", "8B"
Ruang Fisik	`op.classroom`	"R.101", "Lab IPA"
Tingkatan	`op.course`	"Kelas 7"

Aturan: - User bilang "filter kelas" → fetch op.batch - User bilang "ruang kelas" → fetch op.classroom - op.student.classroom_id adalah LEGACY, jangan pakai - Gunakan op.student.current_batch_id untuk rombel aktif siswa

Model Backend (Scola vs OpenEduCat)¶

Aspek	OpenEduCat	Scola Custom
Lokasi	`custom_addons/openeducat_*`	`custom_addons_scola/gcgscola/scola_*`
Status	Reference only	Primary implementation
Prefix	`op.*`	`scola.*`
Contoh	`op.rules`	`scola.rules`

Aturan: Selalu verifikasi model yang aktif di backend sebelum coding frontend.

🔄 Decision Tree: Task Baru¶

Mulai Task
    │
    ▼
┌───────────────────────┐
│ 1. Baca Master Guide  │
│    (dokumen ini)      │
└───────────────────────┘
    │
    ▼
┌───────────────────────┐
│ 2. Deteksi Workspace    │
│    pwd + ls             │
└───────────────────────┘
    │
    ▼
┌───────────────────────┐
│ 3. Pilih Mode:         │
│    Server atau Remote? │
└───────────────────────┘
    │
    ├──────────────┐
    ▼              ▼
┌──────────┐  ┌──────────┐
│ Server   │  │ Remote   │
│ SSH      │  │ Local    │
└──────────┘  └──────────┘
    │              │
    ▼              ▼
┌───────────────────────┐  ┌───────────────────────┐
│ QC on server          │  │ QC lokal (opsional)   │
│ Deploy on server      │  │ Commit + Push         │
│ Commit [skip ci]      │  │ GitHub Actions deploy │
│ Push                  │  │                       │
└───────────────────────┘  └───────────────────────┘
    │
    ▼
Done

📞 Eskalasi¶

Jika menemukan situasi yang tidak tercakup di Master Guide ini:

Situasi	Tindakan
Konflik antar dokumen	Ikuti Master Guide, laporkan untuk update
Ketidakpastian mode kerja	Tanya user atau default ke Mode Server
Perubahan besar di infrastruktur	Buat task khusus, jangan ad-hoc
Dokumen lain outdated	Update Master Guide terlebih dahulu

📝 Changelog Master Guide¶

Tanggal	Versi	Perubahan
2026-06-09	2.0	SSOT consolidation: merge semua panduan ke dokumen ini
2026-06-09	1.9	Update deployment workflow: clear Server vs Remote mode
2026-01-21	1.0	Initial Master Guide creation

Selalu refer ke dokumen ini sebagai SSOT utama. Dokumen lain adalah suplemen.