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>
116 lines
3.0 KiB
Markdown
116 lines
3.0 KiB
Markdown
# 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
|