236 lines
14 KiB
Markdown
236 lines
14 KiB
Markdown
---
|
||
plan_id: 20260706-1248-fundament-wydatki-przychody
|
||
title: Fundament finansePRO + moduł wydatków/przychodów bieżących
|
||
storage: plan-first
|
||
legacy_phase: null
|
||
created: 2026-07-06T12:48:27+02:00
|
||
status: planned
|
||
type: execute
|
||
autonomous: false
|
||
delegation: auto
|
||
files_modified:
|
||
- composer.json
|
||
- .env
|
||
- app/Config/Database.php
|
||
- app/Config/Routes.php
|
||
- app/Config/Filters.php
|
||
- app/Filters/AuthFilter.php
|
||
- app/Controllers/BaseController.php
|
||
- app/Controllers/Auth.php
|
||
- app/Controllers/Categories.php
|
||
- app/Controllers/Operations.php
|
||
- app/Controllers/Dashboard.php
|
||
- app/Models/CategoryModel.php
|
||
- app/Models/OperationModel.php
|
||
- app/Database/Migrations/*_create_categories.php
|
||
- app/Database/Migrations/*_create_operations.php
|
||
- app/Database/Seeds/DefaultCategoriesSeeder.php
|
||
- app/Views/layout/main.php
|
||
- app/Views/auth/login.php
|
||
- app/Views/categories/*
|
||
- app/Views/operations/*
|
||
- app/Views/dashboard/index.php
|
||
quality_radar: degraded
|
||
---
|
||
|
||
<objective>
|
||
## Cel
|
||
Postawić fundament aplikacji finansePRO na CodeIgniter 4 (MySQL z `.env`), logowanie jednego użytkownika oraz kompletny moduł finansów bieżących: kategorie (hierarchiczne, typ przychód/wydatek), operacje (CRUD + filtry) i dashboard z wykresami ApexCharts.
|
||
|
||
## Po co
|
||
To pierwsza, uruchamialna wersja narzędzia do analizy finansów osobistych. Daje działający szkielet (auth + DB + layout), na którym Plan 2 dołoży moduł inwestycji. Wzorzec domenowy (kategorie/operacje) świadomie czerpie z modułu finansów crmPRO, ale kod pisany jest od zera w CI4 — bez przenoszenia frameworka crmPRO.
|
||
|
||
## Wynik
|
||
Działająca aplikacja CI4: logowanie → dashboard z wykresami → zarządzanie kategoriami i operacjami. Migracje tworzą schemat, seeder wrzuca startowe kategorie.
|
||
</objective>
|
||
|
||
<context>
|
||
## Dokumenty projektu
|
||
@.paul/PROJECT.md
|
||
@.paul/STATE.md
|
||
@.paul/config.md
|
||
@.paul/codebase/impact_map.md
|
||
@.paul/codebase/quality_risks.md
|
||
|
||
## Referencja (NIE modyfikować — tylko wzorzec domenowy)
|
||
@C:/visual-studio-code/crmPRO/autoload/Domain/Finances/FinanceRepository.php
|
||
@C:/visual-studio-code/crmPRO/templates/finances/main-view.php
|
||
@C:/visual-studio-code/crmPRO/templates/finances/operations-list.php
|
||
|
||
## Konfiguracja środowiska
|
||
@.env
|
||
</context>
|
||
|
||
<clarifications>
|
||
- Stack: **CodeIgniter 4** (użytkownik zna go z innej aplikacji, wdrożenie na hostido OK).
|
||
- Logowanie: **jeden użytkownik wprost z `.env`** (`user_email` + `user_password`), bez tabeli users, bez rejestracji, bez remember-tokenów.
|
||
- Zakres tego planu: **fundament + moduł bieżących wydatków/przychodów**. Moduł inwestycji to osobny Plan 2 (ręczne snapshoty wartości).
|
||
- Kategorie: hierarchiczne (`parent_id`), z typem przychód/wydatek — wzorzec jak `finance_categories` w crmPRO.
|
||
- Wykresy: **ApexCharts** (znane z crmPRO).
|
||
- Hasło w `.env` jest jawne — logowanie porównuje wprost (narzędzie jednoosobowe). Podniesienie do hasha zostawione jako możliwa późniejsza zmiana.
|
||
</clarifications>
|
||
|
||
<impact_scan>
|
||
## Quality Radar
|
||
|
||
**Status:** degraded (finansePRO to greenfield — brak kodu do skanowania; codebase-memory-mcp nie ma czego indeksować)
|
||
**Tools:** codebase-memory-mcp (brak indeksu — projekt pusty); jscpd/ast-grep wyłączone polityką
|
||
|
||
## Obszary objęte planem
|
||
- fundament CI4 — `app/Config/*`, `composer.json`, bootstrap
|
||
- auth (jeden user z .env) — `app/Filters/AuthFilter.php`, `app/Controllers/Auth.php`
|
||
- domena finansów bieżących — `app/Models/{Category,Operation}Model.php`, `app/Controllers/{Categories,Operations,Dashboard}.php`, migracje, widoki
|
||
- config DB — `app/Config/Database.php` czyta klucze z istniejącego `.env`
|
||
|
||
## Ryzyka duplikacji / hardcode
|
||
- **Drugie źródło prawdy dla configu DB** — istniejący `.env` używa własnych kluczy (`db_host`, `db_user`, `db_name`, `db_password`), NIE standardowych CI4 (`database.default.*`). Obsłużone w Task 1: `Database.php` czyta te klucze przez `env('db_host')` itd., bez dublowania wartości i bez zmiany `.env`.
|
||
- **Typ operacji (przychód/wydatek)** — nie utrwalać go w dwóch miejscach niespójnie. Obsłużone w Task 2: `type` jest kolumną enum na kategorii i na operacji; walidacja spójności w `OperationModel`.
|
||
- **Wzorzec z crmPRO** — czerpiemy schemat domenowy, ale nie kopiujemy kodu 1:1 (inny framework). Brak ryzyka copy-paste między repo.
|
||
|
||
## Świadome odroczenia
|
||
- Hashowanie hasła użytkownika — odroczone (jawne `.env`, narzędzie jednoosobowe).
|
||
- Pełny skan radaru (codebase-memory-mcp index) — po zbudowaniu kodu, w `$paul-apply`/`$paul-map-codebase`.
|
||
- Moduł inwestycji — Plan 2.
|
||
</impact_scan>
|
||
|
||
<skills>
|
||
Brak SPECIAL-FLOWS.md — sekcja skills pominięta.
|
||
</skills>
|
||
|
||
<acceptance_criteria>
|
||
|
||
## AC-1: Aplikacja startuje i łączy się z bazą z .env
|
||
```gherkin
|
||
Given świeżo zainstalowany CodeIgniter 4 z konfiguracją z .env
|
||
When uruchomię `php spark serve` i otworzę stronę główną
|
||
Then aplikacja ładuje się bez błędu połączenia z MySQL, używając db_host/db_user/db_name/db_password z .env
|
||
```
|
||
|
||
## AC-2: Logowanie jednego użytkownika z .env
|
||
```gherkin
|
||
Given niezalogowany użytkownik wchodzi na dowolną chronioną trasę
|
||
When zostaje przekierowany na /login i poda email oraz hasło zgodne z user_email/user_password z .env
|
||
Then zostaje zalogowany (sesja) i przekierowany na dashboard; błędne dane pokazują komunikat, a /logout kończy sesję
|
||
```
|
||
|
||
## AC-3: Zarządzanie kategoriami (hierarchia + typ)
|
||
```gherkin
|
||
Given zalogowany użytkownik w widoku kategorii
|
||
When doda/edytuje/usunie kategorię z nazwą, typem (przychód/wydatek) i opcjonalnym rodzicem
|
||
Then kategoria zapisuje się w tabeli categories, respektuje parent_id, a usunięcie kategorii z operacjami jest zablokowane lub przenosi operacje zgodnie z regułą (patrz Task 3)
|
||
```
|
||
|
||
## AC-4: CRUD operacji z filtrami
|
||
```gherkin
|
||
Given zalogowany użytkownik w widoku operacji
|
||
When doda operację (data, kwota, typ, kategoria, opis) i użyje filtra po zakresie dat oraz kategorii
|
||
Then operacja zapisuje się w tabeli operations, lista pokazuje przefiltrowane wyniki i sumy (przychody, wydatki, saldo)
|
||
```
|
||
|
||
## AC-5: Dashboard z wykresami
|
||
```gherkin
|
||
Given istnieją operacje w bazie
|
||
When otworzę dashboard
|
||
Then widzę wykresy ApexCharts: (a) bilans miesięczny przychody vs wydatki, (b) wydatki wg kategorii (donut), (c) saldo skumulowane w czasie — z danymi zgodnymi z operacjami
|
||
```
|
||
|
||
</acceptance_criteria>
|
||
|
||
<tasks>
|
||
|
||
<task type="auto">
|
||
<name>Task 1: Bootstrap CI4 + konfiguracja DB z .env + logowanie jednego użytkownika</name>
|
||
<files>composer.json, app/Config/Database.php, app/Config/Routes.php, app/Config/Filters.php, app/Filters/AuthFilter.php, app/Controllers/Auth.php, app/Views/auth/login.php, app/Views/layout/main.php</files>
|
||
<action>
|
||
- Zainstalować szkielet CodeIgniter 4 (`composer create-project codeigniter4/appstarter` lub równoważnie) w katalogu projektu, zachowując istniejący `.env`, `.paul/`, `.claude/`, `.vscode/`.
|
||
- W `app/Config/Database.php` ustawić `default` z istniejących kluczy .env: `hostname = env('db_host')`, `username = env('db_user')`, `database = env('db_name')`, `password = env('db_password')`, `DBDriver = 'MySQLi'`, `charset = 'utf8mb4'`. NIE dodawać nowych kluczy do `.env` (żeby nie tworzyć drugiego źródła prawdy). Zdalny host `db_host_remote` zostawić jako komentarz/opcję na wdrożenie.
|
||
- Utworzyć `AuthFilter` sprawdzający `session()->get('logged_in')`; niezalogowanych przekierowuje na `/login`. Zarejestrować w `Filters.php` jako alias `auth` i nałożyć na grupę tras chronionych w `Routes.php`.
|
||
- `Auth` controller: `login` (GET formularz, POST weryfikacja wobec `env('user_email')`/`env('user_password')` — porównanie wprost; // ponytail: jawne haslo z .env, podniesc do password_hash jesli pojawi sie wiecej userow), `logout` (czyści sesję).
|
||
- `app/Views/layout/main.php`: wspólny layout Bootstrap + miejsce na treść + nawigacja (Dashboard, Operacje, Kategorie, Wyloguj). ApexCharts i Bootstrap wpiąć (CDN lub `public/`).
|
||
- Trasa domyślna `/` → redirect na dashboard (gdy zalogowany) lub `/login`.
|
||
</action>
|
||
<verify>`php spark serve`, wejście na chronioną trasę przekierowuje na /login; poprawne dane z .env logują i przekierowują na dashboard; złe dane = komunikat; /logout wylogowuje. Brak błędu połączenia z DB.</verify>
|
||
<done>AC-1, AC-2</done>
|
||
</task>
|
||
|
||
<task type="auto">
|
||
<name>Task 2: Schemat DB (migracje) + modele + seeder kategorii</name>
|
||
<files>app/Database/Migrations/*_create_categories.php, app/Database/Migrations/*_create_operations.php, app/Models/CategoryModel.php, app/Models/OperationModel.php, app/Database/Seeds/DefaultCategoriesSeeder.php</files>
|
||
<action>
|
||
- Migracja `categories`: `id` PK, `name` VARCHAR, `type` ENUM('income','expense'), `parent_id` INT NULL (FK self, ON DELETE SET NULL), `created_at`/`updated_at`. Indeks na `parent_id`, `type`.
|
||
- Migracja `operations`: `id` PK, `date` DATE, `amount` DECIMAL(12,2) (dodatnia), `type` ENUM('income','expense'), `category_id` INT NULL (FK categories, ON DELETE SET NULL), `description` VARCHAR NULL, `created_at`/`updated_at`. Indeksy na `date`, `category_id`, `type`.
|
||
- `CategoryModel`: allowedFields, walidacja (name wymagane, type in income/expense, parent_id istnieje lub null), metoda `flatList()`/`treeList()` i `usedByOperations($id)`.
|
||
- `OperationModel`: allowedFields, walidacja (date, amount > 0, type in income/expense, category_id istnieje lub null); reguła spójności: `type` operacji musi zgadzać się z `type` wybranej kategorii (jedno źródło prawdy — kategoria narzuca typ). Metody agregujące dla dashboardu: `monthlyBalance($from,$to)`, `byCategory($from,$to,$type)`, `runningBalance($from,$to)`.
|
||
- `DefaultCategoriesSeeder`: kilka startowych kategorii przychodów (np. Wynagrodzenie, Inne przychody) i wydatków (np. Jedzenie, Mieszkanie, Transport, Rozrywka).
|
||
</action>
|
||
<verify>`php spark migrate` tworzy tabele bez błędów; `php spark db:seed DefaultCategoriesSeeder` wstawia kategorie; szybki tinker/SQL potwierdza strukturę i FK.</verify>
|
||
<done>AC-3 (schemat), AC-4 (schemat), AC-5 (agregacje)</done>
|
||
</task>
|
||
|
||
<task type="auto">
|
||
<name>Task 3: Moduł kategorii i operacji (CRUD + filtry + sumy)</name>
|
||
<files>app/Controllers/Categories.php, app/Controllers/Operations.php, app/Controllers/BaseController.php, app/Views/categories/*, app/Views/operations/*, app/Config/Routes.php</files>
|
||
<action>
|
||
- `Categories` controller + widoki: lista (drzewko/płaska z wcięciem wg parent_id), formularz dodaj/edytuj (name, type, parent_id), usuwanie. Usunięcie kategorii używanej przez operacje: zablokować z komunikatem LUB pozwolić (operacje przechodzą na category_id=NULL dzięki FK) — wybrać blokadę z jasnym komunikatem dla bezpieczeństwa danych.
|
||
- `Operations` controller + widoki: lista z filtrami (zakres dat — datepicker/`<input type=date>`, kategoria, typ), formularz dodaj/edytuj (date, amount, type auto z kategorii, category_id, description), usuwanie. Wybór kategorii ustawia typ operacji (spójność jak w Task 2). Lista pokazuje sumy: przychody, wydatki, saldo dla aktualnego filtra.
|
||
- Trasy CRUD w `Routes.php` w grupie chronionej filtrem `auth`.
|
||
- Walidacja po stronie serwera przez modele; komunikaty błędów w widokach.
|
||
</action>
|
||
<verify>Ręcznie: dodać/edytować/usunąć kategorię i operację; filtr po dacie i kategorii zawęża listę; sumy się zgadzają; próba usunięcia używanej kategorii jest zablokowana z komunikatem.</verify>
|
||
<done>AC-3, AC-4</done>
|
||
</task>
|
||
|
||
<task type="auto">
|
||
<name>Task 4: Dashboard z wykresami ApexCharts</name>
|
||
<files>app/Controllers/Dashboard.php, app/Views/dashboard/index.php, app/Config/Routes.php</files>
|
||
<action>
|
||
- `Dashboard` controller: pobiera z `OperationModel` dane dla domyślnego zakresu (np. bieżący rok) i oddaje do widoku jako JSON dla ApexCharts. Opcjonalny filtr zakresu dat u góry dashboardu.
|
||
- Wykresy ApexCharts w `dashboard/index.php`:
|
||
(a) bilans miesięczny — słupki przychody vs wydatki per miesiąc,
|
||
(b) wydatki wg kategorii — donut (tylko type=expense),
|
||
(c) saldo skumulowane w czasie — linia (cumsum operacji: +przychód, −wydatek).
|
||
- Kafelki podsumowania: suma przychodów, suma wydatków, saldo dla wybranego zakresu.
|
||
- Trasa `/dashboard` (i `/`) w grupie chronionej.
|
||
</action>
|
||
<verify>Ręcznie: po dodaniu operacji dashboard pokazuje trzy wykresy z poprawnymi danymi; zmiana zakresu dat aktualizuje wykresy i kafelki.</verify>
|
||
<done>AC-5</done>
|
||
</task>
|
||
|
||
</tasks>
|
||
|
||
<boundaries>
|
||
## Nie zmieniać
|
||
- `.env` — czytamy istniejące klucze, nie dodajemy nowych ani nie zmieniamy wartości.
|
||
- `.paul/`, `.claude/`, `.vscode/` — infrastruktura projektu.
|
||
- Repozytorium crmPRO (`C:/visual-studio-code/crmPRO/`) — wyłącznie referencja wzorca, zero modyfikacji.
|
||
|
||
## Poza zakresem
|
||
- Moduł inwestycji (operacje inwestycyjne, wyceny, wykres wpłaty vs zarobek) — Plan 2.
|
||
- Tabela users, rejestracja, reset hasła, wielu użytkowników.
|
||
- Import z Fakturownia / integracje zewnętrzne (były w crmPRO, tu niepotrzebne).
|
||
- Hashowanie hasła, 2FA, remember-me.
|
||
- Wdrożenie produkcyjne na hostido (osobny krok po akceptacji lokalnej).
|
||
</boundaries>
|
||
|
||
<verification>
|
||
- [ ] `php spark serve` startuje, `/` przekierowuje wg stanu logowania.
|
||
- [ ] Logowanie wobec `.env` działa (poprawne/błędne dane, logout).
|
||
- [ ] `php spark migrate` i seeder wykonują się bez błędów.
|
||
- [ ] CRUD kategorii i operacji działa, filtry i sumy poprawne.
|
||
- [ ] Dashboard renderuje 3 wykresy ApexCharts z danymi zgodnymi z operacjami.
|
||
- [ ] Config DB czyta wyłącznie z `.env` (brak drugiego źródła prawdy).
|
||
- [ ] Typ operacji spójny z typem kategorii (jedno źródło prawdy).
|
||
- [ ] Quality Radar: ryzyka z `<impact_scan>` obsłużone lub odroczone świadomie.
|
||
</verification>
|
||
|
||
<success_criteria>
|
||
- [ ] Wszystkie AC (AC-1..AC-5) przechodzą.
|
||
- [ ] Weryfikacja kompletna.
|
||
- [ ] Radar/impact_map zaktualizowane po zbudowaniu kodu (w `$paul-apply`).
|
||
- [ ] Fundament gotowy pod Plan 2 (inwestycje).
|
||
</success_criteria>
|
||
|
||
<output>
|
||
SUMMARY.md path: `.paul/plans/20260706-1248-fundament-wydatki-przychody/SUMMARY.md`
|
||
</output>
|