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/ProductListJsonRenderer.php

@@ -9,6 +9,7 @@ use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
 use Doctrine\DBAL\ParameterType;
 use Evomedien\Vitec\Domain\Repository\ProductRepository;
 use Psr\Http\Message\ServerRequestInterface;
+use TYPO3\CMS\Core\Core\Environment;
 use TYPO3\CMS\Core\Database\Connection;
 use TYPO3\CMS\Core\Imaging\ImageManipulation\CropVariantCollection;
 use TYPO3\CMS\Core\Resource\FileReference;
@@ -141,6 +142,7 @@ class ProductListJsonRenderer
                         'categoryUids' => $categoryUids,
                         'productCount' => count($productsData),
                         'settings' => $settings,
+                        'fallbackFiles' => $this->collectFallbackFilesFromProducts($productsData),
                     ],
                 ]);
             }
@@ -413,6 +415,168 @@ class ProductListJsonRenderer
         }, $categories);
     }
 
+    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
+     */
+    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];
+            $letterRank = $this->letterSequenceToRank((string)$matches[2]);
+
+            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,
+        ];
+    }
+
+    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>> $products
+     * @return array<int,array<string,mixed>>
+     */
+    private function collectFallbackFilesFromProducts(array $products): array
+    {
+        $fallbackFiles = [];
+
+        foreach ($products as $product) {
+            $downloads = $product['downloads'] ?? null;
+            if (!is_array($downloads)) {
+                continue;
+            }
+
+            foreach ($downloads as $download) {
+                if (!is_array($download)) {
+                    continue;
+                }
+
+                $file = $download['file'] ?? null;
+                if (!is_array($file) || (int)($file['uid'] ?? 1) !== 0) {
+                    continue;
+                }
+
+                $fallbackFiles[] = [
+                    'productUid' => (int)($product['uid'] ?? 0),
+                    'downloadUid' => (int)($download['uid'] ?? 0),
+                    'name' => (string)($file['name'] ?? ''),
+                    'url' => (string)($file['url'] ?? ''),
+                    'source' => 'naming-convention-fallback',
+                ];
+            }
+        }
+
+        return $fallbackFiles;
+    }
+
     protected function getProductDownloads(int $productUid): array
     {
         $queryBuilder = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
@@ -440,6 +604,9 @@ class ProductListJsonRenderer
         $result = [];
         foreach ($downloads as $download) {
             $fileInfo = null;
+            $downloadUid = (int)$download['uid'];
+            $fileprefix = (string)($download['fileprefix'] ?? '');
+            $filetype = $this->getDownloadFileType($downloadUid);
 
             if (!empty($download['file'])) {
                 $fileQueryBuilder = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
@@ -450,7 +617,7 @@ class ProductListJsonRenderer
                     ->from('sys_file_reference', 'fr')
                     ->join('fr', 'sys_file', 'f', 'fr.uid_local = f.uid')
                     ->where(
-                        $fileQueryBuilder->expr()->eq('fr.uid_foreign', $fileQueryBuilder->createNamedParameter((int)$download['uid'], ParameterType::INTEGER)),
+                        $fileQueryBuilder->expr()->eq('fr.uid_foreign', $fileQueryBuilder->createNamedParameter($downloadUid, ParameterType::INTEGER)),
                         $fileQueryBuilder->expr()->eq('fr.tablenames', $fileQueryBuilder->createNamedParameter('tx_vitec_domain_model_download', ParameterType::STRING)),
                         $fileQueryBuilder->expr()->eq('fr.fieldname', $fileQueryBuilder->createNamedParameter('file', ParameterType::STRING)),
                         $fileQueryBuilder->expr()->eq('fr.deleted', 0),
@@ -473,14 +640,20 @@ class ProductListJsonRenderer
                 }
             }
 
+            if ($fileInfo === null) {
+                $fileInfo = $this->resolveFileByConvention($fileprefix, $filetype);
+            }
+
             $result[] = [
-                'uid' => (int)$download['uid'],
+                'uid' => $downloadUid,
                 'title' => $download['title'] ?? '',
                 'slug' => $download['slug'] ?? '',
                 'teaser' => $download['teaser'] ?? '',
                 'description' => $download['description'] ?? '',
                 'keywords' => $download['keywords'] ?? '',
                 'icon' => $download['icon'] ?? '',
+                'fileprefix' => $fileprefix,
+                'filetype' => $filetype,
                 'file' => $fileInfo,
             ];
         }