Archived

This repository has been archived on 2026-08-11. You can view files and clone it, but cannot push or open issues or pull requests.

kirukib 8fe6d58a09 Document portal auth, profile, and pharmacy ID contracts in backend specs.

Keep the living API sheet aligned with demo personas, avatars, ID-card QR scan, list filters, and Admin/Ecom coordination.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-06 22:10:07 +03:00

3.6 KiB

Raw Blame History

Entity: Session user

Authenticated user context for B2B portal — demo mock now, JWT/session later.

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

Fields

Field	Type	Required	Notes
`id`	`string`	✓	`usr_` or demo `user_`
`email`	`string`	✓
`full_name`	`string`	✓
`phone`	`Phone`
`org_id`	`string`	✓	Active tenant
`member_id`	`string`		Link to Member row if enrolled
`customer_id`	`string`		Shared Gishen customer (Ecom/Mob)
`roles`	`PortalRole[]`	✓	One or more
`active_role`	`PortalRole`	✓	Role used for nav + withhold (must ∈ `roles`)
`locale`	`Locale`	✓	`en` \| `am`
`avatar_url`	`string`		Portrait URL (demo: deterministic DiceBear)
`org_status`	`OrgStatus`	✓	Denormalized for gating
`permissions`	`string[]`		Computed from `active_role` / roles
`demo_profile`	`DemoProfile`		Mock only

PortalRole

SUPER_USER | HR_ADMIN | FINANCE | MEMBER

DemoProfile (mock `/login` only)

Field	Type
`label`	`string`
`description`	`string`

Pre-seeded demo personas: user_super, user_hr, user_fin, user_mem against a shared mock org. Listed via GET /v1/auth/demo-profiles.

Computed permissions

Permission	Roles
`org:read`	SUPER_USER, HR_ADMIN, FINANCE
`org:write_hr`	SUPER_USER, HR_ADMIN
`members:write`	SUPER_USER, HR_ADMIN
`packages:write`	SUPER_USER, HR_ADMIN
`migration:write`	SUPER_USER, HR_ADMIN
`finance:read`	SUPER_USER, HR_ADMIN, FINANCE
`finance:approve`	SUPER_USER, FINANCE
`clinical:read`	SUPER_USER, MEMBER (own)
`prescriptions:write`	MEMBER (own), SUPER_USER
`id_card:print`	SUPER_USER, HR_ADMIN, MEMBER (own)

Locale preference

locale is persisted on the user record and returned in session. Updated via PATCH /v1/auth/me/locale or PATCH /v1/me/profile. Synced to client cookie/localStorage for next-intl.

Active role

Multi-role users (demo Super User) can set active_role on /profile. Portal nav and clinical withhold follow active_role for the session.

Clinical withhold

Session drives RBAC. If effective role is HR_ADMIN or FINANCE and not SUPER_USER, all prescription and clinical serializers apply withhold filters automatically.

Sample session (mock demo — HR)

{
  "id": "user_hr",
  "email": "hr@yaltopia.com",
  "full_name": "Hanna HR",
  "phone": "+251900000001",
  "org_id": "org_yaltopia",
  "member_id": null,
  "customer_id": null,
  "roles": ["HR_ADMIN"],
  "active_role": "HR_ADMIN",
  "locale": "en",
  "avatar_url": "https://api.dicebear.com/9.x/lorelei/svg?seed=user_hr",
  "org_status": "active",
  "permissions": ["org:read", "org:write_hr", "members:write", "packages:write", "migration:write", "finance:read", "id_card:print"],
  "demo_profile": {
    "label": "HR Administrator",
    "description": "Manage members, departments, and packages"
  }
}

Sample session (SUPER_USER)

{
  "id": "user_super",
  "email": "super@yaltopia.com",
  "full_name": "Selam Super",
  "roles": ["SUPER_USER", "HR_ADMIN", "FINANCE", "MEMBER"],
  "active_role": "SUPER_USER",
  "locale": "am",
  "avatar_url": "https://api.dicebear.com/9.x/lorelei/svg?seed=user_super",
  "permissions": ["*"],
  "demo_profile": {
    "label": "Super User",
    "description": "Full portal access including clinical detail"
  }
}

../endpoints/auth.md — login, demo-profiles, /me/profile

3.6 KiB Raw Blame History