POST /api/v1/platform/commission-terms/{termsId}/archive — Архивирование условий платформенной комиссии

Перевод условий Draft | Active → Archived: условия навсегда выводятся из резолюции удержания. Снапшоты применённых условий в созданных начислениях (AppliedPlatformTermsId) остаются живыми — domain/platform-commission-terms.md.

Назначение

Менеджер ПИН немедленно выводит условия из работы (в отличие от досрочного завершения через EffectiveTo — архив действует сразу и безвозвратно) либо списывает ненужный черновик. Архивирование действующих условий оставляет комбинацию измерений без своих условий: резолюция падает на менее специфичный уровень (вплоть до глобального дефолта), а при его отсутствии — на fallback 0 п.п. (платформа перестаёт удерживать долю — операция осознанная). Owning-контекст — rewards. Feature group — platform-terms.

Metadata

Поле	Значение
Сервис/контекст	rewards
API area	platform
Feature group	platform-terms
Статус	draft
Документ	docs/06-services/rewards/api/platform/archive-platform-terms.md

Актор и доступ

Проверка	Значение
Actor type	User (Менеджер ПИН)
Auth policy / Permissions	rewards.platform-terms.manage
Scope (RBAC)	платформа
Tenant isolation	вне tenant-модели — платформенная сущность (ADR-0052)
Audit	update: UpdatedByUserId, Version + 1, доменное событие PlatformTermsArchivedEvent

HTTP-контракт

Поле	Значение
Method	POST
Route	/api/v1/platform/commission-terms/{termsId}/archive
Success status	200
Idempotency header	не применяется (повтор из Archived → REWARDS_PLATFORM_TERMS_INVALID_STATUS_TRANSITION)
Correlation	сквозной trace через заголовок traceparent

Входные данные / параметры запроса

Поле	Источник	Тип	Обязательность	Валидация / Ограничения	Безопасность
ActorUserId	identity claims (sub)	Guid	Да	Required	—
TermsId	route {termsId}	Guid	Да	Required, непустой	—
ExpectedVersion	body	long	Да	>= 1; сверка с Version	optimistic concurrency

Модель ответа ArchivePlatformTermsResult

Поле	Тип	Обязательность	Источник	Masking	Описание
Id	Guid	Да	PlatformCommissionTermsEntity.Id	—	Id условий.
Status	string (enum PlatformCommissionTermsStatus)	Да	Status	—	Всегда Archived.
Version	long	Да	Version	—	Новая версия.

Предусловия и постусловия

• Предусловия. Актор — Менеджер ПИН с rewards.platform-terms.manage; условия существуют в статусе Draft или Active; клиент передаёт актуальный ExpectedVersion.
• Постусловия (успех). Условия в статусе Archived, Version увеличен, актор зафиксирован; условия навсегда исключены из резолюции — новые начисления их комбинации измерений резолвятся в следующего кандидата той же специфичности (по периоду) либо на менее специфичный уровень; если кандидатов не остаётся ни на одном уровне — начисление создаётся с PlatformRetentionPercentagePoints = 0 (fallback), растёт warn-метрика rewards_platform_terms_missing_total + алерт (domain/platform-commission-terms.md, «Резолюция условий», шаг 3). Созданные начисления и их снапшоты (AppliedPlatformTermsId) остаются живыми — физического удаления нет (restrict).
• Постусловия (отказ). Условия без изменений.

Алгоритм

1. Контекст и доступ. Операцию выполняет Менеджер ПИН в платформенном scope; требуется право rewards.platform-terms.manage.
2. Проверка входа и предусловий. TermsId непустой, ExpectedVersion >= 1. Условия существуют — иначе REWARDS_PLATFORM_TERMS_NOT_FOUND. Статус ∈ {Draft, Active}; из Archived — REWARDS_PLATFORM_TERMS_INVALID_STATUS_TRANSITION. Version совпадает с ExpectedVersion — иначе REWARDS_CONCURRENCY_CONFLICT. Наличие начислений со ссылкой на условия архив не блокирует.
3. Переход и запись. Условия переходят в Archived; фиксируются актор и новая версия.
4. Результат. Id, Status = Archived, новый Version → 200. Интеграционные события не публикуются.

