75 lines
3.1 KiB
Java
75 lines
3.1 KiB
Java
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;
|
|
}
|