199 lines
4.9 KiB
Markdown
199 lines
4.9 KiB
Markdown
# English PK 开发文档
|
||
|
||
## 项目简介
|
||
|
||
这是一个面向中班英语课堂的浏览器 Web 应用，已改造为 Next.js 项目。应用包含两个主要页面：
|
||
|
||
- `/pk`：课堂 PK 比赛页面。
|
||
- `/admin`：后台管理页面，使用 shadcn/ui 风格组件。
|
||
|
||
旧版单文件 HTML 与 Tauri 目录仍保留为历史参考，但当前主架构以 Next.js 和 SQLite 为准。
|
||
|
||
## 技术栈
|
||
|
||
- Next.js 16 App Router
|
||
- React 19
|
||
- TypeScript
|
||
- Tailwind CSS
|
||
- shadcn/ui 风格本地组件
|
||
- Sonner toast
|
||
- SQLite（Node `node:sqlite`）
|
||
- Edge TTS（`edge-tts-universal`）
|
||
- Web Speech API
|
||
- Web Audio API
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
englishPk/
|
||
├─ app/
|
||
│ ├─ layout.tsx # 全局布局和顶部导航
|
||
│ ├─ page.tsx # 根路径重定向到 /pk
|
||
│ ├─ globals.css # Tailwind 和 shadcn CSS 变量
|
||
│ ├─ pk/page.tsx # PK 比赛页面
|
||
│ ├─ admin/page.tsx # 后台管理页面
|
||
│ └─ api/ # SQLite CRUD API
|
||
├─ components/ui/ # shadcn 风格基础组件
|
||
├─ data/english-pk.sqlite # SQLite 数据库，运行时自动创建
|
||
├─ lib/db.ts # SQLite 建表、种子数据和 CRUD
|
||
├─ lib/utils.ts # cn 工具函数
|
||
├─ public/audio/ # Edge TTS 生成的单词音频
|
||
├─ components.json # shadcn 配置
|
||
├─ tailwind.config.ts # Tailwind 配置
|
||
├─ package.json # Next.js 开发脚本
|
||
├─ frontend/ # 旧 HTML/Tauri 前端入口，历史保留
|
||
└─ src-tauri/ # 旧 Tauri 桌面壳，历史保留
|
||
```
|
||
|
||
## 路由说明
|
||
|
||
### `/pk`
|
||
|
||
课堂比赛页面。主要功能：
|
||
|
||
- 进入页面后先选择年级和班级类型。
|
||
- 班级类型从 SQLite 数据库读取，只展示已启用项。
|
||
- 只从当前年级、班级类型且已启用的词库中出题。
|
||
- 朗读时优先播放数据库里的本地音频；没有音频时会尝试生成并入库，失败后回退到系统朗读。
|
||
- 红队、蓝队轮流答题。
|
||
- 每题 4 个选项。
|
||
- 答对加 10 分，答错不扣分。
|
||
- 使用浏览器语音能力朗读英文单词。
|
||
- 使用浏览器音频能力播放答对、答错提示音。
|
||
- 页面为左右布局，大屏左右分栏，小屏自动堆叠。
|
||
|
||
### `/admin`
|
||
|
||
后台管理页面。当前已接入 SQLite 持久化，包含：
|
||
|
||
- 词库总览。
|
||
- 启用词库数量统计。
|
||
- 年级、班级类型筛选和题库英语搜索。
|
||
- 词库新增、编辑、删除、中文、图标/图片配置和启用/停用。
|
||
- 可点击生成语音，服务端通过 Edge TTS 生成 mp3 并写回数据库。
|
||
- 可一键生成当前筛选词库的语音，并显示生成进度、成功数和失败数。
|
||
- 添加和编辑词库使用弹窗；编辑年级、班型或英语后会清空旧语音，需要重新生成。
|
||
- 设置使用弹窗，包含 Edge TTS 声音下拉、语速、试听、加分细则和课堂规则，并持久化到 SQLite。
|
||
- 操作反馈使用 Sonner toast。
|
||
- 班级类型新增、编辑、删除和启用/停用。
|
||
- 答对得分、自动朗读等课堂规则控件。
|
||
- 跳转 PK 页面入口。
|
||
|
||
## 本地开发
|
||
|
||
安装依赖：
|
||
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
启动开发服务：
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
访问页面：
|
||
|
||
```text
|
||
http://localhost:3000/pk
|
||
http://localhost:3000/admin
|
||
```
|
||
|
||
生产构建：
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
启动生产服务：
|
||
|
||
```bash
|
||
npm run start
|
||
```
|
||
|
||
## SQLite 数据库
|
||
|
||
数据库文件会在首次访问 API 时自动创建：
|
||
|
||
```text
|
||
data/english-pk.sqlite
|
||
```
|
||
|
||
数据库包含两张表：
|
||
|
||
```text
|
||
class_types
|
||
- id
|
||
- name
|
||
- enabled
|
||
- created_at
|
||
- updated_at
|
||
|
||
words
|
||
- id
|
||
- grade
|
||
- class_type_id
|
||
- english
|
||
- chinese
|
||
- image
|
||
- audio
|
||
- enabled
|
||
- created_at
|
||
- updated_at
|
||
|
||
settings
|
||
- key
|
||
- value
|
||
- updated_at
|
||
```
|
||
|
||
首次初始化会写入默认班级类型：
|
||
|
||
- 基础班
|
||
- 提高班
|
||
- 复习班
|
||
|
||
也会写入原始 12 个中班 XYZ 单词。
|
||
|
||
`words.image` 可填写 emoji、站内图片路径、外部图片地址或 `data:image/...`：
|
||
|
||
```text
|
||
🍎
|
||
/images/apple.png
|
||
https://example.com/apple.png
|
||
data:image/png;base64,...
|
||
```
|
||
|
||
`words.audio` 保存生成后的音频路径，例如：
|
||
|
||
```text
|
||
/audio/1-box.mp3
|
||
```
|
||
|
||
后台管理页点击某个词库项的麦克风按钮，会调用 Edge TTS 生成 mp3 到 `public/audio/`，然后把音频路径写入 SQLite。PK 页面朗读时会优先播放该音频；没有音频时才使用浏览器系统朗读作为兜底。
|
||
|
||
## API
|
||
|
||
```text
|
||
GET /api/words
|
||
POST /api/words
|
||
PUT /api/words/:id
|
||
DELETE /api/words/:id
|
||
POST /api/words/:id/generate-audio
|
||
|
||
GET /api/class-types
|
||
POST /api/class-types
|
||
PUT /api/class-types/:id
|
||
DELETE /api/class-types/:id
|
||
|
||
GET /api/settings
|
||
PUT /api/settings
|
||
```
|
||
|
||
## 后续开发建议
|
||
|
||
- 增加课堂成绩记录和历史对局统计。
|
||
- 增加删除确认弹窗，避免误删。
|
||
- 引入本地音频文件，保证离线环境下发音稳定。
|