# Hospital File Numbering Frontend Integration

## Purpose

This document describes how the frontend should integrate with the new Hospital Admin patient file-numbering endpoints.

The backend now supports hospital-specific patient file-number formats. Hospital Admin can configure the format, preview the next number, and patient registration will automatically generate the next valid file number using that configuration.

This document also notes the related beneficiary reference-number behavior introduced alongside this work: dependent beneficiaries now have their own unique referral numbers derived from the principal referral number, for example `REF20265E43AA-01`.

## Audience

- Hospital Admin settings frontend
- Reception and patient registration frontend
- Mobile or web flows that create patients through the same API

## Auth and Access

- Base route prefix: `/api/admin`
- Authentication: `auth:sanctum`
- Allowed roles: `HOSPITAL_ADMIN` and `SUPER_ADMIN`

## Response Envelope

All endpoints return the standard API response structure:

```json
{
  "status": true,
  "response": {},
  "message": "Query ok."
}
```

The frontend should always read payload data from `response`.

## New Endpoints

### 1. Get current hospital file-numbering configuration

- Method: `GET`
- URL: `/api/admin/hospital-settings/file-numbering`

#### Success response

```json
{
  "status": true,
  "response": {
    "settings": {
      "id": 1,
      "hospital_id": 12,
      "prefix": "RIP",
      "separator": "/",
      "number_padding": 6,
      "starting_sequence": 1,
      "include_year": true,
      "year_format": "YYYY",
      "reset_frequency": "yearly",
      "created_at": "2026-04-21T10:00:00.000000Z",
      "updated_at": "2026-04-21T10:00:00.000000Z"
    },
    "preview_file_number": "RIP/2026/000001"
  },
  "message": "Query ok."
}
```

#### Frontend usage

- Use this endpoint to prefill the Hospital Admin settings form.
- Show `preview_file_number` in the UI as the current preview.

### 2. Preview the next file number for unsaved settings

- Method: `POST`
- URL: `/api/admin/hospital-settings/file-numbering/preview`

#### Request body

```json
{
  "prefix": "RIP",
  "separator": "/",
  "number_padding": 6,
  "starting_sequence": 1,
  "include_year": true,
  "year_format": "YYYY",
  "reset_frequency": "yearly"
}
```

#### Success response

```json
{
  "status": true,
  "response": {
    "preview_file_number": "RIP/2026/000245"
  },
  "message": "Query ok."
}
```

#### Frontend usage

- Call this when any config field changes.
- Debounce the request by about `300ms` to `500ms`.
- Do not wait until save before showing preview.
- If the request fails validation, keep the last valid preview and show the returned error message.

### 3. Save hospital file-numbering configuration

- Method: `PUT`
- URL: `/api/admin/hospital-settings/file-numbering`

#### Request body

```json
{
  "prefix": "RIP",
  "separator": "/",
  "number_padding": 6,
  "starting_sequence": 1,
  "include_year": true,
  "year_format": "YYYY",
  "reset_frequency": "yearly"
}
```

#### Success response

```json
{
  "status": true,
  "response": {
    "settings": {
      "id": 1,
      "hospital_id": 12,
      "prefix": "RIP",
      "separator": "/",
      "number_padding": 6,
      "starting_sequence": 1,
      "include_year": true,
      "year_format": "YYYY",
      "reset_frequency": "yearly",
      "created_at": "2026-04-21T10:00:00.000000Z",
      "updated_at": "2026-04-21T10:15:00.000000Z"
    },
    "preview_file_number": "RIP/2026/000245"
  },
  "message": "Hospital file numbering updated successfully."
}
```

#### Frontend usage

- Save the form state with this endpoint.
- After success, update the local form state from `response.settings` rather than assuming the submitted values are final.
- Refresh the displayed preview using `response.preview_file_number`.

## Supported Configuration Fields

### `prefix`

- Type: `string | null`
- Max length: `20`
- Example: `RIP`, `LTH`, `GH`

### `separator`

- Type: `string`
- Max length: `3`
- Examples: `/`, `-`, empty string if UI allows it

### `number_padding`

- Type: `number`
- Valid range: `1` to `12`
- Controls the left-zero padding of the sequence number
- Example: `6` produces `000245`

### `starting_sequence`

- Type: `number`
- Valid range: `1+`
- Used when the hospital starts a new numbering pattern

### `include_year`

- Type: `boolean`
- If `true`, the year segment is included in the generated number

### `year_format`

- Type: `string`
- Allowed values:
  - `YY`
  - `YYYY`

### `reset_frequency`

- Type: `string`
- Allowed values:
  - `none`
  - `yearly`

## Important Validation Rules

- If `reset_frequency` is `yearly`, then `include_year` must be `true`.
- The `prefix` must not contain the selected separator.
- The backend keeps patient file numbers globally unique, even though configuration is hospital-specific.

## Recommended Hospital Admin UI

### Suggested screen title

- `Patient File Numbering`

