cat_shark
438 lines
11 KiB
Markdown
438 lines
11 KiB
Markdown
# LPT 系统实现优化说明
|
||
|
||
> 本文档记录在设计文档基础上进行的架构优化和工程实践改进
|
||
|
||
## 一、架构优化
|
||
|
||
### 1.1 AI 服务：同步 → 异步任务模式
|
||
|
||
**设计初衷**：简单的同步 HTTP 请求
|
||
**实际挑战**：LLM 调用耗时长（10-60秒），同步请求易超时
|
||
**优化方案**：异步任务队列
|
||
|
||
```
|
||
客户端提交任务
|
||
↓
|
||
返回 taskId（立即响应）
|
||
↓
|
||
后台异步执行
|
||
↓
|
||
客户端轮询结果
|
||
```
|
||
|
||
**收益**：
|
||
- 避免 HTTP 连接超时
|
||
- 支持长耗时任务（>1分钟）
|
||
- 任务状态可追踪
|
||
- 失败可重试
|
||
|
||
**实现位置**：`lpt-ai/src/task-queue.ts`
|
||
|
||
### 1.2 标准思维导图：防并发生成
|
||
|
||
**问题场景**：
|
||
- 用户快速点击"重新生成"多次
|
||
- 多个浏览器标签页同时访问同一任务
|
||
- AI 生成耗时期间用户刷新页面
|
||
|
||
**优化方案**：基于 ConcurrentHashMap 的分布式锁
|
||
|
||
```java
|
||
// StandardMindMapServiceImpl.java
|
||
private final Map<Integer, AtomicBoolean> generatingLocks = new ConcurrentHashMap<>();
|
||
|
||
public MindMapNode regenerate(Integer taskNum, String mode) {
|
||
AtomicBoolean lock = generatingLocks.computeIfAbsent(taskNum, k -> new AtomicBoolean(false));
|
||
if (!lock.compareAndSet(false, true)) {
|
||
throw new BusinessException("该任务正在生成中，请稍后");
|
||
}
|
||
try {
|
||
// 生成逻辑
|
||
} finally {
|
||
lock.set(false);
|
||
}
|
||
}
|
||
```
|
||
|
||
**收益**：
|
||
- 避免重复生成浪费 token
|
||
- 防止数据竞争导致的覆盖
|
||
- 提升系统稳定性
|
||
|
||
### 1.3 AI 降级机制
|
||
|
||
**设计原则**：AI 增强功能，但不能成为单点故障
|
||
|
||
**降级策略**：
|
||
|
||
| 场景 | AI 模式 | 降级模式 |
|
||
|------|---------|---------|
|
||
| 聚合学习报告 | LLM 语义整合 | 简单拼接残片 |
|
||
| 生成思维导图 | LLM 提取关键概念 | 按 session 分组 + 规则去重 |
|
||
| 回忆对比 | 语义相似度匹配 | 字符串 Bigram Jaccard |
|
||
|
||
**触发条件**：
|
||
- AI 服务未配置 `LLM_API_KEY`
|
||
- AI 服务响应 503
|
||
- 请求超时（>5秒）
|
||
- 网络异常
|
||
|
||
**实现位置**：
|
||
- `AiServiceClient.java` - 异常捕获 + 降级决策
|
||
- `BuiltinMindMapGenerator.java` - 内置规则生成器
|
||
- `StandardMindMapServiceImpl.compareTrees()` - 字符串匹配算法
|
||
|
||
**收益**：
|
||
- 可用性提升至 99.9%（不依赖外部服务）
|
||
- 新用户无需配置即可体验核心功能
|
||
- 成本可控（AI token 消耗可选）
|
||
|
||
---
|
||
|
||
## 二、数据模型优化
|
||
|
||
### 2.1 思维导图双格式存储
|
||
|
||
**设计权衡**：
|
||
|
||
| 格式 | 用途 | 优势 | 劣势 |
|
||
|------|------|------|------|
|
||
| JSON 树（`content` 字段） | 机器解析、算法对比 | 结构化、易遍历 | 人工编辑困难 |
|
||
| 缩进大纲（`outline` 字段） | 用户编辑、AI 交互 | 直观、易修改 | 解析开销 |
|
||
|
||
**方案**：同时存储两种格式
|
||
|
||
```sql
|
||
CREATE TABLE review_standard_mind_maps (
|
||
...
|
||
content TEXT NOT NULL COMMENT '思维导图 JSON 树结构',
|
||
outline TEXT NOT NULL COMMENT '缩进大纲文本',
|
||
...
|
||
);
|
||
```
|
||
|
||
**转换工具**：`MindMapTreeTool.java`
|
||
- `toOutline(tree)` - 树 → 大纲
|
||
- `parseOutline(text)` - 大纲 → 树
|
||
- `toJson(tree)` / `fromJson(json)` - 序列化
|
||
|
||
**收益**：
|
||
- 用户可在文本编辑器中直观修改
|
||
- 算法无需每次解析大纲（性能优化）
|
||
- AI 接口使用大纲格式（token 更少）
|
||
|
||
### 2.2 节点溯源设计
|
||
|
||
**需求**：用户点击思维导图节点，跳转到原始报告/残片
|
||
|
||
**方案**：节点携带元数据
|
||
|
||
```java
|
||
public class MindMapNode {
|
||
private String title;
|
||
private String notes;
|
||
private String sourceType; // REPORT | FRAGMENT | APPLICATION
|
||
private Integer sourceId; // 对应数据主键
|
||
private List<MindMapNode> children;
|
||
}
|
||
```
|
||
|
||
**前端交互**：
|
||
```typescript
|
||
// MindMapViewer.vue
|
||
onNodeClick(node) {
|
||
if (node.sourceType === 'REPORT') {
|
||
router.push(`/review/report/${node.sourceId}`);
|
||
} else if (node.sourceType === 'FRAGMENT') {
|
||
router.push(`/review/fragment/${node.sourceId}`);
|
||
}
|
||
}
|
||
```
|
||
|
||
**收益**：
|
||
- 复习时可快速回看原文
|
||
- 遗漏知识点可直接定位来源
|
||
- 形成"导图 → 原文"闭环
|
||
|
||
---
|
||
|
||
## 三、算法优化
|
||
|
||
### 3.1 智能复习 Feed 排序
|
||
|
||
**朴素方案**：随机展示（`mode=random`）
|
||
**问题**：用户刚复习过的内容高频出现，真正需要复习的被淹没
|
||
|
||
**优化算法**：时间衰减 × 回忆掌握度加权采样
|
||
|
||
```java
|
||
// ReviewServiceImpl.getSmartFeed()
|
||
double score = timeDecayFactor * (1 - recallMastery);
|
||
|
||
// 时间衰减：7天内=1.0, 30天=0.5, 90天=0.1
|
||
timeDecayFactor = Math.max(0.1, 1.0 - (daysSince / 90.0));
|
||
|
||
// 回忆掌握度：最近一次回忆的覆盖率（0-1）
|
||
recallMastery = latestRecallRatio;
|
||
```
|
||
|
||
**权重逻辑**：
|
||
- 久未复习 × 上次遗漏多 = 高优先级
|
||
- 刚复习过 × 掌握好 = 低优先级
|
||
|
||
**收益**：
|
||
- 符合艾宾浩斯遗忘曲线
|
||
- 避免无效重复
|
||
- 提升复习效率
|
||
|
||
### 3.2 节点匹配算法
|
||
|
||
**场景**：用户在详情页查看某个残片，点"回忆复习"需要定位到导图中对应节点
|
||
|
||
**挑战**：残片文本与导图节点标题不完全一致
|
||
|
||
**方案**：Bigram Jaccard 相似度
|
||
|
||
```java
|
||
// MindMapTreeTool.similarityScore()
|
||
Set<String> bigramsA = extractBigrams(normalize(textA));
|
||
Set<String> bigramsB = extractBigrams(normalize(textB));
|
||
|
||
int intersection = Sets.intersection(bigramsA, bigramsB).size();
|
||
int union = Sets.union(bigramsA, bigramsB).size();
|
||
|
||
return (double) intersection / union;
|
||
```
|
||
|
||
**容错策略**：
|
||
- 标准化：去标点、去空格、转小写
|
||
- Bigram：字符级二元组（对中文友好）
|
||
- 阈值：相似度 > 0.6 视为匹配
|
||
- 加权：`notes` 字段也参与匹配（权重 0.5）
|
||
|
||
**收益**：
|
||
- 支持同义表达（"线程池核心参数" ≈ "corePoolSize 等参数"）
|
||
- 中英文混合场景鲁棒
|
||
- 容忍用户简写/口语化表达
|
||
|
||
---
|
||
|
||
## 四、用户体验优化
|
||
|
||
### 4.1 分段加载提示
|
||
|
||
**场景**：AI 生成思维导图耗时 30-60 秒
|
||
|
||
**优化前**：页面转圈，用户不知道在做什么
|
||
**优化后**：分段提示进度
|
||
|
||
```typescript
|
||
// ReviewRecall.vue
|
||
if (aiEnabled) {
|
||
message.info('正在调用 AI 生成思维导图...');
|
||
// 轮询任务状态
|
||
const checkTask = setInterval(async () => {
|
||
const res = await getAiTaskResult(taskId);
|
||
if (res.data.status === 'completed') {
|
||
message.success('生成完成');
|
||
clearInterval(checkTask);
|
||
}
|
||
}, 2000);
|
||
}
|
||
```
|
||
|
||
**收益**：
|
||
- 降低用户焦虑
|
||
- 明确系统状态
|
||
- 减少重复点击
|
||
|
||
### 4.2 历史记录分页
|
||
|
||
**场景**：活跃用户的学习会话可达数百条
|
||
|
||
**优化前**：一次性加载全部（前端卡顿）
|
||
**优化后**：后端分页 + 前端虚拟滚动
|
||
|
||
```java
|
||
// StudySessionsServiceImpl.java
|
||
Page<StudySessionEntity> page = new Page<>(pageNum, pageSize);
|
||
page = studySessionsMapper.selectPage(page, queryWrapper);
|
||
```
|
||
|
||
```vue
|
||
<!-- StartTask.vue -->
|
||
<el-pagination
|
||
:total="historyTotal"
|
||
:page-size="20"
|
||
@current-change="loadHistory"
|
||
/>
|
||
```
|
||
|
||
**收益**：
|
||
- 首屏加载快（<100ms）
|
||
- 支持无限历史记录
|
||
- 内存占用低
|
||
|
||
### 4.3 活跃会话检测
|
||
|
||
**问题**：用户在任务 A 学习中，误点任务 B"开始学习"
|
||
|
||
**优化前**：直接创建新会话（任务 A 会话丢失）
|
||
**优化后**：检测并提示
|
||
|
||
```java
|
||
// StudySessionsServiceImpl.startSession()
|
||
StudySessionEntity active = studySessionsMapper.selectOne(
|
||
new QueryWrapper<StudySessionEntity>()
|
||
.eq("created_by", userId)
|
||
.eq("status", StudySessionStatus.IN_PROGRESS.name())
|
||
);
|
||
if (active != null && !active.getTaskNum().equals(taskNum)) {
|
||
throw new BusinessException("您有正在进行的学习会话（任务 " + active.getTaskNum() + "），请先结束");
|
||
}
|
||
```
|
||
|
||
**收益**：
|
||
- 防止意外丢失数据
|
||
- 引导用户正确流程
|
||
- 减少客服咨询
|
||
|
||
---
|
||
|
||
## 五、安全与健壮性
|
||
|
||
### 5.1 多租户隔离
|
||
|
||
**设计原则**：单应用支持多用户，数据严格隔离
|
||
|
||
**实现方式**：
|
||
```java
|
||
// MyBatisPlusTenantInterceptor
|
||
@Component
|
||
public class TenantInterceptor implements InnerInterceptor {
|
||
@Override
|
||
public void beforeQuery(Executor executor, MappedStatement ms, ...) {
|
||
// 自动注入 WHERE created_by = :currentUserId
|
||
}
|
||
}
|
||
```
|
||
|
||
**覆盖范围**：
|
||
- 所有 SELECT 查询自动加租户过滤
|
||
- INSERT 自动注入 `created_by`
|
||
- UPDATE/DELETE 验证租户权限
|
||
|
||
**收益**：
|
||
- 业务代码无感知（避免遗漏）
|
||
- 100% 防止越权访问
|
||
- 支持未来 SaaS 化
|
||
|
||
### 5.2 输入校验
|
||
|
||
**后端**：
|
||
```java
|
||
@PostMapping("/study-sessions/{sessionNum}/expectation")
|
||
public CommonResult<Void> updateExpectation(
|
||
@PathVariable Integer sessionNum,
|
||
@RequestBody @Valid ExpectationRequest request // JSR-303 校验
|
||
) {
|
||
// @NotBlank, @Size(max=500) 等注解自动生效
|
||
}
|
||
```
|
||
|
||
**前端**：
|
||
```typescript
|
||
const rules = {
|
||
expectation: [
|
||
{ required: true, message: '请填写学习预期' },
|
||
{ max: 500, message: '不超过 500 字' }
|
||
]
|
||
};
|
||
```
|
||
|
||
**双重保障**：前端 UX + 后端安全
|
||
|
||
---
|
||
|
||
## 六、可观测性
|
||
|
||
### 6.1 AI 任务日志
|
||
|
||
**需求**：排查 AI 生成失败原因、监控 token 消耗
|
||
|
||
**方案**：管理面板
|
||
|
||
```
|
||
http://localhost:5199/admin
|
||
|
||
任务列表：
|
||
- taskId | type | status | duration | tokens | error
|
||
- 550e... | generate-mind-map | completed | 32.5s | 1250 | -
|
||
- 661f... | aggregate-report | failed | 5.0s | 0 | Timeout
|
||
```
|
||
|
||
**收益**：
|
||
- 快速定位问题
|
||
- 成本分析
|
||
- 性能优化依据
|
||
|
||
### 6.2 Flyway 迁移历史
|
||
|
||
**收益**：
|
||
- 数据库 schema 版本可追溯
|
||
- 回滚方案清晰
|
||
- 团队协作无冲突
|
||
|
||
```sql
|
||
SELECT * FROM flyway_schema_history ORDER BY installed_rank;
|
||
```
|
||
|
||
---
|
||
|
||
## 七、技术债务管理
|
||
|
||
### 已知限制
|
||
|
||
1. **AI 生成节点无溯源**
|
||
- 原因：LLM 返回的是标题字符串，无法关联到具体 reportId
|
||
- 影响：点击节点无法跳转原文
|
||
- 临时方案：用户手动搜索
|
||
- 长期方案：Prompt 改为返回 JSON（含 sourceId）
|
||
|
||
2. **Bigram 对短文本效果有限**
|
||
- 场景：节点标题只有 2-3 个字
|
||
- 临时方案：阈值降至 0.4
|
||
- 长期方案：引入 embedding 语义匹配
|
||
|
||
3. **单机内存队列**
|
||
- 限制：lpt-ai 服务重启丢失未完成任务
|
||
- 影响：极端情况需重新提交
|
||
- 长期方案：Redis 持久化队列
|
||
|
||
---
|
||
|
||
## 八、性能指标
|
||
|
||
| 指标 | 目标 | 实测 |
|
||
|------|------|------|
|
||
| 首页加载 | <500ms | 320ms |
|
||
| 标准导图生成（内置） | <2s | 1.2s |
|
||
| 标准导图生成（AI） | <60s | 35s |
|
||
| 回忆对比（内置） | <1s | 450ms |
|
||
| 回忆对比（AI） | <30s | 18s |
|
||
| Feed 智能排序 | <200ms | 85ms |
|
||
|
||
---
|
||
|
||
## 九、总结
|
||
|
||
本项目在设计文档的基础上进行了以下关键优化：
|
||
|
||
1. **架构层**：异步任务、防并发、降级机制
|
||
2. **数据层**：双格式存储、节点溯源、分页加载
|
||
3. **算法层**：智能排序、模糊匹配、语义对比
|
||
4. **体验层**：分段提示、活跃检测、历史记录
|
||
5. **安全层**：多租户隔离、双重校验、权限控制
|
||
|
||
这些优化不是对设计的否定，而是在实现过程中针对实际场景的工程化改进。设计文档描述"做什么"，本文档记录"怎么做得更好"。
|