# Технический план 001 — Antirion Rework Дата: 2026-11-12. Статус: функциональная реализация проверена, визуальная приёмка открыта повторно. [Порядок переноса оригинальной вёрстки с проверкой пользователя](design-transfer.md). Действующие маршруты и запуск — [runtime.md](runtime.md); этот документ сохраняет этапы и обоснование архитектуры. Основание: [спецификация](spec.md). Учёт выполнения: [задачи](tasks.md). ## 1. Подход и границы Выполнить два последовательных результата: сначала новое оформление существующей админки, затем сервисы и общий буфер редакторов с интерактивным превью. Контрольные точки обязательны перед переходом к следующему результату. Сохранить `core/`, `parsing/`, `storage/`, `services/`, `web/`, dataclass-модели и файловые контракты. Развивать существующие модули без переименования всего пакета в слои из предложенной структуры stage7. Один администратор остаётся в `AuthService`; контекст автора создаётся на сервере. SQLite/RBAC, новый release pipeline и MCP не являются зависимостями 001. Принять подход flexly-estimator: браузер/htmx → HTML UI FastAPI → серверный API-клиент → JSON API FastAPI → прикладные сервисы. `web/admin/api_client.py` предоставляет методы предметных операций; транспорт — `httpx.AsyncClient` с `ASGITransport(app=...)`. Сетевой порт для внутреннего вызова не требуется, но авторизация, сериализация и валидация FastAPI выполняются. Lifespan инициализирует зависимости один раз в основном приложении; ASGITransport не запускает его повторно. Пока выполняется оформление этапа B, допускается действующий прямой вызов сервисов из старых обработчиков. Этапы C–D переводят чтение данных и операции контента, превью и публикации на API-клиент. Аутентификация UI, загрузка локальной статики и рендер шаблонов остаются в UI. CLI и будущий MCP могут обращаться к сервисам напрямую. Отдельное развёртывание UI/API не требуется для 001; клиент изолирует транспорт для будущего расширения. ## 2. Аудит и документация — этап A Сопоставить stage7 с `core/models.py`, `core/values.py`, `core/registry.py`, `core/draft_check.py`, `services/content.py`, `services/publish.py`, `web/admin/editor.py` и текущими тестами. В stage7 пометить каждую возможность как реализованную, доработку 001 или следующую очередь. Исправить примеры Page/Entry относительно схем сайта-примера: query wrapper, `richtext.content`, доступный layout и поля коллекции. При проверке примеров использовать временную копию сайта, а не рабочие данные. Сопоставить номера ADR и сохранить историю предложений. Не объявлять все предложенные ADR принятыми автоматически. Проверить актуальность AGENTS.md: HTML использует `etag`, сервис — `if_match`; принято направление htmx → UI → JSON API. Эти сведения уже зафиксированы. Описание интерактивного превью обновить после его реализации, сохранив требования к безопасности. Подготовить изолированное окружение через доступный `uv`, установить extras `server,dev` и средства browser QA. Выполнить исходные проверки и сохранить вывод. Если установка или тест недоступны, записать конкретную причину без объявления проверки успешной. **Выход:** актуальная матрица расхождений, проверяемые примеры, исходные результаты тестов, визуальные эталоны по выбранным HTML/CSS. ## 3. Оформление рабочих экранов — этап B ### 3.1. Runtime-ресурсы и шаблоны Разместить CSS/JS в `src/site_engine/web/admin/static/`, общие Jinja-компоненты и шаблоны — в `web/admin/templates/`. Согласовать токены Antirion из shell, builder и publication; стили отдельных экранов ограничить их контейнерами, чтобы правила таблиц и форм не конфликтовали. Общие компоненты: shell, боковое меню, верхняя панель, заголовок, статус, таблица, поле формы, диагностика, пустое состояние, диалог и уведомление. JS подключать внешним локальным файлом; inline event handlers и inline-стили прототипа перенести в разрешённые механизмы. Светлая палитра — исходная; предусмотренное Antirion переключение светлой/тёмной палитры реализовать общими токенами. Хранить только UI-предпочтение. Скругления/палитру Rose Graphite не переносить. Сохранить обычные формы и полноценную навигацию до внедрения новых редакторов. Статические ресурсы выдаются по allowlist с корректными MIME. Уточнить package-data для вложенных partials и будущих ресурсов превью; установленный пакет не читает `design/`. `static/htmx.min.js` версии 2.0.11 уже перенесён побайтно из flexly-estimator; источник, лицензия 0BSD и SHA-256 находятся в `static/VENDOR.md`. Для обновления проверять новый дистрибутив и обновлять запись; установка Node и загрузка CDN в runtime не нужны. Эта поставка не закрывает задачи нового редактора или API. ### 3.2. Представления и данные Последовательно перенести вход, обзор, списки, формы Page/Block/Entry, публикацию, сообщения и пустые состояния. У входа нет отдельного прототипа: использовать те же токены и компоненты формы без копирования shell защищённого раздела. Данные получать из Registry и действующих сервисов. Добавить эффективный layout, файл, число блоков, статусы и current build. Поиск/фильтры реализовать через GET-параметры `q`, `status`, `layout` (последний только для Page). Неверные значения фильтра не расширяют доступ и отображаются как ошибка запроса. Выбранный объект идентифицируется по проверенному ID; отсутствие выбора даёт пустой инспектор. Счётчики «изменено относительно live», diff, время/автор релиза показываются только при наличии реальных данных. В 001 не вычислять их из вымышленных seed-моделей или времени изменения файлов. Новые разделы прототипа до реализации получают объяснение недоступности, без маршрутов фиктивного CRUD. `/admin/publish` продолжает выполнять существующие publish/rollback. Добавить подтверждение действия и реальные состояния успеха/ошибки. Кандидат релиза не появляется до спецификации 002. ### 3.3. Исправления интеграции - Для существующего iframe явно добавить `frame-src 'self'`, сохранив ограничения `frame-ancestors` админки и sandbox превью. - Для пассивного превью предоставить авторизованную раздачу ассетов workspace из разрешённого `assets/` с safe path, nosniff и ограничивающим CSP. Обновить URL в preview-рендере и CSS, включая вложенные ссылки ресурсов; публичная сборка сохраняет `/assets/...`. - Поддержать бинарные ответы ассетов, не декодируя изображение как текст. - При 422 повторно отрисовывать переданные значения; при 409 сохранить пользовательские поля и предоставить текущую версию без автоматического повторного POST. **Контрольная точка B:** AC-01, AC-08, AC-09 и упаковочная часть AC-10. Оформление не блокируется отсутствием отдельного preview origin: на этом этапе используется безопасное пассивное превью. ## 4. Прикладные сервисы и запись — этап C ### 4.1. Разделение ответственности | Слой | Ответственность | |---|---| | UI-роутер | Request/FormData, cookie, Origin/CSRF, вызов серверного API-клиента | | Обработчик UI | Сбор представления и partials из DTO API, статусы/редиректы, введённые значения | | API-клиент UI | Преобразование полей формы в JSON DTO, внутренний авторизованный вызов, разбор DTO/ошибок | | JSON API FastAPI | Явные маршруты и Pydantic DTO, проверенный автор, HTTP-коды и общий формат ошибок; без Jinja и HX-веток | | PageService / EntryService | Проверенный объект, создание/чтение, операции буфера, validation, сохранение и аудит | | ContentService / storage | Разрешённый путь, один lock, CAS, история, атомарная запись | | Core | Схемы, разбор/разрешение значений, дерево, валидация и рендер | Добавить `services/pages.py`, `services/entries.py` и общий модуль результатов редактора при необходимости. Формы `p.*` остаются представлением; прикладной сервис получает разобранные значения и не зависит от Request или Jinja. UI-роутеры, использующие AsyncClient, выполняются как `async def` и ожидают API-клиент. Из прежнего EditorHandlers выделить сборку представлений из DTO; не запускать отдельный event loop на каждый вызов и не выполнять вложенный синхронный HTTP-запрос к тому же uvicorn-процессу. ### 4.2. Внутренние контракты Использовать dataclass-результаты, сохраняя существующий Report/Issue: | Контракт | Обязательные данные | |---|---| | DocumentSnapshot | Тип Page/Entry, логический ID, относительный путь, исходник, модель, ETag, Report | | EditorContext | Проверенный Principal, IP/источник операции для аудита; создаётся адаптером | | BufferResult | Текущий исходник, последняя корректная модель или диагностика ошибки, ETag основы, номер редакции UI | | SaveResult | Сохранённый снимок и новый ETag | | ConflictResult | Переданный исходник, ETag основы и текущий серверный снимок | | PreviewResult | URL ограниченного снимка, срок действия, номер редакции UI | Общие возможности сервисов: `get`, `create`, `validate_source`, `transform_buffer`, `save_source`. PageService также применяет операции с блоками; EntryService проверяет поля коллекции. Превью использует тот же разобранный документ/Report, а не отдельный browser codec. ### 4.3. Транзакционная граница одного файла В ContentService добавить операцию обновления с владельцем блокировки. Под одним SiteLock: проверить путь → перечитать байты → проверить if_match/ABSENT → загрузить актуальную схему → подготовить изменение → проверить → сохранить предыдущую версию → atomic_write. Отдельная точка входа записывает уже подготовленный исходник через тот же цикл. Не вызывать публичный `write`, повторно захватывающий SiteLock, из участка с уже удерживаемой блокировкой. Старый интерфейс ContentService сохранить или адаптировать совместимо с тестами и текущими вызовами. При отказе до записи история и канонический файл не меняются. Аудит успешной операции формируется сервисом однократно, без второго события из старого обработчика. Ошибки журналирования не маскировать под успешное завершение; клиенту не предлагать слепой повтор с прежним ETag после уже состоявшейся записи. **Выход:** JSON API вызывает общие сервисы, старый UI переводится на API-клиент; существующие тесты сохраняют семантику, два писателя не теряют изменения. ### 4.4. JSON-контракт и внутренний клиент Разместить API-роутеры, схемы и зависимости в `src/site_engine/web/api/`; HTML-маршруты остаются в `web/admin/`. Добавить `httpx` в extra `server`, поскольку это runtime-зависимость API-клиента, а не только средство тестирования. Ядро и сервисные результаты остаются dataclass; Pydantic-модели на HTTP-границе явно преобразуются в них и обратно. Использовать `response_model` или аннотированные модели ответов, а не произвольные dict. Префикс API — `/admin/api/v1/`. UI сохраняет существующие URL и префикс `/admin/editor/` для HTML-фрагментов. Объявить API- и UI-маршруты до существующего catch-all редактора и до раздачи публичного сайта. Не подменять JSON на HTML при наличии HX-Request. | Операция | JSON API | |---|---| | Обзор и доступные коллекции | `GET /admin/api/v1/site`, `GET /admin/api/v1/collections` | | Списки/создание документов | `GET/POST /admin/api/v1/pages`, `GET/POST /admin/api/v1/entries/{collection}` | | Снимок Page | `GET /admin/api/v1/editor/pages/{id}/source` | | Буфер Page | `POST /admin/api/v1/editor/pages/{id}/{transform,validate,save,preview}` | | Снимок Entry | `GET /admin/api/v1/editor/entries/{collection}/{slug}/source` | | Буфер Entry | `POST /admin/api/v1/editor/entries/{collection}/{slug}/{transform,validate,save,preview}` | | Релизы и текущая публикация | `GET /admin/api/v1/releases` | | Текущие publish/rollback | `POST /admin/api/v1/publish`, `POST /admin/api/v1/rollback` | Фигурная группа действий обозначает отдельный явный маршрут для каждого действия. Вложенные ID Page с `/` поддерживаются и проверяются по Registry; маршрут не принимает произвольный файловый путь. Списки принимают те же q/status/layout, что UI. Create возвращает 201 и DocumentSnapshot; чтение/transform/validate/save/preview — 200 с соответствующим DTO. Старые Publish/rollback сохраняют прежний контракт действующих сервисов. Новый candidate workflow повторного этапа 5 описан в publication-backend.md. DTO запросов буфера: `source`, `etag`, `revision`; transform дополнительно содержит дискриминированное типизированное `action`. `revision` — неотрицательное целое, возвращаемое без изменения, `etag` — прежний непрозрачный маркер версии. Схемы запрещают неизвестные служебные поля; пользовательские props проверяет действующая схема фрагмента/коллекции. В JSON не передаются csrf, Principal или произвольный путь записи. Ответы соответствуют DocumentSnapshot/BufferResult/SaveResult/ConflictResult/PreviewResult из раздела 4.2. Модель документа передаёт только сериализуемые разрешённые данные, включая типы значений и дерево; Python-объекты и пути вне сайта не выдаются. Ошибка имеет форму `error: {code, message, issues, revision}`; issue содержит code, message и field/path, если применимо. Для 409 дополнительно передаются `submitted_source`, `base_etag`, `current` (DocumentSnapshot). Для ошибок схемы запроса и предметной валидации использовать один envelope, сохраняя различимые коды. HTTP-статусы: 401 — нет действительных внутренних credentials, 403 — запрещённая операция, 404 — объект отсутствует, 409 — конфликт, 422 — недопустимый запрос/документ. Недопустимый буфер validate возвращает 422 с диагностикой; валидный неполный draft — 200 с предупреждениями. Ошибки 5xx не содержат трассировки; UI сохраняет введённые данные, сообщает о сбое и не выполняет альтернативную запись напрямую. Pydantic-схемы служат источником OpenAPI. Добавить воспроизводимую выгрузку схемы для CI; доступ к HTTP-схеме `/admin/api/v1/openapi.json` и документации `/admin/api/v1/docs` разрешить только проверенной админской сессии. Скрытие docs не заменяет авторизацию API. Тесты проверяют маршруты, модели успешных ответов, envelope ошибок и версию контракта; не требуется отдельная сборка TypeScript-клиента. ### 4.5. Автор и авторизация между UI и API UI сначала проверяет действующую cookie, Origin и CSRF, включая validate/transform/preview без канонической записи. API принимает только серверные credentials, связанные с проверенным администратором, сессией и auth epoch. Наличие /admin в URL или заголовка HX-Request не даёт доступа; одна cookie браузера не авторизует JSON API. Внутренние токены создаёт сервер после проверки сессии, хранит в памяти процесса и ограничивает сроком этой сессии. ASGITransport вызывает тот же экземпляр приложения. Logout/изменение эпохи и истечение сессии проверяются на API-границе, не только в UI; после перезапуска прежние внутренние токены недействительны. Клиент передаёт авторизованный audit-контекст; login/epoch/IP нельзя брать из полей формы или копировать из произвольных входящих заголовков. Токены, cookie и исходник не попадают в журналы запросов. API-ключ не включается в HTML, JS, URL или browser storage. В 001 не добавлять внешние API-ключи, scopes или настройки внешнего деплоя UI: это отдельное развитие. Файловые операции и рендер остаются синхронными; JSON-адаптер выполняет их в пуле потоков, не блокируя event loop вложенного ASGI-вызова. ## 5. Буфер и редакторы — этап D ### 5.1. Жизненный цикл ```text GET документа → source + base_etag + корректная модель → изменение поля / исходника → server validate/transform → новый буфер, прежний base_etag → preview → временный результат, прежний base_etag → явное Save → CAS + validation + history + write → новый source + новый base_etag, буфер отмечен сохранённым ``` Состояния UI: сохранён, есть несохранённые правки, проверяется, ошибка исходника, сохраняется, конфликт. Полнота для публикации показывается отдельно от допустимости сохранения draft. Проверка без правок не меняет dirty-состояние. При переключении режима валидный source становится представлением той же модели. Невалидный source остаётся в «Эксперте»; доступны исправление, скачивание текста и явный отказ от правок. Без пользовательского действия не возвращать другую версию документа. При внутреннем переходе к другому документу подтверждать потерю несохранённых правок через окно интерфейса. Не использовать нативные alert/confirm/prompt и beforeunload-диалоги; отдельного подтверждения пересборки YAML нет. ### 5.2. HTTP-интерфейс Существующие страницы `/admin/pages/{id}` и `/admin/content/{collection}/{slug}` сохраняются. В новом редакторе GET-параметр `mode=constructor|expert` задаёт представление; значение по умолчанию — constructor. Добавить внутренние endpoints под отдельным префиксом, чтобы вложенный ID Page не конфликтовал с прежней адресацией: | Действие | Page | Entry | |---|---|---| | Получить исходник | `GET /admin/editor/pages/{id}/source` | `GET /admin/editor/entries/{collection}/{slug}/source` | | Изменить буфер | `POST /admin/editor/pages/{id}/transform` | `POST /admin/editor/entries/{collection}/{slug}/transform` | | Проверить | `POST /admin/editor/pages/{id}/validate` | `POST /admin/editor/entries/{collection}/{slug}/validate` | | Сохранить | `POST /admin/editor/pages/{id}/save` | `POST /admin/editor/entries/{collection}/{slug}/save` | | Подготовить превью | `POST /admin/editor/pages/{id}/preview` | `POST /admin/editor/entries/{collection}/{slug}/preview` | Это HTML-маршруты UI. Каждый вызывает одноимённую операцию JSON API из раздела 4.4 через серверный клиент; UI не обращается к Registry/ContentService для выполнения этих операций. Все POST UI требуют существующие сессию, проверку источника и `csrf`, включая операции без записи. Общие поля формы: `source`, `etag`, `revision` (номер изменения в UI); transform также передаёт типизированное действие и его значения. ID с `/` разбирается как логический ID Page и сверяется с реестром на API/сервисной границе до доступа к файлу. Типы transform: метаданные Page, поля/статус/Markdown Entry, props/настройки блока, add/delete/toggle/move блока. Для перемещения использовать ID и `before`/`after` внутри указанного региона/слота; сохранять проверку allow, fixed, предельной вложенности и отсутствия циклов. Кнопки порядка остаются доступны с клавиатуры; drag-and-drop не является отдельным требованием 001. HTML-ответы UI: 200 — partials и актуальное состояние буфера; успешный Save — сохранённое состояние (для полной формы допустим 303); 409 — панель сравнения с обеими версиями; 422 — исходник и диагностика. Остальные коды сохраняют смысл действующей админки. JSON API предназначен серверному клиенту UI; анонимный/внешний API не открывается. Частичные ответы включают согласованные дерево, инспектор, исходник, диагностику и статус. Каждому ответу соответствует revision; устаревшие ответы игнорируются. Отправка Save блокирует конкурирующее повторное нажатие, но отказ сети сохраняет буфер и позволяет проверить серверную версию перед повтором. ### 5.3. Реализация UI и конфликтов Использовать поставленную локальную версию htmx с лицензионным уведомлением. Настройки `allowEval=false`, `allowScriptTags=false`, `selfRequestsOnly=true`, `includeIndicatorStyles=false`, `historyCacheSize=0` задавать без inline JS, не использовать inline hx-on. История htmx не должна сохранять HTML с контентом/CSRF в localStorage. Разрешить подстановку ожидаемых 409/422: htmx по умолчанию их не подставляет. UI задаёт HX-Retarget/HX-Reswap для области диагностики или панели конфликта, а не заменяет редактор общей страницей ошибки. Сбой 5xx/сети сохраняет буфер и отображается внешним JS. Для истёкшей сессии UI возвращает HX-Redirect на вход при htmx-запросе и 303 при обычной навигации. Нельзя молча заменить инспектор HTML-формой входа; перед потерей dirty-буфера предложить скачивание исходника. После Save обновлять состояние редактора без обязательного полного перехода страницы, который используется в estimator. Основные операции сохранения доступны обычной формой; интерактивное превью требует JS. Небольшой внешний JS-модуль отвечает за буфер, debounce/порядок запросов, защиту от устаревших revision, dirty-состояние, фокус/выделение и postMessage превью. htmx отвечает за отправку форм и подстановку согласованных HTML-фрагментов, в том числе OOB для дерева/статуса при необходимости. Буфер не пересоздаётся при замене инспектора. Сохранить текущие лимиты YAML; запретить повтор ключа вместо молчаливой перезаписи SafeLoader. Валидатор исходника использует те же ограничения, что Конструктор. Не допускать изменение Entry.slug или запись по пути из тела формы. Неподдерживаемый ключ не отбрасывается для получения формально успешного сохранения. 409 не меняет буфер и base_etag. Панель сравнивает пользовательский текст с текущим source; действия — принять серверную версию либо вручную объединить и явно подтвердить использование новой основы. После этого повторный Save снова проходит CAS; третье изменение на сервере вновь даёт 409. **Контрольная точка D:** AC-02–AC-05. Проверять Page с вложенными слотами и привязками, а также Entry со схемой коллекции и Markdown. ## 6. Интерактивное превью — этап E ### 6.1. Конфигурация и развёртывание Добавить проверяемые полные URL-origin `SITE_ADMIN_ORIGIN` и `SITE_PREVIEW_ORIGIN`: схема, host и необязательный порт без пути/query/fragment. Для интерактивного режима оба обязательны и различаются. В production использовать HTTPS; локально допустим HTTP на loopback. Локальный пример: admin `http://localhost:8000`, preview `http://localhost:8001`. Production-пример: `https://cms.example.com` и `https://preview.example.com`. Origin включает порт; CORS-доступ к админке для preview не открывать. Добавить отдельную фабрику приложения превью, запускаемую вторым uvicorn-процессом или отдельным контейнером того же образа. Она читает только подготовленные артефакты и необходимые параметры проверки токена/эпохи, без подключения admin router. Preview-контейнеру достаточно read-only доступа к каталогу подготовленных снимков и auth epoch; исходники сайта и возможность их записи ему не требуются. При неполной конфигурации новые редакторы сохраняют возможность работы и пассивное превью; интерактивный режим показывает недоступность с причиной конфигурации. Для закрытия этапа E требуется рабочая проверка на двух origin. ### 6.2. Снимок и токен В авторизованном основном приложении разобрать буфер, наложить документ на временное представление Registry и отрендерить HTML. Копирование изменённой Page/Entry в канонический каталог для превью запрещено. Подготовить необходимые ассеты и зависимые CSS-ресурсы из workspace в служебном `SITE_STATE_DIR/preview/`. Снимок после выдачи URL неизменяем. Он содержит HTML, ассеты, карту разрешённых блоков, revision, срок и служебные данные авторизации. Токен — криптографически случайный идентификатор с подписью; подпись использует отдельный производный ключ, отличный от назначения подписи сессий. Срок — 600 секунд, токен привязан к одному снимку и текущему auth epoch. Проверять доступ к HTML и каждому ассету. Токены/исходники не записывать в аудит и диагностические сообщения; журнал доступа к preview должен маскировать токен в URL. Удалять просроченные/незавершённые артефакты при обслуживании основным приложением и при запуске. Ограничить число сохранённых снимков одного документа одной сессии последними 20; удалённый снимок корректно отвечает отказом доступа, редактор может запросить новый. ### 6.3. Браузерная изоляция В iframe использовать sandbox `allow-scripts allow-same-origin` только при гарантированно отдельном origin. Это сохраняет проверяемый origin сообщений; сочетание этих разрешений для same-origin превью запрещено. Формы, popups и top navigation не разрешаются. CSP preview: разрешён только служебный скрипт с nonce, собственные подготовленные изображения/шрифты и стили рендера; код сайта не включается в JS-бандл превью. `frame-ancestors` ограничен SITE_ADMIN_ORIGIN, `form-action 'none'`, `base-uri 'none'`, `Referrer-Policy: no-referrer`, `Cache-Control: no-store`, nosniff. `X-Frame-Options: SAMEORIGIN` на cross-origin preview не переносится. Админка разрешает frame-src только собственный origin для пассивного превью и настроенный preview origin. ### 6.4. Маркировка и протокол Добавить явный preview-mode Renderer, по умолчанию выключенный. Идентификатор блока включает область page/layout/display, владельца и локальный block ID. Маркировка не добавляет контейнеров, меняющих layout. Для fixed/display-блока действие выбора возвращает read-only инспектор. Минимальные сообщения: | Направление | Типы | Назначение | |---|---|---| | Preview → admin | ready, select, viewport | Готовность, выбранный блок, положение/размер viewport | | Admin → preview | highlight, navigate, restore | Выделение, переход по выбору дерева, восстановление позиции | Сообщение содержит ID снимка, revision и разрешённый идентификатор блока, если нужен. Обе стороны проверяют origin, source окна, структуру, текущий снимок и допустимый тип. Не использовать wildcard targetOrigin. Предварительный обмен ready инициируется preview в известный admin origin. При refresh сохранить viewport через служебный скрипт; после ready нового снимка восстановить положение и выделение. Навигацию к новому месту выполнять для явного выбора/добавления/перемещения, а не на каждое изменение поля. Учитывать reduced motion. Ответ предыдущей revision не заменяет свежую. **Контрольная точка E:** AC-06, AC-07 и публичная часть AC-10/FR-17. ## 7. Проверки и поставка — этап F | Уровень | Обязательная проверка | |---|---| | Существующие тесты | Ядро, сборка, routes, auth, редактор, формы, история, конфликты и упаковка | | Сервисы | Общая валидация, один lock без deadlock, CAS двух писателей, отказ без записи/истории, аудит один раз | | Буфер | Page/Entry round-trip, вложенные слоты, refs/query, ошибки YAML/дубли, режимы, сохранение всего документа | | JSON API | Реальные маршруты и Pydantic request/response, OpenAPI, envelope ошибок, недействительные credentials/epoch, проверенный автор, UI использует ASGITransport без обхода API | | HTTP/UI | Реальный FastAPI: cookie/CSRF/Origin, старые и новые маршруты, вложенные ID, HTML отдельно от JSON, 409/422 с вводом, binary assets | | Preview security | Два origin, срок/подпись/эпоха токена, подмена снимка, traversal/symlink, spoofed messages, отсутствие admin/login | | Browser | Настоящий htmx: partial swap, CSRF, 409/422, HX-Redirect и отсутствие API-ключа; dirty-buffer, конфликт, selection/scroll, быстрые правки, истечение токена, недоступность preview | | Visual/accessibility | Заданные ширины, клавиатура, focus, диалоги, статусы, палитры, reduced motion | | Packaging/build | Wheel, запуск из установленного пакета, CLI validate/build и отсутствие служебного preview-кода в публичном HTML | Команды существующей проверки после подготовки окружения, из корня репозитория: ```bash PYTHONPATH=src python -m unittest discover -s tests -v PYTHONPATH=src python -m site_engine.cli validate examples/studio-site PYTHONPATH=src python -m site_engine.cli build examples/studio-site --out /tmp/studio-dist ``` HTTP/browser-проверки добавляются как воспроизводимые dev-команды; файлы тестов и зависимости включить в документацию. Сохранять снимки/логи QA отдельно от канонического сайта. В отчёте различать выполненные, упавшие и недоступные проверки. Результаты выполненной приёмки приведены в [verification.md](verification.md), действующий контракт и запуск — в [runtime.md](runtime.md). Этап B можно проверять и принимать до новых редакторов. Этап D принимается после сервисов C; завершение 001 требует E и F. Контентная миграция и миграция БД для 001 не нужны. Перед первым реальным сохранением новой версией редактора сделать резервную копию тестируемого сайта; deployment сначала проверить на его копии. ## 8. Следующая очередь спецификаций | Номер | Направление | Доработка и результат приёмки | |---|---|---| | — | Релизы — расширение | Надёжные фоновые jobs, реестр безопасных повторов, retention/recovery и связь с reviewed changeset. Build/publish, immutable candidate, hashes/diff и expected_live уже реализованы повторным этапом 5 в 001 | | 003 | Медиа, структура, настройки | Безопасная загрузка, файловые metadata, where-used, changeset с recovery до rename, меню/redirect/site/data/theme; перенос каталога не теряет метаданные | | 004 | Доступы и журнал | Пользователи, разрешения, миграции SQLite, сессии и audit UI; отказ прав проверяется сервисом, а не видимостью кнопки | | 005 | Заявки и outbox | Версия формы, submission+outbox одной транзакцией, Telegram/retry, PII grants; сбой доставки не теряет заявку и rollback сохраняет совместимость | | 006 | MCP | Те же сервисы и ошибки, узкие scopes, TTL/revoke, draft-only; отсутствие publish grant исключает публикацию | Это очередность отдельных работ. Их контракты и задачи не считаются реализованными или полностью специфицированными пакетом 001. ## Уточнение плана: повторный перенос Content (2026-11-17) Этап 4 опирается на исходный content-antirion и уже работающую очередь 003. Дополнение сервера: коллекции/зависимости, check, CAS duplicate/delete, entry manifest hashes/routes и настоящий Live/Page. Подробности и ограничения — [content-backend.md](content-backend.md), техническая приёмка — [verification-content.md](verification-content.md). После реализации требуется проверка пользователя до перехода к этапу 5. Новая схема хранения, Node frontend и серверное autosave для этого этапа не требуются. ## Уточнение плана: Publication (2026-11-17) Пользователь разрешил этап 5. Для оригинального publication-antirion потребовалось настоящее разделение build/activate и частное происхождение релиза. Это уточнение прежнего отнесения всего candidate/diff к следующей очереди. Реализация: PublicationService под SiteLock; build_site(activate=False); отдельные API/HTML endpoints; source/render/output hash и expected_live; пассивный snapshot релиза; исходные диалоги и видимые ошибки. Старые CLI/API/обычные формы совместимы. Контракт — [publication-backend.md](publication-backend.md), приёмка — [verification-publication.md](verification-publication.md). Более широкий workflow релизов/агентских changeset не входит в этап.