Alo/phaseflow
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
04a532bb01c11e7b8b6b0bdaac3b47f3c618ee4c
phaseflow/IMPLEMENTATION_PLAN.md
Petru Paler 04a532bb01
All checks were successful
Deploy / deploy (push) Successful in 2m28s
Details
Add 4 Garmin E2E tests for network error recovery 
Add tests to verify error handling when network requests fail:
- Error toast when token save fails (500 response)
- Error toast when disconnect fails (500 response)
- Error state display when status fetch fails
- Retry succeeds after network failure

These tests improve resilience coverage for the Garmin connection flow.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 18:54:58 +00:00

162 lines
7.3 KiB
Markdown
Raw Blame History

# PhaseFlow Implementation Plan
This file is maintained by Ralph. Run `./ralph-sandbox.sh plan 3` to generate tasks.
## Current Status: Feature Complete
**Test Coverage:** 1014 unit tests (51 files) + 202 E2E tests (13 files) = 1216 total tests
All P0-P5 items are complete. The project is feature complete.
---
## Architecture Summary
### Tech Stack
| Layer | Choice |
|-------|--------|
| Framework | Next.js 16 (App Router) |
| Runtime | Node.js 24 |
| Database | PocketBase |
| Validation | Zod |
| Testing | Vitest + jsdom + Playwright |
| Linting | Biome |
### Critical Business Rules
1. **Override Priority:** flare > stress > sleep > pms (enforced in order)
2. **HRV Unbalanced:** ALWAYS forces REST (highest algorithmic priority, non-overridable)
3. **Phase Limits:** Strictly enforced per phase configuration
4. **Token Expiration Warnings:** Email at 14 days and 7 days before expiry
5. **ICS Feed:** Generates 90 days of phase events for calendar subscription
---
## Completed Implementation
### Library Files (12 files, 250+ tests)
| File | Tests | Key Functions |
|------|-------|---------------|
| `cycle.ts` | 22 | `getCycleDay`, `getPhase`, `getPhaseConfig`, dynamic phase boundaries |
| `nutrition.ts` | 17 | `getNutritionGuidance`, `getSeedSwitchAlert`, phase-specific guidance |
| `email.ts` | 32 | `sendDailyEmail`, `sendPeriodConfirmationEmail`, `sendTokenExpirationWarning` |
| `ics.ts` | 33 | `generateIcsFeed`, 90-day events, period prediction feedback, CATEGORIES |
| `encryption.ts` | 14 | AES-256-GCM encrypt/decrypt |
| `decision-engine.ts` | 24 | `getTrainingDecision`, `getDecisionWithOverrides`, 8 priority rules |
| `garmin.ts` | 33 | `fetchHrvStatus`, `fetchBodyBattery`, `fetchIntensityMinutes`, token validation |
| `pocketbase.ts` | 10 | `createPocketBaseClient`, `isAuthenticated`, `getCurrentUser`, `loadAuthFromCookies` |
| `auth-middleware.ts` | 12 | `withAuth()` wrapper, structured logging, IP logging |
| `middleware.ts` | 12 | Next.js page protection, redirects |
| `logger.ts` | 16 | Pino JSON output, log levels, child loggers |
| `metrics.ts` | 33 | Prometheus metrics, counters, gauges, histograms |
### API Routes (21 endpoints, 350+ tests)
| Route | Tests | Purpose |
|-------|-------|---------|
| POST /api/auth/logout | 5 | Session logout |
| GET /api/user | 4 | User profile |
| PATCH /api/user | 17 | Update preferences |
| POST /api/cycle/period | 13 | Log period start with prediction tracking |
| GET /api/cycle/current | 10 | Current cycle state |
| GET /api/today | 24 | Daily snapshot with decision |
| POST/DELETE /api/overrides | 14 | Override management |
| POST/DELETE /api/garmin/tokens | 15 | Token storage |
| GET /api/garmin/status | 11 | Connection status |
| POST /api/cron/garmin-sync | 32 | Daily data sync |
| POST /api/cron/notifications | 20 | Email notifications |
| GET /api/calendar/[userId]/[token].ics | 11 | ICS feed |
| POST /api/calendar/regenerate-token | 9 | Token regeneration |
| GET /api/history | 19 | Daily log history |
| GET /api/period-history | 18 | Period log history |
| PATCH/DELETE /api/period-logs/[id] | 16 | Period log management |
| GET /api/health | 14 | Health check |
| GET /metrics | 15 | Prometheus metrics |
### Pages (8 pages, 230+ tests)
| Page | Tests | Features |
|------|-------|----------|
| Dashboard (`/`) | 28 | Decision card, data panel, nutrition, overrides, mini calendar |
| Login (`/login`) | 32 | OIDC + email/password, rate limiting |
| Settings (`/settings`) | 34 | Preferences, logout |
| Settings/Garmin | 27 | Token management, status |
| Calendar (`/calendar`) | 23 | Month view, ICS subscription |
| History (`/history`) | 26 | Daily log table |
| Period History | 27 | Period log table, edit/delete |
| Plan (`/plan`) | 16 | Phase overview, training reference |
### Components (10 components, 200+ tests)
| Component | Tests | Purpose |
|-----------|-------|---------|
| DecisionCard | 19 | Status display with color coding |
| DataPanel | 29 | Biometrics display, HRV color coding, progress bar |
| NutritionPanel | 16 | Seeds, carbs, keto guidance |
| OverrideToggles | 18 | Override buttons |
| DayCell | 32 | Calendar day with phase colors, period indicator |
| MiniCalendar | 23 | Dashboard calendar widget |
| OnboardingBanner | 16 | Setup prompts |
| MonthView | 31 | Full calendar with navigation, keyboard nav |
| PeriodDateModal | 22 | Period input modal |
| Skeletons | 29 | Loading states with shimmer |
### E2E Tests (13 files, 202 tests)
| File | Tests | Coverage |
|------|-------|----------|
| smoke.spec.ts | 3 | Basic app functionality |
| auth.spec.ts | 20 | Login, protected routes, OIDC flow, session persistence |
| dashboard.spec.ts | 40 | Dashboard display, overrides, accessibility |
| settings.spec.ts | 27 | Settings form, validation, persistence, error recovery |
| garmin.spec.ts | 16 | Garmin connection, expiry warnings, network error recovery |
| period-logging.spec.ts | 19 | Period history, logging, modal flows |
| calendar.spec.ts | 34 | Calendar view, ICS feed, content validation, accessibility |
| decision-engine.spec.ts | 8 | Decision priority chain |
| cycle.spec.ts | 11 | Cycle tracking |
| history.spec.ts | 7 | History page |
| plan.spec.ts | 7 | Plan page |
| health.spec.ts | 3 | Health/observability |
| mobile.spec.ts | 7 | Mobile viewport behavior, responsive layout, calendar mobile |
---
## E2E Test Enhancement Opportunities
These are optional enhancements to improve E2E coverage. Not required for feature completeness.
### New Test Files (Lower Priority)
| File | Tests | Description |
|------|-------|-------------|
| notifications.spec.ts | 3 | Notification preferences |
| dark-mode.spec.ts | 2 | System preference detection |
### Completed Enhancements
| File | Tests Added | Focus Area |
|------|-------------|------------|
| garmin.spec.ts | +4 | Network error recovery (save, disconnect, status fetch, retry) |
| calendar.spec.ts | +4 | Accessibility (ARIA, keyboard nav) |
| settings.spec.ts | +1 | Error recovery on failed save |
| mobile.spec.ts | +3 | Calendar responsive behavior |
---
## Notes
1. **TDD Approach:** Write failing tests first, then implement
2. **Auth First:** P0 items unlock all other work
3. **No Mock Mode:** Use real data and APIs only
4. **ABOUTME Comments:** All files start with 2-line ABOUTME
5. **Commit Format:** Descriptive message + Claude footer
6. **Never use --no-verify:** All commits go through pre-commit hooks
---
## Revision History
- 2026-01-13: Added 4 Garmin E2E tests (network error recovery for save, disconnect, status fetch, retry)
- 2026-01-13: Added 8 E2E tests (calendar accessibility, settings error recovery, calendar mobile behavior)
- 2026-01-13: Added mobile.spec.ts with 4 E2E tests (mobile viewport behavior, responsive layout)
- 2026-01-13: Added 6 auth E2E tests (OIDC button display, loading states, session persistence across pages/refresh)
- 2026-01-13: Added 5 settings persistence E2E tests (notification time, timezone, multi-field persistence)
- 2026-01-13: Added 5 period-logging E2E tests (modal flow, future date restriction, edit/delete flows)
- 2026-01-13: Added 5 Garmin E2E tests (expiry warnings, expired state, persistence, reconnection)
- 2026-01-13: Condensed plan after feature completion (reduced from 1514 to ~170 lines)
- 2026-01-12: Fixed spec gaps (email format, HRV colors, progress bar, emojis)
- 2026-01-11: Completed P5.1-P5.4 (period history, toast, CI, E2E)
Reference in New Issue View Git Blame Copy Permalink