# Gishen Admin — Entity schemas

**Living schema pack** for the Admin backend contract and cross-app master.  
**Spec sheet:** [`admin-backend-spec.md`](./admin-backend-spec.md) · **Master:** [`GISHEN-MASTER-SPEC.md`](./GISHEN-MASTER-SPEC.md)

| Field | Value |
| --- | --- |
| **Source of types** | `src/types/index.ts`, `src/mocks/catalog.ts`, `src/mocks/data.ts` |
| **Wire format** | JSON over REST (`application/json`) |
| **Timestamps** | ISO-8601 UTC (`2026-08-06T08:30:00Z`) unless noted |
| **IDs** | Prefer prefix + opaque id (`org_*`, `rx_*`, `ord_*`, `adm_*`) or UUID — pick one platform-wide |

When you change a field on a main element, update **this file**, the Admin sheet changelog, and the master schema summary in the same change.

## Changelog

| Date | Change |
| --- | --- |
| 2026-08-08 | Initial schema pack for Money, Staff, Org/Commercial, Doctor, Rx, Order, Catalogue Item/UOM, Stock, Customer, Settlement, Dispatch trip, envelopes |

---

## Index

| Schema | Kind | Cross-app |
| --- | --- | --- |
| [Money](#money) | Shared value object | B2B `Money` |
| [Envelopes](#api-envelopes) | List / error / event | B2B pagination preferred long-term |
| [StaffUser](#staffuser) | Admin principal | — |
| [Branch](#branch) | Location | Ecom `/branches` |
| [Organisation](#organisation--commercialterms) | B2B / hospital account | B2B `organisation.md` |
| [Doctor](#doctor) | External clinical actor | Open IdP |
| [Prescription](#prescription) | Rx queue | B2B Rx clinical withhold |
| [Order](#order) | Branch fulfilment | Ecom/Mob orders |
| [MedicationItem](#medicationitem--itemuom) | Catalogue master | Mob/Ecom PDP + catalog |
| [StockRow](#stockrow) | Branch inventory | ERP sync |
| [Customer](#customer) | CRM / loyalty | Shared `customer_id` |
| [Settlement](#settlement) | Finance batch | — |
| [RiderTrip](#rider--ridertrip) | Dispatch | Dispatch Bot |
| [MigrationJob](#migrationjob) | Admin imports | Distinct from B2B tenant migration |

---

## Money

```ts
interface Money {
  amount: string   // decimal major units, e.g. "1250.00"
  currency: 'ETB'
}
```

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `amount` | `string` | ✓ | Decimal string — never float JSON numbers for money |
| `currency` | `"ETB"` | ✓ | Only ETB in v1 |

Admin UI may keep parallel numeric major-ETB fields (`creditLimitEtb`, `totalEtb`) for demos — **API wiring uses `Money`** (or syncs numbers from `commercial`).

---

## API envelopes

### Success (single)

```ts
type DataEnvelope<T> = { data: T }
```

### Success (list) — target platform

```ts
type ListEnvelope<T> = {
  data: T[]
  pagination: {
    page: number
    page_size: number
    total_items: number
    total_pages: number
  }
}
```

Legacy Admin sketches: `?page=&limit=` → `{ data, meta: { page, limit, total } }`. Prefer `page_size` / `pagination` when consolidating with B2B.

### Error

```ts
type ErrorEnvelope = {
  error: {
    code: string
    message: string
    details?: Array<{ field?: string; code?: string; message: string }> | Record<string, unknown>
    request_id?: string
  }
}
```

### Domain event

```ts
type DomainEvent<T = Record<string, unknown>> = {
  id: string
  type: string              // e.g. "org.activated", "prescription.review_updated"
  occurred_at: string       // ISO timestamp
  org_id?: string | null
  actor_id?: string | null
  payload: T
  schema_version: string    // "1"
}
```

---

## StaffUser

```ts
type StaffRole =
  | 'pharmacist'
  | 'stock_manager'
  | 'procurement'
  | 'finance'
  | 'marketing_manager'
  | 'operations'
  | 'super_admin'

type AuthProvider = 'email' | 'google' | 'phone' | 'telegram'

interface StaffUser {
  id: string
  name: string
  email: string
  role: StaffRole
  branchId?: string
  branchName?: string
  preferredLocale?: 'en' | 'am'
  avatarUrl?: string
  authProvider?: AuthProvider
  phone?: string
}
```

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `id` | `string` | ✓ | Staff principal id |
| `name` | `string` | ✓ | Display name |
| `email` | `string` | ✓ | Login / Google subject email |
| `role` | `StaffRole` | ✓ | Single primary role in Admin SPA |
| `branchId` | `string` | | Required for pharmacist (and optionally stock) |
| `preferredLocale` | `"en" \| "am"` | | UI language |
| `authProvider` | `AuthProvider` | | How this session was established |

**Not** a StaffRole: Doctor, B2B `SUPER_USER` / `HR_ADMIN` / `FINANCE` / `MEMBER`, retail `customer`.

### Login response sketch

```json
{
  "accessToken": "...",
  "refreshToken": "...",
  "user": {
    "id": "adm_01H...",
    "name": "Hana Pharmacist",
    "email": "pharmacist@gishen.et",
    "role": "pharmacist",
    "branchId": "br-bole",
    "branchName": "Bole Branch",
    "preferredLocale": "en",
    "authProvider": "email"
  }
}
```

---

## Branch

```ts
interface Branch {
  id: string
  name: string
  zone: string
  phone: string
  lat?: number
  lng?: number
  hours?: string
}
```

---

## Organisation & CommercialTerms

```ts
type OrganisationType = 'corporate' | 'hospital' | 'clinic' | 'ngo' | 'other'
type OrgStatus = 'pending_activation' | 'active' | 'suspended' | 'closed' | 'rejected'

interface CommercialTerms {
  credit_limit: Money
  credit_used: Money
  payment_terms_days: number
  price_list_id?: string
  contract_start?: string   // ISO date YYYY-MM-DD
  contract_end?: string
  activated_at?: string
  activated_by?: string     // admin user id
}

interface Organisation {
  id: string
  name: string
  orgType: OrganisationType
  tin: string
  vatNumber?: string
  businessLicense?: string
  commercialRegistration?: string
  status: OrgStatus
  commercial: CommercialTerms | null
  /** Demo UI only — keep in sync with commercial when set */
  creditLimitEtb: number
  usedEtb: number
  billingContact: string
  source: 'admin' | 'self_register'
  createdAt: string
  reviewedBy?: string
  reviewedAt?: string
  decisionNote?: string
}
```

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `orgType` | `OrganisationType` | ✓ | `hospital` / `clinic` unlock Doctors roster |
| `status` | `OrgStatus` | ✓ | Canonical lifecycle (not bare `pending`) |
| `commercial` | `CommercialTerms \| null` | ✓ | `null` until activate / admin-create |
| `tin` | `string` | ✓ | 10-digit Ethiopian TIN |
| `source` | `admin \| self_register` | ✓ | Who created the org |

### Activate request body

```ts
type OrgActivateBody = {
  commercial: {
    credit_limit: Money
    payment_terms_days: number
    price_list_id?: string
    contract_start?: string
    contract_end?: string
  }
  admin_notes?: string
}
```

Emits `org.activated`. Sample commercial payload matches B2B `organisation.md`.

---

## Doctor

```ts
interface Doctor {
  id: string
  name: string
  specialty: string
  licenseNumber: string
  phone: string
  email: string
  status: 'active' | 'inactive'
  orgId: string
  orgName: string
  branchId?: string
  branchName?: string
  hasLinkedAccount: boolean
  createdAt: string
  updatedAt: string
  avatarUrl?: string
}
```

Affiliation org **must** be `orgType` `hospital` or `clinic`. Auth: `POST /auth/doctor/login` (separate JWT / `actor=doctor`).

---

## Prescription

```ts
type DosingFrequency = 'QD' | 'BID' | 'TID' | 'QID' | 'QXH' | 'custom'
type PrescriptionStatus =
  | 'draft'           // B2B/Ecom may create drafts
  | 'submitted'
  | 'under_review'
  | 'approved'
  | 'queried'
  | 'rejected'

interface PrescriptionItem {
  name: string
  qty: number
  controlled?: boolean
  frequency?: DosingFrequency
  intervalHours?: number   // when frequency === 'QXH'
  times?: string[]         // HH:mm 24h — Mob reminder seed
  sku?: string
  dosage?: string
  instructions?: string
}

interface Prescription {
  id: string
  customerName: string
  branchId: string
  status: Exclude<PrescriptionStatus, 'draft'> | PrescriptionStatus
  items: PrescriptionItem[]
  submittedAt: string
  prescriber?: string
  doctorId?: string
  orgId?: string
  customerId?: string      // shared platform identity when known
  memberId?: string        // B2B member when from institutional portal
  reviewStartedAt?: string
  reviewedBy?: string
  reviewedAt?: string
  decisionNote?: string
  query_message?: string
  rejection_reason?: string
  days_supply?: number
  refill_due_at?: string
}
```

| Rule | Notes |
| --- | --- |
| Clinical withhold | HR/Finance B2B never receive `items`, images, diagnosis |
| Verify | `POST /admin/prescriptions/:id/verify` → `prescription.review_updated` |
| Dosing helper | `src/lib/dosingSchedule.ts` |

### Verify body

```ts
type PrescriptionVerifyBody = {
  status: 'approved' | 'queried' | 'rejected'
  medicine_lines?: PrescriptionItem[]
  qtyAdjustments?: unknown
  substitute?: unknown
  notes?: string
  query_message?: string
  rejection_reason?: string
  days_supply?: number
}
```

---

## Order

```ts
type OrderCustomerType = 'registered' | 'guest'
type OrderFulfillment = 'delivery' | 'pickup'
/** Suggested shared status pipeline (align with Ecom) */
type OrderStatus =
  | 'draft'
  | 'requested'
  | 'pending'           // demo alias
  | 'pending_approval'
  | 'confirmed'
  | 'picking'
  | 'out_for_delivery'
  | 'ready_for_pickup'
  | 'completed'
  | 'cancelled'

interface OrderLine {
  sku: string
  name: string
  qty: number
  unitEtb: number
}

interface Order {
  id: string
  customerName: string
  customerType?: OrderCustomerType
  customerId?: string
  customerPhone?: string
  notes?: string
  branchId: string
  fulfillment: OrderFulfillment
  status: string            // OrderStatus in production
  totalEtb: number          // demo major ETB; prefer Money later
  channel: string           // web | telegram | mobile | b2b | pos | doctor | …
  assignedRiderId?: string
  zone?: string
  address?: string
  createdAt: string
  paid: boolean
  rxApproved?: boolean
  doctorId?: string
  orgId?: string
  lines?: OrderLine[]
}
```

| Rule | Notes |
| --- | --- |
| Guest | Requires `customerPhone`; no `customerId`; loyalty gated |
| Registered | Prefer `customerId` + shared platform identity |
| Doctor-authored | Set `doctorId` + hospital `orgId` |

---

## MedicationItem & ItemUom

Catalogue master (`/admin/catalog/items`, UI `/items`). Retail reads as `/catalog/products`.

```ts
interface ItemUom {
  uom: string
  conversionFactor: number  // how many base/stock units = 1 of this UOM
  isStockUom?: boolean
  isPurchaseUom?: boolean
  isSalesUom?: boolean
}

interface ActiveIngredient {
  name: string
  strength: string
}

interface MedicationItem {
  id: string
  sku: string
  genericName: string
  brandName: string
  manufacturer: string
  countryOfOrigin: string
  efdaRegistrationNumber: string
  barcodes: { value: string; label?: string }[]

  productType: string
  therapeuticClass: string
  ingredients: ActiveIngredient[]
  dosageForm: string
  routeOfAdministration?: string
  controlledSchedule?: string

  packSize: string
  baseUnit: string
  sellByUnit: string
  packUnit: string
  uoms: ItemUom[]
  parentItemId?: string

  costPriceEtb: number
  sellingPriceEtb: number
  currency: 'ETB'
  sellingPriceOwner: 'platform' | 'erp' | string
  vatApplicable: boolean
  discountEligible: boolean
  b2bPriceListId?: string

  prescriptionRequired: boolean
  efdaStatus: string
  controlledSubstance: boolean
  advertisingRestricted: boolean
  ageRestriction: string

  shortDescription: string
  dosageGuidance: string
  sideEffects: string
  sideEffectsMild?: string[]
  sideEffectsSevere?: string[]
  warnings: string
  storageInstructions: string
  storageNotes?: { title: string; body: string }[]
  directions?: { title: string; body: string }[]
  pharmacistTip?: string
  useCase?: string
  storefrontUnit?: string
  compareAtPriceEtb?: number
  alternativeItemIds: string[]

  defaultReorderPoint: number
  defaultExpiryAlertDays: number

  images: string[]
  thumbnailUrl?: string
  badges: string[]
  seoSlug: string
  metaTitle: string
  metaDescription: string

  ownership: Record<string, string>  // FieldGroupOwnership
  lastErpSyncAt?: string
  erpSyncError?: string | null

  b2bEligible: boolean
  loyaltyEligible: boolean

  createdBy: string
  createdAt: string
  updatedBy: string
  updatedAt: string
  status: 'active' | 'draft' | 'archived'
}
```

Stock qty is always in `baseUnit`. Use `toStockQty` / `fromStockQty` for sales/purchase UOM conversions.

---

## StockRow

```ts
interface StockRow {
  sku: string
  name: string
  category: string
  branchId: string
  qty: number              // baseUnit
  batch: string
  expiry: string           // YYYY-MM
  erpQty: number
  unitEtb: number
  itemId?: string          // → MedicationItem.id
  reserved?: number
}
```

---

## Customer

```ts
interface Customer {
  id: string               // platform customer_id
  name: string
  phone: string
  tier: string
  points: number
  branch: string
  joinedAt: string
  orders: number
  spendEtb: number
  lastOrderAt: string | null
  avatarUrl?: string
}
```

Same `id` links B2B `member.customer_id` and retail sessions when enrolled.

---

## Settlement

```ts
interface Settlement {
  id: string
  channel: string          // Chapa | Telebirr | COD | M-Pesa | …
  date: string             // YYYY-MM-DD
  volumeEtb: number
  status: 'reconciled' | 'pending' | 'matched' | 'unmatched' | 'refunded' | string
  txnCount: number
  feesEtb: number
}
```

---

## Rider & RiderTrip

```ts
interface Rider {
  id: string
  name: string
  phone: string
  telegramId?: string
  branchId: string
  zone: string
  avatarUrl?: string
}

interface RiderTrip {
  id: string
  orderId: string
  customerName: string
  zone: string
  assignedAt: string
  completedAt: string | null
  status: 'delivered' | 'failed' | 'en_route' | 'returned'
  minutes: number
  onTime: boolean
  codEtb: number
}
```

Dispatch board assigns riders; Telegram bot consumes `trip.assigned` / status updates.

---

## MigrationJob

Admin **platform** import (stock, catalog, riders…) — not the same as B2B HR `MigrationJob` tenant imports.

```ts
interface MigrationJob {
  id: string
  templateId: string       // stock | catalog | hr | branches | riders | generic
  templateLabel: string
  filename: string
  rowsTotal: number
  rowsImported: number
  rowsFailed: number
  status: 'completed' | 'partial' | 'failed' | 'running'
  runBy: string
  runAt: string
  durationSec: number
  mapping: Record<string, string>
}
```

---

## Sample: Organisation (active)

```json
{
  "id": "org-1",
  "name": "Horizon Bank",
  "orgType": "corporate",
  "tin": "0001234567",
  "vatNumber": "VAT-ET-0001234567",
  "businessLicense": "BL-AA/48291/2014",
  "commercialRegistration": "CR/015842/2014",
  "status": "active",
  "commercial": {
    "credit_limit": { "amount": "500000.00", "currency": "ETB" },
    "credit_used": { "amount": "124000.00", "currency": "ETB" },
    "payment_terms_days": 30,
    "price_list_id": "pl_corporate_2026",
    "contract_start": "2026-01-01",
    "contract_end": "2026-12-31",
    "activated_at": "2026-05-02T09:40:00Z",
    "activated_by": "adm_finance"
  },
  "creditLimitEtb": 500000,
  "usedEtb": 124000,
  "billingContact": "finance@horizon.et",
  "source": "admin",
  "createdAt": "2026-05-01T00:00:00Z",
  "reviewedBy": "Yonas Finance",
  "reviewedAt": "2026-05-02T09:40:00Z"
}
```

## Sample: Prescription (under review)

```json
{
  "id": "rx-1001",
  "customerName": "Abebe Kebede",
  "branchId": "br-bole",
  "status": "under_review",
  "items": [
    {
      "name": "Amoxicillin 500mg",
      "qty": 21,
      "frequency": "TID",
      "times": ["08:00", "14:00", "20:00"]
    }
  ],
  "submittedAt": "2026-08-06T08:10:00Z",
  "prescriber": "Dr. Selam",
  "doctorId": "doc-1",
  "orgId": "org-3"
}
```

---

## Related

| Doc | Role |
| --- | --- |
| [`admin-backend-spec.md`](./admin-backend-spec.md) | Endpoints + modules using these schemas |
| [`GISHEN-MASTER-SPEC.md`](./GISHEN-MASTER-SPEC.md) | Cross-app map + schema summary |
| B2B `docs/backend/entities/` | Portal-facing entities (clinical withhold, members, packages) |
| Ecom `docs/backend.md` | Retail order/catalog contract |