public/idmagicodocs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
idmagicodocs/COMPANY_MAGICO_APP_MANAGMENT_V2.md

9.3 KiB
Raw Permalink Blame History

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

{
  "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)

{
  "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

{
  "status": "error",
  "message": "Invalid company data",
  "errors": ["company_id is required", "company_name is required"]
}

409 Conflict - Tenant już istnieje

{
  "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

{
  "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)

{
  "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

-- 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

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

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 View Git Blame Copy Permalink