PRD: ExSize 2.0 — To-Do/Reminders, PWA push, serwer MCP

[MrCrystal2]

PRD: ExSize 2.0

Problem Statement

ExSize działa dziś wyłącznie jako apka do obowiązków dla dzieci z nagrodami (exbucks / XP / avatar). To ogranicza użyteczność: dorośli w tej samej rodzinie nie mają własnego miejsca na zadania i przypomnienia i muszą używać osobnych apek (np. Apple Reminders). Poza tym ExSize nie rozmawia z żadnym AI — nie da się nim sterować z poziomu asystenta (Claude) ani agenta telefonicznego (SizeAgent).

Z perspektywy użytkownika: „Chcę jedną apkę, w której mam swoje przypomnienia jak w Apple Reminders oraz obowiązki i nagrody dla dzieci — i chcę móc nią sterować przez AI."

Solution

ExSize 2.0 staje się aplikacją dwufunkcyjną:

1. To-Do / Reminders (jak Apple Reminders) — dla każdego po zalogowaniu: listy, elementy, termin (data + godzina), cykliczność, przypomnienia push przez PWA.
2. Obowiązki + nagrody (istniejący system Task + exbucks/XP/avatar) — dla dzieci; dorosły ma tylko To-Do (+ zarządzanie rodziną, jeśli jest właścicielem). Rodzina jest opcjonalna — bez rodziny ExSize to po prostu To-Do.

Dodatkowo:

3. Serwer MCP (prod-only) — wystawia ExSize jako narzędzia dla AI (Claude / innych AI) przez istniejącą autoryzację tokenem API.
4. Wzmocnienie API — tylko tyle, ile potrzebują nowe funkcje (endpointy To-Do, pola due_date w Task, phone_number w User) + podstawowa spójność.
5. Dwa repozytoria publiczne: exsize (pełne) i exsize-oss (czysta edycja bez Cryplo + most krypto i bez MCP).
6. SizeAgent — głosowy agent do przeterminowanych zadań; osobny blok issues (patrz PRD SizeAgent). Nie część tego PRD.

User Stories

To-Do / Reminders (każdy po zalogowaniu)

1. Jako zalogowany użytkownik, chcę stworzyć listę To-Do, żeby grupować swoje zadania (np. „Zakupy", „Praca").
2. Jako zalogowany użytkownik, chcę dodać element z terminem (data + godzina), żeby wiedzieć, do kiedy zrobić.
3. Jako zalogowany użytkownik, chcę odhaczyć zrobiony element, żeby śledzić postęp.
4. Jako zalogowany użytkownik, chcę ustawić cykliczność (codziennie / co tydzień), żeby element powtarzał się sam.
5. Jako zalogowany użytkownik, chcę dostać powiadomienie push w terminie, żeby nie zapomnieć — nawet gdy apka jest zamknięta.
6. Jako zalogowany użytkownik, chcę zainstalować ExSize jako PWA, żeby używać go jak natywnej apki na telefonie/pulpicie.
7. Jako zalogowany użytkownik, chcę widzieć elementy nadchodzące i przeterminowane po wejściu w apkę, żeby wiedzieć, co pilne.
8. Jako zalogowany użytkownik, chcę edytować i usuwać elementy oraz listy, żeby utrzymać porządek.
9. Jako dorosły bez rodziny, chcę używać ExSize wyłącznie jako To-Do, bez zakładania rodziny.

Role i model użytkownika
10. Jako nowy użytkownik, chcę przy rejestracji wybrać, czy jestem rodzicem (członkiem), czy dzieckiem, żeby apka dopasowała funkcje.
11. Jako dziecko, chcę mieć To-Do oraz obowiązki z nagrodami (exbucks/XP/avatar).
12. Jako rodzic / członek, chcę mieć To-Do + zarządzać rodziną, ale bez nagród dla siebie.
13. Jako właściciel rodziny (admin), chcę dodawać członków i dzieci oraz przypisywać dzieciom obowiązki z nagrodą.

MCP / AI (prod-only)
14. Jako użytkownik z tokenem API, chcę podłączyć Claude (lub inne AI) do ExSize przez MCP, żeby sterować apką z poziomu asystenta.
15. Jako użytkownik, chcę poprosić AI „dodaj mleko do listy Zakupy", żeby nie wchodzić do apki.
16. Jako użytkownik, chcę zapytać AI o moje nadchodzące elementy To-Do i status obowiązków dziecka.
17. Jako użytkownik, chcę, żeby AI odczytało moje saldo exbucks / XP / poziom.
18. Jako użytkownik, chcę, żeby AI odczytało skład rodziny (członków, dzieci, role).

