<?php

declare(strict_types=1);

namespace App\Support;

/**
 * Маппинг строки региона из ответа DaData → код субъекта РФ (1..89).
 *
 * DaData возвращает регион в поле `region` (например «Москва», «Московская область»).
 * Большинство имён точно совпадают с App\Support\RussianRegions::CODE_TO_NAME;
 * расхождения (если найдутся на staging) кладутся в OVERRIDES.
 *
 * «Объединённые» агломерации («Санкт-Петербург и область») — DaData не различает
 * город и область внутри поля region. Такие строки помечаются isAmbiguous() →
 * LeadRegionResolver уходит за точным subject_code в Россвязь (spec §3.4.1).
 */
final class DaDataRegionMap
{
    /**
     * Строки-агломерации, по которым нельзя однозначно определить субъект.
     * Расширяется по реальным наблюдениям на staging (spec §3.4.1).
     *
     * @var list<string>
     */
    public const AMBIGUOUS_REGIONS = [
        'Санкт-Петербург и область',
        'Москва и область',
    ];

    /**
     * Ручные переопределения для имён DaData, не совпадающих с RussianRegions.
     * На старте пуст — заполняется по findings со staging-smoke.
     *
     * @var array<string, int>
     */
    public const OVERRIDES = [];

    public static function toSubjectCode(string $name): ?int
    {
        $name = trim($name);
        if ($name === '') {
            return null;
        }

        return self::OVERRIDES[$name] ?? RussianRegions::nameToCode()[$name] ?? null;
    }

    public static function isAmbiguous(string $name): bool
    {
        return in_array(trim($name), self::AMBIGUOUS_REGIONS, true);
    }
}
