---
phase: 10-receipt-issue
plan: 01
subsystem: accounting
tags: [php, receipts, orders, crud, snapshots, atomic-numbering]

requires:
  - phase: 08-db-foundation
    provides: receipts, receipt_configs, receipt_number_counters tables
  - phase: 09-receipt-config
    provides: ReceiptConfigRepository CRUD, active configs
provides:
  - Wystawianie paragonow z poziomu zamowienia
  - ReceiptRepository (CRUD + atomowe numerowanie)
  - ReceiptController (formularz + zapis ze snapshotami)
  - Przycisk "Wystaw paragon" w widoku zamowienia
  - Lista paragonow + dokumentow zewnetrznych w zakladce Dokumenty
  - Activity log entry po wystawieniu paragonu
affects: [11-receipt-print, 12-accounting-list]

tech-stack:
  added: []
  patterns: [snapshot-json-pattern for seller/buyer/items, atomic-counter-pattern for receipt numbering]

key-files:
  created:
    - src/Modules/Accounting/ReceiptRepository.php
    - src/Modules/Accounting/ReceiptController.php
    - resources/views/orders/receipt-create.php
  modified:
    - src/Modules/Orders/OrdersController.php
    - resources/views/orders/show.php
    - routes/web.php
    - resources/lang/pl.php
    - DOCS/ARCHITECTURE.md

key-decisions:
  - "ReceiptRepository w App\\Modules\\Accounting (nowy modul, nie w Settings)"
  - "Snapshot pattern: seller/buyer/items jako JSON w momencie wystawienia"
  - "Atomowe numerowanie: INSERT ON DUPLICATE KEY UPDATE na receipt_number_counters"
  - "total_net = total_gross (paragony nie rozdzielaja netto/brutto)"
  - "OrdersController rozszerzony o opcjonalne ?ReceiptRepository i ?ReceiptConfigRepository"

patterns-established:
  - "Modul Accounting: osobny namespace dla funkcjonalnosci ksiegowych"
  - "Snapshot przy tworzeniu dokumentu: dane zamrazane w JSON, niezalezne od przyszlych zmian zrodla"
  - "Activity log: recordActivity() po kazdej akcji generujacej dokument"

duration: ~25min
completed: 2026-03-15
---

# Phase 10 Plan 01: Wystawianie paragonow z zamowienia Summary

**Pelny flow wystawiania paragonow: przycisk w zamowieniu, formularz z podgladem pozycji/sprzedawcy, zapis z atomowym numerowaniem i snapshotami, lista w zakladce Dokumenty + wpis w historii.**

## Performance

| Metric | Value |
|--------|-------|
| Duration | ~25min |
| Completed | 2026-03-15 |
| Tasks | 3 auto + 1 checkpoint |
| Files created | 3 |
| Files modified | 5 |

## Acceptance Criteria Results

| Criterion | Status | Notes |
|-----------|--------|-------|
| AC-1: Przycisk "Wystaw paragon" w widoku zamowienia | Pass | Widoczny tylko gdy sa aktywne konfiguracje |
| AC-2: Formularz wystawiania paragonu | Pass | Select konfiguracji, tabela pozycji, podglad sprzedawcy, data wystawienia |
| AC-3: Zapis paragonu z atomowym numerowaniem | Pass | INSERT ON DUPLICATE KEY UPDATE, snapshoty JSON |
| AC-4: Lista paragonow w zakladce Dokumenty | Pass | Paragony + dokumenty zewnetrzne w osobnych sekcjach |
| AC-5: Walidacja — brak duplikatow i brak pustych konfiguracji | Pass | Przycisk ukryty bez konfiguracji, walidacja config_id |

## Accomplishments

- Nowy modul `App\Modules\Accounting` z ReceiptRepository i ReceiptController
- Atomowe numerowanie paragonow przez receipt_number_counters (INSERT ON DUPLICATE KEY UPDATE)
- Snapshoty seller/buyer/items jako JSON — dane zamrozone w momencie wystawienia
- Zakladka Dokumenty wyswietla zarowno paragony jak i dokumenty zewnetrzne z marketplace

## Files Created/Modified

| File | Change | Purpose |
|------|--------|---------|
| `src/Modules/Accounting/ReceiptRepository.php` | Created | CRUD na receipts + atomowe numerowanie |
| `src/Modules/Accounting/ReceiptController.php` | Created | Formularz tworzenia + zapis paragonu + activity log |
| `resources/views/orders/receipt-create.php` | Created | Widok formularza wystawiania paragonu |
| `src/Modules/Orders/OrdersController.php` | Modified | Dodano ?ReceiptRepository, ?ReceiptConfigRepository do konstruktora + show() |
| `resources/views/orders/show.php` | Modified | Przycisk "Wystaw paragon", zakladka Dokumenty z paragony + dokumenty zewnetrzne |
| `routes/web.php` | Modified | Instancje ReceiptRepository/ReceiptController, 2 nowe trasy |
| `resources/lang/pl.php` | Modified | Tlumaczenia receipts.create.*, receipts.documents.*, receipt_issued |
| `DOCS/ARCHITECTURE.md` | Modified | Klasy Accounting, przeplyw wystawiania paragonu |

## Deviations from Plan

### Summary

| Type | Count | Impact |
|------|-------|--------|
| Scope additions | 2 | User feedback — activity log + dokumenty zewnetrzne |

**Total impact:** Dwa uzasadnione rozszerzenia poza planem, poprawiajace UX.

### Scope Additions

**1. Activity log po wystawieniu paragonu**
- **Source:** User feedback podczas checkpoint
- **Issue:** Brak wpisu w historii zmian zamowienia po wystawieniu paragonu
- **Fix:** Dodano recordActivity() z typem `receipt_issued` + tlumaczenie
- **Files:** ReceiptController.php, resources/lang/pl.php

**2. Dokumenty zewnetrzne w zakladce Dokumenty**
- **Source:** User feedback — licznik Dokumenty(2) ale widoczny tylko 1 paragon
- **Issue:** Zakladka wyswietlala tylko paragony, nie dokumenty z order_documents
- **Fix:** Dodano sekcje "Dokumenty zewnetrzne" z tabela order_documents
- **Files:** resources/views/orders/show.php

## Issues Encountered

| Issue | Resolution |
|-------|------------|
| Duplikacja instancji ReceiptConfigRepository/ReceiptRepository w web.php | Przeniesiono tworzenie przed ordersController, usunieto duplikaty |

## Next Phase Readiness

**Ready:**
- ReceiptRepository::findById() gotowe pod podglad paragonu (faza 11)
- Snapshoty JSON (seller, buyer, items) gotowe do renderowania HTML/PDF
- receipt_number unikalne — gotowe do wyswietlania

**Concerns:**
- Brak

**Blockers:**
- Brak

---
*Phase: 10-receipt-issue, Plan: 01*
*Completed: 2026-03-15*