# Feature: Finance

Spend analytics, credit usage, monthly statements, Excel export, and threshold approvals.

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

## Pages

| Route | Purpose |
|-------|---------|
| `/finance` | Spend dashboard — by dept/member/category, credit usage |
| `/finance/approvals` | Flagged spend queue — approve/reject |
| `/statements` | Monthly statement list + PDF download |

## Entities

- [`Finance`](../backend/entities/finance.md) — SpendSummary, SpendLine, Statement, ApprovalFlag, CreditUsage

## Endpoints

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

## Role access

| Capability | SUPER_USER | HR_ADMIN | FINANCE |
|------------|:----------:|:--------:|:-------:|
| Spend summary | ✓ | ✓ (aggregates) | ✓ |
| Spend lines | ✓ | ✗ | ✓ (redacted) |
| Excel export | ✓ | ✗ | ✓ |
| Credit usage | ✓ | ✓ read | ✓ |
| Statements | ✓ | ✗ | ✓ |
| Approvals | ✓ | ✗ | ✓ |

## Spend dimensions

| Group by | Use case |
|----------|----------|
| Department | Branch/division budget tracking |
| Category | Chronic vs OTC vs other |
| Member | Individual spend (metadata + amounts) |

Date range filter default: current calendar month.

## Approval workflow

Threshold rules (configured by Admin or org policy) flag spend lines:

| Reason | Example |
|--------|---------|
| `threshold_exceeded` | Single order > 5,000 ETB |
| `unusual_category` | High cosmetics spend |
| `first_time_high_value` | New member large order |

Finance reviews on `/finance/approvals` → approve or reject with notes.

## Statements

Monthly PDF statements from billing engine:

- Opening/closing balance
- Charges and payments
- Credit limit snapshot
- Issued date

## Credit usage widget

Shown on `/finance` and optionally `/organisation`:

```
Credit used: 1,245,000 / 5,000,000 ETB (24.9%)
```

Warning styling (accent `#e28a1a`) above 80% utilization.

## Clinical withhold

**Critical:** Finance views never show:

- Prescription images
- Medicine names, SKUs, dosages
- Prescriber or diagnosis data

Spend lines use:

- `category_code` (e.g. `chronic`)
- Redacted `description` (e.g. "Chronic medication order")
- Amounts: total, org-covered, member-paid

HR_ADMIN sees **summary aggregates only** — not line detail or approvals.

## Validation / errors

| Scenario | Code |
|----------|------|
| Org pending (no commercial) | `ORG_PENDING` |
| HR accessing spend lines | `FORBIDDEN` |
| HR mutating approval | `FORBIDDEN` |

## UI components

- Spend charts (by dept/category) — shadcn cards
- DataTable for spend lines and approvals
- Date range picker
- Export button → XLSX download
- Statement list with PDF link

## Coordination

- Statements generated by Admin/billing — [`gishen-admin.md`](../coordination/gishen-admin.md)
- Order events from Ecom feed spend — [`gishen-ecom.md`](../coordination/gishen-ecom.md)

## Related

- [org-departments.md](org-departments.md) — department sub-limits
- [packages.md](packages.md) — category coverage drives org-covered amounts