Document report screen flow and tester guide
epic-structured-post-session-report-screen-task-010 — Write developer-facing documentation covering the post-session report screen's route arguments, session-lock guard contract, draft detection logic, activity_id linkage, and the speech-to-text permission flow. Additionally produce a plain-language tester guide for the Blindeforbundet pilot group explaining how to open the report after a session, what the draft indicator means, and how to use voice input. Ensure all content is in Norwegian BokmĂĄl for the tester guide and English for the developer docs.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 6 - 158 tasks
Can start after Tier 5 completes
Implementation Notes
For the developer documentation, co-locate a README.md or doc comment block directly in the post-session report screen's directory so it stays close to the code it describes and is updated alongside code changes. Use code snippets to show the GoRouter route definition and the required arguments map. For the tester guide, use large font, short sentences, and avoid all technical jargon — the target audience includes people with visual impairments who may be using VoiceOver to read the guide. Include screenshots only if they are high-contrast and labelled with alt text.
Deliver the tester guide as a PDF generated from a clean Markdown source so it can be regenerated easily for future pilot rounds.
Testing Requirements
Have one developer who was not involved in building the screen follow the developer documentation to navigate to the screen in a local dev environment and confirm all route argument descriptions are accurate. Have one non-technical stakeholder (or a team member roleplaying as a tester) follow the Norwegian tester guide on a real device and flag any step that is unclear or produces an unexpected result. Both reviews must be completed before the documents are considered done.
End-to-end integration tests that span Flutter UI → Supabase → RLS → storage are inherently flaky in CI due to network timing, test database state, and Supabase cold-start latency. Flaky tests erode confidence and slow the release pipeline.
Mitigation & Contingency
Mitigation: Use a dedicated Supabase test project with seeded org and user fixtures. Wrap all E2E tests in retry logic with a fixed seed and tear-down hooks. Keep E2E tests in a separate test suite that runs on-demand rather than on every PR, with unit and widget tests as the primary CI gate.
Contingency: If E2E tests remain unreliable, replace the Supabase calls in integration tests with a verified fake (in-memory repository implementations) and promote the real Supabase tests to a nightly scheduled run rather than blocking PR merges.
Health status, course interest, and assistive device fields contain personal health data. If any logger, analytics event, or crash reporter captures field values — through automated error serialisation or developer-added debug logs — the feature could violate GDPR and Blindeforbundet's data processor agreement.
Mitigation & Contingency
Mitigation: Audit all log statements in the report feature's code paths before the epic is marked done. Apply a PII-safe logging wrapper that strips field values from any serialised form state before it reaches the logger. Add a CI lint rule that flags direct logger calls within report-related files.
Contingency: If PII is found in logs post-launch, immediately disable the affected logging call and rotate any credentials that were exposed. Notify the data protection officer and document the incident per GDPR Article 33 requirements.