aso/AGENTS.md

AGENTS.md

File ini berisi instruksi untuk AI coding agent yang bekerja di repository ini.

Project Overview

Project name: ASO (Laravel + Modules) Purpose: Platform operasional health insurance/managed care untuk pengelolaan member, corporate policy, claim, monitoring, livechat, dan pelaporan. Main users: Tim internal operasional, portal client corporate, portal hospital. Business domain: Healthtech / asuransi kesehatan / manajemen klaim dan layanan kesehatan.

Tech Stack

Backend: PHP 8+, Laravel 9, nwidart/laravel-modules. Frontend: React + TypeScript + Vite (utama di frontend/dashboard dan frontend/client-portal), plus aset root Laravel (resources/, Vite/Mix). Database: MySQL/MariaDB (via Eloquent ORM + Laravel migrations). Queue/background jobs: Laravel Queue (jobs table tersedia; default testing sync). Cache: Laravel cache (driver mengikuti .env, testing pakai array). Auth: Laravel Sanctum, Spatie Permission (role/permission middleware), sebagian flow JWT untuk integrasi tertentu. Deployment: Build frontend ke public/dashboard dan public/client-portal; backend Laravel standar. Package manager: Composer (PHP), npm/yarn/pnpm (frontend, mixed antar subproject).

Local Setup

Install dependencies:

composer install
npm install
cd frontend/dashboard && yarn install
cd ../client-portal && yarn install

Run app:

php artisan serve
npm run dev
cd frontend/dashboard && yarn start
cd ../client-portal && yarn start

Run tests:

php artisan test

Run lint:

cd frontend/dashboard && yarn lint
cd ../client-portal && yarn lint

Run typecheck:

# Belum ada script typecheck standar di root/subproject.
# Jika diperlukan, gunakan tsc manual per frontend setelah konfirmasi tim.

Run build:

npm run production
cd frontend/dashboard && yarn build
cd ../client-portal && yarn build

Run migrations:

php artisan migrate

Repository Structure

app/                      # Core Laravel app (models, services, middleware, controllers)
routes/                   # Root web/api routes
Modules/                  # Domain/module-based backend (Client, Internal, Linksehat, Primaya, HospitalPortal)
Modules/*/Routes/         # Route entry point tiap module
Modules/*/Http/Controllers/Api/
database/migrations/      # Root migrations
frontend/dashboard/       # React TS admin/internal dashboard
frontend/client-portal/   # React TS client portal
resources/                # Blade/views/assets untuk app Laravel utama
public/                   # Public assets + output build frontend
tests/                    # PHPUnit tests (Feature/Unit)

Architecture Rules

• Tempatkan business logic di layer service/domain yang sudah ada (app/Services, Modules/*/Services) dan jaga controller tetap tipis.
• API layer mengikuti pemisahan module: endpoint module didefinisikan di Modules/<ModuleName>/Routes/api.php dengan controller module terkait.
• Untuk perubahan schema, gunakan migration baru; jangan ubah migration lama kecuali ada instruksi eksplisit.
• Untuk frontend, ikuti pattern existing per app (src/pages, src/components, src/hooks, src/sections) dan hindari cross-import antar app dashboard/client-portal.
• Testing backend utama menggunakan PHPUnit (tests/Feature, tests/Unit); tambah regression test untuk perubahan behavior penting.

Coding Standards

• Ikuti pattern existing project sebelum membuat pattern baru.
• Buat perubahan kecil dan fokus.
• Jangan lakukan refactor yang tidak berhubungan.
• Jangan hardcode secrets.
• Jangan bypass validation.
• Jangan bypass auth/permission checks.
• Pilih code yang eksplisit dan mudah dibaca dibanding code yang terlalu clever.
• Tambahkan atau update test jika behavior berubah.

Git Rules

• Jangan commit kecuali user secara eksplisit meminta.
• Jangan push kecuali user secara eksplisit meminta.
• Jangan rewrite git history kecuali user secara eksplisit meminta.
• Tampilkan file yang berubah di final response.

Security Rules

• Jangan pernah print secrets.
• Jangan ubah nilai .env asli kecuali diminta secara eksplisit.
• Gunakan .env-example/.env.example untuk dokumentasi environment variables.
• Validasi auth, permissions, dan scoping corporate/member untuk protected data.
• Untuk endpoint API, pertahankan middleware auth yang ada (auth:sanctum, role/permission, middleware khusus module).
• Minta konfirmasi sebelum destructive data changes.

Database Rules

• Gunakan migration system project ini.
• Jangan edit historical migrations kecuali project ini memang mengizinkan.
• Sertakan rollback/safety notes untuk schema changes.
• Pertimbangkan existing production data.
• Perhatikan migrasi dapat berasal dari root database/migrations dan modul tertentu.

Testing Rules

Sebelum selesai, jalankan command yang relevan:

php artisan test
cd frontend/dashboard && yarn lint
cd frontend/client-portal && yarn lint

Jika command tidak bisa dijalankan, jelaskan alasannya dan command apa yang harus dijalankan manual.

AI Agent Workflow

Untuk feature work:

1. Baca file ini.
2. Inspect pattern yang sudah ada.
3. Tulis plan singkat untuk pekerjaan non-trivial.
4. Tanya klarifikasi jika requirement kurang jelas.
5. Implement perubahan kecil dan fokus.
6. Jalankan test/lint/typecheck/build yang relevan.
7. Rangkum file yang berubah, command yang dijalankan, dan risiko.

Untuk debugging:

1. Reproduce atau inspect issue.
2. Identifikasi root cause sebelum mengubah code.
3. Buat fix minimal yang aman.
4. Tambahkan regression test jika memungkinkan.
5. Jalankan verification.

Final Response Format

Summary:
- ...

Files changed:
- ...

Commands run:
- ...

Risks / notes:
- ...