План исправления архитектуры, React-кода и качества BELF

1. Статус документа

Этот документ — актуальный исполняемый план следующего цикла рефакторинга BELF. Он дополняет завершённую миграцию CSS Modules и заменяет старые планы в части будущих работ.

План составлен по состоянию проекта на 16 сентября 2026 года. Исходный baseline:

npm run check — PASS;
Vitest — 17 тестов PASS;
Playwright — 96 тестов PASS на шести viewport;
production и SSR/prerender build — PASS;
полный recommended preset установленного eslint-plugin-react-hooks — FAIL: одна ошибка react-hooks/set-state-in-effect в NavigationOverlay;
текущие ESLint boundary rules допускают запрещённые относительные импорты;
keyboard focus в открытом modal navigation может выйти за пределы dialog.

Работа по этому плану считается завершённой только после одновременного прохождения всех пунктов Final Quality Gate из раздела 13.

2. Цели

Исправить все обнаруженные ошибки, не меняя согласованный дизайн и контент.
Сделать архитектурные границы автоматически проверяемыми, а не только описанными в документации.
Привести React-код к полному recommended preset используемой версии eslint-plugin-react-hooks.
Сделать modal navigation корректным для клавиатуры и assistive technologies.
Исключить молчаливые ошибки в связке modules ↔ pricing.
Создать единый источник истины для контактов, site identity и SEO metadata.
Разделить крупные файлы по самостоятельным обязанностям без over-componentization.
Сделать код предсказуемым для чтения: единые импорты, имена, public API, расположение тестов и правила владения стилями.
Усилить CI так, чтобы регрессия архитектуры, accessibility, типов, поведения, визуала или bundle size блокировала deploy.
Построить устойчивое SEO для брендовых и предметных запросов: сделать BELF однозначной поисковой сущностью, расширить индексируемую информационную архитектуру и измерять позиции, видимость и органические обращения.

3. Неприкосновенные ограничения

Во время выполнения запрещено:

менять тексты, цены, маршруты, anchors, контакты и SEO-смысл без отдельного продуктового требования;
менять согласованные размеры, цвета, spacing, typography, breakpoints и анимации только ради рефакторинга;
обновлять visual snapshots до установления точной причины расхождения и ручного подтверждения изменения;
отключать правила ESLint, TypeScript, Stylelint или accessibility-проверки;
добавлять eslint-disable, @ts-ignore, @ts-nocheck, any, необоснованные type assertions или !important для прохождения gate;
ослаблять assertions, coverage threshold или visual threshold ради зелёного CI;
смешивать исправление поведения, перенос файлов и массовое форматирование в одной итерации;
создавать компоненты, hooks, types или директории «на будущее»;
создавать глобальные barrel-файлы, скрывающие направление зависимостей;
добавлять runtime dependency, если задача решается React, DOM API или текущими библиотеками;
удалять или перезаписывать несвязанные пользовательские изменения;
выполнять commit, push, merge или deploy без отдельного запроса владельца.

Для SEO дополнительно запрещено:

обещать гарантированное первое место или фиксированный срок выхода в топ;
создавать doorway pages, массовые шаблонные страницы или тексты только ради вариаций ключевого запроса;
использовать keyword stuffing, скрытый текст, покупные ссылки, cloaking или ложные отзывы;
публиковать неподтверждённые цифры, кейсы, сертификаты, интеграции и сравнения;
добавлять structured data, содержание которого не видно пользователю или не соответствует странице.

Допустимая визуальная дельта по умолчанию — нулевая. Исключение: технически необходимая кнопка закрытия внутри modal navigation. Она должна визуально совпасть с текущей кнопкой-крестиком и пройти отдельное ручное подтверждение.

4. Целевая архитектура

4.1. Слои

app → pages → widgets → features → shared

Разрешённые зависимости:

Слой	Может импортировать
`app`	`pages`, `widgets`, `features`, `shared`
`pages`	локальные sections, `widgets`, `features`, `shared`
`widgets`	`features`, `shared`
`features`	`shared`
`shared`	только другие модули `shared` и внешние пакеты

Дополнительные правила:

одна страница не импортирует внутренности другой страницы;
feature не знает, в какой странице или widget она отображается;
widget не импортирует page-specific data или page CSS;
shared не содержит бизнес-сценариев страницы;
cross-layer import использует @/...;
относительный ./... используется только внутри одной директории модуля;
parent-relative imports ../... запрещены;
внутренние файлы feature/widget не импортируются снаружи в обход его public API;
допустим только локальный index.ts на корне самостоятельного feature/widget; общий src/index.ts не создаётся.

4.2. Целевая структура

