<?php

declare(strict_types=1);

namespace Evomedien\Vitec\UserFunc;


use Evomedien\Vitec\Service\StructuredDataService;
use TYPO3\CMS\Core\Attribute\AsAllowedCallable;
use TYPO3\CMS\Core\Core\Environment;
use TYPO3\CMS\Core\Database\ConnectionPool;
use TYPO3\CMS\Core\Service\FlexFormService;
use Evomedien\Vitec\Service\RteResolver;
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Core\Resource\ResourceFactory;
use TYPO3\CMS\Core\Imaging\ImageManipulation\CropVariantCollection;
use TYPO3\CMS\Core\Resource\FileReference;
use TYPO3\CMS\Extbase\Service\ImageService;
use Doctrine\DBAL\ParameterType;
use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;

/**
 * UserFunc to render a single product as JSON for headless output.
 *
 * `render()` performs page discovery (top-level plugin via TypoScript).
 * `renderForRecord()` processes one specific tt_content row and is reused
 * by ContainerChildrenProcessor for product-show plugins nested in a
 * b13 container.
 */
class ProductShowJsonRenderer
{
    private ?ContentObjectRenderer $cObj = null;

    /**
     * TYPO3 v14 hands the ContentObjectRenderer over through this setter only -
     * ContentObjectRenderer::callUserFunction() duck-types it with
     * is_callable([$classObj, 'setContentObjectRenderer']). Without the method
     * $this->cObj stays null, the cObj branch of render() never fires and the
     * call falls through to page discovery, which picks the FIRST element of
     * this CType on the page rather than the one actually being rendered.
     */
    public function setContentObjectRenderer(ContentObjectRenderer $cObj): void
    {
        $this->cObj = $cObj;
    }

    #[AsAllowedCallable]
    public function render(string $content, array $conf): string
    {
        // 1) cObj data path
        $row = is_array($this->cObj?->data ?? null) ? $this->cObj->data : null;
        if ($row && (string)($row['CType'] ?? '') === 'vitec_productshow') {
            return $this->renderForRecord($row);
        }

        // 2) Page-id via v14 request attribute (TSFE->id is often null in JSON cObj context)
        $pageId = 0;
        $request = $GLOBALS['TYPO3_REQUEST'] ?? null;
        if ($request !== null) {
            $pageInfo = $request->getAttribute('frontend.page.information');
            if ($pageInfo !== null) {
                $pageId = (int)$pageInfo->getId();
            }
        }
        if ($pageId <= 0) {
            $pageId = (int)($GLOBALS['TSFE']->id ?? 0);
        }
        if ($pageId <= 0) {
            return '';
        }

        $queryBuilder = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
            ->getQueryBuilderForTable('tt_content');

        $contentElements = $queryBuilder
            ->select('*')
            ->from('tt_content')
            ->where(
                $queryBuilder->expr()->eq('pid', $queryBuilder->createNamedParameter($pageId, ParameterType::INTEGER)),
                $queryBuilder->expr()->eq('CType', $queryBuilder->createNamedParameter('vitec_productshow', ParameterType::STRING)),
                $queryBuilder->expr()->eq('deleted', 0),
                $queryBuilder->expr()->eq('hidden', 0)
            )
            ->executeQuery()
            ->fetchAllAssociative();

        if (empty($contentElements)) {
            return '';
        }

        return $this->renderForRecord($contentElements[0]);
    }


