# 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