# Dług techniczny w Apollo backend

\[DRAFT\] Stan na 2026-10-09.

Strona zbiera zgłoszenia długu technicznego w `apollo/backend`, wyjaśnia, skąd się wzięło ich tyle, i proponuje sposób pracy z nimi. Jest dla programistów, recenzentów i osób planujących sprint. Propozycja "jedno zadanie na sprint" czeka na akceptację zespołu.

Skan kodu i treść zgłoszeń przygotowano z pomocą narzędzi AI. Autor zatwierdził każde zgłoszenie przed utworzeniem, ale opisy mogą zawierać błędy. Dotyczy to numerów linii, liczby wywołań, podejrzeń błędów i proponowanych rozwiązań. Wykonawca powinien sprawdzić opis w kodzie, zanim zacznie zmianę.

## Skąd tyle zadań

Kod backendu zawiera adnotacje `@Deprecated`, `@deprecated` w komentarzu i `@RefactorCandidate`. Adnotacja mówi, że fragment kodu wymaga zmiany, ale nie mówi, kto ma to zrobić ani kiedy. Adnotacja `@RefactorCandidate` ma pole `youtrackTask`, a prawie wszystkie użycia zostawiały je puste.

Skan branchu `develop` z 2026-10-09 znalazł 133 takie elementy bez numeru zgłoszenia. Elementy należące do jednego tematu zgrupowano, więc powstało 51 zgłoszeń od [A-19391](<https://youtrack.logintegra.com/issue/A-19391>) do [A-19446](<https://youtrack.logintegra.com/issue/A-19446>). Dwa tematy miały już zgłoszenia: [A-16139](<https://youtrack.logintegra.com/issue/A-16139>) dla `TransportPackagingService` i [A-14448](<https://youtrack.logintegra.com/issue/A-14448>) dla `ExchangeRatesTableService`. Cztery elementy świadomie pominięto: `SendMailJob`, `PeriodicTransportsUpdateJob`, `TransportSearchDefinition.toCriteria` i `GuardPaginationService`.

Zgłoszenie dotyczy tematu, a nie pojedynczej metody. Na przykład [A-19424](<https://youtrack.logintegra.com/issue/A-19424>) obejmuje pięć metod `TimeWindowService`, które razem tworzą wyszukiwanie wolnego miejsca dla okna. Wiele przestarzałych metod ma nadal wywołania w kodzie, więc samo usunięcie nie wystarcza. Metoda `CompanyService.findShortName` ma 14 wywołań, a jej zamiennik wymaga decyzji o tym, jaki skrót nazwy firmy pokazujemy w dokumentach CMR i raportach.

Numer zgłoszenia jest zapisany w kodzie:

- w adnotacji, np. `@RefactorCandidate(youtrackTask = "A-19402")`
- w komentarzu dokumentacyjnym elementu `@Deprecated`, w linii `Zadanie: A-19402`
- w linii `// Zadanie: A-19404` nad adnotacją, gdy element nie ma komentarza dokumentacyjnego

Listę oznaczonych miejsc daje polecenie:

```
grep -rn "youtrackTask\|Zadanie: A-" grails-app src
```

## Jak czytać zgłoszenie

Wszystkie zgłoszenia mają ten sam układ.

| Sekcja | Znaczenie |
| --- | --- |
| Jaki jest cel zadania? | opis obecnego kodu, jego wywołań i problemów |
| Wymagana analiza lub decyzja | pytania, na które trzeba odpowiedzieć przed zmianą kodu |
| Proponowane rozwiązanie | kolejne fazy zmiany po rozstrzygnięciu decyzji |
| Jaki jest oczekiwany rezultat? | stan docelowy w jednym lub dwóch zdaniach |
| Kryteria akceptacji | lista kontrolna do przejścia przed merge |

Sekcja o analizie lub decyzji stoi przed rozwiązaniem celowo. Rozwiązanie jest propozycją, która obowiązuje dopiero po rozstrzygnięciu pytań. Zgłoszenie bez tej sekcji opisuje zmianę, którą można zacząć od razu.

## Jak pracować nad zgłoszeniem

Poniższe zasady są propozycją.

1. Przeczytaj całe zgłoszenie i kod, którego dotyczy. Numery linii w opisie pochodzą ze skanu z 2026-10-09 i mogą się przesunąć.
2. Gdy masz wątpliwości co do rozpisanego zadania albo proponowanej zmiany, zgłoś je w komentarzu do zgłoszenia i oznacz @dariusz.bakowski. Nie realizuj opisu, w którym masz wątpliwości. Zadanie zostanie opisane ponownie, a dopiero potem wraca do planowania.
3. Rozstrzygnij pytania z sekcji "Wymagana analiza lub decyzja" i zapisz odpowiedzi w komentarzu do zgłoszenia. Decyzję, która zmienia treść dokumentu albo raportu u klienta, uzgodnij z analitykiem przed napisaniem kodu.
4. Dodaj testy, które utrwalają obecne zachowanie, zanim zmienisz kod (opcjonalne). Większość zgłoszeń wymienia je w kryteriach akceptacji.
5. Pracuj na branchu z numerem zgłoszenia, np. `A-19424`, i trzymaj jeden temat w jednym pull requeście.
6. Po zmianie usuń z kodu znacznik razem z komentarzem `Zadanie: A-XXXX`. Gdy element zostaje, zostaw adnotację z numerem zgłoszenia.
7. Gdy zmiana zmienia opisane zachowanie, zmień dokumentację w tym samym pull requeście.
8. Gdy w trakcie pracy znajdziesz błąd, zapisz go w zgłoszeniu i nie naprawiaj go po cichu w tym samym pull requeście.

Nowy `@RefactorCandidate` powinien od razu dostawać numer zgłoszenia w polu `youtrackTask`, tak jak `TODO` ma numer według zasad dokumentacji. Znacznik bez numeru jest długiem bez właściciela.

## Backlog: jedno zadanie na sprint

Propozycja: w każdym sprincie bierzemy do realizacji jedno zgłoszenie z tej listy.

Dług spłaci się powoli. Jedno zadanie powinno zmieścić się w sprincie razem z bieżącą pracą i nie blokować wydań. Mały, regularny zakres daje czas na recenzję i testy.

Kolejność wyboru:

1. zgłoszenia z podejrzeniem błędu, wymienione niżej
2. zgłoszenia, które usuwają nieużywany kod, np. [A-19404](<https://youtrack.logintegra.com/issue/A-19404>) i [A-19413](<https://youtrack.logintegra.com/issue/A-19413>)
3. deprecacje z gotowym zamiennikiem, np. [A-19391](<https://youtrack.logintegra.com/issue/A-19391>) i [A-19392](<https://youtrack.logintegra.com/issue/A-19392>)
4. refaktory z decyzjami, gdy decyzje są już zapisane
5. duże refaktory dzielone na części

Zgłoszenia z podejrzeniem błędu w obecnym kodzie. Podejrzenia opisują zgłoszenia i wymagają potwierdzenia na danych:

| Zgłoszenie | Podejrzenie |
| --- | --- |
| [A-19391](<https://youtrack.logintegra.com/issue/A-19391>) | zamiennik `PersonRepositoryService.findByToken` rzuca `NullPointerException` dla nieistniejącego tokenu |
| [A-19424](<https://youtrack.logintegra.com/issue/A-19424>) | wyszukiwanie wolnego miejsca zmienia czas przesuwanego okna na encji |
| [A-19429](<https://youtrack.logintegra.com/issue/A-19429>) | odpowiedź w `TruckTypeRESTController.index` jest renderowana dwa razy |
| [A-19434](<https://youtrack.logintegra.com/issue/A-19434>) | zapis szablonu okien może wykonać `INSERT ... VALUES` bez wartości |
| [A-19439](<https://youtrack.logintegra.com/issue/A-19439>) | dokument pojazdu bez daty ważności blokuje awizację z pustą datą w komunikacie |
| [A-19440](<https://youtrack.logintegra.com/issue/A-19440>) | filtr transportów w raporcie awizacji nie odrzuca usuniętych transportów |
| [A-19443](<https://youtrack.logintegra.com/issue/A-19443>) | NIP pryncypała i przewoźnika wygląda na zamieniony w zleceniu transportowym |

## Lista zgłoszeń

Tytuły pochodzą z YouTrack. Rodzaj "Deprecacja" oznacza kod z `@Deprecated`, a "Refaktor" kod z `@RefactorCandidate`.

### Wycofanie przestarzałego kodu

| Zgłoszenie | Rodzaj | Temat | Stan |
| --- | --- | --- | --- |
| ~~[A-19391](<https://youtrack.logintegra.com/issue/A-19391>)~~ | ~~Deprecacja~~ | ~~`Person.findByToken` na `IPersonRepositoryService.findByToken`~~ | Rozwiązane |
| [A-19392](<https://youtrack.logintegra.com/issue/A-19392>) | Deprecacja | `Setting.findValueByCompany` i `findIntegerValueByCompany` na `SettingCacheService` |  |
| [A-19398](<https://youtrack.logintegra.com/issue/A-19398>) | Deprecacja | `Company.getTransportTypes()` i `Warehouse.getTransportTypes(Person)` z domeny |  |
| [A-19400](<https://youtrack.logintegra.com/issue/A-19400>) | Deprecacja | sortowanie ofert `SORT_BY_PRICE_AND_DATE_CREATED` i `findAllOffersEnabledAndSorted` |  |
| [A-19401](<https://youtrack.logintegra.com/issue/A-19401>) | Deprecacja | `MoveWindowCommand` i stare walidacje przesuwania okien na `TimeWindowMoveService` |  |
| [A-19403](<https://youtrack.logintegra.com/issue/A-19403>) | Deprecacja | `TransportFilterUtil` na `TransportQueryBuilder` |  |
| [A-19404](<https://youtrack.logintegra.com/issue/A-19404>) | Deprecacja | nieużywane pola `company` i `recipient` w `Index` i `IndexCommand` |  |
| [A-19405](<https://youtrack.logintegra.com/issue/A-19405>) | Deprecacja | `AddressService.findAddresses` |  |
| [A-19406](<https://youtrack.logintegra.com/issue/A-19406>) | Deprecacja | planowanie powiadomienia `ADVICE_VERIFICATION` |  |
| [A-19407](<https://youtrack.logintegra.com/issue/A-19407>) | Deprecacja | `AdviceService.queryAdvices` i `GET /api/advices` |  |
| [A-19408](<https://youtrack.logintegra.com/issue/A-19408>) | Deprecacja | liczenie sumy palet na `PalletQuantityService` |  |
| [A-19409](<https://youtrack.logintegra.com/issue/A-19409>) | Deprecacja | `placedInAssortmentGroupWorkingHours` do `TimeWindowValidationService` |  |
| [A-19410](<https://youtrack.logintegra.com/issue/A-19410>) | Deprecacja | `CompanyService.count`, `find` i `getCompaniesQuery` na `CompanyListService` |  |
| [A-19412](<https://youtrack.logintegra.com/issue/A-19412>) | Deprecacja | `GET /api/advices/getAdviceByDriver` i metoda dla SK API |  |
| [A-19413](<https://youtrack.logintegra.com/issue/A-19413>) | Deprecacja | nieużywane `canBeSeenByPerson` i stała parametru kurierskiego |  |
| [A-19446](<https://youtrack.logintegra.com/issue/A-19446>) | Deprecacja | `CompanyService.findShortName` i reguła skrótu nazwy firmy |  |

### Integracje i wysyłka

| Zgłoszenie | Rodzaj | Temat |
| --- | --- | --- |
| [A-19402](<https://youtrack.logintegra.com/issue/A-19402>) | Deprecacja | `ApiService` i joby wysyłające komunikaty API po aktualizacji transportu |
| [A-19425](<https://youtrack.logintegra.com/issue/A-19425>) | Refaktor | `RestfulService` i `RestfullJob`, wysyłka SMS i komunikatów przez Quartz |
| [A-19426](<https://youtrack.logintegra.com/issue/A-19426>) | Refaktor | `CheckpointConfirmationHandlerService`, ponawianie wysyłki i specjalna notacja adresów |

### Transport, step'y i etapy

| Zgłoszenie | Rodzaj | Temat |
| --- | --- | --- |
| [A-19411](<https://youtrack.logintegra.com/issue/A-19411>) | Refaktor | `StepCommand`, tworzenie step'a, firmy i okna czasowego |
| [A-19444](<https://youtrack.logintegra.com/issue/A-19444>) | Refaktor | `StepCommandFactory`, statyczna fabryka z `Holders` |
| [A-19421](<https://youtrack.logintegra.com/issue/A-19421>) | Refaktor | `WorkflowService`, potwierdzanie etapów i etapów transportów łączonych |
| [A-19422](<https://youtrack.logintegra.com/issue/A-19422>) | Refaktor | odtwarzanie etapów transportu i planowanie jobów |
| [A-19423](<https://youtrack.logintegra.com/issue/A-19423>) | Refaktor | `TransportService.updateTransport`, podział na fazy |
| [A-19428](<https://youtrack.logintegra.com/issue/A-19428>) | Refaktor | `StepService`, zapis i aktualizacja step'ów z oknami czasowymi |
| [A-19437](<https://youtrack.logintegra.com/issue/A-19437>) | Refaktor | `TransportUpdateChangesCommand` i `TransportTransportRelationCommand` bez zapytań w konstruktorach |
| [A-19427](<https://youtrack.logintegra.com/issue/A-19427>) | Refaktor | zapytania i zależności od serwisów w encjach `Step`, `Transport`, `Company`, `Ramp`, `TimeWindow` |

### Okna czasowe i rampy

| Zgłoszenie | Rodzaj | Temat |
| --- | --- | --- |
| [A-19424](<https://youtrack.logintegra.com/issue/A-19424>) | Refaktor | `TimeWindowService`, wolne miejsce dla okna i przesuwanie opóźnionych okien |
| [A-19419](<https://youtrack.logintegra.com/issue/A-19419>) | Refaktor | `WarehouseService.overlapsAnyWindowOnRamp`, jedna metoda zamiast czterech przeciążeń |
| [A-19438](<https://youtrack.logintegra.com/issue/A-19438>) | Refaktor | obliczanie długości okna czasowego |
| [A-19439](<https://youtrack.logintegra.com/issue/A-19439>) | Refaktor | `TimeWindowCommand.validateTruckDates`, ważność dokumentów pojazdu |

### Kontrolery REST

| Zgłoszenie | Rodzaj | Temat |
| --- | --- | --- |
| [A-19415](<https://youtrack.logintegra.com/issue/A-19415>) | Refaktor | `CheckpointRESTController.confirm` |
| [A-19416](<https://youtrack.logintegra.com/issue/A-19416>) | Refaktor | `PersonRESTController.update`, uprawnienia i zmiana hasła |
| [A-19417](<https://youtrack.logintegra.com/issue/A-19417>) | Refaktor | `PartnershipRESTController.index` i `PartnershipService.findPartnerships` |
| [A-19418](<https://youtrack.logintegra.com/issue/A-19418>) | Refaktor | składanie oferty w aukcji, `OfferRESTController.save` i `OfferService.saveOffer` |
| [A-19420](<https://youtrack.logintegra.com/issue/A-19420>) | Refaktor | trasy cenników, `RouteRESTController.save`, `RouteService` i `RouteCommandFactory` |
| [A-19429](<https://youtrack.logintegra.com/issue/A-19429>) | Refaktor | `TransportRESTController.validate` i `TruckTypeRESTController.index` |

### Serwisy i zapis danych

| Zgłoszenie | Rodzaj | Temat |
| --- | --- | --- |
| [A-19396](<https://youtrack.logintegra.com/issue/A-19396>) | Refaktor | `Setting.create*` z domeny do `ChangelogUtil` |
| [A-19414](<https://youtrack.logintegra.com/issue/A-19414>) | Refaktor | `PartnershipService.findPartnershipWithPrincipal` jednym zapytaniem |
| [A-19430](<https://youtrack.logintegra.com/issue/A-19430>) | Refaktor | `CustomFieldsService.save`, definicja custom-fielda z opcjami |
| [A-19432](<https://youtrack.logintegra.com/issue/A-19432>) | Refaktor | podział `AdviceService` |
| [A-19433](<https://youtrack.logintegra.com/issue/A-19433>) | Refaktor | dopłaty, `SurchargeValueService.confirm` i reguły uprawnień |
| [A-19434](<https://youtrack.logintegra.com/issue/A-19434>) | Refaktor | `WarehouseTemplateService.saveNewTemplateTimeWindows` bez ręcznego SQL |
| [A-19435](<https://youtrack.logintegra.com/issue/A-19435>) | Refaktor | `SapToLpService.saveOrUpdateDelivery`, jedna ścieżka zapisu |
| [A-19436](<https://youtrack.logintegra.com/issue/A-19436>) | Refaktor | `CacheService.clearCacheForTransport`, flaga `includeRelatedCaches` |

### Raporty i dokumenty

| Zgłoszenie | Rodzaj | Temat |
| --- | --- | --- |
| [A-19431](<https://youtrack.logintegra.com/issue/A-19431>) | Refaktor | oferty tras, `RouteOfferService.findActiveTransports` bez zapytań w pętli |
| [A-19440](<https://youtrack.logintegra.com/issue/A-19440>) | Refaktor | raporty Excel, wybór transportów i checkpoint'ów |
| [A-19441](<https://youtrack.logintegra.com/issue/A-19441>) | Refaktor | `TransportExcelSheetConfig`, definicja kolumn |
| [A-19442](<https://youtrack.logintegra.com/issue/A-19442>) | Refaktor | `RouteOfferExcelMap`, konstruktor z `Holders` |
| [A-19443](<https://youtrack.logintegra.com/issue/A-19443>) | Refaktor | `GenericTransportOrderModelBuilder`, model zlecenia transportowego |

### Migracje

| Zgłoszenie | Rodzaj | Temat |
| --- | --- | --- |
| [A-19445](<https://youtrack.logintegra.com/issue/A-19445>) | Refaktor | `ChangelogUtil.createIndex`, konwencja nazw indeksów |

### Zgłoszenia, które już istniały

| Zgłoszenie | Temat |
| --- | --- |
| [A-16139](<https://youtrack.logintegra.com/issue/A-16139>) | `TransportPackagingService` |
| [A-14448](<https://youtrack.logintegra.com/issue/A-14448>) | `ExchangeRatesTableService` |