src/
  app/
    entrypoints/
      home.tsx
      partners.tsx
      careers.tsx
    entry-server.tsx
    mountApp.tsx

  pages/
    home/
      HomePage.tsx
      sections/
        HeroSection/
          HeroSection.tsx
          HeroSection.module.css
        SignalStrip/
          SignalStrip.tsx
          SignalStrip.module.css
        PlatformSection/
        ModulesSection/
        ProctoringSection/
        DeploymentSection/
        CalculatorSection/
          CalculatorSection.tsx
          CalculatorSection.module.css
        ClosingSections/
    partners/
      PartnersPage.tsx
      data.ts
      components/
        ApplicationForm/
      sections/
    careers/
      CareersPage.tsx
      data.ts
      components/
        ResumeForm/
      sections/

  widgets/
    site-header/
      index.ts
      SiteHeader.tsx
      SiteHeader.module.css
      SiteHeader.test.tsx
      NavigationDialog.tsx
      NavigationDialog.module.css
      NavigationDialog.test.tsx
      navigation-dialog.model.ts
      navigation-dialog.model.test.ts
      NavigationGroups.tsx
      NavigationContact.tsx
    site-footer/
      index.ts
      SiteFooter.tsx
      SiteFooter.module.css

  features/
    navigation-theme/
      index.ts
      NavigationThemeProvider.tsx
      NavThemeRegion.tsx
      useHeaderTheme.ts
      navigation-theme.model.ts
      navigation-theme.model.test.ts
    calculator/
      index.ts
      Calculator.tsx
      Calculator.test.tsx
      components/
        CalculatorForm/
          CalculatorForm.tsx
          CalculatorForm.module.css
          CalculatorForm.test.tsx
        CalculatorQuote/
          CalculatorQuote.tsx
          CalculatorQuote.module.css
      model/
        calculator.types.ts
        calculator.ts
        calculator.test.ts

  shared/
    config/
      site.ts
      seo.ts
    data/
      modules.ts
      pricing.ts
    lib/
      clipboard.ts
      mailto.ts
    ui/
    assets/

  styles/
    fonts.css
    tokens.css
    reset.css
    global.css
    home-utilities.css
    partners-utilities.css
    careers-utilities.css

Это целевое дерево, а не требование создать все папки заранее. Директория создаётся только вместе с реальным владельцем и тестом.

4.3. Правило выделения компонента

Новый компонент создаётся, если выполняется хотя бы одно условие:

блок имеет самостоятельную пользовательскую или бизнес-ответственность;
у блока есть собственное состояние, effect, accessibility contract или тест;
блок повторяется минимум в двух местах;
блок имеет самостоятельный CSS-владелец;
имя компонента объясняет код лучше, чем чтение его JSX;
часть можно изменить независимо от родителя.

Не выделять компонент:

ради уменьшения количества строк без смысловой границы;
вокруг одного div, заголовка или иконки;
если единственный результат — прокидывание тех же props через дополнительный слой;
если компонент получает неявный контракт вроде styles: Record<string, string>;
если разделение создаёт циклическую зависимость или скрывает владельца данных.

5. Обязательные стандарты кода

5.1. React

включён полный eslint-plugin-react-hooks recommended preset;
components и hooks чистые и детерминированные во время render;
hook вызывается только на верхнем уровне компонента или custom hook;
effect используется только для синхронизации с внешней системой;
синхронный setState внутри effect запрещён;
derived values не хранятся в state;
props, state и hook arguments не мутируются;
DOM globals не читаются во время SSR render без SSR-safe abstraction;
timers, observers и event listeners всегда имеют cleanup;
async effect защищён от stale completion или поддерживает cancellation;
interactive state проверяется component test;
StrictMode остаётся включённым;
SSR output и первый client render должны совпадать без hydration warning.

5.2. TypeScript

strict: true сохраняется;
включаются noUncheckedIndexedAccess, exactOptionalPropertyTypes, noFallthroughCasesInSwitch и noImplicitOverride;
запрещены any, необоснованный non-null assertion и широкие string там, где существует закрытый домен;
состояния UI с несколькими режимами описываются discriminated union;
конфиги проверяются через satisfies, чтобы сохранить литеральные типы;
типы бизнес-модели не объявляются внутри UI-компонента;
парсинг внешних JSON/API-данных имеет runtime validation на границе;
функция не принимает состояние, невозможное в пользовательском интерфейсе, без явной валидации.

5.3. Имена и файлы

компонент и файл компонента имеют одинаковое PascalCase-имя;
hooks начинаются с use и отражают один сценарий;
model.ts заменяется предметным именем, если в директории больше одной модели;
булевы значения именуются is*, has*, can* или should*;
обработчики: handle* внутри компонента, on* в props;
magic numbers получают предметное имя или token;
default export допустим для page entry; reusable feature/widget использует named exports через локальный public API;
комментарий объясняет причину или ограничение, а не пересказывает код.

5.4. Ограничения сложности

Значения являются blocking threshold, а не целью искусственно дробить код:

cyclomatic complexity функции — не более 10;
вложенность — не более 3 уровней;
функция/компонент — не более 80 значимых строк;
TS/TSX-файл — не более 220 значимых строк;
CSS Module — не более 300 строк;
при обоснованном исключении требуется ADR или комментарий в quality report; inline-disable не допускается.

Для существующего файла выше порога сначала определяется смысловая граница, и только затем выполняется разбиение.

5.5. Стили

компонент импортирует только собственный CSS Module;
CSS Module не передаётся другому компоненту через props;
глобальные стили содержат только fonts, reset, tokens и доказанно общие utilities;
повторяемые цвета, spacing, radius, shadow и z-index получают семантические tokens;
уникальное иллюстративное значение может остаться локальным;
новые hardcoded brand colors запрещены;
!important запрещён;
focus-visible state обязателен для интерактивных элементов;
prefers-reduced-motion обязателен для значимой анимации.

5.6. Тесты

тест проверяет наблюдаемое поведение, а не внутреннюю реализацию;
query priority Testing Library: role/name → label → text → test id;
data-testid используется только при отсутствии устойчивой семантики;
каждый исправленный дефект сначала получает падающий regression test;
pure model/lib code покрывается минимум на 95% lines/functions и 90% branches;
общий threshold: 85% lines/statements, 90% functions, 80% branches;
на новых и изменённых строках coverage не ниже 90%;
accessibility проверяется автоматикой и отдельными keyboard-сценариями;
visual test не заменяет semantic или behavioral assertion.

6. Этап 0 — неизменяемый baseline

Перед первой реализационной правкой:

