# Corporate Phase 5 Reports and Finance Audit

## Scope

Phase 5 adds organization-scoped corporate reports, safe finance summaries, and private final-delivery PDFs on top of Phases 1-4.

## Current Findings

### Organization reports portal

Status: Placeholder.

Evidence:
- `app/Livewire/Org/OrgReportsPage.php` renders `livewire.org.org-placeholder-page`.
- The placeholder lists planned attendance, progress, and Excel export features.

Gap:
- No organization-scoped report listing.
- No protected report download from the organization portal.

### Finance module

Status: Individual/general finance exists; corporate finance linkage is incomplete.

Evidence:
- `app/Models/FinancialTransaction.php` stores `type`, `source_type`, `source_id`, `amount_dzd`, `occurred_at`, and `category`.
- `database/migrations/2026_04_12_100500_create_financial_transactions_table.php` has no `organization_id`, `corporate_agreement_id`, or `cohort_id`.
- Admin finance report pages exist under `app/Livewire/FinanceReports/*`.

Decision:
- Add nullable corporate linkage fields to `financial_transactions`.
- Do not migrate old data blindly.
- Build a read-only summary service that never fabricates amounts.

### Corporate operational data

Status: Ready as report inputs.

Evidence:
- `CorporateAgreement` links to `Organization`, `CorporateProposal`, and `course_sessions` through Phase 4.
- `course_sessions` has corporate fields including `cohort_type`, `organization_id`, `corporate_agreement_id`.
- `corporate_trainees` stores participants.
- `attendance_sessions` stores planned/generated sessions.
- `corporate_attendance_records` stores corporate trainee attendance.

Reusable:
- `CorporateAttendanceSummaryService` can be extended/kept for headline counts.
- Existing private disk and DomPDF service are used by corporate proposals and agreements.

### PDF generation

Status: Existing pattern is reusable.

Evidence:
- `CorporateAgreementPdfService` renders a Blade PDF and writes to `storage/app/private`.
- `CorporateAgreementFileController` protects downloads with policy checks.

Decision:
- Create report-specific PDF service and protected controller.
- Store PDFs under `storage/app/private/corporate/reports/{reference}.pdf`.

### Messaging

Status: Existing stack can be reused.

Evidence:
- `CorporateAgreementNotificationService` logs Telegram messages and creates WhatsApp outbox records without blocking workflow.
- `MessageTemplatesSeeder` already contains corporate proposal/agreement templates.

Decision:
- Add report templates and a small notification service.
- Do not send public report files by WhatsApp.

## What Will Be Created

- `corporate_reports`
- `corporate_report_activities`
- `CorporateReport` and `CorporateReportActivity` models.
- `CorporateReportReferenceGenerator`
- `CorporateReportBuilder`
- `CorporateFinanceSummaryService`
- `CorporateReportPdfService`
- `CorporateReportNotificationService`
- Admin report index/create/detail pages.
- Organization portal report list.
- Protected report download controller.
- Policy and RBAC permissions.

## Finance Linkage

Minimal nullable fields added to `financial_transactions`:
- `organization_id`
- `corporate_agreement_id`
- `cohort_id`

The summary service will return:
- `configured` when corporate linked revenue exists.
- `partial` when an agreement amount exists but no linked payment data exists.
- `not_configured` when no agreement/proposal amount is available.

## Security and IDOR Risks

- Report files must never be public URLs.
- Admin/support access must be policy-gated.
- Organization portal must only show reports where `report.organization_id == selected_organization_id`.
- Financial values must be hidden unless the actor has `corporate_finance.view`.
- Download routes must record activity and check policy before reading private storage.

## Implementation Decision

Reports are read-model artifacts generated from current operational data. They do not become invoices and do not modify payments or finance records.