# Projekt weight-gateway

Zadanie: [A-19606 Aplikacja weight-gateway dla wagi Drogbruk Piła](<https://youtrack.logintegra.com/issue/A-19606/Aplikacja-weight-gateway-dla-wagi-Drogbruk-Pila>)

## Cel

Serwis, który nasłuchuje na połączenia TCP (port 14002) i serwuje ostatnio odczytany rekord dla Apollo jako odpowiedź na żądanie HTTP. Dodatkowy panel administracyjny jako narzędzie dla testerów i supportu, razem z mockiem wagi.

![](<https://docs.logintegra.com/weight-gateway/IMG_2448.jpeg>)

![](<https://docs.logintegra.com/weight-gateway/IMG_2449.jpeg>)

**Główne założenia odbioru rekordu:**

- Rozdziela rekordy (odczyt wagi) na podstawie CRLF.
- Tylko liczba całkowita od 1 do 6 znaków (0–999999), bez znaku.
- Ostatni rekord jest przechowywany w pamięci także po rozłączeniu wagi. Jest serwowany tylko dopóki jest świeży (domyślnie 5 s), potem serwis zwraca błąd `STALE`.

## A. Aplikacja dla wagi

### 1\. Repozytorium z multi-projektem Gradle (S)

Repozytorium `weight-gateway` to multi-projekt Gradle ([dokumentacja](<https://docs.gradle.org/current/userguide/multi_project_builds_intermediate.html>)). Moduły (`settings.gradle`):

| Moduł | Rodzaj | Rola |
| --- | --- | --- |
| `weight-protocol` | biblioteka Java | model rekordu, parser pakietów, klasyfikator |
| `tcp-service` | aplikacja Grails | nasłuch TCP od MOXA + endpoint HTTP dla Apollo |
| `admin` | aplikacja Grails | panel administracyjny, w tym strona symulatora wagi |
| `mock` | biblioteka Java + CLI | symulator wagi (klient TCP) |

### 2\. Czas uruchomienia aplikacji

TODO. Nie mamy jeszcze pomiaru. Do zmierzenia: czas od startu procesu do otwarcia portu TCP i do pierwszej poprawnej odpowiedzi `GET /weight`.

## B. Protokół wagi (`weight-protocol`)

Zwykła Java, bez zależności od frameworka.

**`Record`** (`record Record(RecordClass type, Integer value, byte[] raw)`)

- `type` to klasa rekordu, `value` to waga (tylko dla `OK`, w pozostałych przypadkach `null`).
- `raw` to dokładne bajty przesłane przez sterownik dla danego rekordu, **razem z końcowym CRLF**.
- Dla rekordu, który przekroczył limit długości, `raw` to dokładnie `max` pierwszych bajtów.
- `toString()` wypisuje `raw` jako hex oraz `humanRaw` jako tekst w UTF-8 Przykład: `Record[type=OK, value=42, raw=[34 32 0D 0A] humanRaw="42\r\n"]`.

**`RecordParser`**

- `new RecordParser(maxRecordBytes)`, potem `parse(buf, off, len, consumer)`. Konsument dostaje każdy ukończony rekord.
- Rekord kończy się sekwencją `CR LF`. Rekord może być rozcięty między porcjami TCP, parser trzyma stan między wywołaniami.
- Gdy linia osiąga `maxRecordBytes`, parser emituje rekord `NON_DIGIT` (`raw` = pierwsze `max` bajtów). Potem odrzuca resztę linii aż do następnego CRLF, bez ponownego raportowania.
- W serwisie `max-record-bytes` = 512 (konfigurowalne).

**`RecordClassifier`** klasyfikuje linię (bez CRLF) do `RecordClass`:

| Klasa | Znaczenie |
| --- | --- |
| `OK` | 1–6 cyfr ASCII, bez znaku. Wartość 0–999999. |
| `EMPTY_LINE` | pusta linia (samo CRLF) |
| `NEGATIVE` | zaczyna się od `-` (reszta ignorowana, wartość odrzucona) |
| `OVERWEIGHT` | więcej niż 6 znaków i bez `-` (czyli ≥ 1 000 000, ponad 100 t, uznajemy za błąd). Sprawdzane przed walidacją cyfr. |
| `NON_DIGIT` | znak niebędący cyfrą albo linia dłuższa niż limit parsera |

Szczegóły pakietów z MOXA: [protokol-moxa.md](<https://docs.logintegra.com/weight-gateway/protokol-moxa/index.md>).

## C. Serwis nasłuchiwacza połączeń TCP (`tcp-service`)

Minimalna aplikacja Grails 8cd.

**`TcpListenerService`** (`SmartLifecycle`)

- Otwiera `ServerSocket` na `weight.port` (domyślnie 14002) przy starcie aplikacji.
- Obsługuje **jedno połączenie naraz**. Nowy klient zamyka poprzednie połączenie i je przejmuje.
- Ustawia `SO_KEEPALIVE` i timeout odczytu `weight.read-timeout-ms` (60 s). Jeśli waga milczy dłużej, połączenie jest zamykane.
- Przy zatrzymaniu aplikacji zamyka gniazdo serwera i aktualne połączenie.
- Bajty przekazuje do `WeightService`, sam niczego nie parsuje.

**`WeightService`**

- `handle(InputStream)` czyta strumień i podaje go do `RecordParser`.
- Każdy rekord, także niepoprawny, zapisuje jako najnowszy `WeightReading` (rekord + czas odebrania `receivedAt`). Niepoprawny rekord **nadpisuje** poprzedni dobry odczyt.
- `isStale(reading)` zwraca `true`, gdy odczyt jest starszy niż `weight.max-age-ms`.
- Odczyt przeżywa rozłączenie wagi, ale po `max-age-ms` staje się nieświeży.

**`WeightController`: `GET /weight`**

Odpowiedź to mała strona HTML, zgodna z tym co już przyjmuje Apollo.

Świeży, poprawny odczyt, status **200**:

```
<span id="weight" data-received-at="2026-11-02T07:47:36.239Z">37900</span>
```

W pozostałych przypadkach status **503** i strona błędu. Stara wartość nigdy nie jest zwracana.

```
<p id="error" data-code="STALE">The last reading is older than 5 s.</p>
```

| `data-code` | Kiedy |
| --- | --- |
| `NO_DATA` | od startu nie odebrano żadnego rekordu |
| `STALE` | ostatni rekord starszy niż `weight.max-age-ms` |
| `INVALID` | ostatni rekord nie był poprawną wagą (np. `NEGATIVE`, `OVERWEIGHT`) |

Kolejność sprawdzania: `NO_DATA`, potem `STALE`, potem `INVALID`.

**`StatusController`: `GET /status`** (tylko GET, nagłówek `Cache-Control: no-store`)

Stan połączenia z wagą jako JSON, dla panelu admin. Endpoint zawsze zwraca status 200, bo brak wagi jest stanem, a nie błędem. Pola bez danych mają wartość `null`.

```
{"connected":true,"peer":"10.0.0.5:51234","connectedSince":"2026-11-02T07:40:00.100Z",
 "lastRecordAt":"2026-11-02T07:47:36.239Z","lastRecordType":"OK","lastValue":37900,"stale":false}
```

| Pole | Znaczenie |
| --- | --- |
| `connected` | czy waga jest teraz połączona z bramką |
| `peer` | adres klienta w postaci `host:port`, `null` bez połączenia |
| `connectedSince` | czas nawiązania obecnego połączenia |
| `lastRecordAt` | czas odebrania ostatniego rekordu, także niepoprawnego |
| `lastRecordType` | klasa ostatniego rekordu, np. `OK` albo `NEGATIVE` |
| `lastValue` | waga z ostatniego rekordu, `null` dla rekordu niepoprawnego |
| `stale` | czy ostatni rekord jest starszy niż `weight.max-age-ms`, `null` przed pierwszym rekordem |

Ostatni rekord pozostaje w odpowiedzi po rozłączeniu wagi.

**Konfiguracja** (`application.yml`):

| Klucz | Domyślnie | Opis |
| --- | --- | --- |
| `weight.port` | `14002` | port nasłuchu TCP (w środowisku `test`: `0`, czyli port losowy) |
| `weight.max-record-bytes` | `512` | limit długości jednej linii |
| `weight.read-timeout-ms` | `60000` | timeout ciszy od wagi |
| `weight.max-age-ms` | `5000` | maksymalny wiek odczytu serwowanego przez HTTP |

## D. Mock (`mock`)

Symulator wagi, czyli klient TCP, który łączy się z `tcp-service` tak jak MOXA. Moduł to biblioteka Java z klasą `ScaleMock` oraz CLI `ScaleMockCli`. `admin` używa `ScaleMock` jako zależności, a testy integracyjne `tcp-service` wysyłają nim dane do prawdziwej aplikacji.

**`ScaleMock`** (`AutoCloseable`)

- `new ScaleMock(host, port)` albo `new ScaleMock(port)` łączy się z `127.0.0.1`. Połączenie nie jest zamykane przez mocka samodzielnie.
- `sendWeight(int)` wysyła liczbę z końcowym CRLF.
- `sendLine(String)` wysyła dowolną linię z CRLF, np. rekord niepoprawny.
- `sendRaw(String)` wysyła tekst bez CRLF, czyli rekord niedokończony.
- `sendChunks(pauseMs, chunks...)` wysyła porcje z przerwą, żeby sprawdzić rekord rozcięty między porcjami TCP.
- `startStreaming(periodMs, weights)` i `stopStreaming()` wysyłają wagę w stałym odstępie z osobnego wątku.
- `isOpen()` i `isClosedByGateway()` pozwalają sprawdzić, czy bramka zamknęła połączenie, np. po przekroczeniu `weight.read-timeout-ms` albo przejęciu przez nowego klienta.
- Zapisy są synchronizowane, więc ręczne wysyłanie można mieszać ze strumieniem.

**`ScaleMockCli`**

```
./gradlew :mock:run --args="<host> <port> [periodMs] [weight]"
```

Bez `periodMs` odstęp wynosi 1000 ms, a bez `weight` mock losuje wagę z zakresu 0–100000. Opis uruchamiania jest na stronie [Uruchamianie i testowanie](<https://docs.logintegra.com/weight-gateway/uruchamianie/index.md>).

Test jednostkowy: `ScaleMockTest`.

## E. Integracje, dokumentacje i wdrożenia

**Testy**:

- Jednostkowe `weight-protocol`: `RecordParserTest` (m.in. `raw` per rekord przy wielu rekordach w porcji, rekord rozcięty między porcjami, przepełnienie), `RecordTest`.
- Jednostkowe `weight-protocol`: także `RecordClassifierTest`.
- Jednostkowe `tcp-service`: `WeightServiceSpec`, `WeightControllerSpec`, `StatusControllerSpec`, `TcpListenerServiceSpec`.
- Jednostkowe `admin`: `GatewayControllerSpec`, `GatewayStatusServiceSpec`, `MockScaleControllerSpec`, `MockScaleServiceSpec`.
- Jednostkowe `mock`: `ScaleMockTest`.
- Integracyjne `tcp-service`: `WeightEndpointSpec`, aplikacja na losowym porcie i dane z `ScaleMock`.
- Integracyjne `admin`: `WeightGatewaySpec`, Geb z kontenerem Dockera.

Polecenia testów opisuje strona [Uruchamianie i testowanie](<https://docs.logintegra.com/weight-gateway/uruchamianie/index.md>).

**Wdrożenie:**

- `Dockerfile` buduje obrazy `tcp-service` i `admin`, a `docker-compose.yml` w katalogu głównym to stack lokalny.
- Pipeline TeamCity (check, publish, deploy) opisuje strona [Wdrożenie](<https://docs.logintegra.com/weight-gateway/wdrozenie/index.md>).
- Ustawienia aplikacji opisuje strona [Konfiguracja](<https://docs.logintegra.com/weight-gateway/konfiguracja/index.md>).

**Do zrobienia:**

- Integracja z `apollo-docker`
- Przygotowanie sieci i serwera (zadania DEV)
- Testy akceptacyjne z prawdziwą wagą

## F. Panel administracyjny (`admin`)

Aplikacja Grails dla testerów i supportu. Ma dwie strony: status połączenia z MOXA i symulator wagi. Nie ma logowania, więc na produkcji powinna być dostępna tylko z VPN. Baza H2 jest skonfigurowana, ale panel niczego w niej nie zapisuje. Port HTTP to `8081`.

**Status połączenia z MOXA** (`/gateway`)

Strona odpytuje `GET /status` w `tcp-service` i pokazuje, czy waga jest połączona. Przy połączeniu widać adres klienta i czas nawiązania połączenia. Widać też ostatni rekord: czas, klasę, wagę i informację, czy odczyt jest świeży. Gdy `tcp-service` nie odpowiada, strona pokazuje stan "Gateway unreachable" z przyczyną. Strona przeładowuje się sama co 3 sekundy.

**Symulator wagi** (`/mockScale`)

Strona steruje jednym symulowanym połączeniem (`MockScaleService`, oparty o `ScaleMock`). Stan jest w pamięci i znika po restarcie panelu. Strona działa tylko, gdy `mock.enabled` ma wartość `true`, a w środowisku `production` każda akcja zwraca 404 (`MockScaleInterceptor`).

| Sekcja | Działanie |
| --- | --- |
| Connection | połączenie z bramką, domyślnie `mock.gateway.host` i `mock.gateway.port`, oraz rozłączenie |
| Streaming | wysyłanie wagi co `periodMs` (minimum 10 ms), stała waga albo losowa gdy pole jest puste |
| Send once | pojedyncza waga z zakresu 0–999999 |
| Presety | rekordy do testów błędów, tabela poniżej |

| Preset | Wysyłane dane | Oczekiwany efekt w `GET /weight` |
| --- | --- | --- |
| `EMPTY_LINE` | samo CRLF | `INVALID` |
| `NEGATIVE` | `-12` | `INVALID` |
| `NON_DIGIT` | `12a` | `INVALID` |
| `OVERWEIGHT` | `1234567` | `INVALID` |
| `TOO_LONG` | 1000 znaków `x` | `INVALID` (rekord przekroczył limit) |
| `PARTIAL` | `12` bez CRLF | bez zmiany, rekord czeka na koniec linii |

Błędy połączenia i niepoprawne dane wracają jako komunikat nad formularzem, a przy błędzie zapisu mock rozłącza się sam.

Konfiguracja panelu jest na stronie [Konfiguracja](<https://docs.logintegra.com/weight-gateway/konfiguracja/index.md#admin>).
