ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
788efee1c2
TenantAtlas/specs/379-management-report-pdf-runtime/artifacts/storage-operationrun-decision.md
ahmido dbff2a0a90 feat(report): implement management report pdf runtime (#450) 
Added jobs, controllers, and PDF generation logic for management report runtime as defined in Spec 379. Includes artifact migrations, payload builders, and testing coverage.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #450
2026-06-15 11:36:29 +00:00

3.7 KiB
Raw Blame History

Spec 379 Storage, OperationRun, and UI Decisions

Date: 2026-06-14

Owner Surface

V1 generation is owned by ReviewPackResource detail (ViewReviewPack).

Rationale:

  • The Review Pack detail already owns the current customer-safe ZIP artifact, rendered-report action, readiness checks, and download capability.
  • The management PDF is derived from the current ready Review Pack, not from an independent report center.
  • Server-side generation authorization uses REVIEW_PACK_MANAGE; download uses REVIEW_PACK_VIEW.

Storage Substrate

The PDF uses StoredReport as the persisted artifact substrate.

Rationale:

  • Avoids a new report-center table or broad artifact lifecycle framework.
  • Keeps workspace and managed-environment scope on the existing report model.
  • Adds only narrow nullable fields required for source linkage, operation linkage, private file metadata, profile, format, status, SHA-256, and generated timestamp.
  • Keeps StoredReportResource::$isGloballySearchable = false; no global-search behavior changed.

Private files are stored on the existing exports disk under management-reports/... with generated safe filenames. Ready artifacts are exposed only through a signed route that re-checks tenant scope, current source Review Pack, artifact status, file existence, and REVIEW_PACK_VIEW.

OperationRun

A distinct canonical operation type was added:

  • report.management.generate
  • Enum: OperationRunType::ManagementReportGenerate
  • Catalog label: Management report PDF generation

Rationale:

  • Reusing environment.review_pack.generate would mislabel PDF generation as ZIP generation in monitoring, audit, and notifications.
  • The operation does not introduce a new artifact-family taxonomy in OperationCatalog; it remains a stored-report-backed workflow.

Generation queues GenerateManagementReportPdfJob through OperationRunService::dispatchOrFail() and writes terminal state through OperationRunService::updateRun().

Audit

Distinct audit action IDs were added because ZIP generation/download and management-PDF generation/download have different artifact semantics:

  • management_report_pdf.generation_requested
  • management_report_pdf.generation_blocked
  • management_report_pdf.generated
  • management_report_pdf.generation_failed
  • management_report_pdf.downloaded

Audit metadata records workspace, managed environment, source review, source Review Pack, stored report id, operation run id, profile, SHA-256 where available, and redacted request context. Signed URLs, secrets, raw provider payloads, stack traces, and SQL errors are not included.

Runtime Gate

Generation is gated by ManagementReportPdfRuntimeGate.

Blocked states include:

  • renderer disabled
  • unsupported renderer driver
  • staging/runtime validation missing
  • source Review Pack not ready, expired, missing artifact, or not current
  • disclosure/profile blockers
  • active generation already running

The default environment remains blocked until TENANTPILOT_PDF_RENDERER_RUNTIME_VALIDATED=true.

UI Coverage

  • Generate management PDF appears in the Review Pack detail header only when no ready PDF exists.
  • The action uses Action::make(...)->action(...), ->requiresConfirmation(), and server-side REVIEW_PACK_MANAGE.
  • When generation is active, the header shows Open PDF operation.
  • When a ready PDF exists, the header shows Download management PDF.
  • Browser evidence:
    • specs/379-management-report-pdf-runtime/artifacts/screenshots/generate-state.png
    • specs/379-management-report-pdf-runtime/artifacts/screenshots/download-state.png

No navigation redesign, customer workspace redesign, scheduled delivery, public links, AI-generated copy, or secondary renderer was added.