# Inpatient Management - Frontend API Implementation Guide

This guide provides comprehensive documentation for implementing frontend interfaces for the Inpatient Management system endpoints.

## Base URL
All endpoints are prefixed with `/api/admin/` and require authentication.

## Authentication
All requests require a Bearer token in the Authorization header:
```
Authorization: Bearer {your-token}
```

## Common Response Structure
All endpoints return responses in this format:
```json
{
  "message": "Success/Error message",
  "status": true/false,
  "response": {} // Data payload
}
```

---

## 1. Ward Management

### 1.1 Get All Wards
**Endpoint:** `GET /api/admin/inpatient/wards`

**Response Structure:**
```json
{
  "message": "Wards retrieved successfully",
  "status": true,
  "response": [
    {
      "id": 1,
      "name": "General Ward",
      "description": "General medical ward",
      "status": 1,
      "capacity": 20,
      "status_name": "Active",
      "available_beds_count": 15,
      "occupied_beds_count": 5,
      "hospital": {
        "id": 1,
        "name": "Hospital Name"
      },
      "rooms_count": 4,
      "current_admissions_count": 5
    }
  ]
}
```

### 1.2 Create Ward
**Endpoint:** `POST /api/admin/inpatient/wards`

**Request Body:**
```json
{
  "name": "ICU Ward",
  "description": "Intensive Care Unit",
  "capacity": 10
}
```

**Validation Rules:**
- `name`: required, string, max 255 characters, unique per hospital
- `description`: optional, string, max 1000 characters
- `capacity`: required, integer, minimum 1

**Success Response:**
```json
{
  "message": "Ward created successfully",
  "status": true,
  "response": {
    "id": 2,
    "name": "ICU Ward",
    "description": "Intensive Care Unit",
    "capacity": 10,
    "status": 1,
    "status_name": "Active"
  }
}
```

### 1.3 Get Single Ward
**Endpoint:** `GET /api/admin/inpatient/wards/{id}`

**Response:** Same structure as create response with additional relationships loaded.

### 1.4 Update Ward
**Endpoint:** `PUT /api/admin/inpatient/wards/{id}`

**Request Body:**
```json
{
  "name": "Updated Ward Name",
  "description": "Updated description",
  "capacity": 25,
  "status": 1
}
```

**Validation Rules:**
- `name`: required, string, max 255 characters
- `description`: optional, string, max 1000 characters
- `capacity`: required, integer, minimum 1
- `status`: required, integer, values: 0 (inactive) or 1 (active)

### 1.5 Delete Ward
**Endpoint:** `DELETE /api/admin/inpatient/wards/{id}`

**Response:**
```json
{
  "message": "Ward deleted successfully",
  "status": true,
  "response": null
}
```

---

## 2. Room Management

### 2.1 Get All Rooms
**Endpoint:** `GET /api/admin/inpatient/rooms`

**Query Parameters:**
- `ward_id` (optional): Filter rooms by ward

**Response Structure:**
```json
{
  "message": "Rooms retrieved successfully",
  "status": true,
  "response": [
    {
      "id": 1,
      "ward_id": 1,
      "room_number": "R101",
      "room_type": "private",
      "capacity": 2,
      "status": 1,
      "status_name": "Active",
      "available_beds_count": 1,
      "occupied_beds_count": 1,
      "full_room_number": "General Ward - R101",
      "ward": {
        "id": 1,
        "name": "General Ward"
      }
    }
  ]
}
```

### 2.2 Create Room
**Endpoint:** `POST /api/admin/inpatient/rooms`

**Request Body:**
```json
{
  "ward_id": 1,
  "room_number": "R102",
  "room_type": "shared",
  "capacity": 4
}
```

**Validation Rules:**
- `ward_id`: required, integer, must exist in wards table
- `room_number`: required, string, max 50 characters, unique per ward
- `room_type`: required, string, values: private, shared, icu, emergency, isolation
- `capacity`: required, integer, min 1, max 10

### 2.3 Get Single Room
**Endpoint:** `GET /api/admin/inpatient/rooms/{id}`

### 2.4 Update Room
**Endpoint:** `PUT /api/admin/inpatient/rooms/{id}`

