From 4b30c88b7fd9fe5a8b249f938d4015a69f1c2fe9 Mon Sep 17 00:00:00 2001
From: cat-shark <1716967236@qq.com>
Date: Sat, 10 Oct 2026 16:08:48 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=A0=87=E7=AD=BE=E8=8C=83=E5=9B=B4?=
=?UTF-8?q?=E5=9B=9E=E5=BF=86=E5=AF=B9=E6=AF=94=E4=B8=8E=E8=AE=B0=E5=BD=95?=
=?UTF-8?q?=E5=8F=A3=E5=BE=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.../controller/TagMindMapController.java | 15 ++-
.../dto/TagMindMapView.java | 4 +
.../entity/ReviewRecallRecordEntity.java | 20 +++-
.../enums/AiTaskTypeEnum.java | 3 +
.../enums/ReviewScopeTypeEnum.java | 23 ++++
.../service/ReviewTagMindMapService.java | 23 +++-
.../impl/ReviewTagMindMapServiceImpl.java | 96 +++++++++++++++-
.../impl/StandardMindMapServiceImpl.java | 3 +
.../impl/TagRecallCompareAiTaskHandler.java | 69 ++++++++++++
.../V20261010_3__add_recall_scope_columns.sql | 17 +++
.../TagMindMapControllerUnitTest.java | 12 ++
.../impl/TagMindMapIntegrationTest.java | 106 ++++++++++++++++++
12 files changed, 386 insertions(+), 5 deletions(-)
create mode 100644 src/main/java/com/guo/learningprogresstracker/enums/ReviewScopeTypeEnum.java
create mode 100644 src/main/java/com/guo/learningprogresstracker/service/impl/TagRecallCompareAiTaskHandler.java
create mode 100644 src/main/resources/db/migration/V20261010_3__add_recall_scope_columns.sql
diff --git a/src/main/java/com/guo/learningprogresstracker/controller/TagMindMapController.java b/src/main/java/com/guo/learningprogresstracker/controller/TagMindMapController.java
index da7342e..274cc32 100644
--- a/src/main/java/com/guo/learningprogresstracker/controller/TagMindMapController.java
+++ b/src/main/java/com/guo/learningprogresstracker/controller/TagMindMapController.java
@@ -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;
/**
- * 读取该范围的状态:范围键、标签集合与已有导图。
+ * 读取该范围的状态:范围键、标签集合、已有导图与最近一次回忆对比。
*
*
读取不触发生成:没有导图时 {@code map} 为 null,由前端提交生成任务。
* 用请求体而不是查询参数,是因为标签名由用户自由输入、可能含逗号。
@@ -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> listRecallRecords(
+ @Valid @RequestBody TagScopeRequest request) throws ErrorParameterException {
+ TagScope scope = reviewTagMindMapService.resolveScope(request.getTags(), request.getMode());
+ return CommonResult.success(reviewTagMindMapService.listRecallRecords(scope));
+ }
}
diff --git a/src/main/java/com/guo/learningprogresstracker/dto/TagMindMapView.java b/src/main/java/com/guo/learningprogresstracker/dto/TagMindMapView.java
index d42b8cb..80ba372 100644
--- a/src/main/java/com/guo/learningprogresstracker/dto/TagMindMapView.java
+++ b/src/main/java/com/guo/learningprogresstracker/dto/TagMindMapView.java
@@ -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;
}
diff --git a/src/main/java/com/guo/learningprogresstracker/entity/ReviewRecallRecordEntity.java b/src/main/java/com/guo/learningprogresstracker/entity/ReviewRecallRecordEntity.java
index f39d521..aa94278 100644
--- a/src/main/java/com/guo/learningprogresstracker/entity/ReviewRecallRecordEntity.java
+++ b/src/main/java/com/guo/learningprogresstracker/entity/ReviewRecallRecordEntity.java
@@ -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;
diff --git a/src/main/java/com/guo/learningprogresstracker/enums/AiTaskTypeEnum.java b/src/main/java/com/guo/learningprogresstracker/enums/AiTaskTypeEnum.java
index a1c99a2..7207934 100644
--- a/src/main/java/com/guo/learningprogresstracker/enums/AiTaskTypeEnum.java
+++ b/src/main/java/com/guo/learningprogresstracker/enums/AiTaskTypeEnum.java
@@ -19,6 +19,9 @@ public enum AiTaskTypeEnum {
/** 标签思维导图生成:按「标签集合 + 取数模式」生成或重建(闭环-04) */
TAG_MIND_MAP("标签思维导图生成"),
+ /** 标签范围回忆对比:把用户回忆大纲与标签导图对比(闭环-04) */
+ TAG_RECALL_COMPARE("标签回忆对比"),
+
/** 学习报告草稿聚合 */
REPORT_DRAFT("学习报告草稿"),
diff --git a/src/main/java/com/guo/learningprogresstracker/enums/ReviewScopeTypeEnum.java b/src/main/java/com/guo/learningprogresstracker/enums/ReviewScopeTypeEnum.java
new file mode 100644
index 0000000..9794108
--- /dev/null
+++ b/src/main/java/com/guo/learningprogresstracker/enums/ReviewScopeTypeEnum.java
@@ -0,0 +1,23 @@
+package com.guo.learningprogresstracker.enums;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * 回忆记录的复习范围(闭环-04)。
+ *
+ * 两种范围并存、互不替代:任务范围取材于内容归属为该任务的碎片,标签范围取材于带该标签集合的碎片。
+ * 范围落在回忆记录上,让复习耗时与覆盖率统计仍然可用。
+ */
+@Getter
+@AllArgsConstructor
+public enum ReviewScopeTypeEnum {
+
+ /** 任务导图:复习对象是一个学习任务 */
+ TASK("任务"),
+
+ /** 标签导图:复习对象是一个标签集合 + 取数模式 */
+ TAG("标签");
+
+ private final String description;
+}
diff --git a/src/main/java/com/guo/learningprogresstracker/service/ReviewTagMindMapService.java b/src/main/java/com/guo/learningprogresstracker/service/ReviewTagMindMapService.java
index 26cd9ad..4bee6c4 100644
--- a/src/main/java/com/guo/learningprogresstracker/service/ReviewTagMindMapService.java
+++ b/src/main/java/com/guo/learningprogresstracker/service/ReviewTagMindMapService.java
@@ -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 tags, String mode) throws ErrorParameterException;
/**
- * 读取该范围的状态:范围描述 + 已有导图;读取不触发生成。
+ * 读取该范围的状态:范围描述 + 已有导图 + 最近一次回忆对比;读取不触发生成。
*/
TagMindMapView query(TagScope scope);
@@ -52,6 +55,24 @@ public interface ReviewTagMindMapService {
*/
ReviewTagMindMapEntity incrementalGenerate(TagScope scope) throws NotFindEntitiesException, OperationFailedException;
+ /**
+ * 提交一次标签范围的回忆对比并落回忆记录(范围=标签集合 + 取数模式,任务列为空)。
+ *
+ * 由 AI 任务执行器在请求线程之外调用;方法本身不持有事务,避免等待 AI 时占用数据库连接。
+ *
+ * @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 listRecallRecords(TagScope scope);
+
/**
* 素材发生变化时的置「待更新」(不重建)。
*
diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/ReviewTagMindMapServiceImpl.java b/src/main/java/com/guo/learningprogresstracker/service/impl/ReviewTagMindMapServiceImpl.java
index ed78240..55fbe1f 100644
--- a/src/main/java/com/guo/learningprogresstracker/service/impl/ReviewTagMindMapServiceImpl.java
+++ b/src/main/java/com/guo/learningprogresstracker/service/impl/ReviewTagMindMapServiceImpl.java
@@ -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)。
*
- * 取材与生成两条链路都刻意与任务导图共用口径:素材来自带这些标签的碎片(软删除的不取材),
- * 生成走 {@link MindMapOutlineGenerator}(AI 优先、内置规则降级)。
+ * 取材、生成、对比三条链路都刻意与任务导图共用口径:素材来自带这些标签的碎片(软删除的不取材),
+ * 生成走 {@link MindMapOutlineGenerator}(AI 优先、内置规则降级),对比走
+ * {@link StandardMindMapService#compareWithRecall}(AI 语义对比、失败降级文本匹配)。
*/
@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 listRecallRecords(TagScope scope) {
+ return recallRecordMapper.selectList(Wrappers.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.lambdaQuery()
+ .eq(ReviewRecallRecordEntity::getScopeKey, scopeKey)
+ .orderByDesc(ReviewRecallRecordEntity::getId)
+ .last("LIMIT 1"));
+ }
+
/**
* 取数:带这些标签的知识碎片。并集取「带任一标签」,交集取「同时带全部标签」;
* 软删除的碎片由 {@code @TableLogic} 自动排除。
diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImpl.java b/src/main/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImpl.java
index a322334..d793d77 100644
--- a/src/main/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImpl.java
+++ b/src/main/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImpl.java
@@ -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);
diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/TagRecallCompareAiTaskHandler.java b/src/main/java/com/guo/learningprogresstracker/service/impl/TagRecallCompareAiTaskHandler.java
new file mode 100644
index 0000000..5800352
--- /dev/null
+++ b/src/main/java/com/guo/learningprogresstracker/service/impl/TagRecallCompareAiTaskHandler.java
@@ -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)。
+ *
+ * 任务目标 {@code targetNum} 是标签范围的规范键;范围与回忆内容由参数给出
+ * ({@code tags}、{@code combineMode}、{@code recallOutline}、{@code focusPath} 与复习计时字段,
+ * 后四项与任务范围回忆对比同名同义)。对比落在回忆记录里,范围=标签集合 + 取数模式,任务列为空。
+ */
+@Slf4j
+@Component
+@RequiredArgsConstructor
+public class TagRecallCompareAiTaskHandler implements AiTaskHandler {
+
+ private final ReviewTagMindMapService reviewTagMindMapService;
+
+ @Override
+ public AiTaskTypeEnum type() {
+ return AiTaskTypeEnum.TAG_RECALL_COMPARE;
+ }
+
+ @Override
+ public Map execute(AiTaskEntity task, Map 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("标签范围和导图标识对不上,请刷新页面后重试");
+ }
+ }
+}
diff --git a/src/main/resources/db/migration/V20261010_3__add_recall_scope_columns.sql b/src/main/resources/db/migration/V20261010_3__add_recall_scope_columns.sql
new file mode 100644
index 0000000..a2bf6b3
--- /dev/null
+++ b/src/main/resources/db/migration/V20261010_3__add_recall_scope_columns.sql
@@ -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);
diff --git a/src/test/java/com/guo/learningprogresstracker/controller/TagMindMapControllerUnitTest.java b/src/test/java/com/guo/learningprogresstracker/controller/TagMindMapControllerUnitTest.java
index 61d93be..1146d83 100644
--- a/src/test/java/com/guo/learningprogresstracker/controller/TagMindMapControllerUnitTest.java
+++ b/src/test/java/com/guo/learningprogresstracker/controller/TagMindMapControllerUnitTest.java
@@ -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.enums.TagCombineModeEnum;
import com.guo.learningprogresstracker.service.ReviewTagMindMapService;
@@ -86,4 +87,15 @@ class TagMindMapControllerUnitTest {
assertSame(updated, result.getData());
}
+ @Test
+ void listRecallRecords_returnsRangeHistory() throws Exception {
+ List records = List.of(new ReviewRecallRecordEntity());
+ when(reviewTagMindMapService.resolveScope(List.of("Java", "并发"), "UNION")).thenReturn(scope());
+ when(reviewTagMindMapService.listRecallRecords(scope())).thenReturn(records);
+
+ CommonResult> result = controller.listRecallRecords(request("UNION"));
+
+ assertEquals(200, result.getCode());
+ assertSame(records, result.getData());
+ }
}
diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/TagMindMapIntegrationTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/TagMindMapIntegrationTest.java
index 6588603..21c56a1 100644
--- a/src/test/java/com/guo/learningprogresstracker/service/impl/TagMindMapIntegrationTest.java
+++ b/src/test/java/com/guo/learningprogresstracker/service/impl/TagMindMapIntegrationTest.java
@@ -3,18 +3,25 @@ package com.guo.learningprogresstracker.service.impl;
import cn.dev33.satoken.stp.StpUtil;
import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import com.guo.learningprogresstracker.dto.AiTaskResponse;
+import com.guo.learningprogresstracker.dto.RecallCompareOutcome;
+import com.guo.learningprogresstracker.dto.ReviewTiming;
+import com.guo.learningprogresstracker.dto.TaskRecallRatio;
+import com.guo.learningprogresstracker.dto.TaskReviewDuration;
import com.guo.learningprogresstracker.dto.TagScope;
import com.guo.learningprogresstracker.dto.request.AiTaskSubmitRequest;
import com.guo.learningprogresstracker.dto.request.CreateFragmentsRequest;
+import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.StudySessionsEntity;
import com.guo.learningprogresstracker.entity.TaskEntity;
import com.guo.learningprogresstracker.enums.AiTaskStatusEnum;
import com.guo.learningprogresstracker.enums.MarkerObjectTypeEnum;
+import com.guo.learningprogresstracker.enums.ReviewScopeTypeEnum;
import com.guo.learningprogresstracker.enums.TagCombineModeEnum;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
+import com.guo.learningprogresstracker.mapper.ReviewRecallRecordMapper;
import com.guo.learningprogresstracker.mapper.ReviewTagMindMapMapper;
import com.guo.learningprogresstracker.mapper.StudyReportFragmentsMapper;
import com.guo.learningprogresstracker.mapper.StudySessionsMapper;
@@ -22,8 +29,10 @@ import com.guo.learningprogresstracker.mapper.TasksMapper;
import com.guo.learningprogresstracker.service.AiTaskService;
import com.guo.learningprogresstracker.service.MarkerService;
import com.guo.learningprogresstracker.service.ReviewTagMindMapService;
+import com.guo.learningprogresstracker.service.StandardMindMapService;
import com.guo.learningprogresstracker.service.StudyReportFragmentsService;
import com.guo.learningprogresstracker.utils.GenerateNumTool;
+import com.guo.learningprogresstracker.utils.TagScopeTool;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
@@ -33,6 +42,7 @@ import org.springframework.boot.test.mock.mockito.MockBean;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;
+import java.util.Set;
import java.util.concurrent.atomic.AtomicInteger;
import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -67,6 +77,9 @@ class TagMindMapIntegrationTest {
@Autowired
private ReviewTagMindMapMapper tagMindMapMapper;
+ @Autowired
+ private ReviewRecallRecordMapper recallRecordMapper;
+
@Autowired
private MarkerService markerService;
@@ -82,6 +95,9 @@ class TagMindMapIntegrationTest {
@Autowired
private TasksMapper tasksMapper;
+ @Autowired
+ private StandardMindMapService standardMindMapService;
+
@Autowired
private AiTaskService aiTaskService;
@@ -343,6 +359,71 @@ class TagMindMapIntegrationTest {
assertFalse(map.getOutline().contains("其他用户的碎片"));
}
+ // ============ 标签范围回忆对比与范围列 ============
+
+ @Test
+ void tagScopeRecallCompare_persistsRecordWithRangeAndDuration() throws Exception {
+ String taskNum = saveTask("标签回忆任务-" + SEQ.incrementAndGet());
+ String tagA = tag("标签回忆A");
+ addTag(createFragment(taskNum, "标签回忆碎片"), tagA);
+ TagScope scope = scope("UNION", tagA);
+ tagMindMapService.regenerate(scope);
+
+ RecallCompareOutcome outcome = tagMindMapService.recallCompare(scope, "- 标签回忆碎片", null,
+ new ReviewTiming(LocalDateTime.now().minusMinutes(10), LocalDateTime.now(), 300));
+
+ ReviewRecallRecordEntity record = recallRecordMapper.selectById(outcome.recallRecordId());
+ assertNotNull(record);
+ assertNull(record.getTaskNum(), "标签范围的复习不挂任务");
+ assertEquals(ReviewScopeTypeEnum.TAG.name(), record.getScopeType());
+ assertEquals(scope.scopeKey(), record.getScopeKey());
+ assertEquals(scope.tags(), TagScopeTool.parseStoredTags(record.getScopeTags()));
+ assertEquals(TagCombineModeEnum.UNION.name(), record.getScopeMode());
+ assertEquals(300, record.getReviewDurationSeconds().intValue(), "复习耗时按既有口径结算并落库");
+ assertNotNull(record.getRecallRatio());
+ assertEquals(tagMindMapService.query(scope).getMap().getId(), record.getStandardMapId(),
+ "记录能追溯回对比用的标签导图");
+
+ // 历史与最新结果都可查
+ List history = tagMindMapService.listRecallRecords(scope);
+ assertEquals(1, history.size());
+ assertEquals(record.getId(), history.get(0).getId());
+ assertEquals(record.getId(), tagMindMapService.query(scope).getLatestRecallRecord().getId());
+ }
+
+ @Test
+ void taskScopeQueriesAndStats_areNotAffectedByTagRecords() throws Exception {
+ // 任务范围的一条记录:耗时 120 秒
+ String taskNum = saveTask("任务口径任务-" + SEQ.incrementAndGet());
+ addTag(createFragment(taskNum, "任务口径碎片"), tag("任务口径-" + SEQ.incrementAndGet()));
+ standardMindMapService.recallCompare(taskNum, "- 任一回忆", null,
+ new ReviewTiming(LocalDateTime.now().minusMinutes(10), LocalDateTime.now(), 120));
+
+ // 标签范围的一条记录:耗时 600 秒,task_num 为空
+ String tagA = tag("统计隔离A");
+ String tagTaskNum = saveTask("统计隔离任务-" + SEQ.incrementAndGet());
+ addTag(createFragment(tagTaskNum, "统计隔离碎片"), tagA);
+ TagScope scope = scope("UNION", tagA);
+ tagMindMapService.regenerate(scope);
+ tagMindMapService.recallCompare(scope, "- 统计隔离碎片", null,
+ new ReviewTiming(LocalDateTime.now().minusMinutes(10), LocalDateTime.now(), 600));
+
+ // 任务维度的既有查询与统计只看带 task_num 的行
+ List ratios = recallRecordMapper.selectLatestRatioByTask(Set.of(taskNum));
+ assertEquals(1, ratios.size());
+ assertEquals(taskNum, ratios.get(0).getTaskNum());
+
+ List durations = recallRecordMapper.sumReviewDurationByTask(Set.of(taskNum));
+ assertEquals(1, durations.size());
+ assertEquals(120L, durations.get(0).getReviewDurationSeconds().longValue(),
+ "标签范围的复习耗时不并入任务统计");
+
+ // 标签范围的记录仍可追溯
+ List tagRecords = tagMindMapService.listRecallRecords(scope);
+ assertEquals(1, tagRecords.size());
+ assertNull(tagRecords.get(0).getTaskNum());
+ }
+
// ============ AI 任务链路(前端实际接线路径) ============
@Test
@@ -384,6 +465,31 @@ class TagMindMapIntegrationTest {
assertTrue(done.getErrorMessage().contains("对不上"), "失败原因应说明范围与目标不一致:" + done.getErrorMessage());
}
+ @Test
+ void tagRecallCompareTask_persistsRecordAndReturnsOutcome() throws Exception {
+ String taskNum = saveTask("标签对比任务-" + SEQ.incrementAndGet());
+ String tagA = tag("标签对比A");
+ addTag(createFragment(taskNum, "标签对比碎片"), tagA);
+ TagScope scope = scope("UNION", tagA);
+ tagMindMapService.regenerate(scope);
+
+ AiTaskResponse done = awaitTerminal(aiTaskService.submit(request("TAG_RECALL_COMPARE", scope.scopeKey(),
+ Map.of("tags", scope.tags(),
+ "combineMode", "UNION",
+ "recallOutline", "- 标签对比碎片",
+ "reviewStartedAt", LocalDateTime.now().minusMinutes(2).toString(),
+ "reviewDurationSeconds", 111))).getTaskNum());
+
+ assertEquals(AiTaskStatusEnum.SUCCEEDED.name(), done.getStatus(), done.getErrorMessage());
+ Integer recordId = (Integer) done.getResult().get("recallRecordId");
+ assertNotNull(recordId);
+ ReviewRecallRecordEntity record = recallRecordMapper.selectById(recordId);
+ assertEquals(ReviewScopeTypeEnum.TAG.name(), record.getScopeType());
+ assertEquals(scope.scopeKey(), record.getScopeKey());
+ assertEquals(111, record.getReviewDurationSeconds().intValue());
+ assertNull(record.getTaskNum());
+ }
+
// ============ 用户编辑与参数校验 ============
@Test