    /**
     * Render exactly the given tt_content row (the product-show plugin element).
     * Exception-safe: returns '' on any failure.
     *
     * @param array<string,mixed> $contentElement
     */
    public function renderForRecord(array $contentElement): string
    {
        try {
            $pageId = (int)($GLOBALS['TSFE']->id ?? 0);

            $flexFormService = GeneralUtility::makeInstance(FlexFormService::class);
            $flexFormData = $flexFormService->convertFlexFormContentToArray($contentElement['pi_flexform'] ?? '');
            $settings = $flexFormData['settings'] ?? [];

            $productUid = (int)($settings['product'] ?? 0);
            $layout = (int)($settings['layout'] ?? 0);
            $debugMode = (bool)($settings['debug'] ?? false);

            if (!$productUid) {
                $routeParams = $GLOBALS['TYPO3_REQUEST']->getQueryParams();
                $productParam = $routeParams['tx_vitec_productshow']['product'] ?? null;

                if ($productParam) {
                    if (!is_numeric($productParam)) {
                        $slugQueryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
                            ->getQueryBuilderForTable('tx_vitec_domain_model_product');

                        $productBySlug = $slugQueryBuilder
                            ->select('uid')
                            ->from('tx_vitec_domain_model_product')
                            ->where(
                                $slugQueryBuilder->expr()->eq('slug', $slugQueryBuilder->createNamedParameter($productParam)),
                                $slugQueryBuilder->expr()->eq('deleted', 0),
                                $slugQueryBuilder->expr()->eq('hidden', 0)
                            )
                            ->executeQuery()
                            ->fetchAssociative();

                        $productUid = (int)($productBySlug['uid'] ?? 0);
                    } else {
                        $productUid = (int)$productParam;
                    }
                }
            }

            if (!$productUid) {
                return $debugMode
                    ? json_encode(['error' => 'No product selected or found', 'debug' => ['settings' => $settings]])
                    : '';
            }

            $productQueryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
                ->getQueryBuilderForTable('tx_vitec_domain_model_product');

            $product = $productQueryBuilder
                ->select('*')
                ->from('tx_vitec_domain_model_product')
                ->where(
                    $productQueryBuilder->expr()->eq('uid', $productQueryBuilder->createNamedParameter($productUid, ParameterType::INTEGER)),
                    $productQueryBuilder->expr()->eq('deleted', 0),
                    $productQueryBuilder->expr()->eq('hidden', 0)
                )
                ->executeQuery()
                ->fetchAssociative();

            if (!$product) {
                return $debugMode
                    ? json_encode(['error' => 'Product not found', 'debug' => ['productUid' => $productUid]])
                    : '';
            }

            // Page <title> for the detail page: the product's seotitle, falling
            // back to its title. Fed from here because in headless mode the
            // Extbase showAction (which used to do this) never runs; headless's
            // MetaHandler reads the provider chain when composing `seo`.
            $pageTitle = trim((string)($product['seotitle'] ?? ''));
            if ($pageTitle === '') {
                $pageTitle = trim((string)($product['title'] ?? ''));
            }
            if ($pageTitle !== '') {
                GeneralUtility::makeInstance(\Evomedien\Vitec\PageTitle\ProductPageTitleProvider::class)
                    ->setSeoTitle($pageTitle);
            }

            $response = [
                'product' => $this->serializeProduct($product),
                'layout' => $layout,
                'settings' => [
                    'layout' => $layout,
                ],
            ];

            if ($debugMode) {
                $response['debug'] = [
                    'pageId' => $pageId,
                    'productUid' => $productUid,
                    'layout' => $layout,
                    'settings' => $settings,
                    'fallbackFiles' => $this->collectFallbackFilesFromDownloads((array)($response['product']['downloads'] ?? [])),
                ];
            }

            return json_encode($response);
        } catch (\Throwable $e) {
            return '';
        }
    }

