Files
flexly-cms/specs/001-antirion-admin/tasks.md
T
phelex 88ac95dd19 Integrate Antirion admin with FastAPI and htmx
Add the shared document API, constructor and expert editors, isolated preview, and fragment catalog metadata with typed block IDs.

Include design references, specification 001, QA scripts, project guidance, and cached Docker dependency installation. Leave example sites for a separate commit.
2026-11-12 21:55:36 +03:00

24 KiB
Raw Blame History

Задачи 001 — Antirion Rework

Дата: 2026-11-12. Статус: функциональная реализация проверена; задачи переноса и визуальной приёмки открыты повторно после замечаний пользователя. Поэтапная проверка дизайна. Результаты и ограничения — verification.md, воспроизводимый контракт и запуск — runtime.md.

Основание: спецификация и технический план. Создание этих документов не закрывает перечисленные задачи разработки. Новые ID T037–T041 добавлены без перенумерации прежних задач; порядок выполнения задаётся этапами и зависимостями.

Правила выполнения

  • Выполнять этапы A → B → C → D → E → F с контрольными точками ниже.
  • Задача закрывается после изменения, относящейся к нему проверки и записи результата; наличие кода без проверки не равно завершению.
  • Существующие проверки запускаются по характеру изменения; чистые CSS-правки проверяются сборкой и браузером, а не тестами, повторяющими CSS.
  • Несвязанные пользовательские файлы и прототипы сохраняются. Рабочие данные и секреты не используются как место реализации.
  • Результаты реально выполненных проверок записываются при реализации. Не отмечать задачи выполненными по результатам чтения документации или QA mock-прототипа.

A. Подготовка и соответствие документации

Зависимость: нет. Выход — проверяемая исходная точка для оформления и сервисов.

  • T001 Сопоставить stage7 текущему коду и исправить несовместимые примеры/контракты.
    • Матрица охватывает файловую модель, query/content, visibility, layout/schema Entry, маршруты, csrf/etag, preview, release, DB/MCP-заготовки. Примеры проверены в временной копии сайта.
  • T002 Сопоставить ADR и зафиксировать границы 001 в документации stage7.
    • История сохранена; реализованные решения отделены от предложений; новые кандидаты/медиа/RBAC/заявки/MCP отнесены к следующей очереди.
  • T003 Подготовить изолированное окружение и выполнить исходные тесты, validate и build.
    • Зафиксированы команды, результаты и реальные ограничения окружения. Включены server/dev-зависимости; подготовлен способ запускать HTTP/browser QA.
  • T004 Зафиксировать визуальные эталоны рабочих экранов и тестовые состояния.
    • Использованы выбранные HTML/CSS; сохранены проверки desktop/mobile, пустых состояний, ошибок, формы входа и данных сайта-примера.
  • T041 Поставить локальный htmx из flexly-estimator и проверить существующее подключение.
    • Побайтовая копия 2.0.11, SHA-256 совпадает с источником и VENDOR.md; лицензия/источник записаны, статическая раздача и wheel проверены. Это не реализация API или нового редактора.
    • Проверено 2026-11-12: node --check; 62 теста обработчиков/редактора и 2 теста упаковки, включая сборку wheel; HTTP smoke через настоящий FastAPI/TestClient (файл/MIME/nosniff, вход, hx-boost-разметка, CSRF/422, конфигурация и allowlist).
    • Тесты обработчиков/редактора запускались на временной копии примера без .engine: исходный запуск упёрся в недоступный рабочий .engine/audit.jsonl. Рабочие данные и права не менялись. На момент подготовки T041 исполнение htmx в браузере ещё не проверялось; итоговые T023/T032 закрыты реальными Chromium-сценариями, см. verification.md.

B. Оформление рабочих экранов

