Initial commit: WordLoop 单词学习应用

Vue 前端 + FastAPI 后端，含部署脚本与词典数据。 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-04 14:30:53 -07:00
commit bd7635986a
66 changed files with 5495 additions and 0 deletions
@@ -0,0 +1,162 @@
+# WordLoop 单词循环记忆系统
+
+输入中文/英文 → 自动翻译 → 加入个人单词库 → 每日测验 → 根据答题情况反复记忆 → 达标后进入已掌握词库。
+
+## 技术栈
+
+- **前端**: Vue 3 + Vite + TypeScript
+- **后端**: Python FastAPI
+- **数据库**: MySQL（本地 `wordloop` 库）
+
+## 本地启动
+
+端口：**前端 18003** · **后端 18004**
+
+**推荐** 在项目根目录一条命令同时启动：
+
+```bash
+chmod +x start.sh   # 首次
+./start.sh          # 或 ./start.sh all
+```
+
+也可开两个终端分别执行 `./start.sh backend` / `./start.sh frontend`，或手动进入子目录：
+
+### MySQL
+
+本地需已安装 MySQL，并创建库（账号示例与默认 `.env` 一致）：
+
+```bash
+mysql -h localhost -u boot -p888888 -e "CREATE DATABASE IF NOT EXISTS wordloop CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
+```
+
+连接参数在 `backend/.env`（可从 `backend/.env.example` 复制）：
+
+| 变量 | 默认值 |
+|------|--------|
+| `MYSQL_HOST` | localhost |
+| `MYSQL_PORT` | 3306 |
+| `MYSQL_USER` | boot |
+| `MYSQL_PASSWORD` | 888888 |
+| `MYSQL_DATABASE` | wordloop |
+
+首次启动后端时会自动建表。
+
+### 导入离线翻译词典
+
+后端启动后，将内置词条（或自定义词库）导入 `dictionary_entries` 表：
+
+```bash
+cd backend
+source venv/bin/activate   # Windows: venv\Scripts\activate
+
+# 导入默认 seed 词库（36 条）
+python -m scripts.import_dictionary
+
+# 导入自定义 JSON / CSV
+python -m scripts.import_dictionary --file /path/to/your_dict.json --source ecdict
+```
+
+**JSON 格式**（数组或 `{ "entries": [...] }`）：
+
+```json
+[
+  {
+    "lemma_en": "apple",
+    "zh": "苹果",
+    "phonetic": "/ˈæpəl/",
+    "example_en": "I eat an apple every day.",
+    "example_cn": "我每天吃一个苹果。"
+  }
+]
+```
+
+**CSV 列名**：`lemma_en`, `zh`, `phonetic`, `example_en`, `example_cn`（也支持 `en` / `cn` 别名）。
+
+翻译 API 会优先查该表；未命中时返回占位结果，暂不接入外部 API。
+
+### 从线上导入 ECDICT 词库（推荐）
+
+自动从 GitHub 下载 [ECDICT](https://github.com/skywind3000/ECDICT) SQLite 词库（约 340 万词条）并写入数据库：
+
+```bash
+cd backend
+source venv/bin/activate
+
+# 常用词（默认，约 83 万条，含 transformer 等）
+python -m scripts.import_dictionary_online
+
+# 核心词（Collins / 牛津，约 1.4 万条，速度快）
+python -m scripts.import_dictionary_online --preset core
+
+# 全量（约 338 万条，耗时长、占空间大）
+python -m scripts.import_dictionary_online --preset full
+
+# 已有本地 cache 时跳过下载
+python -m scripts.import_dictionary_online --skip-download
+```
+
+首次运行会下载约 207MB 压缩包并解压到 `backend/data/cache/`（已加入 `.gitignore`）。
+
+### 后端
+
+```bash
+cd backend
+python -m venv venv
+
+# macOS / Linux
+source venv/bin/activate
+
+# Windows
+venv\Scripts\activate
+
+pip install -r requirements.txt
+cp .env.example .env   # 首次，按需改密码
+uvicorn main:app --reload --host 0.0.0.0 --port 18004
+```
+
+API 文档：http://localhost:18004/docs
+
+### 前端
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+浏览器访问：http://localhost:18003
+
+## 默认测试账号
+
+注册后即可使用，或自行注册新账号。
+
+## 线上部署（105 服务器 · w.tkmind.cn）
+
+生产目录：**`/root/wordloop`**，服务器 **`120.26.184.105`**，RDS MySQL。
+
+```bash
+chmod +x deploy/publish.sh deploy/install-production.sh
+./deploy/publish.sh                    # 默认 root@120.26.184.105
+# 数据库等可写在 deploy/secrets.env（见 secrets.env.example）
+```
+
+Cloudflare DNS：子域 **`w`** → A 记录 **`120.26.184.105`**（橙云代理）。Tunnel 方案见 **[deploy/DEPLOY.md](deploy/DEPLOY.md)**。
+
+## 项目结构
+
+```
+wordloop/
+├── backend/          # FastAPI 后端
+├── frontend/         # Vue 3 前端
+├── deploy/           # Nginx、Cloudflare Tunnel、部署说明
+└── README.md
+```
+
+## 核心功能
+
+- 用户注册 / 登录（JWT）
+- 中英互译（本地词典 MVP，可扩展 AI）
+- 个人单词库（新词 / 学习中 / 已掌握 / 易错词）
+- 每日选择题训练
+- 掌握规则与复习间隔
+- 学习统计与设置