    /**
     * @param array<string,mixed> $product
     * @return array<string,mixed>
     */
    protected function serializeProduct(array $product): array
    {
        $uid = (int)$product['uid'];

        $data = [
            'uid' => $uid,

            'title' => (string)($product['title'] ?? ''),
            'slug' => (string)($product['slug'] ?? ''),
            'urltitle' => (string)($product['urltitle'] ?? ''),
            'seotitle' => (string)($product['seotitle'] ?? ''),
            'seometa' => (string)($product['seometa'] ?? ''),
            'keywords' => (string)($product['keywords'] ?? ''),
            'structureddata' => (string)($product['structureddata'] ?? ''),
            'teaser' => (string)($product['teaser'] ?? ''),
            'subtitle' => (string)($product['subtitle'] ?? ''),
            'video' => (string)($product['video'] ?? ''),
            'applications' => RteResolver::html($product['applications'] ?? ''),
            'capabilities' => RteResolver::html($product['capabilities'] ?? ''),
            'description' => RteResolver::html($product['description'] ?? ''),
            'description2' => RteResolver::html($product['description2'] ?? ''),
            'highlights' => RteResolver::html($product['highlights'] ?? ''),
            'textrelatedproducts' => RteResolver::html($product['textrelatedproducts'] ?? ''),
            'shortcutpid' => (string)($product['shortcutpid'] ?? ''),
            'contentelement' => \Evomedien\Vitec\Service\ContentElementResolver::resolveLink((string)($product['contentelement'] ?? '')),
            'contentelementcta' => \Evomedien\Vitec\Service\ContentElementResolver::resolveLink((string)($product['contentelementcta'] ?? '')),
            'portfolio' => \Evomedien\Vitec\Service\LinkResolver::typolinkUrl((string)($product['portfolio'] ?? '')),

            'hideonapp' => (bool)($product['hideonapp'] ?? false),
            'hideonwebsite' => (bool)($product['hideonwebsite'] ?? false),
            'hideondatasheets' => (bool)($product['hideondatasheets'] ?? false),
            'hideonproducts' => (bool)($product['hideonproducts'] ?? false),
            'shortcut' => (bool)($product['shortcut'] ?? false),
            'legacy' => (bool)($product['legacy'] ?? false),
            'supportproduct' => (bool)($product['supportproduct'] ?? false),
            'subproduct' => (bool)($product['subproduct'] ?? false),
            'showdatapath' => (bool)($product['showdatapath'] ?? false),

            'link' => '/product/' . (string)($product['slug'] ?? ''),

            'categories' => $this->getProductCategories($uid),
            'images' => $this->getProductImages($uid),
            'heroimage' => $this->getProductImages($uid, 'heroimage'),
            'downloads' => $this->getProductDownloads($uid),
            'ogimage' => $this->getProductOgImage($uid),
            'videofile' => $this->getProductVideoFile($uid),
            'relatedprodukt' => $this->getRelatedProducts($uid),
            'solutions' => $this->getProductSolutions($uid),
            // Detail-only like heroimage: resource cards are detail-page
            // furniture a list never shows.
            'resources' => $this->resourcesBand($uid, (string)(($product['resources_layout'] ?? '') ?: '50-50')),
        ];

        // schema.org JSON-LD (Product + optional VideoObject) as a ready-to-emit
        // @graph string. The frontend injects it as <script type="application/ld+json">.
        // Supersedes the manual `structureddata` field above (kept for backwards
        // compatibility until the frontend has switched over).
        $data['jsonLd'] = $this->buildJsonLd($product, $data);

        return $data;
    }

    /**
     * Build the product's structured-data @graph from the already-serialized
     * product array. Exception-safe: returns '' on any failure.
     *
     * @param array<string,mixed> $rawProduct  raw DB row (for crdate/tstamp)
     * @param array<string,mixed> $data        serialized product
     */
    protected function buildJsonLd(array $rawProduct, array $data): string
    {
        try {
            $service = GeneralUtility::makeInstance(StructuredDataService::class);
            $base = $this->resolveCanonicalBase();

            $imageUrls = [];
            foreach (($data['images'] ?? []) as $img) {
                if (!empty($img['url'])) {
                    $imageUrls[] = $service->absUrl((string)$img['url'], $base);
                }
            }
            if ($imageUrls === [] && !empty($data['ogimage']['url'])) {
                $imageUrls[] = $service->absUrl((string)$data['ogimage']['url'], $base);
            }

            $hasOrganization = trim((string)($this->siteSettings()?->get('seo.organization.name') ?? '')) !== '';

            $product = $service->buildProduct($data, $base, $imageUrls, $hasOrganization);

            $uploadTs = (int)($rawProduct['crdate'] ?? $rawProduct['tstamp'] ?? 0);
            $video = $service->buildVideoObject($data, $base, $imageUrls, $uploadTs);

            return $service->encodeGraph([$product, $video]);
        } catch (\Throwable $e) {
            return '';
        }
    }

    /**
     * Site settings of the current request, or null outside a site context.
     */
    protected function siteSettings(): ?\TYPO3\CMS\Core\Site\Entity\SiteSettings
    {
        $request = $GLOBALS['TYPO3_REQUEST'] ?? null;
        return $request?->getAttribute('site')?->getSettings();
    }

    /**
     * Canonical absolute base (e.g. "https://www.vitec.com"). Prefers the
     * explicit site setting, falls back to the request host.
     */
    protected function resolveCanonicalBase(): string
    {
        $configured = trim((string)($this->siteSettings()?->get('seo.site.canonicalBase') ?? ''));
        if ($configured !== '') {
            return rtrim($configured, '/');
        }

        $request = $GLOBALS['TYPO3_REQUEST'] ?? null;
        $normalizedParams = $request?->getAttribute('normalizedParams');
        if ($normalizedParams !== null) {
            return rtrim($normalizedParams->getSiteUrl(), '/');
        }

        return '';
    }

