# AGENTS.md

## 1. Tujuan Repository
`crmsales` adalah aplikasi CRM modular berbasis Krayin/Webkul untuk operasional sales, customer management, follow-up customer, sales activity, quotation, produk, email, automation, warehouse, dan import/export data.

Tujuan implementasi di repo ini:
- Menambah atau menyesuaikan modul bisnis di atas fondasi Krayin/Webkul yang sudah ada.
- Menjaga konsistensi arsitektur modular package-based di `packages/Webkul/*`.
- Menjaga stabilitas fitur bawaan CRM sambil menambahkan domain logic baru secara aman, incremental, dan audit-ready.

## 2. Stack Dan Arsitektur
Stack yang terdeteksi dari repo:
- Backend: PHP 8.3
- Framework: Laravel 12
- Auth: session guard `user`, dengan Sanctum untuk kebutuhan API/front stateful request
- Frontend admin: Blade + Vue 3 + Tailwind CSS + Vite 5
- Admin UI libraries: axios, vee-validate, flatpickr, vue-cal, vuedraggable, dompurify
- Testing: Pest, PHPUnit, Playwright E2E untuk admin
- Database: MySQL default
- Repository pattern: `prettus/l5-repository`
- Modular system: `konekt/concord`

Arsitektur yang tampak dari kode:
- Route -> Controller -> Repository/Service -> Model -> Blade/DataGrid/JSON response
- Banyak listing admin memakai `DataGrid` dari `packages/Webkul/DataGrid`
- Modul package di-boot lewat `config/concord.php` dan service provider masing-masing package
- Admin package adalah pusat UX operasional, ACL, menu, route admin, view, DataGrid, middleware, dan helper

## 3. Konvensi Struktur Project
Struktur utama yang harus dipertahankan:
- `packages/Webkul/*/src` sebagai lokasi utama domain dan module code
- `packages/Webkul/Admin/src` sebagai pusat admin UX, ACL, menu, routes admin, DataGrid, controller, views, helpers, middleware, dan workflow operasional
- `packages/Webkul/*/src/Database/Migrations` untuk skema tabel per modul
- `packages/Webkul/*/src/Models`, `Repositories`, `Services`, `Helpers`, `Console`, `Listeners` untuk domain logic
- `packages/Webkul/Admin/src/Config/acl.php` untuk permission tree
- `packages/Webkul/Admin/src/Config/menu.php` untuk admin navigation
- `packages/Webkul/Admin/src/Routes/Admin/*.php` untuk route admin modular
- `packages/Webkul/Admin/src/DataGrids/*` untuk list/report admin berbasis DataGrid
- `packages/Webkul/Admin/src/Resources/views/*` untuk Blade UI admin
- `packages/Webkul/WebForm/src/Resources/*` untuk UI, assets, dan komponen WebForm
- `tests/` untuk Pest/PHPUnit

Lokasi yang penting untuk integrasi project:
- `bootstrap/app.php` untuk middleware bootstrap, CSRF exception, Sanctum stateful API, dan installer middleware
- `config/concord.php` untuk registrasi module provider
- `routes/console.php` untuk scheduler/command level project
- `routes/breadcrumbs.php` untuk breadcrumb admin
- `packages/Webkul/Admin/src/Providers/AdminServiceProvider.php` untuk route, view, migration, morph map, aliases, dan exception handler

## 4. Aturan Menjaga Platform Tetap Utuh
- `crmsales` starter kit adalah fondasi utama dan tidak boleh diganti.
- Jangan mengganti frontend stack, backend structure, routing style, ACL model, UI language, atau pola modular Concord/Webkul.
- Jangan refactor besar ke arsitektur berbeda.
- Jangan membuat arsitektur tandingan di luar pola package Webkul yang sudah ada.
- Jika requirement domain bertabrakan dengan konvensi platform, adaptasikan requirement, bukan platform.
- Kompatibilitas dengan modul existing wajib dijaga.
- Hindari perubahan visual/UX yang tidak perlu.
- Jangan menghapus fitur built-in kecuali ada kebutuhan eksplisit yang disetujui.

## 5. Standar Implementasi Umum
Implementasi harus incremental per modul:
1. Schema
2. Model/Repository/Service
3. ACL
4. Menu
5. UI (Blade/DataGrid)
6. Testing
7. Reconciliation

Prinsip kerja:
- Prioritaskan service-oriented logic untuk proses bisnis kompleks.
- Reuse komponen platform sebelum membuat komponen baru.
- Gunakan event/listener hanya jika pola existing sudah memakainya.
- Jaga backward compatibility pada route, response, dan data contract yang sudah dipakai UI atau integrasi.

