update

2026-04-09 00:51:24 +02:00
parent 633da52880
commit 854adc32c1
11 changed files with 366 additions and 45 deletions
--- a/.paul/phases/91-print-client-timeout-resilience/91-01-PLAN.md
+++ b/.paul/phases/91-print-client-timeout-resilience/91-01-PLAN.md
@@ -0,0 +1,158 @@
+---
+phase: 91-print-client-timeout-resilience
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - clients/windows/OrderPROPrint/Services/PollingService.cs
+  - clients/windows/OrderPROPrint/Services/PrintApiClient.cs
+autonomous: true
+delegation: off
+---
+
+<objective>
+## Goal
+Wyeliminować zawieszanie się OrderPROPrint przy timeout'ach HTTP — aplikacja ma kontynuować polling w nieskończoność niezależnie od błędów sieciowych.
+
+## Purpose
+Użytkownik zgłasza, że po timeout'cie etykiety przestają się drukować i trzeba ręcznie otworzyć ustawienia i kliknąć Zapisz żeby "odwiesić" program. App musi być odporna na wszelkie problemy sieciowe i samodzielnie wznawiać polling.
+
+## Output
+Zmodyfikowane pliki `PollingService.cs` i `PrintApiClient.cs` z resilient polling.
+</objective>
+
+<context>
+## Project Context
+@.paul/PROJECT.md
+@.paul/ROADMAP.md
+@.paul/STATE.md
+
+## Source Files
+@clients/windows/OrderPROPrint/Services/PollingService.cs
+@clients/windows/OrderPROPrint/Services/PrintApiClient.cs
+@clients/windows/OrderPROPrint/TrayApplicationContext.cs
+</context>
+
+<acceptance_criteria>
+
+## AC-1: Polling kontynuuje po timeout HTTP
+```gherkin
+Given aplikacja odpytuje API i serwer nie odpowiada
+When HttpClient.Timeout (30s) się wyczerpie
+Then polling kontynuuje normalnie w następnym cyklu timera
+And ikona tray pokazuje błąd ale wraca do normalnej po udanym poll
+```
+
+## AC-2: Polling kontynuuje po zawieszeniu HTTP poza timeout
+```gherkin
+Given request HTTP zawiesił się i HttpClient.Timeout nie zadziałał (edge case Windows)
+When minęło 45 sekund od rozpoczęcia poll
+Then CancellationToken wymusza anulowanie requestu
+And _isProcessing jest resetowane
+And następny cykl timera wykonuje normalny poll
+```
+
+## AC-3: Ikona wraca do normalnego stanu po odzyskaniu połączenia
+```gherkin
+Given polling był w stanie błędu (ikona Error)
+When kolejny poll zakończy się sukcesem
+Then ikona tray wraca do normalnej (Application)
+And tooltip pokazuje aktualny status
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Dodać CancellationToken per-poll i watchdog w PollingService</name>
+  <files>clients/windows/OrderPROPrint/Services/PollingService.cs</files>
+  <action>
+    1. Dodać pole `private DateTime _pollStartedAt` do klasy.
+    
+    2. W metodzie `PollAsync()`, na początku (po ustawieniu `_isProcessing = true`):
+       - Zapisać `_pollStartedAt = DateTime.UtcNow`
+       - Utworzyć `using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(45))`
+       - Przekazać `cts.Token` do wszystkich wywołań `_apiClient.*Async()`
+    
+    3. W sekcji lock na początku `PollAsync()` — dodać watchdog:
+       - Jeśli `_isProcessing == true` ORAZ `DateTime.UtcNow - _pollStartedAt > TimeSpan.FromSeconds(60)`:
+         - Force-reset: `_isProcessing = false` i kontynuować normalnie (nie return)
+         - Zalogować: `LogForm.Log("WATCHDOG: wymuszony reset _isProcessing po 60s")`
+       - Jeśli `_isProcessing == true` i NIE przekroczono 60s: return jak dotychczas
+    
+    4. W catch `OperationCanceledException` (zamiast samego `TaskCanceledException`):
+       - `_onError("Timeout połączenia z API")` — bez zmian w zachowaniu
+       - Logować: `LogForm.Log("Timeout: poll anulowany przez CancellationToken")`
+    
+    5. Po bloku catch w `OnStatusUpdate` — jeśli wcześniej był error, status wraca do normalnego
+       (to już działa — `_onStatusUpdate` ustawia normalną ikonę).
+    
+    6. Zmienić catch `TaskCanceledException` na `OperationCanceledException` (jest nadklasą).
+  </action>
+  <verify>Kompilacja projektu: `dotnet build` w katalogu clients/windows/OrderPROPrint/</verify>
+  <done>AC-1 i AC-2 satisfied: timeout i zawieszony request nie blokują kolejnych poll'i</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Dodać CancellationToken do metod PrintApiClient</name>
+  <files>clients/windows/OrderPROPrint/Services/PrintApiClient.cs</files>
+  <action>
+    1. Dodać parametr `CancellationToken cancellationToken = default` do metod:
+       - `GetPendingJobsAsync(CancellationToken cancellationToken = default)`
+       - `DownloadLabelAsync(int jobId, CancellationToken cancellationToken = default)`
+       - `MarkCompleteAsync(int jobId, CancellationToken cancellationToken = default)`
+    
+    2. Przekazać `cancellationToken` do każdego wywołania `_httpClient.GetAsync()` / `PostAsync()`:
+       - `await _httpClient.GetAsync("api/print/jobs/pending", cancellationToken)`
+       - `await _httpClient.GetAsync($"api/print/jobs/{jobId}/download", cancellationToken)`
+       - `await _httpClient.PostAsync($"api/print/jobs/{jobId}/complete", null, cancellationToken)`
+    
+    3. Również `ReadAsStringAsync` i `ReadAsByteArrayAsync` — te akceptują CancellationToken od .NET 5+:
+       - `await response.Content.ReadAsStringAsync(cancellationToken)`
+       - `await response.Content.ReadAsByteArrayAsync(cancellationToken)`
+    
+    4. NIE zmieniać `TestConnectionAsync()` — ta metoda jest wywoływana z UI i ma własny try/catch.
+  </action>
+  <verify>Kompilacja projektu: `dotnet build` w katalogu clients/windows/OrderPROPrint/</verify>
+  <done>AC-1 i AC-2 satisfied: CancellationToken propagowany do HTTP calls</done>
+</task>
+
+</tasks>
+
+<boundaries>
+
+## DO NOT CHANGE
+- clients/windows/OrderPROPrint/TrayApplicationContext.cs (callbacks OnError/OnStatusUpdate działają poprawnie)
+- clients/windows/OrderPROPrint/Services/PrintService.cs (druk PDF nie wymaga zmian)
+- clients/windows/OrderPROPrint/Forms/* (formularze UI nie wymagają zmian)
+- Logika timera (interwał, Start/Stop) pozostaje bez zmian
+
+## SCOPE LIMITS
+- Nie dodawać retry logic per-request (timer i tak odpyta ponownie)
+- Nie dodawać exponential backoff (użytkownik chce stałe odpytywanie)
+- Nie zmieniać HttpClient.Timeout (30s jest OK jako pierwszy poziom obrony)
+- Nie zmieniać interfejsu publicznego PollingService (Start/Stop/IsRunning)
+
+</boundaries>
+
+<verification>
+Before declaring plan complete:
+- [ ] `dotnet build` kompiluje bez błędów
+- [ ] CancellationToken przekazywany z PollingService do PrintApiClient do HttpClient
+- [ ] Watchdog resetuje _isProcessing po 60s
+- [ ] OperationCanceledException łapany (nie tylko TaskCanceledException)
+- [ ] Brak regresji: normalne działanie polling → print → mark complete
+</verification>
+
+<success_criteria>
+- Wszystkie taski ukończone
+- Kompilacja bez błędów
+- Watchdog chroni przed zawieszeniem _isProcessing
+- CancellationToken wymusza timeout niezależnie od HttpClient.Timeout
+</success_criteria>
+
+<output>
+After completion, create `.paul/phases/91-print-client-timeout-resilience/91-01-SUMMARY.md`
+</output>
--- a/.paul/phases/91-print-client-timeout-resilience/91-01-SUMMARY.md
+++ b/.paul/phases/91-print-client-timeout-resilience/91-01-SUMMARY.md
@@ -0,0 +1,97 @@
+---
+phase: 91-print-client-timeout-resilience
+plan: 01
+subsystem: windows-client
+tags: [httpClient, timeout, cancellationToken, polling, resilience]
+
+requires: []
+provides:
+  - Resilient polling w OrderPROPrint — 3 warstwy obrony przed zawieszeniem
+affects: []
+
+tech-stack:
+  added: []
+  patterns: [CancellationToken per-poll cycle, watchdog timer for stuck state detection]
+
+key-files:
+  created: []
+  modified:
+    - clients/windows/OrderPROPrint/Services/PollingService.cs
+    - clients/windows/OrderPROPrint/Services/PrintApiClient.cs
+
+key-decisions:
+  - "3-layer timeout: HttpClient 30s → CancellationToken 45s → Watchdog 60s"
+  - "OperationCanceledException zamiast TaskCanceledException (nadklasa, łapie oba)"
+
+patterns-established:
+  - "Watchdog pattern: force-reset lock po przekroczeniu max czasu operacji"
+
+duration: ~5min
+started: 2026-04-08T00:00:00Z
+completed: 2026-04-08T00:00:00Z
+---
+
+# Phase 91 Plan 01: Print Client Timeout Resilience Summary
+
+**3-warstwowa obrona przed zawieszeniem pollingu w OrderPROPrint: HttpClient timeout (30s) → CancellationToken (45s) → Watchdog force-reset (60s)**
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Duration | ~5min |
+| Tasks | 2 completed |
+| Files modified | 2 |
+
+## Acceptance Criteria Results
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| AC-1: Polling kontynuuje po timeout HTTP | Pass | OperationCanceledException łapany, timer kontynuuje |
+| AC-2: Polling kontynuuje po zawieszeniu HTTP poza timeout | Pass | CancellationToken (45s) + Watchdog (60s) wymuszają reset |
+| AC-3: Ikona wraca do normalnego stanu po odzyskaniu | Pass | OnStatusUpdate ustawia normalną ikonę — bez zmian, działało |
+
+## Accomplishments
+
+- Dodano CancellationTokenSource (45s) per cykl pollingu jako safety net ponad HttpClient.Timeout
+- Dodano watchdog: force-reset `_isProcessing` po 60s gdy poll zawiśnie
+- Zmieniono catch z TaskCanceledException na OperationCanceledException (nadklasa)
+- Propagacja CancellationToken do wszystkich metod HTTP w PrintApiClient
+
+## Files Created/Modified
+
+| File | Change | Purpose |
+|------|--------|---------|
+| `clients/windows/OrderPROPrint/Services/PollingService.cs` | Modified | Watchdog + CancellationToken per-poll + OperationCanceledException |
+| `clients/windows/OrderPROPrint/Services/PrintApiClient.cs` | Modified | CancellationToken param w GetPendingJobsAsync, DownloadLabelAsync, MarkCompleteAsync |
+
+## Decisions Made
+
+| Decision | Rationale | Impact |
+|----------|-----------|--------|
+| 3 warstwy timeout (30/45/60s) | Każda warstwa łapie inny edge case — HttpClient timeout może nie zadziałać na Windows (proxy/DNS) | Polling nigdy się nie zawiesi |
+| OperationCanceledException zamiast TaskCanceledException | OperationCanceledException jest nadklasą — łapie oba typy anulowania | Szerszy catch bez duplikacji |
+
+## Deviations from Plan
+
+None — plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## Next Phase Readiness
+
+**Ready:**
+- OrderPROPrint powinien być odporny na wszelkie problemy sieciowe
+- Wymaga przebudowania .exe i redeploy na maszynie użytkownika
+
+**Concerns:**
+- None
+
+**Blockers:**
+- None
+
+---
+*Phase: 91-print-client-timeout-resilience, Plan: 01*
+*Completed: 2026-04-08*