akyldash/docs/product/implementation-roadmap.md

План реализации и приёмки Акылдаш

Дата актуализации: 2 ноября 2026 года. Основа сверки: main на 7ece39f212b67e497a8dfb360d5d271ab088ef57. Это единый план работ по продукту, интерфейсу и переходу к production. Он не заменяет эксплуатационные runbooks и не подтверждает состояние живого сервиса.

1. Статус и границы достоверности

Различаем три вида сведений:

• В коде — наличие исходного кода на указанном commit; это не доказывает, что функция развёрнута или доступна пользователям.
• Историческое наблюдение — результат конкретного аудита, дата и пределы которого указаны рядом. Оно не является повторной проверкой текущего сайта.
• Цель / gate — требование, которое нужно выполнить и подтвердить до следующего этапа.

На сверенном commit источники кода показывают Backend 0.13.3 (backend/search/minjust_opensearch.py), Frontend 0.3.3 (backend/search/review.html) и Telegram-бот 0.2.2 (tools/telegram-bot/bot.py). Это версии исходного кода, а не подтверждение установленных production-версий. В этом PR согласованы версии в корневом и общем документационном README; backend/README.md отдельно называет версию загрузчика minjust_cbd.py (0.9.3). При новых изменениях сверять версию компонента с соответствующим исполняемым кодом.

В Search API и frontend реализованы поиск RU/KY, фильтры, карточка документа, редакции, поиск в тексте, внутренняя лаборатория, вход и административные действия. В коде также есть локальные Noto Sans/Serif с лицензиями, favicon и встроенный SVG-знак бренда. Наличие файлов и ссылок в HTML не подтверждает, что они загрузились в live-браузере. Результаты браузерной проверки приведены только в отчёте визуальной приёмки.

Production readiness не следует из наличия Compose, release workflow или deploy-кода. Подтверждённое состояние и ограничения находятся в CURRENT_STATE.md; статус релиза — в DEPLOYMENT.md, ограничения backup/restore — в BACKUP.md, rollback — в ROLLBACK.md, аварийное восстановление — в RECOVERY.md. Этот план не повторяет команды из этих runbooks.

2. Очерёдность работ

2.1 Продукт и качество правовых данных

1. Поддерживать воспроизводимое получение и нормализацию официальных правовых материалов с сохранением источника, редакции и контрольных сумм.
2. Подтвердить полноту и актуальность RU/KY корпуса, правила для отсутствующих текстов и одноязычных редакций; не выдумывать перевод или реквизиты.
3. Развивать замороженный relevance set и измерять качество на одной и той же выборке до и после изменений ранжирования.
4. Развивать версионируемые API и справочники, сохраняя совместимость существующих клиентов.
5. Публичный frontend, персональные функции и RAG остаются отдельными продуктовыми решениями и readiness gates. Сверяться с обзором проекта, планом frontend и готовностью публичного frontend. Конкурентная гипотеза и сегмент рынка отдельно описаны в стратегическом сравнении с Токтом.

2.2 Интерфейс: датированный реестр UI-01—UI-33

Реестр ниже сохраняет исходные наблюдения аудита 23 октября 2026 года и критерии приёмки; это не список текущих открытых дефектов. Актуальный план на main указывает, что все UI-01—UI-33 реализованы в PR #54. Он также описывает follow-up по поиску, кабинету и лаборатории, локальную браузерную проверку и синтетические regression fixtures. Их результаты привязаны к указанным в исходном документе commits и окружению, а не являются повторным live-аудитом в этой документационной задаче. Сверяться с отчётом visual-review; не открывать снова выполненные пункты без нового воспроизводимого свидетельства.

