281 lines
7.1 KiB
Markdown
281 lines
7.1 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 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
|
||
|