# Corporate Phase 3: Agreements

## Scope

Phase 3 converts accepted corporate proposals into official agreements. It covers agreement records, private PDF generation, signed PDF upload, workflow states, permissions, and notifications.

This phase does not create corporate cohorts, invoices, or finance automation.

## Data Model

Canonical tables:

- `corporate_agreements`
- `corporate_agreement_files`
- `corporate_agreement_activities`

Relationships:

- `CorporateAgreement` belongs to `Organization`.
- `CorporateAgreement` optionally belongs to `CorporateProposal` for traceability.
- `CorporateAgreement` optionally belongs to `B2bLead`.
- `CorporateProposal` has one agreement in this phase.

Legacy `companies`, `users.company_id`, and `companies.agreement_path` remain forbidden for new corporate work.

## Creation Rule

Agreements are created from accepted proposals only.

Required conditions:

- proposal status is `accepted`;
- proposal has `organization_id`;
- organization is the canonical `organizations` table.

When created, the agreement starts as `draft` and the proposal is immediately updated to `converted_to_agreement`.

## Workflow

Allowed transitions:

- `draft -> sent_for_signature`
- `sent_for_signature -> signed`
- `signed -> active`
- `active -> completed`
- `draft|sent_for_signature|signed|active -> cancelled`

Terminal states:

- `completed`
- `cancelled`

Rules:

- `send_for_signature` requires a generated PDF.
- `mark_signed` requires a signed PDF upload.
- `cancel` requires a cancellation reason.

## Private Files

Generated agreement PDFs are stored at:

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

Signed copies are stored under:

`storage/app/private/corporate/agreements/signed/`

Files are downloaded only through protected admin routes. No public URLs are created.

## Permissions

- `corporate_agreements.view`
- `corporate_agreements.create`
- `corporate_agreements.update`
- `corporate_agreements.generate_pdf`
- `corporate_agreements.send_for_signature`
- `corporate_agreements.upload_signed`
- `corporate_agreements.mark_signed`
- `corporate_agreements.activate`
- `corporate_agreements.complete`
- `corporate_agreements.cancel`
- `corporate_agreements.download_files`

Admins and super admins receive full access. Support receives view-only access by default.

## Notifications

Non-blocking messaging records are created for:

- `admin_corporate_agreement_created`
- `institution_agreement_ready`
- `admin_corporate_agreement_signed`
- `admin_corporate_agreement_activated`

Messaging failures are reported but do not block agreement workflow actions.

## Remaining For Phase 4

- Corporate cohort creation from active agreements.
- Bulk employee import.
- Corporate learner enrollment.
- Group finance/invoicing.