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
|
||||
|
||||
Reference in New Issue
Block a user