diff --git a/DEPLOYMENT_PROGRESS.md b/DEPLOYMENT_PROGRESS.md deleted file mode 100644 index a4c31d7..0000000 --- a/DEPLOYMENT_PROGRESS.md +++ /dev/null @@ -1,71 +0,0 @@ -# 部署流水线问题排查进度 - -**日期**: 2026-07-20（更新） - -## 当前部署方式 - -- **当前方案**：Gitea Actions（`.gitea/workflows/deploy.yml`） - 手动 `workflow_dispatch` → 构建镜像 → 推私有 Registry → `kubectl set image` 到 K8s - -## 分支 ↔ 环境约定（已写入 workflow 强制校验） - -| 仓库 | 部署 dev (`lpt-dev`) | 部署 prod (`lpt-prod`) | -|------|----------------------|-------------------------| -| **lpt-fe** | 必须在 **`dev` 分支** 上 Run | 必须在 **`master`/`main`** 上 Run | -| **lpt-be** | 必须在 **`dev` 分支** 上 Run | 必须在 **`master`/`main`** 上 Run | -| **lpt-ai** | 仅有 **`main`**，从 main 部署到 dev | 从 **main** 部署到 prod | - -在错误分支上选择 environment 会在第一步直接失败，避免「dev 环境跑了 master 代码」。 - -### 正确操作 - -1. Gitea 仓库页面切换到目标分支（fe/be 的 dev 或 master） -2. Actions → 对应 workflow → Run workflow -3. 选择 `environment` = `dev` 或 `prod`（须与当前分支匹配） - -## 已修复项（2026-07-20） - -1. **分支与环境绑定校验** — 三个仓库的 `deploy.yml` 增加 Validate 步骤 -2. **`IMAGE_TAG` 持久化** — 除 `GITHUB_ENV` 外，写入 `GITEA_ENV`（若存在）+ 临时文件兜底，Deploy 步读取失败则明确报错 -3. **fe `BUILD_MODE`** — 在 shell 内根据 environment 设置 `production` / `development`，避免表达式兼容问题 -4. **lpt-fe `dev` 分支同步** — 将 master 合并进 dev，保证 dev 上也有完整 workflow 与最新代码 - -## 历史问题（部分仍可能相关） - -### Registry / Secrets - -若出现 `ImagePullBackOff` / `docker login` 失败，检查各仓库 Gitea Secrets： - -- `REGISTRY_USERNAME`（如 `admin`） -- `REGISTRY_PASSWORD` -- `KUBECONFIG_B64`（kubeconfig 的 base64） - -Registry: `192.168.123.199:5000` - -### K8s - -- 共享清单：`k8s/dev/*`、`k8s/prod/*`（按环境） -- 各服务仓库内 `k8s/` 仍多为 `lpt-dev` 模板；日常 CI 只 `set image`，不 `apply` 整份 YAML -- Deployment 需有 `imagePullSecrets: [regcred]`；workflow 每次会 create/update `regcred` - -## 镜像与命名空间 - -| environment | 镜像 tag（浮动） | 不可变 tag | namespace | -|-------------|------------------|------------|-----------| -| dev | `app:dev` | `app:-` | `lpt-dev` | -| prod | `app:prod` | `app:-` | `lpt-prod` | - -部署使用不可变 tag，避免 `imagePullPolicy` 与缓存导致未更新。 - -## 验证清单 - -1. [ ] 三仓库 Secrets 已配置 -2. [ ] lpt-fe：在 **dev** 分支 Run → environment=dev 成功 -3. [ ] lpt-fe：在 **master** 上选 environment=dev 应 **失败**（校验） -4. [ ] lpt-be：同上 -5. [ ] lpt-ai：在 **main** 上 Run → dev / prod -6. [ ] `kubectl get pods -n lpt-dev` / `lpt-prod` 正常 - ---- - -**备注**: 部署流程为 Gitea Actions + K8s，勿再使用旧 Jenkins 容器部署。 diff --git a/DESIGN_REVIEW.md b/DESIGN_REVIEW.md deleted file mode 100644 index 747fc3a..0000000 --- a/DESIGN_REVIEW.md +++ /dev/null @@ -1,413 +0,0 @@ -# LPT 复习流程设计文档 - -> 本文档描述 LPT 系统中「回忆复习」（Recall Review）功能的完整设计，包括数据模型、API、前端交互流程和三种入口的处理方式。 - ---- - -## 1. 核心概念 - -### 1.1 标准思维导图（Standard Mind Map） - -- **任务级单一知识树**：每个学习任务有且仅有一棵标准思维导图，存储在 `review_standard_mind_maps` 表 -- **生成方式**： - - `BUILTIN`：内置规则引擎，按 session 分组、去重、合并 - - `AI`：调用 lpt-ai 服务生成缩进大纲后解析 - - `USER`：用户手动编辑 - - `USER_MERGE`：增量合并后（保留用户编辑 + 追加 AI 新节点） -- **数据结构**：`content` 字段存储 JSON 树（递归 `MindMapNode`），`outline` 字段存储缩进大纲文本 -- **节点模型**： - ``` - MindMapNode { - title: string // 节点标题 - notes?: string // 备注 / 对比标记（MATCHED| / MISSED|） - sourceType?: string // REPORT | FRAGMENT | APPLICATION - sourceId?: number // 对应源数据主键 - children?: MindMapNode[] - } - ``` -- **节点标记约定**（用于对比着色）： - - `notes` 以 `MATCHED|` 开头 → 绿色（回忆命中） - - `notes` 以 `MISSED|` 开头 → 红色（回忆遗漏） - - 无标记 → 默认色（未参与对比） - -### 1.2 回忆对比记录（Recall Record） - -- 每次用户提交回忆 → 生成一条 `review_recall_records` 记录 -- 核心字段： - - `task_num`：关联任务 - - `standard_map_id`：对比时使用的标准导图版本 - - `focus_path`：复习起点节点路径（`"根 / 分支A / 子节点B"`），null 为全量 - - `recall_content`：用户回忆大纲文本 - - `compare_result`：对比结果 JSON（含 `matchedTree`、`extraNodes`、覆盖率等） - - `recall_ratio` / `matched_count` / `missed_count` / `extra_count`：统计摘要 - ---- - -## 2. 复习流程 - -### 2.1 核心逻辑 - -``` -1. 确定复习起点（节点路径） -2. 获取标准导图 -3. 按起点提取子树作为对比基准 -4. 用户在大纲编辑器中回忆填充 -5. 提交对比（AI 语义匹配 或 BUILTIN 字符串匹配） -6. 展示对比结果（着色 + 统计） -``` - -### 2.2 节点选择 - -- 用户在标准导图上点击节点 → `MindMapViewer` 发射 `node-select` 事件（含 `title`、`path`、`childCount`） -- 弹窗确认：「以「节点名」为起点，复习其下 N 个子知识点？」 -- 确认后： - - `focusPath` = 选中节点的路径（如 `"Java基础 / 集合 / HashMap"`） - - `recallTree` 根节点标题 = 选中节点标题 - - 回忆导图以该标题为根，用户补充子节点 - -### 2.3 对比范围 - -- **有 `focusPath`**：`MindMapTreeTool.extractSubtree(root, focusPath)` 提取子树，对比基准 = 子树 -- **无 `focusPath`**：对比基准 = 整棵标准导图 -- AI 对比：发给 lpt-ai 的 outline 只包含子树范围 -- BUILTIN 对比：`compareTrees()` 在子树范围内做标题匹配 - -### 2.4 对比算法 - -**AI 语义匹配（优先）：** -``` -POST /ai/tasks → type: "compare-recall" -→ 异步轮询结果 -→ 返回 { matches: [{standardTitle, recallTitle}], missedTitles, extraNodes, evaluation } -→ Java 端 buildCompareResultFromAI() 标注标准树 -``` - -**BUILTIN 字符串匹配（降级）：** -- 展平标准树和回忆树 -- 标题标准化（去标点、去空格、转小写） -- 精确匹配 → 模糊匹配（bigram Jaccard ≥ 0.6） -- 标记 MATCHED / MISSED / 额外 - -### 2.5 结果展示 - -- 标准导图面板直接显示着色对比结果（不再有独立对比面板） -- 绿色（`#c8e6c9`）= 命中，红色（`#ffcdd2`）= 遗漏 -- 统计卡片：覆盖率、命中/遗漏/额外计数 -- 遗漏项列表 + 额外项列表（可点击回看原文） - ---- - -## 3. 三个复习入口 - -### 入口 A：复习总览 → "回忆复习" - -**路径：** `Welcome.vue` → "复习回看" → `Review.vue`（任务列表）→ 每行"回忆复习"按钮 - -**前端代码：** `Review.vue:110` -```typescript -router.push(`/review/recall/${row.taskNum}`) -``` - -**流程：** -1. 跳转到 `ReviewRecall.vue`，URL 为 `/review/recall/:taskNum` -2. 页面加载 → `loadData()` 获取标准导图 -3. 标准导图 `selectable=true`，显示提示「点击导图节点选择复习起点」 -4. 用户点击节点 → 弹窗确认 → 进入回忆模式 -5. 回忆填充 → 提交对比 → 展示结果 - -**相关文件：** -- `lpt-fe/src/components/Review.vue` -- `lpt-fe/src/components/ReviewRecall.vue` - -### 入口 B：从某个残片/报告详情 → "回忆复习" - -**路径：** `Welcome.vue` 滚动回顾 → 点击卡片 → `ReviewDetail.vue` → "回忆复习"按钮 - -**前端代码：** `ReviewDetail.vue` 的 `goToRecall()` -```typescript -const res = await findNode(taskNum, content.substring(0, 500)); -if (res?.data?.path) { - router.push(`/review/recall/${taskNum}?focusPath=${encodeURIComponent(res.data.path)}`); -} -``` - -**流程：** -1. 用户在详情页查看某个残片/报告的内容 -2. 点击"回忆复习" → 前端调 `POST /review/standard-mind-map/{taskNum}/find-node` -3. 后端 `findClosestNode()` 用 bigram Jaccard 匹配最接近的节点 -4. 返回 `{ path, nodeTitle, score }` -5. 跳转到 `/review/recall/:taskNum?focusPath=...` -6. `ReviewRecall.vue` 检测到 URL 参数 → 跳过节点选择，直接进入回忆模式 - -**后端 API：** -```http -POST /review/standard-mind-map/{taskNum}/find-node -Content-Type: application/json - -{ "content": "用户查看的残片/报告文本" } - -→ 200 OK -{ "code": 200, "data": { "path": "根 / 分支A / 子节点B", "nodeTitle": "子节点B", "score": 0.85 } } -``` - -**匹配算法（`MindMapTreeTool.findClosestNode`）：** -1. 展平标准导图所有节点 -2. 对每个节点，计算其 `title` 与输入文本的 bigram Jaccard 相似度 -3. `notes` 字段也参与匹配（权重 0.5） -4. 返回得分最高（>0.1）的节点 - -**相关文件：** -- `lpt-fe/src/components/ReviewDetail.vue` -- `learning-progress-tracker/.../utils/MindMapTreeTool.java`（`findClosestNode`、`similarityScore`） - -### 入口 C：首页欢迎页 → 回忆卡片 → "前往回忆复习" - -**路径：** `Welcome.vue` → 滚动回顾标签 → 点击弹出回忆对话框 → "前往回忆复习"按钮 - -**前端代码：** `Welcome.vue` 的 `goToRecallFromCard()` -```typescript -const tn = group.taskNum; -const res = await findNode(tn, content.substring(0, 500)); -if (res?.data?.path) { - router.push(`/review/recall/${tn}?focusPath=${encodeURIComponent(res.data.path)}`); -} -``` - -**流程：** -1. Welcome 页加载 `GET /review/feed` 获取复习 feed -2. 按 session 分组为标签卡片 -3. 用户点击某个标签 → 弹出回忆对话框（先回忆→展开对照） -4. 点击"前往回忆复习" → 同入口 B，先调 findNode 再跳转 - -**相关文件：** -- `lpt-fe/src/components/Welcome.vue` - ---- - -## 4. 关键 API 清单 - -### 4.1 标准思维导图 - -| 方法 | 路径 | 说明 | -|------|------|------| -| `GET` | `/review/standard-mind-map/{taskNum}` | 获取/自动生成标准导图 | -| `POST` | `/review/standard-mind-map/{taskNum}/regenerate?mode=full\|incremental` | 重新生成 | -| `PUT` | `/review/standard-mind-map/{taskNum}` | 用户编辑（大纲文本） | -| `POST` | `/review/standard-mind-map/{taskNum}/recall` | 提交回忆对比 | -| `POST` | `/review/standard-mind-map/{taskNum}/find-node` | 匹配最近节点 | -| `GET` | `/review/standard-mind-map/{taskNum}/recall-records` | 历史回忆记录 | - -### 4.2 回忆对比请求体 - -```json -{ - "recallOutline": "用户回忆的缩进大纲文本\n - 子节点1\n - 子节点2", - "focusPath": "根标题 / 分支A / 子节点B" -} -``` - -- `recallOutline`：必填，用户回忆的缩进大纲 -- `focusPath`：可选，复习起点节点路径。null = 全量，提供时对比范围为该子树 - -### 4.3 对比结果结构（CompareResult） - -```json -{ - "matchedTree": { - "title": "根节点", - "notes": "", - "children": [ - { - "title": "命中的知识点", - "notes": "MATCHED|完整原文内容", - "sourceType": "REPORT", - "sourceId": 1, - "children": [] - }, - { - "title": "遗漏的知识点", - "notes": "MISSED|完整原文内容", - "sourceType": "FRAGMENT", - "sourceId": 2, - "children": [] - } - ] - }, - "extraNodes": [ - { "title": "用户额外回忆的知识", "path": "/额外/..." } - ], - "recallRatio": 0.75, - "matchedCount": 3, - "missedCount": 1, - "extraCount": 1, - "evaluation": "AI 评价文本（仅 AI 对比时有值）" -} -``` - ---- - -## 5. 前端组件结构 - -``` -ReviewRecall.vue（主页面） -├── Page header（返回、标题、历史记录按钮） -├── 复习起点指示（focusPath 显示 + 重选按钮） -├── 节点选择确认弹窗（el-dialog） -├── 统计卡片（覆盖率/命中/遗漏/额外） -├── 回忆历史列表 -├── 回忆输入（editable MindMapViewer） -├── 标准导图 + 对比结果（color-by-compare MindMapViewer） -│ ├── 未选择起点时 → selectable 模式 -│ ├── 已选择起点/已对比 → 着色展示 -│ └── 编辑模式 → editable 模式 -└── 遗漏项 + 额外项详情列表 -``` - -### 5.1 MindMapViewer 组件 Props - -| 属性 | 类型 | 默认 | 说明 | -|------|------|------|------| -| `tree` | `MindMapTreeNode \| null` | — | 树数据 | -| `editable` | `boolean` | `false` | 是否可编辑 | -| `colorByCompare` | `boolean` | `false` | 按 MATCHED/MISSED 着色 | -| `height` | `string` | `'480px'` | 画布高度 | -| `selectable` | `boolean` | `false` | 节点单击可选择 | -| `selectedPath` | `string` | `''` | 当前选中节点路径 | - -### 5.2 MindMapViewer 事件 - -| 事件 | 载荷 | 触发时机 | -|------|------|----------| -| `change` | `outline: string` | 编辑模式下结构变化 | -| `node-click` | `{ sourceType, sourceId }` | 点击带溯源标签的节点 | -| `node-select` | `{ title, path, childCount }` | selectable 模式下点击节点 | - -### 5.3 MindMapViewer 暴露方法 - -```typescript -defineExpose({ toOutline }) -// toOutline() → 缩进大纲文本 -``` - ---- - -## 6. 后端核心工具方法 - -### `MindMapTreeTool.java` - -| 方法 | 说明 | -|------|------| -| `extractSubtree(root, path)` | 按 "/" 分隔路径提取子树，返回深拷贝 | -| `findClosestNode(root, content)` | bigram Jaccard 匹配最近节点 | -| `getPath(root, targetTitle)` | 获取节点到根的路径字符串 | -| `similarityScore(a, b)` | 两段文本的 bigram Jaccard 相似度 | -| `mergeTrees(oldRoot, newRoot)` | 按标准化标题合并新旧树 | -| `toJson(root, mapper)` | 序列化为 JSON | -| `fromJson(json, mapper)` | 从 JSON 反序列化 | -| `toOutline(root)` | 树 → 缩进大纲 | -| `toFullOutline(root)` | 树 → 完整大纲（含根标题） | -| `parseOutline(text)` | 缩进大纲 → 树 | -| `flatten(root)` | 前序遍历展平 | -| `countNodes(root)` | 节点总数 | -| `maxDepth(root)` | 最大深度 | - -### `StandardMindMapServiceImpl.java` - -| 方法 | 说明 | -|------|------| -| `getOrGenerate(taskNum)` | 获取/自动生成标准导图 | -| `regenerate(taskNum)` | 全量重新生成（防并发） | -| `incrementalGenerate(taskNum)` | 增量合并（保留用户编辑） | -| `updateByOutline(taskNum, outline)` | 用户编辑 | -| `recallCompare(taskNum, outline, focusPath)` | 回忆对比 | -| `findNode(taskNum, content)` | 查找最近节点 | -| `listRecallRecords(taskNum)` | 历史记录 | -| `getRecallRecord(id)` | 单条记录详情 | - ---- - -## 7. 关键文件索引 - -### 前端（`lpt-fe/src/`） - -| 文件 | 说明 | -|------|------| -| `components/ReviewRecall.vue` | 回忆复习主页面 | -| `components/Review.vue` | 复习总览（任务列表+入口） | -| `components/ReviewDetail.vue` | 残片/报告详情页 | -| `components/Welcome.vue` | 首页（内含回忆卡片入口） | -| `components/MindMapViewer.vue` | 思维导图渲染/编辑/选择组件 | -| `api/standardMindMap.ts` | 标准导图 API 封装 | -| `api/review.ts` | 复习 feed API | -| `api/studySessions.ts` | 学习会话 API | - -### 后端（`learning-progress-tracker/src/main/java/.../`） - -| 文件 | 说明 | -|------|------| -| `controller/ReviewController.java` | 复习相关端点 | -| `service/StandardMindMapService.java` | 标准导图服务接口 | -| `service/impl/StandardMindMapServiceImpl.java` | 服务实现 | -| `service/impl/BuiltinMindMapGenerator.java` | 内置规则生成器 | -| `service/impl/RemoteAiMindMapClient.java` | AI 导图客户端 | -| `service/impl/AiServiceClient.java` | lpt-ai 通用客户端 | -| `utils/MindMapNode.java` | 树节点 DTO | -| `utils/MindMapTreeTool.java` | 树操作工具类 | -| `utils/CompareResult.java` | 对比结果 DTO | -| `entity/ReviewStandardMindMapEntity.java` | 标准导图实体 | -| `entity/ReviewRecallRecordEntity.java` | 回忆记录实体 | -| `db/migration/V20260706_1__add_focus_path_to_recall_records.sql` | focus_path 迁移 | - -### AI 服务（`lpt-ai/src/`） - -| 文件 | 说明 | -|------|------| -| `routes/ai.ts` | AI 任务提交/轮询/抓取标题 | -| `task-queue.ts` | 异步任务队列 | -| `llm/prompts.ts` | prompt 模板（generate-mind-map / compare-recall / aggregate-report） | -| `llm/client.ts` | LLM API 客户端 | -| `admin/routes.ts` | 管理面板 | - ---- - -## 8. 数据流图 - -``` -学习碎片/报告 - ↓ (按 session 分组) -BuiltinMindMapGenerator / RemoteAiMindMapClient - ↓ -标准思维导图（review_standard_mind_maps） - ↓ (用户选择节点) -extractSubtree(root, focusPath) - ↓ -子树（对比基准） - ↓ AI / BUILTIN 对比 ← 用户回忆大纲 - ↓ -CompareResult - ↓ (序列化存储 + 前端渲染) -review_recall_records + 着色 MindMapViewer -``` - ---- - -## 9. 历史版本记录 - -| Commit | 说明 | -|--------|------| -| `a636e51` | 新增 sessionNum 追踪 + 维度选择（已回退） | -| `e5adb40` | 前端会话选择器（已回退） | -| `3c3f682` | 防并发生成 + `mergeTrees` + 增量合 | -| `5a5a294` | 前端防抖/生成提示/移除冗余面板 | -| `84fe452` | **节点选择交互 + focusPath + findNode（当前）** | -| `b18f8b4` | **后端 focusPath + extractSubtree + 回退 session（当前）** | -| `ebbbeb4` | fix: Array.map 多参数 bug | - ---- - -## 10. 待办/已知问题 - -- [ ] AI 生成的导图（`RemoteAiMindMapClient`）因为没有 `sourceId`/`sourceType`，`node-click` 溯源不可用 -- [ ] `selectable` 模式下，点击无子节点的叶子节点，`childCount` = 0 的确认弹窗体验略奇怪 -- [ ] `findClosestNode` 的 bigram 相似度对短文本效果有限，可能需要 `notes` 加权优化 -- [ ] 欢迎页（Welcome.vue）的回忆卡片入口「前往回忆复习」按钮文字和位置可以优化 diff --git a/README.md b/README.md deleted file mode 100644 index c067f40..0000000 --- a/README.md +++ /dev/null @@ -1,33 +0,0 @@ -# LPT-FE - -This template should help get you started developing with Vue 3 in Vite. - -## Recommended IDE Setup - -[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) (and disable Vetur). - -## Type Support for `.vue` Imports in TS - -TypeScript cannot handle type information for `.vue` imports by default, so we replace the `tsc` CLI with `vue-tsc` for type checking. In editors, we need [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar) to make the TypeScript language service aware of `.vue` types. - -## Customize configuration - -See [Vite Configuration Reference](https://vite.dev/config/). - -## Project Setup - -```sh -npm install -``` - -### Compile and Hot-Reload for Development - -```sh -npm run dev -``` - -### Type-Check, Compile and Minify for Production - -```sh -npm run build -``` diff --git a/docs/architecture-optimizations.md b/docs/architecture-optimizations.md deleted file mode 100644 index e314a62..0000000 --- a/docs/architecture-optimizations.md +++ /dev/null @@ -1,630 +0,0 @@ -# LPT 前端架构优化说明 - -> 记录前端实现中的关键设计决策和优化策略 - -## 一、组件设计优化 - -### 1.1 MindMapViewer 多模式设计 - -**挑战**：思维导图需要支持三种不同场景 -- 查看标准导图（只读） -- 编辑标准导图（可修改） -- 选择复习起点（可点击节点） -- 展示对比结果（节点着色） - -**方案**：单组件多模式 - -```typescript -// MindMapViewer.vue -interface Props { - tree: MindMapTreeNode | null; - editable?: boolean; // 编辑模式 - selectable?: boolean; // 选择模式 - colorByCompare?: boolean; // 对比着色模式 - height?: string; - selectedPath?: string; -} -``` - -**模式互斥关系**： -- `editable=true` → 用户可修改节点 -- `selectable=true` → 点击节点触发 `node-select` 事件 -- `colorByCompare=true` → 根据 `notes` 字段着色（MATCHED|/MISSED|） -- 默认 → 只读浏览，点击带 `sourceType` 的节点可溯源 - -**收益**： -- 代码复用率高（一个组件覆盖所有场景） -- API 简洁（通过 props 控制行为） -- 维护成本低（修改一处全局生效） - -### 1.2 回忆卡片交互设计 - -**需求**：滚动 feed 中点击内容，先让用户回忆再展示答案 - -**实现**：两阶段弹窗 - -```typescript -// Welcome.vue -const showRecallDialog = (item: FeedItem) => { - // 阶段 1：只显示片段标题 - recallDialogContent.value = item.content.substring(0, 100) + '...'; - recallDialogExpanded.value = false; - - // 用户点击"我想起来了" - const expand = () => { - recallDialogExpanded.value = true; - // 阶段 2：展示完整内容 + 同会话其他内容 - loadFullSession(item.sessionNum); - }; -}; -``` - -**心理学原理**： -- 主动回忆 > 被动阅读（Testing Effect） -- 认知失调驱动记忆巩固 -- 答案延迟呈现增强记忆深度 - -**收益**： -- 提升复习效果 -- 增加用户参与感 -- 符合间隔重复理论 - -### 1.3 历史记录虚拟滚动 - -**问题**：活跃用户可能有 500+ 条学习记录 - -**优化前**： -```typescript -// ❌ 一次性渲染全部 -
...
-``` - -**优化后**： -```typescript -// ✅ 分页 + 懒加载 - -``` - -**收益**： -- 首屏渲染时间：2.5s → 0.3s -- 内存占用：120MB → 15MB -- 支持无限历史 - ---- - -## 二、状态管理优化 - -### 2.1 学习会话状态同步 - -**场景**：用户在任务 A 学习中，打开新标签页访问任务 B - -**挑战**：多标签页状态不一致 - -**方案**：每次进入学习页检测活跃会话 - -```typescript -// StartTask.vue -onMounted(async () => { - // 检测是否有其他任务的活跃会话 - const active = await checkActiveSession(); - if (active && active.taskNum !== currentTaskNum) { - ElMessageBox.confirm( - `您有正在进行的学习会话（任务 ${active.taskNum}），是否继续？`, - { type: 'warning' } - ).then(() => { - router.push(`/start-task/${active.taskNum}`); - }); - } -}); -``` - -**收益**： -- 防止数据丢失 -- 引导用户正确流程 -- 多标签页一致性 - -### 2.2 权重配置实时校验 - -**需求**：五个维度权重总和必须为 100% - -**实现**：响应式计算 + 即时反馈 - -```typescript -// Study.vue -const weightSum = computed(() => { - return Object.values(weights.value).reduce((sum, w) => sum + w, 0); -}); - -const isSumValid = computed(() => weightSum.value === 100); - -watch(weightSum, (newSum) => { - if (newSum !== 100) { - message.warning(`当前总和 ${newSum}%，需调整为 100%`); - } -}); -``` - -**收益**： -- 即时反馈（无需点保存才知道错误） -- 视觉提示（红色警告 + 禁用保存按钮） -- 防止无效提交 - -### 2.3 Markdown 链接标题缓存 - -**场景**：学习材料中有 10 个 URL，每个都要调 `/fetch-title` - -**优化前**： -```typescript -// ❌ 重复请求 -for (const url of urls) { - const title = await fetchTitle(url); -} -``` - -**优化后**： -```typescript -// ✅ 内存缓存 + 请求去重 -const titleCache = new Map>(); - -export const getUrlTitle = (url: string) => { - if (titleCache.has(url)) { - return titleCache.get(url); - } - const promise = fetchTitle(url); - titleCache.set(url, promise); - return promise; -}; -``` - -**收益**： -- 重复 URL 零请求 -- 并发请求自动去重（Promise 复用） -- 会话内持久化 - ---- - -## 三、用户体验优化 - -### 3.1 学习预期常驻展示 - -**需求**：用户学习过程中可随时查看预期，结束时对比 - -**实现**：卡片式展示 + 弹窗对比 - -```vue - - - -

