diff --git a/CLAUDE.md b/CLAUDE.md index 107760f..537d1cf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,124 +1,19 @@ # CLAUDE.md -本文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。 - -## 项目概述 - -这是一个基于 Next.js 16 构建的全栈语言学习平台，提供翻译工具、文本转语音、字幕播放、字母学习和记忆功能。平台支持 8 种语言，具有完整的国际化支持。 - -## 开发命令 - ```bash -# 启动开发服务器（启用 HTTPS） -pnpm run dev - -# 构建生产版本（standalone 输出模式，用于 Docker） +# 使用以下命令检查代码合法性 pnpm run build - -# 启动生产服务器 -pnpm run start - -# 代码检查 -pnpm run lint - -# 数据库操作 -# 不要进行数据库操作，让用户操作数据库 ``` -## 技术栈 - **Next.js 16** 使用 App Router 和 standalone 输出模式 - **React 19** 启用 React Compiler 进行优化 - **TypeScript** 严格模式和 ES2023 目标 - **Tailwind CSS v4** 样式框架 - **PostgreSQL** + **Prisma ORM**（自定义输出目录：`src/generated/prisma`） -- **better-auth** 身份验证（邮箱/密码 + OAuth） +- **better-auth** 身份验证（邮箱/密码） - **next-intl** 国际化（支持：en-US, zh-CN, ja-JP, ko-KR, de-DE, fr-FR, it-IT, ug-CN） - **阿里云千问 TTS** (qwen3-tts-flash) 文本转语音 -- **pnpm** 包管理器 - -## 架构设计 - -### 路由结构 - -应用使用 Next.js App Router 和基于功能的组织方式： - -``` -src/app/ -├── (features)/ # 功能模块（translator, alphabet, memorize, dictionary, srt-player） -│ └── [locale]/ # 国际化路由 -├── auth/ # 认证页面（sign-in, sign-up） -├── folders/ # 用户学习文件夹管理 -├── users/[username]/# 用户资料页面（Server Component） -├── profile/ # 重定向到当前用户的资料页面 -└── api/ # API 路由 -``` - -### 后端架构模式 - -项目使用 **Action-Service-Repository 三层架构**： - -``` -src/modules/{module}/ -├── {module}-action.ts # Server Actions 层（表单处理、重定向） -├── {module}-action-dto.ts # Action 层 DTO（Zod 验证） -├── {module}-service.ts # Service 层（业务逻辑） -├── {module}-service-dto.ts # Service 层 DTO -├── {module}-repository.ts # Repository 层（数据库操作） -└── {module}-repository-dto.ts # Repository 层 DTO -``` - -各层职责： -- **Action 层**：处理表单数据、验证输入、调用 service 层、处理重定向和错误响应 -- **Service 层**：实现业务逻辑、调用 better-auth API、协调多个 repository 操作 -- **Repository 层**：直接使用 Prisma 进行数据库查询和操作 - -现有模块： -- `auth` - 认证和用户管理（支持用户名/邮箱登录） -- `folder` - 学习文件夹管理 -- `dictionary` - 词典查询 -- `translator` - 翻译服务 - -### 数据库 Schema - -核心模型（见 [prisma/schema.prisma](prisma/schema.prisma)）： -- **User**: 用户中心实体，包含认证信息 -- **Folder**: 用户拥有的学习资料容器（级联删除 pairs） -- **Pair**: 语言对（翻译/词汇），支持 IPA，唯一约束为 (folderId, locale1, locale2, text1) -- **Session/Account**: better-auth 追踪 -- **Verification**: 邮箱验证系统 - -### 核心模式 - -**Server Actions**: 数据库变更使用 `src/lib/actions/` 中的 Server Actions，配合类型安全的 Prisma 操作。 - -**基于功能的组件**: 每个功能在 `(features)/` 下有自己的路由组，带有 locale 前缀。 - -**国际化**: 所有面向用户的内容通过 next-intl 处理。消息文件在 `messages/` 目录。locale 自动检测并在路由中前缀。 - -**认证流程**: better-auth 使用客户端适配器 (`authClient`)，通过 hooks 管理会话，受保护的路由使用条件渲染。 - -**LLM 集成**: 使用智谱 AI API 进行翻译和 IPA 生成。通过环境变量 `ZHIPU_API_KEY` 和 `ZHIPU_MODEL_NAME` 配置。 - -- **Standalone 输出**: 为 Docker 部署配置 -- **React Compiler**: 在 `next.config.ts` 中启用以自动优化 -- **HTTPS 开发**: 开发服务器使用 `--experimental-https` 标志 -- **图片优化**: 通过 remote patterns 允许 GitHub 头像 - -## 代码组织 - -- `src/modules/`: 业务模块（auth, folder, dictionary, translator） -- `src/lib/actions/`: 数据库变更的 Server Actions（旧架构，正在迁移到 modules） -- `src/lib/server/`: 服务端工具（AI 集成、认证、翻译器） -- `src/lib/browser/`: 客户端工具 -- `src/hooks/`: 自定义 React hooks（认证 hooks、会话管理） -- `src/i18n/`: 国际化配置 -- `messages/`: 各支持语言的翻译文件 -- `src/components/`: 可复用的 UI 组件（buttons, cards 等） -- `src/shared/`: 共享常量和类型定义 - -## 开发注意事项 - - 使用 pnpm，而不是 npm 或 yarn - 应用使用 TypeScript 严格模式 - 确保类型安全 - 所有面向用户的文本都需要国际化 diff --git a/package.json b/package.json index 1b38dcf..5fffbc7 100644 --- a/package.json +++ b/package.json @@ -27,7 +27,8 @@ "sonner": "^2.0.7", "tailwind-merge": "^3.4.0", "unstorage": "^1.17.3", - "zod": "^4.3.5" + "zod": "^4.3.5", + "zustand": "^5.0.11" }, "devDependencies": { "@better-auth/cli": "^1.4.10", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c10ac22..d5d51bb 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -63,6 +63,9 @@ importers: zod: specifier: ^4.3.5 version: 4.3.5 + zustand: + specifier: ^5.0.11 + version: 5.0.11(@types/react@19.2.7)(react@19.2.3) devDependencies: '@better-auth/cli': specifier: ^1.4.10 @@ -3292,6 +3295,24 @@ packages: zod@4.3.5: resolution: {integrity: sha512-k7Nwx6vuWx1IJ9Bjuf4Zt1PEllcwe7cls3VNzm4CQ1/hgtFUK2bRNG3rvnpPUhFjmqJKAKtjV576KnUkHocg/g==} + zustand@5.0.11: + resolution: {integrity: sha512-fdZY+dk7zn/vbWNCYmzZULHRrss0jx5pPFiOuMZ/5HJN6Yv3u+1Wswy/4MpZEkEGhtNH+pwxZB8OKgUBPzYAGg==} + engines: {node: '>=12.20.0'} + peerDependencies: + '@types/react': 19.2.7 + immer: '>=9.0.6' + react: '>=18.0.0' + use-sync-external-store: '>=1.2.0' + peerDependenciesMeta: + '@types/react': + optional: true + immer: + optional: true + react: + optional: true + use-sync-external-store: + optional: true + snapshots: '@alloc/quick-lru@5.2.0': {} @@ -6682,3 +6703,8 @@ snapshots: zod: 4.3.5 zod@4.3.5: {} + + zustand@5.0.11(@types/react@19.2.7)(react@19.2.3): + optionalDependencies: + '@types/react': 19.2.7 + react: 19.2.3