base-api-scramble-mcp 1.0.0

package/docs/starting_point.md

@@ -0,0 +1,423 @@
+# Starting Point - Base API Scramble
+
+> Kickoff guide untuk clone base project dan memulai development baru.
+> Optimized agar AI (Claude, Cursor, dll) langsung paham arsitektur dan konvensi project.
+
+---
+
+## Quick Start (5 Menit)
+
+```bash
+# 1. Clone & masuk
+git clone <repo-url> nama-project
+cd nama-project
+
+# 2. Install dependencies
+composer install
+
+# 3. Setup environment
+cp .env.example .env
+php artisan key:generate
+
+# 4. Konfigurasi database di .env
+DB_CONNECTION=mysql
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DATABASE=nama_database
+DB_USERNAME=root
+DB_PASSWORD=
+
+# 5. Migrasi & seed
+php artisan migrate
+php artisan db:seed
+
+# 6. Jalankan server
+php artisan serve
+```
+
+**Default Login:**
+| Email | Password |
+|---|---|
+| `admin@gmail.com` | `password` |
+| `dev@gotrasoft.com` | `gotradev` |
+
+**Base URL:** `http://localhost:8000/api/v1`
+**API Docs:** `http://localhost:8000/docs/api` (Scramble)
+
+---
+
+## Tech Stack
+
+| Komponen | Package | Versi |
+|---|---|---|
+| Framework | Laravel | ^10.10 |
+| PHP | | ^8.1 |
+| Auth | Laravel Sanctum | ^3.3 |
+| API Docs | Scramble (auto-docs) | ^1.0 |
+| Query Builder | Spatie Query Builder | ^6.3 |
+| Role & Permission | Spatie Permission | ^6.13 |
+| Activity Log | Spatie Activity Log | ^4.9 |
+| Excel Export | PhpSpreadsheet | ^5.4 |
+
+---
+
+## Arsitektur & Pola Utama
+
+### Flow Request
+
+```
+Request → Route → FormRequest (validasi) → Controller → Query/Model → Response (ApiResponse trait)
+```
+
+### Struktur Direktori Penting
+
+```
+app/
+├── Console/Commands/
+│   ├── GC.php                    # CRUD Generator (artisan gc)
+│   └── GCFromMigration.php       # Generate dari migration existing
+├── Exports/                      # Excel export system
+│   ├── BaseExport.php            # Abstract base export
+│   └── ...DataProvider.php       # Interface-based data providers
+├── Helpers/
+│   ├── ApiResponse.php           # Trait: responseSuccess/Data/Created/Deleted/Error
+│   └── FileManagerHelper.php     # File management utilities
+├── Http/
+│   ├── Controllers/Api/V1/       # Semua controller API v1
+│   ├── Middleware/                # Standard Laravel middleware
+│   └── Requests/Api/V1/          # Form Request validasi per-endpoint
+├── Models/                       # Eloquent models (semua pakai UUID + Queryable trait)
+├── Observers/                    # Activity log observers (User, Role, Permission)
+├── Queries/                      # Query classes (Spatie QueryBuilder)
+├── Services/                     # Business logic (FileService, Payment gateways)
+└── Traits/
+    └── Queryable.php             # Trait utama: filter, sort, search, include
+
+routes/
+├── api.php                       # Base API routing
+└── api_v1.php                    # Semua route v1 (prefix /api/v1)
+
+config/
+├── export_info.php               # Custom: konfigurasi Excel export
+├── services.php                  # Payment gateway credentials (Midtrans, Xendit, PayPal, Doku)
+└── ...                           # Standard Laravel configs
+```
+
+---
+
+## Konvensi & Pattern Wajib
+
+### 1. Model
+
+Semua model **WAJIB** menggunakan:
+- `HasUuids` trait (UUID sebagai primary key, BUKAN auto-increment)
+- `Queryable` trait (integrasi Spatie QueryBuilder)
+
+```php
+use App\Traits\Queryable;
+use Illuminate\Database\Eloquent\Concerns\HasUuids;
+
+class NamaModel extends Model
+{
+    use HasFactory, HasUuids, Queryable;
+
+    protected $fillable = ['field1', 'field2'];
+
+    // Opsional: kolom yang bisa di-search via ?search=keyword
+    protected $searchable = ['field1', 'field2'];
+
+    // Opsional: relasi yang bisa di-include via ?include=relation
+    protected $relationIncludes = ['relation1', 'relation2'];
+}
+```
+
+### 2. Migration
+
+Semua migration menggunakan **UUID primary key**:
+
+```php
+Schema::create('table_name', function (Blueprint $table) {
+    $table->uuid('id')->primary();
+    // ... kolom lain
+    $table->foreignUuid('parent_id')->constrained('parents')->cascadeOnDelete(); // foreign key
+    $table->timestamps();
+});
+```
+
+### 3. Query Class
+
+Setiap model punya Query class di `app/Queries/`:
+
+```php
+namespace App\Queries;
+
+use App\Models\NamaModel;
+use Spatie\QueryBuilder\AllowedFilter;
+use Spatie\QueryBuilder\AllowedInclude;
+use Spatie\QueryBuilder\QueryBuilder;
+
+class NamaModelQuery extends QueryBuilder
+{
+    public function __construct()
+    {
+        parent::__construct(NamaModel::query());
+
+        $this
+            ->allowedIncludes([
+                AllowedInclude::relationship('relation1'),
+            ])
+            ->allowedFilters([
+                AllowedFilter::exact('id'),
+                AllowedFilter::partial('name'),
+                AllowedFilter::exact('foreign_id'),
+            ]);
+    }
+}
+```
+
+### 4. Controller
+
+Extends `Controller` (sudah include `ApiResponse` trait + `baseQuery()` method):
+
+```php
+namespace App\Http\Controllers\Api\V1;
+
+use App\Http\Controllers\Controller;
+use App\Models\NamaModel;
+use App\Queries\NamaModelQuery;
+use App\Http\Requests\Api\V1\IndexRequest;
+use App\Http\Requests\Api\V1\NamaModelStoreRequest;
+use App\Http\Requests\Api\V1\NamaModelUpdateRequest;
+
+class NamaModelController extends Controller
+{
+    public function index(IndexRequest $request)
+    {
+        $query = new NamaModelQuery();
+        return $this->responseData($this->baseQuery($query, $request), 'NamaModel retrieved successfully');
+    }
+
+    public function show(string $id)
+    {
+        $query = new NamaModelQuery();
+        return $this->responseSuccess($query->findOrFail($id), 'NamaModel retrieved successfully');
+    }
+
+    public function store(NamaModelStoreRequest $request)
+    {
+        $data = $request->validated();
+        $model = NamaModel::create($data);
+        return $this->responseSuccess($model, 'NamaModel created successfully', 201);
+    }
+
+    public function update(NamaModelUpdateRequest $request, NamaModel $namaModel)
+    {
+        $data = array_filter($request->validated(), fn($v) => $v !== null);
+        $namaModel->update($data);
+        return $this->responseSuccess($namaModel, 'NamaModel updated successfully');
+    }
+
+    public function destroy(NamaModel $namaModel)
+    {
+        $namaModel->delete();
+        return $this->responseSuccess(null, 'NamaModel deleted successfully');
+    }
+}
+```
+
+### 5. Form Request
+
+```php
+namespace App\Http\Requests\Api\V1;
+
+use Illuminate\Foundation\Http\FormRequest;
+
+class NamaModelStoreRequest extends FormRequest
+{
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    public function rules(): array
+    {
+        return [
+            /** @example John Doe */
+            'name' => 'required|string|max:255',
+            /** @example john@example.com */
+            'email' => 'required|email|unique:App\Models\NamaModel,email',
+        ];
+    }
+}
+```
+
+> Gunakan PHPDoc `@example` pada setiap rule agar Scramble auto-generate contoh di API docs.
+
+### 6. Route
+
+Tambahkan di `routes/api_v1.php` di dalam group `auth:sanctum`:
+
+```php
+Route::apiResource('nama-model', Controllers\NamaModelController::class);
+```
+
+### 7. API Response Format
+
+Semua response menggunakan format konsisten via `ApiResponse` trait:
+
+**Success:**
+```json
+{ "success": true, "message": "...", "code": 200, "data": { } }
+```
+
+**Paginated:**
+```json
+{ "success": true, "message": "...", "code": 200, "data": [], "pagination": { "current_page": 1, "total": 50, "per_page": 10, "last_page": 5, "..." : "..." } }
+```
+
+**Error:**
+```json
+{ "success": false, "message": "...", "code": 400 }
+```
+
+---
+
+## Query Parameters (Built-in)
+
+Semua endpoint `index` otomatis support:
+
+| Parameter | Contoh | Keterangan |
+|---|---|---|
+| `search` | `?search=keyword` | Full-text search di kolom `$searchable` |
+| `filter` | `?filter[name]=john&filter[status]=active` | Filter per kolom |
+| `sort_by` | `?sort_by=name&sort_order=asc` | Sorting (default: `created_at` desc) |
+| `include` | `?include=roles,permissions` | Eager load relasi |
+| `paginate` | `?paginate=20&page=2` | Pagination (default: 10) |
+| `paginate=false` | `?paginate=false` | Ambil semua tanpa pagination |
+| `first` | `?first=true` | Ambil hanya 1 data pertama |
+
+---
+
+## CRUD Generator (Artisan GC)
+
+Generate module lengkap (Migration + Model + Query + Controller + Requests + Route) dalam 1 command:
+
+```bash
+# Basic
+php artisan gc Product --fields="name:string,price:decimal,description:text"
+
+# Dengan relasi
+php artisan gc Product --fields="name:string,price:decimal,image:file" --belongsTo="Category,User" --hasMany="Review"
+
+# Preview dulu sebelum generate
+php artisan gc Product --fields="name:string,price:decimal" --preview
+
+# Lihat migration text saja
+php artisan gc Product --fields="name:string,price:decimal" --migration
+```
+
+**Field types:** `string`, `text`, `integer`/`int`, `decimal`/`float`, `boolean`/`bool`, `date`, `datetime`, `file`/`image`
+
+**Setelah generate:**
+```bash
+php artisan migrate
+```
+
+### Generate dari Migration Existing
+
+```bash
+php artisan gc:from-migration
+```
+
+---
+
+## Fitur Bawaan yang Sudah Tersedia
+
+### Authentication (Sanctum)
+- `POST /api/v1/login` - Login, dapat token
+- `POST /api/v1/logout` - Logout (auth required)
+- `GET /api/v1/me` - Profile user login
+- `PUT /api/v1/me` - Update profile
+- `PUT /api/v1/change-password` - Ganti password
+
+### Role & Permission (Spatie)
+- CRUD Role: `/api/v1/role`
+- CRUD Permission: `/api/v1/permission`
+- Assign: `/api/v1/user-role/attach`, `detach`, `sync-roles`, `sync-users`
+- Assign: `/api/v1/role-permission/attach`, `detach`, `sync-permissions`, `sync-roles`
+
+### File Management
+- CRUD File & Folder dengan soft-delete, restore, force-delete
+- Upload dengan auto-compression (Imagick)
+- Support S3 dan local disk
+
+### Excel Export
+- Flexible, Multi-Sheet, Multi-Table template
+- Data Provider pattern (interface-based)
+- Custom styling via `config/export_info.php`
+
+### Activity Log
+- Auto-log perubahan via Observers (User, Role, Permission)
+- `GET /api/v1/log-activity` - Lihat semua log
+
+### Payment Gateways
+- Midtrans, Xendit, PayPal, Doku (service classes tersedia di `app/Services/`)
+
+---
+
+## Langkah Memulai Project Baru
+
+### Checklist Setup
+
+1. **Clone & install** (lihat Quick Start di atas)
+2. **Update `.env`:**
+   - `APP_NAME` - Nama project
+   - `APP_URL` - URL production
+   - `DB_DATABASE` - Nama database
+3. **Hapus module contoh** (opsional):
+   - Hapus migration, model, controller, query, request untuk: `Post`, `Label`, `Folder`, `File` jika tidak dibutuhkan
+4. **Buat module baru** via `php artisan gc NamaModule --fields="..."`
+5. **Jalankan** `php artisan migrate`
+6. **Test** via Scramble docs di `/docs/api`
+
+### Instruksi untuk AI
+
+Saat meminta AI membuat fitur baru, gunakan prompt seperti ini:
+
+```
+Buatkan module [NamaModule] dengan fields: [daftar fields].
+Ikuti pattern yang ada di project ini:
+- Model: UUID + Queryable trait
+- Query class di app/Queries/
+- Controller extends Controller (gunakan baseQuery + ApiResponse)
+- FormRequest dengan @example untuk Scramble docs
+- Route di routes/api_v1.php dalam group auth:sanctum
+- Migration dengan uuid('id')->primary()
+```
+
+Atau lebih simpel, gunakan artisan gc dulu lalu minta AI untuk menyesuaikan:
+
+```
+Jalankan: php artisan gc Product --fields="name:string,price:decimal" --belongsTo="Category"
+Lalu sesuaikan validasi dan business logic-nya.
+```
+
+---
+
+## Referensi File Penting
+
+| Kebutuhan | File |
+|---|---|
+| Response format | `app/Helpers/ApiResponse.php` |
+| Base controller | `app/Http/Controllers/Controller.php` |
+| Queryable trait | `app/Traits/Queryable.php` |
+| Contoh controller | `app/Http/Controllers/Api/V1/UserController.php` |
+| Contoh query | `app/Queries/UserQuery.php` |
+| Contoh model | `app/Models/User.php` |
+| Contoh request | `app/Http/Requests/Api/V1/UserStoreRequest.php` |
+| Route API v1 | `routes/api_v1.php` |
+| CRUD generator | `app/Console/Commands/GC.php` |
+| File upload service | `app/Services/FileService.php` |
+| Excel export service | `app/Services/ExcelExportService.php` |
+| Export config | `config/export_info.php` |
+| Payment services | `app/Services/{Midtrans,Xendit,PayPal,Doku}/` |