Gishen-B2B/docs/backend/entities

Entities index

Data model entities required by Gishen-B2B. Types below are canonical for mocks in src/types/ and the future shared API.

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

Entity catalog

Entity	Doc	Primary consumers
Organisation	organisation.md	All roles (scoped)
Org registration	org-registration.md	Public signup, Admin
Department	department.md	HR, Finance (aggregates)
Member	member.md	HR, Member; Finance (metadata); pharmacy ID card (avatar_url, card_id, verification_id)
Package	package.md	HR, Member
Migration job	migration-job.md	HR, SUPER_USER
Finance	finance.md	Finance, HR (read), SUPER_USER
Prescription	prescription.md	Member, SUPER_USER; Admin review
Session user	session-user.md	Auth layer

ID conventions

org_01HXXXXXXXXXXXXXX
dept_01HXXXXXXXXXXXXXX
mbr_01HXXXXXXXXXXXXXX
pkg_01HXXXXXXXXXXXXXX
mig_01HXXXXXXXXXXXXXX
rx_01HXXXXXXXXXXXXXX
usr_01HXXXXXXXXXXXXXX

ULID-style prefixes for human readability in logs.

Printed pharmacy card numbers use org-scoped display IDs (e.g. GSH-1042) on Member.card_id — not a separate entity.

Common field types

Type	Format
Money	{ "amount": "1250.00", "currency": "ETB" } — decimal string
Timestamp	ISO 8601 UTC
Phone	E.164, e.g. +251911234567
Locale	en | am

Cross-cutting enums

OrgStatus

pending_activation | active | suspended | closed

MemberStatus

invited | active | inactive | offboarded

PrescriptionStatus

draft | submitted | under_review | approved | queried | rejected

Clinical withhold (entity-level)

When serializing for HR_ADMIN or FINANCE:

Entity	Withheld fields
Prescription	pages[], medicine_lines[], prescriber_notes, diagnosis_codes
Member (finance view)	Link to full Rx list — only prescription_count aggregate
Order line (if clinical)	Medicine SKU detail → category + amount only

SUPER_USER receives full payloads. MEMBER receives own clinical data only.

Relationships (ER sketch)

Organisation 1──* Department
Organisation 1──* Member
Organisation 1──* Package
Member *──1 Package (assignment)
Member 1──* Prescription
Member 0──1 Member (primary_member for dependants)
Organisation 1──* MigrationJob
Organisation 1──* Statement (finance)

Versioning

Each entity includes created_at, updated_at. Optimistic concurrency via version (integer) on mutable resources.