Feature Specification: Export & Delivery

1. Overview & Vision

Export & Delivery is the final stage of the reporting lifecycle. It ensures that the insights generated by the AI reach the right people in the right format. By providing high-fidelity PDF exports and multi-channel notifications (In-app, Email), it makes reporting actionable and portable for stakeholders outside the platform.

2. Personas & Stakeholders

Persona	Goal
Executive	Receive professional PDF reports via email for board meetings.
Admin	Distribute automated summaries to specific team channels.
External Auditor	Review historical PDF snapshots of organization state.

3. User Stories

• As an admin, I want to export a generated report to PDF so I can print it for a physical meeting.
• As a manager, I want to be notified in the Shell as soon as my weekly report is ready.
• As an admin, I want the system to email the monthly asset report to the CFO automatically.

4. Functional Requirements (FR)

• REQ-DEL-001: High-fidelity PDF generation from Markdown content.
• REQ-DEL-002: Multi-channel delivery: In-app, Email, and Slack (planned).
• REQ-DEL-003: Configurable delivery lists (who receives which report).
• REQ-DEL-004: Support for custom branding (Logo, Colors) in PDF exports.

5. Non-Functional Requirements (NFR)

• Performance: PDF generation < 10 seconds for a 5-page report.
• Fidelity: PDF layout MUST exactly match the web preview.

6. Business Logic & Rules

• Snapshot Finality: Reports are read-only once delivered.
• Link Security: Links in emails MUST use secure, one-time-use tokens for authentication.
• Branding: Uses the organization_id settings to apply the correct company logo to the PDF header.

7. User Interface (UI/UX)

• Delivery Config: Multi-select dropdown for team members and external email inputs.
• Export Menu: Clear "Download PDF" and "Send Email" actions on every report result.
• Notification Bell: Visual indicator when a background generation task finishes.

8. Information Architecture

• Part of the "Report Result" view.
• "Delivery Settings" within the Template Editor.

9. Data Model & Persistence

• Table: report_results (stores the PDF storage path).
• Config: Delivery recipients stored in report_templates.delivery_config.

10. API & Service Layer

• GET /executions/:id/export: Triggers PDF generation.
• POST /executions/:id/deliver: Triggers multi-channel delivery.

11. Integration Patterns

• Puppeteer: Headless Chrome service used to render the HTML-to-PDF.
• SendGrid: Integrated for reliable email delivery.
• Drive: Generated PDFs are automatically archived in a hidden "Reports" folder in Drive.

12. Security & Permissions

• RBAC: reports:view required to download or trigger delivery.
• Redaction: (Future) Ability to mask sensitive data based on recipient role.

13. Error Handling & Resilience

• Bounce Tracking: Log if an email delivery fails.
• Generation Retry: Automatically retry PDF generation if the headless browser crashes.

14. Performance & Scalability

• PDF generation is offloaded to a background task queue.
• Support for generating 100+ PDFs simultaneously.

15. Globalization & i18n

• Support for Vietnamese fonts and characters in PDF generation.

16. Accessibility (a11y)

• Generated PDFs follow Tagged PDF standards for screen readers.

17. Observability & Analytics

• Tracking of "Open Rates" for emailed reports.
• Monitoring of "PDF Generation Latency".

18. Testing & Quality

• Visual regression testing for PDF layouts.
• Email deliverability testing across major providers (Gmail, Outlook).

19. Constraints & Assumptions

• Assumes that the Puppeteer service has access to the required fonts and styling assets.

20. Future Enhancements

• Slack / Microsoft Teams delivery hooks.
• Interactive PDFs (with clickable links back to VENI-AI).
• Batch export (Download all reports for Quarter 1).