update AGENTS.md
This commit is contained in:
@@ -19,4 +19,4 @@ pnpm build
|
||||
- Better-auth 处理会话管理 - 使用 authClient 适配器进行认证操作
|
||||
- 组件尽量复用/src/design-system里的可复用组件与/src/components里的业务相关组件
|
||||
- 不要创建index.ts
|
||||
- 每变更一个完整项目自动git commit，如需就git reset
|
||||
- 每变更一个完整项目自动git commit，如需撤销就git reset
|
||||
|
||||
545
README.md
545
README.md
@@ -1,189 +1,372 @@
|
||||
# 多语言学习平台
|
||||
# 🌍 多语言学习平台
|
||||
|
||||
一个基于 Next.js 构建的全功能多语言学习平台，提供翻译、发音、字幕播放、字母学习等多种语言学习工具，帮助用户更高效地掌握新语言。
|
||||
<div align="center">
|
||||
|
||||
## ✨ 主要功能
|
||||
[](https://nextjs.org/)
|
||||
[](https://reactjs.org/)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](https://www.postgresql.org/)
|
||||
[](./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 <repository-url>
|
||||
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]
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
**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 <repository-url>
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠️ 技术栈
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="50%">
|
||||
|
||||
### 前端
|
||||
- **Next.js 16** - App Router
|
||||
- **React 19** - UI 框架
|
||||
- **TypeScript 5.9** - 类型安全
|
||||
- **Tailwind CSS 4** - 样式方案
|
||||
- **Zustand** - 状态管理
|
||||
- **next-intl** - 国际化
|
||||
|
||||
</td>
|
||||
<td width="50%">
|
||||
|
||||
### 后端
|
||||
- **PostgreSQL** - 关系数据库
|
||||
- **Prisma 7** - ORM
|
||||
- **better-auth** - 认证系统
|
||||
- **智谱 AI** - LLM 服务
|
||||
- **阿里云 TTS** - 语音合成
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
---
|
||||
|
||||
## 📁 项目架构
|
||||
|
||||
```
|
||||
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
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**如果这个项目对你有帮助，请给一个 ⭐️ Star！**
|
||||
|
||||
Made with ❤️ by the community
|
||||
|
||||
</div>
|
||||
|
||||
Reference in New Issue
Block a user