# Corporate Phase 3 Agreements Audit

Date: 2026-05-08

## Scope

This audit checks whether an agreement/convention module already exists before implementing Corporate Phase 3.

## Existing Agreement Code

Status: Missing for the canonical corporate flow.

Evidence:

- No `CorporateAgreement`, `corporate_agreements`, `corporate_agreement_files`, or `corporate_agreement_activities` model/table/view exists.
- No admin routes for `/admin/corporate-agreements` exist.
- `CorporateProposal` already reserves the `converted_to_agreement` status, but Phase 2 only displays a disabled placeholder.

## Legacy Agreement Fields

Status: Legacy only, must not be reused.

Evidence:

- `database/migrations/2026_02_14_143000_create_companies_table.php` creates legacy `companies.agreement_path`.
- `database/migrations/2026_02_14_143500_add_company_id_to_users_table.php` creates legacy `users.company_id`.
- `docs/corporate_data_model_decision.md` explicitly states `companies`, `users.company_id`, and `companies.agreement_path` are compatibility-only and not valid for new corporate work.

Decision:

- Do not read or write `agreement_path`.
- Do not link agreements to `companies` or `users.company_id`.

## EventOffer Boundary

Status: Existing, unrelated.

Evidence:

- `App\Models\EventOffer` and related admin/public Livewire pages are scoped to events.
- Phase 2 audit already documented that EventOffer is out of scope for corporate proposals.

Decision:

- Do not reuse `EventOffer` for corporate agreements.

## Corporate Proposal Foundation

Status: Ready for conversion.

Evidence:

- `App\Models\CorporateProposal` has statuses including `accepted` and `converted_to_agreement`.
- Proposal has `organization_id`, `b2b_lead_id`, title, terms, total amount, items, activities, and private PDF support.
- Existing Phase 2 policy and admin detail page protect proposal actions.

## What Phase 3 Will Create

New database tables:

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

New application units:

- `CorporateAgreement`, `CorporateAgreementFile`, `CorporateAgreementActivity`
- agreement reference generator
- agreement workflow service
- agreement PDF service
- agreement notification service
- agreement file download controller
- `CorporateAgreementPolicy`
- admin Livewire index/form/detail pages

## Relationship Rules

Agreement relationships:

- `corporate_agreements.organization_id` is required and points to `organizations.id`.
- `corporate_agreements.corporate_proposal_id` is nullable by schema for future manual agreements, but Phase 3 creates agreements from proposals only.
- `corporate_agreements.b2b_lead_id` is nullable for traceability.

Creation guard:

- Agreement creation is allowed only from `CorporateProposal::STATUS_ACCEPTED`.
- The proposal must have `organization_id`.
- Accepted proposals that are only linked to an unconverted B2B lead must be blocked until the lead is converted to `Organization`.

## Workflow Decision

When an agreement is created from an accepted proposal:

- create `CorporateAgreement` in `draft`;
- immediately set proposal status to `converted_to_agreement`;
- log activity on both the proposal and the agreement.

This makes the sales pipeline explicit: an accepted proposal has entered the agreement workflow and should not be edited as an active proposal anymore.

## Out Of Scope

- No Corporate Cohorts in this phase.
- No invoices or full finance module.
- No `companies` compatibility migration.
- No EventOffer reuse.