    protected function getProductImages(int $productUid, string $fieldName = 'productimage'): array
    {
        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
            ->getQueryBuilderForTable('sys_file_reference');

        $fileReferences = $queryBuilder
            ->select('*')
            ->from('sys_file_reference')
            ->where(
                $queryBuilder->expr()->eq('uid_foreign', $queryBuilder->createNamedParameter($productUid, ParameterType::INTEGER)),
                $queryBuilder->expr()->eq('tablenames', $queryBuilder->createNamedParameter('tx_vitec_domain_model_product', ParameterType::STRING)),
                $queryBuilder->expr()->eq('fieldname', $queryBuilder->createNamedParameter($fieldName, ParameterType::STRING)),
                $queryBuilder->expr()->eq('deleted', 0),
                $queryBuilder->expr()->eq('hidden', 0)
            )
            ->orderBy('sorting_foreign', 'ASC')
            ->executeQuery()
            ->fetchAllAssociative();

        if (empty($fileReferences)) {
            return [];
        }

        $resourceFactory = GeneralUtility::makeInstance(ResourceFactory::class);
        $imageService = GeneralUtility::makeInstance(ImageService::class);
        $images = [];

        foreach ($fileReferences as $fileRef) {
            try {
                $fileReference = $resourceFactory->getFileReferenceObject($fileRef['uid']);
                $originalFile = $fileReference->getOriginalFile();

                $processedImage = $imageService->applyProcessingInstructions(
                    $fileReference,
                    ['width' => '1874c', 'height' => '625c', 'fileExtension' => 'webp']
                );

                $srcset = [];
                foreach ([400, 800, 1200, 1600] as $width) {
                    $processedVariant = $imageService->applyProcessingInstructions(
                        $fileReference,
                        ['width' => $width . 'c', 'height' => (int)($width / 3) . 'c', 'fileExtension' => 'webp']
                    );
                    $srcset[] = [
                        'url' => $imageService->getImageUri($processedVariant),
                        'width' => $width,
                        'descriptor' => $width . 'w',
                    ];
                }

                $images[] = [
                    'uid' => $fileRef['uid'],
                    'url' => $imageService->getImageUri($processedImage),
                    'title' => $fileReference->getTitle() ?: '',
                    'alternative' => $fileReference->getAlternative() ?: '',
                    'description' => $fileReference->getDescription() ?: '',
                    'srcset' => $srcset,
                    'properties' => [
                        'width' => $originalFile->getProperty('width'),
                        'height' => $originalFile->getProperty('height'),
                        'mimeType' => $originalFile->getMimeType(),
                    ],
                ];
            } catch (\Exception $e) {
                continue;
            }
        }

        return $images;
    }

    /**
     * @return array<string,mixed>|null
     */
    protected function getProductOgImage(int $productUid): ?array
    {
        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
            ->getQueryBuilderForTable('sys_file_reference');

        $fileRef = $queryBuilder
            ->select('*')
            ->from('sys_file_reference')
            ->where(
                $queryBuilder->expr()->eq('uid_foreign', $queryBuilder->createNamedParameter($productUid, ParameterType::INTEGER)),
                $queryBuilder->expr()->eq('tablenames', $queryBuilder->createNamedParameter('tx_vitec_domain_model_product', ParameterType::STRING)),
                $queryBuilder->expr()->eq('fieldname', $queryBuilder->createNamedParameter('ogimage', ParameterType::STRING)),
                $queryBuilder->expr()->eq('deleted', 0),
                $queryBuilder->expr()->eq('hidden', 0)
            )
            ->orderBy('sorting_foreign', 'ASC')
            ->setMaxResults(1)
            ->executeQuery()
            ->fetchAssociative();

        if (!$fileRef) {
            return null;
        }

        try {
            $resourceFactory = GeneralUtility::makeInstance(ResourceFactory::class);
            $imageService = GeneralUtility::makeInstance(ImageService::class);
            $fileReference = $resourceFactory->getFileReferenceObject($fileRef['uid']);
            $originalFile = $fileReference->getOriginalFile();

            $processedImage = $imageService->applyProcessingInstructions(
                $fileReference,
                ['width' => 1200, 'fileExtension' => 'webp']
            );

            return [
                'uid' => $fileRef['uid'],
                'url' => $imageService->getImageUri($processedImage),
                'title' => $fileReference->getTitle() ?: '',
                'alternative' => $fileReference->getAlternative() ?: '',
                'description' => $fileReference->getDescription() ?: '',
                'properties' => [
                    'width' => $originalFile->getProperty('width'),
                    'height' => $originalFile->getProperty('height'),
                    'mimeType' => $originalFile->getMimeType(),
                ],
            ];
        } catch (\Exception $e) {
            return null;
        }
    }


