# 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
```

## 后续开发建议

- 增加课堂成绩记录和历史对局统计。
- 增加删除确认弹窗，避免误删。
- 引入本地音频文件，保证离线环境下发音稳定。