base-api-scramble-mcp 1.0.0

package/docs/LARAVEL-API-TEST.md

@@ -0,0 +1,355 @@
+# KONTEKS & TUJUAN
+Anda adalah Laravel Testing Expert. Tugas Anda: membuat automated feature tests untuk semua module/endpoint API di aplikasi Laravel, dengan pendekatan sistematis dan problem-solving otomatis.
+
+# AUTHENTICATION & AUTHORIZATION
+
+## Default Test Account
+Aplikasi ini memiliki akun default dari seeder untuk testing:
+- **Email:** admin@gmail.com
+- **Password:** password
+
+## Cara Mendapatkan Token untuk Authenticated Requests
+```php
+// Di dalam test method atau setUp()
+$response = $this->postJson('/api/v1/login', [
+    'email' => 'admin@gmail.com',
+    'password' => 'password',
+]);
+
+$this->token = $response->json('token');
+```
+
+## Penggunaan Token dalam Request
+```php
+// Untuk endpoint yang memerlukan authentication
+$response = $this->withHeaders([
+    'Authorization' => 'Bearer ' . $this->token,
+])->getJson('/api/v1/endpoint');
+
+// ATAU menggunakan method helper (jika tersedia)
+$response = $this->withToken($this->token)
+    ->getJson('/api/v1/endpoint');
+```
+
+## Template Test Class dengan Authentication
+```php
+<?php
+
+namespace Tests\Feature;
+
+use Tests\TestCase;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use App\Models\{ModelName};
+
+class {ModuleName}Test extends TestCase
+{
+    use RefreshDatabase;
+
+    protected string $token;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        
+        // Seed database (jika diperlukan)
+        $this->seed();
+        
+        // Get authentication token
+        $response = $this->postJson('/api/v1/login', [
+            'email' => 'admin@gmail.com',
+            'password' => 'password',
+        ]);
+        
+        $this->token = $response->json('token');
+    }
+
+    /** @test */
+    public function it_can_list_{module}_with_pagination()
+    {
+        $response = $this->withHeaders([
+            'Authorization' => 'Bearer ' . $this->token,
+        ])->getJson('/api/v1/{endpoint}');
+
+        $response->assertStatus(200);
+        // ... assertions lainnya
+    }
+
+    // ... test methods lainnya
+}
+```
+
+## Strategi Authentication dalam Test
+
+1. **Setup Method (Recommended):**
+   - Login sekali di `setUp()` untuk semua test dalam class
+   - Efisien untuk multiple test methods
+   - Token tersedia di semua test methods via `$this->token`
+
+2. **Per Test Method:**
+   - Login di setiap test method jika butuh kondisi berbeda
+   - Gunakan jika test memerlukan user dengan role/permission berbeda
+
+3. **Helper Method (Optional):**
+```php
+protected function authenticatedRequest(string $method, string $uri, array $data = [])
+{
+    return $this->withHeaders([
+        'Authorization' => 'Bearer ' . $this->token,
+    ])->json($method, $uri, $data);
+}
+
+// Penggunaan:
+$response = $this->authenticatedRequest('GET', '/api/v1/endpoint');
+```
+
+# LANGKAH KERJA SISTEMATIS
+
+## FASE 1: DISCOVERY & MAPPING
+1. Jalankan `php artisan route:list --json` untuk mendapatkan daftar lengkap routes
+2. Identifikasi routes yang memerlukan authentication (middleware: auth, auth:sanctum, dll)
+3. Kelompokkan routes berdasarkan module/resource (prefix atau controller)
+4. Identifikasi struktur CRUD untuk setiap module:
+   - Index/List (GET)
+   - Show/Detail (GET)
+   - Store/Create (POST)
+   - Update (PUT/PATCH)
+   - Delete (DELETE)
+   - Custom endpoints lainnya
+
+## FASE 2: ANALISIS PER MODULE
+Sebelum membuat test untuk setiap module, lakukan analisis:
+
+1. **Authentication Requirements:**
+   - Cek apakah endpoint memerlukan authentication
+   - Identifikasi middleware yang digunakan (auth:sanctum, auth:api, dll)
+   - Catat jika ada role/permission tertentu yang diperlukan
+
+2. **Request Requirements:**
+   - Buka file FormRequest atau validasi di Controller
+   - Catat semua field yang required, optional, dan rule validasinya
+   - Identifikasi field relationship (belongsTo, hasMany, dll)
+
+3. **Response Structure:**
+   - Periksa struktur response dari Controller/Resource
+   - Identifikasi field yang di-return di response JSON
+   - Catat struktur nested data (relationships yang di-load)
+
+4. **Dependencies:**
+   - Identifikasi model dependencies (foreign keys)
+   - Tentukan urutan factory/seeding yang diperlukan
+   - Catat middleware atau authorization yang digunakan
+
+## FASE 3: IMPLEMENTASI TEST PER MODULE
+
+Untuk setiap module, buat test file dengan struktur lengkap:
+
+### Template Test Structure:
+```php
+<?php
+
+namespace Tests\Feature;
+
+use Tests\TestCase;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+use App\Models\{ModelName};
+// Import models lain yang dibutuhkan
+
+class {ModuleName}Test extends TestCase
+{
+    use RefreshDatabase;
+
+    protected string $token;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        
+        // Seed database (pastikan UserSeeder dijalankan)
+        $this->seed();
+        
+        // Login to get authentication token
+        $response = $this->postJson('/api/v1/login', [
+            'email' => 'admin@gmail.com',
+            'password' => 'password',
+        ]);
+        
+        $this->token = $response->json('token');
+    }
+
+    /** @test */
+    public function it_requires_authentication()
+    {
+        // Test tanpa token harus return 401
+        $response = $this->getJson('/api/v1/{endpoint}');
+        $response->assertStatus(401);
+    }
+
+    /** @test */
+    public function it_can_list_{module}_with_pagination()
+    {
+        // Setup: Create sample data
+        // Act: Hit endpoint with token
+        $response = $this->withHeaders([
+            'Authorization' => 'Bearer ' . $this->token,
+        ])->getJson('/api/v1/{endpoint}');
+        
+        // Assert: Check response structure, pagination, data
+        $response->assertStatus(200);
+    }
+
+    /** @test */
+    public function it_can_show_{module}_detail()
+    {
+        // Test dengan data valid dan token
+    }
+
+    /** @test */
+    public function it_returns_404_when_{module}_not_found()
+    {
+        // Test edge case dengan authentication
+    }
+
+    /** @test */
+    public function it_can_create_{module}_with_valid_data()
+    {
+        // Setup: Prepare valid payload sesuai FormRequest
+        $payload = [
+            // ... data sesuai validation rules
+        ];
+        
+        // Act: POST request with authentication
+        $response = $this->withHeaders([
+            'Authorization' => 'Bearer ' . $this->token,
+        ])->postJson('/api/v1/{endpoint}', $payload);
+        
+        // Assert: Check 201, response structure, database
+        $response->assertStatus(201);
+    }
+
+    /** @test */
+    public function it_validates_required_fields_when_creating_{module}()
+    {
+        // Test validation untuk setiap required field dengan auth
+        $response = $this->withHeaders([
+            'Authorization' => 'Bearer ' . $this->token,
+        ])->postJson('/api/v1/{endpoint}', []);
+        
+        $response->assertStatus(422);
+    }
+
+    /** @test */
+    public function it_can_update_{module}_with_valid_data()
+    {
+        // Test update dengan partial/full data dan authentication
+    }
+
+    /** @test */
+    public function it_can_delete_{module}()
+    {
+        // Test soft delete atau hard delete dengan authentication
+    }
+    
+    // Tambahkan test untuk custom endpoints jika ada
+}
+```
+
+### Assertion Checklist untuk Setiap Test:
+- ✅ Authentication check (401 without token)
+- ✅ HTTP Status Code (200, 201, 204, 404, 422, dll)
+- ✅ Response JSON structure (`assertJsonStructure`)
+- ✅ Response data accuracy (`assertJsonFragment`, `assertJson`)
+- ✅ Database changes (`assertDatabaseHas`, `assertDatabaseMissing`)
+- ✅ Database count (`assertDatabaseCount`)
+- ✅ Validation error messages (untuk negative tests)
+
+## FASE 4: PROBLEM SOLVING OTOMATIS
+
+Jika test GAGAL, lakukan troubleshooting sistematis:
+
+1. **Analisis Error Message:**
+   - Baca error stack trace dengan teliti
+   - Identifikasi root cause (validation, missing data, logic error, auth issue)
+
+2. **Authentication Issues:**
+   - Jika error 401: Pastikan token sudah diset dengan benar
+   - Jika error 403: Check role/permission requirements
+   - Jika token null: Pastikan seeder sudah dijalankan dan login berhasil
+   - Verify endpoint login (`/api/v1/login`) dan token location di response
+
+3. **Perbaikan Bertahap:**
+   - Jika authentication error: Periksa token dan header Authorization
+   - Jika validation error: Sesuaikan payload dengan FormRequest rules
+   - Jika database error: Periksa foreign key constraints dan dependencies
+   - Jika response mismatch: Update assertion atau perbaiki Controller
+
+4. **Iterasi & Verifikasi:**
+   - Perbaiki satu issue pada satu waktu
+   - Re-run test setelah setiap perbaikan
+   - Jika masih gagal, cek file Controller dan Model terkait
+   - Dokumentasikan perubahan yang dilakukan
+
+5. **Edge Cases:**
+   - Test tanpa authentication (should return 401)
+   - Test dengan invalid/expired token
+   - Test dengan data kosong
+   - Test dengan data invalid (wrong type, format)
+   - Test dengan foreign key yang tidak exist
+   - Test authorization (jika ada role/permission)
+
+## FASE 5: EKSEKUSI BERTAHAP
+
+**PENTING - RULES EKSEKUSI:**
+1. ⚠️ Pastikan seeder sudah dijalankan (`$this->seed()` atau `php artisan db:seed`)
+2. ⚠️ Verify akun admin@gmail.com tersedia dan bisa login
+3. ⚠️ Kerjakan SATU module FULL hingga SEMUA test PASS
+4. ⚠️ Jangan lanjut ke module berikutnya jika masih ada test yang FAILED
+5. ⚠️ Jalankan `php artisan test --filter={ModuleName}Test` untuk verifikasi
+6. ⚠️ Setelah ALL PASS, commit perubahan sebelum lanjut module berikutnya
+7. ⚠️ Ulangi proses untuk module berikutnya
+
+## FASE 6: REPORTING
+
+Setelah menyelesaikan setiap module, buat summary:
+```
+✅ Module: {Nama Module}
+- Total Endpoints: X
+- Total Tests: X (including authentication tests)
+- Status: ALL PASSED
+- Coverage: Authentication + List/Show/Create/Update/Delete + custom endpoints
+- Waktu Eksekusi: X seconds
+- Authentication: ✅ Token-based (Sanctum/Passport)
+```
+
+# MODULE YANG DIABAIKAN (SKIP)
+- User
+- Permissions  
+- Roles
+- Telescope
+- Activity Log
+- Post
+- Label
+
+Jika menemukan routes dari module ini, SKIP dan lanjut ke module berikutnya.
+
+# OUTPUT YANG DIHARAPKAN
+1. Test file PHP yang executable dan comprehensive
+2. Semua test PASS tanpa error
+3. Authentication handling yang proper di setiap test
+4. Coverage minimal: Authentication check + CRUD lengkap per module
+5. Code yang clean, readable, dan well-documented
+6. Problem solving dilakukan secara otomatis hingga test berhasil
+
+# VALIDASI AKHIR
+Sebelum declare selesai:
+- [ ] Seeder berhasil dijalankan dan akun admin tersedia
+- [ ] Login endpoint working dan return token dengan benar
+- [ ] Token digunakan di semua authenticated requests
+- [ ] Semua module (kecuali yang di-skip) sudah memiliki test
+- [ ] Semua test berstatus PASSED
+- [ ] Authentication tests included (401 without token)
+- [ ] Response structure sesuai dengan actual API
+- [ ] Request payload sesuai dengan validation rules
+- [ ] Database assertions akurat
+- [ ] Jalankan `php artisan test` untuk final check
+
+Mulai dengan menjalankan `php artisan route:list --json` dan laporkan hasilnya.