ID	Приоритет	Историческое наблюдение 23.10.2026	Требование / критерий
UI-01	P1	При пустом запросе одновременно показывались подсказка и empty-состояние	Разделить initial/loading/results/empty/error; empty показывать после завершённого поиска
UI-02	P1	До выбора документа были доступны действия и пустые select	До загрузки документа показывать понятное приглашение; действия доступны после выбора
UI-03	P1	Фильтры имели горизонтальное переполнение (clientWidth=194, scrollWidth=231 при 1064 px)	Исключить переполнение; длинные списки раскрывать по запросу
UI-04	P1	Действие «Сбросить» обрезалось заголовком	Заголовок и действие видны целиком на поддерживаемых размерах
UI-05	P1	Счётчики отрывались от подписей, переносы растягивали панель	Разделить колонки выбора/подписи/числа; переносить только длинные названия
UI-06	P1	Все 28 видов и 8 статусов были раскрыты, орган и даты находились ниже первого экрана	Показывать основные значения и сворачиваемые группы, сохраняя доступ ко всему каталогу
UI-07	P1	Ширины около 78 px не хватало для RU/KY названий языка	Подбирать размер по самой длинной локализованной подписи без обрезки
UI-08	P1	На 390 px навигация прокручивалась горизонтально, кабинет и фильтры уходили за край	Адаптивно показывать поиск, фильтры и кабинет без горизонтальной прокрутки основных действий
UI-09	P2	Кабинет был малозаметной иконкой во второй строке	Подписанная desktop-кнопка; на mobile — доступное имя и достаточная touch-область
UI-10	P1	Три колонки оставались тесными на 1024/1064 px	Перейти к двухпанельному режиму и скрытию фильтров, не сжимать колонки бесконечно
UI-11	P2	Название документа повторялось в breadcrumb, заголовке и тексте	Breadcrumb обозначает контекст; официальный текст не переписывать
UI-12	P1	Ссылка на источник и toolbar переполнялись на промежуточной ширине	Переносить действия группами без обрезки; сохранять подписи редакции и языка
UI-13	P2	Пустые абзацы и синие ссылки конфликтовали с оболочкой	Нормализовать отступы и ссылки без потери структуры официального текста
UI-14	P1	Таблицы в документе шире панели (clientWidth=412, scrollWidth=834)	Дать таблице отдельную обозначенную прокрутку; не прокручивать всю страницу по горизонтали
UI-15	P1	Встречались Temp-пути и HTTP-ссылки исходного редактора	Классифицировать ссылки безопасно, не удалять юридический текст; не считать локальные/IP-ссылки проверенными
UI-16	P2	Развёрнутый документ терял поиск, совпадение и toolbar	Сохранять редакцию, язык, позицию и навигацию; обеспечить очевидный возврат
UI-17	P2	Часть KY-интерфейса оставалась на русском	Инвентаризировать строки интерфейса; не заменять переводом язык документа
UI-18	P1	На /review отображались два footer, общий footer был выше сохранения	Один footer после основного содержимого и панели сохранения
UI-19	P1	Шапка, формы, панели и footer лаборатории имели разные направляющие	Единая оболочка и совпадающие границы контента
UI-20	P1	Высокая шапка лаборатории отодвигала работу на mobile	Компактный заголовок и помощь; поиск и рабочая область доступны сразу
UI-21	P1	Заголовок кабинета был пустым	Видимый заголовок и доступное имя диалога
UI-22	P1	Не было постоянного крестика; закрытие находилось внизу формы	Крестик 44×44, доступное имя, Escape и возврат фокуса; отмена редактирования остаётся
UI-23	P1	Навигация, выход, профиль и смена пароля были смешаны	Разделить «Профиль» и «Безопасность», отделить выход от формы
UI-24	P1	Окно пользователей открывалось поверх кабинета	Не оставлять конкурирующие модальные окна; сохранять контекст и корректный фокус
UI-25	P1	Список пользователей был длинным модальным окном с закрытием ниже экрана	Отдельный экран списка и короткие диалоги для создания/сброса
UI-26	P2	Создание, удаление, сброс и входные данные смешивались	Действия на строке, отдельное подтверждение удаления, не раскрывать лишние формы
UI-27	P2	Бренд, навигация, шрифты и ссылки различались между экранами	Общие header, logo, button, link, dialog и footer
UI-28	P2	Диалоги закрывались разными способами	Единая модель окна и доступного закрытия
UI-29	P2	Обучение появлялось с задержкой и перехватывало ввод	Запуск по запросу или ненавязчиво до начала ввода; не отбирать фокус
UI-30	P2	Шкала 0–3 переносилась, комментарии всегда занимали место	Полные подписи; допустима сетка 2×2; раскрываемый комментарий без потери текста
UI-31	P2	Пустой экран лаборатории выглядел готовым к отправке оценки	Явное состояние снимка, прогресс и статус черновика; не менять смысл пустой оценки
UI-32	P2	Footer live-сайта показывал «Концепция Түндүк»	Рабочий интерфейс показывает продукт и реальные версии; концепция подписывается только в макете/демо
UI-33	P1	Документ растягивал лабораторию до y≈636935 px, сохранение уходило ниже	Ограничить высоту области чтения и прокручивать её отдельно; сохранение доступно независимо от длины текста

