user affiliation schema completed

backend/app/Http/Controllers/UserAffiliationController.php

@@ -0,0 +1,138 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Http\Requests\IndexUserAffiliationRequest;
+use App\Http\Requests\StoreUserAffiliationRequest;
+use App\Http\Requests\UpdateUserAffiliationRequest;
+use App\Http\Traits\ApiResponse;
+use App\Models\UserAffiliation;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Http\JsonResponse;
+
+/**
+ * CRUD delle affiliazioni utente-ente (scrittura riservata agli Admin via tier
+ * di rotta). Risorsa standalone: institution_id, user_id e user_position_id
+ * viaggiano nel body, non nella route (l'affiliazione ha due "genitori" forti).
+ *
+ * Soft delete: destroy = cestina, restore = ripristina, forceDestroy = elimina
+ * definitivamente.
+ */
+class UserAffiliationController extends Controller
+{
+    use ApiResponse;
+
+    /**
+     * Elenco paginato, con filtri opzionali (ente, utente, posizione, aperte/chiuse, cestino).
+     */
+    public function index(IndexUserAffiliationRequest $request): JsonResponse
+    {
+        $query = UserAffiliation::query()
+            ->with(['institution', 'user', 'userPosition'])
+            ->orderByDesc('start_year');
+
+        $this->applyTrashed($query, $request->input('trashed'));
+
+        if ($request->filled('institution_id')) {
+            $query->where('institution_id', $request->integer('institution_id'));
+        }
+
+        if ($request->filled('user_id')) {
+            $query->where('user_id', $request->integer('user_id'));
+        }
+
+        if ($request->filled('user_position_id')) {
+            $query->where('user_position_id', $request->integer('user_position_id'));
+        }
+
+        if ($request->filled('open')) {
+            $request->boolean('open')
+                ? $query->whereNotNull('is_open')
+                : $query->whereNull('is_open');
+        }
+
+        $affiliations = $query->paginate($request->integer('per_page') ?: 20);
+
+        return $this->paginatedCollectionResponse($affiliations);
+    }
+
+    /**
+     * Crea un'affiliazione.
+     */
+    public function store(StoreUserAffiliationRequest $request): JsonResponse
+    {
+        $affiliation = UserAffiliation::create($request->validated());
+
+        return $this->createdResponse($affiliation->load(['institution', 'user', 'userPosition']));
+    }
+
+    /**
+     * Dettaglio (con ente, utente e posizione).
+     */
+    public function show(UserAffiliation $userAffiliation): JsonResponse
+    {
+        return $this->okResponse($userAffiliation->load(['institution', 'user', 'userPosition']));
+    }
+
+    /**
+     * Aggiorna un'affiliazione.
+     */
+    public function update(UpdateUserAffiliationRequest $request, UserAffiliation $userAffiliation): JsonResponse
+    {
+        $userAffiliation->update($request->validated());
+
+        return $this->updatedResponse($userAffiliation->load(['institution', 'user', 'userPosition']));
+    }
+
+    /**
+     * Cestina (soft delete).
+     */
+    public function destroy(UserAffiliation $userAffiliation): JsonResponse
+    {
+        $userAffiliation->delete();
+
+        return $this->deletedResponse();
+    }
+
+    /**
+     * Ripristina un'affiliazione cestinata. Bloccato (409) se nel frattempo è
+     * stata aperta un'altra affiliazione per lo stesso ente+utente: va prima
+     * chiusa/eliminata quella attuale, oppure si elimina definitivamente questa.
+     */
+    public function restore(UserAffiliation $userAffiliation): JsonResponse
+    {
+        if ($userAffiliation->hasConflictingOpenAffiliation()) {
+            return $this->conflictResponse(
+                'Cannot restore: another open affiliation already exists for this user at this institution.'
+            );
+        }
+
+        $userAffiliation->restore();
+
+        return $this->restoredResponse($userAffiliation->load(['institution', 'user', 'userPosition']));
+    }
+
+    /**
+     * Elimina definitivamente un'affiliazione.
+     */
+    public function forceDestroy(UserAffiliation $userAffiliation): JsonResponse
+    {
+        $userAffiliation->forceDelete();
+
+        return $this->deletedResponse();
+    }
+
+    /**
+     * Include i soft-deleted: `with` (tutti) o `only` (solo cestinati).
+     *
+     * @param  Builder<UserAffiliation>  $query
+     */
+    private function applyTrashed(Builder $query, ?string $trashed): void
+    {
+        match ($trashed) {
+            'with' => $query->withTrashed(),
+            'only' => $query->onlyTrashed(),
+            default => null,
+        };
+    }
+}