package/docs/MAKE-EXPORT-EXCEL-COMMAND.md

@@ -0,0 +1,215 @@
+# Make Export Excel Command
+
+Command untuk generate controller dan DataProvider export Excel secara otomatis.
+
+## Usage
+
+```bash
+php artisan make:export-excel {namaExport}
+```
+
+### Contoh
+
+```bash
+php artisan make:export-excel Category
+```
+
+Akan menghasilkan:
+- **DataProvider**: `app/Exports/DataProviders/CategoryExportDataProvider.php`
+- **Controller**: `app/Http/Controllers/Api/V1/CategoryExportController.php`
+
+## File yang di-generate
+
+### 1. DataProvider (`CategoryExportDataProvider.php`)
+
+DataProvider akan otomatis:
+- Membaca data dari model yang sesuai (misal: `Category` model)
+- Menyediakan method `getRawData()` untuk query data
+- Menyediakan method `getHeaders()` untuk header kolom
+- Menyediakan method `getDataMapper()` untuk mapping data
+- Support filtering via Request (search, status, dll)
+
+**Contoh struktur:**
+```php
+namespace App\Exports\DataProviders;
+
+use App\Models\Category;
+use Illuminate\Http\Request;
+
+class CategoryExportDataProvider implements ExportDataProviderInterface
+{
+    private Request $request;
+
+    public function __construct(Request $request)
+    {
+        $this->request = $request;
+    }
+
+    public function getRawData($filters = null): array
+    {
+        $query = Category::query();
+        
+        // Apply filters dari request
+        if ($this->request->filled('search')) {
+            $query->where('name', 'like', '%' . $this->request->search . '%');
+        }
+        
+        return $query->get()->toArray();
+    }
+
+    public function getHeaders(): array
+    {
+        return ['ID', 'Name', 'Created At', 'Updated At'];
+    }
+
+    public function getDataMapper(): array
+    {
+        return [
+            'id',
+            'name',
+            'created_at' => function($item) {
+                return date('Y-m-d H:i:s', strtotime($item['created_at']));
+            },
+            'updated_at' => function($item) {
+                return date('Y-m-d H:i:s', strtotime($item['updated_at']));
+            },
+        ];
+    }
+
+    public function getOptions(): array
+    {
+        return [
+            'report_title' => 'Category Export Report',
+            'include_summary' => true,
+            'auto_size' => true,
+            'bold_header' => true,
+            'freeze_header' => true,
+        ];
+    }
+}
+```
+
+### 2. Controller (`CategoryExportController.php`)
+
+Controller akan otomatis:
+- Berada di namespace `App\Http\Controllers\Api\V1`
+- Memiliki method `export(Request $request)`
+- Menggunakan DataProvider untuk get data
+- Menggunakan `FlexibleExport` template
+- Support download langsung atau save to file
+
+**Contoh struktur:**
+```php
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Exports\Templates\FlexibleExport;
+use App\Exports\DataProviders\CategoryExportDataProvider;
+use Illuminate\Http\Request;
+
+class CategoryExportController extends Controller
+{
+    public function export(Request $request)
+    {
+        try {
+            $provider = new CategoryExportDataProvider($request);
+            
+            $rawData = $provider->getRawData();
+            $headers = $provider->getHeaders();
+            $dataMapper = $provider->getDataMapper();
+            $options = $provider->getOptions();
+
+            $export = FlexibleExport::create($rawData, $headers, array_merge($options, [
+                'data_mapper' => $dataMapper
+            ]));
+
+            if ($request->boolean('download', true)) {
+                return $export->download();
+            } else {
+                $filePath = $export->toFile();
+                return response()->json([
+                    'success' => true,
+                    'message' => 'Category export created successfully',
+                    'file_path' => $filePath,
+                    'filename' => $export->getFilename()
+                ]);
+            }
+        } catch (\Exception $e) {
+            return response()->json([
+                'success' => false,
+                'message' => 'Export failed: ' . $e->getMessage()
+            ], 500);
+        }
+    }
+}
+```
+
+## Langkah Setelah Generate
+
+1. **Pastikan Model Ada**
+   - Command akan menggunakan nama yang sama untuk model
+   - Contoh: `make:export-excel Category` akan menggunakan model `App\Models\Category`
+
+2. **Tambahkan Route**
+   
+   Edit file `routes/api_v1.php`:
+   ```php
+   use App\Http\Controllers\Api\V1\CategoryExportController;
+   
+   Route::get('categories/export', [CategoryExportController::class, 'export']);
+   ```
+
+3. **Customize DataProvider** (Optional)
+   
+   Sesuaikan logic di DataProvider:
+   - Tambah filter custom
+   - Ubah field yang di-export
+   - Sesuaikan header
+   - Tambah relationship jika perlu
+
+## Contoh Penggunaan API
+
+### Export dengan download langsung
+```bash
+GET /api/v1/categories/export
+```
+
+### Export save to file
+```bash
+GET /api/v1/categories/export?download=false
+```
+
+### Export dengan filter
+```bash
+GET /api/v1/categories/export?search=electronics
+```
+
+## Fitur
+
+✅ Auto-generate DataProvider dengan model binding  
+✅ Auto-generate Controller di folder `api/v1`  
+✅ Support filtering via Request  
+✅ Support download atau save to file  
+✅ Menggunakan FlexibleExport template  
+✅ Include header styling (bold, freeze)  
+✅ Auto-size columns  
+✅ Customizable data mapping  
+
+## Tips
+
+1. **Naming Convention**: 
+   - Command akan menghapus suffix "Export" jika ada
+   - `make:export-excel CategoryExport` = `make:export-excel Category`
+
+2. **Model Detection**:
+   - Model harus ada di `App\Models\{Name}`
+   - Pastikan model sudah dibuat sebelumnya
+
+3. **Customization**:
+   - Edit DataProvider untuk logic export yang lebih complex
+   - Tambah relationship dengan eager loading
+   - Tambah filter custom sesuai kebutuhan
+
+4. **Route Naming**:
+   - Recommended format: `{plural-resource}/export`
+   - Example: `products/export`, `users/export`, `categories/export`