# Entity: Finance

Spend aggregates, statements, credit usage, and approval flags — **no clinical line detail** for HR/Finance roles.

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

## Sub-entities

| Entity | Purpose |
|--------|---------|
| `SpendSummary` | Aggregated spend by dimension |
| `SpendLine` | Individual covered transaction (redacted for HR/Finance) |
| `Statement` | Monthly org invoice summary |
| `ApprovalFlag` | Threshold-triggered item for Finance |
| `CreditUsage` | Real-time credit vs limit |

## SpendSummary

| Field | Type | Notes |
|-------|------|-------|
| `org_id` | `string` | |
| `period_start` | `date` | |
| `period_end` | `date` | |
| `total_spend` | `Money` | |
| `by_department` | `DeptSpend[]` | |
| `by_category` | `CategorySpend[]` | |
| `by_member` | `MemberSpend[]` | Optional; paginated separately |

### DeptSpend / CategorySpend

| Field | Type |
|-------|------|
| `id` / `code` | `string` |
| `label` | `string` |
| `amount` | `Money` |
| `order_count` | `integer` |

### MemberSpend (HR/Finance view)

| Field | Type | Notes |
|-------|------|-------|
| `member_id` | `string` | |
| `full_name` | `string` | |
| `employee_id` | `string` | |
| `department_name` | `string` | |
| `amount` | `Money` | |
| `order_count` | `integer` | |
| `rx_order_count` | `integer` | Count only — no Rx detail |

## SpendLine

| Field | Type | Notes |
|-------|------|-------|
| `id` | `string` | `spd_*` |
| `org_id` | `string` | |
| `member_id` | `string` | |
| `order_id` | `string` | Ecom order ref |
| `occurred_at` | `Timestamp` | |
| `amount_total` | `Money` | |
| `amount_org_covered` | `Money` | |
| `amount_member_paid` | `Money` | Co-pay / OOP |
| `category_code` | `string` | **Not** SKU/medicine name for HR/Finance |
| `department_id` | `string` | |
| `description` | `string` | Redacted: "Chronic medication order" |
| `approval_status` | `ApprovalStatus` | |

### ApprovalStatus

```
none | flagged | approved | rejected
```

## Statement

| Field | Type | Notes |
|-------|------|-------|
| `id` | `string` | `stmt_*` |
| `org_id` | `string` | |
| `period` | `string` | e.g. `2026-02` |
| `opening_balance` | `Money` | |
| `charges` | `Money` | |
| `payments` | `Money` | |
| `closing_balance` | `Money` | |
| `credit_limit` | `Money` | Snapshot |
| `pdf_url` | `string` | Download |
| `issued_at` | `Timestamp` | |

## ApprovalFlag

| Field | Type | Notes |
|-------|------|-------|
| `id` | `string` | `appr_*` |
| `org_id` | `string` | |
| `spend_line_id` | `string` | |
| `member_id` | `string` | |
| `reason` | `FlagReason` | |
| `threshold_rule` | `string` | e.g. `single_order > 5000 ETB` |
| `amount` | `Money` | |
| `status` | `ApprovalStatus` | |
| `reviewed_by` | `string` | |
| `reviewed_at` | `Timestamp` | |
| `notes` | `string` | Finance notes |

### FlagReason

```
threshold_exceeded | unusual_category | first_time_high_value | manual_flag
```

## CreditUsage

| Field | Type |
|-------|------|
| `credit_limit` | `Money` |
| `credit_used` | `Money` |
| `credit_available` | `Money` |
| `utilization_percent` | `number` |
| `period_end` | `date` |

## Clinical withhold

For HR_ADMIN and FINANCE:

| Withheld on SpendLine | Allowed substitute |
|-----------------------|-------------------|
| Medicine names, SKUs, dosages | `category_code` + redacted `description` |
| Prescription image refs | `rx_order_count` on member aggregate |
| Prescriber / diagnosis | Never exposed |

SUPER_USER may request full order detail via Admin/Ecom cross-ref (out of B2B finance API default).

## Sample: SpendSummary

```json
{
  "org_id": "org_01HQXYZ",
  "period_start": "2026-03-01",
  "period_end": "2026-03-31",
  "total_spend": { "amount": "1245000.00", "currency": "ETB" },
  "by_department": [
    { "id": "dept_01HABC", "label": "Addis HQ", "amount": { "amount": "800000.00", "currency": "ETB" }, "order_count": 420 }
  ],
  "by_category": [
    { "code": "chronic", "label": "Chronic", "amount": { "amount": "900000.00", "currency": "ETB" }, "order_count": 310 }
  ]
}
```

## Sample: ApprovalFlag

```json
{
  "id": "appr_01H001",
  "org_id": "org_01HQXYZ",
  "spend_line_id": "spd_01H999",
  "member_id": "mbr_01HMEM001",
  "reason": "threshold_exceeded",
  "threshold_rule": "single_order > 5000 ETB",
  "amount": { "amount": "7200.00", "currency": "ETB" },
  "status": "flagged",
  "reviewed_by": null,
  "reviewed_at": null,
  "notes": null
}
```

## Related endpoints

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