Wang Zhuoxuan
cff1c148de
- implementation-plan.md 新增 Phase 1d Game Economy 索引 - 更新总体进度表、依赖图、成功标准 - 链接到 gamification-server-plan.md 和 GAMIFICATION_DESIGN.md - Success Criteria 新增游戏化相关验收条目
213 lines
10 KiB
Markdown
213 lines
10 KiB
Markdown
# 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`](./gamification-server-plan.md)，设计文档见 [`docs/GAMIFICATION_DESIGN.md`](./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
|
||
|
||
- [x] Guest and Huawei login both work returning valid JWTs
|
||
- [x] Seed script imports 50+ quiz questions with knowledge cards
|
||
- [x] Quiz engine delivers randomized questions without leaking answers
|
||
- [x] Answer submission validates correctness and updates XP/streak/hearts
|
||
- [x] Hearts system differentiates free vs Pro user behavior
|
||
- [x] Streak correctly handles daily reset and freeze
|
||
- [x] Skill tree progress tracks chapter unlock status
|
||
- [x] All admin CRUD endpoints work with real data
|
||
- [x] Leaderboard ranks users via live XP ranking
|
||
- [x] Achievements unlock based on user behavior
|
||
- [x] Huawei IAP verification works with subscription management
|
||
- [x] All endpoints have rate limiting and input validation
|
||
- [x] Challenge groups (5 questions per session) with idempotent submission
|
||
- [x] 50-level XP curve with combo bonus and streak milestone rewards
|
||
- [x] Coin economy: wallet, shop, item inventory, chest rewards
|
||
- [x] Ad recovery via unified reward ledger with idempotency
|
||
- [x] Weekly leaderboard with 20-30 user groups, top-3 coin rewards
|
||
- [x] Plus subscription: unlimited hearts, ad-free, subscription benefits in API response
|
||
- [ ] Test coverage >= 80% across all services (current: unit tests for core logic)
|
||
- [x] TypeScript strict mode compiles with zero errors
|