diff --git a/src/main/java/com/guo/learningprogresstracker/dto/MindMapFragmentPayload.java b/src/main/java/com/guo/learningprogresstracker/dto/MindMapFragmentPayload.java
new file mode 100644
index 0000000..d46b067
--- /dev/null
+++ b/src/main/java/com/guo/learningprogresstracker/dto/MindMapFragmentPayload.java
@@ -0,0 +1,10 @@
+package com.guo.learningprogresstracker.dto;
+
+/**
+ * 传给 lpt-ai 的一条碎片素材及其报告关联(报告-02)。
+ *
+ *
碎片正文之外带一个可空的 {@code reportRef}:指向同源的报告上下文。
+ * LLM 据此知道哪些碎片来自带报告的那次会话,从而只从中提取与这些碎片相关的内容。
+ */
+public record MindMapFragmentPayload(String content, String reportRef) {
+}
diff --git a/src/main/java/com/guo/learningprogresstracker/dto/MindMapReportContext.java b/src/main/java/com/guo/learningprogresstracker/dto/MindMapReportContext.java
new file mode 100644
index 0000000..9793713
--- /dev/null
+++ b/src/main/java/com/guo/learningprogresstracker/dto/MindMapReportContext.java
@@ -0,0 +1,36 @@
+package com.guo.learningprogresstracker.dto;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+
+/**
+ * 导图生成的报告参考上下文(报告-02)。
+ *
+ * 一次总结可能把若干碎片拼接出新的定义与观点,这些内容只存在于报告里、不在碎片里。
+ * 生成导图时,把碎片所在会话的报告一并带上作为 LLM 的参考,让它自行判断
+ * 「报告是否实质讨论了这些碎片的同一主题」:只有强相关才提取其内容,
+ * 只是简单提及或没提及则完全不用。
+ *
+ * {@code ref} 是报告所属会话编号,与碎片记录上下文的 {@code contextNum} 对应,
+ * 用于告诉 LLM 哪份报告与哪批碎片同源;{@code taskName} 帮助它判断领域是否一致。
+ */
+public record MindMapReportContext(
+ @Schema(description = "报告所属会话编号,用于与碎片记录上下文关联")
+ String ref,
+ @Schema(description = "产生该报告的会话所属任务名(仅作判断领域的参考,报告可能来自旁支任务)")
+ String taskName,
+ @Schema(description = "会话摘要:这次实际学了什么")
+ String sessionSummary,
+ @Schema(description = "预期达成判断:对照学习预期得出的结论")
+ String expectationVerdict,
+ @Schema(description = "自由总结:用户对本次学习的叙述")
+ String freeSummary) {
+
+ /** 三段是否都为空白:全空的报告没有参考价值,不进入导图上下文 */
+ public boolean isBlank() {
+ return isBlank(sessionSummary) && isBlank(expectationVerdict) && isBlank(freeSummary);
+ }
+
+ private static boolean isBlank(String text) {
+ return text == null || text.isBlank();
+ }
+}
diff --git a/src/main/java/com/guo/learningprogresstracker/service/MindMapAiClient.java b/src/main/java/com/guo/learningprogresstracker/service/MindMapAiClient.java
index 6528d1c..174d1ce 100644
--- a/src/main/java/com/guo/learningprogresstracker/service/MindMapAiClient.java
+++ b/src/main/java/com/guo/learningprogresstracker/service/MindMapAiClient.java
@@ -1,5 +1,6 @@
package com.guo.learningprogresstracker.service;
+import com.guo.learningprogresstracker.dto.MindMapReportContext;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.TaskApplicationEntity;
import com.guo.learningprogresstracker.entity.TaskEntity;
@@ -26,12 +27,15 @@ public interface MindMapAiClient {
* @param task 学习任务
* @param fragments 该任务名下的知识碎片(**按内容归属取**,不是按产生它的会话取)
* @param applications 该任务的应用场景(可选)
+ * @param reports 碎片同源会话的学习报告(**参考上下文**,报告-02):总结里由碎片拼接出的
+ * 新定义/观点只能从报告里取到。是否采用由实现按相关性判断;内置规则可用于忽略
* @param clientHint 前端已有的大纲文本(可选,用于 AI 续写而非全量生成)
* @return 标准思维导图的根节点;若无可生成数据则返回 {@link Optional#empty()}
*/
Optional generate(TaskEntity task,
List fragments,
List applications,
+ List reports,
String clientHint);
/**
diff --git a/src/main/java/com/guo/learningprogresstracker/service/StudyReportFragmentsService.java b/src/main/java/com/guo/learningprogresstracker/service/StudyReportFragmentsService.java
index 05a9c7d..812f0c8 100644
--- a/src/main/java/com/guo/learningprogresstracker/service/StudyReportFragmentsService.java
+++ b/src/main/java/com/guo/learningprogresstracker/service/StudyReportFragmentsService.java
@@ -35,4 +35,12 @@ public interface StudyReportFragmentsService extends IService报告现在是导图生成的参考上下文,因此它也属于「导图素材」的一部分:
+ * 变化只置「待更新」,重建仍由用户手动触发,与碎片/标签变化同口径。
+ */
+ void markMindMapsStaleForSession(String sessionNum);
}
diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/AiServiceClient.java b/src/main/java/com/guo/learningprogresstracker/service/impl/AiServiceClient.java
index e766d67..abb7cb5 100644
--- a/src/main/java/com/guo/learningprogresstracker/service/impl/AiServiceClient.java
+++ b/src/main/java/com/guo/learningprogresstracker/service/impl/AiServiceClient.java
@@ -5,6 +5,8 @@ import cn.dev33.satoken.stp.StpUtil;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.guo.learningprogresstracker.common.TenantContext;
+import com.guo.learningprogresstracker.dto.MindMapFragmentPayload;
+import com.guo.learningprogresstracker.dto.MindMapReportContext;
import com.guo.learningprogresstracker.dto.ReportSections;
import jakarta.annotation.PostConstruct;
import lombok.Setter;
@@ -130,19 +132,27 @@ public class AiServiceClient {
/**
* 调用 lpt-ai 从知识碎片生成思维导图大纲。
*
- * @param fragments 该任务名下的知识碎片正文(按内容归属取)
+ * @param fragments 该任务名下的知识碎片正文(按内容归属取),带可空的报告关联
+ * @param reports 碎片同源会话的学习报告,作为参考上下文(报告-02);由 LLM 按相关性决定是否采用
*/
public Optional generateMindMap(String taskName, String taskDescription,
- List fragments) {
+ List fragments,
+ List reports) {
if (!isConfigured()) {
return Optional.empty();
}
try {
- Map params = Map.of(
- "taskName", taskName,
- "taskDescription", taskDescription != null ? taskDescription : "",
- "fragments", fragments != null ? fragments : List.of()
- );
+ List