init push

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

@@ -0,0 +1,146 @@
+# 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.