diff --git a/.github/specs/plan-achievements.md b/.github/specs/plan-achievements.md new file mode 100644 index 0000000..f73c932 --- /dev/null +++ b/.github/specs/plan-achievements.md @@ -0,0 +1,70 @@ +## Plan: Achievements Feature Design + +Published to Gitea wiki page: Achievements + +Design an achievements system that starts with low-risk, high-fun rules using existing tracking data, then expands to streak and behavior achievements. This approach gives fast player-visible value without major schema risk, while leaving room for deeper gamification. +Status: Approved by user for implementation kickoff. + +**Steps** + +1. Phase 1: Define achievement taxonomy and product goals +2. Define families: points progression, consistency/streaks, reward habits, task diversity, check-in/engagement, social/funny outcomes. +3. Define unlock semantics: one-time unlocks vs repeatable milestones, per-child scope, optional parent aggregate view. Depends on step 2. +4. Define badge rarity tiers (common, rare, epic, legendary) and naming/tone guide so achievements feel playful, not punitive. +5. Phase 2: MVP achievement set (no new raw telemetry) +6. Use existing TrackingEvent and PendingConfirmation signals to launch 20-30 achievements immediately. Depends on phase 1. +7. Include serious progression set: first points earned, 100/500/1000 lifetime points, best day records, no-miss week, kindness count milestones. +8. Include funny set: zero points 7 days, last-minute legend (frequent late confirmations), window shopper (many reward requests without redemption), tiny spender (chooses low-cost rewards repeatedly). +9. Include non-point set: reward loyalty (same reward redeemed N times), variety collector (N distinct chores completed), daily checker (opened/triggered chores on N consecutive days), comeback kid (returns after inactivity). +10. Phase 3: Data model and evaluation architecture +11. Add achievement definition catalog (static or DB-backed) and child achievement progress/unlock records. Depends on phase 2. +12. Evaluate on mutation events (tracking event creation, chore confirmation, reward request/redeem), with idempotent unlock logic and timezone-aware daily boundaries. +13. Emit achievement unlocked SSE events for real-time UI celebration and maintain API for achievement list/progress. +14. Phase 4: UX and rollout +15. Parent view: child achievement timeline, rarity filters, and progress-to-next badge. +16. Child view: badge cabinet, streak flame, and lightweight celebration effects. +17. Roll out behind feature flag, start with read-only earned badges, then add near-miss/progress indicators. Depends on phase 3. +18. Phase 5: Validation and balancing +19. Add unit tests for each rule family and timezone edge cases. +20. Add end-to-end tests for unlock notifications and badge rendering. +21. Run a balancing pass using anonymized historical events to ensure unlock pacing feels rewarding (not too sparse, not too noisy). +22. Documentation deliverable: publish the final approved achievements plan to a new Gitea wiki page for the chore project as part of implementation handoff. + +**Relevant files** + +- /Users/ryan/Projects/chore/backend/models/tracking_event.py - existing event ledger for points/actions and occurred_at timestamps. +- /Users/ryan/Projects/chore/backend/models/pending_confirmation.py - reward/chore confirmation states useful for request/approval achievements. +- /Users/ryan/Projects/chore/backend/db/tracking.py - insertion/query leverage point for achievement evaluation trigger. +- /Users/ryan/Projects/chore/backend/events/types/event_types.py - event taxonomy to extend with achievement unlock notifications. +- /Users/ryan/Projects/chore/backend/api/child_api.py - existing child-facing data APIs to mirror for achievement endpoints. +- /Users/ryan/Projects/chore/frontend/vue-app/src/common/models.ts - add Achievement interfaces (backend parity). +- /Users/ryan/Projects/chore/frontend/vue-app/src/common/backendEvents.ts - frontend SSE subscriptions for unlock celebrations. +- /Users/ryan/Projects/chore/frontend/vue-app/src/common/api.ts - API helpers for listing achievements and progress. + +**Verification** + +1. Rule correctness: seed deterministic tracking histories and verify each achievement unlock threshold exactly once. +2. Timezone correctness: validate day/week achievements for users in at least three timezones and around midnight boundaries. +3. Idempotency: replay the same event stream and verify no duplicate unlocks. +4. UX behavior: confirm unlocked badges appear in parent and child views without manual refresh via SSE. +5. Regression safety: run backend pytest suite and focused Playwright specs for parent/child dashboards. + +**Decisions** + +- Included in MVP: achievements derivable from existing signals (tracking events, pending confirmations, child points, reward history). +- Data schema decision for wave 1: no new fields required on task/chore/reward models (no complexity/category requirement for initial launch). +- Deliberately excluded from MVP: complex streak rules requiring schedule reinterpretation across every task mode; these are phase 2+ enhancements. +- Scope model: per-child achievements first, optional parent-level achievements later. +- Tone model: include playful/funny achievements but avoid shaming language; treat low-performance badges as light easter eggs. + +**Further Considerations** + +1. Modularity architecture recommendation: isolate all achievement logic into an Achievement Engine module with a rule interface (evaluate(event, context) -> unlocks) and a central registry so no existing chore/reward/business logic needs branching changes. +2. Toggle recommendation: add a global feature flag plus optional per-user flag; when disabled, route through a no-op evaluator and suppress achievement APIs/SSE/UI sections without impacting core chore/reward flows. +3. Editability recommendation: store initial achievement definitions in a versioned JSON or YAML catalog with schema validation at startup, stable ids, enabled flag, and threshold params so add/remove/edit is config-only for most rules. +4. Progress UX recommendation: show top 3 near-unlock achievements to increase motivation without overwhelming the child dashboard. +5. Seasonal/event achievements recommendation: add limited-time badges after baseline system proves stable. +6. UI isolation recommendation: keep achievement state in a dedicated frontend store/module and render via isolated components; chore/reward screens should only publish domain events and never compute achievement rules directly. +7. UI kill-switch behavior: when feature flag is off, hide achievement routes/cards/listeners behind one composition helper so no scattered conditional logic across pages. +8. Backfill and migration recommendation: run one-time historical recompute job to award existing users fairly; mark job version so reruns are idempotent. +9. Observability recommendation: emit achievement engine metrics (rules evaluated, unlock count, rule errors, evaluation latency) and add dead-letter logging for malformed catalog entries. diff --git a/.vscode/mcp.json b/.vscode/mcp.json index a4615ef..dff126d 100644 --- a/.vscode/mcp.json +++ b/.vscode/mcp.json @@ -9,7 +9,20 @@ "--config=playwright.config.ts" ], "cwd": "frontend" + }, + "gitea": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "GITEA_ACCESS_TOKEN=${env:GITEA_ACCESS_TOKEN}", + "-e", + "GITEA_HOST=https://git.ryankegel.com", + "docker.gitea.com/gitea-mcp-server" + ], + "type": "stdio" } - }, - "inputs": [] + } } \ No newline at end of file diff --git a/frontend/vue-app/playwright-report/index.html b/frontend/vue-app/playwright-report/index.html new file mode 100644 index 0000000..000c039 --- /dev/null +++ b/frontend/vue-app/playwright-report/index.html @@ -0,0 +1,85 @@ + + + + +
+ + + +