# Resource Types (`Api/src/types/resource/`)

Type definitions for the Clinic Resources system. These types are used across the API package, Cloud Functions, and the ClinicApp frontend (via the `@blackcode_sa/metaestetics-api` package).

## File: `index.ts`

### Collection Constants

| Constant | Value | Description |
|----------|-------|-------------|
| `RESOURCES_COLLECTION` | `"resources"` | Subcollection under clinics |
| `RESOURCE_INSTANCES_SUBCOLLECTION` | `"instances"` | Subcollection under resources |
| `RESOURCE_CALENDAR_SUBCOLLECTION` | `"calendar"` | Subcollection under instances |

### Firestore Path

```
clinics/{clinicId}/resources/{resourceId}
clinics/{clinicId}/resources/{resourceId}/instances/{instanceId}
clinics/{clinicId}/resources/{resourceId}/instances/{instanceId}/calendar/{eventId}
```

### Enums

#### `ResourceCategory`
Categorizes the type of physical resource.

| Value | Description |
|-------|-------------|
| `MEDICAL_DEVICE` | Medical equipment (e.g., laser machine) |
| `ROOM` | General room (e.g., consultation room) |
| `SURGERY_SUITE` | Operating/surgery room |
| `EQUIPMENT` | General equipment |
| `OTHER` | Uncategorized |

#### `ResourceStatus`
Tracks the operational state of a resource or instance.

| Value | Description |
|-------|-------------|
| `ACTIVE` | Available for booking |
| `INACTIVE` | Soft-deleted or disabled |
| `MAINTENANCE` | Temporarily unavailable |

### Interfaces

#### `Resource`
The main resource definition owned by a clinic branch.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier |
| `clinicBranchId` | `string` | Owning clinic branch |
| `name` | `string` | Display name |
| `nameLower` | `string` | Lowercase for case-insensitive search |
| `category` | `ResourceCategory` | Type of resource |
| `description` | `string?` | Optional description |
| `quantity` | `number` | Number of physical instances |
| `status` | `ResourceStatus` | Current status |
| `linkedProcedureIds` | `string[]` | Procedures requiring this resource |
| `createdAt` | `Timestamp` | Creation timestamp |
| `updatedAt` | `Timestamp` | Last update timestamp |

#### `ResourceInstance`
A single physical unit of a resource. Each instance has its own calendar.

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier |
| `resourceId` | `string` | Parent resource ID |
| `clinicBranchId` | `string` | Owning clinic branch |
| `label` | `string` | Auto-generated: `"{Resource.name} #{index}"` |
| `index` | `number` | 1-based index |
| `status` | `ResourceStatus` | Current status |
| `createdAt` / `updatedAt` | `Timestamp` | Timestamps |

#### `ResourceCalendarEvent`
A calendar event on a resource instance. Can be a booking event (auto-created during appointment creation) or a blocking event (manually created by admin for maintenance/downtime).

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Unique identifier |
| `resourceId` | `string` | Parent resource |
| `resourceInstanceId` | `string` | Specific instance |
| `clinicBranchId` | `string` | Clinic branch |
| `eventType` | `CalendarEventType` | `RESOURCE_BOOKING` for bookings, `BLOCKING` for manual blocks |
| `appointmentId` | `string?` | Linked appointment (only for booking events) |
| `procedureId` | `string?` | Procedure requiring this resource (only for booking events) |
| `practitionerId` | `string?` | Practitioner performing procedure (only for booking events) |
| `patientId` | `string?` | Patient for the appointment (only for booking events) |
| `eventTime` | `CalendarEventTime` | Start and end times |
| `status` | `CalendarEventStatus` | `CONFIRMED` for blocking events, mirrors appointment status for bookings |
| `eventName` | `string` | Display name |
| `description` | `string?` | Optional description (primarily for blocking events) |
| `createdAt` / `updatedAt` | `Timestamp` | Timestamps |

#### `ResourceRequirement`
Lightweight reference stored on procedures.

| Field | Type | Description |
|-------|------|-------------|
| `resourceId` | `string` | ID of the required resource |
| `resourceName` | `string` | Snapshot of resource name |
| `resourceCategory` | `ResourceCategory` | Snapshot of category |

#### `ResourceBookingInfo`
Stored on the appointment after resource allocation.

| Field | Type | Description |
|-------|------|-------------|
| `resourceId` | `string` | Booked resource |
| `resourceName` | `string` | Resource name snapshot |
| `resourceInstanceId` | `string` | Allocated instance |
| `resourceInstanceLabel` | `string` | Instance label (e.g., "Room #2") |
| `calendarEventId` | `string` | Calendar event on instance |

#### `CreateResourceData` / `UpdateResourceData`
Input types for resource CRUD operations. See source for field details.

#### `CreateResourceBlockingEventParams`
Parameters for creating a blocking event on a resource instance.

| Field | Type | Description |
|-------|------|-------------|
| `clinicBranchId` | `string` | Clinic branch |
| `resourceId` | `string` | Parent resource |
| `resourceInstanceId` | `string` | Target instance |
| `eventName` | `string` | Display name (e.g., "Maintenance") |
| `eventTime` | `CalendarEventTime` | Block start and end times |
| `description` | `string?` | Optional reason for the block |

#### `UpdateResourceBlockingEventParams`
Parameters for updating an existing blocking event. Only provided fields are updated.

| Field | Type | Description |
|-------|------|-------------|
| `clinicBranchId` | `string` | Clinic branch |
| `resourceId` | `string` | Parent resource |
| `resourceInstanceId` | `string` | Target instance |
| `eventId` | `string` | ID of the event to update |
| `eventName` | `string?` | New display name |
| `eventTime` | `CalendarEventTime?` | New time range |
| `description` | `string?` | New description |

### Related Type Extensions

This system also extends existing types:

- **`Procedure`** (`types/procedure/index.ts`): Added optional `resourceRequirements?: ResourceRequirement[]`
- **`Appointment`** (`types/appointment/index.ts`): Added optional `resourceBookings?: ResourceBookingInfo[]`
- **`CalendarEventType`** (`types/calendar/index.ts`): Added `RESOURCE_BOOKING = "resource_booking"`

See [main Resource System README](../../../docs/RESOURCE_SYSTEM.md) for the full system overview.