backend/app/Http/Requests/IndexUserAffiliationRequest.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Contracts\Validation\ValidationRule;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class IndexUserAffiliationRequest extends FormRequest
+{
+    /**
+     * L'autorizzazione è gestita dal middleware di rotta (tier.app).
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'institution_id' => ['nullable', 'integer', 'exists:institutions,id'],
+            'user_id' => ['nullable', 'integer', 'exists:users,id'],
+            'user_position_id' => ['nullable', 'integer', 'exists:user_positions,id'],
+            'open' => ['nullable', 'boolean'],
+            'trashed' => ['nullable', Rule::in(['with', 'only'])],
+            'per_page' => ['nullable', 'integer', 'min:1', 'max:100'],
+        ];
+    }
+}

backend/app/Http/Requests/StoreUserAffiliationRequest.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Contracts\Validation\ValidationRule;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class StoreUserAffiliationRequest extends FormRequest
+{
+    /**
+     * L'autorizzazione (solo Admin) è gestita dal middleware di rotta.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        $rules = [
+            'institution_id' => ['required', 'integer', 'exists:institutions,id'],
+            'user_id' => ['required', 'integer', 'exists:users,id'],
+            'user_position_id' => ['required', 'integer', 'exists:user_positions,id'],
+            'start_year' => ['required', 'integer', 'min:1800', 'max:'.now()->year],
+            'end_year' => ['nullable', 'integer', 'min:1800', 'gte:start_year'],
+        ];
+
+        // Un utente non può avere più di un incarico aperto (end_year nullo) nello
+        // stesso ente: il guard definitivo è l'indice unique sulla colonna virtuale
+        // is_open, qui serve solo a restituire un 422 leggibile invece di un 500 SQL.
+        if (! $this->filled('end_year')) {
+            $rules['institution_id'][] = Rule::unique('user_affiliations', 'institution_id')
+                ->where('user_id', $this->input('user_id'))
+                ->whereNull('end_year')
+                ->whereNull('deleted_at');
+        }
+
+        return $rules;
+    }
+}

backend/app/Http/Requests/UpdateUserAffiliationRequest.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace App\Http\Requests;
+
+use Illuminate\Contracts\Validation\ValidationRule;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class UpdateUserAffiliationRequest extends FormRequest
+{
+    /**
+     * L'autorizzazione (solo Admin) è gestita dal middleware di rotta.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * @return array<string, ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        $id = $this->route('user_affiliation')->id;
+
+        $rules = [
+            'institution_id' => ['required', 'integer', 'exists:institutions,id'],
+            'user_id' => ['required', 'integer', 'exists:users,id'],
+            'user_position_id' => ['required', 'integer', 'exists:user_positions,id'],
+            'start_year' => ['required', 'integer', 'min:1800', 'max:'.now()->year],
+            'end_year' => ['nullable', 'integer', 'min:1800', 'gte:start_year'],
+        ];
+
+        // Stesso vincolo di StoreUserAffiliationRequest: niente doppio incarico
+        // aperto sullo stesso ente, escludendo il record che si sta modificando.
+        if (! $this->filled('end_year')) {
+            $rules['institution_id'][] = Rule::unique('user_affiliations', 'institution_id')
+                ->where('user_id', $this->input('user_id'))
+                ->whereNull('end_year')
+                ->whereNull('deleted_at')
+                ->ignore($id);
+        }
+
+        return $rules;
+    }
+}