Refactor code structure for improved readability and maintainability
This commit is contained in:
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
|
||||
|
||||
Reference in New Issue
Block a user