# MOWI OTM – wysyłka statusów transportu

Ta strona jest dla programistów backendu i testerów. Opisuje, kiedy Apollo wysyła mapę transportu do MOWI OTM (`POST /status2otm`), co jest wysyłane i gdzie szukać śladów wysyłki. Autoryzację OAuth 2.0 i konfigurację klienta opisuje [Klient OAuth 2.0 Client Credentials](<https://docs.logintegra.com/apollo-backend/oauth2-client-credentials/index.md>).

## Kiedy wysyłamy komunikat

Komunikat jest wysyłany po potwierdzeniu i po wycofaniu statusu, gdy spełnione są wszystkie warunki:

1. Integracja jest włączona: `mowi.otm.oauth.enabled = true`.
2. Transport należy do pryncypała MOWI (alias firmy `mowi`, `Company.MOWI_ALIAS`).
3. Task statusu ma włączoną flagę „Wysyłanie komunikatu API” (`Task.sendApiMessage`).

Sprawdzenie pryncypała (`MowiOtmStatusService#isMowi`) jest tymczasowe. Docelowo integracja powinna być konfigurowana per pryncypał.

| Zdarzenie | Co wysyłamy | Kolejność |
| --- | --- | --- |
| potwierdzenie statusu | osobny komunikat dla każdego potwierdzonego statusu z flagą, także dla statusów potwierdzonych automatycznie w tej samej operacji | rosnący `idx` |
| wycofanie statusu | osobny komunikat dla każdego wycofanego statusu z flagą (wycofanie cofa też wszystkie późniejsze statusy) | malejący `idx` |

Źródło potwierdzenia nie ma znaczenia: UI, Public API, automat, SMS, infokiosk itd. Wszystkie ścieżki przechodzą przez `WorkflowService`.

Na transportach MOWI flaga uruchamia wyłącznie wysyłkę do MOWI OTM. Standardowa wysyłka na adres z ustawienia `API_MESSAGE_URL` jest dla nich pomijana, niezależnie od `mowi.otm.oauth.enabled`.

Na transportach innych pryncypałów flaga działa jak dotąd: po potwierdzeniu wysyła komunikat na `API_MESSAGE_URL`. Wycofanie statusu nigdy nie wysyła komunikatu na `API_MESSAGE_URL`.

## Co wysyłamy

Body to pełna mapa transportu w formacie Public API v1 (`PublicApiDTO`, `PublicApiMapper`). Ma ten sam kształt co odpowiedź `GET /api/transports/{id}` z nagłówkiem `APIVersion: v1` i co komunikaty wysyłane na `API_MESSAGE_URL`. Daty są tekstem w UTC. Mapa jest budowana z bazy (z pominięciem cache) w stanie po potwierdzeniu albo po wycofaniu statusu.

Body nie zawiera osobnego pola ze statusem. MOWI odczytuje stan z listy `checkpoints`: potwierdzony status ma uzupełnione `executionDate`, wycofany ma je puste.

## Przepływ

```
sequenceDiagram
    participant W as WorkflowService
    participant L as CheckpointConfirmationListenerService
    participant M as MowiOtmStatusService
    participant O as MOWI OTM
    W->>W: confirm / revoke, commit transakcji
    W-->>L: CheckpointConfirmedEvent / CheckpointsRevokedEvent (po commicie)
    L->>M: sendAfterConfirmation(ids) / sendAfterRevoke(snapshots)
    M->>M: filtr: enabled, MOWI, sendApiMessage
    loop każdy status
        M->>O: POST /status2otm (Bearer)
        O-->>M: odpowiedź
        M->>M: log aplikacji + PublicApiLog
    end
```

| Klasa | Zadanie |
| --- | --- |
| `WorkflowService` | publikuje `CheckpointConfirmedEvent` z listą wszystkich statusów potwierdzonych w operacji oraz `CheckpointsRevokedEvent` po wycofaniu |
| `CheckpointConfirmationListenerService` | odbiera oba eventy; dla transportów MOWI pomija wysyłkę na `API_MESSAGE_URL`, dla pozostałych działa ona jak dotąd |
| `MowiOtmStatusService` | filtruje statusy, buduje body, wysyła, loguje i zapisuje wpis w „Integracji” |
| `MowiOtmClientService` | klient HTTP z autoryzacją OAuth 2.0 |

Eventy są dostarczane asynchronicznie, po commicie transakcji potwierdzenia lub wycofania. Wysyłka nie wydłuża więc odpowiedzi dla użytkownika i widzi zapisany stan transportu.

Event wycofania niesie migawki (`RevokedCheckpointSnapshot`), a nie encje. Wycofanie może usunąć i odtworzyć statusy (`recalculateCheckpointsIfTransactionDependent`), więc identyfikatory checkpointów mogłyby już nie istnieć.

## Obsługa błędów

Błąd wysyłki nie cofa i nie blokuje potwierdzenia ani wycofania statusu. Nie ma ponawiania: każda próba kończy się jednym wpisem w logach i w „Integracji”.

| Sytuacja | `responseCode` w „Integracji” |
| --- | --- |
| sukces | kod HTTP, np. `200 OK` |
| MOWI odpowiedziało błędem | kod HTTP, np. `500 INTERNAL_SERVER_ERROR` |
| nie udało się pobrać tokenu | `OAUTH_TOKEN_ERROR:<reason>`, np. `OAUTH_TOKEN_ERROR:INVALID_CREDENTIALS` |
| timeout lub brak połączenia | `MOWI_UNREACHABLE` |
| brak `mowi.otm.baseUrl` | `NOT_CONFIGURED` |
| inny błąd | `UNKNOWN_ERROR` |

## Gdzie szukać śladów wysyłki

**Sekcja „Integracja” transportu** (`PublicApiLog`):

| Pole | Wartość |
| --- | --- |
| `event` | `MOWI_OTM_STATUS_CONFIRMED` albo `MOWI_OTM_STATUS_REVOKED` |
| `url` | pełny adres `/status2otm` |
| `httpMethod` | `POST` |
| `request` | wysłane body |
| `responseCode` | wynik, patrz tabela wyżej |
| `actor` | potwierdzający albo wycofujący użytkownik |
| `canBeResend` | `false`, ponowna wysyłka z „Integracji” nie jest obsługiwana |

**Logi aplikacji** mają prefiks `MOWI OTM`:

```
MOWI OTM | transport 123 | status ARRIVAL_UPPER_BARRIER | MOWI_OTM_STATUS_CONFIRMED | SUCCESS | 200 OK | 87 ms | response: ...
MOWI OTM | transport 123 | status ARRIVAL_UPPER_BARRIER | MOWI_OTM_STATUS_REVOKED | FAILURE | 500 INTERNAL_SERVER_ERROR | 120 ms | details: ...
```

Treść odpowiedzi MOWI i alias statusu są tylko w logach aplikacji. Logi nie zawierają tokenu ani sekretu klienta.

## Testowanie lokalnie

1. Uruchom stack Dockera z mockiem `mowi-otm-mock` (WireMock) i ustaw `MOWI_OTM_OAUTH_ENABLED=true` (klucze w `application-docker.yml`).
2. W workflow transportu MOWI włącz flagę „Wysyłanie komunikatu API” na wybranym tasku.
3. Potwierdź status w UI albo przez Public API: `PUT /api/transports/{identifier}/confirm/{taskAlias}`.
4. Sprawdź żądanie w WireMocku, wpis w „Integracji” (`GET /api/transports/{id}/getIntegrationLogs`) i logi: `docker logs -f apollo_backend | grep "MOWI OTM"`.
5. Wycofaj status i powtórz sprawdzenie.

Testy jednostkowe: `MowiOtmStatusServiceSpec`, `MowiOtmStatusServiceRequestBodySpec` i `CheckpointConfirmationListenerServiceSpec`.

## Ograniczenia

| Ograniczenie | Skutek |
| --- | --- |
| łączenie transportów (`TransportRelationService`) nie publikuje eventu potwierdzenia | statusy potwierdzone przy łączeniu nie są wysyłane |
| automatyczne potwierdzenie przy edycji transportu | wysyłany jest tylko status potwierdzony wprost, bez wcześniejszych potwierdzonych razem z nim |
| brak ponawiania | po błędzie trzeba ponownie potwierdzić status albo wycofać go i potwierdzić |
| pryncypał rozpoznawany po aliasie | tymczasowe, do zastąpienia konfiguracją per pryncypał |
