Jacek Pyziak
ed057fc304
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>
204 lines
8.1 KiB
Markdown
204 lines
8.1 KiB
Markdown
---
|
|
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>
|