Gishen-B2B/docs/product/b2b-features.md

# §3 B2B feature checklist

Product brief for **Gishen-B2B** — institutional portal for organisations that cover medical/pharmacy expenses for employees and dependants.

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

## Product framing

- The **organisation** holds the contract, credit limit, and monthly invoice.
- **HR** enrols people and configures coverage (packages / entitlements).
- **Finance** sees spend against coverage and statements — not clinical detail.
- **Members** use covered allowance; prescriptions and personal history stay with the person if they leave the org.

## Roles

| Role | Code | Portal access |
|------|------|---------------|
| Super User | `SUPER_USER` | Full access — HR + Finance + settings + any member record; clinical withhold **does not** apply |
| HR Administrator | `HR_ADMIN` | Org profile (read commercial), departments, members, import/invite, packages, verification, offboarding — **no** clinical detail |
| Finance Approver | `FINANCE` | Spend, Excel, statements, credit usage, threshold approve/flag — **no** clinical detail; no HR enrol mutations unless also granted |
| Member | `MEMBER` | Own plan/allowance, orders, Rx upload/status, loyalty — no org-wide HR/Finance |

Multiple roles per user are allowed in the data model. Mock login at `/login` includes a demo role selector for all four personas.

## Feature checklist

### Auth & shell

- [ ] Demo login with role selector (SUPER_USER / HR_ADMIN / FINANCE / MEMBER)
- [ ] Role-filtered navigation and route guards
- [ ] Clinical withhold enforcement for HR_ADMIN and FINANCE
- [ ] AppShell: collapsible sidebar, topbar (search, notifications, profile, language switcher)
- [ ] PageShell / detail / create layouts (Fortune Admin `ui` patterns + shadcn)
- [ ] Gishen brand tokens (mint `#a8c73a`, forest `#141414`)

### i18n

- [ ] English + Amharic at launch
- [ ] Language switcher on `/login` and topbar/profile
- [ ] `user.locale` preference persisted

### Org registration

- [ ] Self-register: company details + first SUPER_USER → `pending_activation`
- [ ] Request-to-register: email/phone capture → `org_registration_request`
- [ ] Pending org UX: status visible; entitlements blocked until Admin activates
- [ ] Events: `org.registration_submitted`, `org.registration_requested`, `org.activated`

### Org & departments

- [ ] Org profile — read commercial fields once active (credit, terms, price list, contract dates)
- [ ] Departments/sites with sub-limits
- [ ] Verification method setup (`/settings/verification`)

### Data migration

- [ ] Migration hub, new job wizard, job detail/progress
- [ ] Datasets: departments, packages, members, overrides, dependants, verification IDs
- [ ] Upload Excel/CSV, column mapper, validation report, preview, commit
- [ ] Events: `migration.job_started`, `migration.job_completed`, `migration.job_failed`

### Members & onboarding

- [ ] Members CRUD, detail, dependants
- [ ] Quick Excel import (`/members/import`)
- [ ] Invites (`/invite/[token]`), join codes, domain rules (`/join`)
- [ ] Offboarding

### Packages & entitlements

- [ ] Corporate packages (benefit plans): allowance, co-pay, categories, perks, caps/exclusions
- [ ] Per-member overrides
- [ ] Allowance views for members

### Finance

- [ ] Spend by department / member / category
- [ ] Excel export
- [ ] Monthly statements (`/statements`)
- [ ] Credit usage vs limit
- [ ] Threshold approve/flag (`/finance/approvals`)

### Member experience

- [ ] Member home: plan/allowance summary (`/me`)
- [ ] Order history (`/me/orders`)
- [ ] Prescription upload + status (`/prescriptions`, `/prescriptions/new`)
- [ ] Loyalty summary pointer (customer identity shared with Ecom)
- [ ] Remaining allowance visible before checkout (split UI lives in Ecom — see coordination)

### Prescriptions (member-facing)

- [ ] Multi-page photo/file upload (web)
- [ ] Status: submitted → under review → approved / queried / rejected
- [ ] Refill reminders when days-of-supply low
- [ ] Review/dispensing in Admin pharmacist queue
- [ ] Event: `prescription.submitted`

## Route map

| Area | Routes |
|------|--------|
| Auth | `/login` |
| Org signup | `/register/organisation`, `/register/request` |
| Org (HR) | `/organisation`, `/departments`, `/settings/verification` |
| Migration | `/migration`, `/migration/new`, `/migration/[jobId]` |
| People | `/members`, `/members/import`, `/members/[id]`, `/join`, `/invite/[token]` |
| Packages | `/packages`, `/packages/[id]` |
| Member | `/me`, `/me/orders`, `/prescriptions`, `/prescriptions/new` |
| Finance | `/finance`, `/finance/approvals`, `/statements` |

## Out of scope (this repo)

- Health trackers, educational content, community, AI Phase 2+, Referral Program v2
- Handwritten Rx OCR; mobile edge-detection camera (Mobile repo)
- Building Admin / Ecom / Mobile UIs
- Implementing the shared backend service
- Admin-owned credit/price list activation UI (Admin repo)

## Open cross-repo items

See [`coordination/open-items.md`](../coordination/open-items.md):

- Checkout entitlement split (org credit vs member gateway) — shared with Ecom
- Telegram Mini App rides Ecom backend spec

## Spec sync

Each checked feature above must have corresponding entries in:

- `docs/backend/entities/`
- `docs/backend/endpoints/`
- `docs/backend/events/` (when state crosses systems)
- `docs/features/INDEX.md`