RU docs revision comparison

Сравнение моделей с привязкой к ревизии

CADYX позволяет только для чтения сравнить две зафиксированные контрольные точки модели или два предложения транзакционного preview, созданные внутри процесса, в рамках одного проекта. Сравнение не получает блокировку на изменение, не меняет документ и его ревизию, не публикует файлы. Нативные измерения OCCT считаются выполненными только тогда, когда это явно отражено в ответе.

Список контрольных точек

GET /api/v1/agent/projects/{id}/revisions?offset=0&limit=50

Инструмент MCP: cadyx_list_revision_checkpoints.

Ответ перечисляет доступные ревизии с отпечатками SHA-256, начиная с последней, а также явными total и has_more. Текущая авторитетная ревизия project.json всегда доступна для чтения.

Начиная с реализации этой функции, каждый успешный ProjectWorkspace.save, который продвигает ревизию документа, сохраняет предыдущий и новый документы в закрытый файл проекта .cadyx-revisions.sqlite3 как сжатый канонический JSON. Снимки связаны с точным префиксом подтверждённой истории и идентификатором документа проекта. Архив сначала записывается, и лишь затем атомарно заменяется project.json; проверка истории не позволяет выдать незавершённое сохранение за зафиксированную контрольную точку. Авторитетным файлом остаётся project.json.

Историческая совместимость. Команды, зафиксированные до начала сохранения контрольных точек, нельзя без потерь восстановить из истории. Старые ревизии не создаются предположительно: запрос отсутствующей ревизии возвращает REVISION_UNAVAILABLE. Предложение с атомарной пачкой команд фиксирует только итоговый подготовленный документ; промежуточные номера ревизий внутри пачки являются записями истории, а не независимо сохранёнными снимками. Сравнивайте целое предложение до фиксации либо итоговую контрольную точку после неё.

Архив находится в каталоге проекта, исключён из обычного списка файлов проекта и перемещается вместе с каталогом при стандартном переименовании. Потеря закрытого архива не повреждает авторитетный проект, но удаляет старые точки сравнения. Если важна история сравнений, включайте этот файл в резервную копию вместе с файлами проекта.

Сравнение ревизий и preview

POST /api/v1/agent/projects/{id}/revisions/compare

Инструмент MCP: cadyx_compare_revisions.

Пример:

{
  "expected_revision": 17,
  "before": {"revision": 15},
  "after": {"proposal_id": "existing-preview-uuid"},
  "absolute_tolerance": 0.00000001,
  "relative_tolerance": 0.000000001
}

Для каждого селектора укажите ровно одно: revision (зафиксированная контрольная точка) или proposal_id (предложение, ранее полученное через /commands/preview). Оба должны относиться к одному документу. Неизвестное или вытесненное предложение, а также предложение из перезапущенного процесса недоступны.

Даже если оба селектора указывают на исторические снимки, expected_revision служит защитой от изменения текущей подтверждённой ревизии проекта. Будущая ревизия preview — предложение, не зафиксированная ревизия; сравнение предложения не расходует его и не разрешает фиксацию.

Ответ содержит:

• версию документа, идентификаторы обоих селекторов, SHA-256 обоих снимков, текущую зафиксированную ревизию и явно объявленные единицы модели/миллиметры сборки;
• добавленные, удалённые и изменённые ID объектов и элементов, значения параметров и их привязки;
• добавленные, удалённые и изменённые детали, подсборки, сопряжения и экземпляры, включая старый и новый перенос и кватернион перемещённых экземпляров;
• для пар с одинаковым body_id — хеши описания геометрии и, если доступна поддерживаемая OCCT B-rep, точные измерения сохранения объёма: объём эталона и кандидата, общий (пересекающийся) объём, потерянный и добавленный объём, оценку разрешения нативного вычисления, расхождение баланса объёмов и сводку изменений топологии;
• ограниченный массив unmatched_body_reports для новых и удалённых тел с отдельным точным объёмом и сводкой топологии OCCT, если доступны. Объём отдельного тела не равен чистому объёму объединения всей модели;
• списки ID добавленных, удалённых и изменённых тел visual_highlights. Это подсказки выбора для внешнего просмотрщика/агента; пассивный браузер CADYX автоматически не накладывает вторую модель и не отображает удалённую геометрию;
• явное неполное покрытие untested / partial, включая недоступные точные B-rep, неопределённый баланс объёмов, несопоставленные добавленные/удалённые тела, исчерпание бюджета пар тел и отсутствие соответствия граней/рёбер топологии.

Допуски по умолчанию — абсолютный 1e-8 единиц объёма модели и относительный 1e-9 от большего объёма сравниваемых тел. В порог включается нативное estimated_volume_resolution OCCT. Эти величины проверяют изменение объёма; они не устанавливают идентичность топологии, эквивалентность элементов, производственную посадку или объём объединения разных тел. Изменение поверхности при неизменном объёме всё равно может менять топологию.

Расчёты изменённой геометрии используют общий бюджет 32 измерения: сначала проверяются пары тел с совпадающими ID в отсортированном порядке, затем отдельные новые и удалённые тела на оставшийся бюджет. Дополнительные измерения явно опускаются; это ограничение ресурсов инспекции, не создания элементов модели. Каждая пара и несопоставленное тело рассчитываются отдельно. Треугольные сетки и неподдерживаемые операции ядра получают untested.

Общий статус partial, если по отдельным новым/удалённым телам нельзя определить действительную разность объединений между моделями. Сравнение не заявляет точный общий добавленный/удалённый объём объединения и не выводит идентичность тела после его удаления и повторного создания.

Боковая SQLite-база является производными метаданными, а не способом записывать геометрию. Изменения модели требуют обычной блокировки Command System и проверки ревизии. Новые контрольные точки занимают место пропорционально сохраняемым моделям; автоматического уплотнения истории и политики хранения пока нет. Учитывайте это место при планировании ёмкости и резервного копирования.

Проверка

Сценарии tests/test_revision_diff.py охватывают происхождение контрольных точек, прерванную/изменённую историю, недоступные старые ревизии, изменения параметров и сборок, контракт измерений OCCT, ограничения сеток, выбор preview в Core, регистрацию публичных маршрутов и MCP-инструментов. Изменения исходного кода для исходной реализации создавались без локального запуска тестов. Перед утверждением работоспособности необходимо отдельно проверить Windows CI и нативные результаты.