Дополнительные целевые критерии исходного аудита:

• Сетка и ресайз колонок: desktop — три колонки с доступными разделителями; ориентиры 1440 px: 280 / 408 / 736 плюс два захвата по 8 px, 1280 px: 256 / 384 / 624 плюс захваты. Рекомендуемые пределы фильтров 256–360 px, выдачи от 360 px, документа от 560 px. При недостатке ширины сначала скрыть фильтры, затем показывать документ отдельно.
• Разделители должны иметь role=separator, доступное имя, min/max/current значения, pointer drag и управление стрелками клавиатуры. Отдельные кнопки скрытия/показа фильтров и сброса ширины обязательны; двойной клик не заменяет доступный сброс. Сохранённая ширина ограничивается текущим viewport.
• Панели и формы: понятный заголовок и крестик 44×44; именованный modal dialog, фокус внутри, Tab/Shift+Tab без выхода в фон, Escape там, где закрытие допустимо, возврат фокуса инициатору. Не наслаивать кабинет и пользователей. Права по-прежнему проверяет сервер; пароли не предзаполнять и не сохранять в материалах аудита. Ошибки сохраняют допустимый ввод, loading исключает повторную отправку.
• Приёмка: единая оболочка/header/footer; нет общей горизонтальной прокрутки; initial не сообщает об empty до поиска; действия документа активируются по состоянию; keyboard и touch работают; RU/KY подписи и язык документа независимы; таблицы прокручиваются отдельно; тестируются contrast WCAG AA, видимый focus, reduced motion, zoom/reflow и доступные имена.
• Viewport: 1440×900, 1280×800, 1024×768, 390×844, дополнительно 320 CSS px для reflow. Визуальное сравнение — детерминированное fixture; нулевой pixel-diff не является критерием. Авторизация и destructive-сценарии проверяются только в безопасном тестовом контуре.

Исторически выполненные браузерные сценарии и ограничения аудита 23.10.2026:

Область	Выполнено в том аудите	Не проверено тогда
Начальная страница и поиск RU	Пустой запрос, фильтры, footer; поиск «налог на прибыль», открытие кодекса	Экспертная оценка юридической релевантности
Фильтры, сортировка, страницы	Статус, chip, снятие фильтра, дата/релевантность, страница 2 и сброс на страницу 1	Все комбинации справочников
Пустая выдача и документ	Контрольный заведомо пустой запрос, реальные текст и редакции, язык, разворот	Искусственное создание серверного сбоя, реальная печать/PDF
Поиск в документе и локализация	Совпадения, переход к следующему, переключение RU/KY и чтение подписей	Поиск после смены редакции; полная проверка всех переводов
Источники и мобильные фильтры	Открытие/закрытие панели и раздела источников	Внешний сайт Минюста, полный touch на физическом устройстве
Кабинет и пользователи	Профиль, поля смены пароля, Escape/возврат фокуса; просмотр списка	Ввод пароля, создание/удаление пользователя, сброс пароля
/review	Пустое состояние, поиск, шкала, документ, обучение	Отправка оценки и подтверждение серверного сохранения
Авторизация	Наличие локальной реализации	Live login, истечение сессии и обязательная смена пароля

