6c7a80e275
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 5m7s
Added jobs, controllers, and PDF generation logic for management report runtime as defined in Spec 379. Includes artifact migrations, payload builders, and testing coverage.
81 lines
3.7 KiB
Markdown
81 lines
3.7 KiB
Markdown
# 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.
|