wordloop/README.md

# 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)）
- 掌握规则与复习间隔
- 学习统计与设置