{{ expectation }}

- -``` - -结束会话时： -```typescript -ElMessageBox.confirm(` -

预期：${expectation}

-

实际：${reportContent}

-

是否达成预期？

-`, { dangerouslyUseHTMLString: true }); -``` - -**收益**： -- 元认知训练 -- 学习目标明确 -- 防止跑偏 - -### 3.2 AI 生成进度提示 - -**场景**：AI 生成思维导图需要 30-60 秒 - -**实现**：分段提示 + 轮询进度 - -```typescript -// ReviewRecall.vue -const generateWithAi = async () => { - message.info('正在调用 AI 生成思维导图...'); - - const { taskId } = await submitAiTask({ - type: 'generate-mind-map', - params: { taskName, reports, fragments } - }); - - // 轮询任务状态 - const poll = setInterval(async () => { - const result = await getAiTaskResult(taskId); - - if (result.status === 'running') { - message.info(`生成中... ${result.progress || 50}%`); - } else if (result.status === 'completed') { - message.success('生成完成！'); - clearInterval(poll); - loadStandardMap(); - } else if (result.status === 'failed') { - message.error('生成失败，已降级为内置规则'); - clearInterval(poll); - } - }, 2000); -}; -``` - -**收益**： -- 降低用户焦虑 -- 明确系统状态 -- 减少重复点击 - -### 3.3 节点路径面包屑 - -**场景**：用户选择复习起点后，需明确当前在导图的哪个位置 - -**实现**： -```vue - - - 复习起点 - - {{ part }} - - -``` - -**收益**： -- 空间定位清晰 -- 复习范围明确 -- 可点击返回上级 - ---- - -## 四、性能优化 - -### 4.1 Markdown 渲染优化 - -**挑战**：复杂正则可能导致嵌套 HTML（XSS 风险） - -**方案**：占位符两阶段渲染 - -```typescript -// utils/markdown.ts -export const renderMarkdown = (raw: string): string => { - const placeholders = new Map(); - let counter = 0; - - // 阶段 1：提取链接，替换为占位符 - let stage1 = raw.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_, text, url) => { - const key = `__LINK_${counter++}__`; - placeholders.set(key, `${text}`); - return key; - }); - - // 阶段 2：替换占位符为真实 HTML - placeholders.forEach((html, key) => { - stage1 = stage1.replace(key, html); - }); - - return stage1; -}; -``` - -**收益**： -- 避免正则二次匹配导致的嵌套 -- 性能提升（单次遍历） -- 安全性高（输出可预测） - -### 4.2 防抖与节流 - -**场景**： -- 搜索框输入（防抖） -- 滚动加载（节流） -- 权重滑块调整（防抖） - -**实现**： -```typescript -import { debounce } from 'lodash-es'; - -// 搜索输入 -const handleSearch = debounce((keyword: string) => { - searchTasks(keyword); -}, 300); - -// 滚动加载 -const handleScroll = throttle(() => { - if (isBottom()) loadMore(); -}, 200); -``` - -**收益**： -- 减少 API 调用 -- 降低 CPU 占用 -- 提升响应速度 - -### 4.3 图片懒加载 - -**场景**：学习材料中可能包含多张图片 - -**实现**： -```vue -学习材料配图 -``` - -```typescript -// main.ts -import VueLazyload from 'vue-lazyload'; -app.use(VueLazyload, { - loading: '/placeholder.png', - error: '/error.png' -}); -``` - -**收益**： -- 首屏加载快 -- 节省带宽 -- 平滑加载体验 - ---- - -## 五、错误处理 - -### 5.1 统一异常拦截 - -**实现**： -```typescript -// utils/request.ts -axios.interceptors.response.use( - response => { - const { code, message } = response.data; - if (code !== 200) { - ElMessage.error(message || '请求失败'); - return Promise.reject(new Error(message)); - } - return response; - }, - error => { - if (error.response?.status === 401) { - localStorage.removeItem('isLoggedIn'); - router.push('/login'); - ElMessage.error('登录已过期，请重新登录'); - } else if (error.response?.status === 403) { - ElMessage.error('无权限访问'); - } else { - ElMessage.error(error.message || '网络错误'); - } - return Promise.reject(error); - } -); -``` - -**收益**： -- 业务代码无需重复处理 -- 统一错误提示样式 -- 自动处理登录过期 - -### 5.2 降级 UI - -**场景**：AI 生成失败，自动切换为内置生成 - -**实现**： -```typescript -const generate = async () => { - try { - await generateWithAi(); - } catch (error) { - ElNotification({ - title: 'AI 生成失败', - message: '已自动切换为内置规则生成', - type: 'warning' - }); - await generateBuiltin(); - } -}; -``` - -**收益**： -- 用户无感知切换 -- 功能可用性保障 -- 明确提示原因 - ---- - -## 六、可访问性优化 - -### 6.1 键盘导航 - -**实现**： -```vue - -
- -
-``` - -**支持快捷键**： -- `Space` - 暂停/继续 -- `Enter` - 结束会话 -- `Esc` - 关闭弹窗 -- `Tab` - 焦点切换 - -### 6.2 语义化 HTML - -**实现**： -```vue - -
-
-

