344 lines
9.3 KiB
Markdown
344 lines
9.3 KiB
Markdown
# 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
|
||
|