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

---
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>