127 lines
8.5 KiB
Markdown
127 lines
8.5 KiB
Markdown
# Готовность к проектированию 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.
|