Зависимость: T001–T004. Этап завершается до перехода к новому общему буферу.

  • T005 Перенести стили, токены и ресурсы Antirion Rework в runtime-пакет.
    • Shell/editor/publication не конфликтуют; светлая палитра по умолчанию и тёмная палитра Antirion согласованы; работа не зависит от design/ на сервере.
  • T006 Реализовать общий shell, адаптивную навигацию, диалоги и UI-настройки.
    • Клавиатура, фокус, открытие/закрытие мобильного меню, Esc, возврат фокуса; localStorage содержит только настройки интерфейса.
  • T007 Перенести вход, обзор, сообщения и пустые состояния.
    • Реальные статусы сайта/релиза, ошибки входа и недоступного сайта; сохранены текущие защитные заголовки и cookie.
  • T008 Перенести списки Page/Entry, поиск, фильтры и просмотр свойств.
    • Проверены q/status/layout, вложенные ID, пустая выдача, выбранный объект и неизвестный ID; представлены реальные file/layout/count/current.
  • T009 Перенести формы Page, Block и Entry и существующие операции блоков.
    • Сохранены имена полей и URL, создание draft, слоты/привязки, добавление/порядок/видимость/удаление и семантика формы без изменений.
  • T010 Перенести существующие публикацию, историю и откат с подтверждениями.
    • В UI отражены реальные build+publish и rollback; кандидат/diff не имитируются; ошибки сборки и отсутствие релизов отображаются.
  • T011 Исправить CSP iframe и защищённые ассеты workspace.
    • Браузер загружает пассивное превью; изображения и зависимые ресурсы берутся из workspace; traversal/выход по symlink отклоняется; binary MIME корректен.
  • T012 Сохранить пользовательские значения при 409/422 на существующих формах.
    • Ошибка не теряет ввод, не выдаёт новый ETag за согласие перезаписать файл и не запускает повторный POST автоматически.
  • T013 Принять оформление рабочих экранов по AC-01, AC-08, AC-09 и упаковочной части AC-10.
    • Выполнены подходящие существующие тесты, реальные HTTP/browser-сценарии, адаптивная проверка и проверка wheel со статикой/шаблонами.

Контрольная точка B: существующие операции работают в новом оформлении. Новый буфер и интерактивное превью ещё не считаются выполненными.

C. Общие сервисы и файловая запись

Зависимость: T013. Новые сервисы сохраняют действующие файловые контракты.

  • T014 Определить снимки документов, результаты буфера/сохранения/конфликта и контекст автора.
    • Использованы dataclass/Report; сервис не зависит от Request/Jinja, автор получен из проверенной сессии.
  • T015 Реализовать обновление файла с одним владельцем SiteLock.
    • CAS и актуальная validation находятся внутри цикла обновления; нет вложенного lock/deadlock; отказ не создаёт историю или частичный файл; два писателя проверены.
  • T016 Выделить PageService и перевести операции Page/Block на него.
    • Чтение, создание, metadata, props, add/delete/toggle/move используют общий validation/save; аудит без дублирования, старые маршруты совместимы.
  • T017 Выделить EntryService и перевести операции Entry на него.
    • Поля коллекции, статус и Markdown проходят общую проверку; идентичность записи и запрет записи кода сохраняются.
  • T037 Реализовать основу версионированного JSON API FastAPI и схемы контракта.
    • Зависимость: T014–T017. Явные маршруты /admin/api/v1/, Pydantic request/response и error envelope, текущее чтение/создание/изменение документов, пассивное превью и publish/rollback; защищённые OpenAPI/docs и выгрузка схемы. DTO буфера определены; операции развиваются в T019/T020, интерактивное превью — в T026. Dataclass-ядро сохранено.
  • T038 Реализовать серверный API-клиент UI и внутреннюю авторизацию.
    • Зависимость: T037. httpx включён в server extra; ASGITransport вызывает то же приложение с общим lifespan, синхронные операции не блокируют event loop; credentials связаны с автором/сессией/epoch и не попадают в браузер или логи.
  • T039 Перевести существующие UI-операции на единый API-клиент.
    • Зависимость: T038. Списки/обзор, Page/Block/Entry, validation, превью и publish/rollback используют контракт API; HTML-маршруты сохраняются, ошибки API не обходятся прямым вызовом сервисов. Вход/сессия/статика остаются в UI.
  • T040 Проверить API-контракт и реальное прохождение UI → API по AC-11.
    • Зависимость: T037–T039. Реальный FastAPI проверяет реализованные операции: request/response/OpenAPI, единые 401/403/404/409/422, авторство, эпоху/logout, разграничение JSON/HTML и отсутствие обхода при ошибке API. Проверки расширяются в T024/T030/T032; полная приёмка AC-11 выполняется после редакторов/превью.

