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

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

Этот документ определяет обязательный результат до начала проектирования и разработки пользовательского интерфейса. Он дополняет план frontend поисковой СПС: тот описывает 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.