## 6. Standar CRUD, API, Job, Command, Report, Import/Export
Pattern standar CRUD admin:
1. Route di `packages/Webkul/Admin/src/Routes/Admin/<module>-routes.php` dengan naming `admin.<module>.*`
2. Controller di `packages/Webkul/Admin/src/Http/Controllers/*`
3. Validasi via FormRequest atau `request()->validate()` sesuai pattern existing
4. Query/listing via DataGrid class di `packages/Webkul/Admin/src/DataGrids/*`
5. View tetap Blade di `packages/Webkul/Admin/src/Resources/views/*`
6. Gunakan repository/service Webkul untuk domain write/read yang kompleks
7. Flash message, response JSON, dan redirect mengikuti pattern controller existing

Standar identifier:
- Route publik/admin yang baru atau dimodernisasi sebaiknya memakai `public_id` sebagai identifier publik, bukan raw auto-increment ID
- Pola ini sudah dipakai di beberapa model follow-up admin lewat trait `Webkul\Admin\Models\Concerns\HasPublicId`
- Untuk entitas legacy yang masih memakai integer ID, jangan paksa migrasi identifier tanpa kebutuhan eksplisit

Standar API dan response:
- API public repo ini terlihat minimal; jangan ubah contract API/JSON response yang sudah dipakai UI tanpa task yang jelas
- Untuk response admin, ikuti pola existing: HTML view untuk page load, JSON untuk AJAX/DataGrid/update action
- Error message harus aman dan tidak mengungkap detail sensitif

Standar job/command/report/import/export:
- Gunakan command bila proses bersifat batch, scheduled, atau integrasi mailbox/campaign
- Gunakan DataGrid atau helper reporting untuk list/report admin
- Untuk import/export, ikuti pola `DataTransfer` dan `FollowUp` yang sudah ada
- Untuk proses berat atau multi-step, gunakan `DB::transaction()`
- Jika ada risiko race condition, gunakan locking seperti `lockForUpdate()`

## 7. Standar Database, Migration, Model, Public Identifier, Index, Query
Pola database yang terlihat:
- Banyak tabel modul memakai internal integer PK legacy (`increments`)
- Tabel baru atau tabel follow-up tertentu memakai `char(26)` `public_id` unique
- FK umumnya `unsignedInteger` pada tabel legacy, atau `unsignedBigInteger` untuk struktur baru bila cocok
- Timestamp hampir selalu dipakai
- Soft delete hanya dipakai bila ada kebutuhan bisnis/audit yang jelas

Aturan database:
- Untuk modul baru, default enterprise yang disarankan tetap internal bigint PK, FK bertipe sesuai referensi, dan index pada kolom filter berat
- Jika terhubung ke tabel legacy yang masih `unsignedInteger/increments`, FK harus mengikuti tipe tabel referensi agar integritas DB aman
- Simpan enum/status sebagai string terkontrol dan validasi di aplikasi
- Tambahkan index untuk kolom listing, filter, search, reporting, dan foreign key
- Untuk data besar, pertimbangkan snapshot/summary table hanya jika source-of-truth query terlalu berat

Pola `public_id`:
- Gunakan `char(26)` + unique index
- Nilai default di-create via `Str::ulid()`
- Gunakan trait `Webkul\Admin\Models\Concerns\HasPublicId` pada model baru yang memang butuh identifier publik
- Jika model perlu route key publik, override `getRouteKeyName(): 'public_id'`
- Pertahankan internal numeric PK untuk relasi dan performa join

Contoh yang sudah terlihat:
- `CustomerFollowUpCustomer`, `CustomerFollowUpLog`, `CustomerFollowUpResult`, `CustomerFollowUpImportBatch`, dan `CustomerServiceHistory` memakai `public_id`
- `Person` memakai `unique_id` untuk business identity legacy follow-up, bukan `public_id`

## 8. Standar Auth, Permission, ACL, Middleware
Auth flow:
- Default guard adalah `user`
- Provider `users` menunjuk ke `Webkul\User\Models\User`
- Session login/logout admin berada di route admin auth

ACL dan permission:
- Semua permission didefinisikan di `packages/Webkul/Admin/src/Config/acl.php`
- Semua menu didefinisikan di `packages/Webkul/Admin/src/Config/menu.php`
- Setiap fitur baru wajib punya mapping:
  - key ACL
  - route terkait
  - menu visibility
- Enforcement ACL di controller menggunakan pola `bouncer()->hasPermission(...)` dan guard `auth()->guard('user')`
- Pertahankan hierarki permission existing seperti `module`, `module.create`, `module.edit`, `module.delete`, `module.view`
- Untuk scoped visibility, hormati `bouncer()->getAuthorizedUserIds()`

