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:

• 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