wangzhuoxuan/duoqi-api
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
main
duoqi-api/docs/implementation-plan.md
Wang Zhuoxuan cff1c148de 更新实施计划索引添加 Game Economy 阶段 
- implementation-plan.md 新增 Phase 1d Game Economy 索引
- 更新总体进度表、依赖图、成功标准
- 链接到 gamification-server-plan.md 和 GAMIFICATION_DESIGN.md
- Success Criteria 新增游戏化相关验收条目
2026-05-13 22:20:07 +08:00

10 KiB
Raw Permalink Blame History

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

  • 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
  • Challenge groups (5 questions per session) with idempotent submission
  • 50-level XP curve with combo bonus and streak milestone rewards
  • Coin economy: wallet, shop, item inventory, chest rewards
  • Ad recovery via unified reward ledger with idempotency
  • Weekly leaderboard with 20-30 user groups, top-3 coin rewards
  • Plus subscription: unlimited hearts, ad-free, subscription benefits in API response
  • Test coverage >= 80% across all services (current: unit tests for core logic)
  • TypeScript strict mode compiles with zero errors