**Request Body:** Same as create, plus:
```json
{
  "status": 1
}
```

### 2.5 Delete Room
**Endpoint:** `DELETE /api/admin/inpatient/rooms/{id}`

---

## 3. Bed Management

### 3.1 Get All Beds
**Endpoint:** `GET /api/admin/inpatient/beds`

**Query Parameters:**
- `room_id` (optional): Filter beds by room
- `ward_id` (optional): Filter beds by ward
- `status` (optional): Filter by bed status

**Response Structure:**
```json
{
  "message": "Beds retrieved successfully",
  "status": true,
  "response": [
    {
      "id": 1,
      "room_id": 1,
      "bed_number": "B01",
      "bed_type": "standard",
      "status": "available",
      "full_bed_number": "General Ward - R101 - B01",
      "current_patient": null,
      "room": {
        "id": 1,
        "room_number": "R101",
        "ward": {
          "id": 1,
          "name": "General Ward"
        }
      }
    }
  ]
}
```

### 3.2 Create Bed
**Endpoint:** `POST /api/admin/inpatient/beds`

**Request Body:**
```json
{
  "room_id": 1,
  "bed_number": "B02",
  "bed_type": "icu"
}
```

**Validation Rules:**
- `room_id`: required, integer, must exist in rooms table
- `bed_number`: required, string, max 50 characters, unique per room
- `bed_type`: required, string, values: standard, icu, pediatric, maternity, isolation

### 3.3 Get Single Bed
**Endpoint:** `GET /api/admin/inpatient/beds/{id}`

**Response includes current admission details if occupied:**
```json
{
  "message": "Bed retrieved successfully",
  "status": true,
  "response": {
    "id": 1,
    "bed_number": "B01",
    "bed_type": "standard",
    "status": "occupied",
    "current_admission": {
      "patient": {
        "id": 1,
        "file_number": "25/001",
        "first_name": "John",
        "last_name": "Doe"
      },
      "doctor": {
        "id": 1,
        "name": "Dr. Smith"
      }
    }
  }
}
```

### 3.4 Update Bed
**Endpoint:** `PUT /api/admin/inpatient/beds/{id}`

**Request Body:**
```json
{
  "bed_number": "B01-Updated",
  "bed_type": "icu",
  "status": "maintenance"
}
```

**Validation Rules:**
- `bed_number`: required, string, max 50 characters
- `bed_type`: required, string, values: standard, icu, pediatric, maternity, isolation
- `status`: required, string, values: available, occupied, maintenance, reserved

**Note:** Cannot change status from "occupied" if there's a current patient admission.

### 3.5 Delete Bed
**Endpoint:** `DELETE /api/admin/inpatient/beds/{id}`

---

## 4. Patient Admission Management (Hospital Admin)

### 4.1 Get Current Admissions
**Endpoint:** `GET /api/admin/inpatient/current-admissions`

**Query Parameters:**
- `search` (optional): Search by patient name or file number
- `ward_id` (optional): Filter by ward
- `doctor_id` (optional): Filter by doctor

**Response Structure:**
```json
{
  "message": "Current admissions retrieved successfully",
  "status": true,
  "response": [
    {
      "id": 1,
      "patient_id": 1,
      "admission_date": "2025-01-15T10:30:00.000000Z",
      "admission_reason": "Chest pain investigation",
      "status": "admitted",
      "status_name": "Currently Admitted",
      "admission_duration": "2 days",
      "is_current_admission": true,
      "patient": {
        "id": 1,
        "file_number": "25/001",
        "first_name": "John",
        "last_name": "Doe"
      },
      "doctor": {
        "id": 1,
        "name": "Dr. Smith"
      },
      "ward": {
        "id": 1,
        "name": "General Ward"
      },
      "room": {
        "id": 1,
        "room_number": "R101"
      },
      "bed": {
        "id": 1,
        "bed_number": "B01"
      }
    }
  ]
}
```

### 4.2 Get Discharged Patients
**Endpoint:** `GET /api/admin/inpatient/discharged-patients`

**Query Parameters:**
- `search` (optional): Search by patient name or file number
- `start_date` (optional): Filter from date (YYYY-MM-DD)
- `end_date` (optional): Filter to date (YYYY-MM-DD)