Зафиксировать git status --short и не смешивать пользовательские изменения.
Выполнить npm ci в чистом CI окружении.
Выполнить npm run check, npm run test:e2e и git diff --check.
Сохранить число unit/component/e2e tests и список snapshots.
Зафиксировать production bundle sizes.
Сохранить representative screenshots: mobile 390, tablet 768, desktop 1440.
Проверить прямое открытие /, /partners/, /careers/.

Gate 0

исходный git status записан;
npm run check — PASS;
17 текущих Vitest tests — PASS;
96 текущих Playwright tests — PASS;
build и prerender — PASS;
screenshots проходят без update;
bundle baseline записан;
известные ошибки из раздела 1 воспроизводятся отдельными probe/tests.

При красном baseline сначала документируется исходная ошибка. Рефакторинг поверх необъяснённого FAIL не начинается.

7. Этап 1 — regression tests до исправлений

Добавить тесты, которые до исправления должны падать:

при открытии focus перемещается внутрь dialog;
активный элемент является потомком [role="dialog"];
Tab с последнего элемента переходит на первый внутри dialog;
Shift+Tab с первого элемента переходит на последний внутри dialog;
focus не попадает на logo, header CTA, main или footer;
внутри dialog есть видимая кнопка закрытия с accessible name;
Escape закрывает dialog и возвращает focus на trigger;
закрытие по кнопке, backdrop и navigation link возвращает ожидаемое состояние;
закрытый overlay не находится в accessibility tree и tab order;
повторное открытие не создаёт дубликатов listeners или portal nodes.

7.2. Architecture probes

Добавить lint fixtures или programmatic tests, доказывающие, что CI отклоняет:

shared → pages через alias и через relative import;
shared → features/widgets/app;
features → pages/widgets/app;
widgets → pages/app;
импорт внутреннего feature-файла в обход public API;
cross-page import;
любой parent-relative import ../....

7.3. Calculator contracts

Добавить тесты:

каждый ModuleId имеет self/cloud pricing;
pricing не содержит orphan module id;
неизвестный module id невозможно передать на уровне TypeScript;
допустимые months — только 1 | 6 | 12;
employees/computers/servers — целые числа в заданном диапазоне;
недопустимые значения не попадают в расчёт и estimate;
ни одна корректная конфигурация не возвращает NaN, Infinity или отрицательную итоговую цену.

Gate 1

новые regression tests воспроизводят каждую проблему;
каждый тест красный по ожидаемой причине;
существующие тесты не изменены и не ослаблены;
snapshots не обновлены;
git diff --check — PASS.

Сохранить trigger в SiteHeader, но использовать его только для открытия.
Разместить визуально доступную кнопку закрытия внутри dialog DOM subtree.
При открытии перемещать focus на осмысленный элемент внутри dialog.
Focus trap должен вычислять только видимые и доступные descendants dialog.
Всё вне активного dialog должно быть inert; предыдущее значение inert необходимо сохранить и восстановить.
При закрытии восстановить body overflow, padding и focus на исходный trigger.
Cleanup должен быть корректен при unmount и React StrictMode remount.
Portal/client-ready механизм переписать без синхронного setState в effect и без hydration mismatch.
Сохранить текущую геометрию, цвета и responsive-поведение overlay.

8.2. Полный React lint

Подключить flat recommended preset установленного eslint-plugin-react-hooks.
Удалить ручное дублирование правил, уже входящих в preset.
Исправить все diagnostics без disable-комментариев.
Добавить отдельную проверку отсутствия hydration warnings в Playwright.
Проверить работу StrictMode в dev и hydration production build.

Gate 2

полный React recommended preset — 0 errors, 0 warnings;
все navigation regression tests из Gate 1 — PASS;
Tab/Shift+Tab остаются внутри dialog во всех шести viewport;
Escape и кнопка закрытия возвращают focus на trigger;
внешняя страница inert, scroll заблокирован и полностью восстанавливается;
нет hydration warning, pageerror и console.error;
visual snapshots navigation — PASS без необъяснённого update;
npm run check — PASS;
релевантные Playwright tests — PASS.

9. Этап 3 — реальные архитектурные границы

Переименовать общий слой components в widgets, потому что header/footer — составные блоки страницы, а не атомарные shared UI-компоненты.
Выделить features/navigation-theme как самостоятельный механизм темы header.
Убрать зависимость calculator от navigation widget: page-specific CalculatorSection владеет NavThemeRegion, feature Calculator — только состоянием, формой, расчётом и quote.
Перенести cross-layer imports на @/...; оставить ./... внутри директории.
Запретить parent-relative imports ESLint-правилом.
Настроить ограничения из таблицы раздела 4 для всех способов импорта.
Добавить локальные public API для site-header, site-footer, navigation-theme, calculator.
Добавить cycle detection в CI; допустимое число циклов — 0.
Обновить docs/architecture.md и CONTRIBUTING.md одновременно с кодом.

Gate 3

все architecture fixtures из Gate 1 отклоняются линтером;
фактический import graph соответствует таблице раздела 4;
parent-relative imports отсутствуют;
cross-page imports отсутствуют;
deep imports в feature/widget internals отсутствуют;
циклических зависимостей — 0;
orphan exports и orphan files — 0;
документация совпадает с фактическим деревом;
npm run typecheck, npm run lint, npm run test, npm run build — PASS.

10. Этап 4 — типобезопасные данные и единый site config

10.1. Calculator domain

Ввести ModuleId как литеральный union, выведенный из единого каталога модулей либо объявленный один раз.
Связать pricing с ModuleId через satisfies Record<ModuleId, ...>.
Сделать Hosting, Installation, BillingPeriod и Adjustment закрытыми доменами.
Вынести parsing/clamping input values в чистые функции модели.
Удалить fallback ?? 0 для отсутствующей цены: это ошибка конфигурации, а не бесплатный модуль.
Проверять целые min/max значения в модели, а не только HTML attributes.
Разделить calculation, validation и estimate formatting.

