# Base Contact Roles Frontend Flow (English)

This document explains the frontend flow for contact assignment in the **Bases** module:
- `responsible_flight_rescuer_contact_ids` (multi-contact)
- `chief_physician_in_charge_contact_ids` (multi-contact)

Contact source is always based on **contact id (`users.id`)**.

## 1) Data Source for Contact Dropdowns

Get contact candidates from contacts API:
- `GET /api/v1/contacts/get-all?role=air_rescuer&limit=200`

Minimum fields for FE:
- `id` (resource id) => send this in base payload
- `attributes.first_name`, `attributes.last_name`, `attributes.short_name` (display label)
- optional: `attributes.is_active`

UI suggestion:
- Use 2 separate multi-select components:
  - Responsible Flight Rescuer
  - Chief Physician In Charge
- The same person may exist in both lists if business rules allow it.

## 2) Create Base Flow

Endpoint:
- `POST /api/v1/bases/create`

Example payload:
```json
{
  "data": {
    "type": "base",
    "attributes": {
      "base": "Lude",
      "base_category": "regular",
      "responsible_flight_rescuer_contact_ids": [
        "0196a111-1111-7abc-9def-111111111111",
        "0196a222-2222-7abc-9def-222222222222"
      ],
      "chief_physician_in_charge_contact_ids": [
        "0196a333-3333-7abc-9def-333333333333"
      ]
    }
  }
}
```

Backend behavior:
- each id must be a valid UUID and exist in `users`
- invalid UUID / missing user id => request fails (`4xx`)

## 3) Update Base Flow

Endpoint:
- `PATCH /api/v1/bases/update/{uuid}`

Payload to update assignment only:
```json
{
  "data": {
    "type": "base_update",
    "attributes": {
      "responsible_flight_rescuer_contact_ids": [
        "0196a111-1111-7abc-9def-111111111111"
      ],
      "chief_physician_in_charge_contact_ids": []
    }
  }
}
```

Important notes:
- update uses **replace** semantics per base (not append)
- always submit the final arrays from current UI state
- send `[]` to clear all assignments for that role

## 4) Load Base Detail into Edit Form

Endpoint:
- `GET /api/v1/bases/get/{uuid}`

Response fields used by FE:
- `data.attributes.responsible_flight_rescuer_contact_ids`
- `data.attributes.chief_physician_in_charge_contact_ids`
- `data.attributes.responsible_flight_rescuers` (id + first_name + last_name)
- `data.attributes.chief_physicians_in_charge` (id + first_name + last_name)

FE flow:
1. Load base detail.
2. Load contact options for dropdown.
3. Map selected ids to option objects for selected state.
4. Use detailed arrays to show human-readable names immediately.

## 5) Show Base Roles in Contacts Module

Contacts API now includes:
- `attributes.base_roles` (array)

Item format:
```json
{
  "base_id": "0196b111-1111-7abc-9def-111111111111",
  "base_name": "Lude",
  "role_code": "responsible_flight_rescuer"
}
```

Affected endpoints:
- `GET /api/v1/contacts/get-all`
- `GET /api/v1/contacts/get-all/dt`
- `GET /api/v1/contacts/{user_id}`

Suggested label mapping in UI:
- `responsible_flight_rescuer` => `Responsible Flight Rescuer`
- `chief_physician_in_charge` => `Chief Physician In Charge`

## 6) UX Recommendations

- In contact detail page, group `base_roles` by `base_name`.
- In contact list, show compact chips, e.g.:
  - `Lude (Responsible Flight Rescuer)`
  - `Berlin (Chief Physician In Charge)`
- For large lists, show only first N chips + `+X more`.

## 7) Minimum Error Handling

- If base submit fails because UUID validation fails:
  - show general message: `Invalid contact assignment`.
- If contact id no longer exists:
  - show message: `Some contacts are no longer available, please refresh`.
- After successful create/update:
  - refresh base detail to keep assignment state synced with backend.

## 8) Compatibility Note

For backward compatibility, both ID arrays and detailed name arrays are returned:
- `responsible_flight_rescuer_contact_ids`
- `responsible_flight_rescuers`
- `chief_physician_in_charge_contact_ids`
- `chief_physicians_in_charge`

Recommended FE usage:
- Use `..._contact_ids` for submit payload.
- Use detailed arrays for display names.