Implement preview flow — no audit record finalised
epic-bufdir-report-export-orchestration-task-006 — Implement requestPreview() in BufdirExportService. This path invokes the edge function with a preview flag, routes the response to the appropriate file generator (PDF or CSV based on format), and returns a BufdirPreviewResult containing the temporary file URL. Must NOT persist an ExportAuditRecord — the preview is a read-only operation. Include a clear code comment explaining this invariant.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 3 - 413 tasks
Can start after Tier 2 completes
Implementation Notes
Implement requestPreview() as a distinct code path from requestFinalExport() — do not share a single method with a boolean flag. The audit-record exclusion invariant is easier to verify in code review and testing when it is structurally impossible (i.e., the preview method simply has no reference to the audit repository). Pass preview: true in the BufdirEdgeFunctionRequest DTO. After receiving the FileGeneratorResult from task-008 routing, create a signed URL via supabase.storage.from('bufdir-previews').createSignedUrl() with a 3600-second expiry.
Construct BufdirPreviewResult from the signed URL and return. Do not catch exceptions here — let them propagate for the UI layer to display.
Testing Requirements
Unit tests with flutter_test: (1) successful preview returns BufdirPreviewResult with correct URL, mimeType, and expiresAt, (2) no audit record created on success (mock repository's persistAuditRecord and assert zero calls), (3) no audit record created when edge function throws BufdirServerException, (4) PDF format routes to PDF generator, (5) CSV format routes to CSV generator, (6) expiresAt is within 1 hour of test execution time. Use mockito to stub invokeEdgeFunction and the file generator dependencies.
The scope selector must accurately reflect each coordinator's access rights within the org hierarchy. If a coordinator can select a scope broader than their authorised access, the edge function's RLS enforcement must catch the attempt — but a permissive RLS policy or a bug in the scope resolver could allow unauthorised data to be exported.
Mitigation & Contingency
Mitigation: Implement permission enforcement at two independent layers: (1) the scope selector only renders options permitted by the user's role record, and (2) the edge function re-validates the requested scope against the user's JWT claims before executing any queries. Write integration tests that attempt to invoke the edge function with a scope beyond the user's permissions and assert rejection.
Contingency: If a permission bypass is discovered post-launch, immediately disable the export feature via the org-level feature flag while the fix is deployed. Review all audit records for exports that may have included out-of-scope data and notify affected organisations.
The export workflow has 7+ discrete states (idle, scope selected, period selected, preview loading, preview ready, confirming, exporting, complete, failed) and several conditional transitions. An incomplete BLoC state machine could allow duplicate submissions, stale preview data to be confirmed, or error states to be unrecoverable without a restart.
Mitigation & Contingency
Mitigation: Model the state machine explicitly as a sealed class hierarchy before coding. Review the state diagram against all user story acceptance criteria. Write bloc unit tests for every valid and invalid state transition, including the happy path and all documented error states.
Contingency: If the BLoC grows too complex to test reliably, decompose it into two cooperating blocs: one for configuration (scope + period selection) and one for execution (preview + confirm + export), linked by a coordinator object.