feat: 标签范围回忆对比与记录口径

This commit is contained in:
2026-10-10 16:08:48 +08:00
parent 6a30022af5
commit 4b30c88b7f
12 changed files with 386 additions and 5 deletions
@@ -5,6 +5,7 @@ import com.guo.learningprogresstracker.dto.TagScope;
import com.guo.learningprogresstracker.dto.request.TagScopeRequest;
import com.guo.learningprogresstracker.dto.request.UpdateTagMindMapRequest;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.service.ReviewTagMindMapService;
@@ -13,6 +14,8 @@ import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import java.util.List;
/**
* 标签导图控制层(闭环-04)。
*
@@ -31,7 +34,7 @@ public class TagMindMapController {
private final ReviewTagMindMapService reviewTagMindMapService;
/**
* 读取该范围的状态:范围键、标签集合与已有导图。
* 读取该范围的状态:范围键、标签集合、已有导图与最近一次回忆对比。
*
* <p>读取不触发生成:没有导图时 {@code map} 为 null,由前端提交生成任务。
* 用请求体而不是查询参数,是因为标签名由用户自由输入、可能含逗号。</p>
@@ -52,4 +55,14 @@ public class TagMindMapController {
TagScope scope = reviewTagMindMapService.resolveScope(request.getTags(), request.getMode());
return CommonResult.success(reviewTagMindMapService.updateByOutline(scope, request.getOutline()));
}
/**
* 该范围的回忆对比记录(倒序,最近一次在最前);范围里没有记录时返回空列表。
*/
@PostMapping("/recall-records")
public CommonResult<List<ReviewRecallRecordEntity>> listRecallRecords(
@Valid @RequestBody TagScopeRequest request) throws ErrorParameterException {
TagScope scope = reviewTagMindMapService.resolveScope(request.getTags(), request.getMode());
return CommonResult.success(reviewTagMindMapService.listRecallRecords(scope));
}
}
@@ -1,5 +1,6 @@
package com.guo.learningprogresstracker.dto;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
@@ -27,4 +28,7 @@ public class TagMindMapView {
@Schema(description = "该范围已有的标签导图;没有时为 null")
private ReviewTagMindMapEntity map;
@Schema(description = "该范围最近一次回忆对比记录;没复习过时为 null")
private ReviewRecallRecordEntity latestRecallRecord;
}
@@ -18,14 +18,32 @@ public class ReviewRecallRecordEntity extends BaseEntity implements Serializable
@TableId(value = "id", type = IdType.AUTO)
private Integer id;
/** 任务编码;标签范围复习时为空,取值口径见 {@code scopeType} */
@TableField(value = "task_num")
private String taskNum;
/** 复习范围:TASK=任务导图 / TAG=标签导图,取值见 {@code ReviewScopeTypeEnum} */
@TableField(value = "scope_type")
private String scopeType;
/** 标签范围的规范键(与标签导图同源);任务范围为空 */
@TableField(value = "scope_key")
private String scopeKey;
/** 范围的标签集合(JSON 数组,按归一化名排序);任务范围为空 */
@TableField(value = "scope_tags")
private String scopeTags;
/** 标签范围的取数模式:UNION / INTERSECT;任务范围为空 */
@TableField(value = "scope_mode")
private String scopeMode;
/** 对比时使用的基准导图 ID:任务范围指向任务导图,标签范围指向标签导图 */
@TableField(value = "standard_map_id")
private Integer standardMapId;
/**
* 复习起点节点路径(以 / 分隔),null 表示任务维度复习
* 复习起点节点路径(以 / 分隔),null 表示整棵树
*/
@TableField(value = "focus_path")
private String focusPath;
@@ -19,6 +19,9 @@ public enum AiTaskTypeEnum {
/** 标签思维导图生成:按「标签集合 + 取数模式」生成或重建(闭环-04) */
TAG_MIND_MAP("标签思维导图生成"),
/** 标签范围回忆对比:把用户回忆大纲与标签导图对比(闭环-04) */
TAG_RECALL_COMPARE("标签回忆对比"),
/** 学习报告草稿聚合 */
REPORT_DRAFT("学习报告草稿"),
@@ -0,0 +1,23 @@
package com.guo.learningprogresstracker.enums;
import lombok.AllArgsConstructor;
import lombok.Getter;
/**
* 回忆记录的复习范围(闭环-04)。
*
* <p>两种范围并存、互不替代:任务范围取材于内容归属为该任务的碎片,标签范围取材于带该标签集合的碎片。
* 范围落在回忆记录上,让复习耗时与覆盖率统计仍然可用。</p>
*/
@Getter
@AllArgsConstructor
public enum ReviewScopeTypeEnum {
/** 任务导图:复习对象是一个学习任务 */
TASK("任务"),
/** 标签导图:复习对象是一个标签集合 + 取数模式 */
TAG("标签");
private final String description;
}
@@ -1,7 +1,10 @@
package com.guo.learningprogresstracker.service;
import com.guo.learningprogresstracker.dto.RecallCompareOutcome;
import com.guo.learningprogresstracker.dto.ReviewTiming;
import com.guo.learningprogresstracker.dto.TagMindMapView;
import com.guo.learningprogresstracker.dto.TagScope;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
@@ -33,7 +36,7 @@ public interface ReviewTagMindMapService {
TagScope resolveScope(List<String> tags, String mode) throws ErrorParameterException;
/**
* 读取该范围的状态:范围描述 + 已有导图;读取不触发生成。
* 读取该范围的状态:范围描述 + 已有导图 + 最近一次回忆对比;读取不触发生成。
*/
TagMindMapView query(TagScope scope);
@@ -52,6 +55,24 @@ public interface ReviewTagMindMapService {
*/
ReviewTagMindMapEntity incrementalGenerate(TagScope scope) throws NotFindEntitiesException, OperationFailedException;
/**
* 提交一次标签范围的回忆对比并落回忆记录(范围=标签集合 + 取数模式,任务列为空)。
*
* <p>由 AI 任务执行器在请求线程之外调用;方法本身不持有事务,避免等待 AI 时占用数据库连接。</p>
*
* @param recallOutline 用户回忆的缩进大纲文本
* @param focusPath 可选:标签导图中的节点路径(/ 分隔),指定后仅对比该子树
* @param timing 可选:本次复习行为的计时信息(复习-07),为空时不计复习耗时
* @return 对比结果;其中 {@code standardMapId} 是本次对比使用的基准导图 ID(标签范围下即标签导图 ID)
*/
RecallCompareOutcome recallCompare(TagScope scope, String recallOutline, String focusPath, ReviewTiming timing)
throws OperationFailedException;
/**
* 该范围的回忆对比记录(倒序,最近一次在最前)。
*/
List<ReviewRecallRecordEntity> listRecallRecords(TagScope scope);
/**
* 素材发生变化时的置「待更新」(不重建)。
*
@@ -3,21 +3,29 @@ package com.guo.learningprogresstracker.service.impl;
import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.guo.learningprogresstracker.dto.FragmentTagMatch;
import com.guo.learningprogresstracker.dto.RecallCompareOutcome;
import com.guo.learningprogresstracker.dto.ReviewTiming;
import com.guo.learningprogresstracker.dto.TagMindMapView;
import com.guo.learningprogresstracker.dto.TagScope;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.TaskEntity;
import com.guo.learningprogresstracker.enums.ReviewScopeTypeEnum;
import com.guo.learningprogresstracker.enums.TagCombineModeEnum;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.mapper.MarkerMapper;
import com.guo.learningprogresstracker.mapper.ReviewRecallRecordMapper;
import com.guo.learningprogresstracker.mapper.ReviewTagMindMapMapper;
import com.guo.learningprogresstracker.mapper.StudyReportFragmentsMapper;
import com.guo.learningprogresstracker.service.ReviewTagMindMapService;
import com.guo.learningprogresstracker.service.StandardMindMapService;
import com.guo.learningprogresstracker.utils.CompareResult;
import com.guo.learningprogresstracker.utils.MindMapNode;
import com.guo.learningprogresstracker.utils.MindMapTreeTool;
import com.guo.learningprogresstracker.utils.ReviewDurationTool;
import com.guo.learningprogresstracker.utils.TagScopeTool;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
@@ -35,8 +43,9 @@ import java.util.Set;
/**
* 标签思维导图服务实现(闭环-04)。
*
* <p>取材与生成两条链路都刻意与任务导图共用口径:素材来自带这些标签的碎片(软删除的不取材),
* 生成走 {@link MindMapOutlineGenerator}(AI 优先、内置规则降级)。</p>
* <p>取材、生成、对比三条链路都刻意与任务导图共用口径:素材来自带这些标签的碎片(软删除的不取材),
* 生成走 {@link MindMapOutlineGenerator}(AI 优先、内置规则降级),对比走
* {@link StandardMindMapService#compareWithRecall}(AI 语义对比、失败降级文本匹配)。</p>
*/
@Slf4j
@Service
@@ -51,8 +60,10 @@ public class ReviewTagMindMapServiceImpl implements ReviewTagMindMapService {
private static final int MAX_TAG_NAME_LENGTH = 100;
private final ReviewTagMindMapMapper tagMindMapMapper;
private final ReviewRecallRecordMapper recallRecordMapper;
private final MarkerMapper markerMapper;
private final StudyReportFragmentsMapper studyReportFragmentsMapper;
private final StandardMindMapService standardMindMapService;
private final MindMapOutlineGenerator outlineGenerator;
private final ObjectMapper objectMapper;
@@ -97,9 +108,17 @@ public class ReviewTagMindMapServiceImpl implements ReviewTagMindMapService {
view.setTags(scope.tags());
view.setMode(scope.mode().name());
view.setMap(queryByScopeKey(scope.scopeKey()));
view.setLatestRecallRecord(latestRecallRecord(scope.scopeKey()));
return view;
}
@Override
public List<ReviewRecallRecordEntity> listRecallRecords(TagScope scope) {
return recallRecordMapper.selectList(Wrappers.<ReviewRecallRecordEntity>lambdaQuery()
.eq(ReviewRecallRecordEntity::getScopeKey, scope.scopeKey())
.orderByDesc(ReviewRecallRecordEntity::getCreatedTime));
}
// ============ 用户编辑 ============
@Override
@@ -165,6 +184,72 @@ public class ReviewTagMindMapServiceImpl implements ReviewTagMindMapService {
return existing;
}
// ============ 回忆对比 ============
@Override
public RecallCompareOutcome recallCompare(TagScope scope, String recallOutline, String focusPath,
ReviewTiming timing) throws OperationFailedException {
// 1. 取该范围的标签导图;缺失时按需生成(可能调用 AI,故整个方法不持有事务)
ReviewTagMindMapEntity base = queryByScopeKey(scope.scopeKey());
if (base == null) {
base = doGenerate(scope);
}
// 2. 解析基准树;指定起点时只对比该子树
MindMapNode standardRoot = MindMapTreeTool.fromJson(base.getContent(), objectMapper);
MindMapNode compareRoot = standardRoot;
if (StringUtils.hasText(focusPath)) {
MindMapNode subtree = MindMapTreeTool.extractSubtree(standardRoot, focusPath);
if (subtree == null) {
log.warn("focusPath 未匹配到节点,使用全量标签导图: scopeKey={}, path={}", scope.scopeKey(), focusPath);
} else {
compareRoot = subtree;
}
}
// 3. 执行对比(AI 语义对比优先,失败降级文本匹配):与任务导图共用同一套口径
CompareResult result = standardMindMapService.compareWithRecall(scope.displayName(), compareRoot, recallOutline);
// 4. 序列化对比结果
String resultJson;
try {
resultJson = objectMapper.writeValueAsString(result);
} catch (Exception e) {
log.error("标签范围[{}]对比结果序列化失败", scope.scopeKey(), e);
throw new OperationFailedException("对比结果解析失败了,请稍后再试");
}
// 5. 保存回忆记录:范围=标签集合 + 取数模式,任务列为空(任务范围的统计口径因此不受影响)
ReviewRecallRecordEntity record = new ReviewRecallRecordEntity();
record.setTaskNum(null);
record.setScopeType(ReviewScopeTypeEnum.TAG.name());
record.setScopeKey(scope.scopeKey());
record.setScopeTags(TagScopeTool.toStoredTags(scope.tags()));
record.setScopeMode(scope.mode().name());
record.setStandardMapId(base.getId());
record.setFocusPath(StringUtils.hasText(focusPath) ? focusPath : null);
record.setRecallContent(recallOutline);
record.setCompareResult(resultJson);
record.setRecallRatio(result.getRecallRatio());
record.setMatchedCount(result.getMatchedCount());
record.setMissedCount(result.getMissedCount());
record.setExtraCount(result.getExtraCount());
record.setReviewDurationSeconds(ReviewDurationTool.resolveSeconds(
timing == null ? null : timing.startedAt(),
timing == null ? null : timing.lastInteractionAt(),
timing == null ? null : timing.durationSeconds(),
LocalDateTime.now()));
recallRecordMapper.insert(record);
log.info("标签范围回忆对比: scopeKey={}, tags={}, mode={}, recallRatio={}, matched={}, missed={}, extra={}, 复习耗时={}秒",
scope.scopeKey(), scope.displayName(), scope.mode(), result.getRecallRatio(),
result.getMatchedCount(), result.getMissedCount(), result.getExtraCount(),
record.getReviewDurationSeconds());
return new RecallCompareOutcome(base.getId(), record.getId(), result.getRecallRatio(),
result.getMatchedCount(), result.getMissedCount(), result.getExtraCount());
}
// ============ 素材变化 ============
@Override
@@ -258,6 +343,13 @@ public class ReviewTagMindMapServiceImpl implements ReviewTagMindMapService {
.last("LIMIT 1"));
}
private ReviewRecallRecordEntity latestRecallRecord(String scopeKey) {
return recallRecordMapper.selectOne(Wrappers.<ReviewRecallRecordEntity>lambdaQuery()
.eq(ReviewRecallRecordEntity::getScopeKey, scopeKey)
.orderByDesc(ReviewRecallRecordEntity::getId)
.last("LIMIT 1"));
}
/**
* 取数:带这些标签的知识碎片。并集取「带任一标签」,交集取「同时带全部标签」;
* 软删除的碎片由 {@code @TableLogic} 自动排除。
@@ -6,6 +6,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
import com.guo.learningprogresstracker.dto.RecallCompareOutcome;
import com.guo.learningprogresstracker.dto.ReviewTiming;
import com.guo.learningprogresstracker.entity.*;
import com.guo.learningprogresstracker.enums.ReviewScopeTypeEnum;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.mapper.*;
@@ -163,6 +164,8 @@ public class StandardMindMapServiceImpl implements StandardMindMapService {
// 5. 保存回忆记录
ReviewRecallRecordEntity record = new ReviewRecallRecordEntity();
record.setTaskNum(taskNum);
// 任务范围的复习范围列:任务导图;标签范围的行由标签导图服务自己写
record.setScopeType(ReviewScopeTypeEnum.TASK.name());
record.setStandardMapId(standard.getId());
record.setFocusPath(focusPath != null && !focusPath.isBlank() ? focusPath : null);
record.setRecallContent(recallOutline);
@@ -0,0 +1,69 @@
package com.guo.learningprogresstracker.service.impl;
import com.guo.learningprogresstracker.dto.RecallCompareOutcome;
import com.guo.learningprogresstracker.dto.ReviewTiming;
import com.guo.learningprogresstracker.dto.TagScope;
import com.guo.learningprogresstracker.entity.AiTaskEntity;
import com.guo.learningprogresstracker.enums.AiTaskTypeEnum;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.service.ReviewTagMindMapService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import java.util.Map;
/**
* 标签范围回忆对比任务(闭环-04)。
*
* <p>任务目标 {@code targetNum} 是标签范围的规范键;范围与回忆内容由参数给出
* ({@code tags}、{@code combineMode}、{@code recallOutline}、{@code focusPath} 与复习计时字段,
* 后四项与任务范围回忆对比同名同义)。对比落在回忆记录里,范围=标签集合 + 取数模式,任务列为空。</p>
*/
@Slf4j
@Component
@RequiredArgsConstructor
public class TagRecallCompareAiTaskHandler implements AiTaskHandler {
private final ReviewTagMindMapService reviewTagMindMapService;
@Override
public AiTaskTypeEnum type() {
return AiTaskTypeEnum.TAG_RECALL_COMPARE;
}
@Override
public Map<String, Object> execute(AiTaskEntity task, Map<String, Object> params) {
String recallOutline = AiTaskParams.asString(params, "recallOutline");
if (!StringUtils.hasText(recallOutline)) {
throw new AiTaskFailedException("请先填写回忆大纲");
}
try {
TagScope scope = reviewTagMindMapService.resolveScope(
AiTaskParams.asStringList(params, "tags"), AiTaskParams.asString(params, "combineMode"));
requireScopeMatches(task, scope);
ReviewTiming timing = new ReviewTiming(
AiTaskParams.asLocalDateTime(params, "reviewStartedAt"),
AiTaskParams.asLocalDateTime(params, "reviewLastInteractionAt"),
AiTaskParams.asInteger(params, "reviewDurationSeconds"));
RecallCompareOutcome outcome = reviewTagMindMapService.recallCompare(
scope, recallOutline, AiTaskParams.asString(params, "focusPath"), timing);
return outcome.toPayload();
} catch (ErrorParameterException | OperationFailedException e) {
throw new AiTaskFailedException(e.getMessage());
}
}
/** 任务目标必须是这批参数算出来的范围键:不一致时宁可失败,也不要把记录落到别的范围上 */
private void requireScopeMatches(AiTaskEntity task, TagScope scope) {
if (!scope.scopeKey().equals(task.getTargetNum())) {
log.warn("标签回忆对比任务的参数与目标不一致: targetNum={}, 参数范围={}",
task.getTargetNum(), scope.scopeKey());
throw new AiTaskFailedException("标签范围和导图标识对不上,请刷新页面后重试");
}
}
}
@@ -0,0 +1,17 @@
-- 闭环-04:回忆记录增加「复习范围」列,让按标签范围的复习也能落记录。
--
-- 口径来源(2026-10-10 维护者确认,结论见 lpt-docs/docs/concepts/recall-review.md):
-- 复习范围既可以是任务(任务导图),也可以是标签集合 + 取数模式(标签导图)。
-- 标签范围的记录不再挂在任务上,因此 task_num 改为可空;任务范围的行照旧带 task_num,
-- 既有按任务的查询与统计口径(覆盖率、复习耗时)因此完全不变。
-- scope_key 是标签范围的规范键(与 review_tag_mind_maps.scope_key 同源),
-- 标签集合与模式另存可读副本,便于回看「这次复习的是哪些标签」。
alter table review_recall_records modify column task_num varchar(255) null comment '任务编码;标签范围复习时为空';
alter table review_recall_records add column scope_type varchar(20) not null default 'TASK' comment '复习范围:TASK=任务导图 / TAG=标签导图' after task_num;
alter table review_recall_records add column scope_key varchar(64) null comment '标签范围的规范键(见 review_tag_mind_maps.scope_key);任务范围为空' after scope_type;
alter table review_recall_records add column scope_tags varchar(1100) null comment '范围的标签集合(JSON 数组,按归一化名排序);任务范围为空' after scope_key;
alter table review_recall_records add column scope_mode varchar(20) null comment '标签范围的取数模式:UNION / INTERSECT;任务范围为空' after scope_tags;
-- 按标签范围取历史(含最近一次):WHERE created_by = ? AND scope_key = ? ORDER BY id DESC
-- 键长:created_by(255×4) + scope_key(64×4) = 1276 字节,未越过 InnoDB 3072 字节上限。
create index idx_recall_records_scope on review_recall_records (created_by, scope_key);