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>
136 lines
3.6 KiB
Markdown
136 lines
3.6 KiB
Markdown
# Entity: Package
|
||
|
||
Corporate benefit plan defining allowance, co-pay, covered categories, perks, caps, and exclusions.
|
||
|
||
**Workspace:** `/Users/kirukib/Desktop/Yaltopia Project/Gishen-B2B`
|
||
|
||
## Fields
|
||
|
||
| Field | Type | Required | Notes |
|
||
|-------|------|----------|-------|
|
||
| `id` | `string` | ✓ | `pkg_*` |
|
||
| `org_id` | `string` | ✓ | |
|
||
| `name` | `string` | ✓ | e.g. "Gold Executive" |
|
||
| `code` | `string` | ✓ | Unique per org; used in imports |
|
||
| `description` | `string` | | HR-facing |
|
||
| `status` | `PackageStatus` | ✓ | |
|
||
| `allowance` | `PackageAllowance` | ✓ | |
|
||
| `copay_percent` | `number` | ✓ | 0–100; member pays remainder |
|
||
| `categories` | `CategoryRule[]` | ✓ | Covered product categories |
|
||
| `perks` | `Perk[]` | | Custom perks |
|
||
| `caps` | `PackageCaps` | | |
|
||
| `exclusions` | `Exclusion[]` | | SKU/category blocks |
|
||
| `member_count` | `integer` | | Assigned members |
|
||
| `created_at` | `Timestamp` | ✓ | |
|
||
| `updated_at` | `Timestamp` | ✓ | |
|
||
| `version` | `integer` | ✓ | |
|
||
|
||
### PackageStatus
|
||
|
||
```
|
||
draft | active | archived
|
||
```
|
||
|
||
Pending orgs: packages may be saved as `draft` but cannot be `active` until org activation (configurable; default: block).
|
||
|
||
### PackageAllowance
|
||
|
||
| Field | Type | Notes |
|
||
|-------|------|-------|
|
||
| `amount` | `Money` | Monthly allowance per member |
|
||
| `period` | `AllowancePeriod` | |
|
||
| `rollover` | `boolean` | Unused rolls to next period |
|
||
|
||
```
|
||
AllowancePeriod = monthly | quarterly | annual
|
||
```
|
||
|
||
### CategoryRule
|
||
|
||
| Field | Type |
|
||
|-------|------|
|
||
| `category_code` | `string` |
|
||
| `coverage_percent` | `number` | 0–100 |
|
||
| `max_per_order` | `Money` \| null |
|
||
|
||
### Perk
|
||
|
||
| Field | Type |
|
||
|-------|------|
|
||
| `code` | `string` |
|
||
| `label` | `string` |
|
||
| `description` | `string` |
|
||
|
||
Example perks: `free_delivery`, `priority_dispense`, `annual_checkup_voucher`.
|
||
|
||
### PackageCaps
|
||
|
||
| Field | Type |
|
||
|-------|------|
|
||
| `max_order_amount` | `Money` |
|
||
| `max_orders_per_month` | `integer` |
|
||
| `max_rx_fills_per_month` | `integer` |
|
||
|
||
### Exclusion
|
||
|
||
| Field | Type |
|
||
|-------|------|
|
||
| `type` | `sku` \| `category` |
|
||
| `ref` | `string` |
|
||
| `reason` | `string` |
|
||
|
||
## Validation rules
|
||
|
||
| Rule | Error code |
|
||
|------|------------|
|
||
| `code` unique per org | `DUPLICATE_PACKAGE` |
|
||
| `copay_percent` 0–100 | `VALIDATION_FAILED` |
|
||
| Cannot archive package with active members without reassignment | `PACKAGE_IN_USE` |
|
||
| At least one category rule | `VALIDATION_FAILED` |
|
||
|
||
## Clinical withhold
|
||
|
||
Packages define **coverage rules**, not patient clinical data. Safe for all roles.
|
||
|
||
## Sample payload
|
||
|
||
```json
|
||
{
|
||
"id": "pkg_01HGOLD",
|
||
"org_id": "org_01HQXYZ",
|
||
"name": "Gold Executive",
|
||
"code": "GOLD",
|
||
"description": "Full chronic + acute coverage with 10% co-pay",
|
||
"status": "active",
|
||
"allowance": {
|
||
"amount": { "amount": "15000.00", "currency": "ETB" },
|
||
"period": "monthly",
|
||
"rollover": false
|
||
},
|
||
"copay_percent": 10,
|
||
"categories": [
|
||
{ "category_code": "chronic", "coverage_percent": 100, "max_per_order": null },
|
||
{ "category_code": "otc", "coverage_percent": 80, "max_per_order": { "amount": "500.00", "currency": "ETB" } }
|
||
],
|
||
"perks": [
|
||
{ "code": "free_delivery", "label": "Free delivery", "description": "On all orders" }
|
||
],
|
||
"caps": {
|
||
"max_order_amount": { "amount": "10000.00", "currency": "ETB" },
|
||
"max_orders_per_month": 10,
|
||
"max_rx_fills_per_month": 4
|
||
},
|
||
"exclusions": [
|
||
{ "type": "category", "ref": "cosmetics", "reason": "Not covered" }
|
||
],
|
||
"member_count": 128,
|
||
"created_at": "2026-01-01T00:00:00Z",
|
||
"updated_at": "2026-02-01T00:00:00Z",
|
||
"version": 5
|
||
}
|
||
```
|
||
|
||
## Related endpoints
|
||
|
||
- [`../endpoints/packages.md`](../endpoints/packages.md)
|