Справочник по хранилищу снимков

Постоянный слой снимков состояния для Dashboard V2. Используется для исторических трендов, ручных базовых точек, compare/export workflow и evidence вокруг release gate.

Назначение¶

Слой снимков больше не является только кэшем временных рядов. Это хранилище evidence с метаданными, которое используется для:

• трендов и period compare в dashboard
• ручных снимков проекта и группы
• snapshot-to-snapshot compare и export
• автоматических pre/post снимков release gate
• snapshot context в release-driven notifications

Модель снимка¶

Каждый снимок хранит как агрегированные оценки, так и provenance-метаданные.

Базовые поля идентификации:

• id
• scope — project, group или portfolio
• scope_ref — каноническая ссылка на объект
• project_name / group_id при необходимости
• timestamp

Метаданные evidence:

• reason
• initiator
• trigger_source
• analyzer_version
• rule_version
• source_ref
• immutable
• retention_class

Данные payload:

• сводки по health, audit, compliance, release, SCA и quality
• source bundle для compare/export
• сериализованный snapshot payload для последующего воспроизведения

Жизненный цикл¶

Снятие -> Сохранение -> Compare / Export -> Хранение / Cleanup

Источники создания снимков:

• фоновый планировщик
• ручные вызовы API и CLI
• автоматизация pre/post release gate

Правила retention:

• стандартная очистка использует dashboard.snapshot_retention_days
• снимки с immutable защищены от обычного cleanup
• release-triggered снимки могут иметь отдельный retention class

API¶

Все endpoint’ы находятся под /api/v2/dashboard.

Создание ручного снимка¶

POST /snapshots

Используется для ручного сохранения baseline для project, group или portfolio.

Основные поля запроса:

• scope
• project_name или group_id
• reason
• trigger_source
• analyzer_version
• rule_version
• source_ref
• immutable
• retention_class

ACL совпадает с правилами ProjectContext для исходного project/group.

Список снимков¶

GET /snapshots

Поддерживаемые фильтры:

• scope
• project_name
• group_id
• limit

Максимум записей ограничивается dashboard.snapshot_list_limit.

Policy immutable snapshots¶

GET /snapshots/policy

Возвращает live-контракт immutable-governance. Текущий runtime mode:

• immutable_governance_mode = no_delete_policy
• delete_supported = false
• archival_supported = false
• обычный cleanup по-прежнему уважает immutable = true

Сравнение снимков¶

POST /snapshots/compare

Поддерживаемые режимы:

• сравнение по from_snapshot_id и to_snapshot_id
• сравнение по legacy timestamp path для проекта

Результат compare включает:

• дельты метрик
• trend_direction
• dimension_states со значениями improved, regressed, unchanged
• опциональные drilldown_categories
• опциональные drilldown_previews

Экспорт снимка или compare-отчёта¶

POST /snapshots/{snapshot_id}/export

Поддерживаемые форматы:

• json
• markdown
• pdf

Если передан baseline_snapshot_id, формируется compare-report, а не экспорт одного снимка.

Endpoint’ы трендов¶

Существующие routes трендов остаются доступными:

• GET /snapshots/{project_name}/trends
• GET /snapshots/{project_name}/diff
• GET /snapshots/{project_name}/compare-periods

Эти routes используют persistent snapshot data, когда она доступна, и остаются совместимыми с общей моделью dashboard trends.

CLI¶

Реализовано в src/cli/dashboard_commands.py.

Доступные команды:

• dashboard snapshot create
• dashboard snapshot list
• dashboard snapshot show
• dashboard snapshot policy
• dashboard snapshot compare
• dashboard snapshot export

Примеры:

codegraph dashboard snapshot create --scope project --project my-service --reason "pre-hardening"
codegraph dashboard snapshot list --scope portfolio --group team-a --format json
codegraph dashboard snapshot show <snapshot_id> --format json
codegraph dashboard snapshot policy --format json
codegraph dashboard snapshot compare --from-snapshot <id1> --to-snapshot <id2> --include-drilldown
codegraph dashboard snapshot export <snapshot_id> --baseline-snapshot <older_id> --format markdown

Интеграция с release gate¶

POST /api/v1/release/check может создавать:

• pre snapshot до проверки
• post snapshot после проверки

В ответ добавлены поля:

• pre_snapshot_id
• post_snapshot_id
• snapshot_diff

Поведение управляется через:

• dashboard.snapshot_release_pre_enabled
• dashboard.snapshot_release_post_enabled
• dashboard.snapshot_release_immutable
• dashboard.snapshot_release_retention_class

Интеграция с notifications¶

Notification service использует snapshot-derived context для release-driven notifications. В текущем срезе в event payload передаются:

• идентификаторы снимков
• краткая сводка compare diff
• контекст release outcome

Это позволяет привязать release alerts к воспроизводимому evidence, а не только к строке статуса.

Настройка¶

Ключевые параметры в секции dashboard:

• snapshot_enabled
• snapshot_interval_minutes
• snapshot_retention_days
• snapshot_db_path
• snapshot_list_limit
• snapshot_release_pre_enabled
• snapshot_release_post_enabled
• snapshot_release_immutable
• snapshot_release_retention_class

Эксплуатационные замечания¶

• Хранилище использует SQLite и создаётся автоматически при первом обращении.
• Для фоновой записи рекомендуется один активный экземпляр scheduler.
• Ручные snapshots и compare/export можно использовать и без включённого фонового scheduler.
• immutable теперь оформлен как явный no_delete_policy: runtime не экспонирует delete или mutate endpoints, а обычный cleanup пропускает immutable records.

Основные файлы¶