docs: sync project progress across CLAUDE.md and dev-spec.md
- CLAUDE.md: update project structure (14 tables, admin services, tests, content dir, audit-log middleware, subscription-service) - CLAUDE.md: update tech stack (Zod validated routes, Vitest tests) - CLAUDE.md: add test command to dev commands - CLAUDE.md: update database section (7 → 14 tables with categories) - CLAUDE.md: add implementation-plan.md to docs table - CLAUDE.md: update progress (1a/1b/1c done, 1c-5 remaining) - dev-spec.md: update status from "待启动开发" to actual progress
This commit is contained in:
parent
b872b1cad9
commit
00d9731f06
51
CLAUDE.md
51
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）
|
||||
|
||||
@ -10,4 +10,4 @@
|
||||
---
|
||||
|
||||
*创建日期：2026-04-04*
|
||||
*状态：Phase 1 待启动开发*
|
||||
*状态：Phase 1b + 1c 已完成（42/44 步），剩余 E2E 测试 + 生产部署配置*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user