Middleware dan bootstrap:
- Middleware `user` adalah middleware bouncer admin login/authz
- CSRF dikecualikan hanya untuk endpoint yang memang membutuhkan exception, seperti inbound mail parse dan web form submit
- API memakai `EnsureFrontendRequestsAreStateful` untuk Sanctum
- Installer middleware `CanInstall` ditambahkan di bootstrap app

## 9. Standar Keamanan Default
Wajib diterapkan untuk task berikutnya:
- Backend validation wajib untuk semua input
- Backend authorization wajib untuk aksi yang memodifikasi data atau membaca data terbatas
- Gunakan transaction untuk operasi kritikal multi-step
- Gunakan idempotency untuk submit kritikal jika endpoint bisa menerima submit ganda
- Audit log/event harus menangkap actor, waktu, dan perubahan penting bila fitur sudah memiliki pola audit
- Gunakan query parameterized, jangan string interpolation untuk SQL mentah
- Upload safety wajib: validasi file, tipe file, ukuran, dan sanitasi bila konten diparse
- Error message harus aman dan jangan bocorkan stack trace, query, credential, atau token
- Jangan log secret, token, password, atau data sensitif
- Batasi akses endpoint admin lewat ACL dan middleware `user`
- Untuk proses yang menyentuh data kritikal atau multi-tabel, pertimbangkan `lockForUpdate()`

Catatan sensitif di repo ini:
- Follow-up import/grab data
- Email inbound processing
- Campaign processing
- Upload/import/export data
- User management
- Warehouse/inventory
- Report/query berat pada dashboard dan follow-up

## 10. Standar Frontend Dan Interaktif
Frontend yang tersedia:
- Blade adalah default rendering layer admin
- Vue 3 dipakai untuk interaksi yang lebih dinamis
- Tailwind adalah styling utama
- Icon font `icomoon` dipakai secara luas
- Ada plugin global untuk axios, emitter, flatpickr, vee-validate, draggable, vue-cal, dan helper admin

Pola frontend admin:
- Gunakan Blade untuk page shell, form, table, dan layout operasional
- Gunakan Vue bila ada interaksi yang kompleks, state lokal, picker, drag-drop, kalender, atau AJAX flow yang sering berubah
- Gunakan component/UI existing sebelum membuat komponen baru
- Jaga loading, empty state, error state, dan shimmer state bila komponen/listing butuh
- Hindari perubahan visual yang tidak perlu pada UI inti

Pola WebForm:
- `packages/Webkul/WebForm` punya build dan Tailwind sendiri
- Input asset WebForm terpisah dari admin biasa
- Jangan menyamakan build entry WebForm dengan admin root tanpa alasan kuat

## 11. Standar DataGrid, Table, Form, Component
Pola listing admin:
- DataGrid adalah standar untuk list, filter, sort, dan pagination
- Controller biasanya mengembalikan DataGrid response ketika request AJAX
- View Blade biasanya hanya menyiapkan page shell, filter area, dan container DataGrid

Aturan DataGrid:
- Gunakan kelas DataGrid spesifik per domain di `packages/Webkul/Admin/src/DataGrids/*`
- Pastikan kolom search/filter yang berat punya index database
- Gunakan `public_id` untuk URL row action bila entitas sudah dimodernisasi
- Pastikan mass action aman dan tidak merusak user current atau data yang tidak boleh dihapus

Aturan form:
- Selalu validasi server-side
- Ikuti pola controller existing untuk response JSON, redirect, dan flash message
- Gunakan component existing untuk form control bila tersedia

## 12. Standar Report, Snapshot, Rebuild
Untuk list/report berat:
- Utamakan source-of-truth table terlebih dahulu
- Gunakan snapshot/summary table hanya untuk mempercepat query besar
- Snapshot harus punya strategi rebuild yang jelas
- Rebuild harus bisa dijalankan ulang tanpa merusak integritas data utama
- Definisikan penanda sinkronisasi seperti `last_rebuilt_at` atau setara
- Definisikan ownership rebuild via job/command/service

Area report yang sensitif di repo ini:
- dashboard summary
- follow-up report
- campaign result
- warehouse/product reporting

## 13. Standar Cron, Job, Queue, Scheduler
Pola yang terlihat:
- `routes/console.php` menjadwalkan `inbound-emails:process` setiap 5 menit
- Command email inbound ada di `packages/Webkul/Email/src/Console/Commands/ProcessInboundEmails.php`
- Campaign processing ada sebagai command `campaign:process`

Aturan kerja:
- Proses scheduled, mailbox, campaign, dan batch sync harus dijalankan lewat command atau job yang jelas
- Queue default repo adalah `sync` kecuali `.env` mengubahnya
- Jika task menulis ke banyak tabel atau membutuhkan retry, gunakan job/transaction yang aman
- Jangan asumsi scheduler tambahan ada kalau tidak terlihat di `routes/console.php` atau provider package

