NODEDC_DESIGN_GUIDELINE/docs/MODULE_STUDIO.md

NDC Module Studio

Текущий living catalog эволюционирует в Module Studio без создания второго визуального приложения. Существующие разделы остаются Visual Library; рядом живут Page Library и Applications. Первый вертикальный срез не подключает Engine, Cesium, Authentik, Hub или Deploy.

Page Template contract v0.1

Канонические TypeScript-контракты и manifests находятся в @nodedc/page-patterns, машинно-читаемый реестр — в registry/pages.json.

Первый шаблон Map Page 0.1.0 формально фиксирует:

• template identity и pinned version;
• стартовую страницу и navigation defaults;
• разрешённые feature flags Inspector, Toolbar, Assistant;
• runtime-neutral slots points, traces, routes, zones, selection, commands, assistant;
• template-owned actions.

Шаблон не содержит Cesium token, Engine workflow, React component tree или свободные координаты элементов. Renderer/Cesium adapter и Capability Bindings являются отдельными следующими слоями.

Map Scene Fixture v0.1

Каноническая JSON Schema: registry/schemas/map-scene-fixture-v0.1.schema.json. Проверочные сцены перечислены прямо в контракте map@0.1.0 и лежат в registry/fixtures/map.

Fixture фиксирует provider-neutral viewport, capabilities, общие style profiles, слои, города, движущиеся объекты, станции, маршруты, пути, зоны, selection и ожидаемое поведение. Он не хранит Cesium types, токены, renderer instances, Engine workflow или transport payload конкретного источника.

map-operational-v0.1.json проверяет содержательную сцену и переиспользуемый язык подписей/маркеров. map-empty-offline-v0.1.json проверяет, что shell и системные действия остаются работоспособными без live-данных. Registry validation дополнительно проверяет уникальность id, ссылки на style profiles, selection и непрерывность LOD-диапазонов.

LOD вынесен в отдельный контракт registry/schemas/map-lod-policy-v0.1.schema.json и policy set registry/fixtures/map/map-lod-policies-v0.1.json. Он использует расстояние камеры в метрах, полуоткрытые диапазоны и hysteresis, поэтому не зависит от Cesium DistanceDisplayCondition. Дальнейшая калибровка bands выполняется на живом Map shell, а не в отрыве от визуального результата.

Application Manifest v0.1

Каноническая JSON Schema: registry/schemas/application-manifest-v0.1.schema.json.

Manifest фиксирует:

• identity, slug, draft status и версию;
• ссылку на конкретный Design Profile release (id + version + status + theme);
• хотя бы одну страницу и pinned page-template version;
• navigation visibility;
• только заранее разрешённые feature flags;
• favicon source;
• server-controlled timestamps.

Manifest не хранит runtime credentials, capability bindings, arbitrary component tree, свободные координаты элементов или deployment secrets.

Draft lifecycle

Catalog server предоставляет минимальный временный API:

• GET /api/applications — список drafts;
• GET /api/page-templates — получить канонический page registry;
• POST /api/applications — создать draft из явно выбранных templateId и templateVersion;
• GET /api/applications/:id — открыть draft;
• PUT /api/applications/:id — атомарно сохранить draft.

Файлы находятся в runtime-data/applications и исключены из Git. Этот store доказывает lifecycle create → save → reload → open; целевой production store позже принадлежит Platform application-core.

Согласованный UX Application Projects

• круглая кнопка + в заголовке Applications открывает модалку создания модуля;
• текущий модуль выбирается через Hub-style searchable selector, а не через плоский список проектов;
• root модуля содержит metadata, ссылку на один pinned Design Profile и Application Composition;
• Dark/Light, favicon, Glass и прочие визуальные параметры не настраиваются внутри модуля;
• две равные колонки Доступные страницы / Конфигурация приложения работают только с готовыми Page Templates;
• drag-and-drop меняет состав и порядок ссылок на шаблоны, но не создаёт свободный canvas;
• после сохранения страницы появляются в левой навигации и открывают визуальный preview;
• режимы Настройка / Предпросмотр разделяют Studio controls и поведение будущего приложения;
• удаление draft выполняется только через destructive confirmation modal.

Design Profile lifecycle

Каноническая JSON Schema: registry/schemas/design-profile-v0.1.schema.json.

Visual Library использует отдельный Hub-style selector профилей. Общая кнопка Save открывает каноническую модалку Сохранить / Сохранить как новый / Опубликовать. Приложение хранит pinned profile id + version + status + theme; media, favicon и material settings принадлежат Design Profile.

Draft — изменяемая рабочая голова профиля. Каждое сохранение увеличивает patch-версию. Published — неизменяемый снимок конкретной версии: повторная публикация той же версии запрещена. Application Manifest может ссылаться на draft для внутренней разработки, но стабильный модуль должен фиксировать published release. Изменение будущего draft или публикация следующей версии не меняют уже закреплённое приложение.

Временный catalog server предоставляет:

• GET /api/design-profiles;
• GET /api/design-profiles/:id;
• POST /api/design-profiles;
• PUT /api/design-profiles/:id;
• GET /api/design-profiles/:id/versions;
• GET /api/design-profiles/:id/versions/:version;
• POST /api/design-profiles/:id/publish;
• DELETE /api/applications/:id с переносом draft в локальное deleted-storage.

Catalog server проверяет полный layout-контракт Design Profile и существование выбранной Application Manifest ссылки при создании и сохранении модуля. Опубликованные снимки лежат отдельно от draft-head в runtime-data/design-profile-releases и исключены из Git; в production этот lifecycle должен перейти в Platform design-profile-core без изменения публичного контракта.