Add module generator UI and discovery service documentation

2026-03-15 08:59:53 +02:00
parent dff2cd752c
commit a6b1cfe498
8 changed files with 1482 additions and 1 deletions
--- a/docs/module-generator.md
+++ b/docs/module-generator.md
@@ -0,0 +1,173 @@
+# Module Generator (Admin UI)
+
+A visual tool for creating module skeletons through the Filament admin panel.
+
+> **Development Only**: This tool is only available when `APP_ENV=local`.
+
+## Access
+
+Navigate to: **Admin Panel → Development → Module Generator**
+
+URL: `/admin/module-generator`
+
+## Features
+
+- **Visual Form**: Create modules without command line
+- **Auto Git Branch**: Optionally creates `module/{name}` branch and commits files
+- **Skeleton Only**: Maximum flexibility - creates structure, you add the models
+- **Instant Feedback**: Shows generation logs and next steps
+
+## What Gets Created
+
+```
+app/Modules/{ModuleName}/
+├── Config/{module_name}.php           # Module configuration
+├── Database/
+│   ├── Migrations/                     # Empty, add your migrations
+│   └── Seeders/                        # Empty, add your seeders
+├── Filament/Resources/                 # Empty, add Filament resources
+├── Http/
+│   ├── Controllers/{ModuleName}Controller.php
+│   ├── Middleware/                     # Empty
+│   └── Requests/                       # Empty
+├── Models/                             # Empty, add your models
+├── Policies/                           # Empty, add policies
+├── Services/                           # Empty, add services
+├── Routes/
+│   ├── web.php                         # Basic index route
+│   └── api.php                         # If API option selected
+├── Resources/views/
+│   └── index.blade.php                 # Starter view
+├── Permissions.php                     # CRUD permissions
+├── {ModuleName}ServiceProvider.php     # Auto-registered
+└── README.md                           # Module documentation
+```
+
+## Form Options
+
+| Field | Description |
+|-------|-------------|
+| **Module Name** | PascalCase name (e.g., `Accounting`, `Inventory`) |
+| **Description** | Brief description for README and config |
+| **Create Git Branch** | Auto-create `module/{name}` branch and commit |
+| **Include API Routes** | Add `Routes/api.php` with Sanctum auth |
+
+## Git Integration
+
+When "Create Git Branch" is enabled:
+
+1. **Checks** for uncommitted changes (fails if dirty)
+2. **Creates** branch `module/{module-name}`
+3. **Generates** all module files
+4. **Commits** with message `feat: Add {ModuleName} module skeleton`
+5. **Shows** push command: `git push -u origin module/{name}`
+
+### Requirements
+
+- Working directory must be clean (no uncommitted changes)
+- Git must be installed in the container
+- Repository must be initialized
+
+## After Generation
+
+1. **Run migrations** (if you add any):
+   ```bash
+   php artisan migrate
+   ```
+
+2. **Seed permissions**:
+   ```bash
+   php artisan db:seed --class=RolePermissionSeeder
+   ```
+
+3. **Clear caches**:
+   ```bash
+   php artisan optimize:clear
+   ```
+
+4. **Push branch** (if Git was used):
+   ```bash
+   git push -u origin module/{name}
+   ```
+
+## Adding Models
+
+After generating the skeleton, add models manually:
+
+```php
+// app/Modules/Accounting/Models/Invoice.php
+<?php
+
+namespace App\Modules\Accounting\Models;
+
+use App\Traits\ModuleAuditable;
+use Illuminate\Database\Eloquent\Model;
+use OwenIt\Auditing\Contracts\Auditable;
+
+class Invoice extends Model implements Auditable
+{
+    use ModuleAuditable;
+
+    protected $fillable = [
+        'number',
+        'customer_id',
+        'total',
+        'status',
+    ];
+}
+```
+
+## Adding Filament Resources
+
+Create admin CRUD in `Filament/Resources/`:
+
+```php
+// app/Modules/Accounting/Filament/Resources/InvoiceResource.php
+<?php
+
+namespace App\Modules\Accounting\Filament\Resources;
+
+use App\Modules\Accounting\Models\Invoice;
+use Filament\Resources\Resource;
+// ... standard Filament resource implementation
+```
+
+## Comparison: UI vs CLI
+
+| Feature | UI Generator | `make:module` CLI |
+|---------|--------------|-------------------|
+| Skeleton only | ✅ | ❌ (includes model) |
+| Git integration | ✅ Auto-branch | ❌ Manual |
+| Model generation | ❌ | ✅ With `--model=` |
+| Filament resource | ❌ | ✅ With `--model=` |
+| Visual feedback | ✅ | Terminal output |
+| Environment | Local only | Any |
+
+**Use UI Generator when**: You need a blank canvas for complex modules with multiple models.
+
+**Use CLI when**: You want a quick single-model module with all files generated.
+
+## Troubleshooting
+
+### "Git working directory has uncommitted changes"
+
+Commit or stash your changes first:
+```bash
+git add . && git commit -m "WIP"
+# or
+git stash
+```
+
+### Module not showing in admin
+
+Clear caches:
+```bash
+php artisan optimize:clear
+```
+
+### Permissions not working
+
+Re-seed permissions:
+```bash
+php artisan db:seed --class=RolePermissionSeeder
+```