# 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