john
e76fa586f1
Ship dual-track learning (daily accumulation vs textbook),沪教/商务词书 APIs and UI, native iOS wrapper with bundled H5, and production book import on deploy. Co-authored-by: Cursor <cursoragent@cursor.com>
187 lines
5.4 KiB
Markdown
187 lines
5.4 KiB
Markdown
# 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
|
||
|
||
### 词书（沪版 / 商务）
|
||
|
||
词书目录为全局数据，与「日常积累」练习**完全分开**（独立统计、记忆曲线、选题池）。
|
||
|
||
```bash
|
||
cd backend
|
||
source venv/bin/activate
|
||
pip install openpyxl # 首次从 GitHub 拉取 xlsx 时需要
|
||
|
||
# 从 lilinji/English 下载沪版牛津 + BEC 词汇，生成 JSON 并导入库
|
||
python -m scripts.fetch_hujiao_books --import-db
|
||
|
||
# 若已有 backend/data/books/*.json，仅导入数据库：
|
||
python -m scripts.import_word_books
|
||
```
|
||
|
||
生产部署后 `deploy/install-production.sh` 会自动执行 `import_word_books`（需随代码发布 `data/books/*.json`）。
|
||
|
||
内置词书：小学 `hujiao-primary-1`…`5`、初中 `hujiao-junior-6`…`9`、高中 `hujiao-senior-1`…`3`（高一至高三）、`business-daily`（日常商务）。首页可切换「日常积累 / 词书练习」；词书在「词书设置」页下拉选择并调整每日练习量。
|
||
|
||
## 默认测试账号
|
||
|
||
注册后即可使用，或自行注册新账号。
|
||
|
||
## 线上部署（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）
|
||
- 个人单词库（新词 / 学习中 / 已掌握 / 易错词，记录进入词库时间）
|
||
- 记忆曲线与 Obsidian 式单词关系力导向图
|
||
- 每日选择题训练
|
||
- 拼写练习（中文释义 + 音标，输入英文单词）
|
||
- 记忆对话（Q/K/V token 引导推导英文，显示中文释义与记忆保持，计入练习记录）
|
||
- Transformer 记忆预测（轻量序列模型 + 遗忘曲线，见 [backend/docs/MEMORY_TRANSFORMER.md](backend/docs/MEMORY_TRANSFORMER.md)）
|
||
- 掌握规则与复习间隔
|
||
- 学习统计与设置
|