fm_be/docs/base-contact-roles-frontend-flow.md

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:

{
  "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:

{
  "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:

{
  "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.