# План реализации frontend поисковой СПС Основание: `docs/Функциональные_возможности_поисковой_СПС.docx`. Документ с требованиями описывает не только frontend, но и поиск, юридическую обработку, персональные данные, уведомления и внешние источники. Поэтому frontend следует начинать после появления нормализованной базы, поискового API и API документов. Требования необходимо адаптировать под Кыргызскую Республику: в исходном документе используются примеры ТК РФ и деление «федеральный/региональный/муниципальный», которое нельзя переносить без изменений. ## Задачи до начала frontend-разработки ### Обязательные для MVP 1. Нормализовать архив Минюста: - очистить HTML; - выделить структуру документа и редакций; - унифицировать статусы, органы, виды документов и даты; - сохранить ссылки на официальный источник и дату получения; - определить правила отображения документов без текста. 2. Подготовить backend API: - `GET /search`; - `GET /search/filters`; - `GET /documents/{code}`; - `GET /documents/{code}/editions`; - `GET /documents/{code}/editions/{edition}`; - описание API в OpenAPI; - серверную пагинацию, фильтрацию и сортировку. 3. Развернуть поисковый сервис. Рекомендуемый вариант — self-hosted OpenSearch: - отдельные поля и анализаторы для русского и кыргызского текстов; - русский морфологический анализ; - ICU-нормализация кыргызского текста; - словари синонимов и сокращений; - подсветка совпадений; - индексирование всех редакций. 4. Подготовить тестовый набор из 50–100 реальных запросов на русском и кыргызском языках и вручную отметить ожидаемые результаты. 5. Утвердить справочники: - виды документов; - органы принятия; - статусы; - уровни действия; - тематический классификатор первой версии. OpenSearch имеет встроенный [русский морфологический анализатор](https://docs.opensearch.org/latest/analyzers/language-analyzers/russian/), поддерживает [синонимы и нечёткий поиск](https://docs.opensearch.org/latest/query-dsl/full-text/match/) и [подсветку результатов](https://docs.opensearch.org/latest/search-plugins/searching-data/highlight). Встроенного кыргызского морфологического анализатора в перечне нет, поэтому нужно отдельно проверить ICU и словари на реальных запросах. [ICU-анализатор](https://docs.opensearch.org/latest/analyzers/language-analyzers/icu/) обеспечивает Unicode-нормализацию, но сам по себе не гарантирует кыргызскую морфологию. ### Сторонние сервисы, не нужные для MVP Их не следует подключать заранее: - Keycloak или другой OIDC-провайдер — перед закладками, папками и ролями; - SMTP, Telegram или Web Push — перед «документами на контроле»; - LibreOffice или Gotenberg — перед экспортом в Word, PDF и RTF; - поставщики судебной практики и экспертных комментариев — после проверки лицензий; - источники курсов, календарей и справочных данных — перед соответствующим разделом; - Sentry или аналог — опционально перед публичным запуском. ## Граница MVP MVP — публичная справочно-поисковая система без регистрации и персональных функций. В MVP входят: - интерфейс на русском и кыргызском языках; - строка полнотекстового поиска; - исправление распространённых опечаток; - базовые синонимы и сокращения; - список результатов с подсвеченными фрагментами; - фильтры по языку, виду документа, органу, статусу и дате; - сортировка по релевантности и дате; - пагинация; - карточка документа; - актуальная редакция, статус и дата актуальности; - переключение между доступными языками; - поиск внутри открытого документа; - список редакций и открытие выбранной редакции; - ссылка на официальный источник и сведения о происхождении данных; - адаптивность, доступность, состояния загрузки и ошибок. Сравнение редакций, аккаунты, заметки, уведомления, RAG и судебная практика в MVP не входят. Интерфейс не должен предполагать наличие обоих языков. На момент полного скачивания архива распределение следующее: - только русский язык — 29 433 документа; - только кыргызский язык — 98 905 документов; - оба языка — 80 930 документов; - нет HTML-текста — 690 документов. ## Рекомендуемая основа frontend - Next.js App Router и TypeScript; - CSS Modules с BEM-именованием; - дизайн-токены для цветов, отступов, типографики и состояний; - серверный `fetch` и URL-параметры вместо отдельного глобального хранилища; - Playwright для основных пользовательских сценариев; - адаптивный web-интерфейс без отдельного мобильного приложения. Next.js App Router поддерживает серверные компоненты, маршрутизацию и TypeScript в стандартной конфигурации. См. [официальную документацию](https://nextjs.org/docs/app). ## Дизайн-процесс и внешние ориентиры При проектировании и проверке интерфейса используются следующие источники: - [jakubkrehel/skills](https://github.com/jakubkrehel/skills) — обязательная комплексная проверка интерфейса через `better-interface`, включая UI, типографику, цвета, доступность, layout и тексты; - [UI Skills](https://www.ui-skills.com/) — каталог практик и узких skills, которые подключаются только под конкретную задачу после проверки их содержания и лицензии; - [Refero Styles](https://styles.refero.design/) — библиотека визуальных направлений и примеров `DESIGN.md` для поиска референсов. Правила применения: 1. До разработки экранов выбрать в Refero не более трёх подходящих направлений и на их основе утвердить одно собственное направление Акылдаша. 2. Не копировать чужую дизайн-систему целиком. Цвета, типографика, плотность и компоненты должны учитывать длинные юридические тексты, два языка и доступность. 3. Зафиксировать утверждённое направление в `frontend/DESIGN.md` и перенести значения в дизайн-токены проекта. 4. Дизайн-токены и компоненты Акылдаша являются источником истины. Внешние рекомендации не могут отменять BEM, доступность, требования безопасности и продуктовые ограничения проекта. 5. Каждый завершённый пользовательский сценарий проходит `better-interface` review. Перед выпуском MVP выполняется полный review поиска, фильтров и просмотра документа. 6. UI Skills используется для точечного поиска решения, а не для одновременного смешивания нескольких визуальных стилей. Эти ресурсы используются на этапе проектирования и review и не являются runtime-зависимостями frontend. Регистрация в стороннем SaaS для MVP не нужна. ## План спринтов MVP ### Спринт 0 — фундамент, 1 неделя - создать `frontend/`; - настроить Next.js, TypeScript, lint и сборку; - выбрать до трёх референсов в Refero Styles и утвердить одно визуальное направление; - создать `frontend/DESIGN.md` с правилами выбранного направления; - установить полный набор `jakubkrehel/skills` для проектных design review; - определить маршруты и типы API; - создать дизайн-токены; - реализовать базовые компоненты: кнопка, поле, селект, статус, карточка, пагинация; - создать общий layout и двуязычную навигацию; - добавить footer с версиями frontend и backend; - подготовить макеты поиска, результатов и документа; - провести первый `better-interface` review макетов; - настроить CI. Результат: интерфейсный каркас работает на mock-ответах API. ### Спринт 1 — быстрый поиск, 2 недели - главная страница с поиском; - интеграция с `/search`; - список результатов; - подсветка совпадений; - URL, которым можно поделиться; - переключение RU/KY; - состояния загрузки, отсутствия результатов и ошибки API; - базовая мобильная версия. Результат: пользователь может найти документ и открыть результат. ### Спринт 2 — точный отбор, 2 недели - фильтры по реквизитам; - сортировка; - пагинация; - отображение числа результатов; - сброс отдельных и всех фильтров; - сохранение состояния в URL; - доступное управление с клавиатуры; - адаптивная панель фильтров. Результат: поддерживается быстрый и реквизитный поиск. ### Спринт 3 — просмотр документа, 2 недели - заголовок, реквизиты, статус и дата актуальности; - безопасное отображение очищенного HTML; - переключение языка; - поиск внутри документа; - навигация по найденным фрагментам; - список редакций; - открытие предыдущей редакции; - ссылка на ЦБД Минюста; - печать средствами браузера. Результат: пользователь может проверить текст и его происхождение. ### Спринт 4 — стабилизация и выпуск, 2 недели - сквозные тесты поиска и просмотра; - проверка русских, кыргызских и одноязычных документов; - соответствие WCAG 2.2 AA; - защита от внедрения небезопасного HTML; - проверка производительности; - корректные метаданные страниц; - обработка недоступности API; - production-сборка и развёртывание; - пользовательское тестирование на 10–15 реальных юридических задачах. Результат: публичный MVP. Оценка frontend-части после готовности API: **9 недель**. ## Спринты после MVP ### Спринт 5 — персональный кабинет Авторизация, закладки, заметки, подборки и сохранённые фильтры. ### Спринт 6 — контроль изменений Документы на контроле, подписки на редакции и уведомления. ### Спринт 7 — юридические связи Сравнение редакций, прямые и обратные ссылки, утратившие силу фрагменты. ### Спринт 8 — практические материалы Формы, образцы, инструкции, чек-листы, календари и справочные данные. ### Спринт 9 — расширенный анализ Судебная практика, экспертные комментарии, дерево связей и RAG с обязательными ссылками на источники. ### Спринт 10 — корпоративные функции Роли, журналирование, API, интеграция с СЭД, расширенный экспорт и персонализация. --- Акылдаш · Telegram-бот v0.2.2 · Backend v0.7.1 · Frontend — не создан