John
163 lines
4.1 KiB
Markdown
163 lines
4.1 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
|
||
|
||
## 默认测试账号
|
||
|
||
注册后即可使用，或自行注册新账号。
|
||
|
||
## 线上部署（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）
|
||
- 个人单词库（新词 / 学习中 / 已掌握 / 易错词）
|
||
- 每日选择题训练
|
||
- 掌握规则与复习间隔
|
||
- 学习统计与设置
|