**Response:** Similar structure to current admissions but with discharge information.

### 4.3 Get Admission Statistics
**Endpoint:** `GET /api/admin/inpatient/admission-stats`

**Response Structure:**
```json
{
  "message": "Admission statistics retrieved successfully",
  "status": true,
  "response": {
    "current_admissions": 15,
    "today_admissions": 3,
    "today_discharges": 2,
    "available_beds": 25,
    "total_beds": 40,
    "occupancy_rate": 62.5,
    "ward_stats": [
      {
        "ward_id": 1,
        "ward_name": "General Ward",
        "current_admissions": 8,
        "available_beds": 12,
        "total_beds": 20
      }
    ]
  }
}
```

### 4.4 Get Available Beds
**Endpoint:** `GET /api/admin/inpatient/available-beds`

**Query Parameters:**
- `ward_id` (optional): Filter by ward
- `bed_type` (optional): Filter by bed type

**Response Structure:**
```json
{
  "message": "Available beds retrieved successfully",
  "status": true,
  "response": [
    {
      "id": 2,
      "bed_number": "B02",
      "bed_type": "standard",
      "status": "available",
      "full_bed_number": "General Ward - R101 - B02",
      "room": {
        "id": 1,
        "room_number": "R101",
        "room_type": "private",
        "ward": {
          "id": 1,
          "name": "General Ward"
        }
      }
    }
  ]
}
```

### 4.5 Get Single Admission Details
**Endpoint:** `GET /api/admin/inpatient/admissions/{id}`

**Response Structure:**
```json
{
  "message": "Admission details retrieved successfully",
  "status": true,
  "response": {
    "id": 1,
    "admission_date": "2025-01-15T10:30:00.000000Z",
    "discharge_date": null,
    "admission_reason": "Chest pain investigation",
    "discharge_reason": null,
    "status": "admitted",
    "medical_notes": "Patient stable, monitoring required",
    "treatment_plan": "Cardiac monitoring, medication as prescribed",
    "nurse_comments": "Patient comfortable, vitals stable",
    "admission_fee_charged": true,
    "admission_fee_amount": "500.00",
    "patient": {
      "id": 1,
      "file_number": "25/001",
      "first_name": "John",
      "middle_name": "Michael",
      "last_name": "Doe",
      "phone": "+1234567890",
      "email": "john.doe@email.com"
    },
    "consultation": {
      "id": 1,
      "patient_complaint": "Chest pain",
      "doctor_diagnosis": "Suspected angina",
      "treatment": "Further investigation required"
    },
    "doctor": {
      "id": 1,
      "name": "Dr. Smith",
      "email": "dr.smith@hospital.com",
      "phone": "+1234567891"
    },
    "ward": {
      "id": 1,
      "name": "General Ward"
    },
    "room": {
      "id": 1,
      "room_number": "R101",
      "room_type": "private"
    },
    "bed": {
      "id": 1,
      "bed_number": "B01",
      "bed_type": "standard"
    }
  }
}
```

---

## 5. Doctor Endpoints for Patient Admission

### 5.1 Admit Patient
**Endpoint:** `POST /api/admin/doctor/admit-patient`

**Request Body:**
```json
{
  "patient_id": 1,
  "consultation_id": 1,
  "bed_id": 2,
  "admission_reason": "Requires overnight observation",
  "medical_notes": "Patient stable but needs monitoring",
  "treatment_plan": "IV fluids, regular vitals check",
  "admission_fee_amount": 750.00
}
```

**Validation Rules:**
- `patient_id`: required, integer, must exist in patients table
- `consultation_id`: optional, integer, must exist in consultations table
- `bed_id`: required, integer, must exist and be available
- `admission_reason`: required, string, max 1000 characters
- `medical_notes`: optional, string, max 2000 characters
- `treatment_plan`: optional, string, max 2000 characters
- `admission_fee_amount`: optional, numeric, minimum 0

### 5.2 Discharge Patient
**Endpoint:** `POST /api/admin/doctor/discharge-patient`

**Request Body:**
```json
{
  "admission_id": 1,
  "discharge_reason": "Patient recovered, stable for discharge"
}
```