10.2. Site identity и SEO

Создать shared/config/site.ts с названием, legal name, base URL, контактами, social links и текущим copyright policy.
Создать типизированный page metadata config.
Генерировать или проверять canonical, Open Graph, Twitter и JSON-LD из этого config во время build.
Удалить ручные копии телефона, email, social URL и Organization JSON-LD из HTML shells.
Build должен падать при невалидном JSON-LD, несовпадении canonical route или отсутствии обязательного metadata field.

Gate 4

11. Этап 5 — SEO уровня production

11.1. Принцип и ожидаемый результат

SEO не может гарантировать первое место Google: итоговая позиция зависит от конкуренции, истории домена, качества и известности продукта, внешних упоминаний и алгоритмов поисковой системы. Технический результат этапа — устранить все контролируемые препятствия и создать сильнейшие доступные сигналы релевантности, доверия и идентичности BELF.

Целевые результаты:

по брендовым запросам BELF, Белф, BELF Uzbekistan, belf.uz, BELF Proctor официальный сайт однозначно идентифицируется как основной источник о продукте;
для каждого подтверждённого продуктового поискового намерения существует одна лучшая, содержательная и индексируемая страница;
Google получает полностью отрендеренный HTML, согласованные canonical, sitemap, metadata и structured data без необходимости угадывать назначение страницы;
органический трафик оценивается не только позициями, но и qualified clicks, CTR, заявками и долей брендовой/небрендовой видимости;
рост достигается people-first содержанием и реальной репутацией, без манипулятивных SEO-техник.

11.2. SEO baseline и исследование спроса

До изменения структуры или текстов:

Подключить и подтвердить domain property в Google Search Console.
Зафиксировать индексирование через URL Inspection и отчёт Pages.
Выгрузить последние доступные данные Search Console: queries, pages, countries, devices, impressions, clicks, CTR и average position.
Проверить фактическую выдачу в целевых регионах и языках для брендовых написаний, транслитераций и опечаток.
Собрать семантическое ядро из реальных формулировок потенциальных клиентов, Search Console, интервью продаж и конкурентной выдачи.
Разделить запросы по намерению:
- узнать категорию решения;
- решить конкретную операционную проблему;
- сравнить способы или продукты;
- проверить функции, безопасность, размещение и интеграции;
- узнать цену и условия внедрения;
- найти именно BELF;
- стать партнёром или специалистом по внедрению.
Для каждого кластера зафиксировать аудиторию, ситуацию, главный вопрос, доказательства, целевую страницу и conversion event.
Не утверждать список ключевых слов до подтверждения спроса и релевантности.

SEO Gate 5.1 — baseline

Search Console domain property подтверждён;
XML sitemap отправлен и прочитан Google;
все текущие canonical URL проверены через URL Inspection;
baseline брендовых и небрендовых queries сохранён;
определены целевые регионы и реальные языки продукта;
каждому keyword cluster назначено одно поисковое намерение и одна primary page;
в semantic map нет кластеров без связи с реальной возможностью BELF;
baseline содержит дату, источник и не смешивает desktop/mobile или разные страны без пометки.

11.3. Поисковая информационная архитектура

Текущих трёх страниц недостаточно, чтобы полноценно отвечать на широкий набор продуктовых запросов. Новые страницы создаются только под самостоятельное намерение и реальную полезность, а не под перестановки ключевых слов.

Предварительная карта, которую необходимо подтвердить исследованием:

/
  BELF: категория продукта, основная ценность и выбор следующего шага

/platform/
  единая платформа, роли, доступ, модули и интеграции

/modules/<module-slug>/
  отдельная подтверждённая задача и возможности конкретного модуля

/proctoring/
  рабочий контекст, события, приватность, ограничения и сценарии использования

/deployment/
  self-hosted и cloud: требования, различия, безопасность и внедрение

/pricing/
  модель расчёта, состав цены, условия и калькулятор

/security/
  архитектура защиты, хранение, доступ и подтверждённые меры

/integrations/
  реальные поддерживаемые интеграции и порядок подключения

/use-cases/<verified-use-case>/
  конкретная роль/задача, процесс, результат и ограничения

/customers/<verified-case>/
  проверяемый кейс с разрешёнными фактами и доказательствами

/docs-or-help/
  индексируемые ответы на вопросы выбора и внедрения, если они полезны до покупки

/partners/
/careers/
/about/
/contact/

Правила:

URL короткий, стабильный, человекочитаемый и написан в одном выбранном языке;
один URL соответствует одному основному намерению;
canonical указывает на саму страницу;
важная страница доступна обычной HTML-ссылкой максимум за три перехода от главной;
orphan pages запрещены;
одинаковые страницы по городам, отраслям или языкам без уникальной пользы запрещены;
filter/query/hash URL не индексируются как отдельные контентные страницы;
удалённая страница получает релевантный 301, а не redirect на главную;
отсутствующий URL возвращает настоящий HTTP 404;
sitemap содержит только canonical indexable URLs с кодом 200;
lastmod меняется только при существенном изменении страницы.

SEO Gate 5.2 — информационная архитектура

утверждена карта intent → primary URL → CTA → evidence;
keyword cannibalization отсутствует;
doorway, duplicate и orphan pages — 0;
глубина перехода к priority pages — не более 3;
internal links используют canonical URLs и описательный anchor text;
каждый новый маршрут добавлен в prerender, sitemap, navigation context и e2e crawl;
каждый несуществующий маршрут возвращает корректный 404;
redirect chains и loops — 0.

