kirukib
3778801ef5
Deliver role-aware shell (sidebar, breadcrumbs, quick search, tables, detail/create layouts), locale-ready pages, shared backend/feature docs, and Vercel project config so HR, finance, and members can demo against typed mocks. Co-authored-by: Cursor <cursoragent@cursor.com>
170 lines
4.4 KiB
Markdown
170 lines
4.4 KiB
Markdown
# 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)
|