From 1407b49ba1a6bee26026beffba4302d8849b0d94 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Dec 2025 14:33:09 +0000 Subject: [PATCH 1/2] docs: Add .claude/ AI context files for faster development Add structured context files to speed up AI-assisted development: - FILE-MAP.md: Index of pages, providers, repositories, widgets - TABLES.md: Condensed Drift schema reference - PATTERNS.md: Clean Architecture + Riverpod code patterns - PROMPTS.md: Ready-to-use prompt templates for common tasks --- .claude/FILE-MAP.md | 165 ++++++++++++++++++++++ .claude/PATTERNS.md | 333 ++++++++++++++++++++++++++++++++++++++++++++ .claude/PROMPTS.md | 246 ++++++++++++++++++++++++++++++++ .claude/TABLES.md | 118 ++++++++++++++++ 4 files changed, 862 insertions(+) create mode 100644 .claude/FILE-MAP.md create mode 100644 .claude/PATTERNS.md create mode 100644 .claude/PROMPTS.md create mode 100644 .claude/TABLES.md diff --git a/.claude/FILE-MAP.md b/.claude/FILE-MAP.md new file mode 100644 index 0000000..a2188f8 --- /dev/null +++ b/.claude/FILE-MAP.md @@ -0,0 +1,165 @@ +# FILE-MAP - Index plików projektu + +> Szybki dostęp do lokalizacji kodu. Zamiast Glob/Read - sprawdź tutaj. + +--- + +## Pages (Screens) + +| Page | Ścieżka | Opis | +|------|---------|------| +| **Auth** | | | +| LoginPage | `lib/core/auth/presentation/pages/login_page.dart` | Email/password + OAuth | +| RegisterPage | `lib/core/auth/presentation/pages/register_page.dart` | Rejestracja | +| ForgotPasswordPage | `lib/core/auth/presentation/pages/forgot_password_page.dart` | Reset hasła | +| ResetPasswordPage | `lib/core/auth/presentation/pages/reset_password_page.dart` | Nowe hasło | +| **Profile** | | | +| ProfileEditPage | `lib/core/profile/presentation/pages/profile_edit_page.dart` | Edycja profilu | +| **Fitness** | | | +| WorkoutLogPage | `lib/features/fitness/presentation/pages/workout_log_page.dart` | Lista treningów | +| WorkoutLoggingPage | `lib/features/fitness/presentation/pages/workout_logging_page.dart` | Logowanie treningu | +| QuickLogPage | `lib/features/fitness/presentation/pages/quick_log_page.dart` | Szybkie logowanie | +| TemplatesPage | `lib/features/fitness/presentation/pages/templates_page.dart` | Szablony treningów | +| MeasurementsPage | `lib/features/fitness/presentation/pages/measurements_page.dart` | Pomiary ciała | +| ProgressChartsPage | `lib/features/fitness/presentation/pages/progress_charts_page.dart` | Wykresy postępu | +| **Life Coach** | | | +| DailyPlanPage | `lib/features/life_coach/presentation/pages/daily_plan_page.dart` | Plan dnia | +| DailyPlanEditPage | `lib/features/life_coach/presentation/pages/daily_plan_edit_page.dart` | Edycja planu | +| MorningCheckInPage | `lib/features/life_coach/presentation/pages/morning_check_in_page.dart` | Poranny check-in | +| EveningReflectionPage | `lib/features/life_coach/presentation/pages/evening_reflection_page.dart` | Wieczorna refleksja | +| GoalsListPage | `lib/features/life_coach/presentation/pages/goals_list_page.dart` | Lista celów | +| CreateGoalPage | `lib/features/life_coach/presentation/pages/create_goal_page.dart` | Tworzenie celu | +| GoalSuggestionsPage | `lib/features/life_coach/goals/presentation/pages/goal_suggestions_page.dart` | Sugestie AI | +| CoachChatPage | `lib/features/life_coach/chat/presentation/pages/coach_chat_page.dart` | Chat z AI | +| ProgressDashboardPage | `lib/features/life_coach/presentation/pages/progress_dashboard_page.dart` | Dashboard postępu | +| **Mind** | | | +| MeditationLibraryScreen | `lib/features/mind_emotion/presentation/screens/meditation_library_screen.dart` | Biblioteka medytacji | +| **Exercise** | | | +| ExerciseDetailScreen | `lib/features/exercise/presentation/pages/exercise_detail_screen.dart` | Szczegóły ćwiczenia | +| CreateCustomExerciseScreen | `lib/features/exercise/presentation/pages/create_custom_exercise_screen.dart` | Tworzenie ćwiczenia | +| **Settings** | | | +| DataPrivacyPage | `lib/features/settings/presentation/pages/data_privacy_page.dart` | Prywatność danych | + +--- + +## Providers (State Management) + +| Provider | Ścieżka | Opis | +|----------|---------|------| +| **Auth** | | | +| authProvider | `lib/core/auth/presentation/providers/auth_provider.dart` | Stan auth | +| authNotifier | `lib/core/auth/presentation/providers/auth_notifier.dart` | Logika auth | +| **Profile** | | | +| profileProvider | `lib/core/profile/presentation/providers/profile_provider.dart` | Stan profilu | +| **AI** | | | +| aiProvider | `lib/core/ai/ai_provider.dart` | OpenAI service provider | +| **Fitness** | | | +| workoutProviders | `lib/features/fitness/presentation/providers/` | Folder z providerami | +| **Life Coach** | | | +| dailyPlanProvider | `lib/features/life_coach/ai/providers/daily_plan_provider.dart` | Plan dnia AI | +| checkInProviders | `lib/features/life_coach/presentation/providers/` | Check-in providers | +| goalProviders | `lib/features/life_coach/goals/presentation/providers/` | Goal providers | +| chatProviders | `lib/features/life_coach/chat/presentation/providers/` | Chat providers | +| **Mind** | | | +| meditationProviders | `lib/features/mind_emotion/presentation/providers/meditation_providers.dart` | Medytacje | +| **Sync** | | | +| connectivityProvider | `lib/core/sync/providers/connectivity_provider.dart` | Status połączenia | +| syncStatusProvider | `lib/core/sync/providers/sync_status_provider.dart` | Status synchronizacji | + +--- + +## Repositories + +| Repository | Interface | Implementation | +|------------|-----------|----------------| +| **Auth** | | | +| AuthRepository | `lib/core/auth/domain/repositories/auth_repository.dart` | `lib/core/auth/data/repositories/auth_repository_impl.dart` | +| SessionRepository | `lib/core/auth/domain/repositories/session_repository.dart` | `lib/core/auth/data/repositories/session_repository_impl.dart` | +| **Profile** | | | +| ProfileRepository | `lib/core/profile/domain/repositories/profile_repository.dart` | `lib/core/profile/data/repositories/profile_repository_impl.dart` | +| **Mind** | | | +| MeditationRepository | `lib/features/mind_emotion/domain/repositories/meditation_repository.dart` | `lib/features/mind_emotion/data/repositories/meditation_repository_impl.dart` | + +--- + +## Use Cases + +| UseCase | Ścieżka | +|---------|---------| +| **Auth** | `lib/core/auth/domain/usecases/` | +| LoginWithEmailUsecase | `login_with_email_usecase.dart` | +| RegisterUserUsecase | `register_user_usecase.dart` | +| LoginWithGoogleUsecase | `login_with_google_usecase.dart` | +| LoginWithAppleUsecase | `login_with_apple_usecase.dart` | +| RequestPasswordResetUsecase | `request_password_reset_usecase.dart` | +| UpdatePasswordUsecase | `update_password_usecase.dart` | +| LogoutUsecase | `logout_usecase.dart` | +| CheckAuthStatusUsecase | `check_auth_status_usecase.dart` | +| **Profile** | `lib/core/profile/domain/usecases/` | +| UpdateProfileUsecase | `update_profile_usecase.dart` | +| UploadAvatarUsecase | `upload_avatar_usecase.dart` | +| ChangePasswordUsecase | `change_password_usecase.dart` | +| **Mind** | `lib/features/mind_emotion/domain/usecases/` | +| GetMeditationsUsecase | `get_meditations_usecase.dart` | +| ToggleFavoriteUsecase | `toggle_favorite_usecase.dart` | +| DownloadMeditationUsecase | `download_meditation_usecase.dart` | + +--- + +## Database + +| Plik | Opis | +|------|------| +| `lib/core/database/database.dart` | Główna klasa AppDatabase | +| `lib/core/database/database_providers.dart` | Riverpod providers dla DB | +| `lib/core/database/tables.drift.dart` | Wygenerowany kod Drift | +| **Tables** | | +| `lib/core/database/tables/sprint0_tables.dart` | WorkoutTemplates, Subscriptions, Streaks, AiConversations, MoodLogs, UserDailyMetrics, MentalHealthScreenings | +| `lib/core/database/tables/batch1_tables.dart` | CheckIns, WorkoutLogs, ExerciseSets | +| `lib/core/database/tables/batch3_tables.dart` | Goals, GoalProgress, BodyMeasurements | +| `lib/core/database/tables/life_coach_tables.dart` | DailyPlans, ChatSessions | + +--- + +## Core Services + +| Service | Ścieżka | Opis | +|---------|---------|------| +| AIService | `lib/core/ai/ai_service.dart` | OpenAI integration | +| AIConfig | `lib/core/ai/ai_config.dart` | API key, model config | +| OpenAIProvider | `lib/core/ai/providers/openai_provider.dart` | HTTP calls to OpenAI | +| SyncService | `lib/core/sync/sync_service.dart` | Background sync logic | +| SyncQueue | `lib/core/sync/sync_queue.dart` | Offline queue | +| ConflictResolver | `lib/core/sync/conflict_resolver.dart` | Last-write-wins | +| AppRouter | `lib/core/router/app_router.dart` | GoRouter config | +| AppTheme | `lib/core/theme/app_theme.dart` | Material 3 theme | +| SupabaseConfig | `lib/core/config/supabase_config.dart` | Supabase credentials | + +--- + +## Widgets (Reusable) + +| Widget | Ścieżka | +|--------|---------| +| **Auth** | | +| EmailTextField | `lib/core/auth/presentation/widgets/email_text_field.dart` | +| PasswordTextField | `lib/core/auth/presentation/widgets/password_text_field.dart` | +| OAuthButton | `lib/core/auth/presentation/widgets/oauth_button.dart` | +| **Core** | | +| SubmitButtonWidget | `lib/core/widgets/submit_button_widget.dart` | +| TimePickerWidget | `lib/core/widgets/time_picker_widget.dart` | +| DailyInputForm | `lib/core/widgets/daily_input_form.dart` | +| **Sync** | | +| OfflineBanner | `lib/core/sync/widgets/offline_banner.dart` | +| SyncStatusIndicator | `lib/core/sync/widgets/sync_status_indicator.dart` | +| **Charts** | | +| BarChartWidget | `lib/core/charts/widgets/bar_chart_widget.dart` | +| LineChartWidget | `lib/core/charts/widgets/line_chart_widget.dart` | +| **Mind** | | +| MeditationCard | `lib/features/mind_emotion/presentation/widgets/meditation_card.dart` | +| CategoryTabs | `lib/features/mind_emotion/presentation/widgets/category_tabs.dart` | +| SearchBarWidget | `lib/features/mind_emotion/presentation/widgets/search_bar_widget.dart` | + +--- + +*Ostatnia aktualizacja: 2025-12-02* diff --git a/.claude/PATTERNS.md b/.claude/PATTERNS.md new file mode 100644 index 0000000..b1b81f2 --- /dev/null +++ b/.claude/PATTERNS.md @@ -0,0 +1,333 @@ +# PATTERNS - Wzorce kodu GymApp + +> Kopiuj te wzorce zamiast szukać podobnego kodu w projekcie. + +--- + +## Clean Architecture Structure + +``` +lib/features/{feature_name}/ +├── data/ +│ ├── datasources/ +│ │ ├── {feature}_local_datasource.dart # Drift operations +│ │ └── {feature}_remote_datasource.dart # Supabase operations +│ ├── models/ +│ │ └── {feature}_model.dart # JSON serialization +│ └── repositories/ +│ └── {feature}_repository_impl.dart # Implements interface +├── domain/ +│ ├── entities/ +│ │ └── {feature}_entity.dart # Pure domain object +│ ├── repositories/ +│ │ └── {feature}_repository.dart # Interface (abstract) +│ └── usecases/ +│ └── {verb}_{noun}_usecase.dart # Single responsibility +└── presentation/ + ├── pages/ + │ └── {feature}_page.dart # Screen widget + ├── providers/ + │ └── {feature}_provider.dart # Riverpod state + └── widgets/ + └── {feature}_widget.dart # Reusable UI +``` + +--- + +## Riverpod Provider (riverpod_annotation) + +### AsyncNotifier Pattern +```dart +import 'package:riverpod_annotation/riverpod_annotation.dart'; + +part '{feature}_provider.g.dart'; + +@riverpod +class FeatureNotifier extends _$FeatureNotifier { + @override + Future build() async { + final repository = ref.watch(featureRepositoryProvider); + return repository.getInitialData(); + } + + Future doSomething(String param) async { + state = const AsyncLoading(); + state = await AsyncValue.guard(() async { + final repository = ref.read(featureRepositoryProvider); + return repository.performAction(param); + }); + } +} +``` + +### Simple Provider +```dart +@riverpod +Future> items(ItemsRef ref) async { + final repository = ref.watch(itemRepositoryProvider); + return repository.getAll(); +} +``` + +### Provider with Parameter +```dart +@riverpod +Future itemById(ItemByIdRef ref, String id) async { + final repository = ref.watch(itemRepositoryProvider); + return repository.getById(id); +} +``` + +--- + +## Repository Pattern + +### Interface (Domain) +```dart +abstract class FeatureRepository { + Future> getAll(); + Future getById(String id); + Future save(Entity entity); + Future delete(String id); +} +``` + +### Implementation (Data) +```dart +class FeatureRepositoryImpl implements FeatureRepository { + final AppDatabase _db; + final SupabaseClient _supabase; + + FeatureRepositoryImpl(this._db, this._supabase); + + @override + Future> getAll() async { + // Offline-first: read from Drift + final localData = await _db.select(_db.featureTable).get(); + return localData.map((e) => e.toEntity()).toList(); + } + + @override + Future save(Entity entity) async { + // Write to Drift first + await _db.into(_db.featureTable).insertOnConflictUpdate( + entity.toCompanion(), + ); + // Queue for sync + // ... sync logic + } +} +``` + +--- + +## UseCase Pattern + +```dart +class GetItemsUsecase { + final FeatureRepository _repository; + + GetItemsUsecase(this._repository); + + Future> call({String? filter}) async { + final items = await _repository.getAll(); + if (filter != null) { + return items.where((e) => e.category == filter).toList(); + } + return items; + } +} +``` + +--- + +## Drift Table Definition + +```dart +@DataClassName('FeatureData') +class FeatureTable extends Table { + TextColumn get id => text()(); + TextColumn get userId => text().named('user_id')(); + TextColumn get title => text()(); + TextColumn get description => text().nullable()(); + IntColumn get status => integer().withDefault(const Constant(0))(); + TextColumn get metadataJson => text().named('metadata_json').nullable()(); + DateTimeColumn get createdAt => dateTime().named('created_at').withDefault(currentDateAndTime)(); + DateTimeColumn get updatedAt => dateTime().named('updated_at').withDefault(currentDateAndTime)(); + + // Sync metadata (standard) + BoolColumn get isSynced => boolean().named('is_synced').withDefault(const Constant(false))(); + DateTimeColumn get lastSyncedAt => dateTime().named('last_synced_at').nullable()(); + + @override + Set get primaryKey => {id}; + + @override + List> get uniqueKeys => [{userId, title}]; // Optional +} +``` + +--- + +## Page Widget Pattern + +```dart +import 'package:flutter/material.dart'; +import 'package:flutter_riverpod/flutter_riverpod.dart'; + +class FeaturePage extends ConsumerWidget { + const FeaturePage({super.key}); + + @override + Widget build(BuildContext context, WidgetRef ref) { + final state = ref.watch(featureNotifierProvider); + + return Scaffold( + appBar: AppBar( + title: const Text('Feature'), + ), + body: state.when( + loading: () => const Center(child: CircularProgressIndicator()), + error: (error, stack) => Center(child: Text('Error: $error')), + data: (data) => _buildContent(context, ref, data), + ), + ); + } + + Widget _buildContent(BuildContext context, WidgetRef ref, FeatureState data) { + return ListView.builder( + itemCount: data.items.length, + itemBuilder: (context, index) => _buildItem(data.items[index]), + ); + } + + Widget _buildItem(Item item) { + return ListTile( + title: Text(item.title), + subtitle: Text(item.description ?? ''), + ); + } +} +``` + +--- + +## AI Service Call Pattern + +```dart +// Using AIService +final aiService = ref.read(aiServiceProvider); + +final response = await aiService.chat( + AIRequest( + messages: [ + AIMessage(role: 'system', content: 'You are a life coach...'), + AIMessage(role: 'user', content: userMessage), + ], + model: 'gpt-4o-mini', + maxTokens: 500, + ), +); + +if (response.isSuccess) { + final content = response.content; + // Process AI response +} else { + // Handle error + throw response.error!; +} +``` + +--- + +## GoRouter Route Definition + +```dart +// lib/core/router/app_router.dart + +GoRoute( + path: '/feature', + name: 'feature', + builder: (context, state) => const FeaturePage(), + routes: [ + GoRoute( + path: 'detail/:id', + name: 'feature-detail', + builder: (context, state) { + final id = state.pathParameters['id']!; + return FeatureDetailPage(id: id); + }, + ), + ], +), +``` + +--- + +## Error Handling Pattern + +```dart +// lib/core/error/result.dart - używaj Result + +Future> safeOperation() async { + try { + final data = await repository.getData(); + return Result.success(data); + } on NetworkException catch (e) { + return Result.failure(NetworkFailure(e.message)); + } on DatabaseException catch (e) { + return Result.failure(DatabaseFailure(e.message)); + } catch (e) { + return Result.failure(UnknownFailure(e.toString())); + } +} +``` + +--- + +## Form Validation Pattern + +```dart +class FormValidators { + static String? required(String? value) { + if (value == null || value.isEmpty) { + return 'To pole jest wymagane'; + } + return null; + } + + static String? email(String? value) { + if (value == null || value.isEmpty) return null; + final emailRegex = RegExp(r'^[\w-\.]+@([\w-]+\.)+[\w-]{2,4}$'); + if (!emailRegex.hasMatch(value)) { + return 'Nieprawidłowy adres email'; + } + return null; + } + + static String? minLength(String? value, int min) { + if (value == null || value.length < min) { + return 'Minimum $min znaków'; + } + return null; + } +} +``` + +--- + +## Naming Conventions + +| Element | Format | Przykład | +|---------|--------|----------| +| File | snake_case | `daily_plan_provider.dart` | +| Class | PascalCase | `DailyPlanProvider` | +| Variable/Method | camelCase | `getDailyPlan()` | +| Constant | camelCase | `const defaultTimeout = 30` | +| Enum value | camelCase | `LoadingState.inProgress` | +| Provider | camelCase + Provider | `dailyPlanNotifierProvider` | +| Table | PascalCase + Table | `DailyPlansTable` | + +--- + +*Kopiuj, dostosuj, używaj.* diff --git a/.claude/PROMPTS.md b/.claude/PROMPTS.md new file mode 100644 index 0000000..e041a35 --- /dev/null +++ b/.claude/PROMPTS.md @@ -0,0 +1,246 @@ +# PROMPTS - Szablony promptów dla AI + +> Gotowe prompty do rozpoczęcia pracy. Skopiuj i dostosuj. + +--- + +## 1. Nowy Feature (Pełny) + +``` +Stwórz nowy feature: {NAZWA_FEATURE} + +Wymagania: +- {Requirement 1} +- {Requirement 2} +- {Requirement 3} + +Przed rozpoczęciem: +1. Przeczytaj PATTERNS.md (.claude/PATTERNS.md) +2. Sprawdź TABLES.md czy potrzebna nowa tabela +3. Sprawdź FILE-MAP.md czy podobny feature istnieje + +Struktura do utworzenia: +lib/features/{feature_name}/ +├── data/ +│ ├── datasources/{feature}_local_datasource.dart +│ ├── models/{feature}_model.dart +│ └── repositories/{feature}_repository_impl.dart +├── domain/ +│ ├── entities/{feature}_entity.dart +│ ├── repositories/{feature}_repository.dart +│ └── usecases/ +├── presentation/ +│ ├── pages/{feature}_page.dart +│ ├── providers/{feature}_provider.dart +│ └── widgets/ + +Po zakończeniu: +1. Dodaj route w app_router.dart +2. Zaktualizuj FILE-MAP.md +3. Zaktualizuj docs/2-MANAGEMENT/project-status.md +``` + +--- + +## 2. Nowa Page (Screen) + +``` +Stwórz nową stronę: {NAZWA_PAGE} + +Lokalizacja: lib/features/{feature}/presentation/pages/{page_name}_page.dart + +Wzorce z PATTERNS.md: +- ConsumerWidget pattern +- state.when() dla AsyncValue +- AppBar z tytułem +- Error handling + +Komponenty UI: +- {Lista komponentów} + +Provider do użycia: {nazwa_provider} + +Po zakończeniu zaktualizuj: +- FILE-MAP.md (sekcja Pages) +- app_router.dart (nowa route) +``` + +--- + +## 3. Nowy Provider (Riverpod) + +``` +Stwórz nowy provider: {NAZWA_PROVIDER} + +Typ: [AsyncNotifier / FutureProvider / StateProvider] + +Lokalizacja: lib/features/{feature}/presentation/providers/{provider_name}_provider.dart + +Stan: +- {Field 1}: {Type} +- {Field 2}: {Type} + +Metody: +- {method1}(): {description} +- {method2}(): {description} + +Dependencies: +- {repository/service} + +Użyj riverpod_annotation (@riverpod). +Po zakończeniu uruchom: dart run build_runner build +``` + +--- + +## 4. Nowa Tabela Drift + +``` +Dodaj nową tabelę Drift: {NAZWA_TABELI} + +Lokalizacja: lib/core/database/tables/{batch}_tables.dart + +Pola: +- id: TextColumn (PK) +- userId: TextColumn +- {field}: {Type} - {description} +- createdAt, updatedAt: DateTimeColumn +- isSynced, lastSyncedAt: sync metadata + +Po utworzeniu: +1. Dodaj do database.dart (@DriftDatabase tables: [...]) +2. Uruchom: dart run build_runner build +3. Zaktualizuj TABLES.md +``` + +--- + +## 5. Fix Bug + +``` +Napraw bug: {OPIS_BUGA} + +Lokalizacja problemu: {ścieżka_pliku}:{linia} + +Oczekiwane zachowanie: +- {description} + +Aktualne zachowanie: +- {description} + +Przed naprawą: +1. Przeczytaj kod w {plik} +2. Sprawdź powiązane providery +3. Sprawdź czy bug jest w CLAUDE.md (Known Issues) + +Po naprawie: +1. Usuń z Known Issues w CLAUDE.md jeśli był tam +2. Zaktualizuj MVP-TODO.md jeśli dotyczy +``` + +--- + +## 6. Kontynuacja Pracy + +``` +Kontynuuj pracę nad projektem GymApp. + +Przeczytaj najpierw: +1. docs/2-MANAGEMENT/project-status.md - aktualny stan +2. docs/2-MANAGEMENT/MVP-TODO.md - co zostało +3. CLAUDE.md - Known Issues + +Następnie zaproponuj: +- Które zadania są priorytetowe +- Które można zrobić razem +- Estymowany effort (S/M/L) +``` + +--- + +## 7. Code Review + +``` +Zrób code review dla: {ŚCIEŻKA_PLIKU} + +Sprawdź: +1. Zgodność z Clean Architecture (PATTERNS.md) +2. Poprawność typów i null-safety +3. Error handling +4. Naming conventions +5. Brakujące testy +6. Potencjalne memory leaks (dispose) +7. Hardcoded values (userId, API keys) + +Format odpowiedzi: +- Krytyczne: [lista] +- Poprawki: [lista] +- Sugestie: [lista] +``` + +--- + +## 8. Aktualizacja Dokumentacji + +``` +Zaktualizuj dokumentację po ukończeniu: {OPIS_PRACY} + +Pliki do sprawdzenia/aktualizacji: +1. docs/2-MANAGEMENT/project-status.md - % completion +2. docs/2-MANAGEMENT/epics/epic-{N}.md - status story +3. docs/2-MANAGEMENT/MVP-TODO.md - checkboxy +4. CLAUDE.md - Known Issues (jeśli naprawiono) +5. .claude/FILE-MAP.md - nowe pliki +6. .claude/TABLES.md - nowe tabele +``` + +--- + +## 9. Story Implementation + +``` +Zaimplementuj story: {STORY_ID} - {STORY_TITLE} + +Szczegóły w: docs/2-MANAGEMENT/epics/epic-{N}.md + +Acceptance Criteria: +- [ ] {AC1} +- [ ] {AC2} +- [ ] {AC3} + +Podejście: +1. Przeczytaj pełny opis story w epic file +2. Sprawdź zależności (inne stories, tabele) +3. Użyj wzorców z PATTERNS.md +4. Implementuj krok po kroku + +Po zakończeniu: +1. Oznacz story jako ✅ Done w epic file +2. Zaktualizuj project-status.md +``` + +--- + +## 10. Quick Start (Nowa Sesja) + +``` +Zaczynam nową sesję pracy nad GymApp. + +Quick context: +- Flutter app, Clean Architecture + Riverpod +- Drift (SQLite) + Supabase +- MVP 1.0 ~45% complete + +Moje cele na tę sesję: +1. {Cel 1} +2. {Cel 2} + +Przeczytaj te pliki: +- .claude/FILE-MAP.md (jeśli szukam kodu) +- .claude/TABLES.md (jeśli dotyka DB) +- .claude/PATTERNS.md (jeśli tworzę nowy kod) +``` + +--- + +*Skopiuj prompt, wypełnij {PLACEHOLDERS}, wklej do AI.* diff --git a/.claude/TABLES.md b/.claude/TABLES.md new file mode 100644 index 0000000..a527061 --- /dev/null +++ b/.claude/TABLES.md @@ -0,0 +1,118 @@ +# TABLES - Drift Schema (Skrócone) + +> Szybki przegląd tabel lokalnej bazy danych (SQLite/Drift). +> Pełna dokumentacja: `docs/1-BASELINE/architecture/ARCH-database-schema.md` + +--- + +## Quick Reference + +| Tabela | Plik | Główne pola | +|--------|------|-------------| +| WorkoutTemplates | sprint0 | name, exercises (JSON), category, difficulty | +| Subscriptions | sprint0 | tier, status, stripeSubscriptionId | +| Streaks | sprint0 | streakType, currentStreak, longestStreak | +| AiConversations | sprint0 | messages (JSON), aiModel, conversationType | +| MoodLogs | sprint0 | moodScore, energyScore, stressLevel | +| UserDailyMetrics | sprint0 | [fitness + mind + life coach metrics] | +| MentalHealthScreenings | sprint0 | screeningType (GAD-7/PHQ-9), score, severity | +| CheckIns | batch1 | type (morning/evening), energyLevel, mood | +| WorkoutLogs | batch1 | workoutName, duration, isQuickLog | +| ExerciseSets | batch1 | exerciseName, weight, reps, setNumber | +| Goals | batch3 | title, category, targetValue, currentValue | +| GoalProgress | batch3 | goalId, value, timestamp | +| BodyMeasurements | batch3 | weight, bodyFat, chest, waist, hips... | +| DailyPlans | life_coach | date, tasksJson, dailyTheme | +| ChatSessions | life_coach | messagesJson, title, isArchived | + +--- + +## Tabele szczegółowo + +### CheckIns (Morning/Evening) +```dart +// lib/core/database/tables/batch1_tables.dart +id, userId, timestamp, type ('morning'|'evening') +// Morning: energyLevel, mood, intentions, gratitude +// Evening: productivityRating, wins, improvements, tomorrowFocus +// Common: tags (JSON), notes, isSynced +``` + +### WorkoutLogs + ExerciseSets +```dart +// WorkoutLogs +id, userId, timestamp, workoutName, duration (seconds), isQuickLog + +// ExerciseSets (FK: workoutLogId) +id, workoutLogId, exerciseName, setNumber, weight, reps, duration, restTime +``` + +### Goals + GoalProgress +```dart +// Goals +id, userId, title, description, category +targetDate, targetValue, unit ('kg'|'reps'|'days') +currentValue, completionPercentage, isCompleted +priority (1-5), isArchived + +// GoalProgress (FK: goalId) +id, goalId, timestamp, value, notes +``` + +### DailyPlans +```dart +id, date, tasksJson, dailyTheme, motivationalQuote +source (0=ai_generated, 1=manual), metadataJson +``` + +### ChatSessions +```dart +id, userId, title, messagesJson +lastMessageAt, isArchived +``` + +### UserDailyMetrics (Cross-Module Intelligence) +```dart +id, userId, date +// Fitness +workoutCompleted, workoutDurationMinutes, caloriesBurned, setsCompleted, workoutIntensity +// Mind +meditationCompleted, meditationDurationMinutes, moodScore, stressLevel, journalEntriesCount +// Life Coach +dailyPlanGenerated, tasksCompleted, tasksTotal, completionRate, aiConversationsCount +``` + +### Streaks +```dart +id, userId, streakType ('workout'|'meditation'|'check_in') +currentStreak, longestStreak, lastCompletedDate, freezeUsed +``` + +### Subscriptions +```dart +id, userId, tier ('free'|'mind'|'fitness'|'three_pack'|'plus') +status ('active'|'trial'|'canceled'|'past_due') +stripeCustomerId, stripeSubscriptionId +trialEndsAt, currentPeriodStart, currentPeriodEnd +``` + +--- + +## Sync Metadata (wszystkie tabele) + +```dart +BoolColumn isSynced => withDefault(false) +DateTimeColumn lastSyncedAt => nullable() +``` + +--- + +## Regenerowanie kodu Drift + +```bash +dart run build_runner build +``` + +--- + +*Pliki: sprint0_tables.dart, batch1_tables.dart, batch3_tables.dart, life_coach_tables.dart* From 8c224d5a83ea50a48852947af460e20bd5c252e2 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Dec 2025 14:42:22 +0000 Subject: [PATCH 2/2] docs: Add DOCUMENTATION-TEMPLATE.md for reusable project setup Generic template for restructuring documentation in any project: - BMAD v6 compatible folder structure (docs/) - AI-optimized .claude/ files structure - CLAUDE.md template with all sections - Multi-model workflow guide (Opus/Sonnet/Haiku) - Checklists for new projects and rebuilds - Story implementation workflow --- .claude/DOCUMENTATION-TEMPLATE.md | 547 ++++++++++++++++++++++++++++++ 1 file changed, 547 insertions(+) create mode 100644 .claude/DOCUMENTATION-TEMPLATE.md diff --git a/.claude/DOCUMENTATION-TEMPLATE.md b/.claude/DOCUMENTATION-TEMPLATE.md new file mode 100644 index 0000000..d614a4d --- /dev/null +++ b/.claude/DOCUMENTATION-TEMPLATE.md @@ -0,0 +1,547 @@ +# DOCUMENTATION-TEMPLATE + +> Generyczny szablon do przebudowy dokumentacji projektu. +> Kompatybilny z BMAD Method V6 + optymalizacja dla AI-assisted development. + +--- + +## Spis Treści + +1. [Overview](#1-overview) +2. [Proces Przebudowy](#2-proces-przebudowy) +3. [Struktura docs/ (BMAD V6)](#3-struktura-docs-bmad-v6) +4. [Struktura .claude/](#4-struktura-claude) +5. [Template CLAUDE.md](#5-template-claudemd) +6. [Multi-Model Workflow](#6-multi-model-workflow) +7. [Checklisty](#7-checklisty) + +--- + +## 1. Overview + +### Cel + +Stworzyć dokumentację która: +- Jest **szybka do przeczytania** przez AI (mniej tokenów = szybsze odpowiedzi) +- **Nie wymaga Glob/Grep** dla standardowych operacji +- Jest **kompatybilna z BMAD v6** (fazy, epics, stories) +- Wspiera **multi-model workflow** (różne modele do różnych zadań) + +### Wynik końcowy + +``` +projekt/ +├── CLAUDE.md ← Entry point dla AI (zawsze ładowany) +├── .claude/ +│ ├── FILE-MAP.md ← Index plików projektu +│ ├── TABLES.md ← Schema bazy danych (skrócone) +│ ├── PATTERNS.md ← Wzorce kodu +│ └── PROMPTS.md ← Szablony promptów +│ +└── docs/ ← BMAD-compatible dokumentacja + ├── 00-START-HERE.md ← Entry point dla człowieka + ├── BMAD-STRUCTURE.md ← Jak zorganizowana jest dokumentacja + │ + ├── 1-BASELINE/ ← Wymagania i architektura + │ ├── product/ ← PRD, requirements + │ └── architecture/ ← Tech decisions, schema + │ + ├── 2-MANAGEMENT/ ← Status, TODO, epics + │ ├── project-status.md + │ ├── MVP-TODO.md + │ └── epics/ + │ + ├── 3-ARCHITECTURE/ ← Szczegółowa architektura (opcjonalne) + ├── 4-DEVELOPMENT/ ← Developer guides + └── 5-ARCHIVE/ ← Stara/deprecated dokumentacja +``` + +--- + +## 2. Proces Przebudowy + +### Krok 1: Analiza obecnej dokumentacji + +``` +Przeanalizuj obecną dokumentację projektu: + +1. Jakie pliki dokumentacji istnieją? +2. Jakie są główne sekcje? +3. Co jest aktualne, a co przestarzałe? +4. Czy są epics/stories? W jakim formacie? + +Wynik: Lista plików + ich status (aktualne/do aktualizacji/do archiwizacji) +``` + +### Krok 2: Ekstrakcja kluczowych informacji + +``` +Z istniejącej dokumentacji wyciągnij: + +1. QUICK FACTS (nazwa, typ, tech stack, status %) +2. CODE STRUCTURE (główne foldery, architektura) +3. KNOWN ISSUES (aktywne bugi, TODO) +4. DATABASE SCHEMA (tabele, relacje) +5. CONVENTIONS (nazewnictwo, patterns) +6. EPICS/STORIES (jeśli istnieją) +``` + +### Krok 3: Stwórz CLAUDE.md + +Użyj [Template CLAUDE.md](#5-template-claudemd) poniżej. + +### Krok 4: Stwórz pliki .claude/ + +| Plik | Źródło danych | Instrukcje | +|------|---------------|------------| +| FILE-MAP.md | Struktura `lib/` lub `src/` | Glob all files, categorize by type | +| TABLES.md | Schema DB, migrations | Extract table names + key fields | +| PATTERNS.md | Istniejący kod | Identify recurring patterns | +| PROMPTS.md | Workflow projektu | Create task-specific prompts | + +### Krok 5: Przebuduj docs/ na strukturę BMAD + +Przenieś istniejące pliki do odpowiednich folderów: + +| Zawartość | Cel | +|-----------|-----| +| PRD, requirements, specs | `1-BASELINE/product/` | +| Architecture, schema, decisions | `1-BASELINE/architecture/` | +| Status, TODO, roadmap | `2-MANAGEMENT/` | +| Epics, stories | `2-MANAGEMENT/epics/` | +| Setup guides, tutorials | `4-DEVELOPMENT/` | +| Stare/nieaktualne | `5-ARCHIVE/` | + +### Krok 6: Walidacja + +``` +Sprawdź: +- [ ] CLAUDE.md ładuje się poprawnie +- [ ] FILE-MAP.md zawiera wszystkie key files +- [ ] TABLES.md pokrywa aktywne tabele +- [ ] PATTERNS.md ma wzorce dla głównych operacji +- [ ] docs/ ma czytelną strukturę +``` + +--- + +## 3. Struktura docs/ (BMAD V6) + +### Kompatybilność z BMAD Phases + +| BMAD Phase | Folder docs/ | Zawartość | +|------------|--------------|-----------| +| Phase 1: Analysis | `1-BASELINE/product/` | Research, briefs | +| Phase 2: Planning | `1-BASELINE/product/` | PRD, requirements | +| Phase 3: Solutioning | `1-BASELINE/architecture/` | Architecture, design | +| Phase 4: Implementation | `2-MANAGEMENT/epics/` | Stories, status | + +### Format Epic (BMAD-compatible) + +```markdown +# Epic {N}: {Nazwa} + +## Overview +{Krótki opis epica} + +## Stories + +### Story {N}.1: {Nazwa} +**Status:** ⏳ Planned | 🔄 In Progress | ✅ Done | ❌ Blocked + +**As a** {user type} +**I want** {action} +**So that** {benefit} + +**Acceptance Criteria:** +- [ ] {AC1} +- [ ] {AC2} + +**Technical Notes:** +- {implementation details} + +**Dependencies:** +- Story {X}.{Y} +``` + +### Format project-status.md + +```markdown +# Project Status + +## Quick Stats +| Metric | Value | +|--------|-------| +| Overall Progress | XX% | +| Current Sprint | Sprint N | +| Blockers | X | + +## Module Progress +| Module | Status | % | +|--------|--------|---| +| Auth | ✅ Done | 100% | +| Feature A | 🔄 In Progress | 60% | +| Feature B | ⏳ Planned | 0% | + +## Current Focus +- [ ] Task 1 +- [ ] Task 2 + +## Blockers +1. {Blocker description} +``` + +--- + +## 4. Struktura .claude/ + +### FILE-MAP.md Template + +```markdown +# FILE-MAP + +## Pages/Screens +| Page | Path | Description | +|------|------|-------------| +| HomePage | `src/pages/home.tsx` | Main dashboard | + +## Components +| Component | Path | Description | +|-----------|------|-------------| +| Button | `src/components/Button.tsx` | Reusable button | + +## API/Services +| Service | Path | Description | +|---------|------|-------------| +| AuthService | `src/services/auth.ts` | Authentication | + +## Database/Models +| Model | Path | Description | +|-------|------|-------------| +| User | `src/models/user.ts` | User entity | + +## Config +| File | Path | Description | +|------|------|-------------| +| env | `.env.example` | Environment vars | +``` + +### TABLES.md Template + +```markdown +# TABLES + +## Quick Reference +| Table | Key Fields | Relations | +|-------|------------|-----------| +| users | id, email, name | → posts, → comments | +| posts | id, userId, title | ← users, → comments | + +## Table Details + +### users +- id: UUID (PK) +- email: TEXT UNIQUE +- name: TEXT +- createdAt: TIMESTAMP + +### posts +- id: UUID (PK) +- userId: UUID (FK → users) +- title: TEXT +- content: TEXT +``` + +### PATTERNS.md Template + +```markdown +# PATTERNS + +## Component Pattern +\`\`\`{language} +// Standard component structure +{code example} +\`\`\` + +## API Pattern +\`\`\`{language} +// Standard API endpoint +{code example} +\`\`\` + +## State Management Pattern +\`\`\`{language} +// Standard state handling +{code example} +\`\`\` + +## Error Handling Pattern +\`\`\`{language} +// Standard error handling +{code example} +\`\`\` + +## Naming Conventions +| Element | Format | Example | +|---------|--------|---------| +| File | kebab-case | `user-service.ts` | +| Class | PascalCase | `UserService` | +| Function | camelCase | `getUser()` | +``` + +### PROMPTS.md Template + +```markdown +# PROMPTS + +## 1. New Feature +\`\`\` +Create new feature: {NAME} +Requirements: {list} +Use patterns from PATTERNS.md +Update FILE-MAP.md after completion +\`\`\` + +## 2. Fix Bug +\`\`\` +Fix bug: {DESCRIPTION} +Location: {file:line} +Expected: {behavior} +Actual: {behavior} +\`\`\` + +## 3. Continue Work +\`\`\` +Continue work on project. +Read: project-status.md, MVP-TODO.md +Propose next tasks with priority. +\`\`\` +``` + +--- + +## 5. Template CLAUDE.md + +```markdown +# {Project Name} - AI Assistant Guide + +## Quick Facts + +| Aspect | Value | +|--------|-------| +| **Name** | {project_name} | +| **Type** | {type: web app, mobile app, API, library} | +| **Stack** | {main technologies} | +| **Architecture** | {pattern: Clean Architecture, MVC, etc.} | +| **Database** | {database type} | +| **Status** | {current status, % complete} | + +--- + +## Documentation Index + +### .claude/ Files (AI-optimized) + +| File | Purpose | +|------|---------| +| FILE-MAP.md | Index of all code files | +| TABLES.md | Database schema (condensed) | +| PATTERNS.md | Code patterns to follow | +| PROMPTS.md | Ready-to-use prompts | + +### docs/ Structure + +``` +docs/ +├── 00-START-HERE.md ← Entry point +├── 1-BASELINE/ ← Requirements & Architecture +│ ├── product/ ← PRD, requirements +│ └── architecture/ ← Tech decisions +├── 2-MANAGEMENT/ ← Status & Tracking +│ ├── project-status.md ← Current state +│ ├── MVP-TODO.md ← Task list +│ └── epics/ ← Epic & story files +└── 4-DEVELOPMENT/ ← Developer guides +``` + +### Quick Links + +| Question | File | +|----------|------| +| What is current status? | `docs/2-MANAGEMENT/project-status.md` | +| What's left to do? | `docs/2-MANAGEMENT/MVP-TODO.md` | +| Story details? | `docs/2-MANAGEMENT/epics/epic-*.md` | +| Database schema? | `.claude/TABLES.md` | +| Code patterns? | `.claude/PATTERNS.md` | + +--- + +## Code Structure + +``` +{lib|src}/ +├── {main_folder}/ ← Entry point +├── {core_folder}/ ← Shared infrastructure +│ ├── {subfolder}/ ← Description +│ └── {subfolder}/ ← Description +└── {features_folder}/ ← Feature modules + ├── {feature_a}/ ← % complete + └── {feature_b}/ ← % complete +``` + +--- + +## Known Issues + +### Critical +1. **{Issue Title}** - {short description} + - Location: `{file:line}` + - Fix: {proposed fix} + +### To Do +- {Item 1} +- {Item 2} + +--- + +## Conventions + +### File Naming +``` +{pattern description} +``` + +### Commit Messages +``` +{type}: {description} +Examples: feat:, fix:, docs:, refactor: +``` + +--- + +## AI Instructions + +### Before starting work: +1. Read `project-status.md` - current state +2. Read `MVP-TODO.md` - remaining tasks +3. Check relevant epic file for story details + +### After completing work: +1. Update `project-status.md` if % changed +2. Update epic file if story completed +3. Update `MVP-TODO.md` - mark tasks as done +4. Commit with descriptive message + +### Creating new files: +1. Follow patterns from PATTERNS.md +2. Add to FILE-MAP.md +3. Use naming conventions + +--- + +## Quick Commands + +```bash +# {command description} +{command} + +# {command description} +{command} +``` + +--- + +*Last updated: {date}* +``` + +--- + +## 6. Multi-Model Workflow + +### Podział zadań między modele + +| Zadanie | Model | Dlaczego | +|---------|-------|----------| +| **Planowanie, architektura** | Opus | Głęboka analiza, long-context | +| **Implementacja kodu** | Sonnet | Szybki, dokładny w kodzie | +| **Quick fixes, review** | Haiku | Najszybszy, tani | +| **Dokumentacja** | Sonnet/Opus | Zależnie od złożoności | + +### Workflow Setup + +``` +1. OPUS: Analiza projektu, tworzenie CLAUDE.md + ↓ +2. OPUS: Przebudowa docs/, planowanie epics + ↓ +3. SONNET: Implementacja stories (per story fresh chat) + ↓ +4. HAIKU: Code review, quick fixes + ↓ +5. SONNET: Aktualizacja dokumentacji +``` + +### Fresh Chat Rule (BMAD) + +> **KRYTYCZNE:** Używaj fresh chat dla każdego workflow żeby uniknąć halucynacji. + +- Nowy chat dla każdego story +- Nowy chat po dużej zmianie kontekstu +- Zawsze zaczynaj od przeczytania CLAUDE.md + +--- + +## 7. Checklisty + +### Checklist: Nowy Projekt + +- [ ] Stwórz CLAUDE.md z Quick Facts +- [ ] Stwórz strukturę docs/ (BMAD) +- [ ] Stwórz .claude/FILE-MAP.md +- [ ] Stwórz .claude/TABLES.md (jeśli ma DB) +- [ ] Stwórz .claude/PATTERNS.md +- [ ] Stwórz .claude/PROMPTS.md +- [ ] Dodaj AI-INDEX do kluczowych plików + +### Checklist: Przebudowa Istniejącego Projektu + +- [ ] Przeanalizuj obecną dokumentację +- [ ] Zidentyfikuj co jest aktualne/przestarzałe +- [ ] Stwórz CLAUDE.md z wyekstrahowanych danych +- [ ] Przenieś pliki do struktury docs/ BMAD +- [ ] Zarchiwizuj stare pliki w 5-ARCHIVE/ +- [ ] Stwórz pliki .claude/ +- [ ] Zwaliduj że wszystko działa + +### Checklist: Story Implementation + +- [ ] Fresh chat +- [ ] Przeczytaj CLAUDE.md +- [ ] Przeczytaj story w epic file +- [ ] Sprawdź dependencies +- [ ] Implementuj używając PATTERNS.md +- [ ] Zaktualizuj FILE-MAP.md (jeśli nowe pliki) +- [ ] Zaktualizuj epic file (status: ✅ Done) +- [ ] Zaktualizuj project-status.md +- [ ] Commit z opisowym message + +--- + +## AI-INDEX Format + +Każdy plik dokumentacji powinien mieć: + +```markdown + +``` + +Przykłady: +```markdown + + + +``` + +--- + +*Ten szablon jest generyczny - dostosuj do specyfiki swojego projektu i tech stacku.*