# Corporate Phase 7: Credit Notes, Allocation Reversals, and Receipt Downloads

## Purpose

Phase 7 adds controlled financial correction tools for corporate invoicing without deleting history or changing individual student payment flows.

Implemented capabilities:

- reverse a corporate payment allocation with a full audit trail,
- create and apply corporate credit notes,
- download corporate payment receipts from private storage through policy-protected routes,
- keep receivables aligned with reversals and credit notes.

## No Deletion Rule

Corporate payment allocations and recognized financial transactions are not silently deleted.

When an allocation must be corrected, the system:

- creates a `corporate_allocation_reversals` record,
- marks the original allocation as reversed,
- creates a negative `financial_transactions` row using `source_type=corporate_payment_allocation_reversal`,
- recalculates the invoice paid amount, balance, and status.

This keeps the accounting trail readable and prevents hidden revenue changes.

## Allocation Reversal Workflow

1. Admin opens a corporate invoice or payment.
2. Admin selects an active allocation and enters a reversal reason.
3. `CorporateAllocationReversalService` validates permissions and idempotency.
4. The original allocation remains in place but is marked reversed.
5. A negative revenue correction transaction is created.
6. Invoice receivables are recalculated.

Current MVP limitation:

- reversal is full amount only,
- partial reversal is intentionally deferred.

## Credit Note Workflow

Credit notes reduce the unpaid balance of a corporate invoice.

Workflow:

- `draft`
- `issued`
- `applied`
- `void`

MVP rules:

- credit note amount must be greater than zero,
- credit note amount cannot exceed the current unpaid invoice balance,
- credit notes are not applied against already recognized paid revenue,
- no revenue reversal transaction is generated for credit notes in this MVP.

Invoice totals now distinguish:

- gross total: `total_dzd`,
- credit notes: `credit_note_total_dzd`,
- net total: `net_total_dzd`,
- paid: `paid_dzd`,
- balance: `balance_due_dzd`.

## Private PDFs and Receipts

Credit note PDFs are stored on the private disk:

`storage/app/private/corporate/credit-notes/{reference}.pdf`

Corporate payment receipts are downloaded only through protected controller routes:

- admin: `/admin/corporate-payments/{payment}/receipt/download`
- org portal: `/org/payments/{payment}/receipt/download`

No receipt, invoice, report, agreement, proposal, or credit note file should be exposed through `public/storage`.

## Financial Transaction Behavior

Positive recognized revenue:

- `type = revenue`
- `source_type = corporate_payment_allocation`
- `source_id = corporate_payment_allocations.id`

Reversal correction:

- `type = revenue`
- `source_type = corporate_payment_allocation_reversal`
- `source_id = corporate_allocation_reversals.id`
- `amount_dzd` is negative

This prevents double counting while preserving a traceable ledger-style correction.

## Permissions

New permissions:

- `corporate_payments.reverse_allocation`
- `corporate_payments.download_receipt`
- `corporate_credit_notes.view`
- `corporate_credit_notes.create`
- `corporate_credit_notes.issue`
- `corporate_credit_notes.apply`
- `corporate_credit_notes.void`
- `corporate_credit_notes.download`

Admin and super admin receive these permissions by default. Support keeps limited view access unless explicitly granted more.

## Receivables

Receivables use the invoice net total after credit notes and exclude reversed allocations from effective paid totals.

This means:

- reversing an allocation increases outstanding balance,
- applying a credit note reduces outstanding balance,
- overdue/paid/partial status is recalculated from net total and active paid amount.

## Limitations

Deferred intentionally:

- partial allocation reversal,
- VAT-specific credit note accounting,
- advanced accounting ledger automation,
- public expiring links for credit note or receipt download,
- payment gateway integration.