    /**
     * Resolve the uploaded video file (single FAL reference, fieldname=videofile).
     *
     * @return array<string,mixed>|null
     */
    protected function getProductVideoFile(int $productUid): ?array
    {
        $queryBuilder = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
            ->getQueryBuilderForTable('sys_file_reference');

        $row = $queryBuilder
            ->select('fr.uid', 'fr.title', 'fr.description', 'f.uid as file_uid', 'f.identifier', 'f.name', 'f.size', 'f.extension', 'f.mime_type')
            ->from('sys_file_reference', 'fr')
            ->join('fr', 'sys_file', 'f', 'fr.uid_local = f.uid')
            ->where(
                $queryBuilder->expr()->eq('fr.tablenames', $queryBuilder->createNamedParameter('tx_vitec_domain_model_product', \Doctrine\DBAL\ParameterType::STRING)),
                $queryBuilder->expr()->eq('fr.fieldname', $queryBuilder->createNamedParameter('videofile', \Doctrine\DBAL\ParameterType::STRING)),
                $queryBuilder->expr()->eq('fr.uid_foreign', $queryBuilder->createNamedParameter($productUid, \Doctrine\DBAL\ParameterType::INTEGER)),
                $queryBuilder->expr()->eq('fr.deleted', 0),
                $queryBuilder->expr()->eq('fr.hidden', 0),
                $queryBuilder->expr()->eq('f.missing', 0)
            )
            ->orderBy('fr.sorting_foreign', 'ASC')
            ->setMaxResults(1)
            ->executeQuery()
            ->fetchAssociative();

        if (!$row) {
            return null;
        }

        return [
            'uid' => (int)$row['file_uid'],
            'name' => (string)($row['name'] ?? ''),
            'url' => '/fileadmin' . ($row['identifier'] ?? ''),
            'size' => (int)($row['size'] ?? 0),
            'extension' => (string)($row['extension'] ?? ''),
            'mimeType' => (string)($row['mime_type'] ?? ''),
            'title' => (string)($row['title'] ?? ''),
            'description' => (string)($row['description'] ?? ''),
        ];
    }
    protected function getProductCategories(int $productUid): array
    {
        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
            ->getQueryBuilderForTable('sys_category');

        $categories = $queryBuilder
            ->select('c.uid', 'c.title', 'c.description')
            ->from('sys_category', 'c')
            ->join(
                'c',
                'sys_category_record_mm',
                'mm',
                'mm.uid_local = c.uid AND mm.tablenames = ' .
                $queryBuilder->createNamedParameter('tx_vitec_domain_model_product', ParameterType::STRING) .
                ' AND mm.fieldname = ' .
                $queryBuilder->createNamedParameter('categories', ParameterType::STRING)
            )
            ->where(
                $queryBuilder->expr()->eq('mm.uid_foreign', $queryBuilder->createNamedParameter($productUid, ParameterType::INTEGER)),
                $queryBuilder->expr()->eq('c.deleted', 0),
                $queryBuilder->expr()->eq('c.hidden', 0)
            )
            ->orderBy('mm.sorting', 'ASC')
            ->executeQuery()
            ->fetchAllAssociative();

        return array_map(function ($cat) {
            return [
                'uid' => (int)$cat['uid'],
                'title' => $cat['title'],
                'description' => $cat['description'] ?? '',
                'parents' => $this->getCategoryParents((int)$cat['uid']),
            ];
        }, $categories);
    }

    /** @var array<int,array{parent:int,title:string}>|null Lazy uid => [parent,title] map of all categories. */
    private ?array $categoryTreeMap = null;

