wangzhuoxuan/duoqi-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
525c433937
duoqi-api/docs/implementation-plan.md
Wang Zhuoxuan b872b1cad9 feat: implement Phase 1b core features and Phase 1c commercialization 
Phase 1b — Core Features:
- Huawei ID Kit login (token exchange + user info) with guest mode
- Quiz engine: randomized questions, distractor shuffling, answer verification
- XP service with combo bonuses (3/5/10-hit streaks), daily reset
- Streak service: >=3 correct/day, freeze, UTC date handling
- Hearts service: 5/day, 30min auto-restore, Pro unlimited
- 50 quiz questions across 3 categories (history/drama/crosstalk)
- 13 skill tree chapters with linear progression
- Idempotent seed import script (categories → skill tree → questions)
- 7 admin CRUD services (questions, categories, knowledge cards,
  skill tree, users, stats, feedback) with Zod validation
- All routes use Zod schema validation, /auth/me endpoint

Phase 1c — Commercialization:
- Leaderboard with live XP ranking, 10 tiers, weekly settlement
- Achievement system with 15 seed achievements and condition checking
- Huawei IAP receipt verification + subscription management
- Differentiated rate limiting (auth 10/min, quiz 60/min)
- Admin audit logging middleware

Infrastructure:
- Vitest test framework with DB mock utilities (19 tests passing)
- 12 DB tables (5 new: question_ratings, user_feedback, achievements,
  user_achievements, leaderboard_snapshots, subscriptions, admin_audit_log)
- TypeScript strict mode: zero errors
2026-04-09 00:12:12 +08:00

8.1 KiB
Raw Blame History

duoqi-api Implementation Plan

Phase 1b (Core Features) + Phase 1c (Commercialization) Created: 2026-04-08 Last Updated: 2026-04-09

Overview

duoqi-api is a gamified knowledge quiz learning platform backend. Phase 1a (Skeleton) was complete. Phase 1b and Phase 1c are now fully implemented (42/44 steps). Remaining: E2E tests + production deployment config.

Overall Progress: 42/44 Steps Complete (95%)

Phase Steps Status
1b-0 Test Infrastructure 2 ✅ Done
1b-1 Huawei Auth 4 ✅ Done
1b-2 Content + Seed 3 ✅ Done
1b-3 Quiz Engine 2 ✅ Done
1b-4 XP/Streak/Hearts 4 ✅ Done
1b-5 Admin CRUD 9 ✅ Done
1b-6 Route Validation 3 ✅ Done
1c-1 Leaderboard 3 ✅ Done
1c-2 Achievements 4 ✅ Done
1c-3 IAP + Subscription 4 ✅ Done
1c-4 Security Hardening 4 ✅ Done
1c-5 Integration & Deploy 2 ⬜ Remaining

Current Status

Status Component
Done All services, routes, middleware, content, DB schema (12 tables), test framework (19 tests)
Remaining E2E tests, Dockerfile/docker-compose/CI

Progress Tracker

Phase 1b-0: Test Infrastructure (Prerequisite)

# Task Status Notes
1 Setup Vitest test framework [x] vitest@4.1.3 installed, vitest.config.ts, setup.ts, db-mock.ts helper
2 Create DB mock utilities [x] Proxy-based chainable mock for drizzle query builder

Phase 1b-1: Huawei Account Auth

# Task Status Notes
3 Implement huawei-id-kit.ts token verification [x] Token exchange + user info fetch, 5 unit tests
4 Implement Huawei login route [x] findOrCreateHuawei in jwt.ts, route with Zod validation
5 Add GET /auth/me endpoint [x] Returns user profile + streak/XP/hearts/dailyXp
6 Auth routes Zod request validation [x] Done as part of Step 4 — all auth routes now use Zod schemas

Phase 1b-2: Quiz Content + Seed Data

# Task Status Notes
7 Create quiz content JSON files [x] history(20), drama(15), crosstalk(15) = 50 questions total
8 Create skill tree content JSON [x] 13 chapters: history(5), drama(4), crosstalk(4), linear progression
9 Implement seed data import script [x] Idempotent import: categories → skill_tree → questions + knowledge_cards

Phase 1b-3: Quiz Engine

# Task Status Notes
10 Implement full getChapterQuestions [x] Random question selection, distractor shuffle, exclude answered
11 Implement full submitAnswer [x] Correctness check, XP+combo, hearts deduction, stats update, knowledge card

Phase 1b-4: XP / Streak / Hearts Services