Этот перечень описывает только прежний браузерный сеанс. Не использовать его как подтверждение текущих production-сценариев.

Реализация, зафиксированная в текущем плане main

Документ interface-correction-plan.md на базовом commit этого PR отмечает UI-01—UI-33 реализованными в PR #54. Он связывает группы изменений с регрессионными сценариями:

Пункты	Изменение, зафиксированное в плане main	Regression evidence, указанное там
UI-01—02	Разделены initial/loading/results/empty/error; действия документа зависят от выбранной редакции	Empty, API error и редакция без текста
UI-03—08	Компактные/сворачиваемые фильтры, счётчики, локализованные языковые select и адаптивная навигация	Reflow 320/390/640/1024/1280/1440; на 640 px проверены основные действия /, /review, /users
UI-09—10	Подписанный кабинет и адаптивный layout вместо бесконечного сжатия трёх колонок	Геометрия и overflow на 640/1024/1280/1440
UI-11—16	Breadcrumb, toolbar, отдельный scroll таблиц, очистка небезопасных URL-атрибутов и разворот документа в панели	Синтетические private-IP/relative/HTTP ссылки; ошибки и гонки редакций A/B
UI-17	Перевод интерфейсных подписей RU/KY с независимым языком документа	Переключение языка; полный ручной лингвистический review остаётся открытым
UI-18—20	Один footer, общие направляющие и ограниченная по высоте лаборатория	Один footer и длинный синтетический документ с собственным scroll
UI-21—24	Имя и разделы кабинета, безопасный переход к пользователям без наложенных диалогов	ARIA name, Escape, focus trap/return и отдельные маршруты
UI-25—28	Отдельный экран пользователей, целевые окна для действий, общий способ закрытия	Только фиктивный fixture-created; реальные аккаунты/API не использовались
UI-29	Обучение запускается пользователем	Локальный regression scenario
UI-30—31	Оценка 2×2, раскрываемый комментарий, disable до результата и draft state	Фиктивное сохранение и сохранность оценок при ошибке/устаревшем ответе
UI-32—33	Версии в footer и отдельная прокрутка длинного текста лаборатории	Footer versions и длинный fixture, сохранение остаётся доступно

Тот же план main фиксирует локальный browser run на 320×800, 390×844, 640×450, 1024×900, 1280×800 и 1440×900 CSS px; на 1280 px измерена сетка 256 / 384 / 640 px. Экран лаборатории с длинным текстом имел собственную панель прокрутки, а сохранение/footer оставались доступны. Встроенная проверка fixture не использовала production API или реальные учётные записи. Это точная передача прежнего отчёта; её не следует трактовать как результат нового прогона в этом PR. Полный screen-reader review, 200–400% zoom, физический touch и полный ручной лингвистический review в исходном плане оставлены непроверенными.

Отдельный follow-up плана main описывает последующие изменения: статус «Открыт» выставляется после успешной загрузки; оглавление распознаёт RU/KY структурные заголовки и избегает дублирования упоминаний; размеры и положение языкового выбора, фильтров и splitter скорректированы. В кабинете выровнены пары профильных значений, сохранены семантические ссылки и доступность перехода к пользователям. В лаборатории выровнены оболочка, форма, рабочая область, сохранение и footer; mobile возвращается к естественному потоку документа. Исходный план сообщает о локальной проверке 24 октября 2026 года; статус CI и review относится к конкретному pushed SHA и должен подтверждаться отдельно.

