Przejdź do treści

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 do A-19446. Dwa tematy miały już zgłoszenia: A-16139 dla TransportPackagingService i 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 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 i A-19413
  3. deprecacje z gotowym zamiennikiem, np. A-19391 i 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 zamiennik PersonRepositoryService.findByToken rzuca NullPointerException dla nieistniejącego tokenu
A-19424 wyszukiwanie wolnego miejsca zmienia czas przesuwanego okna na encji
A-19429 odpowiedź w TruckTypeRESTController.index jest renderowana dwa razy
A-19434 zapis szablonu okien może wykonać INSERT ... VALUES bez wartości
A-19439 dokument pojazdu bez daty ważności blokuje awizację z pustą datą w komunikacie
A-19440 filtr transportów w raporcie awizacji nie odrzuca usuniętych transportów
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 Deprecacja Person.findByToken na IPersonRepositoryService.findByToken Rozwiązane
A-19392 Deprecacja Setting.findValueByCompany i findIntegerValueByCompany na SettingCacheService
A-19398 Deprecacja Company.getTransportTypes() i Warehouse.getTransportTypes(Person) z domeny
A-19400 Deprecacja sortowanie ofert SORT_BY_PRICE_AND_DATE_CREATED i findAllOffersEnabledAndSorted
A-19401 Deprecacja MoveWindowCommand i stare walidacje przesuwania okien na TimeWindowMoveService
A-19403 Deprecacja TransportFilterUtil na TransportQueryBuilder
A-19404 Deprecacja nieużywane pola company i recipient w Index i IndexCommand
A-19405 Deprecacja AddressService.findAddresses
A-19406 Deprecacja planowanie powiadomienia ADVICE_VERIFICATION
A-19407 Deprecacja AdviceService.queryAdvices i GET /api/advices
A-19408 Deprecacja liczenie sumy palet na PalletQuantityService
A-19409 Deprecacja placedInAssortmentGroupWorkingHours do TimeWindowValidationService
A-19410 Deprecacja CompanyService.count, find i getCompaniesQuery na CompanyListService
A-19412 Deprecacja GET /api/advices/getAdviceByDriver i metoda dla SK API
A-19413 Deprecacja nieużywane canBeSeenByPerson i stała parametru kurierskiego
A-19446 Deprecacja CompanyService.findShortName i reguła skrótu nazwy firmy

Integracje i wysyłka

Zgłoszenie Rodzaj Temat
A-19402 Deprecacja ApiService i joby wysyłające komunikaty API po aktualizacji transportu
A-19425 Refaktor RestfulService i RestfullJob, wysyłka SMS i komunikatów przez Quartz
A-19426 Refaktor CheckpointConfirmationHandlerService, ponawianie wysyłki i specjalna notacja adresów

Transport, step'y i etapy

Zgłoszenie Rodzaj Temat
A-19411 Refaktor StepCommand, tworzenie step'a, firmy i okna czasowego
A-19444 Refaktor StepCommandFactory, statyczna fabryka z Holders
A-19421 Refaktor WorkflowService, potwierdzanie etapów i etapów transportów łączonych
A-19422 Refaktor odtwarzanie etapów transportu i planowanie jobów
A-19423 Refaktor TransportService.updateTransport, podział na fazy
A-19428 Refaktor StepService, zapis i aktualizacja step'ów z oknami czasowymi
A-19437 Refaktor TransportUpdateChangesCommand i TransportTransportRelationCommand bez zapytań w konstruktorach
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 Refaktor TimeWindowService, wolne miejsce dla okna i przesuwanie opóźnionych okien
A-19419 Refaktor WarehouseService.overlapsAnyWindowOnRamp, jedna metoda zamiast czterech przeciążeń
A-19438 Refaktor obliczanie długości okna czasowego
A-19439 Refaktor TimeWindowCommand.validateTruckDates, ważność dokumentów pojazdu

Kontrolery REST

Zgłoszenie Rodzaj Temat
A-19415 Refaktor CheckpointRESTController.confirm
A-19416 Refaktor PersonRESTController.update, uprawnienia i zmiana hasła
A-19417 Refaktor PartnershipRESTController.index i PartnershipService.findPartnerships
A-19418 Refaktor składanie oferty w aukcji, OfferRESTController.save i OfferService.saveOffer
A-19420 Refaktor trasy cenników, RouteRESTController.save, RouteService i RouteCommandFactory
A-19429 Refaktor TransportRESTController.validate i TruckTypeRESTController.index

Serwisy i zapis danych

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

Raporty i dokumenty

Zgłoszenie Rodzaj Temat
A-19431 Refaktor oferty tras, RouteOfferService.findActiveTransports bez zapytań w pętli
A-19440 Refaktor raporty Excel, wybór transportów i checkpoint'ów
A-19441 Refaktor TransportExcelSheetConfig, definicja kolumn
A-19442 Refaktor RouteOfferExcelMap, konstruktor z Holders
A-19443 Refaktor GenericTransportOrderModelBuilder, model zlecenia transportowego

Migracje

Zgłoszenie Rodzaj Temat
A-19445 Refaktor ChangelogUtil.createIndex, konwencja nazw indeksów

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

Zgłoszenie Temat
A-16139 TransportPackagingService
A-14448 ExchangeRatesTableService

Ostatnia zmiana: 2026-10-22 · olkusz
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e