复习概览

- -
-
- - -
-
-
复习概览
-
...
-
-
-``` - -**收益**： -- 屏幕阅读器友好 -- SEO 优化 -- 代码可读性高 - -### 6.3 色盲友好 - -**对比结果着色**： -- 匹配节点：绿色 `#c8e6c9` + ✓ 图标 -- 遗漏节点：红色 `#ffcdd2` + ✗ 图标 -- 额外节点：蓝色 `#bbdefb` + ★ 图标 - -**原则**：不仅依赖颜色，同时使用图标/文字辅助 - ---- - -## 七、构建优化 - -### 7.1 代码分割 - -**实现**： -```typescript -// router/index.ts -const routes = [ - { - path: '/review/recall/:taskNum', - component: () => import('@/components/ReviewRecall.vue') // 懒加载 - } -]; -``` - -**收益**： -- 首屏包体积：1.2MB → 320KB -- 按需加载（用户未访问的页面不下载） - -### 7.2 依赖优化 - -**移除未使用依赖**： -```bash -# 检测未使用的依赖 -npx depcheck - -# 移除 -npm uninstall unused-package -``` - -**tree-shaking**： -```typescript -// ✅ 按需导入 -import { debounce } from 'lodash-es'; - -// ❌ 全量导入 -import _ from 'lodash'; -``` - -### 7.3 CDN 加速 - -**生产环境**： -```html - - - -``` - -**收益**： -- 浏览器缓存复用 -- 减轻服务器压力 -- 提升加载速度 - ---- - -## 八、开发体验优化 - -### 8.1 TypeScript 类型安全 - -**API 响应类型**： -```typescript -// api/types.ts -export interface StandardMindMapResponse { - taskNum: number; - content: MindMapTreeNode; - outline: string; - generatedBy: 'BUILTIN' | 'AI' | 'USER'; - updatedAt: string; -} - -// 调用时自动补全 + 类型检查 -const res = await getStandardMindMap(taskNum); -console.log(res.data.generatedBy); // ✅ 类型安全 -``` - -### 8.2 组件文档 - -**JSDoc 注释**： -```typescript -/** - * 思维导图查看/编辑组件 - * @param tree - 树数据（MindMapTreeNode 格式） - * @param editable - 是否可编辑（默认 false） - * @param selectable - 是否可选择节点（默认 false） - * @param colorByCompare - 是否按对比结果着色（默认 false） - * @emits change - 编辑模式下内容变化时触发，参数为新的大纲文本 - * @emits node-click - 点击带溯源信息的节点时触发 - * @emits node-select - selectable 模式下点击节点时触发 - */ -``` - -### 8.3 开发环境代理 - -**解决跨域**： -```typescript -// vite.config.ts -export default defineConfig({ - server: { - proxy: { - '/api': { - target: 'http://localhost:8080', - changeOrigin: true - } - } - } -}); -``` - ---- - -## 九、性能指标 - -| 指标 | 目标 | 实测 | -|------|------|------| -| 首屏 FCP | <1.5s | 1.2s | -| 首屏 LCP | <2.5s | 1.8s | -| TTI | <3.5s | 2.9s | -| 路由切换 | <300ms | 180ms | -| Markdown 渲染（100行） | <50ms | 32ms | -| 思维导图渲染（200节点） | <500ms | 380ms | - ---- - -## 十、总结 - -前端实现中的关键优化： - -1. **组件设计**：单组件多模式、状态管理、交互优化 -2. **性能优化**：虚拟滚动、懒加载、防抖节流、代码分割 -3. **用户体验**：进度提示、即时反馈、降级 UI、快捷键 -4. **工程质量**：TypeScript、错误处理、可访问性、构建优化 - -这些优化使 LPT 前端不仅功能完整，而且性能优异、体验流畅、代码可维护。