# 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 dwóch głównych kroków:

1. **Aktywacja aplikacji** – użytkownik/admin włącza TravelManager w panelu Magico
2. **Tworzenie tenanta** – automatyczne utworzenie środowiska dla firmy w TravelManager
3. **Synchronizacja użytkowników** – pobranie listy użytkowników firmy z Magico do TravelManager

---

## 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 wykonuje automatycznie **POST** do TravelManager API w celu utworzenia nowego tenanta.

---

## Krok 2: Tworzenie tenanta w TravelManager

### Endpoint tworzenia tenanta

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

System Magico automatycznie wywołuje ten endpoint po aktywacji aplikacji.

### Nagłówki

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

### Body żądania (minimalne/przykładowe)

```json
{
  "company_name": "Nazwa Firmy Sp. z o.o.",
  "company_id": 34
}
```

| Parametr      | Typ    | Opis                                    |
|---------------|--------|-----------------------------------------|
| `company_name`| string | Pełna nazwa firmy z systemu Magico      |
| `company_id`  | int    | Unikalny identyfikator firmy w Magico   |

### Odpowiedź sukces (201)

```json
{
  "status": "success",
  "message": "Tenant created successfully",
  "tenant_id": "tenant_34_travelmanager",
  "company_id": 34,
  "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 użytkowników z Magico

Po utworzeniu tenanta, TravelManager automatycznie pobiera listę użytkowników firmy z systemu Magico.

### Endpoint pobierania użytkowników

**GET** `company.magico.pro/api/company/{company_id}/users`

TravelManager wykonuje to zapytanie używając tokena systemowego.

### Nagłówki

```
Authorization: Bearer {travelmanager_system_token}
Accept: application/json
```

### Parametry URL

| Parametr    | Typ | Opis                                      |
|-------------|-----|-------------------------------------------|
| `company_id`| int | ID firmy (np. 34) z kroku tworzenia tenanta |

### Przykładowe zapytanie

```
GET https://company.magico.pro/api/company/34/users
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
Accept: application/json
```

### Odpowiedź Magico API (200)

```json
{
  "status": "success",
  "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
    }
  ],
  "total_users": 2
}
```

### Struktura użytkownika

| 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                |

---

## Krok 4: Tworzenie powiązań użytkowników w TravelManager

### Proces powiązywania

Po otrzymaniu listy użytkowników z Magico, TravelManager:

1. **Tworzy rekordy użytkowników** w swoim tenantcie
2. **Zapisuje mapowanie** między `global_user_id` (Magico) a lokalnym ID w TravelManager
3. **Umożliwia powiązanie** użytkowników między systemem Magico a TravelManager

### 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 T as TravelManager
    participant C as Company.Magico.pro

    U->>M: Kliknięcie "Aktywuj TravelManager"
    M->>T: POST /api/tenant (company_name, company_id)
    T->>T: Tworzenie tenanta w bazie
    T->>M: 201 Tenant created
    T->>C: GET /api/company/{id}/users
    C->>T: Lista użytkowników firmy
    T->>T: Tworzenie powiązań użytkowników
    M->>U: Aplikacja aktywowana pomyślnie
```

---

## Bezpieczeństwo i tokeny

### Tokeny systemowe

- **Magico System Token** - używany do tworzenia tenantów w TravelManager
- **TravelManager System Token** - używany do pobierania użytkowników z Magico

### Konfiguracja tokenów

Tokeny muszą być skonfigurowane w:
- **Magico** - endpoint TravelManager dla tworzenia tenantów
- **TravelManager** - endpoint Magico dla pobierania użytkowników
- **Company.Magico.pro** - autoryzacja zapytań od TravelManager

---

## Obsługa błędów

### Scenariusze błędów

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

2. **Błąd pobierania użytkowników**
   - Tenant zostaje utworzony, ale bez użytkowników
   - Możliwość ponownej synchronizacji

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

### Retry i ponowne próby

- **Retry logic** dla zapytań HTTP
- **Timeout** dla długotrwałych operacji  
- **Kolejka zadań** dla operacji asynchronicznych

---


### Logi systemowe

Każda operacja powinna być logowana:
- Aktywacja aplikacji przez użytkownika
- Tworzenie tenanta
- Pobieranie użytkowników
- Błędy i wyjątki