# ERP Frontend AI Agent Instructions (`apps/erp`)

> **Tech Stack:** Vue 3, Vite, Tailwind CSS, PrimeVue 4, Pinia, Vue Router  
> **Role:** Enterprise Back-Office Operations (Inventory, Purchasing, Finance, HR)

---

## 1. Architectural Conventions

1. **Composition API**: Use `<script setup>` syntax for all Vue single file components.
2. **State Management**: Use Pinia stores under `src/stores/` (`auth.js`, `ui.js`, etc.).
3. **Contracts & Permissions**:
   - Import API endpoints from `@keluargamart/contracts/routes`.
   - Import permissions from `@keluargamart/permissions`.
   - Protect views and buttons using `can(authStore.user.permissions, PERMISSIONS.<NAME>)`.
4. **Formatting**:
   - Currency & numbers: Use `@keluargamart/utils` (`formatRupiah`, `formatNumber`, `parseMoney`).
   - Dates: Use `@keluargamart/utils` (`formatDate`).

---

## 2. Component & UI Guidelines

- **Enterprise Components (`src/components/k/`)**: Prefer using standardized design system components (`KButton`, `KDataTable`, `KModal`, `KSelect`, `KBadge`).
- **Nginx Serving & Fallback**: Production builds are served via Nginx with SPA routing fallback. Assets under `/assets/` are immutable and cached for 1 year; `index.html` must never be cached (`Cache-Control: no-cache, no-store`).
- **Same-Origin API Proxy**: In production, API calls route to same-origin `/api/*`, which Nginx proxies to `backend:8080`. Leave `VITE_API_URL` empty for production builds unless external direct routing is required.

---

## 3. Testing & Validation

- Run ERP tests: `pnpm --filter @keluargamart/erp test` (or `vitest run`).
- In test environments (`MODE === 'test'`), toast auto-dismiss is disabled to prevent race conditions during heavy parallel runs.
- Vitest configuration enforces `testTimeout: 15000` for stable component integration tests.
- Verify production build: `pnpm --filter @keluargamart/erp build`.