# Corporate Phase 5 - Reports, Finance Summary, Final Delivery PDF

## Scope

Phase 5 adds a safe reporting layer for corporate training delivery. It does not create invoices, accounting automation, or public report links.

## Data Model

- `corporate_reports` stores report metadata, status, private PDF path, period, notes, and recommendations.
- `corporate_report_activities` stores the report timeline.
- `financial_transactions` now has optional nullable links to `organization_id`, `corporate_agreement_id`, and `cohort_id` for future-safe aggregation.

Every report belongs to an `Organization`. Final delivery reports normally point to a corporate cohort and may also point to the agreement.

## Report Types

- `attendance`: attendance-focused report.
- `progress`: operational progress report.
- `financial`: finance summary only, without invoicing.
- `final_delivery`: complete delivery package for the institution.

## Data Sources

- Organization: `organizations`.
- Agreement: `corporate_agreements`.
- Cohort: `course_sessions` where `cohort_type = corporate`.
- Trainees: `corporate_trainees`.
- Sessions: `attendance_sessions`.
- Attendance: `corporate_attendance_records`.
- Finance: linked `financial_transactions` only when available.

## Finance Limitations

`CorporateFinanceSummaryService` never fabricates numbers.

- If no agreement amount exists, status is `not_configured`.
- If an agreement amount exists but no linked transaction exists, status is `partial`.
- If linked revenue transactions exist, status is `configured`.

Full invoicing, receivables, reconciliation, and payment schedules remain future work.

## PDF Storage

Generated reports are stored privately:

`storage/app/private/corporate/reports/{reference}.pdf`

Downloads go through authenticated, authorized routes only. Reports are never exposed through public storage.

## Admin Workflow

1. Open a corporate cohort or agreement.
2. Create a report draft.
3. Preview summaries in the report detail page.
4. Generate private PDF.
5. Mark as sent when the institution has been notified.
6. Archive when no longer active.

## Organization Portal

`/org/reports` now lists only reports for the selected organization. The tenancy middleware must keep `selected_organization_id` valid. Org members cannot see reports from other organizations.

## Permissions

- `corporate_reports.view`
- `corporate_reports.create`
- `corporate_reports.update`
- `corporate_reports.generate_pdf`
- `corporate_reports.download`
- `corporate_reports.send`
- `corporate_reports.archive`
- `corporate_finance.view`

Support can view reports by default, but financial details are hidden unless `corporate_finance.view` is granted.

## Remaining Future Work

- Corporate invoicing.
- Receivables and payment reconciliation.
- Signed delivery report acceptance.
- Expiring secure report links if the institution should download without portal login.