ADR-0072: Расширяемость вместо хардкода; переиспользование существующих механизмов
Status: accepted Date: 2026-07-09 Deciders: Maxim Belkanov
Контекст
Повторяющийся анти-паттерн: доменные перечни/маппинги/классификации/нормализации решаются хардкодом
в Go — жёсткие мапы, if-цепочки, зашитые списки (пример: список юридических суффиксов производителей
{ооо, ltd, gmbh, …} в коде для схлопывания «Конкорд»/«Конкорд ООО»/«Konkord»). Такое решение не
масштабируется: каждый новый вариант требует правки кода и деплоя, дублирует уже существующие в проекте
механизмы и не даёт admin/LLM/moderation управлять данными.
Проект уже содержит боевой, data-driven механизм нормализации вариантов — valuenorm
(characteristic_value_dictionary: (canonical_name, raw_value_normalised) → canonical_value, source
seed|llm|moderator, needs_review, confidence, unmapped-очередь → LLM/модератор). Он решает ровно
задачу «привести разнобой к единому», расширяем без деплоя.
Решение
- Доменные списки/маппинги/классификации/нормализации — data-driven, не хардкод. Правила живут в справочнике (БД/конфиг), управляются admin / LLM / moderation. Новая запись не требует изменения кода.
- Сначала переиспользовать существующий механизм, потом строить новый. Перед реализацией нормализации/дедупа/классификации — найти уже решённое в проекте (в первую очередь valuenorm) и переиспользовать; новый механизм заводить только с обоснованием, почему существующий не подходит.
- Хардкод-перечень доменных значений в ревью — стоп-сигнал. Зашитый список брендов/суффиксов/ синонимов/категорий переписывается на справочник до мёржа.
- Допустимо в коде: структурные инварианты, схемы, чистая синтаксическая гигиена (trim, lower, срез пунктуации) — то, что не является доменным знанием о конкретных значениях. Само доменное знание («ООО — юр-форма», «Konkord ≡ Конкорд») — данные.
Последствия
- Дедуп/алиасинг производителей делается через valuenorm-словарь (canonical_name «manufacturer»), а не через зашитый список суффиксов; транслит/акронимы добавляются как записи словаря (seed/LLM/moderator).
- Новые классификаторы/нормализаторы по умолчанию проектируются как справочник + резолвер + очередь необработанного, а не как код.
Связано
- valuenorm BC (
internal/core/valuenorm), ADR-0044 (charnorm/LLM pipeline). - Применение: спека
2026-07-09-canonical-identity-manufacturer-scoped-design.md(идентичность производителя через valuenorm), ADR-0071 (идентичность каноника).