CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Не выпущено
 
+- Добавлен roadmap готовности данных, поиска и API перед проектированием
+  frontend.
 - Исправлена выдача для явных запросов об открытии ОсОО и ЖЧК: первыми
   показываются действующие положение о регистрации и закон о хозяйственных
   товариществах и обществах.

docs/README.md

@@ -6,6 +6,8 @@
   правила работы с данными.
 - [План frontend поисковой СПС](product/frontend-search-sps-plan.md) — границы
   MVP, зависимости и спринты.
+- [Готовность к проектированию frontend](product/frontend-design-readiness-plan.md) —
+  обязательные работы и критерии перехода к frontend.
 - [Задание по нормализации документов](product/minjust-document-normalization-agent-task.md) —
   требования и критерии приёмки нормализатора ЦБД Минюста КР.
 

docs/product/frontend-design-readiness-plan.md

@@ -0,0 +1,126 @@
+# Готовность к проектированию 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.