    /**
     * All ancestor categories of one category, ROOT FIRST (excluding itself).
     * Backed by a once-per-request map of sys_category — cheap for any number
     * of products. Cycle-safe.
     *
     * @return array<int,array{uid:int,title:string}>
     */
    private function getCategoryParents(int $categoryUid): array
    {
        if ($this->categoryTreeMap === null) {
            $qb = GeneralUtility::makeInstance(ConnectionPool::class)
                ->getQueryBuilderForTable('sys_category');
            $rows = $qb
                ->select('uid', 'parent', 'title')
                ->from('sys_category')
                ->where(
                    $qb->expr()->eq('deleted', 0),
                    $qb->expr()->eq('hidden', 0)
                )
                ->executeQuery()
                ->fetchAllAssociative();
            $this->categoryTreeMap = [];
            foreach ($rows as $row) {
                $this->categoryTreeMap[(int)$row['uid']] = [
                    'parent' => (int)$row['parent'],
                    'title' => (string)$row['title'],
                ];
            }
        }

        $parents = [];
        $seen = [$categoryUid => true];
        $current = $this->categoryTreeMap[$categoryUid]['parent'] ?? 0;
        while ($current > 0 && isset($this->categoryTreeMap[$current]) && !isset($seen[$current])) {
            $seen[$current] = true;
            array_unshift($parents, ['uid' => $current, 'title' => $this->categoryTreeMap[$current]['title']]);
            $current = $this->categoryTreeMap[$current]['parent'];
        }

        return $parents;
    }

    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>> $downloads
     * @return array<int,array<string,mixed>>
     */
    private function collectFallbackFilesFromDownloads(array $downloads): array
    {
        $fallbackFiles = [];

        foreach ($downloads as $download) {
            if (!is_array($download)) {
                continue;
            }

            $file = $download['file'] ?? null;
            if (!is_array($file) || (int)($file['uid'] ?? 1) !== 0) {
                continue;
            }

            $fallbackFiles[] = [
                'downloadUid' => (int)($download['uid'] ?? 0),
                'name' => (string)($file['name'] ?? ''),
                'url' => (string)($file['url'] ?? ''),
                'source' => 'naming-convention-fallback',
            ];
        }

        return $fallbackFiles;
    }

    /**
     * Solutions linked to this product (tx_vitec_product_solution_mm, editor
     * order) in the shared solution card shape - the same fields the solution
     * list emits, so the front end reuses its card component. detailUrl is
     * null while a solution has no detail page (9.12 contract).
     */
    protected function getProductSolutions(int $productUid): array
    {
        $queryBuilder = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
            ->getQueryBuilderForTable('tx_vitec_domain_model_solution');
        $rows = $queryBuilder
            ->select('s.*')
            ->from('tx_vitec_domain_model_solution', 's')
            ->join('s', 'tx_vitec_product_solution_mm', 'mm', 'mm.uid_foreign = s.uid')
            ->where(
                $queryBuilder->expr()->eq('mm.uid_local', $queryBuilder->createNamedParameter($productUid, \Doctrine\DBAL\ParameterType::INTEGER)),
                $queryBuilder->expr()->eq('s.deleted', 0),
                $queryBuilder->expr()->eq('s.hidden', 0)
            )
            ->orderBy('mm.sorting', 'ASC')
            ->executeQuery()
            ->fetchAllAssociative();

        $serializer = GeneralUtility::makeInstance(\Evomedien\Vitec\Service\UsecaseSerializer::class);
        $result = [];
        foreach ($rows as $solutionRow) {
            $solutionUid = (int)$solutionRow['uid'];
            $result[] = [
                'uid' => $solutionUid,
                'title' => (string)($solutionRow['title'] ?? ''),
                'slug' => (string)($solutionRow['slug'] ?? ''),
                'subtitle' => (string)($solutionRow['subtitle'] ?? ''),
                'teaser' => (string)($solutionRow['teaser'] ?? ''),
                'description' => \Evomedien\Vitec\Service\RteResolver::html($solutionRow['description'] ?? ''),
                'detailUrl' => \Evomedien\Vitec\Service\LinkResolver::pageUrl((int)($solutionRow['detail_page'] ?? 0)),
                'isGroup' => (bool)($solutionRow['is_group'] ?? false),
                'image' => $serializer->image($solutionUid, 'image', 'tx_vitec_domain_model_solution', true),
            ];
        }

        return $result;
    }

