# Corporate Phase 1 Foundation

## Canonical Model

`Organization` is the official B2B tenant model for all new corporate work:

- `organizations`
- `organization_members`
- `org_employees`
- `org_enrollments`
- `org_audit_logs`

Legacy `companies`, `users.company_id`, and `agreement_path` are not used for new work. They are kept only as compatibility references until a future migration phase decides whether to remove or map them.

## Public Routes

- `/b2b` renders the corporate landing page and lead form.
- `/institutions` redirects to `/b2b`.
- `/corporate` redirects to `/b2b`.

The B2B lead form now normalizes Algerian phone numbers into `phone_e164`, applies per-IP submission throttling, and prevents duplicate requests for the same phone, email, or institution name during the recent lead window.

## Admin Lead Lifecycle

Admin routes:

- `/admin/b2b/leads`
- `/admin/b2b/leads/{lead}`

Lead statuses:

- `new`
- `contacted`
- `qualified`
- `proposal_needed`
- `proposal_sent`
- `converted`
- `lost`
- `closed`

Each lead can be assigned, scheduled for a next action, updated, closed as lost, annotated with notes, and converted to an `Organization`.

## Conversion To Organization

Conversion checks for an existing organization by email, normalized phone, Arabic/French name, or legal name before creating a new record. If a match exists, the admin must explicitly link to it. Conversion updates the lead snapshot, records a lead activity, and writes an organization audit entry.

This phase does not create proposals, offers, agreements, corporate cohorts, or employee user accounts.

## Tenancy Security

The organization selector no longer trusts role data from the browser. It loads the active membership from the database and stores only the verified organization id and role.

The tenancy middleware now checks:

- `selected_organization_id` exists in session.
- the current user still has an active membership in that organization.
- the organization is active.
- app tenancy context is set from the verified membership.

Invalid or stale organization selections are cleared and redirected back to organization selection.

## Permissions

New permissions:

- `b2b.leads.view`
- `b2b.leads.update`
- `b2b.leads.assign`
- `b2b.leads.convert`
- `b2b.leads.close`
- `organizations.view`
- `organizations.update`
- `org.employees.view`
- `org.employees.manage`
- `org.enrollments.view`
- `org.enrollments.manage`
- `org.members.view`
- `org.members.manage`

`super_admin` and `admin` receive the full B2B and organization foundation permissions. `support` receives lead view/update/assign only.

## Messaging

When a public B2B lead is created:

- a Telegram admin alert is logged with template key `admin_new_b2b_lead`.
- a WhatsApp outbox message is queued with template key `b2b_lead_received`.

No external API call is sent synchronously during form submission.

## Next Phases

1. Proposals and commercial offers.
2. Agreements and approval workflow.
3. Corporate cohorts and bulk employee enrollment import.
4. Corporate finance, invoicing, and payment reconciliation.
5. Full B2B reports and dashboards.