## 14. Testing Dan Verification Flow
Flow verifikasi minimal per perubahan modul:
1. `php artisan optimize:clear`
2. `composer dump-autoload`
3. `php artisan migrate` atau migrate path modul jika diperlukan
4. Jalankan test otomatis:
   - `php artisan test`
   - atau test terfokus Pest/PHPUnit sesuai area perubahan
5. Smoke test manual:
   - ACL allow/deny
   - menu muncul sesuai permission
   - CRUD utama berjalan
   - DataGrid filter/sort/pagination
   - validasi form dan error handling
6. Reconciliation check:
   - route + ACL + menu sinkron
   - tidak ada regresi fitur existing

Tambahan verifikasi yang relevan di repo ini:
- `npm run build` untuk memastikan bundling frontend tidak rusak
- Untuk WebForm, verifikasi build area package bila task menyentuh asset WebForm
- Untuk E2E admin, gunakan Playwright bila perubahan menyentuh login, dashboard, settings, atau CRUD inti

Jika test penuh tidak memungkinkan, wajib laporkan:
- test apa yang dijalankan
- test apa yang belum dijalankan
- risiko sisa

## 15. Kontrol Dampak Lintas Fitur
Sebelum coding, identifikasi:
- dependency shared yang terdampak
- model/repository/helper/service yang dipakai banyak fitur
- ACL dan menu yang mungkin ikut berubah
- route names yang dipakai view atau redirect lain
- DataGrid, report, dan template Blade yang direferensikan lintas modul

Wajib lakukan:
- backward-compatible check
- petakan fitur lain yang terdampak
- regression smoke test minimal 1 sampai 3 fitur terkait
- laporkan risiko regresi bila ada

Area shared yang sering terdampak:
- `Webkul\Admin\Bouncer`
- `Webkul\Admin\Models\Concerns\HasPublicId`
- `Webkul\Admin\DataGrids`
- `packages/Webkul/Admin/src/Config/acl.php`
- `packages/Webkul/Admin/src/Config/menu.php`
- `packages/Webkul/Admin/src/Routes/Admin/*`
- `packages/Webkul\Core\Acl`
- `packages/Webkul\Core\Vite`
- `packages/Webkul\WebForm`
- `packages/Webkul\DataTransfer`

## 16. Format Jawaban Kerja
Setiap selesai task, gunakan format berikut:
1. Ringkasan hasil: apa yang dikerjakan dan statusnya
2. Daftar file yang diubah dengan path lengkap
3. Perubahan inti per layer:
   - schema
   - service/model/repository
   - acl/menu/route
   - ui/datagrid
4. Hasil verifikasi/testing yang dijalankan
5. Risiko/assumption yang masih terbuka
6. Next step paling relevan jika ada

Aturan komunikasi:
- Singkat, konkret, dan dapat ditindaklanjuti
- Jangan klaim test jalan jika belum dijalankan
- Jangan menyarankan perubahan yang melanggar aturan platform ini
- Jika ada hal yang belum bisa dipastikan, tulis sebagai catatan `perlu verifikasi`, bukan mengarang

## 17. Prioritas Keputusan Saat Konflik
Urutan prioritas saat ada konflik:
1. Keamanan
2. Konsistensi platform Krayin/Webkul
3. Backward compatibility
4. Stabilitas data dan integritas transaksi
5. Kesesuaian pola repo existing
6. Kebutuhan domain request

Jika conflict tidak bisa diselesaikan tanpa mengubah arsitektur utama atau kontrak penting, eskalasi keputusan terlebih dahulu sebelum coding.

## 18. Catatan Project-Specific Penting
- Admin route prefix berasal dari `config('app.admin_path')`, default `admin`
- `routes/web.php` root aplikasi nyaris kosong; traffic utama dikelola lewat package routes
- `packages/Webkul/Admin/src/Routes/Admin/web.php` memuat redirect disabled modules dan include semua route admin utama
- `packages/Webkul/Admin/src/Routes/Admin/follow-up-routes.php` adalah area domain paling spesifik dan paling sensitif di repo ini
- `packages/Webkul/Admin/src/Services/FollowUp/CustomerFollowUpImportService.php` dan model follow-up terkait adalah titik kritikal untuk import, assignment, dan public identifier
- `packages/Webkul/Email` punya command inbound email yang dijalankan scheduler
- `packages/Webkul/Marketing` punya command campaign processing
- `packages/Webkul/WebForm` memiliki build frontend terpisah dengan Vite/Tailwind sendiri
- `packages/Webkul/Admin/tests/e2e-pw` adalah sumber smoke/regression otomatis untuk admin
- Beberapa detail deployment runtime, queue driver, mail driver, dan storage driver bergantung pada `.env`, jadi perlu verifikasi bila task menyentuh area tersebut