feat(08-10-receipt-module): phases 08-10 complete — receipt issuing from orders
Phase 08 — DB Foundation: - 3 new tables: receipt_configs, receipts, receipt_number_counters - company_settings extended with BDO, REGON, KRS, logo fields Phase 09 — Receipt Config: - CRUD for receipt configurations (Settings > Accounting) - ReceiptConfigController + ReceiptConfigRepository Phase 10 — Receipt Issuing: - ReceiptRepository with atomic numbering (INSERT ON DUPLICATE KEY UPDATE) - ReceiptController with snapshot pattern (seller/buyer/items as JSON) - "Wystaw paragon" button in order view - Documents tab showing both receipts and marketplace documents - Activity log entry on receipt creation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
203
.paul/phases/08-db-foundation/08-01-PLAN.md
Normal file
203
.paul/phases/08-db-foundation/08-01-PLAN.md
Normal file
@@ -0,0 +1,203 @@
|
||||
---
|
||||
phase: 08-db-foundation
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- database/migrations/20260315_000050_create_receipt_configs_table.sql
|
||||
- database/migrations/20260315_000051_create_receipts_table.sql
|
||||
- database/migrations/20260315_000052_create_receipt_number_counters_table.sql
|
||||
- database/migrations/20260315_000053_extend_company_settings_extra_fields.sql
|
||||
- src/Modules/Settings/CompanySettingsRepository.php
|
||||
- resources/views/settings/company.php
|
||||
- DOCS/DB_SCHEMA.md
|
||||
- DOCS/ARCHITECTURE.md
|
||||
autonomous: false
|
||||
---
|
||||
|
||||
<objective>
|
||||
## Goal
|
||||
Wdrożyć migracje bazodanowe dla modułu paragonów (receipt_configs, receipts, receipt_number_counters) oraz rozszerzyć company_settings o pola wymagane na paragonach (BDO, REGON, KRS, logo). Zaktualizować UI danych firmy o nowe pola.
|
||||
|
||||
## Purpose
|
||||
Fundament bazodanowy pod cały moduł paragonów — bez tych tabel nie można przejść do logiki konfiguracji ani wystawiania.
|
||||
|
||||
## Output
|
||||
- 4 pliki migracji SQL (już utworzone, do weryfikacji)
|
||||
- Rozszerzony formularz danych firmy o pola BDO, REGON, KRS, logo
|
||||
- Zaktualizowane DOCS/DB_SCHEMA.md i DOCS/ARCHITECTURE.md
|
||||
</objective>
|
||||
|
||||
<context>
|
||||
## Project Context
|
||||
@.paul/PROJECT.md
|
||||
@.paul/ROADMAP.md
|
||||
@.paul/STATE.md
|
||||
|
||||
## Source Files
|
||||
@database/migrations/20260315_000050_create_receipt_configs_table.sql
|
||||
@database/migrations/20260315_000051_create_receipts_table.sql
|
||||
@database/migrations/20260315_000052_create_receipt_number_counters_table.sql
|
||||
@database/migrations/20260315_000053_extend_company_settings_extra_fields.sql
|
||||
@src/Modules/Settings/CompanySettingsRepository.php
|
||||
@resources/views/settings/company.php
|
||||
@DOCS/DB_SCHEMA.md
|
||||
</context>
|
||||
|
||||
<skills>
|
||||
## Required Skills (from SPECIAL-FLOWS.md)
|
||||
|
||||
| Skill | Priority | When to Invoke | Loaded? |
|
||||
|-------|----------|----------------|---------|
|
||||
| sonar-scanner | required | Po APPLY, przed UNIFY | ○ |
|
||||
|
||||
No specialized flows configured for DB migrations.
|
||||
</skills>
|
||||
|
||||
<acceptance_criteria>
|
||||
|
||||
## AC-1: Tabele paragonów istnieją po migracji
|
||||
```gherkin
|
||||
Given baza danych jest dostępna i migrator działa
|
||||
When uruchomię migracje pending
|
||||
Then istnieją tabele receipt_configs, receipts, receipt_number_counters z poprawnymi kolumnami, indeksami i FK
|
||||
```
|
||||
|
||||
## AC-2: Company settings rozszerzony o nowe pola
|
||||
```gherkin
|
||||
Given tabela company_settings istnieje
|
||||
When uruchomię migrację 000053
|
||||
Then tabela ma kolumny bdo_number, regon, court_register, logo_path
|
||||
```
|
||||
|
||||
## AC-3: Formularz danych firmy wyświetla i zapisuje nowe pola
|
||||
```gherkin
|
||||
Given użytkownik jest na stronie /settings/company
|
||||
When wypełni pola BDO, REGON, KRS, logo i kliknie Zapisz
|
||||
Then dane są zapisane w company_settings i widoczne po odświeżeniu
|
||||
```
|
||||
|
||||
## AC-4: Dokumentacja zaktualizowana
|
||||
```gherkin
|
||||
Given migracje zostały wdrożone
|
||||
When przeglądam DOCS/DB_SCHEMA.md i DOCS/ARCHITECTURE.md
|
||||
Then widzę opisy nowych tabel receipt_configs, receipts, receipt_number_counters oraz nowych kolumn company_settings
|
||||
```
|
||||
|
||||
</acceptance_criteria>
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 1: Weryfikacja i wdrożenie migracji SQL</name>
|
||||
<files>
|
||||
database/migrations/20260315_000050_create_receipt_configs_table.sql,
|
||||
database/migrations/20260315_000051_create_receipts_table.sql,
|
||||
database/migrations/20260315_000052_create_receipt_number_counters_table.sql,
|
||||
database/migrations/20260315_000053_extend_company_settings_extra_fields.sql
|
||||
</files>
|
||||
<action>
|
||||
1. Przejrzeć 4 pliki migracji już utworzonych — zweryfikować poprawność SQL:
|
||||
- receipt_configs: pola name, is_active, number_format, numbering_type, is_named, sale_date_source, order_reference
|
||||
- receipts: FK do orders i receipt_configs, UNIQUE na receipt_number, indeksy, JSON kolumny
|
||||
- receipt_number_counters: UNIQUE na (config_id, year, month), FK do receipt_configs
|
||||
- company_settings: ADD COLUMN IF NOT EXISTS dla bdo_number, regon, court_register, logo_path
|
||||
2. Uruchomić migracje przez UI /settings/database lub bezpośrednio
|
||||
3. Zweryfikować struktury tabel po migracji
|
||||
</action>
|
||||
<verify>Sprawdzić SHOW CREATE TABLE dla receipt_configs, receipts, receipt_number_counters; SHOW COLUMNS FROM company_settings</verify>
|
||||
<done>AC-1 i AC-2 spełnione: tabele istnieją z poprawnymi kolumnami i kluczami</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Rozszerzenie formularza danych firmy o nowe pola</name>
|
||||
<files>
|
||||
src/Modules/Settings/CompanySettingsRepository.php,
|
||||
resources/views/settings/company.php
|
||||
</files>
|
||||
<action>
|
||||
1. W CompanySettingsRepository:
|
||||
- Dodać bdo_number, regon, court_register, logo_path do metody defaults()
|
||||
- Dodać te pola do saveSettings() (mapowanie z POST)
|
||||
- Dodać te pola do getSettings() jeśli nie zwracane automatycznie
|
||||
2. W resources/views/settings/company.php:
|
||||
- Dodać 4 nowe pola formularza (input text) w sekcji danych firmy:
|
||||
- Numer BDO (bdo_number) — varchar 20
|
||||
- REGON (regon) — varchar 14
|
||||
- KRS / Wpis do ewidencji (court_register) — varchar 128
|
||||
- Logo firmy (logo_path) — na razie pole tekstowe ze ścieżką (upload w przyszłości)
|
||||
- Zachować istniejący styl formularza
|
||||
3. Nie zmieniać kontrolera — CompanySettingsController::save() przekazuje wszystkie pola POST do repository
|
||||
</action>
|
||||
<verify>Odwiedzić /settings/company — zobaczyć nowe pola, wypełnić, zapisać, odświeżyć — dane zachowane</verify>
|
||||
<done>AC-3 spełnione: nowe pola widoczne i zapisywalne</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<what-built>Migracje DB dla modułu paragonów + rozszerzony formularz danych firmy</what-built>
|
||||
<how-to-verify>
|
||||
1. Wejdź na /settings/database — uruchom pending migracje
|
||||
2. Wejdź na /settings/company — sprawdź czy są nowe pola (BDO, REGON, KRS, Logo)
|
||||
3. Wypełnij nowe pola, zapisz, odśwież — dane powinny być zachowane
|
||||
4. Potwierdź że istniejące dane firmy nie zniknęły
|
||||
</how-to-verify>
|
||||
<resume-signal>Type "approved" to continue, or describe issues to fix</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Aktualizacja dokumentacji DB_SCHEMA.md i ARCHITECTURE.md</name>
|
||||
<files>DOCS/DB_SCHEMA.md, DOCS/ARCHITECTURE.md</files>
|
||||
<action>
|
||||
1. W DOCS/DB_SCHEMA.md dodać sekcje:
|
||||
- ### receipt_configs — z opisem kolumn, indeksów
|
||||
- ### receipts — z opisem kolumn, FK, indeksów
|
||||
- ### receipt_number_counters — z opisem kolumn, UNIQUE, FK
|
||||
- Zaktualizować sekcję company_settings o nowe kolumny
|
||||
- Dodać wpis chronologiczny w sekcji Status
|
||||
2. W DOCS/ARCHITECTURE.md:
|
||||
- Dodać moduł App\Modules\Accounting (przygotowanie)
|
||||
- Dodać informację o nowych tabelach w sekcji domen
|
||||
</action>
|
||||
<verify>Przejrzeć oba pliki — sprawdzić kompletność opisów nowych tabel</verify>
|
||||
<done>AC-4 spełnione: dokumentacja odzwierciedla nowy schemat</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<boundaries>
|
||||
|
||||
## DO NOT CHANGE
|
||||
- Istniejące tabele (orders, order_items, order_activity_log) — żadnych zmian
|
||||
- Istniejące kontrolery i widoki niezwiązane z company settings
|
||||
- Logika istniejących integracji (Allegro, shopPRO, Apaczka, InPost)
|
||||
|
||||
## SCOPE LIMITS
|
||||
- Nie tworzymy jeszcze kontrolera paragonów (Faza 09)
|
||||
- Nie tworzymy widoków konfiguracji paragonów (Faza 09)
|
||||
- Upload logo — na razie tylko pole tekstowe, upload w przyszłości
|
||||
- Nie dodajemy nawigacji do sekcji Księgowość (Faza 12)
|
||||
|
||||
</boundaries>
|
||||
|
||||
<verification>
|
||||
Before declaring plan complete:
|
||||
- [ ] 4 migracje wykonane bez błędów
|
||||
- [ ] Tabele receipt_configs, receipts, receipt_number_counters istnieją z poprawnymi strukturami
|
||||
- [ ] company_settings ma kolumny bdo_number, regon, court_register, logo_path
|
||||
- [ ] Formularz /settings/company wyświetla i zapisuje nowe pola
|
||||
- [ ] DOCS/DB_SCHEMA.md zaktualizowany
|
||||
- [ ] DOCS/ARCHITECTURE.md zaktualizowany
|
||||
- [ ] Istniejąca funkcjonalność danych firmy niezmieniona
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Wszystkie 4 migracje wykonane pomyślnie
|
||||
- Nowe pola w formularzu danych firmy działają (zapis + odczyt)
|
||||
- Dokumentacja kompletna
|
||||
- Brak regresji w istniejącej funkcjonalności
|
||||
</success_criteria>
|
||||
|
||||
<output>
|
||||
After completion, create `.paul/phases/08-db-foundation/08-01-SUMMARY.md`
|
||||
</output>
|
||||
131
.paul/phases/08-db-foundation/08-01-SUMMARY.md
Normal file
131
.paul/phases/08-db-foundation/08-01-SUMMARY.md
Normal file
@@ -0,0 +1,131 @@
|
||||
---
|
||||
phase: 08-db-foundation
|
||||
plan: 01
|
||||
subsystem: database
|
||||
tags: [mysql, migrations, receipts, company-settings]
|
||||
|
||||
requires: []
|
||||
provides:
|
||||
- receipt_configs table
|
||||
- receipts table
|
||||
- receipt_number_counters table
|
||||
- company_settings extended fields (bdo, regon, krs, logo)
|
||||
affects: [09-receipt-config, 10-receipt-issue, 11-receipt-print, 12-accounting-list]
|
||||
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns: [snapshot-json-pattern for receipts]
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- database/migrations/20260315_000050_create_receipt_configs_table.sql
|
||||
- database/migrations/20260315_000051_create_receipts_table.sql
|
||||
- database/migrations/20260315_000052_create_receipt_number_counters_table.sql
|
||||
- database/migrations/20260315_000053_extend_company_settings_extra_fields.sql
|
||||
modified:
|
||||
- src/Modules/Settings/CompanySettingsRepository.php
|
||||
- resources/views/settings/company.php
|
||||
- DOCS/DB_SCHEMA.md
|
||||
- DOCS/ARCHITECTURE.md
|
||||
|
||||
key-decisions:
|
||||
- "receipts.order_id as BIGINT UNSIGNED (match orders.id type)"
|
||||
- "receipts uses JSON snapshots for seller/buyer/items data"
|
||||
- "receipt_configs ON DELETE RESTRICT (nie usuwaj konfiguracji z istniejacymi paragonami)"
|
||||
|
||||
patterns-established:
|
||||
- "Snapshot pattern: dane sprzedawcy/nabywcy/pozycji zapisywane jako JSON w momencie wystawienia"
|
||||
|
||||
duration: ~15min
|
||||
completed: 2026-03-15
|
||||
---
|
||||
|
||||
# Phase 8 Plan 01: DB Foundation + Company Settings Summary
|
||||
|
||||
**Migracje bazodanowe dla modulu paragonow (3 nowe tabele) + rozszerzenie company_settings o BDO/REGON/KRS/logo.**
|
||||
|
||||
## Performance
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Duration | ~15min |
|
||||
| Completed | 2026-03-15 |
|
||||
| Tasks | 4 completed |
|
||||
| Files modified | 8 |
|
||||
|
||||
## Acceptance Criteria Results
|
||||
|
||||
| Criterion | Status | Notes |
|
||||
|-----------|--------|-------|
|
||||
| AC-1: Tabele paragonow istnieja po migracji | Pass | receipt_configs, receipts, receipt_number_counters utworzone |
|
||||
| AC-2: Company settings rozszerzony | Pass | bdo_number, regon, court_register, logo_path dodane |
|
||||
| AC-3: Formularz wyswietla i zapisuje nowe pola | Pass | Zweryfikowane manualnie przez uzytkownika |
|
||||
| AC-4: Dokumentacja zaktualizowana | Pass | DB_SCHEMA.md i ARCHITECTURE.md zaktualizowane |
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- 3 nowe tabele bazodanowe dla modulu paragonow (receipt_configs, receipts, receipt_number_counters)
|
||||
- Rozszerzenie company_settings o 4 pola wymagane na dokumentach ksiegowych
|
||||
- Formularz danych firmy zaktualizowany o nowe pola z pelnym zapisem/odczytem
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
| File | Change | Purpose |
|
||||
|------|--------|---------|
|
||||
| `database/migrations/20260315_000050_*.sql` | Created | Tabela receipt_configs |
|
||||
| `database/migrations/20260315_000051_*.sql` | Created | Tabela receipts |
|
||||
| `database/migrations/20260315_000052_*.sql` | Created | Tabela receipt_number_counters |
|
||||
| `database/migrations/20260315_000053_*.sql` | Created | Rozszerzenie company_settings |
|
||||
| `src/Modules/Settings/CompanySettingsRepository.php` | Modified | Dodano 4 nowe pola (get/save/defaults) |
|
||||
| `resources/views/settings/company.php` | Modified | Dodano pola REGON, BDO, KRS, Logo |
|
||||
| `DOCS/DB_SCHEMA.md` | Modified | Dokumentacja 3 nowych tabel + nowe kolumny |
|
||||
| `DOCS/ARCHITECTURE.md` | Modified | Dodano modul Accounting (w budowie) |
|
||||
|
||||
## Decisions Made
|
||||
|
||||
| Decision | Rationale | Impact |
|
||||
|----------|-----------|--------|
|
||||
| receipts.order_id BIGINT UNSIGNED | orders.id jest BIGINT UNSIGNED — FK musi sie zgadzac | Fix bledu errno 150 |
|
||||
| ON DELETE RESTRICT dla receipt_configs | Nie mozna usunac konfiguracji jesli istnieja paragony | Bezpieczenstwo danych |
|
||||
| Logo jako sciezka tekstowa | Upload w przyszlosci, na razie pole tekstowe | Uproszczenie fazy 08 |
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Summary
|
||||
|
||||
| Type | Count | Impact |
|
||||
|------|-------|--------|
|
||||
| Auto-fixed | 1 | Krytyczny fix typu FK |
|
||||
|
||||
**Total impact:** Jeden fix krytyczny, brak scope creep.
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. FK type mismatch receipts.order_id**
|
||||
- **Found during:** Task 1 (migracje)
|
||||
- **Issue:** receipts.order_id bylo INT UNSIGNED, orders.id jest BIGINT UNSIGNED
|
||||
- **Fix:** Zmieniono na BIGINT UNSIGNED
|
||||
- **Files:** database/migrations/20260315_000051_create_receipts_table.sql
|
||||
- **Verification:** Migracja wykonana pomyslnie po poprawce
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
| Issue | Resolution |
|
||||
|-------|------------|
|
||||
| errno 150 FK constraint | Poprawiono typ order_id z INT na BIGINT UNSIGNED |
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
**Ready:**
|
||||
- Tabele bazodanowe gotowe pod CRUD konfiguracji (faza 09)
|
||||
- Company settings kompletne pod snapshot danych sprzedawcy
|
||||
|
||||
**Concerns:**
|
||||
- Brak
|
||||
|
||||
**Blockers:**
|
||||
- Brak
|
||||
|
||||
---
|
||||
*Phase: 08-db-foundation, Plan: 01*
|
||||
*Completed: 2026-03-15*
|
||||
Reference in New Issue
Block a user