# CLAUDE.md — duoqi-api

> 多奇服务端 API，基于 Node.js + TypeScript + MySQL 8.0+

## 项目概述

多奇（Duoqi）是游戏化知识闯关学习平台。duoqi-api 是三端（HarmonyOS / Flutter / Web）共享的后端服务，从 Phase 1 起即为 HarmonyOS 客户端提供 API 支持。

## 设计文档

设计文档位于项目总目录的 `docs/` 中：

| 文档 | 路径 | 说明 |
|------|------|------|
| 本库开发规格 | [./dev-spec.md](./dev-spec.md) | **工程实施主文档，开发前必读** |
| 产品总纲 | [../docs/product-overview.md](../docs/product-overview.md) | 产品定位、功能范围 |
| 技术选型 | [../docs/tech-stack.md](../docs/tech-stack.md) | 全栈技术决策 |
| 共享设计文档 | [../docs/specs/shared/](../docs/specs/shared/) | 题目格式、游戏化、吉祥物、推送、埋点 |

### 关键共享文档快速索引

- [题目内容格式](../docs/specs/shared/question-format-design.md) — 数据模型、出题引擎、难度算法
- [游戏化 + 广告 + 商业方案](../docs/specs/shared/gamification-monetization-design.md) — XP/心/连胜/技能树规则、订阅定价
- [吉祥物设计规格](../docs/specs/shared/mascot-design.md) — 皮肤系统（Pro+ 权益）
- [推送通知策略](../docs/specs/shared/push-notification-design.md) — 通知触发逻辑
- [数据埋点与反馈](../docs/specs/shared/analytics-feedback-design.md) — 服务端事件

## 开发原则

详见 [dev-spec.md](./dev-spec.md) 获取完整上下文。

## 技术栈速查

- 语言：TypeScript (Node.js)
- 数据库：阿里云 RDS MySQL 8.0+
- 认证：自建 JWT（华为 ID Kit + 游客模式）
- 文件存储：阿里云 OSS
- 分析：PostHog 自托管（独立于业务库）