В актуальном плане main follow-up обозначен как реализованный; там указано, что frontend был повышен до 0.3.0 из-за регулируемой ширины панелей. Текущий source footer и версия кода — 0.3.3. Историческую отметку «ожидаются CI и review» из старого плана нельзя использовать как статус сегодняшнего PR: она относилась к конкретному SHA на момент записи.

Общие критерии окон и форм

• Desktop-окно обычно 480–640 px и не шире viewport; на mobile — отступ 16 px или полноэкранный режим для длинной формы. Заголовок и закрытие остаются доступны при прокрутке.
• Диалог именуется через заголовок, держит фокус внутри и не делает фон интерактивным. Escape закрывает обычные окна; исключения (например, обязательная смена пароля) должны объясняться, а не маскироваться.
• Профиль и безопасность разделены. Удаление требует отдельного подтверждения; создание/сброс не раскрывают дополнительные формы без запроса.
• Поля имеют постоянные подписи; пароль не предзаполняется и не записывается в отчёт. Ошибки объясняют восстановление, допустимый ввод сохраняется, повторная отправка во время loading исключена.
• «Отмена» вторична, выход не смешивается с сохранением; несохранённое редактирование защищено от случайной потери. Обычный просмотр закрывается без лишнего подтверждения.

Последовательность при возобновлении UI-работ

1. Зафиксировать актуальные SHA и версии; читать маршрут, API, DESIGN.md, UI tests и CI. Не переносить состояние live-сайта без новой проверки.
2. Исправить общую оболочку и разделение поиска, лаборатории и служебных экранов; затем initial/loading/empty/error и жизненный цикл документа.
3. Исправить фильтры, адаптивные минимумы и RU/KY; после этого — регулируемые колонки и скрытие фильтров.
4. Привести формы/диалоги к общей модели с сохранением серверной авторизации, прав, валидации, снимков оценок и черновиков.
5. Проверить текст, таблицы, ссылки, редакции, печать, адаптивность, локализацию, доступность и состояния на реальном корпусе, где доступен.
6. Сделать детерминированный fixture-проход и независимый review; обновить версию только при изменении кода, а changelog — после зелёных проверок и разрешения blocking findings.

Приёмка	Условие
Оболочка	Один header/footer на маршруте, единые границы и порядок контента
Фильтры	Нет общей горизонтальной прокрутки; подписи/действия/счётчики видны полностью
Начальное состояние	До первого завершённого запроса empty-сообщение не показано
Документ	До выбора неактивные действия не вводят в заблуждение
Колонки	Pointer и клавиатура; min/max; скрытие/возврат; reset; адаптация сохранённой ширины к viewport
Телефон	Основные действия без горизонтального скролла; понятный возврат из фильтров/документа
Окна	Заголовок, крестик, Escape, trap/return focus; окна не конкурируют слоями
Лаборатория	Поиск → чтение → оценка → черновик → сохранение; текст не теряется, панель доступна при длинном документе
Локализация	RU/KY labels и символы; язык UI не подменяет язык документа
Типографика и таблицы	Noto действительно загружается; читаемый длинный текст; у широкой таблицы собственный скролл
Доступность	Контраст AA, focus, Tab/Shift+Tab/Enter/Escape, zoom/reflow, reduced motion и touch targets
Авторизация	Неверный пароль, expired session и обязательная смена проверены только в безопасном тестовом контуре
Снимки	1440×900, 1280×800, 1024×768, 390×844 и 320 CSS px; стабильные fixture и объяснённые различия

2.3 Инфраструктура и переход к production

Инфраструктурные источники содержали повторяющиеся этапы deployment и устаревшие снимки VPS. В этом плане оставлены только gates; актуальные подтверждённые данные и процедуры находятся в операционных документах.

