Перейти к основному содержимому

GET /api/v1/agency/rewards-exports/{jobId} — Статус выгрузки и ссылка на скачивание

Опрос задачи Excel-выгрузки вознаграждений, поставленной операцией create-rewards-export.md: текущий статус жизненного цикла и — для завершённой задачи — короткоживущая подписанная ссылка на скачивание файла из приватного объектного хранилища (ADR-0041).

Назначение​

Владелец/руководитель агентства после постановки выгрузки опрашивает её статус («готовится» → «готово») и получает ссылку на XLSX-файл. Ссылка живёт ограниченное время (1 час) — при истечении клиент повторяет запрос и получает новую, пока файл не удалён по retention. Feature group — rewards-exports.

Metadata​

ПолеЗначение
Сервис/контекстrewards
API areaagency
Feature grouprewards-exports
Статусdraft
Документdocs/06-services/rewards/api/agency/get-rewards-export-job.md

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

ПроверкаЗначение
Actor typeUser (владелец/руководитель агентства)
Auth policy / Permissionsrewards.commission.view-all
Scope (RBAC)организация: компания Type ∈ {Agency, Broker, Pin}
Record-levelне применяется (доступ на уровне tenant: задача своего агентства)
Tenant isolationTenantId из claims; чужая задача невидима → 404
Auditвыдача ссылки на скачивание — audit-запись ExportSensitive (актор, JobId, время выдачи URL)

HTTP-контракт​

ПолеЗначение
MethodGET
Route/api/v1/agency/rewards-exports/{jobId}
Success status200
Idempotency headerне применяется (read; каждая выдача ссылки генерирует новый signed URL)
Correlationсквозной trace через заголовок traceparent

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

ПолеИсточникТипОбязательностьВалидация / ОграниченияБезопасность
TenantIdidentity claims (tenant_id)GuidДаRequiredTenant isolation
ActorUserIdidentity claims (sub)GuidДаRequiredaudit выдачи ссылки
JobIdroute {jobId}GuidДаRequired, непустой—

Модель ответа RewardsExportJobModel​

Дом модели — README.md («Общие контрактные модели»). Особенности этого ответа: DownloadUrl заполняется только при Status = Completed и непросроченном файле — подписанная ссылка на объектное хранилище с TTL 1 час; в остальных статусах DownloadUrl = null. FailureCode заполняется только при Status = Failed (например, REWARDS_EXPORT_ROW_LIMIT_EXCEEDED).

Алгоритм​

  1. Контекст и доступ. Операцию выполняет владелец/руководитель агентства; scope — организация (TenantId из claims); требуется право rewards.commission.view-all.
  2. Проверка входа и существования. JobId непустой; задача существует в tenant-е агентства — иначе REWARDS_EXPORT_JOB_NOT_FOUND (чужая задача не раскрывается).
  3. Проекция статуса. Возвращается текущее состояние задачи (Queued/Running/Completed/Failed/ Expired). Для Completed: если retention файла (7 дней) ещё не истёк — генерируется подписанная ссылка с TTL 1 час, DownloadUrl заполняется, пишется audit-запись выдачи; если файл уже удалён по retention — задача отдается как Expired, DownloadUrl = null.
  4. Результат. RewardsExportJobModel → 200. Клиент при Queued/Running повторяет опрос (рекомендованный интервал — 5–10 с); при Expired — ставит новую выгрузку (create-rewards-export.md); при Failed — читает FailureCode и сужает фильтры.

Ошибки и failure modes​

Общие коды (ValidationError, FORBIDDEN, UNAUTHORIZED) — дом README.md «Общие ошибки». Дельта операции:

КодHTTP statusУсловиеСообщениеRetry
REWARDS_EXPORT_JOB_NOT_FOUND404Задача не существует или принадлежит чужому tenant«Выгрузка не найдена»no retry

Статус Failed самой задачи — не HTTP-ошибка: ответ 200 с Status = Failed и FailureCode (причины — create-rewards-export.md, «Ошибки»).

Acceptance criteria​

  • AC-1 (готовый файл). Given задача в Completed, файл в хранилище (retention не истёк); When GET; Then 200, Status = Completed, DownloadUrl — подписанная ссылка с TTL 1 час; выдача зафиксирована audit-записью ExportSensitive.
  • AC-2 (повторная выдача ссылки). Given прежняя ссылка истекла (прошло > 1 часа), файл ещё жив; When повторный GET; Then 200 с новой действующей ссылкой (каждая выдача — новый signed URL и новая audit-запись).
  • AC-3 (в процессе). Given задача Queued или Running; When GET; Then 200, соответствующий статус, DownloadUrl = null; клиент продолжает опрос.
  • AC-4 (retention истёк). Given с момента готовности файла прошло > 7 дней; When GET; Then 200, Status = Expired, DownloadUrl = null — клиент ставит новую выгрузку.
  • AC-5 (неуспех генерации). Given задача упала (например, превышен лимит 100 000 строк); When GET; Then 200, Status = Failed, FailureCode = REWARDS_EXPORT_ROW_LIMIT_EXCEEDED, DownloadUrl = null.
  • AC-6 (чужой tenant). Given JobId задачи другого агентства; When GET; Then REWARDS_EXPORT_JOB_NOT_FOUND (404) — без раскрытия существования.

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

  • Новые optional поля модели задачи — additive; новые значения статуса задачи — additive (unknown статус клиент трактует как «в процессе»).
  • Logs: JobId, TenantId, Status, факт выдачи ссылки (сам URL не логируется); metrics: rewards_export_download_url_issued_total; traces: OTel, correlation через traceparent.
  • Скачивание файла идёт напрямую из объектного хранилища по подписанной ссылке — минуя API rewards (SLA API не зависит от размера файла, ADR-0041).

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

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

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