Refactor code structure for improved readability and maintainability
This commit is contained in:
281
COMPANY_MAGICO_APP_MANAGMENT.md
Normal file
281
COMPANY_MAGICO_APP_MANAGMENT.md
Normal file
@@ -0,0 +1,281 @@
|
|||||||
|
# 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
|
||||||
|
|
||||||
345
COMPANY_MAGICO_APP_MANAGMENT_V2.md
Normal file
345
COMPANY_MAGICO_APP_MANAGMENT_V2.md
Normal file
@@ -0,0 +1,345 @@
|
|||||||
|
# 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
|
||||||
|
|
||||||
330
ID_MAGICO_AUTH_PROCCESS.md
Normal file
330
ID_MAGICO_AUTH_PROCCESS.md
Normal file
@@ -0,0 +1,330 @@
|
|||||||
|
# Logowanie i ustawianie sesji z Id Magico
|
||||||
|
|
||||||
|
Dokumentacja autentykacji przez Id Magico (https://id.magico.pro) i ustawiania sesji w API TravelManager.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Przegląd
|
||||||
|
|
||||||
|
API TravelManager korzysta z **Id Magico** jako centralnego systemu autentykacji. Pełny flow:
|
||||||
|
|
||||||
|
1. **OAuth** – przekierowanie użytkownika do Id Magico, otrzymanie `code`
|
||||||
|
2. **Token** – wymiana `code` na `access_token`
|
||||||
|
3. **Sesja** – użycie tokena w `POST v1/auth/session` do ustawienia sesji w API TravelManager
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Krok 1: Uzyskiwanie tokena (OAuth 2.0 – Authorization Code)
|
||||||
|
|
||||||
|
### 1.1. Generowanie linku autoryzacyjnego
|
||||||
|
|
||||||
|
Przekieruj użytkownika do Id Magico, aby się zalogował. Skonstruuj URL:
|
||||||
|
|
||||||
|
```
|
||||||
|
GET {id.baseURL}oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&response_type=code&scope={scope}&state={state}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Parametr | Opis |
|
||||||
|
|----------------|----------------------------------------------------------------------|
|
||||||
|
| `client_id` | ID aplikacji w Id Magico (otrzymane przy rejestracji klienta OAuth) |
|
||||||
|
| `redirect_uri` | Adres powrotu po autoryzacji – musi być zarejestrowany w Id Magico |
|
||||||
|
| `response_type`| Stała: `code` |
|
||||||
|
| `scope` | Zakres uprawnień (np. `openid`, `profile` – wg dokumentacji Id Magico) |
|
||||||
|
| `state` | Losowy ciąg do weryfikacji (zabezpieczenie CSRF) |
|
||||||
|
|
||||||
|
**Przykład:**
|
||||||
|
|
||||||
|
```
|
||||||
|
https://id.magico.pro/oauth/authorize?client_id=travelmanager&redirect_uri=https://manager.travel360.pl/auth/callback&response_type=code&scope=openid&state=abc123xyz
|
||||||
|
```
|
||||||
|
|
||||||
|
Użytkownik zaloguje się w Id Magico. Po akceptacji zostanie przekierowany z powrotem na `redirect_uri` z parametrem `code`:
|
||||||
|
|
||||||
|
```
|
||||||
|
https://manager.travel360.pl/auth/callback?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&state=abc123xyz
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.2. Wymiana code na access_token
|
||||||
|
|
||||||
|
Wyślij żądanie POST do endpointu tokenów Id Magico:
|
||||||
|
|
||||||
|
```
|
||||||
|
POST {id.baseURL}oauth/token
|
||||||
|
Content-Type: application/x-www-form-urlencoded
|
||||||
|
|
||||||
|
grant_type=authorization_code&code={code}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Parametr | Opis |
|
||||||
|
|-----------------|---------------------------------------------------------------|
|
||||||
|
| `grant_type` | Stała: `authorization_code` |
|
||||||
|
| `code` | Kod autoryzacyjny z kroku 1 (jeden raz, krótko ważny) |
|
||||||
|
| `redirect_uri` | Ten sam adres co w żądaniu autoryzacji |
|
||||||
|
| `client_id` | ID aplikacji |
|
||||||
|
| `client_secret` | Tajny klucz aplikacji (tylko po stronie serwera) |
|
||||||
|
|
||||||
|
**Przykład odpowiedzi (200):**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
|
||||||
|
"token_type": "Bearer",
|
||||||
|
"expires_in": 3600
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Krok 2: Ustawianie sesji w API TravelManager
|
||||||
|
|
||||||
|
Mając `access_token` z kroku 1, wywołaj endpoint sesji API TravelManager.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Endpoint ustawiania sesji
|
||||||
|
|
||||||
|
**POST** `v1/auth/session`
|
||||||
|
|
||||||
|
Weryfikuje token Bearer z Id Magico i ustawia sesję. W tym miejscu zwracany jest company_id (tenant_id), używany do rozróźnienia tenanta na backendzie
|
||||||
|
|
||||||
|
### Nagłówek
|
||||||
|
|
||||||
|
```
|
||||||
|
Authorization: Bearer {token_z_id_magico}
|
||||||
|
Content-Type: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
### Przykładowe żądanie
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /v1/auth/session
|
||||||
|
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
|
||||||
|
Accept: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
### Odpowiedź sukces (200)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": true,
|
||||||
|
"message": "is login"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Odpowiedź błąd (401)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": false,
|
||||||
|
"message": "401 Unauthorized"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Błąd 401 zwracany jest gdy:
|
||||||
|
- token jest nieprawidłowy lub wygasły,
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Co jest zapisywane w sesji
|
||||||
|
|
||||||
|
Po poprawnym wywołaniu `v1/auth/session` w sesji zapisywane są m.in.:
|
||||||
|
|
||||||
|
| Klucz sesji | Opis |
|
||||||
|
|---------------|--------------------------------------------------|
|
||||||
|
| `userdata` | Obiekt z danymi użytkownika (patrz niżej) |
|
||||||
|
| `user_id` | ID użytkownika z Id Magico |
|
||||||
|
|
||||||
|
### Struktura `userdata`
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"username": "jan.kowalski",
|
||||||
|
"id": 123,
|
||||||
|
"user_id": 123,
|
||||||
|
"level": "admin",
|
||||||
|
"image": "https://...",
|
||||||
|
"name": "Jan Kowalski",
|
||||||
|
"client_id": 123,
|
||||||
|
"guid": "uuid-guid",
|
||||||
|
"company_id": 123,
|
||||||
|
"token": "eyJ0eXAiOiJKV1QiLCJhbGc..."
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Pole | Opis |
|
||||||
|
|-------------|-------------------------------------------|
|
||||||
|
| `username` | Login użytkownika |
|
||||||
|
| `user_id` | ID użytkownika w Id Magico |
|
||||||
|
| `level` | Rola (np. `admin`) |
|
||||||
|
| `company_id`| ID firmy |
|
||||||
|
| `token` | Token Bearer z Id Magico |
|
||||||
|
| `guid` | Identyfikator GUID z Id Magico |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Wylogowanie
|
||||||
|
|
||||||
|
**GET** `v1/auth/logout`
|
||||||
|
**POST** `v1/auth/logout`
|
||||||
|
|
||||||
|
Niszczy sesję i usuwa dane użytkownika.
|
||||||
|
|
||||||
|
### Przykład
|
||||||
|
|
||||||
|
```
|
||||||
|
POST /v1/auth/logout
|
||||||
|
Cookie: app_session=...
|
||||||
|
```
|
||||||
|
|
||||||
|
### Odpowiedź (200)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": true,
|
||||||
|
"message": "logout"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Weryfikacja tokena w Id Magico
|
||||||
|
|
||||||
|
API TravelManager weryfikuje token przez wywołanie Id Magico:
|
||||||
|
|
||||||
|
```
|
||||||
|
GET {magico.auth.serwer}api/v1/authorize/me
|
||||||
|
Authorization: Bearer {token}
|
||||||
|
Accept: application/json
|
||||||
|
```
|
||||||
|
|
||||||
|
Zmienna środowiskowa: `magico.auth.serwer` (np. `https://id.magico.pro/`).
|
||||||
|
|
||||||
|
### Oczekiwana odpowiedź Id Magico
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"user": {
|
||||||
|
"username": "jan.kowalski",
|
||||||
|
"user_id": 123,
|
||||||
|
"image": "https://...",
|
||||||
|
"name": "Jan Kowalski"
|
||||||
|
},
|
||||||
|
"company_id": 123,
|
||||||
|
"role": "admin",
|
||||||
|
"guid": "uuid-guid"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Flow integracji (pełny przebieg)
|
||||||
|
|
||||||
|
1. **Generuj link** do Id Magico (Krok 1.1) i przekieruj użytkownika.
|
||||||
|
2. Po zalogowaniu Id Magico przekierowuje na `redirect_uri` z parametrem `code`.
|
||||||
|
3. **Wymień `code` na token** – POST do Id Magico `/oauth/token` (Krok 1.2).
|
||||||
|
4. **Ustaw sesję** – `POST v1/auth/session` z nagłówkiem `Authorization: Bearer {access_token}`.
|
||||||
|
5. API zwraca `200` i ustawia sesję (ciastko `app_session`).
|
||||||
|
6. Kolejne żądania do chronionych endpointów wysyłają ciastko sesji.
|
||||||
|
7. Przy wylogowaniu: `POST v1/auth/logout`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Diagram sekwencji procesu autentykacji
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
sequenceDiagram
|
||||||
|
participant User as Użytkownik
|
||||||
|
participant App as Aplikacja TravelManager
|
||||||
|
participant IdMagico as Id Magico
|
||||||
|
participant API as TravelManager API
|
||||||
|
|
||||||
|
Note over User, API: OAuth 2.0 Authorization Code Flow
|
||||||
|
|
||||||
|
User->>App: Chce się zalogować
|
||||||
|
App->>User: Przekierowanie do Id Magico
|
||||||
|
Note right of App: GET /oauth/authorize?<br/>client_id={client_id}&<br/>redirect_uri={redirect_uri}&<br/>response_type=code&<br/>scope={scope}&<br/>state={state}
|
||||||
|
|
||||||
|
User->>IdMagico: Logowanie użytkownika
|
||||||
|
IdMagico->>User: Formularz logowania
|
||||||
|
User->>IdMagico: Dane logowania
|
||||||
|
IdMagico->>User: Przekierowanie z kodem
|
||||||
|
Note right of IdMagico: Redirect na: {redirect_uri}?<br/>code={authorization_code}&<br/>state={state}
|
||||||
|
|
||||||
|
User->>App: Powrót z kodem autoryzacyjnym
|
||||||
|
App->>IdMagico: Wymiana code na token
|
||||||
|
Note right of App: POST /oauth/token<br/>grant_type=authorization_code<br/>code={code}<br/>client_id={client_id}<br/>client_secret={client_secret}
|
||||||
|
|
||||||
|
IdMagico->>App: access_token
|
||||||
|
Note left of IdMagico: {<br/>"access_token": "eyJ...",<br/>"token_type": "Bearer",<br/>"expires_in": 3600<br/>}
|
||||||
|
|
||||||
|
App->>API: Ustawienie sesji
|
||||||
|
Note right of App: POST /v1/auth/session<br/>Authorization: Bearer {access_token}
|
||||||
|
|
||||||
|
API->>IdMagico: Weryfikacja tokena
|
||||||
|
Note right of API: GET /api/v1/authorize/me<br/>Authorization: Bearer {access_token}
|
||||||
|
|
||||||
|
IdMagico->>API: Dane użytkownika
|
||||||
|
Note left of IdMagico: {<br/>"user": {...},<br/>"company_id": 123,<br/>"role": "admin"<br/>}
|
||||||
|
|
||||||
|
alt Użytkownik ma prawidłowy token
|
||||||
|
API->>API: Utworzenie sesji
|
||||||
|
API->>App: Sukces (200)
|
||||||
|
Note left of API: {<br/>"status": true,<br/>"message": "is login"<br/>}<br/>+ cookie app_session
|
||||||
|
App->>User: Zalogowany - dostęp do aplikacji
|
||||||
|
|
||||||
|
Note over User, API: Dalsze żądania z ciastkiem sesji
|
||||||
|
User->>App: Żądania do chronionych zasobów
|
||||||
|
App->>API: Żądania z cookie app_session
|
||||||
|
API->>App: Odpowiedzi (autoryzowane)
|
||||||
|
App->>User: Dane/funkcjonalność
|
||||||
|
|
||||||
|
Note over User, API: Wylogowanie
|
||||||
|
User->>App: Wyloguj
|
||||||
|
App->>API: POST /v1/auth/logout
|
||||||
|
API->>App: Sukces wylogowania
|
||||||
|
App->>User: Wylogowany
|
||||||
|
else Nieprawidłowy token lub brak uprawnień
|
||||||
|
API->>App: Błąd (401)
|
||||||
|
Note left of API: {<br/>"status": false,<br/>"message": "401 Unauthorized"<br/>}
|
||||||
|
App->>User: Błąd autoryzacji
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Endpointy chronione
|
||||||
|
|
||||||
|
Endpointy z filtrem `login` (np. `v1/project`, `v1/ticket`, `v1/setting`) wymagają:
|
||||||
|
- poprawnej sesji (ciastko `app_session`), lub
|
||||||
|
- wcześniejszego wywołania `POST v1/auth/session` z tokenem Bearer.
|
||||||
|
|
||||||
|
Brak sesji skutkuje odpowiedzią **401 Unauthorized**:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"status": false,
|
||||||
|
"data": [],
|
||||||
|
"message": "Nieautoryzowany dostęp"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Konfiguracja
|
||||||
|
|
||||||
|
| Zmienna | Opis |
|
||||||
|
|----------------------|-----------------------------------------------------|
|
||||||
|
| `magico.auth.serwer` | URL serwera Id Magico (np. `https://id.magico.pro/`) |
|
||||||
|
| `id.baseURL` | URL panelu Id Magico (np. `https://id.magico.pro/`) |
|
||||||
|
|
||||||
|
Dla OAuth (krok 1) potrzebujesz także `client_id` i `client_secret` aplikacji zarejestrowanej w Id Magico. `redirect_uri` musi być zgłoszony w konfiguracji klienta OAuth.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Uwagi
|
||||||
|
|
||||||
|
- Token Bearer jest przekazywany **tylko przy wywołaniu** `v1/auth/session`.
|
||||||
|
- Po ustawieniu sesji używane jest **ciastko sesji** (`app_session`), nie token w nagłówku.
|
||||||
BIN
tenant_auth.png
Normal file
BIN
tenant_auth.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 160 KiB |
BIN
tenant_create_v1.png
Normal file
BIN
tenant_create_v1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 56 KiB |
BIN
tenant_create_v2.png
Normal file
BIN
tenant_create_v2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
BIN
tenant_user_sync_v2.png
Normal file
BIN
tenant_user_sync_v2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Reference in New Issue
Block a user