agent/akyldash
1
1
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
akyldash/docs/product/frontend-search-sps-plan.md

15 KiB
Raw Permalink Blame History

План реализации 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 имеет встроенный русский морфологический анализатор, поддерживает синонимы и нечёткий поиск и подсветку результатов. Встроенного кыргызского морфологического анализатора в перечне нет, поэтому нужно отдельно проверить ICU и словари на реальных запросах. 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 в стандартной конфигурации. См. официальную документацию.

Дизайн-процесс и внешние ориентиры

При проектировании и проверке интерфейса используются следующие источники:

  • jakubkrehel/skills — обязательная комплексная проверка интерфейса через better-interface, включая UI, типографику, цвета, доступность, layout и тексты;
  • UI Skills — каталог практик и узких skills, которые подключаются только под конкретную задачу после проверки их содержания и лицензии;
  • Refero Styles — библиотека визуальных направлений и примеров 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 — не создан

Reference in New Issue View Git Blame Copy Permalink