diff --git a/CLAUDE.md b/CLAUDE.md index 7d78dc4..0e34c27 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,7 +15,8 @@ | ORM | **Drizzle ORM** | 轻量、类型安全,`src/db/schema.ts` 为唯一真相源 | | 数据库 | MySQL 8.0+ | 阿里云 RDS | | 认证 | @fastify/jwt | 自建 JWT(华为 ID Kit + 游客模式) | -| 校验 | Zod | 环境变量校验;请求体校验待迁移至 Fastify JSON Schema | +| 校验 | Zod | 环境变量 + 请求体校验(所有路由已接入 Zod) | +| 测试 | Vitest | 单元测试框架,19 个测试全部通过 | | 运行时 | Node.js (ESM) | `"type": "module"`,import 使用 `.js` 后缀 | ## Quick Start @@ -34,10 +35,11 @@ bun run dev # 启动开发服务器,默认端口 3000 bun run dev # 启动开发服务器(tsx watch 热重载) bun run typecheck # 类型检查(tsc --noEmit) bun run build # 编译到 dist/ +bun run test # 运行测试(vitest run) bun run db:push # 推送 schema 到数据库(开发用) bun run db:generate # 生成迁移文件 bun run db:migrate # 执行迁移 -bun run db:seed # 导入种子数据 +bun run db:seed # 导入种子数据(分类 → 技能树 → 题目 → 成就) bun run db:studio # Drizzle Studio(数据库可视化浏览器) bun run lint # ESLint 检查 ``` @@ -49,7 +51,7 @@ src/ ├── index.ts # 入口:Fastify 实例 + 插件注册 + 路由挂载 ├── db/ │ ├── client.ts # 数据库连接(mysql2 pool + drizzle) -│ └── schema.ts # 全部表定义(唯一真相源) +│ └── schema.ts # 全部 14 张表定义(唯一真相源) ├── types/ # TypeScript 类型(auth, quiz, user, api) ├── utils/ │ ├── config.ts # 环境变量(Zod 校验,启动时 fail-fast) @@ -57,19 +59,31 @@ src/ ├── middleware/ │ ├── auth.ts # JWT 认证(排除公开路径和 admin 路径) │ ├── admin-auth.ts # Admin token 认证(/v1/admin/* 路径) +│ ├── audit-log.ts # Admin 操作审计日志 │ └── request-logger.ts # 请求耗时日志 ├── services/ # 业务逻辑(按领域分目录) │ ├── auth/ # jwt, guest, huawei-id-kit, phone -│ ├── quiz/ # quiz-service(出题引擎) +│ ├── quiz/ # quiz-service(出题引擎 + 答题验证) │ ├── progress/ # progress, streak, xp, hearts │ ├── gamification/ # leaderboard, achievement -│ └── payment/ # huawei-iap -└── routes/ # 路由(薄层,调 service) - ├── health.ts, auth.ts, quiz.ts, progress.ts - ├── gamification.ts, payment.ts - └── admin/ # 管理端路由(duoqi-admin 调用) - └── index, auth, questions, categories, knowledge-cards, - skill-tree, users, stats, feedback +│ ├── payment/ # huawei-iap, subscription-service +│ └── admin/ # 7 个管理端 CRUD 服务 +│ └── question, category, knowledge-card, skill-tree, +│ user, stats, feedback +├── routes/ # 路由(薄层,调 service + Zod 校验) +│ ├── health.ts, auth.ts, quiz.ts, progress.ts +│ ├── gamification.ts, payment.ts +│ └── admin/ # 管理端路由(duoqi-admin 调用) +│ └── index, auth, questions, categories, knowledge-cards, +│ skill-tree, users, stats, feedback +└── __tests__/ # 测试(Vitest + DB mock) + ├── setup.ts, smoke.test.ts + ├── helpers/db-mock.ts + └── services/ # 单元测试(auth, quiz, progress) +content/ # 种子数据(JSON) +├── categories.json, skill-tree.json, achievements.json +├── history.json, drama.json, crosstalk.json +db/seeds/index.ts # 幂等种子导入脚本 ``` ## 编码约定 @@ -91,7 +105,12 @@ src/ ## 数据库 -- 7 张核心表:`users`, `categories`, `questions`, `knowledge_cards`, `user_progress`, `skill_tree`, `user_chapter_progress` +- **14 张表**,定义在 `src/db/schema.ts` +- 核心(7):`users`, `categories`, `questions`, `knowledge_cards`, `user_progress`, `skill_tree`, `user_chapter_progress` +- 反馈(2):`question_ratings`, `user_feedback` +- 游戏化(3):`achievements`, `user_achievements`, `leaderboard_snapshots` +- 商业(1):`subscriptions` +- 审计(1):`admin_audit_log` - Schema 定义在 `src/db/schema.ts`,迁移由 `drizzle-kit` 从 schema 自动生成 - `datetime` 列使用 `default(sql\`CURRENT_TIMESTAMP\`)`(MySQL datetime 无 `defaultNow()`) @@ -99,6 +118,7 @@ src/ | 文档 | 路径 | 说明 | |------|------|------| +| 实施计划 | [./docs/implementation-plan.md](./docs/implementation-plan.md) | Phase 1b/1c 实施进度(42/44 步) | | 本库开发规格 | [./dev-spec.md](./dev-spec.md) | 工程实施主文档 | | 产品总纲 | [../docs/product-overview.md](../docs/product-overview.md) | 产品定位、功能范围 | | 技术选型 | [../docs/tech-stack.md](../docs/tech-stack.md) | 全栈技术决策 | @@ -106,6 +126,7 @@ src/ ## 当前进度 -- **Phase 1a 骨架**:已完成(项目结构、数据库 schema、路由框架、中间件) -- **Phase 1b 核心功能**:待实现(华为登录、出题引擎、XP/连胜/心、技能树) -- **Phase 1c 商业化**:待实现(排行榜、成就、华为 IAP、安全加固) +- **Phase 1a 骨架**:✅ 已完成 +- **Phase 1b 核心功能**:✅ 已完成(华为登录、出题引擎、XP/连胜/红心、技能树、Admin CRUD、路由验证) +- **Phase 1c 商业化**:✅ 已完成(排行榜、成就系统、华为 IAP + 订阅、安全加固) +- **Phase 1c-5 集成部署**:⬜ 待完成(E2E 测试、Dockerfile/CI) diff --git a/dev-spec.md b/dev-spec.md index 7b8126d..bdb7e93 100644 --- a/dev-spec.md +++ b/dev-spec.md @@ -10,4 +10,4 @@ --- *创建日期:2026-04-04* -*状态:Phase 1 待启动开发* +*状态:Phase 1b + 1c 已完成(42/44 步),剩余 E2E 测试 + 生产部署配置*