Initial English PK app

README.md

@@ -0,0 +1,109 @@
+# English PK
+
+English PK 是一个用于课堂单词 PK 的 Next.js 应用，包含课堂 PK 页面和后台管理页面。
+
+## 功能
+
+- PK 页面：选择年级和班级类型后开始比赛。
+- 后台管理：维护词库、中文释义、图标/图片、启用状态和班级类型。
+- SQLite 数据库：词库、班级类型、课堂规则和语音设置持久化存储。
+- Edge TTS：支持单词语音生成、试听和批量生成。
+- 课堂规则：可设置答对加分、答错扣分、每轮单词数量、选项数量、自动朗读和单词显示格式。
+- Docker 部署：支持一条命令启动，并持久化数据库与生成语音。
+
+## 技术栈
+
+- Next.js App Router
+- React
+- TypeScript
+- Tailwind CSS
+- shadcn 风格 UI 组件
+- SQLite (`node:sqlite`)
+- edge-tts-universal
+
+## 本地开发
+
+安装依赖：
+
+```bash
+npm install
+```
+
+启动开发服务：
+
+```bash
+npm run dev
+```
+
+访问：
+
+```text
+http://localhost:3000
+```
+
+常用页面：
+
+- PK 页面：`/pk`
+- 后台管理：`/admin`
+
+## 生产构建
+
+```bash
+npm run build
+npm run start
+```
+
+## Docker 部署
+
+默认使用 Docker Hub 加速镜像和 npm 镜像源：
+
+- Node 镜像：`m.daocloud.io/docker.io/library/node:22`
+- npm 源：`https://registry.npmmirror.com`
+
+启动：
+
+```bash
+docker compose up -d --build
+```
+
+访问：
+
+```text
+http://localhost:3000
+```
+
+如需切换镜像源：
+
+```bash
+NODE_IMAGE=node:22 docker compose up -d --build
+```
+
+如需切换 npm 源：
+
+```bash
+NPM_REGISTRY=https://registry.npmjs.org docker compose up -d --build
+```
+
+## 数据持久化
+
+Docker Compose 会挂载以下目录：
+
+- `./data:/app/data`：SQLite 数据库
+- `./public/audio:/app/public/audio`：生成的语音文件
+
+请备份这两个目录，避免迁移或重建服务器时丢失数据。
+
+## 配置说明
+
+后台管理中的「设置」包含：
+
+- 语音设置：Edge TTS 声音、语速、试听
+- 课堂规则：得分规则、显示单词数量、选项数量、自动朗读、单词大小写显示
+- 班级类型：新增、编辑、启停、删除
+- 页面预览：打开 PK 页面检查课堂展示效果
+
+## 注意事项
+
+- 项目依赖 `node:sqlite`，需要 Node.js 22 或更高版本。
+- 生成语音依赖网络访问 Edge TTS 服务。
+- 如果每轮题目数量为奇数，PK 页面会自动向下调整为偶数，保证两队轮流答题公平。