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:

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

Run app:

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

Run tests:

```bash
php artisan test
```

Run lint:

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

Run typecheck:

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

Run build:

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

Run migrations:

```bash
php artisan migrate
```

## Repository Structure

```text
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:

```bash
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

```text
Summary:
- ...

Files changed:
- ...

Commands run:
- ...

Risks / notes:
- ...
```