Checkpoint: headless JSON architecture documented + cleanup (Stufe 1+2)

Restore point before Stufe 3 (central resolver-service refactoring).

Includes this session's work:
- Success Story (usecase) rebuild: new fields/tabs, UsecaseSerializer,
  thin List/Show renderers, MM relations, inline content elements.
- vitec_columns content block (two-column layout with per-item content)
  incl. unified header section; special-cased JSON resolution.
- Container per-column flex (items[].config align/justify) + gap on parent.
- Unified header section across CEs/plugins/containers; header fields in JSON.
- ISO-style architecture spec: Documentation/Headless-JSON-Architecture.md.
- Cleanup: removed local scratch + verified .bak backups.
- Fixes: B-6 (undefined thumbnail variable in Downloadcardcollection image
  resolver), B-7 (unsatisfiable legacy CType OR branch in Downloadcard/Datasheets).

Rollback: git reset --hard snapshot-2026-07-09-pre-stufe3

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

packages/vitec/Classes/UserFunc/DatasheetsJsonRenderer.php

@@ -7,6 +7,7 @@ namespace Evomedien\Vitec\UserFunc;
 
 use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
 use Doctrine\DBAL\ParameterType;
+use TYPO3\CMS\Core\Core\Environment;
 use TYPO3\CMS\Core\Database\ConnectionPool;
 use TYPO3\CMS\Core\Resource\ResourceFactory;
 use TYPO3\CMS\Core\Service\FlexFormService;
@@ -49,13 +50,7 @@ class DatasheetsJsonRenderer
             ->from('tt_content')
             ->where(
                 $qb->expr()->eq('pid', $qb->createNamedParameter($pageId, ParameterType::INTEGER)),
-                $qb->expr()->or(
-                    $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_datasheets', ParameterType::STRING)),
-                    $qb->expr()->and(
-                        $qb->expr()->eq('CType', $qb->createNamedParameter('list', ParameterType::STRING)),
-                        $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_datasheets', ParameterType::STRING))
-                    )
-                ),
+                $qb->expr()->eq('CType', $qb->createNamedParameter('vitec_datasheets', ParameterType::STRING)),
                 $qb->expr()->eq('deleted', 0),
                 $qb->expr()->eq('hidden', 0)
             )
@@ -118,6 +113,7 @@ class DatasheetsJsonRenderer
                 $response['debug'] = [
                     'productCount' => count($itemsOut),
                     'settings'     => $settings,
+                    'fallbackFiles' => $this->collectFallbackFilesFromItems($itemsOut),
                 ];
             }
 
@@ -259,6 +255,7 @@ class DatasheetsJsonRenderer
     private function serializeDatasheet(array $download): array
     {
         $uid = (int)$download['uid'];
+        $filetype = $this->getDownloadFileType($uid);
         return [
             'uid'         => $uid,
             'title'       => (string)($download['title'] ?? ''),
@@ -266,10 +263,48 @@ class DatasheetsJsonRenderer
             'teaser'      => (string)($download['teaser'] ?? ''),
             'description' => (string)($download['description'] ?? ''),
             'tstamp'      => (int)($download['tstamp'] ?? 0),
-            'file'        => $this->getDownloadFile($uid),
+            'filetype'    => $filetype,
+            'file'        => $this->getDownloadFile($uid, (string)($download['fileprefix'] ?? ''), $filetype),
         ];
     }
 
+    private function getDownloadFileType(int $downloadUid): string
+    {
+        $qb = GeneralUtility::makeInstance(ConnectionPool::class)
+            ->getQueryBuilderForTable('sys_category');
+
+        $categories = $qb
+            ->select('c.filetype')
+            ->from('sys_category', 'c')
+            ->join(
+                'c',
+                'sys_category_record_mm',
+                'mm',
+                'mm.uid_local = c.uid AND mm.tablenames = ' .
+                $qb->createNamedParameter('tx_vitec_domain_model_download', ParameterType::STRING) .
+                ' AND mm.fieldname = ' .
+                $qb->createNamedParameter('categories', ParameterType::STRING)
+            )
+            ->where(
+                $qb->expr()->eq('mm.uid_foreign', $qb->createNamedParameter($downloadUid, ParameterType::INTEGER)),
+                $qb->expr()->eq('c.deleted', 0),
+                $qb->expr()->eq('c.hidden', 0),
+                $qb->expr()->eq('c.parent', $qb->createNamedParameter(4, ParameterType::INTEGER))
+            )
+            ->orderBy('mm.sorting', 'ASC')
+            ->executeQuery()
+            ->fetchAllAssociative();
+
+        foreach ($categories as $category) {
+            $filetype = trim((string)($category['filetype'] ?? ''));
+            if ($filetype !== '') {
+                return $filetype;
+            }
+        }
+
+        return '';
+    }
+
     /**
      * @return array<string,mixed>|null
      */