**Validation Rules:**
- `admission_id`: required, integer, must exist and be current admission
- `discharge_reason`: required, string, max 1000 characters

### 5.3 Get Doctor's Admitted Patients
**Endpoint:** `GET /api/admin/doctor/admitted-patients`

**Response:** Similar structure to current admissions but filtered by doctor.

### 5.4 Get Available Beds (Doctor View)
**Endpoint:** `GET /api/admin/doctor/available-beds`

**Response:** Same as admin available beds endpoint.

---

## 6. Multi-Role Access Endpoints

### 6.1 Daily Discharge List
**Endpoint:** `GET /api/admin/discharge/daily-list`

**Query Parameters:**
- `date` (optional): Date in YYYY-MM-DD format (defaults to today)

**Access:** Nurse, Receptionist, Accountant, Doctor, Hospital Admin

**Response Structure:**
```json
{
  "message": "Daily discharge list retrieved successfully",
  "status": true,
  "response": [
    {
      "id": 1,
      "discharge_date": "2025-01-17T14:30:00.000000Z",
      "discharge_reason": "Patient recovered",
      "admission_duration": "3 days",
      "patient": {
        "id": 1,
        "file_number": "25/001",
        "first_name": "John",
        "last_name": "Doe"
      },
      "doctor": {
        "id": 1,
        "name": "Dr. Smith"
      }
    }
  ]
}
```

### 6.2 Discharge Statistics
**Endpoint:** `GET /api/admin/discharge/stats`

**Query Parameters:**
- `start_date` (optional): Start date (defaults to 7 days ago)
- `end_date` (optional): End date (defaults to today)

**Response Structure:**
```json
{
  "message": "Discharge statistics retrieved successfully",
  "status": true,
  "response": {
    "total_discharges": 25,
    "average_stay_duration": 3.2,
    "daily_breakdown": [
      {
        "date": "2025-01-17",
        "discharges": 4,
        "average_duration": 2.8
      }
    ]
  }
}
```

### 6.3 Current Admissions Overview
**Endpoint:** `GET /api/admin/discharge/current-admissions-overview`

**Response:** Simplified view of current admissions for multi-role access.

---

## Error Handling

### Common Error Responses

**Validation Error (422):**
```json
{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "capacity": ["The capacity must be at least 1."]
  }
}
```

**Not Found (404):**
```json
{
  "message": "Ward not found or access denied",
  "status": false,
  "response": null
}
```

**Access Denied (403):**
```json
{
  "message": "Access denied. Insufficient permissions",
  "status": false,
  "response": null
}
```

**Server Error (500):**
```json
{
  "message": "An error occurred while processing your request",
  "status": false,
  "response": null
}
```

---

## Frontend Implementation Tips

### 1. State Management
- Use loading states for all API calls
- Implement proper error handling and user feedback
- Cache frequently accessed data (wards, rooms, bed types)

### 2. Real-time Updates
- Consider implementing WebSocket connections for real-time bed availability
- Refresh admission lists periodically
- Show notifications for new admissions/discharges

### 3. Form Validation
- Implement client-side validation matching server rules
- Provide clear error messages
- Use proper input types and constraints

### 4. User Experience
- Implement search and filtering capabilities
- Use pagination for large datasets
- Provide bulk operations where appropriate
- Show confirmation dialogs for destructive actions

### 5. Data Visualization
- Create dashboards for admission statistics
- Use charts for occupancy rates and trends
- Implement bed availability heat maps

---

## Security Considerations

1. **Authentication**: All endpoints require valid authentication tokens
2. **Authorization**: Role-based access control is enforced
3. **Hospital Isolation**: Users can only access data from their hospital
4. **Input Validation**: All inputs are validated server-side
5. **Rate Limiting**: Implement appropriate rate limiting on the frontend

---

## Testing Recommendations

1. **Unit Tests**: Test individual API calls and response handling
2. **Integration Tests**: Test complete user workflows
3. **Error Scenarios**: Test all error conditions and edge cases
4. **Performance Tests**: Test with large datasets
5. **Security Tests**: Verify authentication and authorization

This guide provides a comprehensive foundation for implementing the inpatient management frontend. Refer to the actual API responses during development as they may contain additional fields or slight variations.