From 0f6f12e0e90d22d72f1c142061c27a7f0139f674 Mon Sep 17 00:00:00 2001 From: Codex Agent Date: Thu, 20 Aug 2026 23:23:19 +0300 Subject: [PATCH 1/2] docs: add frontend design readiness plan --- docs/README.md | 2 + .../product/frontend-design-readiness-plan.md | 126 ++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 docs/product/frontend-design-readiness-plan.md diff --git a/docs/README.md b/docs/README.md index b9c9ab0..feebcc7 100644 --- a/docs/README.md +++ b/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) — требования и критерии приёмки нормализатора ЦБД Минюста КР. diff --git a/docs/product/frontend-design-readiness-plan.md b/docs/product/frontend-design-readiness-plan.md new file mode 100644 index 0000000..ce1ea0a --- /dev/null +++ b/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. -- 2.54.0 From 85672dc041632ba16e7929e5e6f17e7a2740e366 Mon Sep 17 00:00:00 2001 From: Codex Agent Date: Thu, 20 Aug 2026 23:25:12 +0300 Subject: [PATCH 2/2] docs: record frontend readiness roadmap --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bf8b87..73a890a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## Не выпущено +- Добавлен roadmap готовности данных, поиска и API перед проектированием + frontend. - Исправлена выдача для явных запросов об открытии ОсОО и ЖЧК: первыми показываются действующие положение о регистрации и закон о хозяйственных товариществах и обществах. -- 2.54.0