262 lines
15 KiB
Markdown
262 lines
15 KiB
Markdown
# План реализации 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 — не создан
|