feat: 新增标签导图存储与生成

This commit is contained in:
2026-10-10 15:28:06 +08:00
parent d282f1b10a
commit 6a30022af5
29 changed files with 1916 additions and 106 deletions
@@ -0,0 +1,55 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.TagMindMapView;
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.ReviewTagMindMapEntity;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.service.ReviewTagMindMapService;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
/**
* 标签导图控制层(闭环-04)。
*
* <p>按标签复习与按任务复习并存:任务导图仍走 {@code /review/standard-mind-map/{taskNum}},
* 这里只负责以「标签集合 + 取数模式」为范围的那一半。</p>
*
* <p>生成与回忆对比都不在请求线程里等 AI:由前端提交 {@code POST /ai/tasks}
* (type=TAG_MIND_MAP / TAG_RECALL_COMPARE)后轮询结果,与既有 AI 任务链路同一约定。</p>
*/
@RequestMapping("/review/tag-mind-map")
@RestController
@Validated
@RequiredArgsConstructor
public class TagMindMapController {
private final ReviewTagMindMapService reviewTagMindMapService;
/**
* 读取该范围的状态:范围键、标签集合与已有导图。
*
* <p>读取不触发生成:没有导图时 {@code map} 为 null,由前端提交生成任务。
* 用请求体而不是查询参数,是因为标签名由用户自由输入、可能含逗号。</p>
*/
@PostMapping("/query")
public CommonResult<TagMindMapView> query(@Valid @RequestBody TagScopeRequest request)
throws ErrorParameterException {
TagScope scope = reviewTagMindMapService.resolveScope(request.getTags(), request.getMode());
return CommonResult.success(reviewTagMindMapService.query(scope));
}
/**
* 用户编辑标签导图(大纲文本形式);该范围还没有导图时保存即为新建。
*/
@PutMapping
public CommonResult<ReviewTagMindMapEntity> updateTagMindMap(
@Valid @RequestBody UpdateTagMindMapRequest request) throws ErrorParameterException {
TagScope scope = reviewTagMindMapService.resolveScope(request.getTags(), request.getMode());
return CommonResult.success(reviewTagMindMapService.updateByOutline(scope, request.getOutline()));
}
}
@@ -0,0 +1,19 @@
package com.guo.learningprogresstracker.dto;
import lombok.Data;
/**
* 一个碎片命中的标签数(闭环-04 标签导图取材)。
*
* <p>由 Mapper 层的分组查询直接映射:并集取「命中任意一个」的行,交集取「命中数 == 范围标签数」的行。
* 命中数按归一化标签名去重,所以重复打标不会让交集判定失真。</p>
*/
@Data
public class FragmentTagMatch {
/** 碎片 id(标记的 object_num) */
private String objectNum;
/** 命中的标签数(按归一化标签名去重) */
private Integer matchedTagCount;
}
@@ -0,0 +1,30 @@
package com.guo.learningprogresstracker.dto;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import java.util.List;
/**
* 一个标签复习范围的当前状态(闭环-04)。
*
* <p>范围键与标签集合总是返回(即使还没有导图),让前端能用同一组参数发起生成任务与回忆对比;
* {@code map} 为空表示该范围还没生成过导图——读取路径不触发生成,生成走
* {@code POST /ai/tasks}(type=TAG_MIND_MAP)异步完成。</p>
*/
@Data
public class TagMindMapView {
@Schema(description = "范围键:标签集合与取数模式的稳定哈希,同时作为 AI 任务的 targetNum")
private String scopeKey;
@Schema(description = "范围的标签集合(展示用,按归一化名排序)")
private List<String> tags;
@Schema(description = "取数模式:UNION=并集 / INTERSECT=交集")
private String mode;
@Schema(description = "该范围已有的标签导图;没有时为 null")
private ReviewTagMindMapEntity map;
}
@@ -0,0 +1,19 @@
package com.guo.learningprogresstracker.dto;
import com.guo.learningprogresstracker.enums.TagCombineModeEnum;
import java.util.List;
/**
* 解析后的复习范围:标签集合 + 取数模式 + 规范键(闭环-04)。
*
* <p>{@code tags} 是展示用标签集合(按归一化名排序、保留输入原样),{@code normalizedTags} 是规范化标签集合,
* {@code scopeKey} 是两者的稳定哈希——集合相同且模式相同即同一张标签导图。</p>
*/
public record TagScope(String scopeKey, List<String> tags, List<String> normalizedTags, TagCombineModeEnum mode) {
/** 范围的展示名:标签以「、」连接,也是标签导图的根节点标题来源 */
public String displayName() {
return String.join("、", tags);
}
}
@@ -0,0 +1,22 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.constraints.NotEmpty;
import lombok.Data;
import java.util.List;
/**
* 标签复习范围(闭环-04):标签集合 + 取数模式。
*
* <p>用于纯范围寻址的读接口(读取该范围的导图、读取该范围的回忆记录)。
* 字段名与 {@code /ai/tasks} 的 params 保持一致,前端两处可以直接复用。</p>
*/
@Data
public class TagScopeRequest {
@NotEmpty(message = "请先选择标签")
private List<String> tags;
/** 取数模式:UNION=并集(默认)/ INTERSECT=交集 */
private String mode;
}
@@ -0,0 +1,26 @@
package com.guo.learningprogresstracker.dto.request;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotEmpty;
import lombok.Data;
import java.util.List;
/**
* 用户编辑标签导图(大纲文本形式)请求(闭环-04)。
*
* <p>范围绕「标签集合 + 取数模式」寻址,因此请求里带的是范围本身而不是导图 id;
* 该范围还没有导图时,保存即为新建。</p>
*/
@Data
public class UpdateTagMindMapRequest {
@NotEmpty(message = "请先选择标签")
private List<String> tags;
/** 取数模式:UNION=并集(默认)/ INTERSECT=交集 */
private String mode;
@NotBlank(message = "请填写思维导图大纲")
private String outline;
}
@@ -0,0 +1,74 @@
package com.guo.learningprogresstracker.entity;
import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
import java.io.Serializable;
import java.time.LocalDateTime;
/**
* 标签思维导图(闭环-04):以一个「标签集合 + 取数模式」为范围的导图,与任务导图并存。
*
* <p>范围键 {@code scopeKey} 是标签集合(归一化、排序后拼接)与取数模式的稳定哈希:
* 集合相同且模式相同即同一张导图,因此同一用户下范围键唯一。素材是带这些标签的知识碎片,
* 与任务导图共用「碎片 → 缩进大纲」的生成链路与内置规则降级路径。</p>
*/
@TableName(value = "review_tag_mind_maps")
@Data
public class ReviewTagMindMapEntity extends BaseEntity implements Serializable {
@TableId(value = "id", type = IdType.AUTO)
private Integer id;
/** 范围键,见 {@code utils.TagScopeTool#scopeKey} */
@TableField(value = "scope_key")
private String scopeKey;
/** 取数模式:UNION=并集 / INTERSECT=交集,取值见 {@code TagCombineModeEnum} */
@TableField(value = "combine_mode")
private String combineMode;
/** 范围的标签集合(JSON 数组,展示保留输入原样,按归一化名排序) */
@TableField(value = "tag_names")
private String tagNames;
@TableField(value = "title")
private String title;
/** 统一树结构 JSON(根节点:{title, notes, children}) */
@TableField(value = "content")
private String content;
/** 缩进大纲文本,供前端展示与用户编辑 */
@TableField(value = "outline")
private String outline;
@TableField(value = "summary")
private String summary;
/** 生成来源:BUILTIN/AI/USER/USER_MERGE */
@TableField(value = "generator")
private String generator;
@TableField(value = "generator_version")
private String generatorVersion;
@TableField(value = "source_fragment_count")
private Integer sourceFragmentCount;
@TableField(value = "generated_time")
private LocalDateTime generatedTime;
/** 该范围下的素材(碎片标签)发生变化后置为 true,表示这张导图需要重建;重建由用户手动触发 */
@TableField(value = "needs_update")
private Boolean needsUpdate;
@TableField(value = "needs_update_time")
private LocalDateTime needsUpdateTime;
@TableField(exist = false)
private static final long serialVersionUID = 1L;
}
@@ -16,6 +16,9 @@ public enum AiTaskTypeEnum {
/** 标准思维导图生成:全量、增量或按需生成 */
MIND_MAP("思维导图生成"),
/** 标签思维导图生成:按「标签集合 + 取数模式」生成或重建(闭环-04) */
TAG_MIND_MAP("标签思维导图生成"),
/** 学习报告草稿聚合 */
REPORT_DRAFT("学习报告草稿"),
@@ -0,0 +1,37 @@
package com.guo.learningprogresstracker.enums;
import lombok.AllArgsConstructor;
import lombok.Getter;
import java.util.Locale;
/**
* 思维导图的生成模式(AI-02):同一条生成链路按需全量重建、增量合并或缺失时才生成。
*/
@Getter
@AllArgsConstructor
public enum MindMapGenerateModeEnum {
/** 全量重新生成 */
FULL("全量生成"),
/** 增量更新:保留用户编辑过的节点,合并新生成的节点 */
INCREMENTAL("增量更新"),
/** 仅在缺失时生成(读取页面按需触发) */
ENSURE("按需生成");
private final String description;
/** 宽松解析:空值与无法识别的值都按全量生成处理 */
public static MindMapGenerateModeEnum parse(String value) {
if (value == null || value.isBlank()) {
return FULL;
}
try {
return valueOf(value.trim().toUpperCase(Locale.ROOT));
} catch (IllegalArgumentException e) {
return FULL;
}
}
}
@@ -0,0 +1,41 @@
package com.guo.learningprogresstracker.enums;
import lombok.AllArgsConstructor;
import lombok.Getter;
import java.util.Locale;
/**
* 标签导图的取数模式(闭环-04)。
*
* <p>多标签由用户在界面上选并集还是交集,默认并集;模式与标签集合一起构成导图的规范键。</p>
*/
@Getter
@AllArgsConstructor
public enum TagCombineModeEnum {
/** 并集:带任一标签的内容都取材 */
UNION("并集"),
/** 交集:同时带全部标签的内容才取材 */
INTERSECT("交集");
private final String description;
/** 默认取数模式:并集(维护者口径) */
public static TagCombineModeEnum defaultMode() {
return UNION;
}
/** 宽松解析:空值按默认并集处理,无法识别时返回 null(由调用方报参数错误) */
public static TagCombineModeEnum parse(String value) {
if (value == null || value.isBlank()) {
return defaultMode();
}
try {
return valueOf(value.trim().toUpperCase(Locale.ROOT));
} catch (IllegalArgumentException e) {
return null;
}
}
}
@@ -1,12 +1,14 @@
package com.guo.learningprogresstracker.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.guo.learningprogresstracker.dto.FragmentTagMatch;
import com.guo.learningprogresstracker.dto.MarkerUsage;
import com.guo.learningprogresstracker.entity.MarkerEntity;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
import org.apache.ibatis.annotations.Select;
import java.util.Collection;
import java.util.List;
@Mapper
@@ -28,4 +30,28 @@ public interface MarkerMapper extends BaseMapper<MarkerEntity> {
ORDER BY marker_count DESC, marker_name ASC
""")
List<MarkerUsage> selectUserTagUsage(@Param("createdBy") String createdBy);
/**
* 按标签集合统计每个碎片命中的标签数(闭环-04 标签导图取材)。
*
* <p>归一化口径与标签字典一致(去首尾空白 + 小写),所以标签大小写/空白不同也能命中同一组标签;
* 命中数按归一化名去重,并集取「≥1」,交集取「= 范围标签数」。
* 租户条件 {@code created_by} 由 {@code TenantLineInnerInterceptor} 自动追加(有集成测试覆盖)。</p>
*
* @param tagKeys 规范化标签名;为空时返回空列表
*/
@Select("""
<script>
SELECT object_num AS object_num,
COUNT(DISTINCT LOWER(TRIM(marker_name))) AS matched_tag_count
FROM markers
WHERE deleted = 0
AND object_type = 'FRAGMENT'
AND kind = 'USER'
AND LOWER(TRIM(marker_name)) IN
<foreach collection="tagKeys" item="tagKey" open="(" separator="," close=")">#{tagKey}</foreach>
GROUP BY object_num
</script>
""")
List<FragmentTagMatch> countUserTagsPerFragment(@Param("tagKeys") Collection<String> tagKeys);
}
@@ -0,0 +1,13 @@
package com.guo.learningprogresstracker.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import org.apache.ibatis.annotations.Mapper;
/**
* 标签导图 Mapper(闭环-04)。
* <p>查询条件都能用 Wrapper 表达(按范围键取一条、按是否待更新扫一遍),因此不额外下沉自定义 SQL。</p>
*/
@Mapper
public interface ReviewTagMindMapMapper extends BaseMapper<ReviewTagMindMapEntity> {
}
@@ -0,0 +1,61 @@
package com.guo.learningprogresstracker.service;
import com.guo.learningprogresstracker.dto.TagMindMapView;
import com.guo.learningprogresstracker.dto.TagScope;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import java.util.Collection;
import java.util.List;
/**
* 标签思维导图服务(闭环-04)。
*
* <p>标签导图以一个「标签集合 + 取数模式」为范围,与任务导图并存、互不替代:
* 任务导图回答「这个任务学到了什么结构」,标签导图回答「这个概念在不同任务里呈现出什么结构」。
* 范围用规范键({@code TagScope#scopeKey})寻址,集合相同且模式相同即同一张导图。</p>
*
* <p>两条硬口径:</p>
* <ul>
* <li><b>读取不生成</b>:读取路径只返回已有导图,生成走 {@code POST /ai/tasks}(type=TAG_MIND_MAP)异步完成;</li>
* <li><b>重建手动触发</b>:素材(碎片标签)变化只把导图置「待更新」,不自动重建。</li>
* </ul>
*/
public interface ReviewTagMindMapService {
/**
* 解析复习范围:去空白、按归一化名去重排序、算范围键,并校验标签数量与取数模式。
*
* @param mode UNION(默认,并集)/ INTERSECT(交集)
*/
TagScope resolveScope(List<String> tags, String mode) throws ErrorParameterException;
/**
* 读取该范围的状态:范围描述 + 已有导图;读取不触发生成。
*/
TagMindMapView query(TagScope scope);
/**
* 用户手动编辑标签导图(用缩进大纲文本替换);该范围还没有导图时保存即为新建。
*/
ReviewTagMindMapEntity updateByOutline(TagScope scope, String outline);
/**
* 重新生成该范围的标签导图(由 AI 任务执行器在请求线程之外调用)。
*/
ReviewTagMindMapEntity regenerate(TagScope scope) throws OperationFailedException;
/**
* 增量更新:保留用户编辑过的节点,合并最新生成的节点。
*/
ReviewTagMindMapEntity incrementalGenerate(TagScope scope) throws NotFindEntitiesException, OperationFailedException;
/**
* 素材发生变化时的置「待更新」(不重建)。
*
* <p>由标签的增删改与碎片删除调用:只有标签集合与变化标签有交集的那几张导图会被置位。</p>
*/
void markStaleForTags(Collection<String> changedTagNames);
}
@@ -6,6 +6,8 @@ import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.ReviewStandardMindMapEntity;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.utils.CompareResult;
import com.guo.learningprogresstracker.utils.MindMapNode;
import java.util.List;
import java.util.Map;
@@ -50,6 +52,17 @@ public interface StandardMindMapService {
RecallCompareOutcome recallCompare(String taskNum, String recallOutline, String focusPath,
ReviewTiming timing) throws NotFindEntitiesException, OperationFailedException;
/**
* 用同一套对比口径比较一棵基准导图与用户回忆大纲:优先 AI 语义对比,AI 不可用或失败时降级为文本相似度匹配。
*
* <p>任务导图与标签导图共用它,避免两种复习范围出现两套覆盖率口径。</p>
*
* @param scopeName 范围名(任务名或标签集合),仅用于 AI 提示词与日志
* @param standardRoot 作为对比基准的导图树(可能只是标准导图的一棵子树)
* @param recallOutline 用户回忆的缩进大纲文本
*/
CompareResult compareWithRecall(String scopeName, MindMapNode standardRoot, String recallOutline);
/**
* 根据内容文本在标准导图中查找最匹配的节点,返回节点路径。
*
@@ -0,0 +1,77 @@
package com.guo.learningprogresstracker.service.impl;
import lombok.extern.slf4j.Slf4j;
import java.time.LocalDateTime;
import java.time.format.DateTimeParseException;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.Map;
/**
* AI 任务参数的宽松读取(AI-02)。
*
* <p>参数的来源是前端提交的 JSON:数字与时间可能是字符串,缺字段与空值都按「未提供」处理,
* 各任务处理器共用同一套解析口径。</p>
*/
@Slf4j
final class AiTaskParams {
private AiTaskParams() {
}
static String asString(Map<String, Object> params, String key) {
Object value = params == null ? null : params.get(key);
return value == null ? null : String.valueOf(value);
}
static Integer asInteger(Map<String, Object> params, String key) {
Object value = params == null ? null : params.get(key);
if (value instanceof Number number) {
return number.intValue();
}
if (value instanceof String text && !text.isBlank()) {
try {
return Integer.valueOf(text.trim());
} catch (NumberFormatException e) {
return null;
}
}
return null;
}
/** 前端上报的是无时区的本地时间字符串;解析失败按缺失处理,不影响主流程 */
static LocalDateTime asLocalDateTime(Map<String, Object> params, String key) {
String text = asString(params, key);
if (text == null || text.isBlank()) {
return null;
}
try {
return LocalDateTime.parse(text.trim());
} catch (DateTimeParseException e) {
log.warn("AI 任务参数[{}]时间格式无法解析,按缺失处理: {}", key, text);
return null;
}
}
/** 字符串数组参数;非集合类型按单值处理,空元素与空白元素被丢弃 */
static List<String> asStringList(Map<String, Object> params, String key) {
Object value = params == null ? null : params.get(key);
if (value == null) {
return List.of();
}
Collection<?> raw = value instanceof Collection<?> collection ? collection : List.of(value);
List<String> result = new ArrayList<>();
for (Object item : raw) {
if (item == null) {
continue;
}
String text = String.valueOf(item).trim();
if (!text.isEmpty()) {
result.add(text);
}
}
return result;
}
}
@@ -16,6 +16,7 @@ import com.guo.learningprogresstracker.mapper.StudyReportFragmentsMapper;
import com.guo.learningprogresstracker.mapper.TasksMapper;
import com.guo.learningprogresstracker.mapper.UserTagMapper;
import com.guo.learningprogresstracker.service.MarkerService;
import com.guo.learningprogresstracker.service.ReviewTagMindMapService;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
@@ -46,6 +47,7 @@ public class MarkerServiceImpl implements MarkerService {
private final StudyReportFragmentsMapper studyReportFragmentsMapper;
private final TasksMapper tasksMapper;
private final UserTagMapper userTagMapper;
private final ReviewTagMindMapService reviewTagMindMapService;
@Override
public List<MarkerEntity> listByObject(MarkerObjectTypeEnum objectType, String objectNum) {
@@ -104,6 +106,8 @@ public class MarkerServiceImpl implements MarkerService {
markerMapper.insert(marker);
// 打标签时输入的新名字自动补进字典(闭环-03)
ensureDictionaryEntry(name);
// 碎片多了一个标签 → 相关标签导图置「待更新」(闭环-04,不自动重建)
markTagMindMapsStale(objectType, List.of(name));
return marker;
}
@@ -115,6 +119,8 @@ public class MarkerServiceImpl implements MarkerService {
throw new ErrorParameterException("这是系统标记,不能删除");
}
markerMapper.deleteById(existing.getId());
// 碎片少了一个标签 → 相关标签导图置「待更新」(闭环-04,不自动重建)
markTagMindMapsStale(MarkerObjectTypeEnum.parse(existing.getObjectType()), List.of(existing.getMarkerName()));
}
@Override
@@ -153,6 +159,8 @@ public class MarkerServiceImpl implements MarkerService {
renamed++;
}
log.info("标签[{}]重命名为[{}],影响 {} 条标记", from, to, renamed);
// 两个名字的取材范围都变了 → 相关标签导图置「待更新」(闭环-04,不自动重建)
reviewTagMindMapService.markStaleForTags(List.of(from, to));
return renamed;
}
@@ -330,12 +338,33 @@ public class MarkerServiceImpl implements MarkerService {
if (objectType == null || !StringUtils.hasText(objectNum)) {
return;
}
// 对象即将消失:先记下它的用户标签,才能把相关标签导图置「待更新」(闭环-04)
List<String> removedTags = List.of();
if (objectType == MarkerObjectTypeEnum.FRAGMENT) {
removedTags = markerMapper.selectList(Wrappers.<MarkerEntity>lambdaQuery()
.eq(MarkerEntity::getObjectType, objectType.name())
.eq(MarkerEntity::getObjectNum, objectNum.trim())
.eq(MarkerEntity::getKind, MarkerKindEnum.USER.name())
.select(MarkerEntity::getMarkerName))
.stream()
.map(MarkerEntity::getMarkerName)
.toList();
}
int removed = markerMapper.delete(Wrappers.<MarkerEntity>lambdaQuery()
.eq(MarkerEntity::getObjectType, objectType.name())
.eq(MarkerEntity::getObjectNum, objectNum.trim()));
if (removed > 0) {
log.info("对象[{}/{}]的 {} 条标记已随对象删除", objectType, objectNum, removed);
}
markTagMindMapsStale(objectType, removedTags);
}
/** 碎片标签发生变化时的下游影响:相关标签导图置「待更新」,重建由用户手动触发(闭环-04) */
private void markTagMindMapsStale(MarkerObjectTypeEnum objectType, Collection<String> changedTags) {
if (objectType != MarkerObjectTypeEnum.FRAGMENT || changedTags == null || changedTags.isEmpty()) {
return;
}
reviewTagMindMapService.markStaleForTags(changedTags);
}
private MarkerEntity requireMarker(Integer id) throws NotFindEntitiesException {
@@ -1,13 +1,14 @@
package com.guo.learningprogresstracker.service.impl;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.guo.learningprogresstracker.entity.AiTaskEntity;
import com.guo.learningprogresstracker.entity.ReviewStandardMindMapEntity;
import com.guo.learningprogresstracker.enums.AiTaskTypeEnum;
import com.guo.learningprogresstracker.enums.MindMapGenerateModeEnum;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.service.StandardMindMapService;
import com.guo.learningprogresstracker.utils.MindMapTreeTool;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
@@ -26,9 +27,6 @@ import java.util.Map;
@RequiredArgsConstructor
public class MindMapAiTaskHandler implements AiTaskHandler {
private static final String MODE_INCREMENTAL = "incremental";
private static final String MODE_ENSURE = "ensure";
private final StandardMindMapService standardMindMapService;
private final ObjectMapper objectMapper;
@@ -39,19 +37,19 @@ public class MindMapAiTaskHandler implements AiTaskHandler {
@Override
public Map<String, Object> execute(AiTaskEntity task, Map<String, Object> params) {
String mode = params.get("mode") == null ? "full" : String.valueOf(params.get("mode"));
MindMapGenerateModeEnum mode = MindMapGenerateModeEnum.parse(AiTaskParams.asString(params, "mode"));
String taskNum = task.getTargetNum();
try {
// ensure 模式下已有导图就直接返回,不做无意义的重新生成(也不重复计费)
if (MODE_ENSURE.equalsIgnoreCase(mode)) {
if (mode == MindMapGenerateModeEnum.ENSURE) {
ReviewStandardMindMapEntity existing = standardMindMapService.getExisting(taskNum);
if (existing != null) {
return toPayload(existing, "已存在,跳过生成");
}
return toPayload(standardMindMapService.regenerate(taskNum), "按需生成");
}
if (MODE_INCREMENTAL.equalsIgnoreCase(mode)) {
if (mode == MindMapGenerateModeEnum.INCREMENTAL) {
return toPayload(standardMindMapService.incrementalGenerate(taskNum), "增量更新");
}
return toPayload(standardMindMapService.regenerate(taskNum), "全量生成");
@@ -0,0 +1,72 @@
package com.guo.learningprogresstracker.service.impl;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.TaskApplicationEntity;
import com.guo.learningprogresstracker.entity.TaskEntity;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.service.MindMapAiClient;
import com.guo.learningprogresstracker.utils.MindMapNode;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import java.util.Comparator;
import java.util.List;
import java.util.Optional;
/**
* 「碎片 → 缩进大纲」生成链路:优先 AI 客户端,失败时降级到内置规则生成器。
*
* <p>任务导图与标签导图共用它,避免两种取材范围出现两套客户端选择与降级口径。
* <b>取材</b>(按内容归属 / 按标签集合)由调用方决定,本类只回答「给定素材怎么产出树」。</p>
*/
@Slf4j
@Component
@RequiredArgsConstructor
public class MindMapOutlineGenerator {
private static final String GENERATOR_BUILTIN = "BUILTIN";
private final List<MindMapAiClient> aiClients;
/**
* @param root 导图根节点
* @param generatorName 生成来源标识({@code BUILTIN} / AI 客户端名);沿用首选客户端的标识,
* 与既有任务导图口径一致
*/
public record GeneratedOutline(MindMapNode root, String generatorName) {
}
/**
* 生成导图树;没有任何可用生成器或全部生成失败时抛出用户可见的业务异常。
*/
public GeneratedOutline generate(TaskEntity scope,
List<StudyReportFragmentsEntity> fragments,
List<TaskApplicationEntity> applications) throws OperationFailedException {
// 优先选 AI 客户端(非 BUILTIN),其次内置生成器:AI 提升结构质量,内置规则保证 AI 不可用时仍能生成
MindMapAiClient client = aiClients.stream()
.filter(MindMapAiClient::isAvailable)
.min(Comparator.comparing(c -> GENERATOR_BUILTIN.equals(c.generatorName()) ? 1 : 0))
.orElse(null);
if (client == null) {
log.warn("没有可用的思维导图生成器");
throw new OperationFailedException("思维导图暂时生成不了,请稍后再试");
}
Optional<MindMapNode> optRoot = client.generate(scope, fragments, applications, null);
if (optRoot.isEmpty() && !GENERATOR_BUILTIN.equals(client.generatorName())) {
log.info("AI 思维导图生成失败,降级到内置生成器");
MindMapAiClient fallback = aiClients.stream()
.filter(c -> GENERATOR_BUILTIN.equals(c.generatorName()) && c.isAvailable())
.findFirst().orElse(null);
if (fallback != null) {
optRoot = fallback.generate(scope, fragments, applications, null);
}
}
if (optRoot.isEmpty()) {
log.warn("思维导图生成失败,已尝试全部生成器");
throw new OperationFailedException("思维导图生成失败了,请稍后再试");
}
return new GeneratedOutline(optRoot.get(), client.generatorName());
}
}
@@ -12,8 +12,6 @@ import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import java.time.LocalDateTime;
import java.time.format.DateTimeParseException;
import java.util.Map;
/**
@@ -36,15 +34,15 @@ public class RecallCompareAiTaskHandler implements AiTaskHandler {
@Override
public Map<String, Object> execute(AiTaskEntity task, Map<String, Object> params) {
String recallOutline = asString(params, "recallOutline");
String recallOutline = AiTaskParams.asString(params, "recallOutline");
if (!StringUtils.hasText(recallOutline)) {
throw new AiTaskFailedException("请先填写回忆大纲");
}
String focusPath = asString(params, "focusPath");
String focusPath = AiTaskParams.asString(params, "focusPath");
ReviewTiming timing = new ReviewTiming(
asTime(params, "reviewStartedAt"),
asTime(params, "reviewLastInteractionAt"),
asInteger(params, "reviewDurationSeconds"));
AiTaskParams.asLocalDateTime(params, "reviewStartedAt"),
AiTaskParams.asLocalDateTime(params, "reviewLastInteractionAt"),
AiTaskParams.asInteger(params, "reviewDurationSeconds"));
try {
RecallCompareOutcome outcome = standardMindMapService.recallCompare(
@@ -56,38 +54,4 @@ public class RecallCompareAiTaskHandler implements AiTaskHandler {
throw new AiTaskFailedException(e.getMessage());
}
}
private static String asString(Map<String, Object> params, String key) {
Object value = params.get(key);
return value == null ? null : String.valueOf(value);
}
private static Integer asInteger(Map<String, Object> params, String key) {
Object value = params.get(key);
if (value instanceof Number number) {
return number.intValue();
}
if (value instanceof String text && !text.isBlank()) {
try {
return Integer.valueOf(text.trim());
} catch (NumberFormatException e) {
return null;
}
}
return null;
}
/** 前端上报的是无时区的本地时间字符串;解析失败按缺失处理,不影响对比本身 */
private static LocalDateTime asTime(Map<String, Object> params, String key) {
String text = asString(params, key);
if (!StringUtils.hasText(text)) {
return null;
}
try {
return LocalDateTime.parse(text.trim());
} catch (DateTimeParseException e) {
log.warn("AI 任务参数[{}]时间格式无法解析,按缺失处理: {}", key, text);
return null;
}
}
}
@@ -0,0 +1,307 @@
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.TagMindMapView;
import com.guo.learningprogresstracker.dto.TagScope;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.TaskEntity;
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.ReviewTagMindMapMapper;
import com.guo.learningprogresstracker.mapper.StudyReportFragmentsMapper;
import com.guo.learningprogresstracker.service.ReviewTagMindMapService;
import com.guo.learningprogresstracker.utils.MindMapNode;
import com.guo.learningprogresstracker.utils.MindMapTreeTool;
import com.guo.learningprogresstracker.utils.TagScopeTool;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.util.StringUtils;
import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.Collection;
import java.util.Collections;
import java.util.List;
import java.util.Set;
/**
* 标签思维导图服务实现(闭环-04)。
*
* <p>取材与生成两条链路都刻意与任务导图共用口径:素材来自带这些标签的碎片(软删除的不取材),
* 生成走 {@link MindMapOutlineGenerator}(AI 优先、内置规则降级)。</p>
*/
@Slf4j
@Service
@RequiredArgsConstructor
public class ReviewTagMindMapServiceImpl implements ReviewTagMindMapService {
private static final String GENERATOR_USER = "USER";
private static final String GENERATOR_USER_MERGE = "USER_MERGE";
private static final String GENERATOR_VERSION = "1.0";
/** 与标记、标签字典的列宽一致 */
private static final int MAX_TAG_NAME_LENGTH = 100;
private final ReviewTagMindMapMapper tagMindMapMapper;
private final MarkerMapper markerMapper;
private final StudyReportFragmentsMapper studyReportFragmentsMapper;
private final MindMapOutlineGenerator outlineGenerator;
private final ObjectMapper objectMapper;
// ============ 范围解析 ============
@Override
public TagScope resolveScope(List<String> tags, String mode) throws ErrorParameterException {
List<String> cleaned = new ArrayList<>();
if (tags != null) {
for (String tag : tags) {
if (!StringUtils.hasText(tag)) {
continue;
}
String name = tag.trim();
if (name.length() > MAX_TAG_NAME_LENGTH) {
throw new ErrorParameterException("标签名太长了,请控制在 " + MAX_TAG_NAME_LENGTH + " 个字符以内");
}
cleaned.add(name);
}
}
if (cleaned.isEmpty()) {
throw new ErrorParameterException("请先选择要复习的标签");
}
TagCombineModeEnum combineMode = TagCombineModeEnum.parse(mode);
if (combineMode == null) {
throw new ErrorParameterException("取数方式只能是并集或交集");
}
List<String> canonicalTags = TagScopeTool.canonicalTags(cleaned);
if (canonicalTags.size() > TagScopeTool.MAX_RANGE_TAGS) {
throw new ErrorParameterException("一次最多按 " + TagScopeTool.MAX_RANGE_TAGS + " 个标签复习,请把范围缩小一些");
}
return new TagScope(TagScopeTool.scopeKey(canonicalTags, combineMode),
canonicalTags, TagScopeTool.normalizedTags(canonicalTags), combineMode);
}
// ============ 读取 ============
@Override
public TagMindMapView query(TagScope scope) {
TagMindMapView view = new TagMindMapView();
view.setScopeKey(scope.scopeKey());
view.setTags(scope.tags());
view.setMode(scope.mode().name());
view.setMap(queryByScopeKey(scope.scopeKey()));
return view;
}
// ============ 用户编辑 ============
@Override
@Transactional
public ReviewTagMindMapEntity updateByOutline(TagScope scope, String outline) {
ReviewTagMindMapEntity existing = queryByScopeKey(scope.scopeKey());
boolean create = existing == null;
if (create) {
existing = newEntity(scope);
}
MindMapNode root = MindMapTreeTool.parseOutline(outline);
existing.setTitle(root.getTitle() != null ? root.getTitle() : "思维导图");
existing.setContent(MindMapTreeTool.toJson(root, objectMapper));
existing.setOutline(outline);
existing.setGenerator(GENERATOR_USER);
existing.setGeneratorVersion(null);
existing.setSummary("用户编辑,共 " + MindMapTreeTool.countNodes(root) + " 个节点");
existing.setGeneratedTime(LocalDateTime.now());
if (create) {
tagMindMapMapper.insert(existing);
} else {
tagMindMapMapper.updateById(existing);
}
return existing;
}
// ============ 生成 ============
@Override
public ReviewTagMindMapEntity regenerate(TagScope scope) throws OperationFailedException {
// 并发生成由 ai_tasks 的进行中任务判定拦截(AI-04),不依赖 JVM 内存锁
return doGenerate(scope);
}
@Override
public ReviewTagMindMapEntity incrementalGenerate(TagScope scope)
throws NotFindEntitiesException, OperationFailedException {
ReviewTagMindMapEntity existing = queryByScopeKey(scope.scopeKey());
if (existing == null) {
log.warn("标签范围[{}]的导图尚不存在,无法增量更新", scope.scopeKey());
throw new NotFindEntitiesException("这些标签还没有生成过思维导图,请先完整生成一次哦");
}
// 生成(可能调用 AI)不放在事务里:等待 AI 期间不应占用数据库连接(AI-01)
ReviewTagMindMapEntity fresh = doGenerate(scope);
// 合并新旧树:保留用户编辑过的节点,追加新节点
MindMapNode oldRoot = MindMapTreeTool.fromJson(existing.getContent(), objectMapper);
MindMapNode newRoot = MindMapTreeTool.fromJson(fresh.getContent(), objectMapper);
MindMapNode merged = MindMapTreeTool.mergeTrees(oldRoot, newRoot);
existing.setContent(MindMapTreeTool.toJson(merged, objectMapper));
existing.setOutline(MindMapTreeTool.toFullOutline(merged));
existing.setTitle(merged.getTitle() != null ? merged.getTitle() : "思维导图");
existing.setGenerator(GENERATOR_USER_MERGE);
existing.setGeneratorVersion(fresh.getGeneratorVersion());
existing.setSummary("增量更新,共 " + MindMapTreeTool.countNodes(merged) + " 个节点");
existing.setSourceFragmentCount(fresh.getSourceFragmentCount());
existing.setGeneratedTime(LocalDateTime.now());
tagMindMapMapper.updateById(existing);
return existing;
}
// ============ 素材变化 ============
@Override
@Transactional
public void markStaleForTags(Collection<String> changedTagNames) {
Set<String> changed = Set.copyOf(TagScopeTool.normalizedTags(changedTagNames));
if (changed.isEmpty()) {
return;
}
List<ReviewTagMindMapEntity> maps = tagMindMapMapper.selectList(
Wrappers.<ReviewTagMindMapEntity>lambdaQuery()
.eq(ReviewTagMindMapEntity::getNeedsUpdate, false));
int marked = 0;
for (ReviewTagMindMapEntity map : maps) {
Set<String> mapTags = Set.copyOf(
TagScopeTool.normalizedTags(TagScopeTool.parseStoredTags(map.getTagNames())));
if (Collections.disjoint(mapTags, changed)) {
continue;
}
ReviewTagMindMapEntity patch = new ReviewTagMindMapEntity();
patch.setId(map.getId());
patch.setNeedsUpdate(true);
patch.setNeedsUpdateTime(LocalDateTime.now());
tagMindMapMapper.updateById(patch);
marked++;
}
if (marked > 0) {
log.info("标签[{}]的素材发生变化,{} 张标签导图已置为待更新(重建仍由用户手动触发)",
String.join("、", changed), marked);
}
}
// ============ 内部方法 ============
private ReviewTagMindMapEntity doGenerate(TagScope scope) throws OperationFailedException {
List<StudyReportFragmentsEntity> fragments = loadFragments(scope);
if (fragments.isEmpty()) {
log.warn("标签范围[{}]没有取材到知识碎片,无法生成导图", scope.scopeKey());
throw new OperationFailedException("这些标签下还没有内容哦,先给内容打上标签再来吧");
}
// 标签范围没有任务实体:生成链路以「范围名 + 范围描述」作为素材头,
// 这里用一个不落库的临时 TaskEntity 承载它们,从而沿用既有的碎片 → 大纲生成链路
TaskEntity scopeTask = new TaskEntity();
scopeTask.setTaskName(scope.displayName());
scopeTask.setTaskDescription("按标签复习:" + scope.displayName()
+ "(" + scope.mode().getDescription() + "),共取材 " + fragments.size() + " 条知识碎片");
MindMapOutlineGenerator.GeneratedOutline generated =
outlineGenerator.generate(scopeTask, fragments, List.of());
MindMapNode root = generated.root();
ReviewTagMindMapEntity entity = queryByScopeKey(scope.scopeKey());
boolean create = entity == null;
if (create) {
entity = newEntity(scope);
}
entity.setTitle(root.getTitle() != null ? root.getTitle() : scope.displayName());
entity.setContent(MindMapTreeTool.toJson(root, objectMapper));
entity.setOutline(MindMapTreeTool.toFullOutline(root));
entity.setSummary("共 " + MindMapTreeTool.countNodes(root) + " 个节点,最大层级 "
+ MindMapTreeTool.maxDepth(root) + ",取材 " + fragments.size() + " 条碎片");
entity.setGenerator(generated.generatorName());
entity.setGeneratorVersion(GENERATOR_VERSION);
entity.setSourceFragmentCount(fragments.size());
entity.setGeneratedTime(LocalDateTime.now());
// 重建完成后清除「待更新」标记
entity.setNeedsUpdate(false);
entity.setNeedsUpdateTime(null);
if (create) {
tagMindMapMapper.insert(entity);
} else {
tagMindMapMapper.updateById(entity);
}
return entity;
}
private ReviewTagMindMapEntity newEntity(TagScope scope) {
ReviewTagMindMapEntity entity = new ReviewTagMindMapEntity();
entity.setScopeKey(scope.scopeKey());
entity.setCombineMode(scope.mode().name());
entity.setTagNames(TagScopeTool.toStoredTags(scope.tags()));
return entity;
}
private ReviewTagMindMapEntity queryByScopeKey(String scopeKey) {
return tagMindMapMapper.selectOne(Wrappers.<ReviewTagMindMapEntity>lambdaQuery()
.eq(ReviewTagMindMapEntity::getScopeKey, scopeKey)
.last("LIMIT 1"));
}
/**
* 取数:带这些标签的知识碎片。并集取「带任一标签」,交集取「同时带全部标签」;
* 软删除的碎片由 {@code @TableLogic} 自动排除。
*/
private List<StudyReportFragmentsEntity> loadFragments(TagScope scope) {
List<FragmentTagMatch> matches = markerMapper.countUserTagsPerFragment(scope.normalizedTags());
int requiredTagCount = scope.mode() == TagCombineModeEnum.INTERSECT
? scope.normalizedTags().size() : 1;
List<Integer> fragmentIds = new ArrayList<>();
for (FragmentTagMatch match : matches) {
if (match.getMatchedTagCount() == null || match.getMatchedTagCount() < requiredTagCount) {
continue;
}
Integer fragmentId = parseFragmentId(match.getObjectNum());
if (fragmentId != null) {
fragmentIds.add(fragmentId);
}
}
if (fragmentIds.isEmpty()) {
return List.of();
}
return studyReportFragmentsMapper.selectList(Wrappers.<StudyReportFragmentsEntity>lambdaQuery()
.in(StudyReportFragmentsEntity::getId, fragmentIds)
.orderByAsc(StudyReportFragmentsEntity::getCreatedTime));
}
/** 碎片标记的 object_num 一定是数字 id;遇到脏数据只跳过该行,不让整条取材链路失败 */
private static Integer parseFragmentId(String objectNum) {
if (objectNum == null || objectNum.isBlank()) {
return null;
}
String trimmed = objectNum.trim();
for (int i = 0; i < trimmed.length(); i++) {
if (!Character.isDigit(trimmed.charAt(i))) {
log.warn("标记对象标识[{}]不是碎片 id,已跳过", objectNum);
return null;
}
}
try {
return Integer.valueOf(trimmed);
} catch (NumberFormatException e) {
log.warn("标记对象标识[{}]超出碎片 id 范围,已跳过", objectNum);
return null;
}
}
}
@@ -9,7 +9,6 @@ import com.guo.learningprogresstracker.entity.*;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.mapper.*;
import com.guo.learningprogresstracker.service.MindMapAiClient;
import com.guo.learningprogresstracker.service.StandardMindMapService;
import com.guo.learningprogresstracker.utils.CompareResult;
import com.guo.learningprogresstracker.utils.MindMapNode;
@@ -39,7 +38,7 @@ public class StandardMindMapServiceImpl implements StandardMindMapService {
private final TaskApplicationMapper taskApplicationMapper;
private final StudyReportFragmentsMapper studyReportFragmentsMapper;
private final List<MindMapAiClient> aiClients;
private final MindMapOutlineGenerator outlineGenerator;
private final ObjectMapper objectMapper;
private final AiServiceClient aiServiceClient;
@@ -136,9 +135,8 @@ public class StandardMindMapServiceImpl implements StandardMindMapService {
standard = doGenerate(taskNum);
}
// 2. 解析标准树和用户回忆树
// 2. 解析标准树(用户回忆大纲在对比入口里解析,两条复习范围共用同一段逻辑)
MindMapNode standardRoot = MindMapTreeTool.fromJson(standard.getContent(), objectMapper);
MindMapNode recallRoot = MindMapTreeTool.parseOutline(recallOutline);
// 2b. 若指定了起点节点路径,提取该子树作为对比基准
MindMapNode compareRoot = standardRoot;
@@ -150,28 +148,8 @@ public class StandardMindMapServiceImpl implements StandardMindMapService {
}
}
// 3. 执行对比(优先 AI 语义对比,失败时降级为内置算法)
CompareResult result;
if (aiServiceClient.isConfigured()) {
String taskName = tasksMapper.selectOne(
Wrappers.<TaskEntity>lambdaQuery().eq(TaskEntity::getTaskNum, taskNum).last("LIMIT 1"))
.getTaskName();
var optJson = aiServiceClient.compareRecall(
taskName,
MindMapTreeTool.toFullOutline(compareRoot),
recallOutline
);
if (optJson.isPresent()) {
result = buildCompareResultFromAI(optJson.get(), compareRoot);
log.info("AI 回忆对比: taskNum={}, recallRatio={}, evaluation={}",
taskNum, result.getRecallRatio(),
result.getEvaluation() != null ? result.getEvaluation().substring(0, Math.min(50, result.getEvaluation().length())) : "");
} else {
result = compareTrees(compareRoot, recallRoot);
}
} else {
result = compareTrees(compareRoot, recallRoot);
}
// 3. 执行对比(优先 AI 语义对比,失败时降级为内置算法)——与标签导图共用同一套对比口径
CompareResult result = compareWithRecall(resolveScopeName(taskNum), compareRoot, recallOutline);
// 4. 序列化对比结果
String resultJson;
@@ -239,6 +217,36 @@ public class StandardMindMapServiceImpl implements StandardMindMapService {
return result;
}
@Override
public CompareResult compareWithRecall(String scopeName, MindMapNode standardRoot, String recallOutline) {
MindMapNode recallRoot = MindMapTreeTool.parseOutline(recallOutline);
// 优先 AI 语义对比,AI 不可用或返回失败时降级为内置文本相似度匹配
if (aiServiceClient.isConfigured()) {
var optJson = aiServiceClient.compareRecall(
scopeName,
MindMapTreeTool.toFullOutline(standardRoot),
recallOutline);
if (optJson.isPresent()) {
CompareResult result = buildCompareResultFromAI(optJson.get(), standardRoot);
log.info("AI 回忆对比: scope={}, recallRatio={}, evaluation={}",
scopeName, result.getRecallRatio(),
result.getEvaluation() != null
? result.getEvaluation().substring(0, Math.min(50, result.getEvaluation().length()))
: "");
return result;
}
}
return compareTrees(standardRoot, recallRoot);
}
/** 对比口径里的范围名:默认用任务名(导图根节点也是它) */
private String resolveScopeName(String taskNum) {
TaskEntity task = tasksMapper.selectOne(Wrappers.<TaskEntity>lambdaQuery()
.eq(TaskEntity::getTaskNum, taskNum).last("LIMIT 1"));
return task == null || !StringUtils.hasText(task.getTaskName()) ? taskNum : task.getTaskName();
}
// ============ 对比算法核心 ============
/**
@@ -428,34 +436,10 @@ public class StandardMindMapServiceImpl implements StandardMindMapService {
throw new OperationFailedException("这个任务还没开始学习哦,学习后产生知识碎片后再来吧");
}
// 优先选 AI 客户端(非 BUILTIN),其次内置生成器
MindMapAiClient client = aiClients.stream()
.filter(MindMapAiClient::isAvailable)
.min(Comparator.comparing(c -> "BUILTIN".equals(c.generatorName()) ? 1 : 0))
.orElse(null);
// 「碎片 → 缩进大纲」生成链路(AI 优先、内置规则降级)与标签导图共用同一套口径
MindMapOutlineGenerator.GeneratedOutline generated = outlineGenerator.generate(task, fragments, applications);
if (client == null) {
log.warn("任务[{}]没有可用的思维导图生成器", taskNum);
throw new OperationFailedException("思维导图暂时生成不了,请稍后再试");
}
Optional<MindMapNode> optRoot = client.generate(task, fragments, applications, null);
// AI 生成失败时尝试降级到内置生成器
if (optRoot.isEmpty() && !"BUILTIN".equals(client.generatorName())) {
log.info("AI 思维导图生成失败,降级到内置生成器");
MindMapAiClient fallback = aiClients.stream()
.filter(c -> "BUILTIN".equals(c.generatorName()) && c.isAvailable())
.findFirst().orElse(null);
if (fallback != null) {
optRoot = fallback.generate(task, fragments, applications, null);
}
}
if (optRoot.isEmpty()) {
log.warn("任务[{}]思维导图生成失败,已尝试全部生成器", taskNum);
throw new OperationFailedException("思维导图生成失败了,请稍后再试");
}
MindMapNode root = optRoot.get();
MindMapNode root = generated.root();
String contentJson = MindMapTreeTool.toJson(root, objectMapper);
String outline = MindMapTreeTool.toFullOutline(root);
int nodeCount = MindMapTreeTool.countNodes(root);
@@ -472,7 +456,7 @@ public class StandardMindMapServiceImpl implements StandardMindMapService {
entity.setContent(contentJson);
entity.setOutline(outline);
entity.setSummary("共 " + nodeCount + " 个节点,最大层级 " + depth);
entity.setGenerator(client.generatorName());
entity.setGenerator(generated.generatorName());
entity.setGeneratorVersion("1.0");
entity.setSourceReportCount(0);
entity.setSourceFragmentCount(fragments.size());
@@ -0,0 +1,91 @@
package com.guo.learningprogresstracker.service.impl;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.guo.learningprogresstracker.dto.TagScope;
import com.guo.learningprogresstracker.entity.AiTaskEntity;
import com.guo.learningprogresstracker.entity.ReviewTagMindMapEntity;
import com.guo.learningprogresstracker.enums.AiTaskTypeEnum;
import com.guo.learningprogresstracker.enums.MindMapGenerateModeEnum;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.service.ReviewTagMindMapService;
import com.guo.learningprogresstracker.utils.MindMapTreeTool;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import java.util.LinkedHashMap;
import java.util.Map;
/**
* 标签思维导图生成任务(闭环-04)。
*
* <p>任务目标 {@code targetNum} 是标签范围的规范键({@code TagScope#scopeKey}),
* 范围本身由参数给出:{@code tags}(标签集合)、{@code combineMode}(UNION/INTERSECT)、
* {@code mode}(full/incremental/ensure,与任务导图的同名参数同义)。
* 目标与参数不一致说明前端拿了过期的范围,直接失败,避免把这张导图写到别的范围上。</p>
*
* <p>生成模式与任务导图一致,但**不会**被素材变化自动触发:素材变化只把导图置「待更新」,
* 本任务由用户手动发起(与归属-01 的任务导图同口径)。</p>
*/
@Slf4j
@Component
@RequiredArgsConstructor
public class TagMindMapAiTaskHandler implements AiTaskHandler {
private final ReviewTagMindMapService reviewTagMindMapService;
private final ObjectMapper objectMapper;
@Override
public AiTaskTypeEnum type() {
return AiTaskTypeEnum.TAG_MIND_MAP;
}
@Override
public Map<String, Object> execute(AiTaskEntity task, Map<String, Object> params) {
MindMapGenerateModeEnum mode = MindMapGenerateModeEnum.parse(AiTaskParams.asString(params, "mode"));
try {
TagScope scope = reviewTagMindMapService.resolveScope(
AiTaskParams.asStringList(params, "tags"), AiTaskParams.asString(params, "combineMode"));
requireScopeMatches(task, scope);
// ensure 模式下已有导图就直接返回,不做无意义的重新生成(也不重复计费)
if (mode == MindMapGenerateModeEnum.ENSURE) {
ReviewTagMindMapEntity existing = reviewTagMindMapService.query(scope).getMap();
if (existing != null) {
return toPayload(existing, scope, "已存在,跳过生成");
}
return toPayload(reviewTagMindMapService.regenerate(scope), scope, "按需生成");
}
if (mode == MindMapGenerateModeEnum.INCREMENTAL) {
return toPayload(reviewTagMindMapService.incrementalGenerate(scope), scope, "增量更新");
}
return toPayload(reviewTagMindMapService.regenerate(scope), scope, "全量生成");
} catch (ErrorParameterException | NotFindEntitiesException | 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("标签范围和导图标识对不上,请刷新页面后重试");
}
}
private Map<String, Object> toPayload(ReviewTagMindMapEntity entity, TagScope scope, String summary) {
Map<String, Object> payload = new LinkedHashMap<>();
payload.put("tagMapId", entity.getId());
payload.put("scopeKey", scope.scopeKey());
payload.put("tags", scope.tags());
payload.put("mode", scope.mode().name());
payload.put("generator", entity.getGenerator());
payload.put("nodeCount", MindMapTreeTool.countNodes(
MindMapTreeTool.fromJson(entity.getContent(), objectMapper)));
payload.put("summary", summary);
return payload;
}
}
@@ -0,0 +1,125 @@
package com.guo.learningprogresstracker.utils;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.guo.learningprogresstracker.enums.TagCombineModeEnum;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.Collection;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.TreeSet;
/**
* 复习范围(标签集合 + 取数模式)的规范化工具(闭环-04)。
*
* <p>口径(2026-10-10 维护者确认,见 lpt-docs/docs/concepts/standard-mind-map.md「导图的范围」):
* 范围的规范键 = 「标签集合(排序、归一化后的稳定拼接)+ 取数模式」的稳定哈希,集合相同且模式相同即同一张导图。
* 标签归一化口径与标签字典一致:去首尾空白 + 小写({@code user_tags.normalized_name} 同口径)。</p>
*/
public final class TagScopeTool {
/** 一次复习最多可选标签数:范围键要落库,标签多到十来个时界面上也已不可读 */
public static final int MAX_RANGE_TAGS = 10;
/** 存储用分隔符:标签名由用户输入,用不可能出现在标签里的控制字符拼接才不会有歧义 */
private static final String TAG_SEPARATOR = "\u001F";
private static final String MODE_SEPARATOR = "\u001E";
/** 标签集合列是 JSON 数组,只承载字符串,不涉及时间等需要配置的类型 */
private static final ObjectMapper MAPPER = new ObjectMapper();
private TagScopeTool() {
}
/** 标签归一化:去首尾空白 + 小写 */
public static String normalize(String tagName) {
return tagName == null ? "" : tagName.trim().toLowerCase(Locale.ROOT);
}
/** 规范化标签集合:去空白、按归一化名去重、按归一化名排序 */
public static List<String> normalizedTags(Collection<String> tagNames) {
TreeSet<String> normalized = new TreeSet<>();
if (tagNames != null) {
for (String tagName : tagNames) {
String key = normalize(tagName);
if (!key.isEmpty()) {
normalized.add(key);
}
}
}
return new ArrayList<>(normalized);
}
/**
* 展示用标签集合:按归一化名去重与排序,保留输入的原样写法(同一归一化名重复出现时保留先出现的那一个)。
*/
public static List<String> canonicalTags(Collection<String> tagNames) {
Map<String, String> byKey = new LinkedHashMap<>();
if (tagNames != null) {
for (String tagName : tagNames) {
String key = normalize(tagName);
if (!key.isEmpty()) {
byKey.putIfAbsent(key, tagName.trim());
}
}
}
return byKey.entrySet().stream()
.sorted(Map.Entry.comparingByKey())
.map(Map.Entry::getValue)
.toList();
}
/**
* 范围的规范键:标签集合(归一化、排序后稳定拼接)与取数模式的 SHA-256。
*/
public static String scopeKey(Collection<String> tagNames, TagCombineModeEnum mode) {
String canonical = String.join(TAG_SEPARATOR, normalizedTags(tagNames))
+ MODE_SEPARATOR + (mode == null ? TagCombineModeEnum.defaultMode() : mode).name();
return sha256Hex(canonical);
}
/** 标签集合落库:JSON 数组(展示名,已按归一化名排序) */
public static String toStoredTags(Collection<String> tagNames) {
try {
return MAPPER.writeValueAsString(canonicalTags(tagNames));
} catch (Exception e) {
// List<String> 序列化不会失败;真出问题也不能让导图链路整体挂掉
throw new IllegalStateException("标签集合序列化失败", e);
}
}
/** 回读落库的标签集合;内容缺失或损坏时按空集合处理 */
public static List<String> parseStoredTags(String storedTags) {
if (storedTags == null || storedTags.isBlank()) {
return List.of();
}
try {
List<String> tags = MAPPER.readValue(storedTags, new TypeReference<>() {
});
return tags == null ? List.of() : tags;
} catch (Exception e) {
return List.of();
}
}
private static String sha256Hex(String text) {
try {
MessageDigest digest = MessageDigest.getInstance("SHA-256");
byte[] hash = digest.digest(text.getBytes(StandardCharsets.UTF_8));
StringBuilder hex = new StringBuilder(hash.length * 2);
for (byte b : hash) {
hex.append(Character.forDigit((b >> 4) & 0xF, 16)).append(Character.forDigit(b & 0xF, 16));
}
return hex.toString();
} catch (NoSuchAlgorithmException e) {
// JDK 必然提供 SHA-256
throw new IllegalStateException("SHA-256 不可用", e);
}
}
}
@@ -0,0 +1,40 @@
-- 闭环-04:标签导图(按标签集合复习时的对照基准)。
--
-- 口径来源(2026-10-10 维护者确认,结论见 lpt-docs/docs/concepts/standard-mind-map.md「导图的范围」):
-- 标签导图与任务导图并存:任务导图回答「这个任务学到了什么结构」,
-- 标签导图回答「这个概念在不同任务里呈现出什么结构」。
-- 范围 = 规范化标签集合 + 取数模式(UNION 并集 / INTERSECT 交集),集合相同且模式相同即同一张导图,
-- 因此**独立成表**并以范围键寻址:不在 review_standard_mind_maps 上加维度列,
-- 也不动它的 task_num 唯一键。
-- 素材 = 带这些标签的知识碎片(软删除的不取材);素材变化只把导图置 needs_update=1,
-- 重建由用户手动触发(与归属-01 的任务导图同口径)。
create table review_tag_mind_maps
(
id int auto_increment comment 'id无业务含义'
primary key,
scope_key varchar(64) not null comment '范围键:标签集合(归一化、排序后拼接)与取数模式的稳定哈希',
combine_mode varchar(20) not null comment '取数模式:UNION=并集(默认)/ INTERSECT=交集',
tag_names varchar(1100) not null comment '范围的标签集合(JSON 数组,展示保留输入原样,按归一化名排序)',
title varchar(255) not null comment '标签导图标题(根节点标题)',
content mediumtext not null comment '导图统一树结构JSON(根节点:{title, notes, children})',
outline mediumtext null comment '导图缩进大纲文本(用于展示与编辑)',
summary text null comment '生成摘要',
generator varchar(30) not null default 'BUILTIN' comment '生成来源:BUILTIN/AI/USER/USER_MERGE',
generator_version varchar(64) null comment '生成器版本或AI模型名',
source_fragment_count int default 0 not null comment '生成时取材的碎片数',
generated_time datetime null comment '最近生成时间',
needs_update tinyint(1) default 0 not null comment '素材变化后置为1,表示需要重建;重建由用户手动触发',
needs_update_time datetime null comment '置为待更新的时间',
created_time datetime not null comment '创建时间',
created_by varchar(255) null,
last_modified_time datetime null,
last_modified_by varchar(255) null,
device_info varchar(50) null comment '操作者设备类型',
deleted int default 0 not null comment '逻辑删除符',
-- 同一用户下同一范围只有一行。键长:created_by(255×4) + scope_key(64×4) = 1276 字节,
-- 未越过 InnoDB 3072 字节上限;H2 不校验该上限,改动索引时务必用 MigrationIndexKeyLengthTest 复算。
unique key uk_review_tag_mind_maps_scope (created_by, scope_key),
-- 素材变化时扫描「尚未待更新」的行来置位
key idx_review_tag_mind_maps_needs_update (created_by, needs_update)
)
comment '复习模块:标签思维导图(按标签集合取材,与任务导图并存)';
@@ -0,0 +1,89 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.TagMindMapView;
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.ReviewTagMindMapEntity;
import com.guo.learningprogresstracker.enums.TagCombineModeEnum;
import com.guo.learningprogresstracker.service.ReviewTagMindMapService;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.mockito.InjectMocks;
import org.mockito.Mock;
import org.mockito.junit.jupiter.MockitoExtension;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertSame;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
/**
* TagMindMapController 纯单元测试:直接 new 控制器并 mock 服务接口。
*/
@ExtendWith(MockitoExtension.class)
class TagMindMapControllerUnitTest {
@Mock
private ReviewTagMindMapService reviewTagMindMapService;
@InjectMocks
private TagMindMapController controller;
private static TagScope scope() {
return new TagScope("scope-key", List.of("Java", "并发"), List.of("java", "并发"),
TagCombineModeEnum.UNION);
}
private static TagScopeRequest request(String mode) {
TagScopeRequest request = new TagScopeRequest();
request.setTags(List.of("Java", "并发"));
request.setMode(mode);
return request;
}
@Test
void query_resolvesScopeThenReadsRange() throws Exception {
TagMindMapView view = new TagMindMapView();
when(reviewTagMindMapService.resolveScope(List.of("Java", "并发"), "UNION")).thenReturn(scope());
when(reviewTagMindMapService.query(scope())).thenReturn(view);
CommonResult<TagMindMapView> result = controller.query(request("UNION"));
assertEquals(200, result.getCode());
assertSame(view, result.getData());
}
@Test
void query_doesNotGenerate() throws Exception {
when(reviewTagMindMapService.resolveScope(List.of("Java", "并发"), null)).thenReturn(scope());
when(reviewTagMindMapService.query(scope())).thenReturn(new TagMindMapView());
controller.query(request(null));
// AI-02:读取路径不触发生成,生成走 /ai/tasks 的 TAG_MIND_MAP
verify(reviewTagMindMapService, org.mockito.Mockito.never()).regenerate(scope());
}
@Test
void updateTagMindMap_passesOutlineAndMode() throws Exception {
UpdateTagMindMapRequest request = new UpdateTagMindMapRequest();
request.setTags(List.of("Java", "并发"));
request.setMode("INTERSECT");
request.setOutline("- 根节点");
ReviewTagMindMapEntity updated = new ReviewTagMindMapEntity();
TagScope intersectScope = new TagScope("scope-key", List.of("Java", "并发"), List.of("java", "并发"),
TagCombineModeEnum.INTERSECT);
when(reviewTagMindMapService.resolveScope(List.of("Java", "并发"), "INTERSECT")).thenReturn(intersectScope);
when(reviewTagMindMapService.updateByOutline(intersectScope, "- 根节点")).thenReturn(updated);
CommonResult<ReviewTagMindMapEntity> result = controller.updateTagMindMap(request);
assertEquals(200, result.getCode());
assertSame(updated, result.getData());
}
}
@@ -0,0 +1,101 @@
package com.guo.learningprogresstracker.service.impl;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.TaskEntity;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.service.MindMapAiClient;
import com.guo.learningprogresstracker.utils.MindMapNode;
import org.junit.jupiter.api.Test;
import java.util.List;
import java.util.Optional;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.isNull;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.never;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
/**
* 「碎片 → 缩进大纲」生成链路的单元测试:AI 优先、失败降级内置规则、没有可用生成器时报错。
*
* <p>任务导图与标签导图共用这条链路,因此这里守住的是两条取材范围共同的降级口径。</p>
*/
class MindMapOutlineGeneratorTest {
private static final TaskEntity SCOPE = new TaskEntity();
private static final List<StudyReportFragmentsEntity> FRAGMENTS = List.of(new StudyReportFragmentsEntity());
private static MindMapAiClient client(String name, boolean available) {
MindMapAiClient client = mock(MindMapAiClient.class);
when(client.generatorName()).thenReturn(name);
when(client.isAvailable()).thenReturn(available);
return client;
}
private static MindMapNode node(String title) {
return new MindMapNode(title);
}
@Test
void prefersAiClientOverBuiltin() throws Exception {
MindMapAiClient builtin = client("BUILTIN", true);
MindMapAiClient ai = client("AI", true);
when(ai.generate(any(), any(), any(), isNull())).thenReturn(Optional.of(node("AI 导图")));
MindMapOutlineGenerator generator = new MindMapOutlineGenerator(List.of(builtin, ai));
MindMapOutlineGenerator.GeneratedOutline outline = generator.generate(SCOPE, FRAGMENTS, List.of());
assertEquals("AI 导图", outline.root().getTitle());
assertEquals("AI", outline.generatorName());
verify(builtin, never()).generate(any(), any(), any(), any());
}
@Test
void fallsBackToBuiltinWhenAiReturnsNothing() throws Exception {
MindMapAiClient builtin = client("BUILTIN", true);
MindMapAiClient ai = client("AI", true);
when(ai.generate(any(), any(), any(), isNull())).thenReturn(Optional.empty());
when(builtin.generate(any(), any(), any(), isNull())).thenReturn(Optional.of(node("内置导图")));
MindMapOutlineGenerator generator = new MindMapOutlineGenerator(List.of(ai, builtin));
MindMapOutlineGenerator.GeneratedOutline outline = generator.generate(SCOPE, FRAGMENTS, List.of());
assertEquals("内置导图", outline.root().getTitle());
}
@Test
void skipsUnavailableAiAndUsesBuiltin() throws Exception {
MindMapAiClient builtin = client("BUILTIN", true);
MindMapAiClient ai = client("AI", false);
when(builtin.generate(any(), any(), any(), isNull())).thenReturn(Optional.of(node("内置导图")));
MindMapOutlineGenerator generator = new MindMapOutlineGenerator(List.of(ai, builtin));
MindMapOutlineGenerator.GeneratedOutline outline = generator.generate(SCOPE, FRAGMENTS, List.of());
assertEquals("内置导图", outline.root().getTitle());
assertEquals("BUILTIN", outline.generatorName());
verify(ai, never()).generate(any(), any(), any(), any());
}
@Test
void failsWhenNoGeneratorAvailable() {
MindMapOutlineGenerator generator =
new MindMapOutlineGenerator(List.of(client("AI", false)));
assertThrows(OperationFailedException.class, () -> generator.generate(SCOPE, FRAGMENTS, List.of()));
}
@Test
void failsWhenAllGeneratorsReturnNothing() {
MindMapAiClient builtin = client("BUILTIN", true);
when(builtin.generate(any(), any(), any(), isNull())).thenReturn(Optional.empty());
MindMapOutlineGenerator generator = new MindMapOutlineGenerator(List.of(builtin));
assertThrows(OperationFailedException.class, () -> generator.generate(SCOPE, FRAGMENTS, List.of()));
}
}
@@ -38,9 +38,7 @@ class StandardMindMapServiceImplTest {
@Mock
private StudyReportFragmentsMapper studyReportFragmentsMapper;
@Mock
private List<MindMapAiClient> aiClients;
@Mock
private MindMapAiClient mockAiClient;
private MindMapOutlineGenerator outlineGenerator;
@Mock
private AiServiceClient aiServiceClient;
@@ -186,7 +184,7 @@ class StandardMindMapServiceImplTest {
StandardMindMapServiceImpl s = new StandardMindMapServiceImpl(
standardMindMapMapper, recallRecordMapper, tasksMapper,
taskApplicationMapper, studyReportFragmentsMapper,
List.of(mockAiClient), objectMapper, aiServiceClient);
outlineGenerator, objectMapper, aiServiceClient);
return s;
}
}
@@ -0,0 +1,434 @@
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.TagScope;
import com.guo.learningprogresstracker.dto.request.AiTaskSubmitRequest;
import com.guo.learningprogresstracker.dto.request.CreateFragmentsRequest;
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.TagCombineModeEnum;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
import com.guo.learningprogresstracker.mapper.ReviewTagMindMapMapper;
import com.guo.learningprogresstracker.mapper.StudyReportFragmentsMapper;
import com.guo.learningprogresstracker.mapper.StudySessionsMapper;
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.StudyReportFragmentsService;
import com.guo.learningprogresstracker.utils.GenerateNumTool;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.mock.mockito.MockBean;
import java.time.LocalDateTime;
import java.util.List;
import java.util.Map;
import java.util.concurrent.atomic.AtomicInteger;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotEquals;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertNull;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 标签导图与标签范围回忆对比的落库集成测试(闭环-04)。
*
* <p>覆盖口径:并集/交集取数正确、同一标签集合 + 模式命中同一张导图(范围键稳定)、
* 不同模式/不同集合是不同导图、素材变化只置「待更新」不自动重建、软删除碎片不取材、
* 标签范围回忆对比落记录并带范围列、任务范围的既有查询与统计不受影响、租户隔离,
* 以及 AI 任务链路(TAG_MIND_MAP / TAG_RECALL_COMPARE)的端到端可用。</p>
*
* <p>本用例把 {@code AiServiceClient} 置为未配置:生成走内置规则生成器、对比走文本相似度匹配,
* 与任务导图的降级路径是同一套。</p>
*/
@SpringBootTest
class TagMindMapIntegrationTest {
private static final String USER = "标签导图集成测试用户";
private static final AtomicInteger SEQ = new AtomicInteger();
@Autowired
private ReviewTagMindMapService tagMindMapService;
@Autowired
private ReviewTagMindMapMapper tagMindMapMapper;
@Autowired
private MarkerService markerService;
@Autowired
private StudyReportFragmentsService fragmentsService;
@Autowired
private StudyReportFragmentsMapper fragmentsMapper;
@Autowired
private StudySessionsMapper studySessionsMapper;
@Autowired
private TasksMapper tasksMapper;
@Autowired
private AiTaskService aiTaskService;
/** AI 不可用:本用例覆盖的是内置规则降级路径 */
@MockBean
private AiServiceClient aiServiceClient;
@BeforeEach
void setUp() {
StpUtil.login(USER, "test_device");
}
/** 标签名按用例唯一:标签是按名取材的,共用固定名字会让用例之间互相污染 */
private static String tag(String base) {
return base + "-" + SEQ.incrementAndGet();
}
private String saveTask(String taskName) {
String taskNum = "TAGMAP-IT-" + System.nanoTime() + "-" + SEQ.incrementAndGet();
TaskEntity task = new TaskEntity();
task.setTaskNum(taskNum);
task.setTaskName(taskName);
tasksMapper.insert(task);
return taskNum;
}
/** 走创建链路建碎片:记录上下文取学习会话,并自动获得「任务名」标签 */
private StudyReportFragmentsEntity createFragment(String taskNum, String content) throws Exception {
StudySessionsEntity session = new StudySessionsEntity();
session.setSessionNum(GenerateNumTool.generateNum("SESSTAGMAP"));
session.setTaskNum(taskNum);
session.setStartTime(LocalDateTime.now());
session.setLastStartTime(LocalDateTime.now());
session.setSessionState("ENDED");
studySessionsMapper.insert(session);
CreateFragmentsRequest request = new CreateFragmentsRequest();
request.setContextNum(session.getSessionNum());
request.setContent(content);
fragmentsService.createFragments(request);
return fragmentsMapper.selectOne(Wrappers.<StudyReportFragmentsEntity>lambdaQuery()
.eq(StudyReportFragmentsEntity::getContextNum, session.getSessionNum())
.orderByDesc(StudyReportFragmentsEntity::getId)
.last("LIMIT 1"));
}
private void addTag(StudyReportFragmentsEntity fragment, String tagName) throws Exception {
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(fragment.getId()), tagName);
}
private TagScope scope(String mode, String... tags) throws ErrorParameterException {
return tagMindMapService.resolveScope(List.of(tags), mode);
}
/** 轮询到终态(等价于前端的轮询行为) */
private AiTaskResponse awaitTerminal(String taskNum) throws Exception {
AiTaskResponse response = null;
for (int i = 0; i < 200; i++) {
response = aiTaskService.getByTaskNum(taskNum);
if (AiTaskStatusEnum.SUCCEEDED.name().equals(response.getStatus())
|| AiTaskStatusEnum.FAILED.name().equals(response.getStatus())) {
return response;
}
Thread.sleep(50);
}
throw new AssertionError("AI 任务未进入终态,最后状态: " + (response == null ? "null" : response.getStatus()));
}
private static AiTaskSubmitRequest request(String type, String targetNum, Map<String, Object> params) {
AiTaskSubmitRequest request = new AiTaskSubmitRequest();
request.setType(type);
request.setTargetNum(targetNum);
request.setParams(params);
return request;
}
// ============ 取材:并集 / 交集 ============
@Test
void unionAndIntersect_pickDifferentFragments() throws Exception {
String taskNum = saveTask("标签取材任务-" + SEQ.incrementAndGet());
String tagA = tag("并集A");
String tagB = tag("并集B");
StudyReportFragmentsEntity onlyA = createFragment(taskNum, "只有标签A的碎片");
addTag(onlyA, tagA);
StudyReportFragmentsEntity both = createFragment(taskNum, "同时带两标签的碎片");
addTag(both, tagA);
addTag(both, tagB);
StudyReportFragmentsEntity onlyB = createFragment(taskNum, "只有标签B的碎片");
addTag(onlyB, tagB);
ReviewTagMindMapEntity union = tagMindMapService.regenerate(scope("UNION", tagA, tagB));
assertEquals(3, union.getSourceFragmentCount().intValue(), "并集取带任一标签的碎片");
assertTrue(union.getOutline().contains("只有标签A的碎片"));
assertTrue(union.getOutline().contains("同时带两标签的碎片"));
assertTrue(union.getOutline().contains("只有标签B的碎片"));
ReviewTagMindMapEntity intersect = tagMindMapService.regenerate(scope("INTERSECT", tagA, tagB));
assertEquals(1, intersect.getSourceFragmentCount().intValue(), "交集只取同时带全部标签的碎片");
assertTrue(intersect.getOutline().contains("同时带两标签的碎片"));
assertFalse(intersect.getOutline().contains("只有标签A的碎片"));
assertEquals(TagCombineModeEnum.INTERSECT.name(), intersect.getCombineMode());
}
@Test
void singleTag_isItsOwnScope() throws Exception {
String taskNum = saveTask("单标签任务-" + SEQ.incrementAndGet());
String tagA = tag("单标签");
addTag(createFragment(taskNum, "单标签碎片"), tagA);
ReviewTagMindMapEntity map = tagMindMapService.regenerate(scope("UNION", tagA));
assertEquals(1, map.getSourceFragmentCount().intValue());
assertEquals(TagCombineModeEnum.UNION.name(), map.getCombineMode());
}
// ============ 范围键:同一集合 + 同一模式 = 同一张导图 ============
@Test
void sameTagSetAndMode_hitsSameMap() throws Exception {
String taskNum = saveTask("范围键任务-" + SEQ.incrementAndGet());
String tagA = tag("范围键A");
String tagB = tag("范围键B");
addTag(createFragment(taskNum, "范围键碎片"), tagA);
ReviewTagMindMapEntity first = tagMindMapService.regenerate(scope("UNION", tagA, tagB));
// 顺序、大小写、空白不同,仍是同一个范围
ReviewTagMindMapEntity second = tagMindMapService
.regenerate(scope("union", " " + tagB + " ", tagA.toUpperCase()));
assertEquals(first.getId(), second.getId(), "集合相同且模式相同应命中同一张导图");
TagScope reordered = tagMindMapService.resolveScope(List.of(tagB, tagA.toUpperCase()), null);
assertEquals(first.getScopeKey(), reordered.scopeKey(), "范围键与顺序、大小写、空白无关");
assertEquals(1, tagMindMapMapper.selectCount(Wrappers.<ReviewTagMindMapEntity>lambdaQuery()
.eq(ReviewTagMindMapEntity::getScopeKey, first.getScopeKey())).intValue(),
"同一范围不会产生第二行");
}
@Test
void differentModeOrTagSet_isDifferentMap() throws Exception {
String taskNum = saveTask("范围区分任务-" + SEQ.incrementAndGet());
String tagA = tag("范围区分A");
String tagB = tag("范围区分B");
StudyReportFragmentsEntity fragment = createFragment(taskNum, "范围区分碎片");
addTag(fragment, tagA);
addTag(fragment, tagB);
ReviewTagMindMapEntity union = tagMindMapService.regenerate(scope("UNION", tagA, tagB));
ReviewTagMindMapEntity intersect = tagMindMapService.regenerate(scope("INTERSECT", tagA, tagB));
ReviewTagMindMapEntity singleTag = tagMindMapService.regenerate(scope("UNION", tagA));
assertNotEquals(union.getId(), intersect.getId(), "不同取数模式是不同导图");
assertNotEquals(union.getId(), singleTag.getId(), "不同标签集合是不同导图");
}
// ============ 素材变化:只置「待更新」,不自动重建 ============
@Test
void tagChanges_markMapNeedsUpdateWithoutRebuild() throws Exception {
String taskNum = saveTask("待更新任务-" + SEQ.incrementAndGet());
String tagA = tag("待更新A");
String tagB = tag("待更新B");
String unrelatedTag = tag("待更新无关");
StudyReportFragmentsEntity fragment = createFragment(taskNum, "待更新碎片");
addTag(fragment, tagA);
ReviewTagMindMapEntity map = tagMindMapService.regenerate(scope("UNION", tagA, tagB));
assertFalse(map.getNeedsUpdate());
String outlineBefore = map.getOutline();
// 落库精度(微秒)后的值:待更新不应改动它
LocalDateTime generatedBefore = tagMindMapMapper.selectById(map.getId()).getGeneratedTime();
// 范围外的标签变化不影响这张导图
addTag(fragment, unrelatedTag);
assertFalse(tagMindMapMapper.selectById(map.getId()).getNeedsUpdate(), "范围外的标签不影响本导图");
// 范围内新增一个标签:置「待更新」,但内容原样保留(重建由用户手动触发)
addTag(fragment, tagB);
ReviewTagMindMapEntity reloaded = tagMindMapMapper.selectById(map.getId());
assertTrue(reloaded.getNeedsUpdate(), "素材变化后导图应置为待更新");
assertNotNull(reloaded.getNeedsUpdateTime());
assertEquals(outlineBefore, reloaded.getOutline(), "待更新不等于重建:导图内容保持原样");
assertEquals(generatedBefore, reloaded.getGeneratedTime());
assertEquals(1, reloaded.getSourceFragmentCount().intValue());
}
@Test
void tagDeletedFromFragment_marksMapNeedsUpdate() throws Exception {
String taskNum = saveTask("摘标签任务-" + SEQ.incrementAndGet());
String tagA = tag("摘标签A");
StudyReportFragmentsEntity fragment = createFragment(taskNum, "摘标签碎片");
addTag(fragment, tagA);
ReviewTagMindMapEntity map = tagMindMapService.regenerate(scope("UNION", tagA));
assertFalse(map.getNeedsUpdate());
Integer markerId = markerService.listByObject(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(fragment.getId()))
.stream().filter(m -> tagA.equals(m.getMarkerName())).findFirst().orElseThrow().getId();
markerService.deleteMarker(markerId);
ReviewTagMindMapEntity reloaded = tagMindMapMapper.selectById(map.getId());
assertTrue(reloaded.getNeedsUpdate(), "标签被摘掉后导图应置为待更新");
assertEquals(map.getOutline(), reloaded.getOutline(), "置「待更新」不会自动重建");
}
@Test
void fragmentDeleted_marksMapNeedsUpdate() throws Exception {
String taskNum = saveTask("删碎片任务-" + SEQ.incrementAndGet());
String tagA = tag("删碎片A");
StudyReportFragmentsEntity fragment = createFragment(taskNum, "删碎片");
addTag(fragment, tagA);
ReviewTagMindMapEntity map = tagMindMapService.regenerate(scope("UNION", tagA));
assertFalse(map.getNeedsUpdate());
fragmentsService.deleteFragment(fragment.getId());
assertTrue(tagMindMapMapper.selectById(map.getId()).getNeedsUpdate(),
"碎片被删除后导图应置为待更新");
}
@Test
void softDeletedFragment_isNotMaterial() throws Exception {
String taskNum = saveTask("软删除任务-" + SEQ.incrementAndGet());
String tagA = tag("软删除A");
StudyReportFragmentsEntity kept = createFragment(taskNum, "保留的碎片");
StudyReportFragmentsEntity removed = createFragment(taskNum, "被软删除的碎片");
addTag(kept, tagA);
addTag(removed, tagA);
// 直接逻辑删除碎片(保留标记行),验证取材按 deleted=0 过滤
fragmentsMapper.deleteById(removed.getId());
ReviewTagMindMapEntity map = tagMindMapService.regenerate(scope("UNION", tagA));
assertEquals(1, map.getSourceFragmentCount().intValue(), "软删除的碎片不取材");
assertTrue(map.getOutline().contains("保留的碎片"));
assertFalse(map.getOutline().contains("被软删除的碎片"));
}
// ============ 租户隔离 ============
@Test
void otherUsersFragments_areNotMaterial() throws Exception {
String sharedTag = tag("租户隔离");
StpUtil.login(USER + "-其他用户", "test_device");
String otherTask = saveTask("其他用户任务-" + SEQ.incrementAndGet());
addTag(createFragment(otherTask, "其他用户的碎片"), sharedTag);
StpUtil.login(USER, "test_device");
String myTask = saveTask("本用户任务-" + SEQ.incrementAndGet());
addTag(createFragment(myTask, "本用户的碎片"), sharedTag);
ReviewTagMindMapEntity map = tagMindMapService.regenerate(scope("UNION", sharedTag));
assertEquals(1, map.getSourceFragmentCount().intValue(), "取材只覆盖当前用户的数据");
assertTrue(map.getOutline().contains("本用户的碎片"));
assertFalse(map.getOutline().contains("其他用户的碎片"));
}
// ============ AI 任务链路(前端实际接线路径) ============
@Test
void tagMindMapTask_generatesMapAndIsQueryableAgain() throws Exception {
String taskNum = saveTask("标签任务任务-" + SEQ.incrementAndGet());
String tagA = tag("标签任务A");
addTag(createFragment(taskNum, "标签任务碎片"), tagA);
TagScope scope = scope("UNION", tagA);
// 读取不生成
assertNull(tagMindMapService.query(scope).getMap());
AiTaskResponse submitted = aiTaskService.submit(request("TAG_MIND_MAP", scope.scopeKey(),
Map.of("tags", scope.tags(), "combineMode", "UNION", "mode", "full")));
AiTaskResponse done = awaitTerminal(submitted.getTaskNum());
assertEquals(AiTaskStatusEnum.SUCCEEDED.name(), done.getStatus(), done.getErrorMessage());
assertNotNull(done.getResult().get("tagMapId"));
assertEquals(scope.scopeKey(), done.getResult().get("scopeKey"));
assertNotNull(tagMindMapService.query(scope).getMap());
// 已有导图时 ensure 模式不重复生成
AiTaskResponse ensure = awaitTerminal(aiTaskService.submit(request("TAG_MIND_MAP", scope.scopeKey(),
Map.of("tags", scope.tags(), "combineMode", "UNION", "mode", "ensure"))).getTaskNum());
assertEquals(AiTaskStatusEnum.SUCCEEDED.name(), ensure.getStatus(), ensure.getErrorMessage());
assertEquals("已存在,跳过生成", ensure.getResult().get("summary"));
}
@Test
void tagMindMapTask_withMismatchedTarget_fails() throws Exception {
String taskNum = saveTask("标签任务不匹配-" + SEQ.incrementAndGet());
String tagA = tag("标签任务不匹配A");
addTag(createFragment(taskNum, "标签任务不匹配碎片"), tagA);
AiTaskResponse done = awaitTerminal(aiTaskService.submit(request("TAG_MIND_MAP", "不是范围键",
Map.of("tags", List.of(tagA), "combineMode", "UNION"))).getTaskNum());
assertEquals(AiTaskStatusEnum.FAILED.name(), done.getStatus());
assertTrue(done.getErrorMessage().contains("对不上"), "失败原因应说明范围与目标不一致:" + done.getErrorMessage());
}
// ============ 用户编辑与参数校验 ============
@Test
void userEditsOutline_createsThenReplacesSameRangeMap() throws Exception {
String tagA = tag("用户编辑");
TagScope scope = scope("UNION", tagA);
assertNull(tagMindMapService.query(scope).getMap(), "读取不触发生成");
ReviewTagMindMapEntity created = tagMindMapService.updateByOutline(scope,
"我的标签导图\n - 分支一\n - 分支二");
assertEquals("我的标签导图", created.getTitle());
assertEquals("USER", created.getGenerator());
ReviewTagMindMapEntity updated = tagMindMapService.updateByOutline(scope, "改过的导图\n - 只剩一个分支");
assertEquals(created.getId(), updated.getId(), "同一范围只有一张导图");
assertEquals("改过的导图", tagMindMapService.query(scope).getMap().getTitle());
}
@Test
void resolveScope_rejectsEmptyInvalidOversizedAndTooLongRanges() {
assertThrows(ErrorParameterException.class,
() -> tagMindMapService.resolveScope(List.of(" "), "UNION"));
assertThrows(ErrorParameterException.class,
() -> tagMindMapService.resolveScope(List.of("A"), "XOR"));
assertThrows(ErrorParameterException.class, () -> tagMindMapService.resolveScope(
List.of("a", "b", "c", "d", "e", "f", "g", "h", "i", "j", "k"), "UNION"));
assertThrows(ErrorParameterException.class,
() -> tagMindMapService.resolveScope(List.of("x".repeat(101)), "UNION"));
}
@Test
void incrementalGenerateWithoutExistingMap_fails() throws Exception {
TagScope scope = scope("UNION", tag("增量无导图"));
assertThrows(com.guo.learningprogresstracker.exception.NotFindEntitiesException.class,
() -> tagMindMapService.incrementalGenerate(scope));
}
@Test
void generateWithoutMaterial_failsWithReadableMessage() throws Exception {
TagScope scope = scope("UNION", tag("没有取材"));
OperationFailedException failure = assertThrows(OperationFailedException.class,
() -> tagMindMapService.regenerate(scope));
assertTrue(failure.getMessage().contains("标签"), "失败文案应说明这些标签下没有内容,实际:" + failure.getMessage());
}
}
@@ -0,0 +1,62 @@
package com.guo.learningprogresstracker.utils;
import com.guo.learningprogresstracker.enums.TagCombineModeEnum;
import org.junit.jupiter.api.Test;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertNotEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
/**
* 复习范围规范化(闭环-04)的单元测试。
*
* <p>核心口径:集合相同(顺序、大小写、空白无关)且取数模式相同 → 同一个范围键;任一不同 → 不同范围键。</p>
*/
class TagScopeToolTest {
@Test
void normalize_stripsBlankAndLowercases() {
assertEquals("java", TagScopeTool.normalize(" Java "));
assertEquals("并发", TagScopeTool.normalize("并发"));
assertEquals("", TagScopeTool.normalize(null));
}
@Test
void canonicalTags_dedupesByNormalizedNameAndKeepsInputSpelling() {
List<String> canonical = TagScopeTool.canonicalTags(List.of("Java", " java ", "并发"));
assertEquals(List.of("Java", "并发"), canonical, "按归一化名排序,展示保留输入原样");
}
@Test
void scopeKey_isStableAcrossOrderCaseAndBlank() {
String first = TagScopeTool.scopeKey(List.of("Java", "并发"), TagCombineModeEnum.UNION);
String reordered = TagScopeTool.scopeKey(List.of(" 并发 ", "JAVA"), TagCombineModeEnum.UNION);
assertEquals(first, reordered, "集合相同且模式相同时范围键必须一致");
assertEquals(64, first.length(), "范围键是 SHA-256 十六进制串");
}
@Test
void scopeKey_differsByModeOrTagSet() {
String union = TagScopeTool.scopeKey(List.of("Java", "并发"), TagCombineModeEnum.UNION);
String intersect = TagScopeTool.scopeKey(List.of("Java", "并发"), TagCombineModeEnum.INTERSECT);
String otherSet = TagScopeTool.scopeKey(List.of("Java"), TagCombineModeEnum.UNION);
assertNotEquals(union, intersect, "不同取数模式是不同范围");
assertNotEquals(union, otherSet, "不同标签集合是不同范围");
}
@Test
void storedTags_roundTrip() {
List<String> tags = List.of("Java", "并发");
String stored = TagScopeTool.toStoredTags(tags);
assertEquals(tags, TagScopeTool.parseStoredTags(stored));
assertTrue(TagScopeTool.parseStoredTags(null).isEmpty(), "缺失时按空集合处理");
assertTrue(TagScopeTool.parseStoredTags("不是 JSON").isEmpty(), "损坏时按空集合处理");
}
}