englishPk/DEVELOPMENT.md

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

目录结构

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 页面入口。

本地开发

安装依赖：

npm install

启动开发服务：

npm run dev

访问页面：

http://localhost:3000/pk
http://localhost:3000/admin

生产构建：

npm run build

启动生产服务：

npm run start

SQLite 数据库

数据库文件会在首次访问 API 时自动创建：

data/english-pk.sqlite

数据库包含两张表：

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/...：

🍎
/images/apple.png
https://example.com/apple.png
data:image/png;base64,...

words.audio 保存生成后的音频路径，例如：

/audio/1-box.mp3

后台管理页点击某个词库项的麦克风按钮，会调用 Edge TTS 生成 mp3 到 public/audio/，然后把音频路径写入 SQLite。PK 页面朗读时会优先播放该音频；没有音频时才使用浏览器系统朗读作为兜底。

API

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

后续开发建议

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