duoqi-api Implementation Plan
Phase 1b (Core Features) + Phase 1c (Commercialization) + Phase 1d (Game Economy)
Created: 2026-04-08
Last Updated: 2026-05-13
Overview
duoqi-api is a gamified knowledge quiz learning platform backend. Phase 1a (Skeleton) was complete. Phase 1b and Phase 1c are fully implemented (42/44 steps). Phase 1d (Game Economy) is fully implemented (7 phases × ~7 tasks = 48 tasks). Remaining: E2E tests + production deployment config.
Overall Progress
| 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 |
| 1d Game Economy |
48 |
✅ Done |
Phase 1d: Game Economy (2026-05-11 ~ 2026-05-13)
详细计划见 docs/gamification-server-plan.md，设计文档见 docs/GAMIFICATION_DESIGN.md。
| Phase |
Tasks |
Description |
| G0 规则常量与数据模型 |
7/7 ✅ |
集中规则定义、挑战组/钱包/奖励流水/每日进度/周 XP 模型、迁移 |
| G1 挑战组与答题结算 |
7/7 ✅ |
创建挑战组、幂等答题、完成结算、红心扣除、高奖励次数、DTO、测试 |
| G2 XP/等级/连续学习 |
7/7 ✅ |
50 级曲线、XP 来源扩展、连对奖励、streak 按组、里程碑、首日红心、测试 |
| G3 金币/商店/道具 |
7/7 ✅ |
金币发放、宝箱、道具库存、商店购买、道具使用、DTO、测试 |
| G4 广告恢复与订阅 |
7/7 ✅ |
统一奖励结算、恢复规则确认、Plus 分支、旧接口废弃、回归测试 |
| G5 本周排行榜 |
6/6 ✅ |
本周 XP、周一刷新、20-30 人分组、前三奖励、元信息、测试 |
| G6 文档/Admin/运维 |
1/6 |
API 文档已更新；剩余：实施计划索引、Admin 查看、E2E、定时任务、最终验证 |
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]
|
v
1d-G0 [规则/模型] -> G1 [挑战组] -> G2 [XP/等级] -> G3 [金币/商店]
-> G4 [广告恢复] -> G5 [周榜] -> G6 [文档/运维]
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
Wang Zhuoxuan
cff1c148de