base-api-scramble-mcp 1.0.0

package/docs/README.md

@@ -0,0 +1,678 @@
+# 🚀 Laravel API Base with Query Pattern v6.0
+
+[![Laravel](https://img.shields.io/badge/Laravel-10.x-FF2D20?style=flat&logo=laravel)](https://laravel.com)
+[![PHP](https://img.shields.io/badge/PHP-8.1+-777BB4?style=flat&logo=php)](https://php.net)
+[![Sanctum](https://img.shields.io/badge/Sanctum-3.3-4FC08D?style=flat)](https://laravel.com/docs/sanctum)
+[![Scramble](https://img.shields.io/badge/Scramble-Pro-00C7B7?style=flat)](https://scramble.dedoc.co)
+
+> **Production-ready Laravel API with Query Pattern, Spatie QueryBuilder, and Auto-generated OpenAPI Documentation**
+
+---
+
+## 🎯 Architecture
+
+```
+Request → Controller → Query Class → Model → Response
+```
+
+**What makes this different?**
+- ✅ **Query Classes** for business logic separation
+- ✅ **Spatie QueryBuilder** for advanced filtering
+- ✅ **Queryable Trait** for consistent API behavior
+- ✅ **Scramble Pro** for auto-generated API docs
+- ✅ **Activity Logging** for audit trails
+- ✅ **FileService** with auto-compression
+
+---
+
+## ⚡ TWO POWERFUL WORKFLOWS
+
+### Workflow A: Fields-First (Quick & Simple)
+```bash
+php artisan gc Product --fields=name,price:decimal,image:file
+php artisan migrate
+```
+**Perfect for:** Simple schemas, clear requirements
+
+### Workflow B: Migration-First (Recommended)
+```bash
+# 1. Create/Generate migration
+# 2. Generate complete CRUD from migration
+php artisan gc:from-migration products
+php artisan migrate
+```
+**Perfect for:** Complex schemas, AI-generated migrations, existing projects
+
+---
+
+## 🎯 Migration-First Example
+
+**Step 1:** Create migration (manually or AI-generated)
+```php
+// database/migrations/2024_xx_xx_create_products_table.php
+Schema::create('products', function (Blueprint $table) {
+    $table->uuid('id')->primary();
+    $table->string('name');
+    $table->text('description');
+    $table->decimal('price', 10, 2);
+    $table->integer('stock');
+    $table->string('image')->nullable();
+    $table->foreignUuid('category_id')->constrained()->cascadeOnDelete();
+    $table->timestamps();
+});
+```
+
+**Step 2:** Generate complete CRUD
+```bash
+php artisan gc:from-migration products
+php artisan migrate
+```
+
+**Result:** Complete production-ready API! 🎉
+
+```
+✅ Generated Files:
+├── app/Models/Product.php (with Queryable trait)
+├── app/Queries/ProductQuery.php (filtering logic)
+├── app/Http/Controllers/Api/V1/ProductController.php
+├── app/Http/Requests/Api/V1/ProductStoreRequest.php
+├── app/Http/Requests/Api/V1/ProductUpdateRequest.php
+└── routes/api_v1.php (auto-registered)
+
+✅ Auto-detected:
+├── Fields & Types
+├── Foreign keys → belongsTo relationships
+├── File upload → FileService integration
+└── Searchable columns
+
+✅ API Endpoints:
+├── GET    /api/v1/products
+├── GET    /api/v1/products/{id}
+├── POST   /api/v1/products
+├── PUT    /api/v1/products/{id}
+└── DELETE /api/v1/products/{id}
+```
+
+---
+
+## 📦 What Gets Generated
+
+### Standard Generation (6 Files + Routes)
+
+```
+app/
+├── Models/Product.php                       # Model + Queryable trait
+│   ├── $fillable (all columns)
+│   ├── $searchable (text columns)
+│   ├── $relationIncludes (detected relations)
+│   ├── relationships (belongsTo, hasMany)
+│   └── accessors (image_url, etc)
+│
+├── Queries/ProductQuery.php                 # Business Logic Layer
+│   ├── extends Spatie QueryBuilder
+│   ├── allowedIncludes (relations)
+│   └── allowedFilters (all columns)
+│
+├── Http/
+│   ├── Controllers/Api/V1/
+│   │   └── ProductController.php           # Clean CRUD Logic
+│   │       ├── index() with Query class
+│   │       ├── show()
+│   │       ├── store() with FileService
+│   │       ├── update() with FileService
+│   │       └── destroy() with file cleanup
+│   │
+│   └── Requests/Api/V1/
+│       ├── ProductStoreRequest.php         # Create Validation
+│       │   ├── PHPDoc for Scramble
+│       │   └── comprehensive rules
+│       │
+│       └── ProductUpdateRequest.php        # Update Validation
+│           ├── 'sometimes' rules
+│           └── nullable handling
+│
+routes/api_v1.php
+└── Route::apiResource('products', ProductController::class);
+```
+
+---
+
+## 🔍 Built-in Query Features (Via Queryable Trait)
+
+### Filtering
+```bash
+GET /api/v1/products?filter[name]=iPhone
+GET /api/v1/products?filter[category_id]=uuid
+GET /api/v1/products?filter[price]=1000000
+```
+
+### Global Search
+```bash
+GET /api/v1/products?search=iPhone
+# Searches across all $searchable columns
+```
+
+### Sorting
+```bash
+GET /api/v1/products?sort=name           # Ascending
+GET /api/v1/products?sort=-price         # Descending
+GET /api/v1/products?sort=price,-stock   # Multiple
+```
+
+### Pagination
+```bash
+GET /api/v1/products?paginate=20
+GET /api/v1/products?paginate=20&page=2
+```
+
+### Including Relations
+```bash
+GET /api/v1/products?include=category
+GET /api/v1/products?include=category,brand,reviews
+```
+
+### Field Selection
+```bash
+GET /api/v1/products?fields[products]=id,name,price
+```
+
+### Combined (Real-world Example)
+```bash
+GET /api/v1/products?search=iPhone&filter[category_id]=uuid&sort=-price&include=category&paginate=15
+```
+
+---
+
+## 🎨 API Response Format
+
+### Success Response
+```json
+{
+  "success": true,
+  "code": 200,
+  "message": "Product retrieved successfully",
+  "data": {
+    "id": "550e8400-e29b-41d4-a716-446655440000",
+    "name": "iPhone 14 Pro",
+    "price": 15000000,
+    "image": "product_1234567890.jpg",
+    "image_url": "https://api.test/uploads/products/product_1234567890.jpg",
+    "category": {
+      "id": "...",
+      "name": "Smartphones"
+    }
+  }
+}
+```
+
+### Paginated Response
+```json
+{
+  "success": true,
+  "code": 200,
+  "message": "Products retrieved successfully",
+  "data": [...],
+  "pagination": {
+    "current_page": 1,
+    "from": 1,
+    "to": 10,
+    "total": 50,
+    "per_page": 10,
+    "last_page": 5,
+    "next_page": 2,
+    "prev_page": null,
+    "path": "https://api.test/api/v1/products"
+  }
+}
+```
+
+### Error Response
+```json
+{
+  "success": false,
+  "code": 422,
+  "message": "Validation failed",
+  "errors": {
+    "name": ["The name field is required."]
+  }
+}
+```
+
+---
+
+## 🔧 Available Commands
+
+```bash
+# Standard generation (Fields-First)
+php artisan gc Product --fields=name,price:decimal,image:file
+
+# From migration (Migration-First) ⭐ RECOMMENDED
+php artisan gc:from-migration products
+
+# With relationships
+php artisan gc Product --belongsTo=Category,Brand --hasMany=Review
+
+# Interactive wizard
+php artisan gc:wizard Product
+
+# Preview only (no file creation)
+php artisan gc Product --fields=name,price --preview
+
+# Migration text only
+php artisan gc Product --fields=name,price --migration
+
+# Show help
+php artisan gc:help
+```
+
+---
+
+## 📋 Field Types Reference
+
+| Type | Example | Database | Notes |
+|------|---------|----------|-------|
+| `string` | `name:string` | VARCHAR(255) | Default type |
+| `text` | `description:text` | TEXT | Long text |
+| `decimal` | `price:decimal` | DECIMAL(10,2) | For money |
+| `integer` | `stock:integer` | INTEGER | Whole numbers |
+| `boolean` | `is_active:boolean` | BOOLEAN | true/false |
+| `datetime` | `published_at:datetime` | DATETIME | With time |
+| `date` | `birth_date:date` | DATE | Date only |
+| `file` | `image:file` | VARCHAR(255) | ⭐ Auto FileService |
+
+---
+
+## 🎨 File Upload Features
+
+**Automatic when `image:file` or similar detected:**
+
+```php
+// Auto-generated in Controller
+$file = $this->fileService->saveFileComplete(
+    file: $request->file('image'),
+    folder: 'products',              // organized folders
+    fileName: 'product_' . time(),   // custom naming
+    is_compressed: true,             // auto-compression for images
+);
+```
+
+**Features:**
+- ✅ Auto-compression for images (jpg, png)
+- ✅ Organized folder structure
+- ✅ Safe file deletion on update/delete
+- ✅ URL accessor (image_url) auto-generated
+- ✅ Validation rules auto-added
+
+**File storage:**
+```
+storage/app/public/
+└── products/
+    ├── product_1234567890.jpg
+    ├── product_1234567891.jpg
+    └── ...
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Install Dependencies
+```bash
+composer install
+cp .env.example .env
+php artisan key:generate
+```
+
+### 2. Configure Database
+```env
+DB_CONNECTION=mysql
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_DATABASE=your_database
+DB_USERNAME=your_username
+DB_PASSWORD=your_password
+```
+
+### 3. Run Migrations
+```bash
+php artisan migrate
+```
+
+### 4. Create Storage Link
+```bash
+php artisan storage:link
+```
+
+### 5. Generate Your First CRUD
+```bash
+# Option A: Fields-First
+php artisan gc Product --fields=name,price:decimal,image:file
+php artisan migrate
+
+# Option B: Migration-First (Recommended)
+# 1. Create migration file
+# 2. Run:
+php artisan gc:from-migration products
+php artisan migrate
+```
+
+### 6. Test API
+```bash
+# Start server
+php artisan serve
+
+# Test endpoint
+curl http://localhost:8000/api/v1/products
+```
+
+---
+
+## 🔐 Authentication
+
+All API routes protected with Laravel Sanctum.
+
+### Login
+```bash
+POST /api/v1/login
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "password"
+}
+```
+
+### Use Token
+```bash
+GET /api/v1/products
+Authorization: Bearer {your-token-here}
+```
+
+---
+
+## 📊 Tech Stack
+
+| Component | Package | Version | Purpose |
+|-----------|---------|---------|---------|
+| Framework | Laravel | ^10.10 | Core framework |
+| PHP | - | ^8.1 | Language |
+| Auth | Laravel Sanctum | ^3.3 | API authentication |
+| Permissions | Spatie Permission | ^6.13 | RBAC |
+| Query Builder | Spatie Query Builder | ^6.3 | Advanced filtering |
+| Activity Log | Spatie Activity Log | ^4.9 | Audit trail |
+| API Docs | Scramble + Pro | ^0.12.35 / ^0.7.18 | OpenAPI docs |
+| Testing | PHPUnit | ^10.1 | Unit testing |
+
+---
+
+## 📚 Documentation
+
+- **[STRUCTURE.md](STRUCTURE.md)** - Complete project structure
+- **[AI-GUIDE-COMPLETE.md](docs/AI-GUIDE-COMPLETE.md)** - Comprehensive AI integration guide
+- **[DESCRIPTION.md](DESCRIPTION.md)** - Project description (if exists)
+
+### API Documentation
+Access auto-generated Scramble documentation:
+```
+http://your-app.test/docs/api
+```
+
+---
+
+## 🎯 Key Features
+
+### 🏗️ Query Builder Pattern
+- Dedicated Query classes for business logic
+- Clean separation from controllers
+- Reusable across endpoints
+- Easy to test and maintain
+
+### 🔍 Advanced Filtering (Spatie QueryBuilder)
+- Filter by any column
+- Global search across multiple columns
+- Sort by multiple fields
+- Include nested relations
+- Field selection for optimization
+
+### 📝 Queryable Trait
+- Consistent behavior across all models
+- Auto-generates allowed filters
+- Global search functionality
+- Relationship includes
+- Zero repetitive code
+
+### 🎨 Standardized Responses (ApiResponse Helper)
+- Consistent JSON structure
+- Auto-detect pagination
+- Clean error handling
+- Success/Error/Created/Deleted methods
+
+### 📸 FileService
+- Centralized file handling
+- Auto-compression for images
+- Safe deletion
+- Organized storage structure
+- URL accessors
+
+### 📖 Scramble Pro Integration
+- Auto-generated OpenAPI documentation
+- Always up-to-date
+- Interactive API testing
+- PHPDoc-based annotations
+
+### 📋 Activity Logging
+- Automatic audit trail
+- Model observers
+- Track all changes
+- User attribution
+
+---
+
+## 🎓 Best Practices Implemented
+
+1. **Separation of Concerns**
+   - Controllers handle routing
+   - Query classes handle business logic
+   - Models handle data access
+   - Services handle specific operations
+
+2. **DRY Principle**
+   - Queryable trait for shared functionality
+   - ApiResponse helper for consistent responses
+   - FileService for file operations
+
+3. **Type Safety**
+   - Strong typing throughout
+   - FormRequest validation
+   - PHPDoc annotations
+
+4. **Scalability**
+   - API versioning (V1, V2, ...)
+   - Query classes for complex logic
+   - Service layer pattern
+
+5. **Maintainability**
+   - Clear folder structure
+   - Consistent naming
+   - Comprehensive documentation
+
+---
+
+## 🤖 AI Integration
+
+This project is designed to work seamlessly with AI assistants.
+
+### AI can help with:
+1. **Generate migrations** - AI creates schema, you run gc:from-migration
+2. **Complex queries** - AI understands Query class pattern
+3. **Business logic** - AI knows where logic belongs (Query vs Controller)
+4. **Validation rules** - AI writes comprehensive FormRequest rules
+5. **Documentation** - AI generates PHPDoc for Scramble
+
+### Example AI Workflow:
+```
+You: "Bikin API untuk e-commerce product dengan kategori dan brand"
+
+AI: [generates complete migration with all relationships]
+
+You: [saves migration]
+     php artisan gc:from-migration products
+
+Result: Complete CRUD API with relationships ready!
+```
+
+**Read full guide:** [docs/AI-GUIDE-COMPLETE.md](docs/AI-GUIDE-COMPLETE.md)
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run all tests
+php artisan test
+
+# Run specific test
+php artisan test --filter=ProductTest
+
+# With coverage
+php artisan test --coverage
+```
+
+---
+
+## 📈 Performance
+
+**Generated APIs are optimized with:**
+- ✅ Eager loading (via `?include=`)
+- ✅ Pagination by default
+- ✅ Field selection (reduces payload)
+- ✅ Query caching (configurable)
+- ✅ Compressed images
+- ✅ Indexed foreign keys
+
+---
+
+## 🚨 Important Notes
+
+### DO NOT MODIFY
+These files are part of the core framework:
+- `app/Helpers/ApiResponse.php`
+- `app/Traits/Queryable.php`
+- `app/Services/FileService.php`
+- `app/Http/Controllers/Controller.php`
+
+### Safe to Customize
+- Generated Controllers
+- Generated Models
+- Generated Requests
+- Generated Query classes
+- Routes
+
+---
+
+## 🔄 Migration from Old Version
+
+If migrating from version without Query classes:
+
+1. **Backup your code**
+2. **Update controllers** to use Query classes
+3. **Add Queryable trait** to models
+4. **Update routes** to use api_v1.php
+5. **Test thoroughly**
+
+---
+
+## 🎉 Benefits
+
+### Before (Traditional)
+- ⏱️ 30+ minutes per CRUD module
+- 🐛 Manual coding prone to errors
+- 📝 Inconsistent patterns
+- 🔍 Manual filtering logic
+- 📖 Documentation gets outdated
+
+### After (This Framework)
+- ⚡ 30 seconds per CRUD module
+- ✅ Zero errors (tested patterns)
+- 🎯 100% consistent
+- 🔍 Built-in advanced filtering
+- 📖 Auto-generated docs
+- 🤖 AI-powered workflow
+
+---
+
+## 📝 Example: Complete Product API
+
+```bash
+# 1. Create migration (or let AI generate it)
+# 2. Run generator
+php artisan gc:from-migration products
+php artisan migrate
+```
+
+**Result:** You now have:
+- ✅ Full CRUD API
+- ✅ File upload with compression
+- ✅ Advanced filtering
+- ✅ Global search
+- ✅ Relationship loading
+- ✅ Validation
+- ✅ Auto documentation
+- ✅ Activity logging
+
+**Test it:**
+```bash
+# List with filters
+GET /api/v1/products?search=phone&sort=-price&paginate=20
+
+# Create
+POST /api/v1/products
+{
+  "name": "iPhone 14",
+  "price": 15000000,
+  "image": (file upload)
+}
+
+# Update
+PUT /api/v1/products/{id}
+{
+  "price": 14000000
+}
+
+# Delete
+DELETE /api/v1/products/{id}
+```
+
+---
+
+## 🤝 Contributing
+
+This is a base template for Laravel APIs. Feel free to customize for your projects.
+
+---
+
+## 📄 License
+
+MIT License. See LICENSE for details.
+
+---
+
+## 🙏 Credits
+
+Built with:
+- [Laravel](https://laravel.com)
+- [Spatie Packages](https://spatie.be/open-source)
+- [Scramble](https://scramble.dedoc.co)
+
+---
+
+## 📞 Support
+
+For issues or questions, please check:
+1. [STRUCTURE.md](STRUCTURE.md) - Project structure
+2. [docs/AI-GUIDE-COMPLETE.md](docs/AI-GUIDE-COMPLETE.md) - Complete guide
+3. Generated code comments
+
+---
+
+**🚀 Happy Coding! Build APIs in seconds, not hours!**