Initial English PK app
This commit is contained in:
+198
@@ -0,0 +1,198 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
## 后续开发建议
|
||||
|
||||
- 增加课堂成绩记录和历史对局统计。
|
||||
- 增加删除确认弹窗，避免误删。
|
||||
- 引入本地音频文件，保证离线环境下发音稳定。
|
||||
Reference in New Issue
Block a user