kirukib
8fe6d58a09
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>
114 lines
3.6 KiB
Markdown
114 lines
3.6 KiB
Markdown
# 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)
|
|
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
```json
|
|
{
|
|
"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"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Related endpoints
|
|
|
|
- [`../endpoints/auth.md`](../endpoints/auth.md) — login, demo-profiles, `/me/profile`
|