# 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](organisation.md) | All roles (scoped) |
| Org registration | [org-registration.md](org-registration.md) | Public signup, Admin |
| Department | [department.md](department.md) | HR, Finance (aggregates) |
| Member | [member.md](member.md) | HR, Member; Finance (metadata only) |
| Package | [package.md](package.md) | HR, Member |
| Migration job | [migration-job.md](migration-job.md) | HR, SUPER_USER |
| Finance | [finance.md](finance.md) | Finance, HR (read), SUPER_USER |
| Prescription | [prescription.md](prescription.md) | Member, SUPER_USER; Admin review |
| Session user | [session-user.md](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.

## 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.