D. Буфер, Конструктор и «Эксперт»

Зависимость: T014–T017, T037–T040. Изменение буфера не означает сохранение файла.

  • T018 Отклонять повторяющиеся ключи YAML и проверить безопасный разбор.
    • Покрыты вложенные дубли, aliases, лимиты, запрещённые выражения и корректный текущий сайт; ошибка не приводит к потере текста.
  • T019 Реализовать получение, проверку и transform буфера без записи.
    • HTML-endpoints под /admin/editor/ вызывают JSON API через клиент; проверены сессия/Origin/CSRF на UI, credentials на API, вложенные ID, схемы, типизированные действия и прежний ETag основы.
  • T020 Реализовать явное сохранение полного исходника с ETag, историей и аудитом.
    • API save и HTML-адаптер используют общий контракт; Page/Entry сохраняются одной операцией; slug/path/fixed нельзя изменить в обход правил; клиент получает сохранённый source и новый ETag.
  • T021 Реализовать общий буфер Конструктора и «Эксперта», дерево и встроенный инспектор.
    • Constructor выбран по умолчанию, Entry использует схему коллекции, layout/display показываются read-only, неприменимый source остаётся в редакторе.
  • T022 Реализовать подтверждения внутренних переходов с несохранёнными правками через окна интерфейса, скачивание исходника и разрешение 409. Нативные alert/confirm/prompt и beforeunload-диалоги не использовать.
    • Переход режима/документа и уход не отбрасывают правки; две версии доступны; принятие новой основы явно; повторный конфликт обрабатывается.
  • T023 Настроить htmx и обработку согласованных частичных ответов редактора.
    • Локальная библиотека поставлена в T041; нет inline-выражений/eval/скриптов из ответов и сторонних запросов; 409/422 направляются в нужный регион, не очищают буфер; устаревшие revision игнорируются; истечение сессии и полная форма Save работают по AC-12.
  • T024 Принять сервисы и редакторы по AC-02–AC-05.
    • Проверены semantic round-trip, сохранение исходника без правок, вложенные слоты, refs/query, Entry, отсутствие файловых изменений до Save и реальный CAS двух вкладок.

Контрольная точка D: работают общий буфер и ручное сохранение; подготовка интерактивного превью не подменяется mock-iframe.

E. Интерактивное превью

Зависимость: T019–T024. Приёмка требует двух действительных origin.

  • T025 Добавить SITE_ADMIN_ORIGIN/SITE_PREVIEW_ORIGIN и отдельное приложение превью.
    • Валидируются разные точные origin; приложение не имеет admin/login; описан запуск вторым процессом/контейнером, пассивный режим сохранён при отсутствии конфигурации.
  • T026 Реализовать временный рендер буфера, ассеты, токены и очистку.
    • API preview и HTML-адаптер возвращают PreviewResult; 600 секунд, подпись с отдельным назначением ключа, привязка к снимку/epoch, проверка каждого ресурса, последние 20 снимков документа/сессии, очистка и маскирование токенов в логах.
  • T027 Добавить preview-маркировку Renderer с различимыми областями блоков.
    • Page/layout/display и вложенные блоки адресуются однозначно; fixed read-only; лишние контейнеры не меняют layout; обычный рендер не маркируется.
  • T028 Реализовать служебный скрипт и двусторонний протокол сообщений.
    • Точные origin/source, разрешённые типы, snapshot/revision и блоки проверяются; CSP/sandbox допускают только нужное поведение; wildcard отсутствует.
  • T029 Связать превью с деревом и инспектором, сохранить viewport и порядок обновлений.
    • Клик preview без scroll, дерево скроллит только при необходимости, изменение props не сбрасывает позицию; hidden/fixed/deleted и быстрые последовательные правки обработаны.
  • T030 Выполнить security-проверки превью по AC-07.
    • Проверены неверный/истёкший/отозванный токен, чужой снимок, logout, traversal/symlink, поддельные сообщения, запрет admin/login и исполнения скриптов сайта.
  • T031 Проверить живое превью буфера и неизменность публичной сборки по AC-06/AC-10.
    • Используется новый ассет workspace без публикации; canonical/current не меняются; истечение токена/сбой сервиса не теряет буфер; обычный HTML не содержит bridge/служебных атрибутов.

