license: built full stack, test and documentation

backend/app/Enums/LicenseKind.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace App\Enums;
+
+/**
+ * Natura della voce nella tabella `licenses`.
+ *
+ * Non tutto ciò che si applica a record e media è una licenza in senso
+ * stretto: il Public Domain Mark è un *marchio* (dichiara uno stato
+ * esistente, non concede diritti) e gli statement di RightsStatements.org
+ * etichettano lo stato dei diritti senza concederne. La distinzione serve a
+ * UI e download: solo le voci `License` hanno un testo legale da includere
+ * nello zip dei media (colonna `file`).
+ */
+enum LicenseKind: string
+{
+    case License = 'license';
+    case Mark = 'mark';
+    case RightsStatement = 'rights_statement';
+
+    /**
+     * Etichetta leggibile per la UI (inglese: lingua ufficiale dell'applicazione).
+     */
+    public function label(): string
+    {
+        return match ($this) {
+            self::License => 'License',
+            self::Mark => 'Public domain mark',
+            self::RightsStatement => 'Rights statement',
+        };
+    }
+}

backend/app/Http/Controllers/LicenseController.php

@@ -0,0 +1,96 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use App\Http\Requests\IndexLicenseRequest;
+use App\Http\Requests\StoreLicenseRequest;
+use App\Http\Requests\UpdateLicenseRequest;
+use App\Http\Traits\ApiResponse;
+use App\Models\Lists\License;
+use Illuminate\Http\JsonResponse;
+
+/**
+ * CRUD del vocabolario licenze (scrittura riservata agli Admin).
+ *
+ * NB gli id 1-3 sono allineati al legacy e verranno usati dall'ETL per
+ * mappare le FK di artifact/media: per ritirare una licenza usare
+ * `active = false`, non la cancellazione. Nessun soft delete su questo lookup.
+ */
+class LicenseController extends Controller
+{
+    use ApiResponse;
+
+    /**
+     * Elenco delle licenze, ordinate per `sort_order` (dalla più aperta alla
+     * più restrittiva). Filtri: `scope=record|media` (select dei form),
+     * `active=1` (esclude le licenze ritirate).
+     */
+    public function index(IndexLicenseRequest $request): JsonResponse
+    {
+        $query = License::query()->orderBy('sort_order')->orderBy('acronym');
+
+        match ($request->input('scope')) {
+            'record' => $query->forRecord(),
+            'media' => $query->forMedia(),
+            default => null,
+        };
+
+        if ($request->filled('active')) {
+            $query->where('active', $request->boolean('active'));
+        }
+
+        return $this->collectionResponse($query->get());
+    }
+
+    /**
+     * Crea una licenza.
+     */
+    public function store(StoreLicenseRequest $request): JsonResponse
+    {
+        $license = License::create($request->validated());
+
+        return $this->createdResponse($license);
+    }
+
+    /**
+     * Dettaglio di una licenza.
+     */
+    public function show(License $license): JsonResponse
+    {
+        return $this->okResponse($license);
+    }
+
+    /**
+     * Aggiorna una licenza (anche parzialmente, es. solo `active`).
+     */
+    public function update(UpdateLicenseRequest $request, License $license): JsonResponse
+    {
+        $license->update($request->validated());
+
+        return $this->updatedResponse($license);
+    }
+
+    /**
+     * Elimina una licenza (se non assegnata ad alcun contenuto).
+     */
+    public function destroy(License $license): JsonResponse
+    {
+        if ($license->isInUse()) {
+            return $this->conflictResponse('Cannot delete: license assigned to at least one record or media file.');
+        }
+
+        $license->delete();
+
+        return $this->deletedResponse();
+    }
+
+    /**
+     * Indica se la licenza è in uso (bloccata per l'eliminazione).
+     */
+    public function usage(License $license): JsonResponse
+    {
+        return response()->json([
+            'in_use' => $license->isInUse(),
+        ]);
+    }
+}

