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 liniiZadanie: A-19402 - w linii
// Zadanie: A-19404nad adnotacją, gdy element nie ma komentarza dokumentacyjnego
Listę oznaczonych miejsc daje polecenie:
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ą.
- 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ąć.
- 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.
- 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.
- Dodaj testy, które utrwalają obecne zachowanie, zanim zmienisz kod (opcjonalne). Większość zgłoszeń wymienia je w kryteriach akceptacji.
- Pracuj na branchu z numerem zgłoszenia, np.
A-19424, i trzymaj jeden temat w jednym pull requeście. - Po zmianie usuń z kodu znacznik razem z komentarzem
Zadanie: A-XXXX. Gdy element zostaje, zostaw adnotację z numerem zgłoszenia. - Gdy zmiana zmienia opisane zachowanie, zmień dokumentację w tym samym pull requeście.
- 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:
- zgłoszenia z podejrzeniem błędu, wymienione niżej
- zgłoszenia, które usuwają nieużywany kod, np. A-19404 i A-19413
- deprecacje z gotowym zamiennikiem, np. A-19391 i A-19392
- refaktory z decyzjami, gdy decyzje są już zapisane
- 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 |
|---|---|---|---|
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