From 91c59c3ad9f948380508632427445084e724f759 Mon Sep 17 00:00:00 2001 From: goddonebianu Date: Sun, 8 Mar 2026 10:24:31 +0800 Subject: [PATCH] update AGENTS.md --- AGENTS.md | 2 +- README.md | 545 ++++++++++++++++++++++++++++++++++++------------------ 2 files changed, 365 insertions(+), 182 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a23755a..8be3c54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,4 +19,4 @@ pnpm build - Better-auth 处理会话管理 - 使用 authClient 适配器进行认证操作 - 组件尽量复用/src/design-system里的可复用组件与/src/components里的业务相关组件 - 不要创建index.ts -- 每变更一个完整项目自动git commit，如需就git reset +- 每变更一个完整项目自动git commit，如需撤销就git reset diff --git a/README.md b/README.md index 378f327..1149bc8 100644 --- a/README.md +++ b/README.md @@ -1,189 +1,372 @@ -# 多语言学习平台 +# 🌍 多语言学习平台 -一个基于 Next.js 构建的全功能多语言学习平台，提供翻译、发音、字幕播放、字母学习等多种语言学习工具，帮助用户更高效地掌握新语言。 +
-## ✨ 主要功能 +[![Next.js](https://img.shields.io/badge/Next.js-16.1.1-black?logo=next.js)](https://nextjs.org/) +[![React](https://img.shields.io/badge/React-19.2.3-61DAFB?logo=react)](https://reactjs.org/) +[![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-3178C6?logo=typescript)](https://www.typescriptlang.org/) +[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-Latest-336791?logo=postgresql)](https://www.postgresql.org/) +[![License](https://img.shields.io/badge/License-AGPL--3.0-blue)](./LICENSE) -- **智能翻译工具** - 支持多语言互译，包含国际音标(IPA)标注 -- **文本语音合成** - 将文本转换为自然语音，提高发音学习效果 -- **SRT字幕播放器** - 结合视频字幕学习，支持多种字幕格式 -- **字母学习模块** - 针对初学者的字母和发音基础学习 -- **记忆强化工具** - 通过科学记忆法巩固学习内容 -- **词典查询** - 查询单词和短语，提供详细释义和例句 -- **个人学习空间** - 用户可以创建、管理和组织自己的学习资料 -- **用户资料系统** - 支持用户名登录、个人资料页面展示 +**一个现代化的全栈多语言学习平台，集成 AI 驱动的翻译、发音、词典和学习管理功能** -## 🛠 技术栈 +[在线演示](#) · [报告问题](../../issues) · [功能建议](../../issues) -### 前端框架 -- **Next.js 16** - React 全栈框架，使用 App Router -- **React 19** - 用户界面构建 -- **TypeScript** - 类型安全的 JavaScript -- **Tailwind CSS** - 实用优先的 CSS 框架 - -### 数据与后端 -- **PostgreSQL** - 主数据库 -- **Prisma** - 现代数据库工具包和 ORM -- **better-auth** - 安全的身份验证系统 - -### 国际化与辅助功能 -- **next-intl** - 国际化解决方案 -- **阿里云千问 TTS** - qwen3-tts-flash 语音合成 - -### 开发工具 -- **ESLint** - 代码质量检查 -- **pnpm** - 高效的包管理器 - -## 📁 项目结构 - -``` -src/ -├── app/ # Next.js App Router 路由 -│ ├── (features)/ # 功能模块路由 -│ ├── auth/ # 认证相关页面 -│ ├── profile/ # 用户资料重定向 -│ ├── users/[username]/ # 用户资料页面 -│ ├── folders/ # 文件夹管理 -│ └── api/ # API 路由 -├── modules/ # 业务模块（action-service-repository 架构） -│ ├── auth/ # 认证模块 -│ ├── folder/ # 文件夹模块 -│ ├── dictionary/ # 词典模块 -│ └── translator/ # 翻译模块 -├── components/ # React 组件 -│ ├── buttons/ # 按钮组件 -│ ├── cards/ # 卡片组件 -│ └── ... -├── lib/ # 工具函数和库 -│ ├── actions/ # Server Actions -│ ├── browser/ # 浏览器端工具 -│ └── server/ # 服务器端工具 -├── hooks/ # 自定义 React Hooks -├── i18n/ # 国际化配置 -├── shared/ # 共享常量和类型 -└── config/ # 应用配置 -``` - -## 🚀 快速开始 - -### 环境要求 - -- Node.js 23 -- PostgreSQL 数据库 -- pnpm (推荐) 或 npm - -### 本地开发 - -1. 克隆项目 -```bash -git clone -cd learn-languages -``` - -2. 安装依赖 -```bash -pnpm install -``` - -3. 设置环境变量 - -从项目提供的示例文件复制环境变量模板： - -```bash -cp .env.example .env.local -``` - -然后编辑 `.env.local` 文件，配置所有必要的环境变量： - -```env -# LLM 集成（智谱 AI 用于翻译和 IPA 生成） -ZHIPU_API_KEY=your-zhipu-api-key -ZHIPU_MODEL_NAME=your-zhipu-model-name - -# 阿里云千问 TTS（文本转语音） -DASHSCORE_API_KEY=your-dashscore-api-key - -# 认证 -BETTER_AUTH_SECRET=your-better-auth-secret -BETTER_AUTH_URL=http://localhost:3000 -GITHUB_CLIENT_ID=your-github-client-id -GITHUB_CLIENT_SECRET=your-github-client-secret - -# 数据库 -DATABASE_URL=postgresql://username:password@localhost:5432/database_name -``` - -注意：所有带 `your-` 前缀的值需要替换为你的实际配置。 - -4. 初始化数据库 -```bash -pnpm prisma generate -pnpm prisma db push -``` - -5. 启动开发服务器 -```bash -pnpm run dev -``` - -访问 [http://localhost:3000](http://localhost:3000) 查看应用。 - -## 📚 API 文档 - -### 认证系统 - -应用使用 better-auth 提供安全的用户认证系统，支持： -- 邮箱/密码登录和注册 -- **用户名登录**（可通过用户名或邮箱登录） -- GitHub OAuth 第三方登录 -- 邮箱验证功能 - -### 后端架构 - -项目采用 **Action-Service-Repository 三层架构**： -- **Action 层**：处理 Server Actions、表单验证、重定向 -- **Service 层**：业务逻辑、better-auth 集成 -- **Repository 层**：Prisma 数据库操作 - -### 数据模型 - -核心数据模型包括： -- **User** - 用户信息（支持用户名、邮箱、头像） -- **Folder** - 学习资料文件夹 -- **Pair** - 语言对（翻译对、词汇对等） -- **Session/Account** - 认证会话追踪 -- **Verification** - 邮箱验证系统 - -详细模型定义请参考 [prisma/schema.prisma](./prisma/schema.prisma) - -## 🌍 国际化 - -应用支持多语言，当前语言文件位于 `messages/` 目录。添加新语言： - -1. 在 `messages/` 目录创建对应语言的 JSON 文件 -2. 在 `src/i18n/config.ts` 中添加语言配置 - -## 🤝 贡献指南 - -我们欢迎各种形式的贡献！请遵循以下步骤： - -1. Fork 项目 -2. 创建功能分支 (`git checkout -b feature/AmazingFeature`) -3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) -4. 推送到分支 (`git push origin feature/AmazingFeature`) -5. 打开 Pull Request - -## 📄 许可证 - -本项目采用 AGPL-3.0 许可证 - 查看 [LICENSE](./LICENSE) 文件了解详情。 - -## 📞 支持 - -如果您遇到问题或有建议，请通过以下方式联系： - -- 提交 [Issue](../../issues) -- 发送邮件至 [goddonebianu@outlook.com] +
--- -**Happy Learning!** 🌟 +## ✨ 核心特性 + +### 🎯 学习工具 +- **智能翻译** - 基于 AI 的多语言互译，支持 IPA 音标标注 +- **词典查询** - 详细的单词释义、词性分析、例句展示 +- **语音合成** - 阿里云千问 TTS 提供自然的语音输出 +- **个人学习空间** - 文件夹管理、学习资料组织 + +### 🔐 用户系统 +- **多方式认证** - 邮箱/用户名登录、GitHub OAuth +- **个人资料** - 用户主页、学习进度追踪 +- **数据安全** - better-auth 提供企业级安全保障 + +### 🌐 国际化 +- **8 种语言** - en-US, zh-CN, ja-JP, ko-KR, de-DE, fr-FR, it-IT, ug-CN +- **完整本地化** - 所有界面文本支持多语言 + +### 🏗️ 技术亮点 +- **App Router** - 采用 Next.js 16 最新路由系统 +- **Server Components** - 优先服务端渲染，优化性能 +- **Action-Service-Repository** - 清晰的三层架构设计 +- **类型安全** - TypeScript 严格模式 + Zod 验证 + +--- + +## 🚀 快速开始 + +### 前置要求 + +- Node.js 23+ +- PostgreSQL 14+ +- pnpm 8+ (推荐) 或 npm/yarn + +### 安装步骤 + +```bash +# 1. 克隆项目 +git clone +cd learn-languages + +# 2. 安装依赖 +pnpm install + +# 3. 配置环境变量 +cp .env.example .env.local +# 编辑 .env.local 填写必要配置 + +# 4. 初始化数据库 +pnpm prisma generate +pnpm prisma db push + +# 5. 启动开发服务器 +pnpm dev +``` + +访问 **http://localhost:3000** 开始使用！ + +### 环境变量配置 + +```env +# 🤖 AI 服务（必需） +ZHIPU_API_KEY=your-api-key # 智谱 AI - 翻译和词典 +ZHIPU_MODEL_NAME=your-model-name # 模型名称 +DASHSCORE_API_KEY=your-api-key # 阿里云 TTS + +# 🔐 认证配置（必需） +BETTER_AUTH_SECRET=your-secret # 随机字符串 +BETTER_AUTH_URL=http://localhost:3000 + +# 🐙 GitHub OAuth（可选） +GITHUB_CLIENT_ID=your-client-id +GITHUB_CLIENT_SECRET=your-client-secret + +# 💾 数据库（必需） +DATABASE_URL=postgresql://user:password@localhost:5432/dbname +``` + +--- + +## 🛠️ 技术栈 + + + + + + +
+ +### 前端 +- **Next.js 16** - App Router +- **React 19** - UI 框架 +- **TypeScript 5.9** - 类型安全 +- **Tailwind CSS 4** - 样式方案 +- **Zustand** - 状态管理 +- **next-intl** - 国际化 + + + +### 后端 +- **PostgreSQL** - 关系数据库 +- **Prisma 7** - ORM +- **better-auth** - 认证系统 +- **智谱 AI** - LLM 服务 +- **阿里云 TTS** - 语音合成 + +
+ +--- + +## 📁 项目架构 + +``` +learn-languages/ +├── 📂 src/ +│ ├── 📂 app/ # Next.js App Router +│ │ ├── 📂 (auth)/ # 认证相关页面 +│ │ ├── 📂 folders/ # 文件夹管理 +│ │ ├── 📂 users/[username]/ # 用户资料 +│ │ └── 📂 api/ # API 路由 +│ │ +│ ├── 📂 modules/ # 业务模块（三层架构） +│ │ ├── 📂 auth/ # 认证模块 +│ │ ├── 📂 folder/ # 文件夹模块 +│ │ ├── 📂 dictionary/ # 词典模块 +│ │ └── 📂 translator/ # 翻译模块 +│ │ +│ ├── 📂 components/ # React 组件 +│ │ ├── 📂 ui/ # 通用 UI 组件 +│ │ └── 📂 layout/ # 布局组件 +│ │ +│ ├── 📂 design-system/ # 设计系统 +│ │ ├── 📂 base/ # 基础组件 +│ │ ├── 📂 layout/ # 布局组件 +│ │ └── 📂 feedback/ # 反馈组件 +│ │ +│ ├── 📂 lib/ # 工具库 +│ │ ├── 📂 bigmodel/ # AI 集成 +│ │ ├── 📂 browser/ # 浏览器工具 +│ │ └── 📂 server/ # 服务端工具 +│ │ +│ ├── 📂 hooks/ # 自定义 Hooks +│ ├── 📂 i18n/ # 国际化配置 +│ ├── 📂 shared/ # 共享类型和常量 +│ └── 📂 config/ # 应用配置 +│ +├── 📂 prisma/ # 数据库 Schema +├── 📂 messages/ # 多语言文件 +└── 📂 public/ # 静态资源 +``` + +### 架构设计：Action-Service-Repository + +``` +┌─────────────────────────────────────────┐ +│ Presentation Layer │ +│ (Server Components / Client Components)│ +└────────────────┬────────────────────────┘ + │ +┌────────────────▼────────────────────────┐ +│ Action Layer │ +│ • Server Actions │ +│ • Form Validation (Zod) │ +│ • Redirect & Error Handling │ +└────────────────┬────────────────────────┘ + │ +┌────────────────▼────────────────────────┐ +│ Service Layer │ +│ • Business Logic │ +│ • better-auth Integration │ +│ • Cross-module Coordination │ +└────────────────┬────────────────────────┘ + │ +┌────────────────▼────────────────────────┐ +│ Repository Layer │ +│ • Prisma Database Operations │ +│ • Data Access Abstraction │ +│ • Query Optimization │ +└─────────────────────────────────────────┘ +``` + +--- + +## 📚 核心模块 + +### 认证系统 (auth) + +```typescript +// 支持多种登录方式 +- 邮箱/密码登录 +- 用户名登录 +- GitHub OAuth +- 邮箱验证 +``` + +### 翻译模块 (translator) + +```typescript +// AI 驱动的智能翻译 +- 多语言互译 +- IPA 音标标注 +- 翻译历史记录 +- 上下文理解 +``` + +### 词典模块 (dictionary) + +```typescript +// 智能词典查询 +- 单词释义 +- 词性分析 +- 例句展示 +- 词频统计 +``` + +### 文件夹模块 (folder) + +```typescript +// 学习资料管理 +- 创建/删除文件夹 +- 添加语言对 +- IPA 标注 +- 批量管理 +``` + +--- + +## 🗄️ 数据模型 + +核心数据模型关系： + +``` +User (用户) + ├─ Account (账户) + ├─ Session (会话) + ├─ Folder (文件夹) + │ └─ Pair (语言对) + ├─ DictionaryLookUp (查询记录) + │ └─ DictionaryItem (词典项) + │ └─ DictionaryEntry (词条) + └─ TranslationHistory (翻译历史) +``` + +详细模型定义：[prisma/schema.prisma](./prisma/schema.prisma) + +--- + +## 🌍 国际化支持 + +当前支持的语言： + +| 语言 | 代码 | 区域 | +|------|------|------| +| English | en-US | 美国 | +| 中文 | zh-CN | 中国 | +| 日本語 | ja-JP | 日本 | +| 한국어 | ko-KR | 韩国 | +| Deutsch | de-DE | 德国 | +| Français | fr-FR | 法国 | +| Italiano | it-IT | 意大利 | +| ئۇيغۇرچە | ug-CN | 新疆 | + +添加新语言： + +1. 在 `messages/` 创建语言文件 +2. 在 `src/i18n/config.ts` 添加配置 +3. 更新语言选择器组件 + +--- + +## 🔧 开发指南 + +### 可用脚本 + +```bash +# 开发 +pnpm dev # 启动开发服务器 (HTTPS) +pnpm build # 构建生产版本 +pnpm start # 启动生产服务器 +pnpm lint # 代码检查 + +# 数据库 +pnpm prisma studio # 打开数据库 GUI +pnpm prisma db push # 同步 Schema +pnpm prisma migrate # 创建迁移 +``` + +### 代码规范 + +- ✅ TypeScript 严格模式 +- ✅ ESLint + TypeScript Plugin +- ✅ 优先使用 Server Components +- ✅ 新功能遵循 Action-Service-Repository +- ✅ 所有用户文本需要国际化 +- ✅ 组件复用设计系统和业务组件 + +### 目录约定 + +- `modules/` - 业务模块，每个模块包含： + - `*-action.ts` - Server Actions + - `*-service.ts` - 业务逻辑 + - `*-repository.ts` - 数据访问 + - `*-dto.ts` - 数据传输对象 +- `components/` - 业务相关组件 +- `design-system/` - 可复用基础组件 +- `lib/` - 工具函数和库 + +--- + +## 🤝 贡献指南 + +我们欢迎各种贡献！ + +### 贡献流程 + +1. Fork 本仓库 +2. 创建功能分支 (`git checkout -b feature/AmazingFeature`) +3. 提交更改 (`git commit -m 'Add: AmazingFeature'`) +4. 推送到分支 (`git push origin feature/AmazingFeature`) +5. 开启 Pull Request + +### 代码提交规范 + +``` +feat: 新功能 +fix: 修复问题 +docs: 文档变更 +style: 代码格式 +refactor: 重构 +test: 测试相关 +chore: 构建/工具 +``` + +--- + +## 📄 许可证 + +本项目采用 [AGPL-3.0](./LICENSE) 许可证。 + +--- + +## 📞 联系方式 + +- **问题反馈**：[GitHub Issues](../../issues) +- **邮箱**：goddonebianu@outlook.com + +--- + +
+ +**如果这个项目对你有帮助，请给一个 ⭐️ Star！** + +Made with ❤️ by the community + +