11.4. Архитектура сообщений и on-page SEO

Каждая поисковая страница проектируется для конкретной аудитории и этапа решения. Порядок сообщения:

релевантность → ценность → механизм → доказательство → ограничения → действие

Обязательные требования:

Первый экран отвечает: что это, для кого, какую задачу решает и какой следующий шаг доступен.
Один уникальный <title> точно называет тему и BELF; длина не оптимизируется механически, смысл важнее числа символов.
Один видимый h1 соответствует главному намерению страницы; уровни h2–h3 образуют логичную структуру без пропусков ради дизайна.
Meta description уникально и честно описывает пользу страницы; она не повторяет title и не содержит неподтверждённых обещаний.
Основные термины используются естественно в title, h1, вводном тексте, ссылках и alt только там, где помогают человеку.
Сильное утверждение сопровождается рядом расположенным доказательством: механизмом, демонстрацией, документом, разрешённым кейсом или точным ограничением.
Нельзя придумывать ROI, проценты эффективности, отзывы, число клиентов, соответствие стандартам или превосходство над конкурентами.
CTA соответствует готовности посетителя: изучить модуль, посмотреть пример, рассчитать цену, обсудить внедрение.
Изображения получают описательные filename/alt, если несут содержание; декоративные изображения имеют пустой alt.
Видео получает индексируемое название, описание, poster и transcript, если оно важно для страницы.
FAQ создаётся из реальных вопросов клиентов; FAQ structured data добавляется только если текущая документация Google делает страницу подходящей для соответствующего rich result.
Дата обновления показывается только для материалов, где свежесть важна, и меняется при содержательном обновлении.

Контентные типы для устойчивого роста:

подробные страницы модулей и deployment;
документация по требованиям, внедрению и интеграциям;
проверяемые кейсы с исходной ситуацией, процессом, результатом и ограничениями;
сравнения подходов, основанные на проверяемых критериях, а не на нападках на конкурентов;
glossary только для терминов, которые действительно ищет и использует аудитория;
статьи-ответы на сложные вопросы покупателей, если ответ нельзя качественно разместить на основной product page.

SEO Gate 5.3 — content quality

11.5. Brand/entity SEO для запроса BELF

Зафиксировать одно основное имя BELF и допустимые варианты написания.
На главной ясно связать BELF, категорию продукта, разработчика Digital Revolution Makers и официальный домен belf.uz.
Создать содержательные /about/ и /contact/ с проверяемыми сведениями о компании и едиными контактами.
Размещать Organization JSON-LD только на главной или основной странице организации; использовать постоянный @id.
Связать Organization, WebSite, SoftwareApplication и WebPage через стабильные @id, publisher, provider, isPartOf и about.
Указать только реальные sameAs, logo, contactPoint, address и legal data.
Проверить единообразие названия, логотипа, описания и URL на официальных социальных профилях и авторитетных отраслевых площадках.
Получать внешние упоминания через реальные партнёрства, кейсы, публикации и полезные материалы; покупка ссылок запрещена.
Добавить WebSite/site name signals, favicon и согласованные Open Graph данные, чтобы официальный результат визуально распознавался.
Ежемесячно проверять branded SERP на конкурирующие сущности, неверные title, sitelinks и неофициальные страницы.

SEO Gate 5.4 — бренд

главная однозначно объясняет, что такое BELF;
официальный домен, бренд и разработчик связаны видимым текстом и schema;
Organization существует в одном согласованном варианте;
logo/favicon доступны Googlebot, индексируемы и соответствуют бренду;
все sameAs ведут на официальные подтверждённые профили;
NAP/contact data согласованы на сайте и внешних официальных профилях;
запросы BELF, Белф, BELF Proctor, belf.uz отслеживаются отдельно;
целевой внешний KPI: официальный сайт занимает позицию 1 по однозначным брендовым запросам в целевом регионе после периода переиндексации;
отсутствие позиции 1 не маскируется техническим PASS: создаётся отдельная гипотеза по данным Search Console и выдачи.

11.6. Technical SEO и structured data

Для каждого indexable URL build обязан проверять:

HTTP 200, валидный lang, viewport и charset;
уникальные server-rendered title, meta description и self-canonical;
один canonical, согласованный с sitemap, internal links и redirect policy;
robots разрешает индексирование, если страница предназначена для поиска;
важный текст и ссылки присутствуют в prerendered HTML до выполнения JS;
heading outline, link names и image alt валидны;
Open Graph и Twitter metadata используют абсолютные доступные URLs;
social image имеет корректный MIME type, размеры и content;
JSON-LD синтаксически валиден и соответствует видимому содержанию;
Organization, WebSite, SoftwareApplication, BreadcrumbList и другие типы добавляются только на подходящие страницы;
fake review/rating, неподтверждённый Offer и нерелевантная schema запрещены;
sitemap генерируется из page registry и не редактируется вручную;
robots.txt содержит абсолютный sitemap URL и не блокирует CSS, JS, изображения или indexable routes;
ссылки доступны как <a href>, а не только через click handler;
отсутствуют broken internal links, mixed content и redirect chains;
mobile и desktop получают эквивалентные content и metadata;
hreflang добавляется только при существовании полноценной переведённой версии, содержит reciprocal links и корректный x-default.

Добавить автоматический SEO audit, который сканирует production preview, а не исходные шаблоны.

SEO Gate 5.5 — technical

11.7. Производительность и Core Web Vitals

SEO performance gate измеряется отдельно для mobile и desktop. Основным результатом являются field data на 75-м процентиле; Lighthouse используется как лабораторная защита до накопления field data.

Обязательные пороги:

LCP ≤ 2.5 s;
INP ≤ 200 ms;
CLS ≤ 0.1;
TTFB ≤ 0.8 s как внутренний диагностический бюджет;
изображения выше fold имеют заданные размеры и не вызывают layout shift;
основной LCP asset не lazy-load, имеет корректный priority/preload только при доказанной необходимости;
below-fold media lazy-load;
font loading не скрывает содержимое и не создаёт заметный CLS;
third-party scripts не добавляются без performance budget и consent review.

SEO Gate 5.6 — performance

Lighthouse SEO = 100 на всех indexable page templates;
Lighthouse median из трёх mobile запусков: Performance ≥ 90;
field Core Web Vitals имеют статус Good на 75-м процентиле после достаточного периода сбора данных;
LCP, INP и CLS соответствуют указанным порогам;
новый route не превышает bundle budgets Final Quality Gate;
изображения имеют width/height, responsive sources и подходящий формат;
regression budget блокирует ухудшение LCP/CLS/bundle в CI.

11.8. Измерение результата и непрерывное улучшение

Технический gate и внешний SEO outcome разделяются. Код можно признать технически корректным после прохождения audit, но нельзя объявлять SEO успешным без данных поисковой выдачи.

Отслеживать еженедельно в первые восемь недель, затем ежемесячно:

indexed canonical pages и причины исключения;
crawl errors, manual actions и security issues;
брендовые и небрендовые impressions/clicks/CTR/average position;
долю целевых запросов в top 3, top 10 и top 20;
landing pages с impressions, но низким CTR;
queries с позицией 4–20 и достаточными impressions;
органические CTA, qualified leads и конверсию landing pages;
Core Web Vitals field data;
branded SERP и корректность site name/logo/sitelinks.

Цели фиксируются после baseline, а не придумываются заранее. Для каждой цели указываются исходное значение, целевой период, рынок и владелец. Изменение оценивается минимум после полного цикла crawl/index/re-ranking; краткосрочные колебания не считаются доказательством.

SEO Gate 5.7 — post-release outcome

Search Console не показывает manual actions или security issues;
все priority pages проиндексированы с ожидаемым Google-selected canonical;
брендовые queries имеют отдельный dashboard;
небрендовые clusters имеют измеримые impressions и landing pages;
органические conversion events проверены end-to-end;
для страниц с падением зафиксированы данные и гипотеза, а не выполнено бесконтрольное переписывание;
monthly SEO report содержит изменения, причины, риски и следующий эксперимент;
контент без показов/ценности улучшается, объединяется или удаляется только после анализа и корректной redirect/canonical стратегии.

Gate 5 — SEO release

SEO Gates 5.1–5.6 — PASS до production release;
SEO Gate 5.7 имеет настроенный мониторинг и владельца;
people-first content и Google Search Essentials соблюдены;
spam/doorway/keyword-stuffing techniques отсутствуют;
site config, page registry, sitemap, metadata и structured data имеют один источник истины;
SEO audit является blocking частью CI;
post-release KPI не выдаются за гарантированный результат алгоритма.

11.9. Нормативные источники SEO

Реализацию и review сверять с актуальными официальными источниками:

Перед реализацией перепроверить даты обновления документации и доступность конкретных rich result: поддержка Google меняется со временем.

12. Этап 6 — компоненты и читаемость

Миграция выполняется по одному владельцу. Сначала перенос без изменения поведения, затем отдельным изменением — упрощение.

SiteHeader владеет шапкой и trigger;
NavigationDialog владеет modal semantics, portal и focus lifecycle;
navigation-dialog.model владеет поиском focusable elements и переходами;
NavigationGroups только отображает группы ссылок;
NavigationContact только отображает контактный CTA;
дочерние компоненты импортируют собственный CSS либо остаются приватными частями одного файла; styles через props не передаётся.

12.2. Home

выделить SignalStrip из HeroSection с собственным JSX и CSS Module;
сохранить DashboardPreview самостоятельным визуальным компонентом;
HeroSection оставить композицией hero content и preview;
разделить ClosingSections на CustomSection и ContactSection, если они имеют разные anchors, данные и стили;
page component сохраняет только порядок секций.

12.3. Calculator

page CalculatorSection владеет заголовком, theme region и layout секции;
feature Calculator владеет состоянием и orchestration;
CalculatorForm разделить на именованные private blocks только потому, что каждый fieldset имеет самостоятельный набор данных и событий: HostingFieldset, ScaleFieldset, ModulesFieldset, InstallationFieldset;
повторяемые radio options описать типизированными данными, не дублировать JSX;
CalculatorQuote остаётся одним компонентом, пока не превышает thresholds;
бизнес-расчёт и validation не находятся в JSX.

12.4. Partners и careers

сохранить page-specific формы рядом со страницами;
вынести form serialization/navigation side effect в testable hook или action;
вынести Client и registry state из UI-файла в предметную модель;
runtime-валидировать client registry JSON на входной границе;
объединять partners/careers footer только если появился стабильный общий контракт; визуально похожий JSX сам по себе не является основанием;
не создавать универсальный Section, если он скрывает семантику и anchors.

12.5. Design tokens

проинвентаризировать повторяющиеся цвета и размеры;
создать только семантические tokens: surface, text, border, brand, feedback, overlay, focus ring;
заменять hardcoded values небольшими партиями с visual regression после каждой;
не создавать token для уникального декоративного значения.

Gate 6

13. Final Quality Gate

Работа завершена только при одновременном PASS всех пунктов.

13.1. Статика и форматирование

