Files
akyldash/docs/product/implementation-roadmap.md
agent eff704c675
CI / tests-and-images (pull_request) Successful in 2m13s
Runner smoke test / runner-smoke (pull_request) Successful in 3s
docs: preserve release and interface acceptance criteria
2026-11-15 15:11:56 +03:00

453 lines
52 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# План реализации и приёмки Акылдаш
Основа аудита: `main` на `7ece39f212b67e497a8dfb360d5d271ab088ef57`
от 2 ноября 2026 года. Документ хранит результаты UI-аудита, критерии
интерфейсной приёмки и порядок подготовки production. Целевые возможности
и условия публичного MVP ведутся в [функциональности платформы](platform-functionality.md).
## 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-браузере. Результаты браузерной проверки приведены
только в [отчёте визуальной приёмки](visual-review/README.md).
Production readiness не следует из наличия Compose, release workflow или
deploy-кода. Подтверждённое состояние и ограничения находятся в
[CURRENT_STATE.md](../operations/CURRENT_STATE.md); статус релиза — в
[DEPLOYMENT.md](../operations/DEPLOYMENT.md), ограничения backup/restore — в
[BACKUP.md](../operations/BACKUP.md), rollback — в
[ROLLBACK.md](../operations/ROLLBACK.md), аварийное восстановление — в
[RECOVERY.md](../operations/RECOVERY.md). Этот план не повторяет команды из
этих runbooks.
## 2. Очерёдность работ
### 2.1 Интерфейс: датированный реестр UI-01—UI-33
Реестр ниже сохраняет исходные наблюдения аудита **23 октября 2026 года** и
критерии приёмки; это не список текущих открытых дефектов. Актуальный план на
`main` указывает, что все UI-01—UI-33 реализованы в PR #54. Он также описывает
follow-up по поиску, кабинету и лаборатории, локальную браузерную проверку и
синтетические regression fixtures. Их результаты привязаны к указанным в
исходном документе commits и окружению, а не являются повторным live-аудитом в
этой документационной задаче. Сверяться с [отчётом visual-review](visual-review/README.md);
не открывать снова выполненные пункты без нового воспроизводимого свидетельства.
Источники по состоянию на базовый commit этого PR сохранены постоянными
ссылками: [UI-план на `7ece39f`](https://git.vakanaut.ru/admin/akyldash/src/commit/7ece39f212b67e497a8dfb360d5d271ab088ef57/docs/product/interface-correction-plan.md)
и [план pixel-perfect на `7ece39f`](https://git.vakanaut.ru/admin/akyldash/src/commit/7ece39f212b67e497a8dfb360d5d271ab088ef57/docs/product/frontend-pixel-perfect-plan.md).
UI-01—UI-33 вошли в [PR #54](https://git.vakanaut.ru/admin/akyldash/pulls/54)
(merge commit [`01380d3c`](https://git.vakanaut.ru/admin/akyldash/commit/01380d3c09d71e32c965d974a39a4d82de0a15c5));
последующий follow-up поиска, кабинета и лаборатории записан в
[commit `e5a8326a`](https://git.vakanaut.ru/admin/akyldash/commit/e5a8326a5e3def1bf5d5dc94794da82a2af801ab).
В исходном реестре **P1** означает обязательное исправление до визуальной
приёмки/выпуска, **P2** — существенное улучшение понятности и
последовательности. Отсутствие функции само по себе не считается багом;
обозначенные целевые корректировки требуют подтверждения по коду и дизайну.
| 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.
- Остальные правила сетки: фильтры не становятся постоянно прокручиваемой
узкой колонкой; полный каталог значений всегда достижим; API single-select не
изображается множественными checkbox. Длинное название органа читается в
панели выбора полностью. Поля дат имеют постоянные «От» / «До» и переходят
в столбец, когда не помещаются. На desktop выдача и документ могут иметь
отдельную вертикальную прокрутку с доступными заголовком/toolbar; на mobile
основной поток вертикальный с отдельными панелями. Footer использует
растущий main (`min-height: 100dvh`), не перекрывает контент и следует за ним;
панель сохранения имеет собственное место.
- **Панели и формы:** понятный заголовок и крестик 44×44; именованный modal
dialog, фокус внутри, Tab/Shift+Tab без выхода в фон, Escape там, где закрытие
допустимо, возврат фокуса инициатору; фон не интерактивен. Не наслаивать
кабинет и пользователей. Профиль и безопасность — отдельные разделы; права
по-прежнему проверяет сервер. В форме пароля постоянные подписи, требования,
доступное показать/скрыть и подтверждение нового пароля. Пароли не
предзаполнять и не сохранять в материалах аудита; ввод выполняет человек.
- Основное действие одно; отмена вторична, выход отдельно; Enter отправляет
только активную форму. Ошибка у поля и в доступном сообщении, допустимый ввод
сохраняется, 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`
UI-план, находившийся на базовом 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` описывает реализованные после PR #54
корректировки и regression coverage:
- **Поиск:** «Открыт» сбрасывается при смене результата/редакции и ставится
только после успешной загрузки. Оглавление распознаёт самостоятельные
заголовки RU/KY из структурированных абзацев (`p > b > span`), задаёт
уникальные якоря и вложенность, не принимает обычные упоминания за заголовки.
Выбор языка поиска находится в фильтрах и не обрезается; декоративный SVG и
пустое резервное место удалены; активная навигация использует палитру.
Проверены ошибки и гонки загрузки, структура заголовков, splitter и
доступность диапазона его ширины.
- **Кабинет:** ссылки действий сохраняют `<a>` семантику, крестик остаётся
подписанной SVG-кнопкой 44×44, значения профиля стоят в парах «поле—значение»,
длинные значения переносятся, заголовок компактнее; администратору явно
доступно «Управление пользователями». Проверены RU/KY, отсутствие ссылки у
не-администратора, фокус/закрытие и ширина.
- **Лаборатория:** имя показывается без дублирующей роли; ссылки навигации имеют
вид кнопок; оболочка, форма, рабочая область, сохранение и footer выровнены.
Пустой live status не резервирует высоту, результаты и документ образуют
общую поверхность с внутренней прокруткой на desktop, заголовок использует
доступную ширину, а mobile возвращается к естественному потоку. Проверены
desktop/mobile, пустой status, сохранение после длинного документа и page
overflow.
Исходный план сообщает о локальной проверке этих изменений 24 октября 2026
года и повышении frontend до `0.3.0` из-за регулируемой ширины панелей. Текущий
source footer и версия кода — `0.3.3`. Его отметка «ожидаются CI и review»
относилась к конкретному pushed SHA и не задаёт статус этого или любого нового
PR.
#### Проверка сценариев публичного MVP
Каждый завершённый пользовательский сценарий проходит проверку
через `better-interface` с оценкой интерфейса, типографики, цвета,
доступности, компоновки и текстов. Перед выпуском публичного MVP провести
итоговую комплексную проверку поиска, фильтров и просмотра документа.
#### Общие критерии окон и форм
- 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.
Не переносить существующий Python frontend на React/Next.js ради визуальной
корректировки. UI-работа не меняет ранжирование, корпус или права доступа.
| Приёмка | Условие |
|---|---|
| Оболочка | Один header/footer на маршруте, единые границы и порядок контента |
| Фильтры | Нет общей горизонтальной прокрутки; подписи/действия/счётчики видны полностью |
| Начальное состояние | До первого завершённого запроса empty-сообщение не показано |
| Документ | До выбора неактивные действия не вводят в заблуждение |
| Колонки | Pointer и клавиатура; min/max; скрытие/возврат; reset; адаптация сохранённой ширины к viewport |
| Телефон | Основные действия без горизонтального скролла; понятный возврат из фильтров/документа |
| Окна | Заголовок, крестик, Escape, trap/return focus; окна не конкурируют слоями |
| Лаборатория | Поиск → чтение → оценка → черновик → сохранение; текст не теряется, панель доступна при длинном документе |
| Локализация | RU/KY labels и символы; язык UI не подменяет язык документа |
| Геометрия | При 1280×800 границы основных зон и отступы/размеры controls отличаются от измеренного fixture не более чем на 2 CSS px; согласованные исключения описаны |
| Типографика и таблицы | 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 CSS px** для границ крупных зон и отступов/размеров controls при
1280×800 перенесён из исторического pixel-perfect плана по стабильной ссылке
выше. Он применяется к одинаковым детерминированным fixture; расхождения
растра, вызванные сглаживанием текста или содержимым, сами по себе не дают
основания обрезать или уплотнять юридический текст.
#### Нормативный орнамент и фактическое состояние
`DESIGN.md` нормативно требует небольшой золотистый SVG-орнамент в свободной
нижней части desktop-панели фильтров, не перекрывающий длинные списки и не
резервирующий место за счёт управления. Follow-up из commit `e5a8326a` удалил
предыдущий декоративный SVG и его пустой резерв; в `backend/search/review.html`
на базовом `main` целевого орнамента нет. Это не выполненное требование, а
подтверждённое расхождение между `DESIGN.md` и реализацией. Дизайн остаётся
нормативным до отдельного решения владельца: UI-задача должна либо вернуть
орнамент в свободную область без влияния на управление, либо получить явное
одобрение на изменение `DESIGN.md` и подтвердить его визуальной приёмкой.
### 2.2 Инфраструктура и переход к production
Инфраструктурные источники содержали повторяющиеся этапы deployment и
устаревшие снимки VPS. В этом плане оставлены только gates; актуальные
подтверждённые данные и процедуры находятся в операционных документах.
1. **Аудит:** сверить commit `main`, CI, Compose, зависимости, порты, volumes,
healthchecks, данные и перечень env-переменных без вывода секретов. Для VPS
пользоваться только read-only инвентаризацией, разрешённой
[правилами доступа](../operations/ACCESS.md). Не переносить IP, версии,
DNS-статус или ресурсы из старых планов как текущие факты.
2. **Данные и конфигурация:** установить источник и допустимость корпуса,
формат, состав, checksum/manifest, размер и воспроизводимую цепочку импорта.
Обязательный gate любой передачи/публикации корпуса — процедура
[CORPUS_HANDOFF.md](../operations/CORPUS_HANDOFF.md): source → staging →
inventory/manifest и checksum comparison → атомарная публикация
проверенного staging-корпуса в `DATA_ROOT/minjust-normalized` → отдельная
проверка и импорт в индекс → OpenSearch alias switch. Runbook требует
непустые source и staging, явное решение по исключению code 6 и fail-closed
при неполных/несовпадающих данных. Атомарная файловая публикация и
возобновление/отказ после прерывания — обязательный, но ещё не реализованный
gate; до описания и проверки all-or-nothing механизма не заменять им
действующий корпус. Не смешивать его с атомарным переключением OpenSearch
alias. Следовать runbook без копирования его команд сюда; до прохождения
gates корпус в production не передавать и не индексировать. Не подменять
корпус пустым каталогом. Production env/секреты создаются вне Git; в
репозитории остаются только имена переменных и шаблоны без значений.
3. **Build/CI:** PR-проверки не получают production secrets и Docker socket.
Публикация образов должна фиксировать digest и provenance; release workflow
не равен deployment. Production CD не включать до прохождения owner gates,
безопасной сборки, backup и отдельного restore.
4. **Контролируемое изменение существующего production:** последняя датированная
проверка `https://akyldash.kg/review` вернула HTTP 200 25 октября 2026 года
([CURRENT_STATE](../operations/CURRENT_STATE.md)); установленный на хосте
SHA остался неизвестен. План относится к безопасному
обновлению существующего сервиса, а не к первому развёртыванию. До изменения
проверять реальные данные и конфигурацию, доступное место, опубликованные
порты, права, совместимость схем и backup readiness. Выполнять через
существующую ограниченную процедуру; не добавлять общие sudo/Docker-
привилегии. Базы данных и внутренние сервисы не публиковать в интернет.
DNS, reverse proxy и TLS
проверять до выпуска; для Cloudflare применять Full (strict). SSH/UFW и
сетевые ограничения меняются только после owner approval.
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 завершился зелёным.
**Backup/maintenance gate:** настройки CI, проверка конфигурации и подготовка
release provenance должны быть отделены от production cutover. Production CD
в `CURRENT_STATE.md` остаётся неактивным. Перед каждым фактическим production
изменением, включая миграции, создать и проверить внешний pre-change backup.
Полный cold backup требует остановки Compose и может выполняться только в
заранее согласованное с владельцем окно.
Ни полный архив, ни его временная копия никогда не записываются на VPS. По
текущей утверждённой схеме архив передаётся напрямую на фиксированный
`D:\Dev\akyldash\.backups`; фактическая готовность D:, SSH и отдельное
восстановление всё ещё не подтверждены. На VPS остаётся только secret-free
идентификатор/manifest согласно `BACKUP.md`. Политика — одна retained,
проверенная внешняя копия. При замене прежняя копия сохраняется до тех пор,
пока новый candidate не опубликован и не проверен; на время этой проверки две
копии могут сосуществовать. После подтверждения новой копии retention может
изменить только владелец явным решением; автоматическая очистка запрещена.
При неудачной публикации или проверке прежняя подтверждённая копия остаётся.
Локальные VPS cold-backup команды из старых документов superseded и
использоваться не должны.
#### Локальные generated reports
`/reports/` и `/tmp/` игнорируются по умолчанию, чтобы generated bulk не
попадал в обычный `git status`. Уже отслеживаемые historical evidence остаются
отслеживаемыми. Если конкретный отчёт нужен в Git, сначала проверить его
содержимое, удалить секреты, персональные данные, production corpus и
временные файлы, затем добавить только предназначенный к публикации файл
явной командой `git add -f reports/<path>`. Не добавлять каталоги целиком.
Нынешний статус не переопределяется этим roadmap: на сверенной документации
production CD остаётся неактивным, а backup/restore и внешний bootstrap имеют
непроверенные owner prerequisites. Все точные блокировки сверять с
`CURRENT_STATE.md` и `DEPLOYMENT.md` перед планированием действий.
## 3. Визуальные материалы и исходная база
### Макеты Figma
Целевые редактируемые экраны — гипотезы компоновки, а не работающий интерфейс,
источник юридических данных или доказательство доступности.
| Экран | Макет |
|---|---|
| 01. Поиск с документом, 1440×900 | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=3-2) |
| 02. Фильтры скрыты | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=3-173) |
| 03. Начальный поиск | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=3-288) |
| 04. Лаборатория и сохранение | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=3-395) |
| 05. Кабинет: профиль и закрытие | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=5-30) |
| 06. Кабинет: безопасность | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=5-229) |
| 07. Источники | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=5-428) |
| 08. Пользователи: отдельный экран | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=5-605) |
| 09–11. Телефон: выдача, чтение и фильтры (общий Figma-узел) | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=5-670) |
| 12. Эталон 1280×800 | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=7-74) |
| 13. Планшет: две панели | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=7-245) |
| 14. Кабинет на телефоне | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=7-360) |
| 15. Вход, создание и подтверждение удаления | [Figma](https://www.figma.com/design/3PE98PJYOXo7a35u2X5VqB?node-id=8-118) |
Локальные target exports: [поиск](../design/tunduk-search-target.png),
[лаборатория](../design/tunduk-review-target.png),
[кабинет](../design/tunduk-account-target.png). Это изображения цели; они не
заменяют браузерную проверку.
В Figma экраны собраны из редактируемого текста, Auto Layout, SVG, локальных
переменных цвета/отступов и общих экземпляров кнопок; это не один растр.
Состояния 09–11 ведут на один общий мобильный узел, как в исходном плане.
Прокрутка длинной выдачи/текста показывает продолжение содержимого.
Splitter, закрытие и формы описывают целевое поведение, но не являются
работающим web-кодом.
### Исторические свидетельства
Аудит 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](visual-review/README.md). Ветка `main` не
содержит отдельный архив live screenshots этого аудита. Любое использование
результатов требует повторной проверки актуальной версии и окружения.
## 4. Постоянные правила дизайна и полномочия
[DESIGN.md](../../DESIGN.md) остаётся нормативной дизайн-системой: цветовые
токены, типографика, бренд, композиционные принципы и доступность не
дублируются здесь. Этот roadmap задаёт работы, исторические критерии и gates;
он не утверждает новый дизайн и не разрешает production deployment.
Все пункты плана отмечать выполненными только при наличии актуального
свидетельства. Изменения приложения проходят обычные тесты, версионирование,
CI и независимое review. Инфраструктурные изменения отражаются в
`CURRENT_STATE.md` только по фактическим проверкам. Никакие действия с
production, секретами, пользователями или правовым корпусом не следуют из
наличия этого документа. Root-only bootstrap и предоставление секретов
выполняет/утверждает владелец в защищённой среде; DEV готовит проверяемый код
и точный план, reviewer независимо проверяет безопасность и failure paths.