# Готовность к проектированию frontend

Этот документ определяет обязательный результат до начала проектирования и
разработки пользовательского интерфейса. Он дополняет
[план frontend поисковой СПС](frontend-search-sps-plan.md): тот описывает MVP и
спринты frontend, этот — критерий перехода к ним.

## Правило перехода

Проектирование frontend начинается, когда выполнены все обязательные пункты
этого плана и пройден финальный readiness gate. До этого не создаются
`frontend/`, макеты, UI-компоненты или mock-данные, заменяющие неготовый
backend-контракт.

Вне этого этапа остаются аккаунты, уведомления, RAG, судебная практика и
внешние коммерческие сервисы.

## 1. Данные и поисковый индекс

### Результат

В локальном OpenSearch доступен воспроизводимо собранный корпус актуальных
редакций ЦБД Минюста КР, пригодный для поиска на русском и кыргызском языках.

### Обязательные работы

1. Подтвердить для каждого индексируемого документа наличие канонических
   реквизитов: код, редакция, язык, статус, тип, орган, дата, номер, название
   и ссылка на официальный источник.
2. Зафиксировать правила для документов без текста и одноязычных редакций:
   они не скрываются и не получают выдуманный перевод.
3. Проверить versioned-индекс, mapping, анализаторы RU/KY, полноту актуальных
   редакций и процедуру безопасной переиндексации с переключением alias.
4. Описать и выполнить воспроизводимый сценарий обновления:
   выгрузка → нормализация → новый индекс → проверка → переключение alias.

### Критерий приёмки

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

## 2. Relevance set и качество поиска

### Результат

Есть замороженный набор `relevance set v1` из 50 практических запросов:
минимум 25 на русском и 25 на кыргызском языках.

### Обязательные работы

1. Заполнить рабочую копию из `backend/search/relevance-set-v1.template.json`
   естественными формулировками пользователей и подтверждёнными
   `document_code` релевантных действующих актов.
2. Проверить каждый запрос по официальной ЦБД и локальному индексу; не
   включать запросы без установленного эталонного результата.
3. Провести независимую вторую проверку языка, формулировки и полного списка
   кодов. Спорные результаты не включать до согласования.
4. После проверки сохранить неизменяемую копию набора и baseline
   `Recall@10`/`MRR@10`; новые правила ранжирования оценивать только сравнением
   с этим baseline.
5. Отдельно проверить распространённые сокращения, опечатки и запросы о
   практическом действии. Правило принимается, только если улучшает
   подтверждённые запросы и не создаёт ложных срабатываний в негативных
   сценариях.

### Критерий приёмки

Оценщик проходит на полном наборе, выводит метрики и выдачу для каждого
запроса; baseline и результаты его повторного запуска воспроизводимы.

## 3. Справочники и контракт API

### Результат

Frontend получает все юридически значимые данные через версионированный
OpenAPI-контракт, а не реконструирует их из текста фрагментов.

### Обязательные работы

1. Утвердить справочники v1: типы документов, органы принятия, статусы,
   уровни действия и темы. Для каждого значения определить стабильный код и
   подписи RU/KY.
2. Реализовать и описать OpenAPI для:
   - `GET /search` — запрос, язык, фильтры, сортировка, серверная пагинация,
     выдержка и подсветка;
   - `GET /search/filters` — допустимые значения фильтров;
   - `GET /documents/{code}` — карточка актуального документа;
   - `GET /documents/{code}/editions` и
     `GET /documents/{code}/editions/{edition}` — редакции и их содержимое.
3. Зафиксировать единые ответы для пустой выдачи, неизвестного документа,
   недоступной редакции и ошибки upstream; для документов с одним языком
   вернуть доступные языки явно.
4. Добавить контрактные и интеграционные проверки API на локальном OpenSearch:
   поиск, фильтры, пагинация, сортировка, документ, редакции и одноязычные
   акты.

### Критерий приёмки

OpenAPI опубликован вместе с backend, тестовый клиент получает реальные данные
по всем endpoint без mock-слоя, а результаты поиска открывают актуальный
документ и выбранную редакцию.

## 4. Финальный readiness gate

Перед началом frontend выполнить и зафиксировать один сквозной сценарий:

1. Обновить корпус из официальной ЦБД.
2. Нормализовать данные и собрать новый versioned-индекс.
3. Прогнать проверки индекса и relevance baseline.
4. Переключить alias на проверенный индекс.
5. Выполнить API-сценарии поиска, фильтрации, просмотра документа и редакции
   на RU, KY и одноязычном документе.

Gate считается пройденным, если все проверки успешны, зафиксированы версии
backend и индекса, опубликованы известные ограничения и назначен ответственный
за юридическую проверку relevance set.

## Порядок issues

1. Собрать и независимо проверить relevance set v1.
2. Завершить проверку полноты данных и воспроизводимую переиндексацию с alias.
3. Утвердить справочники v1.
4. Реализовать OpenAPI и интеграционные проверки.
5. Провести финальный readiness gate и только затем открыть задачу на
   проектирование frontend.