    /**
     * Resource cards from the product's Resources tab (child table
     * tx_vitec_product_resource): documentation / support / datasheet
     * entries, each an editable card (title, text, icon) around one link -
     * page, external URL, file or download record, resolved per 9.12. A card
     * whose link is empty or unresolvable is dropped (decision 2026-09-24).
     * List envelope: `layout` switches to `carousel` above three cards.
     */
    /**
     * The Technical Highlights / Resources band: resource cards plus the
     * section layout (customer CR 2026-10-26) that tells the front end how to
     * arrange the band. Layout `hardware` (2026-11-02) spreads the highlights
     * over two columns WITHOUT resources - the cards are not emitted at all
     * (same envelope, empty items), while the maintained records stay in the
     * product for a switch back.
     *
     * @return array{layout:string,items:array<int,array<string,mixed>>,sectionLayout:string}
     */
    protected function resourcesBand(int $productUid, string $sectionLayout): array
    {
        $band = $sectionLayout === 'hardware'
            ? ['layout' => 'grid', 'items' => []]
            : $this->getProductResources($productUid);
        $band['sectionLayout'] = $sectionLayout;
        return $band;
    }

    protected function getProductResources(int $productUid): array
    {
        $queryBuilder = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
            ->getQueryBuilderForTable('tx_vitec_product_resource');
        $rows = $queryBuilder
            ->select('*')
            ->from('tx_vitec_product_resource')
            ->where(
                $queryBuilder->expr()->eq('product', $queryBuilder->createNamedParameter($productUid, \Doctrine\DBAL\ParameterType::INTEGER)),
                $queryBuilder->expr()->eq('deleted', 0),
                $queryBuilder->expr()->eq('hidden', 0)
            )
            ->orderBy('sorting', 'ASC')
            ->executeQuery()
            ->fetchAllAssociative();

        $items = [];
        foreach ($rows as $resourceRow) {
            $url = \Evomedien\Vitec\Service\LinkResolver::typolinkUrl((string)($resourceRow['link'] ?? ''));
            if ($url === null) {
                continue;
            }
            $items[] = [
                'type' => (string)($resourceRow['restype'] ?? ''),
                'title' => (string)($resourceRow['title'] ?? ''),
                'text' => (string)($resourceRow['cardtext'] ?? ''),
                'icon' => (string)($resourceRow['icon'] ?? ''),
                'url' => $url,
            ];
        }

        // Datasheets are their own MM selection of download records and join
        // the same envelope as ready-made cards: url is the public forced-
        // download route (slug route since 2026-08-21, uid route as
        // fallback), so the DownloadFileResolver rules apply unchanged -
        // a private or hidden download simply 404s.
        $datasheetQueryBuilder = GeneralUtility::makeInstance(\TYPO3\CMS\Core\Database\ConnectionPool::class)
            ->getQueryBuilderForTable('tx_vitec_domain_model_download');
        $datasheetRows = $datasheetQueryBuilder
            ->select('d.uid', 'd.title', 'd.slug', 'd.teaser', 'd.icon')
            ->from('tx_vitec_domain_model_download', 'd')
            ->join('d', 'tx_vitec_product_datasheet_mm', 'mm', 'mm.uid_foreign = d.uid')
            ->where(
                $datasheetQueryBuilder->expr()->eq('mm.uid_local', $datasheetQueryBuilder->createNamedParameter($productUid, \Doctrine\DBAL\ParameterType::INTEGER)),
                $datasheetQueryBuilder->expr()->eq('d.deleted', 0),
                $datasheetQueryBuilder->expr()->eq('d.hidden', 0)
            )
            ->orderBy('mm.sorting', 'ASC')
            ->executeQuery()
            ->fetchAllAssociative();

        foreach ($datasheetRows as $datasheetRow) {
            $slug = trim((string)($datasheetRow['slug'] ?? ''), "/ ");
            $items[] = [
                'type' => 'datasheet',
                'title' => (string)($datasheetRow['title'] ?? ''),
                'text' => (string)($datasheetRow['teaser'] ?? ''),
                'icon' => ((string)($datasheetRow['icon'] ?? '')) !== '' ? (string)$datasheetRow['icon'] : 'datasheet',
                'url' => $slug !== '' ? '/download/' . $slug : '/download/file/' . (int)$datasheetRow['uid'],
            ];
        }

        return [
            'layout' => count($items) > 3 ? 'carousel' : 'grid',
            'items' => $items,
        ];
    }