Ошибки и failure modes

Код	HTTP status	Условие	Сообщение	Retry
REWARDS_PLATFORM_TERMS_NOT_FOUND	404	Условия не существуют	«Условия не найдены»	no retry
REWARDS_PLATFORM_TERMS_INVALID_STATUS_TRANSITION	409	Уже Archived	«Условия уже в архиве»	no retry
REWARDS_CONCURRENCY_CONFLICT	409	ExpectedVersion устарел	«Условия изменены другим пользователем»	retry после refresh

Общие коды — README.md.

Acceptance-критерии

• Архив действующих условий проекта. Дано: условия уровня Project в Active, действующий глобальный дефолт. Когда: POST .../archive. Тогда: 200, Status = Archived, Version + 1; новые начисления по объектам проекта резолвятся на менее специфичный уровень (вплоть до глобального дефолта); созданные начисления и их снапшоты не изменяются.
• Архив последних условий вообще. Дано: других активных условий нет ни на одном уровне. Когда: POST .../archive + завершение сделки. Тогда: начисление создаётся с PlatformRetentionPercentagePoints = 0 (fallback), растёт warn-метрика rewards_platform_terms_missing_total + алерт.
• Архив черновика. Дано: условия в Draft. Когда: POST .../archive. Тогда: 200, Status = Archived; резолюция не затронута (черновик в ней не участвовал).
• Повторный архив. Дано: условия уже Archived. Когда: POST .../archive. Тогда: 409 REWARDS_PLATFORM_TERMS_INVALID_STATUS_TRANSITION.
• Начисления сохраняются. Дано: на условия ссылаются начисления (AppliedPlatformTermsId). Когда: POST .../archive. Тогда: 200; начисления и их снапшоты не изменяются (restrict, физического удаления нет).
• Конкурентная версия. Дано: ExpectedVersion устарел. Когда: POST. Тогда: 409 REWARDS_CONCURRENCY_CONFLICT.

Совместимость и наблюдаемость

• Архив терминален — восстановление не проектируется (создаётся новый черновик копированием значений + активация; период новых условий не должен пересекаться с оставшимися активными — INV-PT-2).
• Для планового завершения предпочтительно досрочное завершение через EffectiveTo (update-platform-terms.md) — оно сохраняет условия действующими до границы; архив — немедленный вывод (ошибочно заведённые условия, отмена акции «прямо сейчас»).
• Logs: ActorUserId, TermsId, исходный статус, Scope; metrics: rewards_platform_terms_archive_total{result}, warn-метрика последствий — rewards_platform_terms_missing_total (растёт при fallback 0 п.п. на новых начислениях); traces: OTel; dashboard rewards-overview.

Обратные ссылки

Автоссылки: где используется этот документ.

• API (4): GET /api/v1/platform/commission-terms — Реестр условий платформенной комиссии, POST /api/v1/platform/commission-terms/{termsId}/activate — Активация условий платформенной комиссии, PUT /api/v1/platform/commission-terms/{termsId} — Изменение условий платформенной комиссии, Rewards API — реестр операций и общие контрактные модели
• Use Cases (2): UC-RWD-007. Платформа настраивает условия удержания ПИН, US-реестр: Финансовый блок ПИН (US-FIN)
• registries (1): Реестр API-методов PIN

Связанные документы

• Сущность: domain/platform-commission-terms.md (резолюция, fallback 0 п.п., stateDiagram).
• Соседние операции: activate-platform-terms.md, update-platform-terms.md, list-platform-terms.md.
• Точка резолюции: ../../consumers/crm-deal-completed.md.