Референсные шаблоны комнат

FEAT-032 добавляет три неизменяемых контракта шаблонов версии 2.0.0. Первое развёртывание использует каталог Wave 2: существующие записи для создания комнат остаются активными до явной активации с защитными проверками. При запуске новый каталог никогда не активируется, а комнаты не переносятся.

Ревизии репозитория, размеры файлов и зафиксированные хеши SHA-256 лежат в packages/templates/src/product-room-definitions.ts. Прежние определения 0.1.0 и 1.0.0 не меняются. Трансформациями физических поверхностей управляет геометрия сцены, а ID и разрешёнными типами медиаобъектов — подписанный контекст шаблона.

Создание и редактирование

GET /api/templates возвращает активный каталог: версию, описание, фактический URL превью и значения по умолчанию. После активации в нём ровно три записи из таблицы выше. Control plane подставляет значения по умолчанию при выборе шаблона и запрашивает подтверждение, прежде чем заменить изменённые значения. Личному пространству нужен владелец; оно остаётся закрытым, гостевой доступ отключён, заметки изначально закрыты. В зале по умолчанию выбран вход с выключенным микрофоном. Явно заданные настройки звука и заметок сохраняются для каждой комнаты отдельно.

POST /api/rooms определяет активную версию на сервере и сохраняет её полный снимок и абсолютный URL сцены. Чтобы использовать текущую версию, не передавайте templateVersion или передайте именно эту версию. Не передавайте templateSnapshot и sceneBundleUrl референсной сцены. Создание комнаты напрямую через API и через control plane использует одну и ту же материализацию.

Ошибки:

Существующие комнаты старого формата можно редактировать, их зафиксированная версия и URL сцены сохраняются. PATCH для референсной комнаты меняет только разрешённые настройки комнаты и проекцию roomConfig в снимке. Заменить политику или сцену, которые принадлежат версии, он не может. Runtime проверяет манифест сцены и байты самодостаточного GLB до разбора и отрисовки; при ошибке контрольной суммы или отсутствии обязательной поверхности показывается явная диагностика перехода на резервную сцену.

Ассеты при самостоятельном запуске

По умолчанию ассеты берутся из jsDelivr по репозиторию и полному SHA коммита, поэтому их адреса неизменяемы. При необходимости задайте для API ROOM_TEMPLATE_ASSET_BASE_URL=https://mirror.example/scenes. Скопируйте побайтно идентичные файлы по пути:

<mirror-root>/<owner>/<repository>/<full-commit-sha>/<locked-relative-path>

Добавьте зафиксированный корневой manifest.json и все четыре файла пакета. Отдавайте их с CORS, доступным браузеру, правильными типами содержимого и неизменяемым кешированием. В production обязателен HTTPS. Учётные данные в URL, строки запроса, фрагменты и выход за пределы каталога отклоняются. Это хранилище не связано с хранилищем загрузок документов и сцен. Изменения зеркала влияют только на превью в каталоге и на будущие комнаты; существующие абсолютные URL комнат остаются зафиксированными и должны оставаться доступными.

Проверка у себя

Перед тестами пакетов выполните сборку. Используйте одноразовую базу PostgreSQL через VRATA_TEST_POSTGRES_URL; для репетиции с изменением данных укажите в VRATA_TEMPLATE_ROLLBACK_STORAGE_MODULE собранный модуль хранилища API из checkout той ревизии, на которую делается откат. CI собирает этот checkout автоматически. node tools/fetch-reference-template-fixtures.mjs скачивает и проверяет зафиксированные ассеты; изолированный референсный e2e использует отдельную схему PostgreSQL на каждый запуск и побайтно идентичное HTTP-зеркало.

Запустите pnpm build, pnpm lint, pnpm typecheck, pnpm test, шесть проверок зафиксированных шаблонов и сцен, а затем полный pnpm test:e2e. Если выбираете нестандартные тестовые порты, задайте не только E2E_API_PORT, но и BASE_URL, чтобы фикстуры браузера и фикстуры запросов обращались к одному серверу.