    protected function getProductDownloads(int $productUid): array
    {
        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
            ->getQueryBuilderForTable('tx_vitec_domain_model_download');

        $downloads = $queryBuilder
            ->select('d.*')
            ->from('tx_vitec_domain_model_download', 'd')
            ->join(
                'd',
                'tx_vitec_product_download_mm',
                'mm',
                'mm.uid_foreign = d.uid'
            )
            ->where(
                $queryBuilder->expr()->eq('mm.uid_local', $queryBuilder->createNamedParameter($productUid, ParameterType::INTEGER)),
                $queryBuilder->expr()->eq('d.deleted', 0),
                $queryBuilder->expr()->eq('d.hidden', 0),
                $queryBuilder->expr()->eq('d.hideonwebsite', 0)
            )
            ->orderBy('mm.sorting', 'ASC')
            ->executeQuery()
            ->fetchAllAssociative();

        $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(ConnectionPool::class)
                    ->getQueryBuilderForTable('sys_file_reference');

                $fileRef = $fileQueryBuilder
                    ->select('fr.uid', 'f.uid as file_uid', 'f.identifier', 'f.name', 'f.size', 'f.extension', 'f.mime_type')
                    ->from('sys_file_reference', 'fr')
                    ->join('fr', 'sys_file', 'f', 'fr.uid_local = f.uid')
                    ->where(
                        $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),
                        $fileQueryBuilder->expr()->eq('f.missing', 0)
                    )
                    ->orderBy('fr.sorting_foreign', 'ASC')
                    ->setMaxResults(1)
                    ->executeQuery()
                    ->fetchAssociative();

                if ($fileRef) {
                    $fileInfo = [
                        'uid' => (int)$fileRef['file_uid'],
                        'name' => $fileRef['name'],
                        'url' => '/fileadmin' . $fileRef['identifier'],
                        'size' => (int)$fileRef['size'],
                        'extension' => $fileRef['extension'],
                        'mimeType' => $fileRef['mime_type'] ?? '',
                    ];
                }
            }

            if ($fileInfo === null) {
                $fileInfo = $this->resolveFileByConvention($fileprefix, $filetype);
            }

            $result[] = [
                'uid' => $downloadUid,
                'title' => $download['title'] ?? '',
                'slug' => $download['slug'] ?? '',
                'teaser' => $download['teaser'] ?? '',
                'description' => RteResolver::html($download['description'] ?? ''),
                'keywords' => $download['keywords'] ?? '',
                'icon' => $download['icon'] ?? '',
                'fileprefix' => $fileprefix,
                'filetype' => $filetype,
                'file' => $fileInfo,
            ];
        }

        return $result;
    }

    protected function getRelatedProducts(int $productUid): array
    {
        $queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
            ->getQueryBuilderForTable('tx_vitec_domain_model_product');

        $related = $queryBuilder
            ->select('p.uid', 'p.title', 'p.slug', 'p.subtitle', 'p.teaser', 'p.description')
            ->addSelectLiteral('t.cardtext')
            ->from('tx_vitec_domain_model_product', 'p')
            ->join(
                'p',
                'tx_vitec_product_related_mm',
                'mm',
                'mm.uid_foreign = p.uid'
            )
            // Per-pair card copy from the workbook import. A separate table
            // rather than an MM column, because DataHandler rewrites the MM
            // rows on every product save - see tx_vitec_product_related_text
            // in ext_tables.sql.
            ->leftJoin(
                'mm',
                'tx_vitec_product_related_text',
                't',
                't.product_uid = mm.uid_local AND t.related_uid = p.uid'
            )
            ->where(
                $queryBuilder->expr()->eq('mm.uid_local', $queryBuilder->createNamedParameter($productUid, ParameterType::INTEGER)),
                $queryBuilder->expr()->eq('p.deleted', 0),
                $queryBuilder->expr()->eq('p.hidden', 0)
            )
            ->orderBy('mm.sorting', 'ASC')
            ->executeQuery()
            ->fetchAllAssociative();

        $result = [];
        foreach ($related as $rel) {
            $relUid = (int)$rel['uid'];
            $result[] = [
                'uid' => $relUid,
                'title' => (string)($rel['title'] ?? ''),
                'slug' => (string)($rel['slug'] ?? ''),
                'subtitle' => (string)($rel['subtitle'] ?? ''),
                'teaser' => (string)($rel['teaser'] ?? ''),
                'description' => RteResolver::html($rel['description'] ?? ''),
                'cardtext' => (string)($rel['cardtext'] ?? ''),
                'link' => '/product/' . (string)($rel['slug'] ?? ''),
                'images' => $this->getProductImages($relUid),
            ];
        }

        return $result;
    }
}