backend/app/Http/Requests/IndexLicenseRequest.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 IndexLicenseRequest extends FormRequest
+{
+    /**
+     * Rotta pubblica: l'elenco delle licenze è informazione pubblica.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * `scope` filtra le select dei form: `record` per artifact/model (solo
+     * licenze aperte), `media` per i file caricati (tutte). `active` esclude
+     * le licenze ritirate dagli admin.
+     *
+     * @return array<string, ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        return [
+            'scope' => ['nullable', Rule::in(['record', 'media'])],
+            'active' => ['nullable', 'boolean'],
+        ];
+    }
+}

backend/app/Http/Requests/StoreLicenseRequest.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Http\Requests;
+
+use App\Enums\LicenseKind;
+use Illuminate\Contracts\Validation\ValidationRule;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class StoreLicenseRequest 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
+    {
+        return [
+            'name' => ['required', 'string', 'max:200', 'unique:licenses,name'],
+            'acronym' => ['required', 'string', 'max:50', 'unique:licenses,acronym'],
+            // Solo id della SPDX License List ufficiale: per marchi e rights
+            // statement (che non vi compaiono) deve restare NULL.
+            'spdx_id' => ['nullable', 'string', 'max:50', 'unique:licenses,spdx_id'],
+            'kind' => ['required', Rule::enum(LicenseKind::class)],
+            'description' => ['nullable', 'string'],
+            'uri' => ['nullable', 'url', 'max:2000'],
+            'file' => ['nullable', 'string', 'max:512'],
+            'for_record' => ['sometimes', 'boolean'],
+            'for_media' => ['sometimes', 'boolean'],
+            'sort_order' => ['sometimes', 'integer', 'min:0'],
+            'active' => ['sometimes', 'boolean'],
+        ];
+    }
+}

backend/app/Http/Requests/UpdateLicenseRequest.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Http\Requests;
+
+use App\Enums\LicenseKind;
+use Illuminate\Contracts\Validation\ValidationRule;
+use Illuminate\Foundation\Http\FormRequest;
+use Illuminate\Validation\Rule;
+
+class UpdateLicenseRequest extends FormRequest
+{
+    /**
+     * L'autorizzazione (solo Admin) è gestita dal middleware di rotta.
+     */
+    public function authorize(): bool
+    {
+        return true;
+    }
+
+    /**
+     * Aggiornamento parziale: ogni campo è validato solo se presente.
+     *
+     * @return array<string, ValidationRule|array<mixed>|string>
+     */
+    public function rules(): array
+    {
+        $id = $this->route('license')->id;
+
+        return [
+            'name' => ['sometimes', 'required', 'string', 'max:200', Rule::unique('licenses', 'name')->ignore($id)],
+            'acronym' => ['sometimes', 'required', 'string', 'max:50', Rule::unique('licenses', 'acronym')->ignore($id)],
+            'spdx_id' => ['nullable', 'string', 'max:50', Rule::unique('licenses', 'spdx_id')->ignore($id)],
+            'kind' => ['sometimes', 'required', Rule::enum(LicenseKind::class)],
+            'description' => ['nullable', 'string'],
+            'uri' => ['nullable', 'url', 'max:2000'],
+            'file' => ['nullable', 'string', 'max:512'],
+            'for_record' => ['sometimes', 'boolean'],
+            'for_media' => ['sometimes', 'boolean'],
+            'sort_order' => ['sometimes', 'integer', 'min:0'],
+            'active' => ['sometimes', 'boolean'],
+        ];
+    }
+}

backend/app/Models/Lists/License.php

@@ -0,0 +1,99 @@
+<?php
+
+namespace App\Models\Lists;
+
+use App\Enums\LicenseKind;
+use Illuminate\Database\Eloquent\Builder;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use OwenIt\Auditing\Auditable as AuditableTrait;
+use OwenIt\Auditing\Contracts\Auditable;
+
+/**
+ * Vocabolario delle licenze per record (artifact/model) e media.
+ *
+ * Tabella controllata, popolata dal LicenseSeeder in installazione (non
+ * dall'ETL). Gli id 1-3 sono FISSI e coincidono con il DB legacy (v1:
+ * 1=Public Domain, 2=CC0, 3=CC BY) così l'ETL mapperà le FK dei contenuti
+ * 1:1 senza tradurre.
+ *
+ * Il ritiro di una licenza si fa con `active = false` (le select dei form la
+ * nascondono), mai cancellando la riga: i contenuti già licenziati la
+ * referenziano.
+ */
+class License extends Model implements Auditable
+{
+    use AuditableTrait;
+    use HasFactory;
+
+    protected $fillable = [
+        'name',
+        'acronym',
+        'spdx_id',
+        'kind',
+        'description',
+        'uri',
+        'file',
+        'for_record',
+        'for_media',
+        'sort_order',
+        'active',
+    ];
+
+    /**
+     * @return array<string, string>
+     */
+    protected function casts(): array
+    {
+        return [
+            'kind' => LicenseKind::class,
+            'for_record' => 'boolean',
+            'for_media' => 'boolean',
+            'sort_order' => 'integer',
+            'active' => 'boolean',
+        ];
+    }
+
+    /**
+     * Licenze ammesse per i record (artifact/model): solo quelle aperte.
+     *
+     * @param  Builder<License>  $query
+     */
+    public function scopeForRecord(Builder $query): void
+    {
+        $query->where('for_record', true);
+    }
+
+    /**
+     * Licenze ammesse per i media (immagini, documenti, video, modelli 3D).
+     *
+     * @param  Builder<License>  $query
+     */
+    public function scopeForMedia(Builder $query): void
+    {
+        $query->where('for_media', true);
+    }
+
+    /**
+     * Solo le licenze attive (proposte nei form di inserimento/modifica).
+     *
+     * @param  Builder<License>  $query
+     */
+    public function scopeActive(Builder $query): void
+    {
+        $query->where('active', true);
+    }
+
+    /**
+     * La licenza è assegnata ad almeno un contenuto.
+     *
+     * NB: oggi nessuna tabella referenzia `licenses`, quindi nessuna riga
+     * risulta in uso; quando arriveranno le tabelle di artifact/model/media
+     * (con FK su `licenses`) questo metodo dovrà controllarne l'esistenza,
+     * come fa InstitutionCategory::isInUse().
+     */
+    public function isInUse(): bool
+    {
+        return false;
+    }
+}