update

.paul/plans/20260713-2111-skanowanie-paragonu-kamera/PLAN.md

@@ -0,0 +1,147 @@
+---
+plan_id: 20260713-2111-skanowanie-paragonu-kamera
+title: Skanowanie paragonu kamerą telefonu
+storage: plan-first
+legacy_phase: null
+created: 2026-07-13T21:11:21+02:00
+status: planned
+type: execute
+autonomous: false
+delegation: auto
+files_modified:
+  - app/Views/receipts/new.php
+quality_radar: ok
+---
+
+<objective>
+## Cel
+Umożliwić wykonanie zdjęcia paragonu tylną kamerą telefonu bezpośrednio z formularza importu.
+
+## Uzasadnienie
+Użytkownik nie musi wcześniej zapisywać zdjęcia ani wybierać go z galerii; wykonane zdjęcie trafia do istniejącego importu i analizy AI.
+
+## Wynik
+Formularz `receipts/new` korzysta z natywnego mechanizmu HTML `capture="environment"`, zachowując dotychczasowy upload JPG/PNG/PDF/JSON i istniejący endpoint `Receipts::create`.
+</objective>
+
+<context>
+## Dokumentacja projektu
+@.paul/PROJECT.md
+@.paul/STATE.md
+@.paul/plans/20260706-2046-import-paragonow/SUMMARY.md
+@.paul/codebase/architecture.md
+@.paul/codebase/impact_map.md
+@.paul/codebase/quality_risks.md
+
+## Pliki źródłowe
+@app/Views/receipts/new.php
+@app/Controllers/Receipts.php
+@app/Config/Routes.php
+</context>
+
+<clarifications>
+- Przyjęto natywny wybór tylnej kamery telefonu; nie jest potrzebny podgląd obrazu na żywo ani własny interfejs aparatu.
+</clarifications>
+
+<impact_scan>
+## Quality Radar
+
+**Status:** ok
+**Narzędzia:** codebase-memory-mcp 0.6.1 (indeks gotowy, 789 węzłów / 1015 krawędzi); jscpd i ast-grep wyłączone polityką.
+
+## Obszary wpływu
+
+- `app/Views/receipts/new.php` — jedyne miejsce wymagające zmiany: natywna wskazówka użycia tylnej kamery i jasny tekst formularza.
+- `Receipts::create` — bez zmian; już waliduje, zapisuje i parsuje JPG/JPEG/PNG do 10 MB.
+- Routing, parser AI, modele i baza danych — bez zmian.
+- Weryfikacja — telefon z przeglądarką mobilną oraz kontrola zachowania dotychczasowego wyboru pliku.
+
+## Ryzyka duplikacji / hardcodowania
+
+- Nie tworzyć drugiego endpointu ani drugiego przepływu uploadu; zdjęcie ma użyć istniejącego pola `receipt` i `Receipts::create`.
+- Atrybut `capture` jest wskazówką dla przeglądarki, więc zachowanie aparatu zależy od telefonu; obsłużone przez checkpoint UAT.
+
+## Jawne odroczenia
+
+- WebRTC, własny podgląd kamery, kadrowanie, kompresja i skanowanie wielu zdjęć — poza zakresem; dodać dopiero po osobnym wymaganiu.
+</impact_scan>
+
+<!-- Brak SPECIAL-FLOWS.md — sekcja skills pominięta. -->
+
+<acceptance_criteria>
+
+## AC-1: Uruchomienie tylnej kamery na telefonie
+```gherkin
+Given użytkownik otworzył formularz nowego importu na obsługiwanym telefonie
+When wybiera pole skanu paragonu
+Then przeglądarka umożliwia wykonanie zdjęcia tylną kamerą
+```
+
+## AC-2: Zdjęcie korzysta z istniejącego importu
+```gherkin
+Given użytkownik wykonał zdjęcie paragonu w formularzu
+When wysyła formularz
+Then zdjęcie trafia jako pole `receipt` do `Receipts::create` i przechodzi dotychczasowy przepływ parsowania oraz przeglądu
+```
+
+## AC-3: Dotychczasowe formaty pozostają dostępne
+```gherkin
+Given użytkownik nie chce wykonać zdjęcia aparatem
+When korzysta z formularza importu
+Then nadal może przekazać obsługiwany plik JPG, JPEG, PNG, PDF lub JSON
+```
+
+</acceptance_criteria>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Włączyć natywne przechwytywanie zdjęcia</name>
+  <files>app/Views/receipts/new.php</files>
+  <action>
+    Dodać do istniejącego `input type="file"` atrybut `capture="environment"`, bez JavaScriptu i bez nowego formularza lub endpointu. Zachować `name="receipt"`, `required`, wszystkie obecne typy `accept` oraz limit opisany w UI. Zmienić etykietę i krótki tekst pomocniczy tak, aby użytkownik telefonu rozumiał możliwość zrobienia zdjęcia i dalszą analizę AI.
+  </action>
+  <verify>`php -l app/Views/receipts/new.php` oraz kontrola źródła: dokładnie jedno pole `name="receipt"` z `capture="environment"`.</verify>
+  <done>AC-1, AC-2 i AC-3 są pokryte w kodzie formularza, a dotychczasowy backend pozostaje nietknięty.</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 2: Potwierdzić import zdjęcia na telefonie</name>
+  <files>app/Views/receipts/new.php</files>
+  <action>
+    Na telefonie otworzyć `/receipts/new`, uruchomić pole pliku, wykonać zdjęcie paragonu tylną kamerą i wysłać formularz. Potwierdzić przejście do przeglądu rozpoznanych pozycji. Następnie sprawdzić, że formularz nadal pozwala wybrać wcześniej istniejący obsługiwany plik.
+  </action>
+  <verify>Manualny UAT na docelowym telefonie: aparat tylny → zdjęcie → upload → ekran przeglądu; dodatkowo wybór istniejącego pliku.</verify>
+  <done>AC-1, AC-2 i AC-3 potwierdzone na urządzeniu mobilnym.</done>
+</task>
+
+</tasks>
+
+<boundaries>
+## Nie zmieniać
+- `app/Controllers/Receipts.php`, `app/Libraries/ReceiptParser.php`, tras, modeli, migracji ani schematu bazy.
+- Istniejącego limitu 10 MB, whitelisty rozszerzeń oraz półautomatycznego zatwierdzania pozycji.
+
+## Limity zakresu
+- Jedno zdjęcie / jeden plik na import.
+- Bez WebRTC, JavaScriptowego podglądu, kadrowania, filtrów obrazu, kompresji i galerii wielu stron.
+- Bez nowych zależności.
+</boundaries>
+
+<verification>
+- [ ] `php -l app/Views/receipts/new.php`
+- [ ] Pole `receipt` zawiera `capture="environment"` i zachowuje obecny `accept`.
+- [ ] Manualny UAT aparatu i dotychczasowego wyboru pliku na telefonie.
+- [ ] Nie zmieniono backendu, routingu ani bazy danych.
+- [ ] Ryzyka Quality Radar obsłużono lub jawnie odroczono.
+</verification>
+
+<success_criteria>
+- [ ] Wszystkie AC przechodzą.
+- [ ] Weryfikacja automatyczna i mobilna jest zakończona.
+- [ ] Zmiana obejmuje tylko istniejący widok formularza.
+</success_criteria>
+
+<output>
+SUMMARY.md path: `.paul/plans/20260713-2111-skanowanie-paragonu-kamera/SUMMARY.md`
+</output>