Powiadomienia push
19. Jako użytkownik, chcę raz zgodzić się na powiadomienia push, żeby potem dostawać przypomnienia automatycznie.
20. Jako użytkownik, chcę, żeby element cykliczny po terminie wygenerował następne wystąpienie i przypominał ponownie.
21. Jako użytkownik bez zgody na push, chcę nadal widzieć due/overdue elementy w aplikacji.

Repozytoria / OSS
22. Jako opiekun projektu, chcę mieć publiczne exsize (pełne) i exsize-oss (czyste), żeby oddzielić kod regulowany (krypto) i integrację prod-only (MCP) od edycji społecznościowej.
23. Jako opiekun projektu, chcę jasnego procesu synchronizacji zmian z exsize do exsize-oss.

Implementation Decisions

• Stack (korekta — CLAUDE.md jest nieaktualny): backend = FastAPI + SQLAlchemy + uvicorn; frontend = React + Vite + TypeScript + Tailwind + vite-plugin-pwa; DB = SQLite lokalnie / Neon Postgres prod. Istnieje już infrastruktura tokenów API (do autoryzacji MCP).
• Nowe moduły (głębokie):
  • TodoService — listy, elementy, terminy, cykliczność, odhaczanie. Wąski interfejs, ukrywa logikę rozwijania cykliczności i liczenia „due".
  • ReminderService (push) — subskrypcja push, wysyłka, scheduler due. Ukrywa VAPID i protokół web-push.
• Serwer MCP = cienka warstwa adapterów nad TodoService / chores / gamifikacja / rodzina; prod-only; autoryzacja tokenem API. Płytka z założenia (granica integracji).
• Baza danych: phone_number w User, due_date w Task, nowe tabele todo_lists, todo_items, push_subscriptions. Po zmianie schematu: usunąć exsize.db lokalnie / wykonać migrację na Neon.
• Powiadomienia: web push (VAPID); scheduler okresowo sprawdza due elementy i wysyła push do subskrypcji; cykliczność generuje następne wystąpienie po terminie.
• Repozytoria: exsize publiczne (pełne); exsize-oss publiczne, czyste (bez Cryplo + mostu, bez MCP); sync ręczny.
• Wzmocnienie API: ograniczone do tego, co wymagają nowe funkcje (endpointy To-Do CRUD, due_date, phone_number) + podstawowa spójność. Hardening (rate limiting, paginacja) — poza zakresem na ten PRD.

Validation Strategy

To-Do (TodoService)

• Stworzenie listy → dodanie elementu z terminem → odhaczenie działa end-to-end (test automatyczny + weryfikacja ręczna w UI).
• Cykliczność: po upływie terminu element tworzy następne wystąpienie z poprawnym kolejnym terminem (test jednostkowy reguł).
• list_due_before(dt) zwraca dokładnie elementy z terminem ≤ dt (test jednostkowy).

Przypomnienia / push (ReminderService)

• Użytkownik subskrybuje push (zgoda przeglądarki) i otrzymuje powiadomienie przy due item (test integracyjny + ręcznie na prawdziwej przeglądarce).
• Scheduler wykrywa due element i wysyła push do zapisanej subskrypcji.
• Brak subskrypcji / odmowa zgody nie wywala usługi (graceful, test błędu).

Serwer MCP

• Klient MCP (np. Claude Desktop) z ważnym tokenem API widzi narzędzia z zakresów: To-Do, chores, gamifikacja (odczyt), rodzina (odczyt).
• „Dodaj element To-Do przez AI" tworzy element widoczny w aplikacji (test end-to-end przez MCP).
• Bez ważnego tokenu — odmowa dostępu (test autoryzacji).

Out of Scope

• Nowa gamifikacja (nowe XP / streaks / badge) — istniejący system bez zmian.
• Podzadania (subtasks) i priorytety w To-Do — na start bez nich.
• Lokacyjne przypomnienia (geo, jak Apple Reminders).
• Hardening API (rate limiting, paginacja, pełna walidacja) — poza tym PRD.
• Automatyczne wykrywanie „przeterminowane" + scheduler telefonów — własność SizeAgent (osobny PRD), nie ExSize 2.0.
• Automatyczna synchronizacja exsize ↔ exsize-oss — sync ręczny.

Further Notes

• Repo exsize jest PUBLICZNE mimo wcześniejszego planu „prywatne". Relacja z exsize-oss (czy w ogóle potrzebne osobne czyste repo, skoro pełny kod jest już publiczny?) — otwarte pytanie do rozstrzygnięcia.
• Bezpieczeństwo: kod jest publiczny, więc SECRET_KEY na Render musi być losową wartością (w kodzie jest słaby fallback dev-secret-key-change-in-production). Dodać .env.example. ADMIN_SECRET jest bezpieczny z założenia (brak zmiennej = brak dostępu).
• CLAUDE.md do aktualizacji: Flask → FastAPI, „vanilla JS SPA" → React/Vite/TS.
• Planowanie po datach, nie godzinach.