1. Аудит: сверить commit main, CI, Compose, зависимости, порты, volumes, healthchecks, данные и перечень env-переменных без вывода секретов. Для VPS пользоваться только read-only инвентаризацией, разрешённой правилами доступа. Не переносить IP, версии, DNS-статус или ресурсы из старых планов как текущие факты.
2. Данные и конфигурация: установить источник и допустимость корпуса, формат, состав, checksum/manifest, размер и воспроизводимую цепочку импорта. Не подменять корпус пустым каталогом. Production env/секреты создаются вне Git; в репозитории остаются только имена переменных и шаблоны без значений.
3. Build/CI: PR-проверки не получают production secrets и Docker socket. Публикация образов должна фиксировать digest и provenance; release workflow не равен deployment. Production CD не включать до прохождения owner gates, безопасной сборки, backup и отдельного restore.
4. Первое применение: до запуска проверить реальные данные и конфигурацию, требуемое свободное место, открытые порты, права, backup readiness и совместимость схем. Выполнять через существующую ограниченную процедуру; не добавлять общие sudo/Docker-привилегии.
5. Проверка и recovery: проверять health/API, RU/KY canaries, доступность HTTPS, сохранность данных и rollback в пределах его документированных ограничений. Data restore — отдельная процедура в staging, не автоматический побочный эффект отката образа.
6. Автоматизация: только после одобренного отдельного bootstrap и end-to-end проверки; serial deployment, digest verification, backup ACK, health gates и отказ без destructive cleanup. Не включать триггер только потому, что workflow завершился зелёным.

Нынешний статус не переопределяется этим roadmap: на сверенной документации production CD остаётся неактивным, а backup/restore и внешний bootstrap имеют непроверенные owner prerequisites. Все точные блокировки сверять с CURRENT_STATE.md и DEPLOYMENT.md перед планированием действий.

3. Визуальные материалы и исходная база

Макеты Figma

Целевые редактируемые экраны — гипотезы компоновки, а не работающий интерфейс, источник юридических данных или доказательство доступности.

Экран	Макет
01. Поиск с документом, 1440×900	Figma
02. Фильтры скрыты	Figma
03. Начальный поиск	Figma
04. Лаборатория и сохранение	Figma
05. Кабинет: профиль и закрытие	Figma
06. Кабинет: безопасность	Figma
07. Источники	Figma
08. Пользователи: отдельный экран	Figma
09. Телефон: выдача	Figma
10. Телефон: чтение	Figma
11. Телефон: фильтры	Figma
12. Эталон 1280×800	Figma
13. Планшет: две панели	Figma
14. Кабинет на телефоне	Figma
15. Вход, создание и подтверждение удаления	Figma

Локальные target exports: поиск, лаборатория, кабинет. Это изображения цели; они не заменяют браузерную проверку.

Исторические свидетельства

Аудит UI выполнен 23 октября 2026 года в авторизованной сессии на https://akyldash.kg/, где footer показывал Frontend 0.2.3, Backend 0.13.0. Сверка SHA сервиса с checkout не выполнялась. Проверены 1440×900, 1280×800, 1024×768, 390×844 CSS px и дополнительный browser viewport 1064×1244. Пароли не вводились; создание/удаление пользователей и отправка оценки не выполнялись; полный физический touch, screen-reader и принтерный прогоны не выполнялись. Существующие локальные browser evidence и screenshots собраны в отчёте visual-review. Ветка main не содержит отдельный архив live screenshots этого аудита. Любое использование результатов требует повторной проверки актуальной версии и окружения.

4. Постоянные правила дизайна и полномочия

DESIGN.md остаётся нормативной дизайн-системой: цветовые токены, типографика, бренд, композиционные принципы и доступность не дублируются здесь. Этот roadmap задаёт работы, исторические критерии и gates; он не утверждает новый дизайн и не разрешает production deployment.

Все пункты плана отмечать выполненными только при наличии актуального свидетельства. Изменения приложения проходят обычные тесты, версионирование, CI и независимое review. Инфраструктурные изменения отражаются в CURRENT_STATE.md только по фактическим проверкам. Никакие действия с production, секретами, пользователями или правовым корпусом не следуют из наличия этого документа.