### Suggested form fields

- `Prefix`
- `Separator`
- `Number padding`
- `Starting sequence`
- `Include year`
- `Year format`
- `Reset frequency`

### Suggested live preview area

- Label: `Next file number preview`
- Value: `RIP/2026/000245`

### Suggested helper text

- `This format will be used automatically for all new patient registrations in this hospital.`

### Suggested UX behavior

- Load current settings on page open.
- Show a loading skeleton or spinner while fetching.
- Preview updates automatically when the form changes.
- Disable `Year format` if `Include year` is turned off.
- Prevent selecting `Yearly` reset if `Include year` is off, or automatically re-enable year when `Yearly` is selected.
- Show backend validation messages inline where possible.

## Registration Form Changes

The backend no longer allows manual file-number entry during patient registration.

### Required frontend change

- Remove the editable `file_number` input from new patient registration forms.

### Recommended replacement

- Show a read-only note such as:
  - `Patient file number will be generated automatically after registration.`

### Applies to

- Standard patient registration
- Referred patient registration
- Mobile patient creation flows that call the same backend behavior
- Beneficiary-driven onboarding after a successful `/api/admin/patient/verify-beneficiary` lookup

### Backend behavior to expect

If the frontend still sends a non-empty `file_number`, the backend returns a failure message similar to:

```json
{
  "status": false,
  "response": null,
  "message": "Patient file numbers are configured per hospital and generated automatically during registration."
}
```

## Suggested Frontend Types

```ts
export type FileNumberYearFormat = 'YY' | 'YYYY';

export type FileNumberResetFrequency = 'none' | 'yearly';

export interface HospitalFileNumberSettings {
  id: number;
  hospital_id: number;
  prefix: string | null;
  separator: string;
  number_padding: number;
  starting_sequence: number;
  include_year: boolean;
  year_format: FileNumberYearFormat;
  reset_frequency: FileNumberResetFrequency;
  created_at: string;
  updated_at: string;
}

export interface FileNumberSettingsResponse {
  settings: HospitalFileNumberSettings;
  preview_file_number: string;
}

export interface FileNumberPreviewResponse {
  preview_file_number: string;
}
```

## Suggested API Client Methods

```ts
export async function getHospitalFileNumbering() {
  return api.get('/api/admin/hospital-settings/file-numbering');
}

export async function previewHospitalFileNumbering(payload: {
  prefix?: string | null;
  separator?: string;
  number_padding: number;
  starting_sequence: number;
  include_year: boolean;
  year_format: 'YY' | 'YYYY';
  reset_frequency: 'none' | 'yearly';
}) {
  return api.post('/api/admin/hospital-settings/file-numbering/preview', payload);
}

export async function updateHospitalFileNumbering(payload: {
  prefix?: string | null;
  separator?: string;
  number_padding: number;
  starting_sequence: number;
  include_year: boolean;
  year_format: 'YY' | 'YYYY';
  reset_frequency: 'none' | 'yearly';
}) {
  return api.put('/api/admin/hospital-settings/file-numbering', payload);
}
```

## Suggested Frontend Flow

### On settings page load

1. Call `GET /api/admin/hospital-settings/file-numbering`.
2. Bind the result to the form.
3. Render the returned preview.

### On field change

1. Update local form state.
2. Debounce a call to `POST /api/admin/hospital-settings/file-numbering/preview`.
3. Update the preview display from `response.preview_file_number`.

### On save

1. Call `PUT /api/admin/hospital-settings/file-numbering`.
2. Show success toast using `message`.
3. Refresh local state from `response.settings`.
4. Refresh preview from `response.preview_file_number`.

## Edge Cases To Handle

- Empty prefix should still be supported.
- Empty separator may be supported if the frontend allows it.
- Switching from `include_year = true` to `false` should disable `year_format`.
- Validation errors should not wipe current form state.
- The preview may change if another patient is registered while the admin is on the settings page. Treat preview as indicative, not guaranteed final output.
- Beneficiary-dependent referral numbers are no longer shared with the principal, so the frontend should not assume a dependent reference is the same as the parent reference.

## Related Beneficiary Change

The beneficiary verification flow now supports dependent-specific referral numbers. That means a dependent can be verified and onboarded using their own referral number while still exposing the principal relationship in the response.

For the detailed request and response contract, see [docs/beneficiary-verification-pi-update.md](/Users/kesty/www/BlouzaTech/ripple-api/docs/beneficiary-verification-pi-update.md).

## QA Checklist

- Hospital Admin can load existing settings.
- Hospital Admin can change prefix and see preview update.
- Hospital Admin can change separator and see preview update.
- Hospital Admin can change number padding and see zero padding update.
- Hospital Admin can toggle year on and off when valid.
- Hospital Admin can switch between `YY` and `YYYY`.
- Hospital Admin can save settings successfully.
- New patient registration no longer sends a manual `file_number`.
- Newly created patients receive file numbers matching the saved format.