Операции со снимками прослеживаемости

Снимок сохраняет версионированное состояние проекта, группы или портфеля для последующего просмотра, сравнения и экспорта. Пользовательская точка входа — аутентифицированный REST API. Прямой доступ к хранилищу используют сопровождающие для диагностики.

Базовый маршрут и scope

Все операции в этой статье используют:

/api/v1/traceability/snapshots

Маршрут подключён в src/api/app_routers.py, зафиксирован в src/api/route_contracts.py и реализован в src/api/routers/dashboard_core/dashboard_v2_snapshots.py.

Доступ к проекту и группе определяется аутентифицированным ProjectContext. Пользователь без роли администратора не может выйти из этого контекста через query-параметры. Snapshot ID — идентификатор, а не разрешение.

Операции

Операции
Метод и маршрут	Назначение
`POST /api/v1/traceability/snapshots`	Создать ручной снимок проекта, группы или портфеля.
`GET /api/v1/traceability/snapshots`	Получить доступные снимки с ограниченной пагинацией.
`GET /api/v1/traceability/snapshots/policy`	Прочитать действующую политику immutable snapshots.
`GET /api/v1/traceability/snapshots/{snapshot_id}`	Прочитать доступную запись снимка.
`POST /api/v1/traceability/snapshots/compare`	Сравнить два snapshot ID или две временные точки проекта.
`POST /api/v1/traceability/snapshots/{snapshot_id}/export`	Экспортировать снимок или сравнение с baseline.

Состав request/response полей проверяйте по live OpenAPI для развёрнутой версии. Не переносите примеры из прежних dashboard routes.

Создание снимка

curl -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots" \
  -H "Authorization: Bearer $CODEGRAPH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "project",
    "reason": "pre-release baseline",
    "trigger_source": "manual",
    "immutable": true,
    "retention_class": "standard"
  }'

Для project scope не передавайте project_name, чтобы использовать активный проект. Указание другого имени не обходит ProjectContext.

Список и отдельная запись

curl "$CODEGRAPH_URL/api/v1/traceability/snapshots?scope=project&limit=20&offset=0" \
  -H "Authorization: Bearer $CODEGRAPH_TOKEN"

curl "$CODEGRAPH_URL/api/v1/traceability/snapshots/$SNAPSHOT_ID" \
  -H "Authorization: Bearer $CODEGRAPH_TOKEN"

Сервис применяет настроенный максимальный размер страницы, даже если клиент запросил больше.

Сравнение

Для release evidence используйте immutable ID:

curl -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots/compare" \
  -H "Authorization: Bearer $CODEGRAPH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"from_snapshot_id\":\"$BASELINE_ID\",\"to_snapshot_id\":\"$CURRENT_ID\",\"include_drilldown\":true}"

Сравнение по времени поддерживается для project snapshots. Для group и portfolio нужны snapshot ID.

Экспорт

curl -X POST "$CODEGRAPH_URL/api/v1/traceability/snapshots/$CURRENT_ID/export" \
  -H "Authorization: Bearer $CODEGRAPH_TOKEN" \
  -H "Content-Type: application/json" \
  -o snapshot-export.bin \
  -d "{\"format\":\"json\",\"language\":\"ru\",\"baseline_snapshot_id\":\"$BASELINE_ID\"}"

Если указан baseline_snapshot_id, результатом будет пакет сравнения, а не экспорт одного снимка.

Эксплуатационная проверка

Прочитайте /policy до того, как опираться на immutability, retention или export behavior.
Сохраните snapshot ID, идентификатор проекта, время запроса и release revision в acceptance evidence.
Успешный запрос снимка создаёт один из evidence artifacts для оценки готовности релиза.
403 означает проблему scope или роли, 404 — отсутствующую либо недоступную запись. Не переходите к raw storage.
Сверяйте полный набор операций с live OpenAPI развёрнутой версии.

Источники

src/api/route_contracts.py
src/api/app_routers.py
src/api/routers/dashboard_core/dashboard_v2_snapshots.py
src/api/schemas/dashboard_v2_snapshots.py