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)。 * *

一次引导是一次**复习行为**:它有自己的记录实体(记录上下文与复习耗时都挂在它身上), * 产出的知识碎片走碎片的全部既有逻辑(内容归属、待归类、导图取材、Feed 回收), * 只是额外带一个「来自学习引导」的系统标记。

* *

这条链路**没有降级形态**:它不属于核心闭环,AI 不可用时整体不可用。

*/ 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> historyOf(String guidanceNum) throws NotFindEntitiesException; /** * 按引导编号取会话。 */ ReviewGuidanceConversationEntity getByGuidanceNum(String guidanceNum) throws NotFindEntitiesException; /** * 用户确认产出:把这次引导的收获记成一条知识碎片。 * * * * @return 生成的碎片 */ StudyReportFragmentsEntity confirmFragment(String guidanceNum, String content, ReviewTiming timing) throws ErrorParameterException, NotFindEntitiesException; /** * 放弃这次引导:不产出任何数据,只把会话标记为结束(记录上下文因此不会被碎片引用)。 */ void abandon(String guidanceNum) throws NotFindEntitiesException; }