F. Сквозная приёмка и документация

Зависимость: T005–T031, T037–T041.

  • T032 Выполнить сквозные сценарии через реальное FastAPI и браузер.
    • Вход/истечение сессии, Page/Entry, режимы, validate/Save/409/422, preview, publish/rollback; настоящий htmx и ASGI-клиент, AC-11/AC-12; результат приложен отдельно от тестов подставного FastAPI.
  • T033 Проверить размеры, клавиатуру, фокус, ошибки и reduced motion.
    • 1440/1280/1024/768/390/360 px, палитры Antirion, мобильное меню, таблицы, диалоги, инспектор и отсутствие переполнения страницы.
  • T034 Выполнить регрессию, validate/build и проверку установленного wheel.
    • Установленный пакет содержит все runtime-ресурсы, работает без design/, сохраняет существующие гарантии CLI/core/build/security.
  • T035 Обновить README, AGENTS.md, stage7 и инструкцию запуска превью.
    • Документация соответствует фактическому состоянию, описывает env, два origin, состояние/очистку токенов, backup тестового сайта и воспроизводимый локальный/Docker-запуск.
  • T036 Сопоставить результаты с FR-01–FR-20, NFR-01–NFR-06 и AC-01–AC-12.
    • Приложены результаты и ограничения; незавершённые пункты остаются открытыми; 001 не объявляется готовой по одному визуальному сравнению.

Матрица требований и задач

Требования Основные задачи Приёмка
FR-01–FR-03 T004–T008, T033 AC-01, AC-09
FR-04–FR-05 T009–T013, T022–T023 AC-01, AC-04, AC-05
FR-06–FR-07 T014–T017, T019–T020 AC-02–AC-05
FR-08–FR-10 T015–T024 AC-02, AC-03, AC-05
FR-11–FR-13 T018–T024 AC-02, AC-04, AC-05
FR-14–FR-16 T025–T031 AC-03, AC-06, AC-07
FR-17 T027, T031, T034 AC-10
FR-18–FR-19 T014–T017, T037–T040, T032 AC-11, AC-12
FR-20 T019–T023, T032, T041 AC-03–AC-05, AC-12
NFR-01–NFR-02 T003, T009–T020, T025–T030, T032, T034 AC-01, AC-07, AC-08
NFR-03–NFR-04 T004–T006, T021–T023, T029, T033 AC-09
NFR-05–NFR-06 T011–T015, T020, T026, T031, T034–T036 AC-03, AC-05, AC-08, AC-10

Релизы, медиа/настройки, доступы, заявки и MCP следующей очереди не входят в список выполнения 001. Их порядок и зависимости перечислены в конце plan.md.

Прежняя функциональная проверка (визуальная приёмка открыта повторно)

2026-11-12: 239 тестов; настоящий FastAPI/ASGITransport; 25 сценариев Chromium на двух origin; 8 экранов и 60 проверок ширины, обе темы, клавиатура и reduced motion; validate/build примеров stage7 — 0 ошибок/0 предупреждений, 7 страниц; wheel установлен вне checkout без design/. Подробная матрица требований, команды и ограничения — verification.md; машиночитаемые результаты — qa-results.json.

Этапы 1–2 приняты пользователем. Этап 3 (Конструктор/Эксперт Page) подготовлен к проверке: исходные компоненты builder-antirion, реальные дерево/инспектор/каталог/источники, автоматическое применение полей и явное сохранение, дублирование поддерева, перетаскивание, 422 без потери ввода, сравнение/отмена/форматирование исходника. 247 тестов; Chromium — 12 сравнений Конструктора и 6 «Эксперта», 11 групп сценариев; регрессия editor/shell/pages, CLI и установленного wheel — OK. Подробности — design-transfer.md. Этапы 4–5 и общая визуальная приёмка T033/T036 остаются открытыми; переход — после проверки пользователя.