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>
72 lines
2.2 KiB
Markdown
72 lines
2.2 KiB
Markdown
# Entity: Department
|
|
|
|
Organisational unit or site within an org, optionally with spend sub-limits for finance reporting and package routing.
|
|
|
|
**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`
|
|
|
|
## Fields
|
|
|
|
| Field | Type | Required | Notes |
|
|
|-------|------|----------|-------|
|
|
| `id` | `string` | ✓ | `dept_*` |
|
|
| `org_id` | `string` | ✓ | Tenant scope |
|
|
| `name` | `string` | ✓ | e.g. "Addis HQ", "Hawassa Branch" |
|
|
| `code` | `string` | | Short code for imports |
|
|
| `parent_id` | `string` \| null | | Site hierarchy |
|
|
| `sub_limit` | `Money` \| null | | Optional monthly cap for department |
|
|
| `sub_limit_used` | `Money` | | Read-only; current period |
|
|
| `member_count` | `integer` | | Denormalized count |
|
|
| `is_active` | `boolean` | ✓ | Default true |
|
|
| `created_at` | `Timestamp` | ✓ | |
|
|
| `updated_at` | `Timestamp` | ✓ | |
|
|
| `version` | `integer` | ✓ | |
|
|
|
|
## Validation rules
|
|
|
|
| Rule | Error code |
|
|
|------|------------|
|
|
| `name` unique per org (case-insensitive) | `DUPLICATE_DEPARTMENT` |
|
|
| `code` unique per org if provided | `DUPLICATE_DEPARTMENT` |
|
|
| `parent_id` must belong to same org | `VALIDATION_FAILED` |
|
|
| No circular parent chain | `VALIDATION_FAILED` |
|
|
| `sub_limit.amount` ≥ 0 | `VALIDATION_FAILED` |
|
|
| Cannot delete dept with active members | `DEPARTMENT_IN_USE` |
|
|
|
|
## Clinical withhold
|
|
|
|
Departments have no clinical fields. Finance may see spend **aggregated by department** without medicine detail.
|
|
|
|
## Sample payload
|
|
|
|
```json
|
|
{
|
|
"id": "dept_01HABC123",
|
|
"org_id": "org_01HQXYZ",
|
|
"name": "Addis HQ — Finance Division",
|
|
"code": "ADD-FIN",
|
|
"parent_id": "dept_01HROOT",
|
|
"sub_limit": { "amount": "250000.00", "currency": "ETB" },
|
|
"sub_limit_used": { "amount": "87250.00", "currency": "ETB" },
|
|
"member_count": 42,
|
|
"is_active": true,
|
|
"created_at": "2026-01-10T08:00:00Z",
|
|
"updated_at": "2026-02-15T11:00:00Z",
|
|
"version": 3
|
|
}
|
|
```
|
|
|
|
## Migration mapping
|
|
|
|
Canonical import columns:
|
|
|
|
| Column | Field |
|
|
|--------|-------|
|
|
| `department_name` | `name` |
|
|
| `department_code` | `code` |
|
|
| `parent_code` | resolve → `parent_id` |
|
|
| `sub_limit_etb` | `sub_limit.amount` |
|
|
|
|
## Related endpoints
|
|
|
|
- [`../endpoints/org.md`](../endpoints/org.md) — department CRUD
|