# Corporate Phase 6: Invoicing, Receivables, and Payment Allocation

## Scope

Phase 6 adds organization-scoped corporate invoicing without touching the individual student enrollment/payment flow.

- `Organization` remains the customer account.
- Invoices can link to a `CorporateAgreement`, a corporate cohort in `course_sessions`, and optionally a `CorporateReport`.
- Invoice PDFs are stored on the private disk under `corporate/invoices/{reference}.pdf`.
- Downloads always go through controller + policy checks.
- Individual `payments` remain separate. Corporate collection uses `corporate_payments`.

## Data Model

- `corporate_invoices` stores invoice header, financial totals, lifecycle status, due dates, PDF path, and private notes.
- `corporate_invoice_items` stores training/service/report/other line items.
- `corporate_payments` stores organization payments pending review or confirmed by finance/admin users.
- `corporate_payment_allocations` allocates one confirmed corporate payment across one or more invoices.
- `corporate_invoice_activities` and `corporate_payment_activities` keep an audit trail.

## Workflow

Invoice lifecycle:

`draft -> issued -> partially_paid -> paid`

Additional states:

- `overdue` is set by `php artisan corporate:invoices-mark-overdue` when an issued or partially paid invoice is past due and still has balance.
- `cancelled` is for draft/issued invoices without payments.
- `void` is reserved for accounting-style cancellation after issuance.

Payment lifecycle:

`pending_review -> confirmed -> allocated`

Allocation rules:

- Only confirmed payments can be allocated.
- Allocation total cannot exceed the remaining unallocated payment amount.
- Allocation amount cannot exceed the invoice balance.
- Payment and invoice must belong to the same organization.

## Financial Transactions

Revenue is recognized only when a confirmed corporate payment is allocated.

The integration writes `financial_transactions` as:

- `type = revenue`
- `source_type = corporate_payment_allocation`
- `source_id = corporate_payment_allocations.id`
- `category = corporate_training_revenue`
- `organization_id`, `corporate_agreement_id`, and `cohort_id` copied from the invoice/allocation context where available.

This keeps corporate revenue idempotent and avoids double-counting invoices at issue time.

## Admin UX

Admin routes:

- `/admin/corporate-invoices`
- `/admin/corporate-invoices/create`
- `/admin/corporate-invoices/create?agreement={id}`
- `/admin/corporate-invoices/create?cohort={id}`
- `/admin/corporate-invoices/{invoice}`
- `/admin/corporate-payments`
- `/admin/corporate-payments/{payment}`
- `/admin/corporate-finance/receivables`

Agreement and corporate cohort details include a shortcut to create an invoice.

## Organization Portal

`/org/invoices` now lists only invoices for the selected organization tenancy context.

Organization members can only download a PDF if:

- the invoice belongs to the selected organization, and
- the user has `org.invoices.view`, and
- the file exists on the private disk.

## Permissions

Admin permissions added:

- `corporate_invoices.view`
- `corporate_invoices.create`
- `corporate_invoices.update`
- `corporate_invoices.issue`
- `corporate_invoices.cancel`
- `corporate_invoices.void`
- `corporate_invoices.generate_pdf`
- `corporate_invoices.download`
- `corporate_payments.view`
- `corporate_payments.create`
- `corporate_payments.review`
- `corporate_payments.allocate`
- `corporate_receivables.view`
- `org.invoices.view`

Support has view-only access by default and cannot confirm or allocate payments unless explicitly granted.

## Limitations

Not included in Phase 6 itself:

- Advanced tax rules.
- Public expiring invoice links.
- Corporate payment gateway checkout.
- Full accounting ledger automation.

Phase 7 adds credit notes, auditable allocation reversal, and private corporate payment receipt downloads. See `docs/corporate_phase_7_credit_notes_reversals.md`.

## Operational Workflow

1. Create invoice from an organization, corporate agreement, or corporate cohort.
2. Review line items, discount, tax, payment terms, and save as draft.
3. Generate the private PDF and issue the invoice.
4. Register a corporate payment in `pending_review`.
5. Review and confirm the payment.
6. Allocate the confirmed payment to one or more issued invoices.
7. Monitor `/admin/corporate-finance/receivables` and run `php artisan corporate:invoices-mark-overdue` to update overdue invoices.

## Finance Safety Rules

- Payments can only be allocated after confirmation.
- Invoices can receive allocations only when their status is `issued`, `partially_paid`, or `overdue`.
- A payment and invoice must belong to the same `organization_id`.
- An allocation cannot exceed the invoice balance.
- The sum of allocations cannot exceed the payment amount.
- The same payment cannot be allocated to the same invoice twice.
- Revenue is recognized only through `financial_transactions` with `source_type=corporate_payment_allocation`.
- Phase 7 reversal corrections use negative `financial_transactions` with `source_type=corporate_payment_allocation_reversal`; original allocations are not deleted.
- Phase 7 credit notes reduce invoice net totals only within unpaid balance.
- Invoice PDFs and future payment receipts must remain on private storage.

## QA Checklist

- Admin invoice/payment routes are protected by `auth` and explicit permissions.
- Org invoice routes are protected by tenancy and `org.invoices.view`.
- PDF downloads pass through policies and record activity.
- Support users are view-only by default and cannot review or allocate payments without explicit permissions.
- Organization members cannot see or download another organization’s invoices.
- Receivables access requires `corporate_receivables.view`.
- The invoicing subsystem does not use `companies`, `users.company_id`, or `agreement_path`.