npm run format:check — 0 differences;
npm run lint — 0 errors, 0 warnings;
полный React recommended preset включён, а не запускается отдельной пробой;
npm run lint:css — 0 errors, 0 warnings;
npm run typecheck — PASS с усиленными compiler options;
git diff --check — PASS;
нет eslint-disable, @ts-ignore, @ts-nocheck, необоснованного any и новых !important;
dependency cycles — 0;
orphan source files/exports — 0.

13.2. Unit и component tests

все regression tests добавлены до исправления и теперь PASS;
все pure models/utils имеют ≥95% lines/functions и ≥90% branches;
global coverage: ≥85% lines/statements, ≥90% functions, ≥80% branches;
changed-line coverage ≥90%;
тесты проходят минимум три последовательных запуска без flaky retry;
fake timers используются для timer-dependent component tests;
rejected promises и console errors приводят к FAIL.

13.3. Accessibility

axe-проверка трёх маршрутов — 0 serious/critical violations;
axe-проверка открытого navigation dialog — 0 violations;
весь сайт проходим только клавиатурой;
focus всегда видим;
modal focus не покидает dialog;
после закрытия focus возвращается на trigger;
interactive elements имеют role/name/state;
reduced-motion режим проверен;
таблица registry имеет корректные row/header/cell semantics.

13.4. Browser и SSR

13.5. Visual regression

96 существующих Playwright scenarios — PASS;
новые keyboard/accessibility scenarios — PASS;
navbar closed/open screenshots — PASS для 3 routes × 6 viewport;
partners/careers full-page screenshots — PASS для 2 routes × 6 viewport;
home получает full-page baseline для 6 viewport;
maxDiffPixelRatio не выше 0.003;
snapshots не обновлялись автоматически;
каждое намеренное visual изменение просмотрено и записано в отчёт.

13.6. Производительность и bundle

initial route JavaScript ≤100 KiB gzip для каждого маршрута;
общий shared JavaScript ≤85 KiB gzip;
новый runtime dependency имеет записанное обоснование;
отсутствуют duplicate package versions без причины;
Lighthouse median из трёх запусков: Performance ≥90, Accessibility ≥95, Best Practices ≥95, SEO =100;
production dependencies: 0 high/critical security advisories;
изображения и шрифты не загружаются повторно без необходимости.

13.7. Архитектура и читаемость

13.8. SEO

13.9. CI и поставка

npm run quality локально запускает тот же обязательный набор, что и CI;
CI использует npm ci и закреплённую поддерживаемую версию Node;
deploy зависит от static, unit, accessibility, e2e и build gates;
test/Playwright reports загружаются при FAIL;
snapshot update не выполняется в CI;
исходные пользовательские изменения сохранены;
итоговый git status --short приложен к отчёту;
commit, push и deploy выполнены только при отдельном разрешении.

14. Обязательные команды

Итоговый публичный интерфейс проверок должен быть таким:

npm run format:check
npm run lint
npm run lint:css
npm run typecheck
npm run test
npm run test:coverage
npm run test:a11y
npm run test:e2e
npm run test:seo
npm run test:architecture
npm run check:cycles
npm run check:bundle
npm run check:links
npm run check:lighthouse
npm run build
npm run quality

npm run quality обязан запускать все blocking checks либо быть CI-агрегатором, который гарантирует тот же набор. Команды из документации не могут ссылаться на несуществующий script.

15. Порядок поставки

Рекомендуемые независимые изменения:

Regression tests navigation и architecture probes.
Исправление modal navigation и полный React lint preset.
Alias policy, реальные boundary rules и cycle detection.
Calculator domain types и validation.
Site config, page registry и генерация metadata.
Перемещение components → widgets и public API.
Разделение home/navigation/calculator компонентов.
SEO baseline, Search Console и semantic map без изменения страниц.
Technical SEO audit, link crawler, sitemap и structured data validation.
Priority landing pages по одной подтверждённой search intent за итерацию.
Brand/entity signals, about/contact и подтверждённые доказательства.
Design tokens небольшими визуально проверяемыми партиями.
Coverage, axe, bundle, SEO и Lighthouse gates.
Финальная синхронизация документации и CI.

Каждый пункт должен иметь собственный зелёный gate и не смешиваться с соседним, если это затрудняет review или локализацию регрессии.

16. Стоп-условия

Текущий этап немедленно останавливается, если:

меняется screenshot без заранее описанной причины;
возникает hydration warning, pageerror, console.error или overflow;
тест становится зелёным только после ослабления assertion;
для продолжения требуется disable линтера, any, @ts-ignore или !important;
меняется цена, mailto body, route, anchor или SEO-смысл;
появляется новая cross-layer или циклическая зависимость;
обнаружено пересечение с неизвестным пользовательским изменением;
новый компонент не имеет самостоятельной ответственности;
новый dependency добавляется без письменного обоснования;
SEO-страница создаётся без подтверждённого намерения или уникальной пользы;
для роста предлагаются keyword stuffing, doorway pages, скрытый текст, покупные ссылки или неподтверждённые claims;
structured data не соответствует видимому содержанию страницы.

При остановке фиксируются точный файл, сценарий, ожидаемое и фактическое поведение. Snapshot и baseline не обновляются до устранения причины.

17. Формат отчёта после каждого этапа

Этап
- цель;
- изменённые владельцы и файлы;
- какие обязанности разделены;
- какие старые файлы удалены.

Проверки
- каждая команда: PASS/FAIL;
- количество unit/component/e2e tests;
- coverage;
- routes и viewport;
- visual comparison без update: PASS/FAIL.

Архитектура
- новые/изменённые зависимости;
- результат boundary fixtures и cycle detection;
- подтверждение public API.

