# Feature: Org & departments

Organisation profile, commercial field visibility, departments/sites, and verification settings.

**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`

## Pages

| Route | Purpose |
|-------|---------|
| `/organisation` | Org profile — HR-managed fields + read-only commercial (when active) |
| `/departments` | Department/site list with search/site filter |
| `/departments/new` | Create department (site, sub-limit, optional parent) |
| `/settings/verification` | Verification method for member checkout |

## Entities

- [`Organisation`](../backend/entities/organisation.md)
- [`Department`](../backend/entities/department.md)

## Endpoints

- [`org.md`](../backend/endpoints/org.md)
  - `GET /v1/org`, `PATCH /v1/org`
  - `GET/POST/PATCH/DELETE /v1/org/departments*`
  - `PATCH /v1/org/verification`

## Commercial fields (Admin-owned)

Displayed read-only on `/organisation` once active:

- Credit limit & usage
- Payment terms
- Price list reference
- Contract start/end
- Activation date

HR cannot mutate these — attempts return `403 FORBIDDEN`.

## HR-managed fields

Editable by SUPER_USER / HR_ADMIN:

- Display name
- Dependant limit
- Join rules (join code, email domains)
- Verification settings

## Departments

| Capability | Roles |
|------------|-------|
| List / view | SUPER_USER, HR_ADMIN, FINANCE |
| Create / edit / deactivate | SUPER_USER, HR_ADMIN |

Sub-limits optional per department for finance reporting and cap enforcement.

## Verification settings

| Method | Description |
|--------|-------------|
| `employee_id` | Member enters employee ID at checkout |
| `qr_code` | QR issued per member |
| `domain_email` | Email domain match |
| `manual_hr` | HR verifies manually |

`require_at_checkout`: when true, Ecom checkout blocks until verified.

## Validation / errors

| Scenario | Code |
|----------|------|
| Duplicate department name | `DUPLICATE_DEPARTMENT` |
| Delete dept with members | `DEPARTMENT_IN_USE` |
| Edit commercial from B2B | `FORBIDDEN` |
| Org pending | `ORG_PENDING` on mutations |

## Clinical withhold

No clinical data on org/department screens.

## UI notes

- Commercial section: card with credit utilization bar (mint/forest brand)
- Department table: name, code, parent, sub-limit, member count, actions
- Verification: radio group + switch for checkout requirement

## Related features

- [finance.md](finance.md) — spend by department
- [members.md](members.md) — member department assignment
- [migration.md](migration.md) — department bulk import