feat: 新增学习引导链路与来源标记

This commit is contained in:
2026-10-09 19:30:59 +08:00
parent c6258fa6d7
commit b51a6216ce
11 changed files with 929 additions and 25 deletions
@@ -0,0 +1,123 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.ReviewTiming;
import com.guo.learningprogresstracker.dto.request.AiTaskSubmitRequest;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.entity.ReviewGuidanceConversationEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.service.AiTaskService;
import com.guo.learningprogresstracker.service.GuidanceService;
import com.guo.learningprogresstracker.dto.AiTaskResponse;
import io.swagger.v3.oas.annotations.Operation;
import lombok.RequiredArgsConstructor;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import java.time.LocalDateTime;
import java.time.format.DateTimeParseException;
import java.util.LinkedHashMap;
import java.util.Map;
/**
* 学习引导控制层(复习-06)。
*
* <p>多轮对话复用 AI 异步任务(AI-02):每一轮提交一个 {@code GUIDANCE} 任务,前端轮询拿回复。
* 因此生成期间可以离开页面,回来继续;一轮的耗时也不会占用请求线程。</p>
*
* <p>产出的知识碎片走碎片既有逻辑,只是记录上下文是这次复习行为、并带「来自学习引导」系统标记。</p>
*/
@RequestMapping("/review/guidance")
@RestController
@Validated
@RequiredArgsConstructor
public class GuidanceController {
private final GuidanceService guidanceService;
private final AiTaskService aiTaskService;
/**
* 开启一次学习引导并提交第一个问题(AI 任务)。
*/
@PostMapping
@Operation(summary = "开启学习引导:返回引导编号与首个 AI 任务编号")
public CommonResult<Map<String, Object>> start(@RequestBody Map<String, String> body)
throws NotFindEntitiesException, ErrorParameterException {
String taskNum = body == null ? null : body.get("taskNum");
String concept = body == null ? null : body.get("concept");
ReviewGuidanceConversationEntity conversation = guidanceService.start(taskNum, concept);
Map<String, Object> result = new LinkedHashMap<>();
result.put("guidanceNum", conversation.getGuidanceNum());
result.put("taskNum", conversation.getTaskNum());
result.put("concept", conversation.getConcept());
result.put("aiTaskNum", submitTurn(conversation.getGuidanceNum()).getTaskNum());
return CommonResult.success(result);
}
/**
* 继续一轮:提交用户的回答/追问,返回本轮 AI 任务编号
*/
@PostMapping("/{guidanceNum}/turns")
public CommonResult<AiTaskResponse> continueTurn(@PathVariable String guidanceNum,
@RequestBody Map<String, String> body)
throws NotFindEntitiesException, ErrorParameterException {
guidanceService.appendUserTurn(guidanceNum, body == null ? null : body.get("message"));
return CommonResult.success(submitTurn(guidanceNum));
}
/**
* 读取这次引导的当前状态(含对话轮次),用于离开页面后回来继续
*/
@GetMapping("/{guidanceNum}")
public CommonResult<ReviewGuidanceConversationEntity> getConversation(@PathVariable String guidanceNum)
throws NotFindEntitiesException {
return CommonResult.success(guidanceService.getByGuidanceNum(guidanceNum));
}
/**
* 用户确认产出:把这次引导的收获记成一条知识碎片。
* <p>不确认就不产生任何数据。</p>
*/
@PostMapping("/{guidanceNum}/fragments")
public CommonResult<StudyReportFragmentsEntity> confirmFragment(@PathVariable String guidanceNum,
@RequestBody Map<String, Object> body)
throws ErrorParameterException, NotFindEntitiesException {
String content = body == null ? null : (String) body.get("content");
ReviewTiming timing = new ReviewTiming(
parseTime(body == null ? null : body.get("reviewStartedAt")),
parseTime(body == null ? null : body.get("reviewLastInteractionAt")),
body != null && body.get("reviewDurationSeconds") instanceof Number number
? number.intValue() : null);
return CommonResult.success(guidanceService.confirmFragment(guidanceNum, content, timing));
}
/**
* 放弃这次引导:不产出任何数据
*/
@DeleteMapping("/{guidanceNum}")
public CommonResult<Void> abandon(@PathVariable String guidanceNum) throws NotFindEntitiesException {
guidanceService.abandon(guidanceNum);
return CommonResult.success();
}
/** 提交一轮学习引导任务:targetNum 是引导编号,执行器会带上会话里的历史轮次 */
private AiTaskResponse submitTurn(String guidanceNum) throws ErrorParameterException, NotFindEntitiesException {
AiTaskSubmitRequest request = new AiTaskSubmitRequest();
request.setType("GUIDANCE");
request.setTargetNum(guidanceNum);
return aiTaskService.submit(request);
}
private static LocalDateTime parseTime(Object value) {
if (!(value instanceof String text) || text.isBlank()) {
return null;
}
try {
return LocalDateTime.parse(text.trim());
} catch (DateTimeParseException e) {
return null;
}
}
}
@@ -0,0 +1,69 @@
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 com.guo.learningprogresstracker.utils.GenerateNumTool;
import lombok.Data;
import java.io.Serializable;
import java.time.LocalDateTime;
/**
* 学习引导会话(复习-06):一次复习行为。
*
* <p>它有两重身份:产出的知识碎片以它作为**记录上下文**(复习行为),
* 复习耗时也记在它身上(与回忆对比同一口径,见复习-07)。</p>
*/
@TableName(value = "review_guidance_conversations")
@Data
public class ReviewGuidanceConversationEntity extends BaseEntity implements Serializable {
@TableId(value = "id", type = IdType.AUTO)
private Integer id;
/** 对外标识,也是产出碎片的记录上下文编号 */
@TableField(value = "guidance_num")
private String guidanceNum;
/** 被引导概念所属的学习任务,也是产出碎片的默认内容归属 */
@TableField(value = "task_num")
private String taskNum;
/** 被引导的概念(来自 Feed 卡片或导图节点) */
@TableField(value = "concept")
private String concept;
/** 对话轮次 JSON:[{role,content}] */
@TableField(value = "turns_payload")
private String turnsPayload;
/** 本次复习耗时(秒),已按 5 分钟空闲截断 */
@TableField(value = "review_duration_seconds")
private Integer reviewDurationSeconds;
@TableField(value = "finished")
private Boolean finished;
@TableField(value = "started_time")
private LocalDateTime startedTime;
@TableField(value = "finished_time")
private LocalDateTime finishedTime;
@TableField(exist = false)
private static final long serialVersionUID = 1L;
public static ReviewGuidanceConversationEntity initNewConversation(String taskNum, String concept) {
ReviewGuidanceConversationEntity conversation = new ReviewGuidanceConversationEntity();
conversation.setGuidanceNum(GenerateNumTool.generateNum("GUIDANCE"));
conversation.setTaskNum(taskNum);
conversation.setConcept(concept);
conversation.setTurnsPayload("[]");
conversation.setReviewDurationSeconds(0);
conversation.setFinished(false);
conversation.setStartedTime(LocalDateTime.now());
return conversation;
}
}
@@ -17,7 +17,10 @@ public enum AiTaskTypeEnum {
MIND_MAP("思维导图生成"),
/** 学习报告草稿聚合 */
REPORT_DRAFT("学习报告草稿");
REPORT_DRAFT("学习报告草稿"),
/** 学习引导:开放式问题引导与概念边界纠正(复习-06) */
GUIDANCE("学习引导");
private final String description;
@@ -0,0 +1,9 @@
package com.guo.learningprogresstracker.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.guo.learningprogresstracker.entity.ReviewGuidanceConversationEntity;
import org.apache.ibatis.annotations.Mapper;
@Mapper
public interface ReviewGuidanceConversationMapper extends BaseMapper<ReviewGuidanceConversationEntity> {
}
@@ -0,0 +1,74 @@
package com.guo.learningprogresstracker.service;
import com.guo.learningprogresstracker.dto.ReviewTiming;
import com.guo.learningprogresstracker.entity.ReviewGuidanceConversationEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
/**
* 学习引导服务(复习-06)。
*
* <p>一次引导是一次**复习行为**:它有自己的记录实体(记录上下文与复习耗时都挂在它身上),
* 产出的知识碎片走碎片的全部既有逻辑(内容归属、待归类、导图取材、Feed 回收),
* 只是额外带一个「来自学习引导」的系统标记。</p>
*
* <p>这条链路**没有降级形态**:它不属于核心闭环,AI 不可用时整体不可用。</p>
*/
public interface GuidanceService {
/**
* 开启一次学习引导。
*
* @param taskNum 被引导概念所属的学习任务,也是产出碎片的默认内容归属
* @param concept 被引导的概念(来自 Feed 卡片或导图节点)
*/
ReviewGuidanceConversationEntity start(String taskNum, String concept) throws NotFindEntitiesException;
/**
* 记录用户的一轮提问/回答,返回追加后的对话轮次(JSON 字符串),供 AI 任务作为上下文。
*
* @return 追加用户这一轮之后的完整轮次
*/
String appendUserTurn(String guidanceNum, String userMessage) throws NotFindEntitiesException;
/**
* 记录 AI 的回复(由 AI 任务执行器在请求线程之外调用)。
*/
void appendAssistantTurn(String guidanceNum, String reply);
/**
* 读取对话轮次(供 AI 任务取历史上下文)。
*/
String turnsOf(String guidanceNum) throws NotFindEntitiesException;
/**
* 读取并解析对话轮次为列表形式(供拼装 AI 请求)。
*/
java.util.List<java.util.Map<String, String>> historyOf(String guidanceNum) throws NotFindEntitiesException;
/**
* 按引导编号取会话。
*/
ReviewGuidanceConversationEntity getByGuidanceNum(String guidanceNum) throws NotFindEntitiesException;
/**
* 用户确认产出:把这次引导的收获记成一条知识碎片。
*
* <ul>
* <li>记录上下文 = 本次引导(REVIEW);</li>
* <li>内容归属 = 被引导概念所属任务(用户之后可以改);</li>
* <li>带「来自学习引导」系统标记;</li>
* <li>同时把这次引导标记为结束并记下复习耗时。</li>
* </ul>
*
* @return 生成的碎片
*/
StudyReportFragmentsEntity confirmFragment(String guidanceNum, String content, ReviewTiming timing)
throws ErrorParameterException, NotFindEntitiesException;
/**
* 放弃这次引导:不产出任何数据,只把会话标记为结束(记录上下文因此不会被碎片引用)。
*/
void abandon(String guidanceNum) throws NotFindEntitiesException;
}
@@ -129,6 +129,32 @@ public class AiServiceClient {
}
}
/**
* 调用 lpt-ai 进行学习引导的一轮对话(复习-06)。
*
* <p>学习引导允许完全依赖 AI:这条链路没有降级形态,AI 不可用时返回 empty,
* 由调用方把任务标记为失败,前端据此把入口置为不可用。</p>
*
* @param history 之前的轮次(role/content),作为多轮上下文
*/
public Optional<String> guidance(String taskName, String concept, List<Map<String, String>> history) {
if (!isConfigured()) {
return Optional.empty();
}
try {
Map<String, Object> params = Map.of(
"taskName", taskName,
"concept", concept,
"history", history != null ? history : List.of()
);
Optional<JsonNode> result = submitAndWait("guidance", params);
return result.map(r -> r.path("reply").asText(null)).filter(s -> s != null && !s.isBlank());
} catch (Exception e) {
log.warn("lpt-ai 学习引导异常: {}", e.getMessage());
return Optional.empty();
}
}
/**
* 调用 lpt-ai 进行语义化回忆对比。
*/
@@ -0,0 +1,114 @@
package com.guo.learningprogresstracker.service.impl;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.guo.learningprogresstracker.dto.ReviewTiming;
import com.guo.learningprogresstracker.entity.AiTaskEntity;
import com.guo.learningprogresstracker.entity.ReviewGuidanceConversationEntity;
import com.guo.learningprogresstracker.entity.TaskEntity;
import com.guo.learningprogresstracker.enums.AiTaskTypeEnum;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.mapper.TasksMapper;
import com.guo.learningprogresstracker.service.GuidanceService;
import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import java.time.LocalDateTime;
import java.time.format.DateTimeParseException;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.Optional;
/**
* 学习引导任务处理器(复习-06)。
*
* <p>每一轮对话是一个 AI 任务:提交用户的这一轮,执行器在请求线程之外调用 AI 并把回复写回对话。
* 这样多轮对话不需要前端在请求线程里干等,也不受 AI-01 的事务约束。</p>
*
* <p>这条链路没有降级形态:AI 不可用时直接失败,前端把入口置为不可用。</p>
*/
@Slf4j
@Component
@RequiredArgsConstructor
public class GuidanceAiTaskHandler implements AiTaskHandler {
private final GuidanceService guidanceService;
private final AiServiceClient aiServiceClient;
private final TasksMapper tasksMapper;
private final ObjectMapper objectMapper;
@Override
public AiTaskTypeEnum type() {
return AiTaskTypeEnum.GUIDANCE;
}
@Override
public Map<String, Object> execute(AiTaskEntity task, Map<String, Object> params) {
String guidanceNum = task.getTargetNum();
ReviewGuidanceConversationEntity conversation;
try {
conversation = guidanceService.getByGuidanceNum(guidanceNum);
} catch (NotFindEntitiesException e) {
throw new AiTaskFailedException(e.getMessage());
}
if (!aiServiceClient.isConfigured()) {
log.warn("学习引导需要 AI,但未配置 lpt-ai 服务");
throw new AiTaskFailedException("学习引导暂时不可用,请稍后再试");
}
String taskName = loadTaskName(conversation.getTaskNum());
List<Map<String, String>> history = readHistory(conversation);
Optional<String> reply = aiServiceClient.guidance(taskName, conversation.getConcept(), history);
String text = reply.orElseThrow(() -> new AiTaskFailedException("AI 这次没有给出回应,请重试"));
// 把 AI 的回复写回对话,供下一轮作为上下文
guidanceService.appendAssistantTurn(guidanceNum, text);
Map<String, Object> payload = new LinkedHashMap<>();
payload.put("reply", text);
return payload;
}
/**
* 对话历史一律以会话里的轮次为准(提交时只写入用户那一轮),
* 这样「同一个会话被多次提交」也不会把上下文拼错。
*/
private List<Map<String, String>> readHistory(ReviewGuidanceConversationEntity conversation) {
try {
return guidanceService.historyOf(conversation.getGuidanceNum());
} catch (NotFindEntitiesException e) {
return List.of();
}
}
private String loadTaskName(String taskNum) {
return tasksMapper.selectOne(Wrappers.<TaskEntity>lambdaQuery()
.eq(TaskEntity::getTaskNum, taskNum)
.select(TaskEntity::getTaskName)
.last("LIMIT 1"))
.getTaskName();
}
/** 供测试与调用方复用:把前端上报的计时转成 ReviewTiming */
public static ReviewTiming timingOf(Map<String, Object> params) {
return new ReviewTiming(
parseTime(params.get("reviewStartedAt")),
parseTime(params.get("reviewLastInteractionAt")),
params.get("reviewDurationSeconds") instanceof Number number ? number.intValue() : null);
}
private static LocalDateTime parseTime(Object value) {
if (!(value instanceof String text) || text.isBlank()) {
return null;
}
try {
return LocalDateTime.parse(text.trim());
} catch (DateTimeParseException e) {
return null;
}
}
}
@@ -0,0 +1,211 @@
package com.guo.learningprogresstracker.service.impl;
import com.baomidou.mybatisplus.core.toolkit.Wrappers;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.guo.learningprogresstracker.dto.ReviewTiming;
import com.guo.learningprogresstracker.entity.ReviewGuidanceConversationEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.TaskEntity;
import com.guo.learningprogresstracker.enums.FragmentContextTypeEnum;
import com.guo.learningprogresstracker.enums.MarkerObjectTypeEnum;
import com.guo.learningprogresstracker.enums.SystemMarkerEnum;
import com.guo.learningprogresstracker.exception.ErrorParameterException;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.mapper.ReviewGuidanceConversationMapper;
import com.guo.learningprogresstracker.mapper.StudyReportFragmentsMapper;
import com.guo.learningprogresstracker.mapper.TasksMapper;
import com.guo.learningprogresstracker.service.GuidanceService;
import com.guo.learningprogresstracker.service.MarkerService;
import com.guo.learningprogresstracker.utils.ReviewDurationTool;
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.LinkedHashMap;
import java.util.List;
import java.util.Map;
/**
* 学习引导服务实现(复习-06)。
*/
@Slf4j
@Service
@RequiredArgsConstructor
public class GuidanceServiceImpl implements GuidanceService {
private static final String ROLE_USER = "user";
private static final String ROLE_ASSISTANT = "assistant";
private final ReviewGuidanceConversationMapper guidanceMapper;
private final StudyReportFragmentsMapper fragmentsMapper;
private final TasksMapper tasksMapper;
private final MarkerService markerService;
private final ObjectMapper objectMapper;
@Override
@Transactional
public ReviewGuidanceConversationEntity start(String taskNum, String concept) throws NotFindEntitiesException {
if (!StringUtils.hasText(taskNum) || !tasksMapper.exists(
Wrappers.<TaskEntity>lambdaQuery().eq(TaskEntity::getTaskNum, taskNum))) {
throw new NotFindEntitiesException("这个任务不存在或已被删除");
}
if (!StringUtils.hasText(concept)) {
throw new NotFindEntitiesException("请先指定要引导的概念");
}
ReviewGuidanceConversationEntity conversation =
ReviewGuidanceConversationEntity.initNewConversation(taskNum.trim(), concept.trim());
guidanceMapper.insert(conversation);
log.info("学习引导已开启: guidanceNum={}, taskNum={}, concept={}",
conversation.getGuidanceNum(), taskNum, concept);
return conversation;
}
@Override
public ReviewGuidanceConversationEntity getByGuidanceNum(String guidanceNum) throws NotFindEntitiesException {
ReviewGuidanceConversationEntity conversation = guidanceMapper.selectOne(
Wrappers.<ReviewGuidanceConversationEntity>lambdaQuery()
.eq(ReviewGuidanceConversationEntity::getGuidanceNum, guidanceNum)
.last("LIMIT 1"));
if (conversation == null) {
log.warn("学习引导[{}]不存在", guidanceNum);
throw new NotFindEntitiesException("这次学习引导不存在或已被删除");
}
return conversation;
}
@Override
public String turnsOf(String guidanceNum) throws NotFindEntitiesException {
return getByGuidanceNum(guidanceNum).getTurnsPayload();
}
@Override
public List<Map<String, String>> historyOf(String guidanceNum) throws NotFindEntitiesException {
return readTurns(getByGuidanceNum(guidanceNum));
}
@Override
@Transactional
public String appendUserTurn(String guidanceNum, String userMessage) throws NotFindEntitiesException {
if (!StringUtils.hasText(userMessage)) {
throw new NotFindEntitiesException("请先写下你的想法");
}
ReviewGuidanceConversationEntity conversation = getByGuidanceNum(guidanceNum);
List<Map<String, String>> turns = readTurns(conversation);
Map<String, String> turn = new LinkedHashMap<>();
turn.put("role", ROLE_USER);
turn.put("content", userMessage.trim());
turns.add(turn);
String payload = writeTurns(turns);
updateTurns(conversation.getId(), payload);
return payload;
}
@Override
public void appendAssistantTurn(String guidanceNum, String reply) {
if (!StringUtils.hasText(reply)) {
return;
}
try {
ReviewGuidanceConversationEntity conversation = getByGuidanceNum(guidanceNum);
List<Map<String, String>> turns = readTurns(conversation);
Map<String, String> turn = new LinkedHashMap<>();
turn.put("role", ROLE_ASSISTANT);
turn.put("content", reply.trim());
turns.add(turn);
updateTurns(conversation.getId(), writeTurns(turns));
} catch (NotFindEntitiesException e) {
// 会话没了(被删除)时无需报错,AI 回复无处可放而已
log.warn("学习引导[{}]已不存在,AI 回复未记录", guidanceNum);
}
}
@Override
@Transactional
public StudyReportFragmentsEntity confirmFragment(String guidanceNum, String content, ReviewTiming timing)
throws ErrorParameterException, NotFindEntitiesException {
if (!StringUtils.hasText(content)) {
throw new ErrorParameterException("请先写下这次引导的收获");
}
ReviewGuidanceConversationEntity conversation = getByGuidanceNum(guidanceNum);
if (Boolean.TRUE.equals(conversation.getFinished())) {
throw new ErrorParameterException("这次学习引导已经结束了");
}
StudyReportFragmentsEntity fragment = new StudyReportFragmentsEntity();
// 记录上下文 = 这次复习行为(不可变)
fragment.setContextType(FragmentContextTypeEnum.REVIEW.name());
fragment.setContextNum(conversation.getGuidanceNum());
// 默认内容归属 = 被引导概念所属任务;用户之后可以改
fragment.setOwnerTaskNum(conversation.getTaskNum());
fragment.setContent(content.trim());
fragmentsMapper.insert(fragment);
// 「来自学习引导」只说明来源,不改变碎片的任何处理逻辑
markerService.addSystemMarker(MarkerObjectTypeEnum.FRAGMENT,
String.valueOf(fragment.getId()), SystemMarkerEnum.FROM_GUIDANCE);
finishConversation(conversation, timing);
log.info("学习引导[{}]产出碎片[{}],默认归属任务[{}]",
guidanceNum, fragment.getId(), conversation.getTaskNum());
return fragment;
}
@Override
public void abandon(String guidanceNum) throws NotFindEntitiesException {
ReviewGuidanceConversationEntity conversation = getByGuidanceNum(guidanceNum);
if (Boolean.TRUE.equals(conversation.getFinished())) {
return;
}
finishConversation(conversation, null);
log.info("学习引导[{}]已放弃,未产出任何碎片", guidanceNum);
}
/** 结束这次引导:记下复习耗时(与回忆对比同一口径),不产出碎片 */
private void finishConversation(ReviewGuidanceConversationEntity conversation, ReviewTiming timing) {
ReviewGuidanceConversationEntity patch = new ReviewGuidanceConversationEntity();
patch.setId(conversation.getId());
patch.setFinished(true);
patch.setFinishedTime(LocalDateTime.now());
patch.setReviewDurationSeconds(ReviewDurationTool.resolveSeconds(
timing == null ? null : timing.startedAt(),
timing == null ? null : timing.lastInteractionAt(),
timing == null ? null : timing.durationSeconds(),
LocalDateTime.now()));
guidanceMapper.updateById(patch);
}
private void updateTurns(Integer id, String payload) {
ReviewGuidanceConversationEntity patch = new ReviewGuidanceConversationEntity();
patch.setId(id);
patch.setTurnsPayload(payload);
guidanceMapper.updateById(patch);
}
private List<Map<String, String>> readTurns(ReviewGuidanceConversationEntity conversation) {
String payload = conversation.getTurnsPayload();
if (!StringUtils.hasText(payload)) {
return new ArrayList<>();
}
try {
return new ArrayList<>(objectMapper.readValue(payload, new TypeReference<List<Map<String, String>>>() {
}));
} catch (Exception e) {
log.warn("学习引导[{}]的对话轮次解析失败,按空历史继续", conversation.getGuidanceNum());
return new ArrayList<>();
}
}
private String writeTurns(List<Map<String, String>> turns) {
try {
return objectMapper.writeValueAsString(turns);
} catch (Exception e) {
log.warn("学习引导对话轮次序列化失败: {}", e.getMessage());
return "[]";
}
}
}
@@ -0,0 +1,29 @@
-- 复习-06:学习引导。
--
-- 学习引导是一次「复习行为」,因此需要自己的记录实体:
-- 1. 它产出的知识碎片以本次引导作为「记录上下文」(context_type=REVIEW, context_num=guidance_num);
-- 2. 复习耗时(复习-07)也记在这次行为上,与回忆对比同一口径。
--
-- 对话轮次以 JSON 存在会话行上(一次引导的轮次数量有限,不为此单开表)。
CREATE TABLE review_guidance_conversations
(
id INT AUTO_INCREMENT COMMENT 'id无业务含义'
PRIMARY KEY,
guidance_num VARCHAR(255) NOT NULL COMMENT '引导编号(对外标识,也是产出碎片的记录上下文编号)',
task_num VARCHAR(255) NOT NULL COMMENT '被引导概念所属的学习任务,也是产出碎片的默认内容归属',
concept VARCHAR(500) NOT NULL COMMENT '被引导的概念(来自 Feed 卡片或导图节点)',
turns_payload MEDIUMTEXT NULL COMMENT '对话轮次 JSON:[{role,content}],发给 AI 时作为上下文',
review_duration_seconds INT DEFAULT 0 NOT NULL COMMENT '本次复习耗时(秒),已按 5 分钟空闲截断',
finished TINYINT(1) NOT NULL DEFAULT 0 COMMENT '是否已结束(用户确认产出碎片或主动放弃)',
started_time DATETIME NOT NULL COMMENT '开始时间',
finished_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 '逻辑删除符',
UNIQUE KEY uk_review_guidance_guidance_num (guidance_num),
KEY idx_review_guidance_task (created_by, task_num, started_time)
)
COMMENT '学习引导:开放式问题引导 + 概念边界纠正,产出的碎片带「来自学习引导」系统标记';
@@ -0,0 +1,232 @@
package com.guo.learningprogresstracker.service.impl;
import cn.dev33.satoken.stp.StpUtil;
import com.guo.learningprogresstracker.dto.AiTaskResponse;
import com.guo.learningprogresstracker.dto.request.AiTaskSubmitRequest;
import com.guo.learningprogresstracker.entity.MarkerEntity;
import com.guo.learningprogresstracker.entity.ReviewGuidanceConversationEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.TaskEntity;
import com.guo.learningprogresstracker.enums.AiTaskStatusEnum;
import com.guo.learningprogresstracker.enums.MarkerKindEnum;
import com.guo.learningprogresstracker.enums.MarkerObjectTypeEnum;
import com.guo.learningprogresstracker.mapper.StudyReportFragmentsMapper;
import com.guo.learningprogresstracker.mapper.TasksMapper;
import com.guo.learningprogresstracker.service.AiTaskService;
import com.guo.learningprogresstracker.service.GuidanceService;
import com.guo.learningprogresstracker.service.MarkerService;
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.util.Map;
import java.util.Optional;
import java.util.concurrent.atomic.AtomicInteger;
import static org.junit.jupiter.api.Assertions.*;
import static org.mockito.ArgumentMatchers.any;
import static org.mockito.ArgumentMatchers.anyString;
import static org.mockito.Mockito.when;
/**
* 学习引导的落库集成测试(复习-06)。
*
* <p>核心验收:引导结束后用户确认可生成一条<b>归属正确、带来源标记</b>的碎片;
* <b>不确认则不产生任何数据</b>;AI 不可用时链路失败且不影响复习其他部分。</p>
*/
@SpringBootTest
class GuidanceIntegrationTest {
private static final String USER = "学习引导集成测试用户";
private static final AtomicInteger SEQ = new AtomicInteger();
@Autowired
private GuidanceService guidanceService;
@Autowired
private MarkerService markerService;
@Autowired
private AiTaskService aiTaskService;
@Autowired
private AiTaskRunner aiTaskRunner;
@Autowired
private StudyReportFragmentsMapper fragmentsMapper;
@Autowired
private TasksMapper tasksMapper;
@MockBean
private AiServiceClient aiServiceClient;
@BeforeEach
void setUp() {
StpUtil.login(USER, "test_device");
when(aiServiceClient.isConfigured()).thenReturn(true);
when(aiServiceClient.guidance(anyString(), anyString(), any()))
.thenReturn(Optional.of("那 1B 参数量的模型一定占 1GB 显存吗?"));
}
private String saveTask() {
String taskNum = "TASKGD-IT-" + System.nanoTime() + "-" + SEQ.incrementAndGet();
TaskEntity task = new TaskEntity();
task.setTaskNum(taskNum);
task.setTaskName("学习引导测试任务");
tasksMapper.insert(task);
return taskNum;
}
@Test
void start_createsConversationBoundToTask() throws Exception {
String taskNum = saveTask();
ReviewGuidanceConversationEntity conversation = guidanceService.start(taskNum, "参数量与显存");
assertNotNull(conversation.getGuidanceNum());
assertTrue(conversation.getGuidanceNum().startsWith("GUIDANCE-"));
assertEquals(taskNum, conversation.getTaskNum());
assertEquals("参数量与显存", conversation.getConcept());
assertFalse(Boolean.TRUE.equals(conversation.getFinished()));
}
@Test
void confirm_createsFragmentWithContextOwnerAndSourceMarker() throws Exception {
String taskNum = saveTask();
ReviewGuidanceConversationEntity conversation = guidanceService.start(taskNum, "参数量与显存");
StudyReportFragmentsEntity fragment = guidanceService.confirmFragment(
conversation.getGuidanceNum(), "参数量只决定权重占用,不决定激活显存", null);
// 记录上下文是这次复习行为(不是学习会话)
assertEquals("REVIEW", fragment.getContextType());
assertEquals(conversation.getGuidanceNum(), fragment.getContextNum());
// 默认内容归属 = 被引导概念所属任务
assertEquals(taskNum, fragment.getOwnerTaskNum());
// 带「来自学习引导」系统标记,且对用户可见、不可删
var markers = markerService.listByObject(
MarkerObjectTypeEnum.FRAGMENT, String.valueOf(fragment.getId()));
assertEquals(1, markers.size());
MarkerEntity marker = markers.get(0);
assertEquals(MarkerKindEnum.SYSTEM.name(), marker.getKind());
assertEquals("来源", marker.getMarkerName());
assertEquals("学习引导", marker.getMarkerValue());
// 会话被标记为结束
assertTrue(Boolean.TRUE.equals(
guidanceService.getByGuidanceNum(conversation.getGuidanceNum()).getFinished()));
}
@Test
void abandon_producesNoFragment() throws Exception {
String taskNum = saveTask();
ReviewGuidanceConversationEntity conversation = guidanceService.start(taskNum, "某概念");
long before = fragmentsMapper.selectCount(null);
guidanceService.abandon(conversation.getGuidanceNum());
assertEquals(before, fragmentsMapper.selectCount(null), "放弃不应产生任何碎片");
assertTrue(Boolean.TRUE.equals(
guidanceService.getByGuidanceNum(conversation.getGuidanceNum()).getFinished()));
}
@Test
void confirmTwice_isRejected() throws Exception {
String taskNum = saveTask();
ReviewGuidanceConversationEntity conversation = guidanceService.start(taskNum, "某概念");
guidanceService.confirmFragment(conversation.getGuidanceNum(), "收获", null);
assertThrows(com.guo.learningprogresstracker.exception.ErrorParameterException.class,
() -> guidanceService.confirmFragment(conversation.getGuidanceNum(), "再写一条", null));
}
@Test
void blankContent_isRejected() throws Exception {
String taskNum = saveTask();
ReviewGuidanceConversationEntity conversation = guidanceService.start(taskNum, "某概念");
assertThrows(com.guo.learningprogresstracker.exception.ErrorParameterException.class,
() -> guidanceService.confirmFragment(conversation.getGuidanceNum(), " ", null));
}
@Test
void unknownTask_isRejected() {
assertThrows(com.guo.learningprogresstracker.exception.NotFindEntitiesException.class,
() -> guidanceService.start("TASK-NOT-EXIST", "某概念"));
}
@Test
void turns_areAppendedInOrder() throws Exception {
String taskNum = saveTask();
ReviewGuidanceConversationEntity conversation = guidanceService.start(taskNum, "某概念");
String guidanceNum = conversation.getGuidanceNum();
guidanceService.appendUserTurn(guidanceNum, "我觉得参数量越大显存占用越大");
guidanceService.appendAssistantTurn(guidanceNum, "那 1B 模型一定占 1GB 吗?");
var history = guidanceService.historyOf(guidanceNum);
assertEquals(2, history.size());
assertEquals("user", history.get(0).get("role"));
assertEquals("assistant", history.get(1).get("role"));
}
@Test
void guidanceAiTask_completesAndWritesAssistantTurn() throws Exception {
String taskNum = saveTask();
ReviewGuidanceConversationEntity conversation = guidanceService.start(taskNum, "参数量与显存");
String guidanceNum = conversation.getGuidanceNum();
guidanceService.appendUserTurn(guidanceNum, "参数量决定显存");
AiTaskSubmitRequest request = new AiTaskSubmitRequest();
request.setType("GUIDANCE");
request.setTargetNum(guidanceNum);
AiTaskResponse submitted = aiTaskService.submit(request);
// 轮询到终态(等价于前端行为)
AiTaskResponse done = null;
for (int i = 0; i < 150; i++) {
Thread.sleep(50);
done = aiTaskService.getByTaskNum(submitted.getTaskNum());
if (AiTaskStatusEnum.SUCCEEDED.name().equals(done.getStatus())
|| AiTaskStatusEnum.FAILED.name().equals(done.getStatus())) {
break;
}
}
assertNotNull(done);
assertEquals(AiTaskStatusEnum.SUCCEEDED.name(), done.getStatus(), done.getErrorMessage());
assertNotNull(done.getResult().get("reply"));
// AI 回复写回了对话,供下一轮作为上下文
assertEquals(2, guidanceService.historyOf(guidanceNum).size());
}
@Test
void guidanceUnavailable_failsWithoutAffectingOthers() throws Exception {
when(aiServiceClient.isConfigured()).thenReturn(false);
String taskNum = saveTask();
ReviewGuidanceConversationEntity conversation = guidanceService.start(taskNum, "某概念");
AiTaskSubmitRequest request = new AiTaskSubmitRequest();
request.setType("GUIDANCE");
request.setTargetNum(conversation.getGuidanceNum());
AiTaskResponse submitted = aiTaskService.submit(request);
AiTaskResponse done = null;
for (int i = 0; i < 150; i++) {
Thread.sleep(50);
done = aiTaskService.getByTaskNum(submitted.getTaskNum());
if (AiTaskStatusEnum.SUCCEEDED.name().equals(done.getStatus())
|| AiTaskStatusEnum.FAILED.name().equals(done.getStatus())) {
break;
}
}
assertNotNull(done);
assertEquals(AiTaskStatusEnum.FAILED.name(), done.getStatus(),
"学习引导没有降级形态:AI 不可用时该链路直接失败");
}
}
@@ -73,6 +73,11 @@ class MarkerServiceIntegrationTest {
return fragment;
}
/** 标签名按用例唯一:标签是「按名检索」的,共用固定名字会让用例之间互相污染 */
private static String tag(String base) {
return base + "-" + SEQ.incrementAndGet();
}
private String saveTask() {
String taskNum = "TASKMK-IT-" + System.nanoTime() + "-" + SEQ.incrementAndGet();
TaskEntity task = new TaskEntity();
@@ -87,14 +92,15 @@ class MarkerServiceIntegrationTest {
String taskNum = saveTask();
StudyReportFragmentsEntity fragment = saveFragment(taskNum);
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(fragment.getId()), "英语");
// 重复打同一标签应幂等
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(fragment.getId()), " 英语 ");
String tagName = tag("英语");
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(fragment.getId()), tagName);
// 重复打同一标签应幂等(含首尾空白)
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(fragment.getId()), " " + tagName + " ");
List<MarkerEntity> markers = markerService.listByObject(
MarkerObjectTypeEnum.FRAGMENT, String.valueOf(fragment.getId()));
assertEquals(1, markers.size());
assertEquals("英语", markers.get(0).getMarkerName());
assertEquals(tagName, markers.get(0).getMarkerName());
assertEquals(MarkerKindEnum.USER.name(), markers.get(0).getKind());
assertNull(markers.get(0).getMarkerValue(), "用户标签只有名,没有值");
}
@@ -102,11 +108,12 @@ class MarkerServiceIntegrationTest {
@Test
void taskCanBeTaggedToo() throws Exception {
String taskNum = saveTask();
markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, "考研");
String tagName = tag("考研");
markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, tagName);
List<MarkerEntity> markers = markerService.listByObject(MarkerObjectTypeEnum.TASK, taskNum);
assertEquals(1, markers.size());
assertEquals("考研", markers.get(0).getMarkerName());
assertEquals(tagName, markers.get(0).getMarkerName());
}
@Test
@@ -129,17 +136,19 @@ class MarkerServiceIntegrationTest {
String taskNum = saveTask();
StudyReportFragmentsEntity first = saveFragment(taskNum);
StudyReportFragmentsEntity second = saveFragment(taskNum);
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(first.getId()), "英文");
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(second.getId()), "英文");
markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, "英文");
String from = tag("英文");
String to = tag("英语");
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(first.getId()), from);
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(second.getId()), from);
markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, from);
int renamed = markerService.renameUserTag("英文", "英语");
int renamed = markerService.renameUserTag(from, to);
assertEquals(3, renamed);
assertTrue(markerService.findObjectNumsByMarker(
MarkerObjectTypeEnum.FRAGMENT, "英文", null, null).isEmpty());
MarkerObjectTypeEnum.FRAGMENT, from, null, null).isEmpty());
assertEquals(2, markerService.findObjectNumsByMarker(
MarkerObjectTypeEnum.FRAGMENT, "英语", null, null).size());
MarkerObjectTypeEnum.FRAGMENT, to, null, null).size());
}
@Test
@@ -147,10 +156,12 @@ class MarkerServiceIntegrationTest {
String taskNum = saveTask();
StudyReportFragmentsEntity fragment = saveFragment(taskNum);
String id = String.valueOf(fragment.getId());
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, "英文");
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, "英语");
String from = tag("英文");
String to = tag("英语");
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, from);
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, to);
markerService.renameUserTag("英文", "英语");
markerService.renameUserTag(from, to);
assertEquals(1, markerService.listByObject(MarkerObjectTypeEnum.FRAGMENT, id).size(),
"同一对象上合并同名标签时不应产生重复");
@@ -159,7 +170,7 @@ class MarkerServiceIntegrationTest {
@Test
void deleteUserTag_removesIt() throws Exception {
String taskNum = saveTask();
MarkerEntity tag = markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, "待看");
MarkerEntity tag = markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, tag("待看"));
markerService.deleteMarker(tag.getId());
@@ -210,16 +221,18 @@ class MarkerServiceIntegrationTest {
String taskNum = saveTask();
StudyReportFragmentsEntity first = saveFragment(taskNum);
StudyReportFragmentsEntity second = saveFragment(taskNum);
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(first.getId()), "英语");
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(second.getId()), "数学");
String firstTag = tag("英语");
String secondTag = tag("数学");
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(first.getId()), firstTag);
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(second.getId()), secondTag);
Map<String, List<MarkerEntity>> grouped = markerService.listByObjects(
MarkerObjectTypeEnum.FRAGMENT,
List.of(String.valueOf(first.getId()), String.valueOf(second.getId())));
assertEquals(2, grouped.size());
assertEquals("英语", grouped.get(String.valueOf(first.getId())).get(0).getMarkerName());
assertEquals("数学", grouped.get(String.valueOf(second.getId())).get(0).getMarkerName());
assertEquals(firstTag, grouped.get(String.valueOf(first.getId())).get(0).getMarkerName());
assertEquals(secondTag, grouped.get(String.valueOf(second.getId())).get(0).getMarkerName());
}
@Test
@@ -227,12 +240,13 @@ class MarkerServiceIntegrationTest {
String taskNum = saveTask();
StudyReportFragmentsEntity fragment = saveFragment(taskNum);
String id = String.valueOf(fragment.getId());
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, "集成测试标签A");
String tagName = tag("集成测试标签A");
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, tagName);
markerService.addSystemMarker(MarkerObjectTypeEnum.FRAGMENT, id, SystemMarkerEnum.FROM_GUIDANCE);
List<MarkerUsage> usage = markerService.listUserTagUsage();
assertTrue(usage.stream().anyMatch(u -> "集成测试标签A".equals(u.getMarkerName())),
assertTrue(usage.stream().anyMatch(u -> tagName.equals(u.getMarkerName())),
"用户标签应出现在使用情况里");
assertTrue(usage.stream().noneMatch(u -> "来源".equals(u.getMarkerName())),
"系统标记不在用户的治理范围内");
@@ -241,7 +255,7 @@ class MarkerServiceIntegrationTest {
@Test
void markersAreScopedPerUser() throws Exception {
String taskNum = saveTask();
markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, "我的标签");
markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, tag("我的标签"));
StpUtil.login("标记集成测试另一个用户", "test_device");
assertTrue(markerService.listByObject(MarkerObjectTypeEnum.TASK, taskNum).isEmpty(),
@@ -253,7 +267,7 @@ class MarkerServiceIntegrationTest {
String taskNum = saveTask();
StudyReportFragmentsEntity fragment = saveFragment(taskNum);
String id = String.valueOf(fragment.getId());
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, "英语");
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, tag("英语"));
markerService.addSystemMarker(MarkerObjectTypeEnum.FRAGMENT, id, SystemMarkerEnum.FROM_GUIDANCE);
markerService.removeAllMarkers(MarkerObjectTypeEnum.FRAGMENT, id);