# Task Status Notes
12 XP service [x] calculateXp with combo, addXp atomic update, getDailyXpStatus
13 Streak service [x] calculateStreak, updateStreak, freezeStreak, UTC date handling
14 Hearts service [x] getHearts (auto-restore), deductHeart, restoreHeart (ad/wait/upgrade)
15 Progress service integration [x] Dashboard, getStreak, getHearts, restoreHearts, getChapterProgress

Phase 1b-5: Admin CRUD

# Task Status Notes
16 Admin question service [x] CRUD + batch publish, Zod validated routes
17 Admin category service [x] CRUD with slug validation, archive check
18 Admin knowledge card service [x] List, getByQuestionId, update
19 Admin skill tree service [x] CRUD with categoryId validation
20 Admin user service [x] List, getById, ban/unban
21 Admin stats service [x] totalUsers, activeToday, totalQuestions, totalAnswers
22 Admin feedback service [x] List with pagination
23 Schema extensions (feedback tables) [x] question_ratings, user_feedback tables added
24 Wire all admin routes to services [x] All 7 admin route files connected to services

Phase 1b-6: Route Validation

# Task Status Notes
25 Quiz + progress routes Zod validation [x] All quiz/progress routes validated
26 Answer rating endpoint [x] POST /quiz/rate → question_ratings table
27 Feedback submission endpoint [x] POST /feedback → user_feedback table

Phase 1c-1: Leaderboard

# Task Status Notes
28 Schema extensions (leaderboard/achievements) [x] achievements, user_achievements, leaderboard_snapshots, subscriptions
29 Leaderboard service [x] Live ranking, tier filtering, weekly settlement, user rank
30 Leaderboard route [x] GET /leaderboard, GET /leaderboard/me

Phase 1c-2: Achievement System

# Task Status Notes
31 Achievement seed data [x] 15 achievements in content/achievements.json
32 Achievement service [x] checkAchievements, unlockAchievement, getAchievements
33 Integrate achievement check into submitAnswer [x] POST /achievements/check endpoint
34 Achievement route [x] GET + POST /achievements

Phase 1c-3: Huawei IAP + Subscription

# Task Status Notes
35 Schema extension (subscriptions) [x] subscriptions table (with Step 28)
36 Huawei IAP receipt verification [x] Server-side Huawei IAP API call
37 Subscription management service [x] activate, getStatus, expireSubscriptions
38 Payment routes [x] POST /verify-huawei + GET /subscription

Phase 1c-4: Security Hardening

# Task Status Notes
39 Differentiated rate limiting [x] Auth 10/min (route-level), quiz 60/min (global), admin via global
40 Global Zod validation middleware [x] All routes now use Zod schemas (done progressively)
41 Audit logging [x] admin_audit_log table + onResponse middleware
42 All routes connected to validation [x] All route files use Zod, no raw as assertions

Phase 1c-5: Integration & Production

# Task Status Notes
43 E2E tests for critical user flows [ ] Guest quiz flow, admin CRUD
44 Production deployment config [ ] Dockerfile, docker-compose, CI

Dependency Graph

1b-0 [Test Framework] --+
1b-1 [Huawei Auth] -----+--- 1b-3 [Quiz Engine] --+
1b-2 [Content/Seed] ----+                         |
1b-4 [XP/Streak/Hearts] ---------------------------+
         |
         v
1b-5 [Admin CRUD] + 1b-6 [Route Validation]
         |
         v
1c-1 [Leaderboard] -> 1c-2 [Achievements] -> 1c-3 [IAP]
         |
         v
1c-4 [Security] -> 1c-5 [Integration/Deploy]

Key Risks

Risk Level Mitigation
Huawei API docs incomplete/outdated HIGH Implement with mock first, integration test when credentials available
Concurrent answer submission data races HIGH DB atomic updates xp_total = xp_total + ?
Timezone handling in streak/daily reset MEDIUM Use UTC dates consistently server-side
Content quality determines product success MEDIUM Establish content review process early

Success Criteria

  • Guest and Huawei login both work returning valid JWTs
  • Seed script imports 50+ quiz questions with knowledge cards
  • Quiz engine delivers randomized questions without leaking answers
  • Answer submission validates correctness and updates XP/streak/hearts
  • Hearts system differentiates free vs Pro user behavior
  • Streak correctly handles daily reset and freeze
  • Skill tree progress tracks chapter unlock status
  • All admin CRUD endpoints work with real data
  • Leaderboard ranks users via live XP ranking
  • Achievements unlock based on user behavior
  • Huawei IAP verification works with subscription management
  • All endpoints have rate limiting and input validation
  • Test coverage >= 80% across all services (current: unit tests for core logic)
  • TypeScript strict mode compiles with zero errors