eddy
738275b493
- 为同源资源添加网络优先策略，并在离线时回退到缓存 - 缓存带版本号的 CDN 资源，并在发布更新时保留独立缓存条目 - 改进版本更新检查，避免清除 localStorage 或无关缓存 - 将 Service Worker 纳入部署流程并更新相关文档
92 lines
5.4 KiB
Markdown
92 lines
5.4 KiB
Markdown
# AI 英语助教
|
||
|
||
一个纯前端的英语单词学习应用。无需后端，学习数据保存在浏览器 `localStorage`；可导入词库、从邮件提词、进行测试和错题复习，并支持可选的 OpenAI 兼容 AI 服务。
|
||
|
||
仓库包含两个可独立运行的版本：
|
||
|
||
- `src/`：当前单文件式实现（`index.html`、`styles.css`、`script.js`）。
|
||
- `refactor/`：ES Modules 重构版；按页面、服务、UI 与样式拆分，保持原有功能和数据兼容。
|
||
|
||
## 启动
|
||
|
||
应用需要通过 HTTP 服务运行，不能直接打开 HTML 文件。
|
||
|
||
```powershell
|
||
# 在仓库根目录运行
|
||
python -m http.server 8000
|
||
```
|
||
|
||
开发原版 `src/` 时，Windows 10 可用仓库根目录的脚本一键控制服务：
|
||
|
||
```powershell
|
||
python serve.py start # 后台启动，访问 http://localhost:8000/
|
||
python serve.py status # 查看运行状态
|
||
python serve.py stop # 停止服务
|
||
```
|
||
|
||
脚本不生成 PID 文件，而是通过 8000 端口识别 `src/` 的本地 HTTP 服务；当端口被其他程序占用时，可在提示后选择强制关闭该进程并启动。
|
||
|
||
打开：
|
||
|
||
- 原版：<http://localhost:8000/src/>（使用上述根目录命令）或 <http://localhost:8000/>（使用 `serve.py`）
|
||
- 重构版：<http://localhost:8000/refactor/>
|
||
|
||
也可启动重构版预设脚本：
|
||
|
||
```powershell
|
||
cd refactor
|
||
npm run serve
|
||
```
|
||
|
||
该脚本会将仓库根目录作为 HTTP 根目录，因此可正确读取根目录的 `data/` 词库。两版若要共享已有学习数据，必须使用相同的协议、主机和端口；`localStorage` 按 origin 隔离。
|
||
|
||
## 功能概览
|
||
|
||
- 单词库：JSON 导入与导出、搜索、分类与收藏筛选、详情和发音。
|
||
- 学习与复习：基于 `[1, 2, 4, 7, 15, 30]` 天间隔的复习计划、错题卡片复习与学习统计。
|
||
- 测试：英译中、中译英、本地或 AI 出题、错题与收藏范围测试。
|
||
- 邮件学习：从英文邮件提取词汇、批量翻译入库、全文阅读、高亮、朗读与 AI 分析。
|
||
- 设置：主题、AI 配置、词库自动加载、完整数据备份与恢复。
|
||
|
||
## 技术与外部服务
|
||
|
||
- 原生 HTML、CSS、JavaScript；重构版使用浏览器原生 ES Modules，无构建步骤。
|
||
- Font Awesome、Chart.js。
|
||
- Free Dictionary API、Azure TTS、有道 TTS 与浏览器 Web Speech（网络语音不可用时回退到浏览器朗读）。
|
||
- OpenAI 兼容 Chat Completions API（可选，用于出题、翻译和邮件分析）。
|
||
|
||
CDN 或第三方 API 被网络、离线环境或 CSP 阻止时，相应的图标、图表、AI 或网络语音功能会受限。
|
||
|
||
## 数据与兼容性
|
||
|
||
核心数据包括单词、练习记录、复习计划、收藏、邮件、主题与 AI 设置。重构版沿用原版的数据结构，并支持将默认词库的旧键（如 `words`、`records`、`schedule`、`favorites`）迁移为按词库分组的存储键。
|
||
|
||
重构版的主要目录：
|
||
|
||
- `refactor/js/core/`：状态、存储、路由与事件委托。
|
||
- `refactor/js/services/`：TTS、AI、复习算法、统计、出题、提词与词库服务。
|
||
- `refactor/js/pages/`：各页面和学习流程。
|
||
- `refactor/js/ui/`：主题、侧边栏、Toast、Modal 与 DOM 工具。
|
||
- `refactor/styles/`：按原样式级联顺序拆分的样式文件。
|
||
|
||
重构版不使用内联事件处理器；交互通过命名空间化的 `data-action` 和统一事件委托处理。
|
||
|
||
## 验收
|
||
|
||
重构版的手工验收清单位于 [`refactor/docs/smoke-test.md`](refactor/docs/smoke-test.md)。验证时请在开发者工具中检查 Console，并确认两版使用同一 origin 后再检查历史数据。
|
||
|
||
## 发布与缓存
|
||
|
||
Linux 服务器可使用 `deploy.sh` 一键下载并部署 `main` 分支的最新版本：
|
||
|
||
- 保留 deploy 参数，以便下载脚本后直接执行部署，而不是进入交互菜单。
|
||
|
||
```bash
|
||
bash <(curl -fsSL https://gitea.tohub.top/Share/AI_English/raw/branch/main/deploy.sh) deploy
|
||
```
|
||
|
||
脚本会将 `src/index.html`、`src/sw.js`、`src/js/` 和 `src/styles/` 部署到 `/root/data/docker_data/Nginx/html/english/ai/`，清理目标目录中的其他内容，但保留已有的 `data/` 目录。运行前请确认目标路径符合服务器配置；脚本需要 root 权限以及 `curl`、`tar`、`find` 命令。
|
||
|
||
缓存策略分两层：`src/index.html` 通过 CSS 和入口 JavaScript URL 的 `v` 查询参数（`ASSET_VERSION`）控制静态资源缓存，每次发布请同步递增该版本号；`src/sw.js`（Service Worker）对同源请求采用「网络优先、离线回退缓存」——未带版本号的请求以 `cache: 'no-cache'` 强制向服务器做条件校验，绕过浏览器启发式缓存（iOS Safari 卡旧版本的根因），带 `?v=` 的资源则走默认 HTTP 缓存；对 CDN 上带版本号的静态库（Font Awesome、Chart.js）采用「缓存优先」，首次取回后离线也能显示图标与图表，其余跨域请求（AI / TTS 接口）不拦截。服务器应优先为 `index.html` 与 `sw.js` 设置 `Cache-Control: no-cache`；带版本号的静态资源可长期缓存。
|
||
|
||
设置页的“获取最新版本”会检查并更新 Service Worker，再通过带时间戳的 URL 重新加载；重新取得的资源会更新对应 URL 的缓存，带版本号的资源会保留独立条目以避免并发页面互相覆盖，且不会清除 `localStorage`，以免丢失学习数据和 AI 配置。 |