user affiliation schema completed

backend/app/Etl/Importers/InstitutionImporter.php

@@ -77,8 +77,10 @@ class InstitutionImporter implements Importer
 
         if (! in_array($categoryId, $validCategoryIds, true)) {
             $summary->warn(sprintf(
-                "Institution legacy #%d ('%s'): category %d assente nel lookup v2 → saltata.",
-                $row->id, trim((string) $row->name), $categoryId,
+                "Institution legacy  #%d ('%s') : category %d assente nel lookup v2 → saltata.",
+                $row->id,
+                trim((string) $row->name),
+                $categoryId,
             ));
             $summary->skipped++;
 

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;
+    }
+}

backend/app/Models/Institution.php

@@ -87,4 +87,14 @@ class Institution extends Model implements Auditable
     {
         return $this->hasMany(InstitutionLink::class);
     }
+
+    /**
+     * Storico delle affiliazioni (staff) di questa istituzione.
+     *
+     * @return HasMany<UserAffiliation, $this>
+     */
+    public function affiliations(): HasMany
+    {
+        return $this->hasMany(UserAffiliation::class);
+    }
 }

backend/app/Models/User.php

@@ -7,6 +7,7 @@ use App\Notifications\ResetPasswordNotification;
 use Illuminate\Contracts\Auth\MustVerifyEmail;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\Relations\HasMany;
 use Illuminate\Database\Eloquent\SoftDeletes;
 use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
@@ -16,7 +17,7 @@ use OwenIt\Auditing\Contracts\Auditable;
 
 class User extends Authenticatable implements Auditable, MustVerifyEmail
 {
-    /** @use HasFactory<UserFactory> */
+    /** @use HasFactory<\Database\Factories\UserFactory> */
     use HasApiTokens, HasFactory, Notifiable, SoftDeletes;
 
     use \OwenIt\Auditing\Auditable;
@@ -85,6 +86,16 @@ class User extends Authenticatable implements Auditable, MustVerifyEmail
         return $this->belongsTo(UserRole::class, 'role_id');
     }
 
+    /**
+     * Storico delle affiliazioni (incarichi) di questo utente.
+     *
+     * @return HasMany<UserAffiliation, $this>
+     */
+    public function affiliations(): HasMany
+    {
+        return $this->hasMany(UserAffiliation::class);
+    }
+
     /**
      * Send the password reset notification.
      */

backend/app/Models/UserAffiliation.php

@@ -0,0 +1,97 @@
+<?php
+
+namespace App\Models;
+
+use App\Models\Lists\UserPosition;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use OwenIt\Auditing\Auditable as AuditableTrait;
+use OwenIt\Auditing\Contracts\Auditable;
+
+class UserAffiliation extends Model implements Auditable
+{
+    use AuditableTrait;
+    use HasFactory;
+    use SoftDeletes;
+
+    protected $fillable = [
+        'institution_id',
+        'user_id',
+        'user_position_id',
+        'start_year',
+        'end_year',
+        'legacy_user_id',
+        'legacy_institution_id',
+    ];
+
+    /**
+     * Bookkeeping ETL, non rilevanti per l'admin UI.
+     *
+     * @var list<string>
+     */
+    protected $hidden = [
+        'legacy_user_id',
+        'legacy_institution_id',
+    ];
+
+    /**
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'institution_id' => 'integer',
+            'user_id' => 'integer',
+            'user_position_id' => 'integer',
+            'start_year' => 'integer',
+            'end_year' => 'integer',
+            'is_open' => 'boolean',
+            'legacy_user_id' => 'integer',
+            'legacy_institution_id' => 'integer',
+        ];
+    }
+
+    /**
+     * @return BelongsTo<Institution, $this>
+     */
+    public function institution(): BelongsTo
+    {
+        return $this->belongsTo(Institution::class);
+    }
+
+    /**
+     * @return BelongsTo<User, $this>
+     */
+    public function user(): BelongsTo
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    /**
+     * @return BelongsTo<UserPosition, $this>
+     */
+    public function userPosition(): BelongsTo
+    {
+        return $this->belongsTo(UserPosition::class);
+    }
+
+    /**
+     * Esiste già un'altra affiliazione aperta per lo stesso ente+utente: un
+     * restore qui urterebbe l'indice unique su (institution_id, user_id, is_open).
+     */
+    public function hasConflictingOpenAffiliation(): bool
+    {
+        if (filled($this->end_year)) {
+            return false;
+        }
+
+        return self::query()
+            ->where('institution_id', $this->institution_id)
+            ->where('user_id', $this->user_id)
+            ->where('id', '!=', $this->id)
+            ->whereNotNull('is_open')
+            ->exists();
+    }
+}