SEO
- изменённые URLs и search intents;
- title/description/canonical/schema validation;
- indexability, internal links и sitemap;
- Search Console baseline/outcome без обещаний позиции;
- Core Web Vitals и Lighthouse.

Визуальная и поведенческая дельта
- отсутствует;
- либо точное согласованное изменение.

Риски и остаток
- что не выполнено;
- временные compatibility-решения;
- следующий безопасный этап.

Git
- git status --short;
- commit/push/deploy status.

18. Master-checklist всех работ

Этот раздел — единая точка контроля исполнения. Детальные требования и пороги берутся из соответствующих разделов выше, но завершение всей работы определяется только этим checklist.

18.1. Правила ведения checklist

18.2. Baseline и защита исходного поведения

18.3. Regression tests до исправлений

18.5. Архитектурные границы

18.6. TypeScript и calculator domain

18.7. Единый site config и metadata

IMPL-META-01 Создать единый shared/config/site.ts.
IMPL-META-02 Перенести туда brand, legal identity, base URL, контакты и social links.
IMPL-META-03 Создать типизированный page registry/metadata config.
IMPL-META-04 Генерировать title, description, canonical, Open Graph и Twitter metadata.
IMPL-META-05 Генерировать JSON-LD из того же источника.
IMPL-META-06 Удалить ручные дубликаты контактов и Organization data.
IMPL-META-07 Добавить build validation metadata и JSON-LD.
IMPL-META-08 Проверить согласованность UI, mailto, metadata и schema.
IMPL-META-GATE Metadata-часть Gate 4 пройдена полностью.

18.8. SEO baseline и стратегия

18.9. SEO-информационная архитектура и контент

18.10. Brand/entity и technical SEO

18.11. Компонентная декомпозиция и стили

18.12. Coverage, accessibility, performance и SEO automation

18.13. Документация и CI

18.14. Финальная верификация реализации

18.15. Post-release SEO и окончательное закрытие

Эти пункты требуют production deploy, доступа к Search Console и времени на crawl/index/re-ranking. До отдельного разрешения на deploy они остаются unchecked и не могут быть выданы за выполненные.

18.16. Условие завершения

CLOSE-01 Все пункты BASE-*, TEST-*, IMPL-* и VERIFY-* отмечены с доказательствами.
CLOSE-02 Все Gate 0–6 и Final Quality Gate пройдены.
CLOSE-03 Количество unchecked blocking implementation items равно нулю.
CLOSE-04 Итоговый отчёт перечисляет выполненное, команды, тесты, coverage, visual/behavior delta, SEO state, риски и git status.
CLOSE-05 Если production deploy разрешён, все SEO-POST-* закрыты; если не разрешён, implementation task закрывается только как «готово к deploy», а общий SEO-цикл остаётся активным и не называется завершённым.
CLOSE-06 Работа объявляется полностью завершённой только при нулевом числе unchecked пунктов во всём Master-checklist.

1. Статус документа​

2. Цели​

3. Неприкосновенные ограничения​

4. Целевая архитектура​

4.1. Слои​

4.2. Целевая структура​

4.3. Правило выделения компонента​

5. Обязательные стандарты кода​

5.1. React​

5.2. TypeScript​

5.3. Имена и файлы​

5.4. Ограничения сложности​

5.5. Стили​

5.6. Тесты​

6. Этап 0 — неизменяемый baseline​

Gate 0​

7. Этап 1 — regression tests до исправлений​

7.1. Navigation accessibility​

7.2. Architecture probes​

7.3. Calculator contracts​

Gate 1​

8. Этап 2 — modal navigation и React rules​

8.1. Исправление modal navigation​

8.2. Полный React lint​

Gate 2​

9. Этап 3 — реальные архитектурные границы​

Gate 3​

10. Этап 4 — типобезопасные данные и единый site config​

10.1. Calculator domain​

10.2. Site identity и SEO​

Gate 4​

11. Этап 5 — SEO уровня production​

11.1. Принцип и ожидаемый результат​

11.2. SEO baseline и исследование спроса​

SEO Gate 5.1 — baseline​

11.3. Поисковая информационная архитектура​

SEO Gate 5.2 — информационная архитектура​

11.4. Архитектура сообщений и on-page SEO​

SEO Gate 5.3 — content quality​

11.5. Brand/entity SEO для запроса BELF​

SEO Gate 5.4 — бренд​

11.6. Technical SEO и structured data​

SEO Gate 5.5 — technical​

11.7. Производительность и Core Web Vitals​

SEO Gate 5.6 — performance​

11.8. Измерение результата и непрерывное улучшение​

SEO Gate 5.7 — post-release outcome​

Gate 5 — SEO release​

11.9. Нормативные источники SEO​

12. Этап 6 — компоненты и читаемость​

12.1. Navigation​

12.2. Home​

12.3. Calculator​

12.4. Partners и careers​

12.5. Design tokens​

Gate 6​

13. Final Quality Gate​

13.1. Статика и форматирование​

13.2. Unit и component tests​

13.3. Accessibility​

13.4. Browser и SSR​

13.5. Visual regression​

13.6. Производительность и bundle​

13.7. Архитектура и читаемость​

13.8. SEO​

13.9. CI и поставка​

14. Обязательные команды​

15. Порядок поставки​

16. Стоп-условия​

17. Формат отчёта после каждого этапа​

18. Master-checklist всех работ​

18.1. Правила ведения checklist​

18.2. Baseline и защита исходного поведения​

18.3. Regression tests до исправлений​

18.4. Modal navigation и React​

18.5. Архитектурные границы​

18.6. TypeScript и calculator domain​

18.7. Единый site config и metadata​

18.8. SEO baseline и стратегия​

18.9. SEO-информационная архитектура и контент​