@@ -356,7 +391,7 @@ class DatasheetsJsonRenderer
     /**
      * @return array<string,mixed>|null
      */
-    private function getDownloadFile(int $downloadUid): ?array
+    private function getDownloadFile(int $downloadUid, string $fileprefix = '', string $filetype = ''): ?array
     {
         $qb = GeneralUtility::makeInstance(ConnectionPool::class)
             ->getQueryBuilderForTable('sys_file_reference');
@@ -378,7 +413,7 @@ class DatasheetsJsonRenderer
             ->fetchAssociative();
 
         if (!$row) {
-            return null;
+            return $this->resolveFileByConvention($fileprefix, $filetype);
         }
 
         return [
@@ -392,4 +427,129 @@ class DatasheetsJsonRenderer
             'description' => (string)($row['description'] ?? ''),
         ];
     }
+
+    /**
+     * Resolve file from naming convention:
+     * [fileprefix]__[filetype]__[number]-[letter].ext
+     * and pick highest number + highest letter.
+     *
+     * @return array<string,mixed>|null
+     */
+    private function resolveFileByConvention(string $fileprefix, string $filetype): ?array
+    {
+        $fileprefix = trim($fileprefix);
+        $filetype = trim($filetype);
+        if ($fileprefix === '' || $filetype === '') {
+            return null;
+        }
+
+        $baseDir = Environment::getPublicPath() . '/fileadmin/downloads/Collateral';
+        if (!is_dir($baseDir) || !is_readable($baseDir)) {
+            return null;
+        }
+
+        $escapedPrefix = preg_quote($fileprefix, '/');
+        $escapedType = preg_quote($filetype, '/');
+        $pattern = '/^' . $escapedPrefix . '__' . $escapedType . '__(\\d+)-([A-Za-z]+)\\.([A-Za-z0-9]+)$/';
+
+        $bestFile = null;
+        $bestNumber = -1;
+        $bestLetterRank = -1;
+
+        $entries = scandir($baseDir);
+        if ($entries === false) {
+            return null;
+        }
+
+        foreach ($entries as $entry) {
+            if (!is_string($entry) || $entry === '.' || $entry === '..') {
+                continue;
+            }
+
+            if (!preg_match($pattern, $entry, $matches)) {
+                continue;
+            }
+
+            $number = (int)$matches[1];
+            $letter = strtoupper($matches[2]);
+            $letterRank = $this->letterSequenceToRank($letter);
+
+            if ($number > $bestNumber || ($number === $bestNumber && $letterRank > $bestLetterRank)) {
+                $bestNumber = $number;
+                $bestLetterRank = $letterRank;
+                $bestFile = $entry;
+            }
+        }
+
+        if ($bestFile === null) {
+            return null;
+        }
+
+        $fullPath = $baseDir . '/' . $bestFile;
+        if (!is_file($fullPath) || !is_readable($fullPath)) {
+            return null;
+        }
+
+        $extension = strtolower(pathinfo($bestFile, PATHINFO_EXTENSION));
+        $mimeType = function_exists('mime_content_type') ? (string)(mime_content_type($fullPath) ?: '') : '';
+
+        return [
+            'uid' => 0,
+            'name' => $bestFile,
+            'url' => '/fileadmin/downloads/Collateral/' . rawurlencode($bestFile),
+            'size' => (int)(filesize($fullPath) ?: 0),
+            'extension' => $extension,
+            'mimeType' => $mimeType,
+            'title' => '',
+            'description' => '',
+        ];
+    }
+
+    private function letterSequenceToRank(string $letters): int
+    {
+        $rank = 0;
+        $letters = strtoupper($letters);
+        $length = strlen($letters);
+
+        for ($i = 0; $i < $length; $i++) {
+            $char = ord($letters[$i]);
+            if ($char < 65 || $char > 90) {
+                continue;
+            }
+
+            $rank = ($rank * 26) + ($char - 64);
+        }
+
+        return $rank;
+    }
+
+    /**
+     * @param array<int,array<string,mixed>> $items
+     * @return array<int,array<string,mixed>>
+     */
+    private function collectFallbackFilesFromItems(array $items): array
+    {
+        $fallbackFiles = [];
+
+        foreach ($items as $item) {
+            $datasheet = $item['datasheet'] ?? null;
+            if (!is_array($datasheet)) {
+                continue;
+            }
+
+            $file = $datasheet['file'] ?? null;
+            if (!is_array($file) || (int)($file['uid'] ?? 1) !== 0) {
+                continue;
+            }
+
+            $fallbackFiles[] = [
+                'datasheetUid' => (int)($datasheet['uid'] ?? 0),
+                'name' => (string)($file['name'] ?? ''),
+                'url' => (string)($file['url'] ?? ''),
+                'source' => 'naming-convention-fallback',
+            ];
+        }
+
+        return $fallbackFiles;
+    }
 }