license: built full stack, test and documentation

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(),
+        ]);
+    }
+}