Repository navigation
RU codex docs project format v1
Каждый проект хранится в projects/<имя-проекта>/project.json. Для новых проектов используется безопасное для файловой системы имя каталога; если оно занято, добавляется числовой суффикс. Уже существующие каталоги workspace принимаются на месте и сохраняют имена. Локальная метка .cadyx-project-id хранит постоянный UUID, чтобы адрес проекта сохранялся и при повреждении project.json; UUID остаётся идентификатором API и блокировок. Каталоги старого вида projects/<project-id>/ продолжают читаться. JSON-документ кодируется в UTF-8, содержит format: "cadyx-project" и version: 1.
{
"format": "cadyx-project",
"version": 1,
"id": "<uuid>",
"name": "Пример",
"url_slug": "primer",
"created_at": "<UTC ISO-8601>",
"modified_at": "<UTC ISO-8601>",
"document": {
"id": "document:<uuid>",
"version": 12,
"revision": 0,
"objects": [],
"model_parameters": {},
"parameter_bindings": [],
"assembly": {
"version": 3,
"units": "mm",
"parts": [],
"subassemblies": [],
"instances": [],
"mates": []
}
},
"history": []
}name — отображаемое пользователю название проекта, оно может быть на любом языке. Необязательный url_slug — постоянный ключ адреса /p/<slug> на английской основе: строчные ASCII-буквы, цифры и одиночные дефисы. В старых записях без этого поля при загрузке детерминированно строится латинский запасной вариант из названия.
Документ и история успешно выполненных команд фиксируются вместе. project.json заменяется атомарно. Записи истории дописываются в .cadyx-history.jsonl и сбрасываются на диск до изменения снимка проекта, который хранит позицию в истории (число записей и смещение в байтах). Сбой до замены снимка оставляет незафиксированный хвост журнала; сбой после неё оставляет согласованные долговечную историю и ревизию документа.
Блокировки хранятся отдельно, в runtime-файле каждого проекта .cadyx-leases.sqlite3; активные сеансы хоста и блокировки не сериализуются в project.json. Жизненный цикл блокировок и ограничения резервного копирования описаны в контракте локальных нескольких процессов. Неизвестные версии проекта или документа отклоняются, а не интерпретируются предположительно.
Закрытый конверт $cadyx_storage содержит указатель на журнал истории. Дескрипторы импортированных B-rep однократно сохраняются как скрытые файлы по содержимому .cadyx-brep-<sha256>.json в каталоге проекта; поля геометрии документа и истории содержат ссылки на них. При загрузке Workspace проверяет все файлы по ссылкам, разворачивает их, считывает зафиксированный префикс истории и лишь затем выполняет валидацию или отвечает на API-запрос. Вызывающая сторона по-прежнему видит обычный документ и полные результаты команд.
Старые записи со встроенной историей и без конверта хранения остаются читаемыми. При следующем успешном сохранении их история переносится в журнал. Незакоммиченный хвост журнала отсекается по сохранённому смещению в байтах; перед последующим добавлением хвост усекается. Резервная копия и копия проекта должны включать весь его каталог, в том числе скрытые файлы .cadyx-*.
Исполнение команд, preview и сводки списка проектов загружают зафиксированный документ и указатель истории без разбора старых строк журнала. Полная инспекция проекта и компактные страницы истории изменений читают и проверяют зафиксированную историю.
JSON-пример выше показывает развёрнутый вид проекта. После первой успешно зафиксированной команды конверт на диске хранит в $cadyx_storage поле history: {file, count, bytes}. При загрузке Workspace массив истории восстанавливается из журнала. Новый пустой проект может сохранять встроенный пустой history до фиксации первой команды.
При перечислении проектов каждый непосредственный каталог без символьной ссылки, без project.json и без конфликтующих данных .cadyx-project-id принимается как проект. CADYX создаёт в нём новую UUID-метку и пустую запись проекта, публикуя их только если эти файлы ещё отсутствуют, чтобы сохранить существующие данные.
Если запись проекта отсутствует, пригодная существующая метка используется повторно. Существующие project.json и некорректные зарезервированные метаданные никогда не перезаписываются. Вложенные каталоги остаются частью проекта-родителя и не перечисляются как отдельные проекты. Принятые каталоги отображаются в списке; их непосредственные пользовательские файлы доступны через API файлов проекта.
Стоп-маркеры агента и защита ревизии при возобновлении блокировки хранятся отдельно, в .cadyx-agent.sqlite3; переносимый формат проекта они не меняют. См. контракт остановки и продолжения.
Конверт проекта остаётся версии 1, вложенный текущий документ — версии 12 (cadyx/migrations.py). Снимки документа v1–v11 обновляются в памяти при чтении и сохраняются только следующей успешной командой. Базовый граф объектов описан в Document Model v7, именованные параметры — в v8, сборки — в v9, сопряжения — в v10, материалы — в v11, редактируемые эскизы YZ/CUSTOM/FACE — в v12.
Геометрия коробки хранится JSON-дескриптором с ID ядра, размерами и измеренным объёмом. Новые дескрипторы используют occt-v1; Open CASCADE восстанавливает B-rep по размерам и проверяет корректность при создании или проверке проекта. Нативные объекты ядра не сериализуются. Старые дескрипторы коробки primitive-v1 остаются читаемыми и проверяются перестроением соответствующего твёрдого тела Open CASCADE.
Актуальные версии схем и явные пошаговые преобразования принадлежат cadyx/migrations.py. Версии конверта проекта и документа независимы: сначала обновляется конверт, затем вложенный документ. Конверт остаётся v1, поэтому шаг миграции конверта не нужен. Поддерживаемая цепочка миграций документа: v1→v2→v3→v4→v5→v6→v7→v8→v9→v10→v11→v12. При изменении схемы необходимо добавить каждый последовательный шаг, а не переименовывать неизвестный снимок. Отсутствующие шаги, неподдерживаемые (включая будущие) версии и нецелочисленные теги версии являются ошибкой.
При загрузке Workspace и валидации миграция выполняется над глубокими копиями, после чего проверяются текущий документ, ссылки, идентичность проекта, согласованность ревизии и истории. В сохранённом документе должны быть id, revision и objects; неполный снимок отклоняется. Core также проверяет геометрию при инспекции и исполнении команды.
Миграция сохраняет метаданные, ID, геометрию, ссылки и существующую историю; она не создаёт команд и не увеличивает ревизию. Повторное применение миграции к актуальному снимку оставляет его без изменений.
Чтение, перечисление проектов, операции блокировки и отклонённые команды не переписывают старые записи ради миграции. Перечень проектов может первоначально зарегистрировать каталог workspace способом, описанным выше. Только следующая успешная команда Core с действующей блокировкой фиксирует мигрированный снимок вместе с изменением модели и истории в рамках существующего атомарного сохранения. Если атомарная замена завершается ошибкой, исходный файл остаётся цел. Отдельного API для записи миграции нет. Исходные CAD-файлы и сканы не входят в область миграции. Старые версии хоста не обязаны читать новые схемы.