# Zarządzanie aplikacją TravelManager w ekosystemie Magico

Dokumentacja procesu aktywacji i zarządzania aplikacją TravelManager dla firm w systemie Magico.

---

## Przegląd

Proces aktywacji TravelManager dla firmy składa się z następujących kroków:

1. **Aktywacja aplikacji** – użytkownik/admin włącza TravelManager w panelu Magico
2. **Tworzenie tenanta z użytkownikami** – automatyczne utworzenie środowiska dla firmy w TravelManager wraz z przesłaniem listy użytkowników
3. **Synchronizacja zmian** – automatyczne aktualizowanie listy użytkowników przy każdej zmianie w systemie Magico

---

## Krok 1: Aktywacja aplikacji TravelManager

### Scenariusze aktywacji

**Scenariusz A:** Użytkownik w sklepie aplikacji (magico.pro)
- Użytkownik przegląda sklep aplikacji w magico.pro
- Kliknięcie "Aktywuj" przy aplikacji TravelManager

**Scenariusz B:** Administrator w panelu zarządzania Magico
- Administrator loguje się do panelu zarządzania całym systemem Magico
- Włączenie aplikacji TravelManager dla konkretnej firmy

### Rezultat aktywacji

Po kliknięciu aktywacji system Magico:
1. Pobiera listę użytkowników firmy z bazy danych
2. Wykonuje automatycznie **POST** do TravelManager API z pełnymi danymi tenanta i użytkowników

---

## Krok 2: Tworzenie tenanta z użytkownikami w TravelManager

### Endpoint tworzenia tenanta z użytkownikami

**POST** `manager.travelmanager.pl/api/tenant`

System Magico automatycznie wywołuje ten endpoint po aktywacji aplikacji, przesyłając od razu pełną listę użytkowników firmy.

### Nagłówki

```
Content-Type: application/json
Authorization: Bearer {magico_system_token}
```

### Body żądania

```json
{
  "company_name": "Nazwa Firmy Sp. z o.o.",
  "company_id": 34,
  "users": [
    {
      "name": "Jan Kowalski",
      "email": "jan.kowalski@firma.pl",
      "global_user_id": 123,
      "username": "jan.kowalski",
      "role": "admin",
      "active": true
    },
    {
      "name": "Anna Nowak",
      "email": "anna.nowak@firma.pl",
      "global_user_id": 124,
      "username": "anna.nowak",
      "role": "user",
      "active": true
    }
  ]
}
```

| Parametr      | Typ    | Opis                                    |
|---------------|--------|-----------------------------------------|
| `company_name`| string | Pełna nazwa firmy z systemu Magico      |
| `company_id`  | int    | Unikalny identyfikator firmy w Magico   |
| `users`       | array  | Lista wszystkich użytkowników firmy     |

### Struktura użytkownika w tablicy `users`

| Pole             | Typ     | Opis                                   |
|------------------|---------|----------------------------------------|
| `name`           | string  | Pełne imię i nazwisko użytkownika      |
| `email`          | string  | Adres email użytkownika                |
| `global_user_id` | int     | Globalny ID użytkownika w systemie Magico |
| `username`       | string  | Login użytkownika                      |
| `role`           | string  | Rola użytkownika (admin, user, etc.)   |
| `active`         | boolean | Status aktywności konta                |

### Odpowiedź sukces (201)

```json
{
  "status": "success",
  "message": "Tenant created successfully with users",
  "tenant_id": "tenant_34_travelmanager",
  "company_id": 34,
  "users_imported": 2,
  "created_at": "2026-02-17T10:30:00Z"
}
```

### Odpowiedź błąd

**400 Bad Request** - Nieprawidłowe dane
```json
{
  "status": "error",
  "message": "Invalid company data",
  "errors": ["company_id is required", "company_name is required"]
}
```

**409 Conflict** - Tenant już istnieje
```json
{
  "status": "error",
  "message": "Tenant already exists for this company",
  "existing_tenant_id": "tenant_34_travelmanager"
}
```

---

## Krok 3: Synchronizacja zmian użytkowników

Kiedy lista użytkowników w systemie Magico ulegnie zmianie (dodanie, usunięcie, edycja użytkownika), system automatycznie wysyła aktualizację do wszystkich połączonych aplikacji, w tym TravelManager.

### Endpoint aktualizacji użytkowników

**PUT** `manager.travelmanager.pl/api/tenant/{company_id}/users`

Magico.pro wywołuje ten endpoint za każdym razem gdy:
- Dodany zostanie nowy użytkownik do firmy
- Usunięty zostanie użytkownik z firmy  
- Zmienione zostaną dane użytkownika (email, rola, status aktywności)
- Zmieniony zostanie status aktywności użytkownika

### Nagłówki

```
Content-Type: application/json
Authorization: Bearer {magico_system_token}
```

### Parametry URL

| Parametr    | Typ | Opis                                      |
|-------------|-----|-------------------------------------------|
| `company_id`| int | ID firmy (np. 34) dla której aktualizujemy użytkowników |

### Body żądania

