wordloop/README.md

WordLoop 单词循环记忆系统

输入中文/英文 → 自动翻译 → 加入个人单词库 → 每日测验 → 根据答题情况反复记忆 → 达标后进入已掌握词库。

技术栈

• 前端: Vue 3 + Vite + TypeScript
• 后端: Python FastAPI
• 数据库: MySQL（本地 wordloop 库）

本地启动

端口：前端 18003 · 后端 18004

推荐 在项目根目录一条命令同时启动：

chmod +x start.sh   # 首次
./start.sh          # 或 ./start.sh all

也可开两个终端分别执行 ./start.sh backend / ./start.sh frontend，或手动进入子目录：

MySQL

本地需已安装 MySQL，并创建库（账号示例与默认 .env 一致）：

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 表：

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": [...] }）：

[
  {
    "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 SQLite 词库（约 340 万词条）并写入数据库：

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）。

后端

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

前端

cd frontend
npm install
npm run dev

浏览器访问：http://localhost:18003

词书（沪版 / 商务）

词书目录为全局数据，与「日常积累」练习完全分开（独立统计、记忆曲线、选题池）。

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。

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。

项目结构

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