# Entity: Member

Employee or dependant enrolled under an organisation's corporate medical benefit.

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

## Fields

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `id` | `string` | ✓ | `mbr_*` |
| `org_id` | `string` | ✓ | |
| `customer_id` | `string` | | Shared Gishen customer identity (Ecom/Mob) |
| `employee_id` | `string` | | Org HR identifier |
| `full_name` | `string` | ✓ | |
| `email` | `string` | | |
| `phone` | `Phone` | ✓ | Primary contact |
| `department_id` | `string` | | FK → Department |
| `package_id` | `string` | | Assigned benefit plan |
| `role` | `MemberPortalRole` | ✓ | Portal access |
| `member_type` | `MemberType` | ✓ | |
| `primary_member_id` | `string` \| null | | For dependants |
| `status` | `MemberStatus` | ✓ | |
| `start_date` | `date` | | Coverage start |
| `end_date` | `date` \| null | | Offboarding |
| `overrides` | `MemberOverrides` | | Per-member entitlement tweaks |
| `verification_id` | `string` | | Employee ID / QR payload |
| `invite_id` | `string` | | If joined via invite |
| `allowance_summary` | `AllowanceSummary` | | Read-only computed |
| `prescription_count` | `integer` | | Aggregate only for HR/Finance |
| `created_at` | `Timestamp` | ✓ | |
| `updated_at` | `Timestamp` | ✓ | |
| `version` | `integer` | ✓ | |

### MemberPortalRole

```
MEMBER | HR_ADMIN | FINANCE | SUPER_USER
```

A user may hold multiple portal roles; stored on linked `User`, reflected here for display.

### MemberType

```
primary | dependant
```

### MemberStatus

```
invited | active | inactive | offboarded
```

### MemberOverrides

| Field | Type | Notes |
|-------|------|-------|
| `allowance_cap` | `Money` \| null | Overrides package cap |
| `copay_percent` | `number` \| null | 0–100 |
| `excluded_categories` | `string[]` | |
| `included_perks` | `string[]` | Extra perk codes |

### AllowanceSummary

| Field | Type | Notes |
|-------|------|-------|
| `period_start` | `date` | |
| `period_end` | `date` | |
| `allowance_total` | `Money` | |
| `allowance_used` | `Money` | |
| `allowance_remaining` | `Money` | Shown to member pre-checkout |

## Validation rules

| Rule | Error code |
|------|------------|
| Org must be `active` for create (except migration draft) | `ORG_PENDING` |
| Unique `phone` per org (active members) | `DUPLICATE_MEMBER` |
| Unique `employee_id` per org if set | `DUPLICATE_MEMBER` |
| Dependant requires `primary_member_id` | `VALIDATION_FAILED` |
| Dependant count ≤ org `dependant_limit` | `DEPENDANT_LIMIT_EXCEEDED` |
| `package_id` must exist and be active | `NOT_FOUND` |

## Clinical withhold

When `SessionUser.roles` includes HR_ADMIN or FINANCE **without** SUPER_USER:

| Field | Visible |
|-------|---------|
| `full_name`, `email`, `phone`, `employee_id`, `department_id`, `package_id`, `status` | ✓ |
| `allowance_summary` (amounts only) | ✓ |
| `prescription_count` | ✓ (count only) |
| Prescription list / images / medicine lines | ✗ |
| `customer_id` order line medicine detail | ✗ (category + amount in finance spend only) |

SUPER_USER and MEMBER (own record) receive full clinical linkage via prescription endpoints.

## Sample payload (HR view)

```json
{
  "id": "mbr_01HMEM001",
  "org_id": "org_01HQXYZ",
  "customer_id": "cus_01HSHARED",
  "employee_id": "EMP-1042",
  "full_name": "Abel Mekonnen",
  "email": "abel.m@acme.et",
  "phone": "+251911111111",
  "department_id": "dept_01HABC",
  "package_id": "pkg_01HGOLD",
  "role": "MEMBER",
  "member_type": "primary",
  "primary_member_id": null,
  "status": "active",
  "start_date": "2026-01-01",
  "end_date": null,
  "overrides": null,
  "verification_id": "EMP-1042",
  "allowance_summary": {
    "period_start": "2026-03-01",
    "period_end": "2026-03-31",
    "allowance_total": { "amount": "15000.00", "currency": "ETB" },
    "allowance_used": { "amount": "4200.00", "currency": "ETB" },
    "allowance_remaining": { "amount": "10800.00", "currency": "ETB" }
  },
  "prescription_count": 2,
  "created_at": "2026-01-05T10:00:00Z",
  "updated_at": "2026-03-10T14:00:00Z",
  "version": 8
}
```

## Invite token (related)

| Field | Type |
|-------|------|
| `token` | `string` |
| `member_id` | `string` |
| `expires_at` | `Timestamp` |
| `accepted_at` | `Timestamp` \| null |

## Related endpoints

- [`../endpoints/members.md`](../endpoints/members.md)