symfonia-ai-tools 1.0.0

package/templates/packs/laravel/_ai/instructions/module.instructions.md

@@ -0,0 +1,133 @@
+---
+applyTo: "**/Modules/**"
+---
+
+# Modular Architecture - Instrukcje
+
+## Struktura modulu
+
+Kazdy modul biznesowy ma oddzielny katalog w `Modules/`:
+
+```
+Modules/Feature/
+├── Config/
+│   └── config.php                  # Konfiguracja modulu
+├── Console/                        # Artisan commands
+├── Database/
+│   ├── Filters/                    # Custom query filters (Spatie)
+│   ├── Migrations/                 # Migracje modulu
+│   ├── Repositories/               # Data access (CQRS)
+│   │   ├── EloquentFeatureCommandRepository.php
+│   │   └── EloquentFeatureQueryRepository.php
+│   ├── Factories/                  # Model factories (testy)
+│   └── Scopes/                     # Global scopes
+├── Domain/                         # Logika domenowa (DDD)
+│   ├── DTO/                        # Data Transfer Objects
+│   ├── Services/                   # Domain services
+│   ├── Events/                     # Domain events
+│   └── ValueObjects/               # Value Objects
+├── Entities/                       # Eloquent models
+├── Emails/                         # Mailable classes
+├── Http/
+│   ├── Controllers/                # Endpointy API
+│   ├── Policies/                   # Autoryzacja
+│   ├── Requests/                   # Form Requests (walidacja)
+│   └── Resources/                  # API Resources (transformery)
+├── Jobs/                           # Queued jobs
+├── Listeners/                      # Event listeners
+├── Providers/
+│   ├── FeatureServiceProvider.php  # Rejestracja modulu
+│   └── RouteServiceProvider.php    # Routing modulu
+├── Routes/
+│   └── api.php                     # Endpointy API modulu
+├── Tests/
+│   ├── Feature/                    # Integration tests
+│   ├── Unit/                       # Unit tests
+│   └── Fixtures/                   # Test fixtures
+├── module.json                     # Metadane modulu
+└── composer.json                   # Zaleznosci modulu
+```
+
+## module.json
+
+```json
+{
+  "name": "Feature",
+  "alias": "feature",
+  "description": "Opis modulu",
+  "active": 1,
+  "order": 0,
+  "providers": [
+    "Modules\\Feature\\Providers\\FeatureServiceProvider"
+  ]
+}
+```
+
+## ServiceProvider
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Providers;
+
+use Illuminate\Support\ServiceProvider;
+use Illuminate\Support\Facades\Gate;
+
+class FeatureServiceProvider extends ServiceProvider
+{
+    public function boot(): void
+    {
+        $this->loadMigrationsFrom(__DIR__ . '/../Database/Migrations');
+        $this->registerTranslations();
+        $this->registerConfig();
+
+        // Policies
+        Gate::define('feature-admin', FeaturePolicy::class . '@admin');
+
+        // Commands
+        $this->commands([
+            SyncFeatureDataCommand::class,
+        ]);
+    }
+
+    public function register(): void
+    {
+        $this->app->register(RouteServiceProvider::class);
+
+        // Bindings (interface → implementation)
+        $this->app->bind(
+            FeatureCommandRepository::class,
+            EloquentFeatureCommandRepository::class,
+        );
+        $this->app->bind(
+            FeatureQueryRepository::class,
+            EloquentFeatureQueryRepository::class,
+        );
+    }
+}
+```
+
+## Routing modulu
+
+```php
+// Routes/api.php
+use Illuminate\Support\Facades\Route;
+
+Route::middleware(['auth:api'])->prefix('feature')->group(function () {
+    Route::get('/', [FeatureController::class, 'index']);
+    Route::get('/{featureId}', [FeatureController::class, 'show']);
+    Route::post('/', [FeatureController::class, 'store']);
+    Route::put('/{featureId}', [FeatureController::class, 'update']);
+    Route::delete('/{featureId}', [FeatureController::class, 'destroy']);
+});
+```
+
+## Zasady
+
+1. **Jeden modul = jedna domena biznesowa** - nie mieszaj odpowiedzialnosci
+2. **Modul jest samodzielny** - ma swoje migracje, routing, testy, providery
+3. **Komunikacja miedzy modulami** - przez Events/Listeners lub interfejsy, nie bezposrednie zaleznosci
+4. **CQRS** - oddzielne repozytoria Command (zapis) i Query (odczyt)
+5. **Nowy modul**: `php artisan module:make NazwaModulu`, potem dostosuj strukture
+6. **Bindingi** - interfejs → implementacja w ServiceProvider `register()`
+7. **Testy w module** - `Tests/Feature/` i `Tests/Unit/` w katalogu modulu

package/templates/packs/laravel/_ai/instructions/service-repository.instructions.md

@@ -0,0 +1,215 @@
+---
+applyTo: "**/*Service*.php,**/*Repository*.php,**/DTO/**,**/ValueObjects/**"
+---
+
+# Service, Repository, DTO, Value Objects - Instrukcje
+
+## Service Layer
+
+Serwisy koordynuja logike biznesowa. Kontroler deleguje do serwisu, serwis uzywa repozytoriow.
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Domain\Services;
+
+readonly class FeatureService
+{
+    public function __construct(
+        private FeatureCommandRepository $commandRepository,
+        private FeatureQueryRepository $queryRepository,
+    ) {}
+
+    public function create(FeatureDTO $dto): Feature
+    {
+        $feature = Feature::create($dto);
+        $this->commandRepository->save($feature);
+
+        event(new FeatureCreated($feature));
+
+        return $feature;
+    }
+
+    public function getForUser(int $userId, int $limit): LengthAwarePaginator
+    {
+        return $this->queryRepository->getByUser($userId, $limit);
+    }
+}
+```
+
+### Zasady Service
+
+- `readonly class` - serwis nie ma mutowalnego stanu
+- Constructor injection dla zaleznosci
+- Jedna publiczna metoda = jedna operacja biznesowa
+- Serwis **nie** zwraca Response - to robi kontroler
+- Serwis moze emitowac Events
+
+## Repository Pattern (CQRS)
+
+Oddziel operacje zapisu (Command) od odczytu (Query):
+
+### Command Repository (zapis)
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Database\Repositories;
+
+interface FeatureCommandRepository
+{
+    public function save(Feature $feature): void;
+    public function delete(UuidInterface $id): void;
+}
+
+class EloquentFeatureCommandRepository implements FeatureCommandRepository
+{
+    public function save(Feature $feature): void
+    {
+        $model = FeatureModel::query()
+            ->where(FeatureModel::COLUMN_ID, $feature->getId()->toString())
+            ->first();
+
+        if (!$model) {
+            $model = new FeatureModel();
+        }
+
+        $model->fill($feature->toArray())->save();
+    }
+
+    public function delete(UuidInterface $id): void
+    {
+        FeatureModel::query()
+            ->where(FeatureModel::COLUMN_ID, $id->toString())
+            ->delete();
+    }
+}
+```
+
+### Query Repository (odczyt)
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Database\Repositories;
+
+interface FeatureQueryRepository
+{
+    /** @return LengthAwarePaginator<FeatureModel> */
+    public function getByUser(int $userId, int $limit): LengthAwarePaginator;
+
+    public function findById(UuidInterface $id): ?FeatureModel;
+}
+
+class EloquentFeatureQueryRepository implements FeatureQueryRepository
+{
+    /** @return LengthAwarePaginator<FeatureModel> */
+    public function getByUser(int $userId, int $limit): LengthAwarePaginator
+    {
+        return FeatureModel::query()
+            ->where(FeatureModel::COLUMN_USER_ID, $userId)
+            ->with(FeatureModel::RELATION_TYPE)
+            ->orderByDesc(FeatureModel::COLUMN_CREATED_AT)
+            ->paginate($limit);
+    }
+}
+```
+
+## DTO (Data Transfer Object)
+
+Przenosi dane miedzy warstwami bez logiki biznesowej:
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Domain\DTO;
+
+readonly class FeatureDTO
+{
+    public function __construct(
+        public string $name,
+        public string $description,
+        public int $userId,
+        public ?int $categoryId = null,
+    ) {}
+
+    public static function fromRequest(StoreFeatureRequest $request): self
+    {
+        return new self(
+            name: $request->validated('name'),
+            description: $request->validated('description'),
+            userId: $request->user()->getId(),
+            categoryId: $request->validated('category_id'),
+        );
+    }
+}
+```
+
+## Value Objects
+
+Reprezentuja wartosc domenowa - niemutowalne, porownywane przez wartosc:
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Domain\ValueObjects;
+
+readonly class DateRange
+{
+    public function __construct(
+        public Carbon $start,
+        public Carbon $end,
+    ) {
+        if ($start->isAfter($end)) {
+            throw new \InvalidArgumentException('Start date must be before end date');
+        }
+    }
+
+    public function overlaps(self $other): bool
+    {
+        return $this->start->isBefore($other->end)
+            && $this->end->isAfter($other->start);
+    }
+
+    public function days(): int
+    {
+        return $this->start->diffInDays($this->end);
+    }
+}
+```
+
+## Kontroler - integracja
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Http\Controllers;
+
+class FeatureController extends Controller
+{
+    public function __construct(
+        private readonly FeatureService $service,
+    ) {}
+
+    public function store(StoreFeatureRequest $request): JsonResponse
+    {
+        $dto = FeatureDTO::fromRequest($request);
+        $feature = $this->service->create($dto);
+
+        return FeatureResource::make($feature)
+            ->response()
+            ->setStatusCode(Response::HTTP_CREATED);
+    }
+}
+```
+
+## Zasady
+
+1. **Service** - `readonly class`, business logic, emituje events
+2. **Command Repository** - tylko zapis (save, delete, update)
+3. **Query Repository** - tylko odczyt, eager loading, paginacja
+4. **DTO** - `readonly class`, statyczny `fromRequest()`, brak logiki
+5. **Value Object** - `readonly class`, walidacja w konstruktorze, metody porownania
+6. **Interfejsy** - repozytorium ma interfejs, implementacja w `Eloquent*Repository`
+7. **Binding** - interfejs → implementacja rejestrowany w ServiceProvider
+8. **Kontroler nie zawiera logiki** - deleguje do serwisu, zwraca Resource

package/templates/packs/laravel/_ai/instructions/testing.instructions.md

@@ -0,0 +1,278 @@
+---
+applyTo: "**/*Test*.php,**/tests/**,**/*Factory*.php"
+---
+
+# PHP Testing (PHPUnit) - Instrukcje
+
+## Uruchamianie testow
+
+```bash
+# Wszystkie testy
+docker exec {{DOCKER_CONTAINER}} php artisan test
+
+# Konkretny plik
+docker exec {{DOCKER_CONTAINER}} php artisan test --filter=FeatureServiceTest
+
+# Konkretna metoda
+docker exec {{DOCKER_CONTAINER}} php artisan test --filter=test_user_can_create_feature
+
+# Z coverage
+docker exec {{DOCKER_CONTAINER}} php artisan test --coverage
+```
+
+## Feature Tests (integracyjne)
+
+Testuja caly flow: request → kontroler → serwis → baza → response.
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Tests\Feature;
+
+use Tests\TestCase;
+use Illuminate\Foundation\Testing\DatabaseTransactions;
+
+class FeatureControllerTest extends TestCase
+{
+    use DatabaseTransactions;
+
+    private User $user;
+    private Feature $feature;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->user = User::factory()->create();
+        $this->feature = Feature::factory()->create(['user_id' => $this->user->getId()]);
+    }
+
+    public function test_user_can_list_features(): void
+    {
+        // Arrange
+        Feature::factory()->count(5)->create(['user_id' => $this->user->getId()]);
+
+        // Act
+        $response = $this->actingAs($this->user)
+            ->getJson('/api/features?page=1&limit=10');
+
+        // Assert
+        $response->assertOk()
+            ->assertJsonStructure([
+                'data' => [['id', 'name', 'status', 'createdAt']],
+                'meta' => ['total', 'perPage', 'currentPage'],
+            ])
+            ->assertJsonCount(6, 'data');
+    }
+
+    public function test_user_can_create_feature(): void
+    {
+        // Arrange
+        $payload = [
+            'name' => 'New Feature',
+            'description' => 'Description',
+            'status' => 'draft',
+        ];
+
+        // Act
+        $response = $this->actingAs($this->user)
+            ->postJson('/api/features', $payload);
+
+        // Assert
+        $response->assertCreated()
+            ->assertJsonFragment(['name' => 'New Feature']);
+
+        $this->assertDatabaseHas('features', [
+            'name' => 'New Feature',
+            'user_id' => $this->user->getId(),
+        ]);
+    }
+
+    public function test_unauthorized_user_cannot_delete(): void
+    {
+        $otherUser = User::factory()->create();
+
+        $response = $this->actingAs($otherUser)
+            ->deleteJson("/api/features/{$this->feature->getId()}");
+
+        $response->assertForbidden();
+    }
+}
+```
+
+## Unit Tests
+
+Testuja izolowana logike bez bazy i HTTP:
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Tests\Unit;
+
+use PHPUnit\Framework\TestCase;
+
+class FeatureDurationCalculatorTest extends TestCase
+{
+    private FeatureDurationCalculator $calculator;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+        $this->calculator = new FeatureDurationCalculator();
+    }
+
+    public function test_calculates_business_days(): void
+    {
+        $start = Carbon::parse('2025-01-06'); // Poniedzialek
+        $end = Carbon::parse('2025-01-10');   // Piatek
+
+        $result = $this->calculator->businessDays($start, $end);
+
+        $this->assertEquals(5, $result);
+    }
+
+    /**
+     * @dataProvider durationDataProvider
+     */
+    public function test_duration_calculation(
+        string $start,
+        string $end,
+        int $expectedDays,
+    ): void {
+        $result = $this->calculator->businessDays(
+            Carbon::parse($start),
+            Carbon::parse($end),
+        );
+
+        $this->assertEquals($expectedDays, $result);
+    }
+
+    public static function durationDataProvider(): array
+    {
+        return [
+            'full week' => ['2025-01-06', '2025-01-10', 5],
+            'with weekend' => ['2025-01-06', '2025-01-13', 6],
+            'same day' => ['2025-01-06', '2025-01-06', 1],
+            'weekend only' => ['2025-01-11', '2025-01-12', 0],
+        ];
+    }
+}
+```
+
+## Model Factories
+
+```php
+declare(strict_types=1);
+
+namespace Modules\Feature\Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+class FeatureFactory extends Factory
+{
+    protected $model = FeatureModel::class;
+
+    public function definition(): array
+    {
+        return [
+            'name' => fake()->sentence(3),
+            'description' => fake()->paragraph(),
+            'status' => fake()->randomElement(FeatureStatus::cases()),
+            'user_id' => User::factory(),
+            'created_at' => fake()->dateTimeBetween('-1 year'),
+        ];
+    }
+
+    public function draft(): static
+    {
+        return $this->state(['status' => FeatureStatus::DRAFT]);
+    }
+
+    public function published(): static
+    {
+        return $this->state(['status' => FeatureStatus::PUBLISHED]);
+    }
+
+    public function withCategory(int $categoryId): static
+    {
+        return $this->state(['category_id' => $categoryId]);
+    }
+}
+```
+
+## Laravel Fakes
+
+```php
+public function test_sends_notification_on_create(): void
+{
+    Notification::fake();
+
+    $this->actingAs($this->user)
+        ->postJson('/api/features', $this->validPayload());
+
+    Notification::assertSentTo($this->user, FeatureCreatedNotification::class);
+}
+
+public function test_dispatches_export_job(): void
+{
+    Queue::fake();
+
+    $this->actingAs($this->user)
+        ->postJson('/api/features/export');
+
+    Queue::assertPushed(ExportFeatureJob::class, function ($job) {
+        return $job->userId === $this->user->getId();
+    });
+}
+
+public function test_fires_event_on_update(): void
+{
+    Event::fake([FeatureUpdated::class]);
+
+    $this->actingAs($this->user)
+        ->putJson("/api/features/{$this->feature->getId()}", $this->validPayload());
+
+    Event::assertDispatched(FeatureUpdated::class);
+}
+```
+
+## Test Helpers / Fixtures
+
+```php
+// Tests/Fixtures/FeatureFixtures.php
+trait FeatureFixtures
+{
+    protected function createFeatureWithRelations(array $overrides = []): FeatureModel
+    {
+        $category = Category::factory()->create();
+        $user = User::factory()->create();
+
+        return Feature::factory()
+            ->withCategory($category->getId())
+            ->create(array_merge([
+                'user_id' => $user->getId(),
+            ], $overrides));
+    }
+
+    protected function validPayload(array $overrides = []): array
+    {
+        return array_merge([
+            'name' => 'Test Feature',
+            'description' => 'Test description',
+            'status' => 'draft',
+        ], $overrides);
+    }
+}
+```
+
+## Zasady
+
+1. **`test_` prefix + snake_case** - `test_user_can_create_feature()`
+2. **AAA pattern** - Arrange, Act, Assert (komentarze opcjonalne)
+3. **`DatabaseTransactions`** - trait dla Feature tests, auto-rollback
+4. **`setUp()`** - tworzenie wspolnych danych, nie w kazdym tescie
+5. **Data Providers** - dla wielu scenariuszy z roznymi danymi
+6. **Factory states** - `->draft()`, `->published()` zamiast surowych state
+7. **Laravel fakes** - `Notification::fake()`, `Queue::fake()`, `Event::fake()`, `Mail::fake()`
+8. **assertDatabaseHas/Missing** - sprawdzaj stan bazy po operacjach
+9. **actingAs()** - autentykuj uzytkownika w Feature tests
+10. **Testy w module** - `Modules/Feature/Tests/`, nie w globalnym `tests/`