```json
{
  "company_id": 34,
  "company_name": "Nazwa Firmy Sp. z o.o.",
  "users": [
    {
      "name": "Jan Kowalski",
      "email": "jan.kowalski@firma.pl",
      "global_user_id": 123,
      "username": "jan.kowalski",
      "role": "admin",
      "active": true
    },
    {
      "name": "Anna Nowak",
      "email": "anna.nowak@firma.pl",
      "global_user_id": 124,
      "username": "anna.nowak",
      "role": "user",
      "active": true
    },
    {
      "name": "Michał Wiśniewski",
      "email": "michal.wisniewski@firma.pl",
      "global_user_id": 125,
      "username": "michal.wisniewski",
      "role": "user",
      "active": true
    }
  ],
  "total_users": 3,
  "updated_at": "2026-02-17T11:45:00Z"
}
```

### Odpowiedź TravelManager (200)

```json
{
  "status": "success",
  "message": "Users synchronized successfully",
  "company_id": 34,
  "users_updated": 3,
  "users_added": 1,
  "users_removed": 0,
  "users_modified": 2,
  "synchronized_at": "2026-02-17T11:45:15Z"
}
```

---

## Krok 4: Zarządzanie użytkownikami w TravelManager

### Proces zarządzania

TravelManager otrzymuje pełną listę użytkowników od Magico i:

1. **Podczas tworzenia tenanta:**
   - Tworzy rekordy wszystkich użytkowników w swoim tenantcie
   - Zapisuje mapowanie między `global_user_id` (Magico) a lokalnym ID w TravelManager

2. **Podczas synchronizacji zmian:**
   - Porównuje otrzymaną listę z aktualnym stanem
   - Dodaje nowych użytkowników
   - Usuwa użytkowników nieobecnych na nowej liście
   - Aktualizuje dane zmodyfikowanych użytkowników

### Przykładowa struktura w bazie TravelManager

```sql
-- Tabela tenantów
CREATE TABLE tenants (
  id VARCHAR(50) PRIMARY KEY,
  company_id INT NOT NULL,
  company_name VARCHAR(255) NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Tabela użytkowników tenanta
CREATE TABLE tenant_users (
  id INT AUTO_INCREMENT PRIMARY KEY,
  tenant_id VARCHAR(50) NOT NULL,
  global_user_id INT NOT NULL, -- ID z Magico
  local_user_id INT, -- lokalne ID w TravelManager
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) NOT NULL,
  username VARCHAR(100) NOT NULL,
  role VARCHAR(50),
  active BOOLEAN DEFAULT TRUE,
  synced_at TIMESTAMP DEFAULT NOW(),
  FOREIGN KEY (tenant_id) REFERENCES tenants(id)
);
```

---

## Pełny flow aktywacji

```mermaid
sequenceDiagram
    participant U as Użytkownik/Admin
    participant M as Magico.pro
    participant DB as Magico DB
    participant T as TravelManager

    U->>M: Kliknięcie "Aktywuj TravelManager"
    M->>DB: Pobierz listę użytkowników firmy
    DB->>M: Lista użytkowników
    M->>T: POST /api/tenant (company_name, company_id, users[])
    T->>T: Tworzenie tenanta + import użytkowników
    T->>M: 201 Tenant created with users
    M->>U: Aplikacja aktywowana pomyślnie
```

## Flow synchronizacji zmian

```mermaid
sequenceDiagram
    participant A as Admin/System
    participant M as Magico.pro
    participant DB as Magico DB
    participant T as TravelManager

    A->>M: Dodanie/edycja/usunięcie użytkownika
    M->>DB: Aktualizacja danych użytkownika
    M->>DB: Pobierz aktualną listę użytkowników firmy
    DB->>M: Aktualna lista użytkowników
    M->>T: PUT /api/tenant/{company_id}/users (users[])
    T->>T: Synchronizacja użytkowników
    T->>M: 200 Users synchronized
```

---

## Bezpieczeństwo i tokeny

### Tokeny systemowe

- **Magico System Token** - używany do tworzenia tenantów i synchronizacji użytkowników w TravelManager

### Konfiguracja tokenów

Tokeny muszą być skonfigurowane w:
- **Magico** - endpoint TravelManager dla tworzenia tenantów i synchronizacji użytkowników
- **TravelManager** - autoryzacja zapytań od systemu Magico

---

## Obsługa błędów

### Scenariusze błędów

1. **Błąd tworzenia tenanta z użytkownikami**
   - Logowanie błędu w systemie Magico
   - Informowanie użytkownika o problemie z aktywacją
   - Rollback - brak utworzenia tenanta

2. **Błąd synchronizacji użytkowników**
   - Logowanie błędu synchronizacji
   - Retry automatyczny po określonym czasie
   - Alert dla administratorów o problemach synchronizacji

3. **Problemy z tokenami**
   - Sprawdzanie ważności tokena systemowego Magico
   - Procedury odnawiania tokenów

### Retry i ponowne próby

- **Retry logic** dla zapytań synchronizacji użytkowników (maksymalnie 3 próby)
- **Timeout** dla długotrwałych operacji (30 sekund)  
- **Kolejka zadań** dla operacji synchronizacji w przypadku błędów

---


### Logi systemowe

Każda operacja powinna być logowana:
- Aktywacja aplikacji przez użytkownika
- Tworzenie tenanta z użytkownikami
- Synchronizacja zmian użytkowników (dodanie, usunięcie, modyfikacja)
- Błędy i wyjątki