diff --git a/src/main/java/com/guo/learningprogresstracker/common/TenantContext.java b/src/main/java/com/guo/learningprogresstracker/common/TenantContext.java new file mode 100644 index 0000000..32ba690 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/common/TenantContext.java @@ -0,0 +1,56 @@ +package com.guo.learningprogresstracker.common; + +/** + * 显式的租户上下文(AI-02)。 + * + *

租户拦截器与公共字段自动填充都从 {@code StpUtil} 取当前用户,而它依赖 Web 请求上下文。 + * 后台执行线程(AI 任务执行器、定时收敛)没有请求上下文,直接调用会抛 + * {@code NotWebContextException};这里让后台线程显式声明「我以哪个用户身份在执行」。

+ * + *

取值优先级:本上下文优先,没有时才回落到 {@code StpUtil}。这样请求线程的行为完全不变, + * 后台线程也只能以任务所属用户的身份执行,不会意外变成「无租户」而看到全部数据。

+ */ +public final class TenantContext { + + /** + * 执行身份。 + * + * @param loginId 登录用户 + * @param device 设备类型,可为 null(后台任务通常没有设备信息) + */ + public record Identity(String loginId, String device) { + } + + private static final ThreadLocal CURRENT = new ThreadLocal<>(); + + private TenantContext() { + } + + /** 取当前执行身份;未设置时返回 null(表示应回落到 StpUtil) */ + public static Identity get() { + return CURRENT.get(); + } + + /** 在指定身份下执行;执行结束后恢复原身份,避免线程池复用造成身份串号 */ + public static void runAs(String loginId, String device, Runnable action) { + callAs(loginId, device, () -> { + action.run(); + return null; + }); + } + + /** 在指定身份下执行并返回结果(异常原样向外抛,由调用方决定如何回写) */ + public static T callAs(String loginId, String device, java.util.function.Supplier action) { + Identity previous = CURRENT.get(); + CURRENT.set(new Identity(loginId, device)); + try { + return action.get(); + } finally { + if (previous == null) { + CURRENT.remove(); + } else { + CURRENT.set(previous); + } + } + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/config/AiTaskConfig.java b/src/main/java/com/guo/learningprogresstracker/config/AiTaskConfig.java new file mode 100644 index 0000000..650e4a7 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/config/AiTaskConfig.java @@ -0,0 +1,30 @@ +package com.guo.learningprogresstracker.config; + +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.scheduling.annotation.EnableAsync; +import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor; + +/** + * AI 任务执行器装配(AI-02)。 + *

执行线程与请求线程分离,AI 调用不会占用 HTTP 请求线程,也不会持有请求期间打开的数据库连接。

+ */ +@Configuration +@EnableAsync +public class AiTaskConfig { + + public static final String AI_TASK_EXECUTOR = "aiTaskExecutor"; + + @Bean(name = AI_TASK_EXECUTOR) + public ThreadPoolTaskExecutor aiTaskExecutor(AiTaskProperties properties) { + ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); + executor.setCorePoolSize(properties.getExecutorCoreSize()); + executor.setMaxPoolSize(properties.getExecutorMaxSize()); + executor.setQueueCapacity(properties.getExecutorQueueCapacity()); + executor.setThreadNamePrefix("ai-task-"); + // 队列满时由调用线程执行,避免任务被静默丢弃(定时兜底仍会接手) + executor.setRejectedExecutionHandler(new java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy()); + executor.initialize(); + return executor; + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/config/AiTaskProperties.java b/src/main/java/com/guo/learningprogresstracker/config/AiTaskProperties.java new file mode 100644 index 0000000..3305d94 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/config/AiTaskProperties.java @@ -0,0 +1,33 @@ +package com.guo.learningprogresstracker.config; + +import lombok.Data; +import org.springframework.boot.context.properties.ConfigurationProperties; +import org.springframework.context.annotation.Configuration; + +/** + * AI 异步任务配置(AI-02)。 + */ +@Data +@Configuration +@ConfigurationProperties(prefix = "lpt.ai-task") +public class AiTaskProperties { + + /** 单个任务允许的最长执行时间(秒):超过则视为进程中断,回收后可重试 */ + private long stuckTimeoutSeconds = 900; + + /** 兜底扫描间隔(毫秒) */ + private long scanIntervalMs = 3000; + + /** 首次兜底扫描的延迟(毫秒):让「提交后立即投递」先执行 */ + private long scanInitialDelayMs = 3000; + + /** 单次扫描最多处理多少个任务 */ + private int scanBatchSize = 10; + + /** 立即投递用的线程池大小 */ + private int executorCoreSize = 2; + + private int executorMaxSize = 4; + + private int executorQueueCapacity = 50; +} diff --git a/src/main/java/com/guo/learningprogresstracker/config/AutoTableField.java b/src/main/java/com/guo/learningprogresstracker/config/AutoTableField.java index f8c2848..9d78cef 100644 --- a/src/main/java/com/guo/learningprogresstracker/config/AutoTableField.java +++ b/src/main/java/com/guo/learningprogresstracker/config/AutoTableField.java @@ -2,6 +2,7 @@ package com.guo.learningprogresstracker.config; import cn.dev33.satoken.stp.StpUtil; import com.baomidou.mybatisplus.core.handlers.MetaObjectHandler; +import com.guo.learningprogresstracker.common.TenantContext; import lombok.extern.slf4j.Slf4j; import org.apache.ibatis.reflection.MetaObject; import org.springframework.context.annotation.Configuration; @@ -20,18 +21,35 @@ public class AutoTableField implements MetaObjectHandler { @Override public void insertFill(MetaObject metaObject) { - this.strictInsertFill(metaObject, "createdBy", StpUtil::getLoginIdAsString, String.class); + this.strictInsertFill(metaObject, "createdBy", AutoTableField::currentLoginId, String.class); this.strictInsertFill(metaObject, "createdTime", LocalDateTime::now, LocalDateTime.class); - this.strictInsertFill(metaObject, "lastModifiedBy", StpUtil::getLoginIdAsString, String.class); + this.strictInsertFill(metaObject, "lastModifiedBy", AutoTableField::currentLoginId, String.class); this.strictInsertFill(metaObject, "lastModifiedTime", LocalDateTime::now, LocalDateTime.class); + this.strictInsertFill(metaObject, "deviceInfo", AutoTableField::currentDevice, String.class); } @Override public void updateFill(MetaObject metaObject) { - this.strictInsertFill(metaObject, "lastModifiedBy", StpUtil::getLoginIdAsString, String.class); + this.strictInsertFill(metaObject, "lastModifiedBy", AutoTableField::currentLoginId, String.class); this.strictInsertFill(metaObject, "lastModifiedTime", LocalDateTime::now, LocalDateTime.class); - this.strictInsertFill(metaObject,"deviceInfo",StpUtil::getLoginDevice,String.class); + this.strictInsertFill(metaObject, "deviceInfo", AutoTableField::currentDevice, String.class); + } + + /** + * 当前登录用户:后台执行线程通过 {@link TenantContext} 显式声明身份,请求线程仍走 StpUtil。 + */ + static String currentLoginId() { + TenantContext.Identity identity = TenantContext.get(); + return identity != null ? identity.loginId() : StpUtil.getLoginIdAsString(); + } + + /** + * 当前设备:后台任务通常没有设备信息,返回 null 时跳过该项填充(保持列为空而不是写脏值)。 + */ + static String currentDevice() { + TenantContext.Identity identity = TenantContext.get(); + return identity != null ? identity.device() : StpUtil.getLoginDevice(); } } diff --git a/src/main/java/com/guo/learningprogresstracker/config/MybatisPlusConfig.java b/src/main/java/com/guo/learningprogresstracker/config/MybatisPlusConfig.java index 20f5617..e871e95 100644 --- a/src/main/java/com/guo/learningprogresstracker/config/MybatisPlusConfig.java +++ b/src/main/java/com/guo/learningprogresstracker/config/MybatisPlusConfig.java @@ -1,6 +1,7 @@ package com.guo.learningprogresstracker.config; import cn.dev33.satoken.stp.StpUtil; +import com.guo.learningprogresstracker.common.TenantContext; import net.sf.jsqlparser.expression.StringValue; import com.baomidou.mybatisplus.extension.plugins.MybatisPlusInterceptor; import com.baomidou.mybatisplus.extension.plugins.inner.PaginationInnerInterceptor; @@ -39,7 +40,10 @@ public class MybatisPlusConfig { interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(new TenantLineHandler() { @Override public Expression getTenantId() { - return new StringValue(StpUtil.getLoginIdAsString()); + // 后台执行线程(AI 任务、定时收敛)通过 TenantContext 显式声明身份; + // 请求线程没有设置,仍走 StpUtil,行为完全不变 + TenantContext.Identity identity = TenantContext.get(); + return new StringValue(identity != null ? identity.loginId() : StpUtil.getLoginIdAsString()); } @Override diff --git a/src/main/java/com/guo/learningprogresstracker/controller/AiTaskController.java b/src/main/java/com/guo/learningprogresstracker/controller/AiTaskController.java new file mode 100644 index 0000000..a44c630 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/controller/AiTaskController.java @@ -0,0 +1,56 @@ +package com.guo.learningprogresstracker.controller; + +import com.guo.learningprogresstracker.dto.AiTaskResponse; +import com.guo.learningprogresstracker.dto.request.AiTaskSubmitRequest; +import com.guo.learningprogresstracker.entity.CommonResult; +import com.guo.learningprogresstracker.exception.ErrorParameterException; +import com.guo.learningprogresstracker.exception.NotFindEntitiesException; +import com.guo.learningprogresstracker.service.AiTaskService; +import jakarta.validation.Valid; +import lombok.RequiredArgsConstructor; +import org.springframework.validation.annotation.Validated; +import org.springframework.web.bind.annotation.*; + +/** + * AI 异步任务控制层(AI-02)。 + * + *

提交与查询分离:提交接口秒级返回任务标识,前端随后轮询查询接口拿结果。 + * 这样刷新或离开页面都不会丢结果,AI 已消耗的 token 也不会白费。

+ */ +@RequestMapping("/ai/tasks") +@RestController +@Validated +@RequiredArgsConstructor +public class AiTaskController { + + private final AiTaskService aiTaskService; + + /** + * 提交 AI 任务。 + *

同一目标已有进行中任务时直接返回该任务(AI-04:对外是任务状态,而不是可能为空的实体)。

+ */ + @PostMapping + public CommonResult submit(@Valid @RequestBody AiTaskSubmitRequest request) + throws ErrorParameterException, NotFindEntitiesException { + return CommonResult.success(aiTaskService.submit(request)); + } + + /** + * 查询任务状态与结果;结果可重复获取。 + */ + @GetMapping("/{taskNum}") + public CommonResult getTask(@PathVariable String taskNum) throws NotFindEntitiesException { + return CommonResult.success(aiTaskService.getByTaskNum(taskNum)); + } + + /** + * 查询某目标最近的 AI 任务,用于离开页面再回来时恢复生成状态。 + * + * @return 无任务时 data 为 null + */ + @GetMapping("/latest") + public CommonResult getLatestTask(@RequestParam String type, + @RequestParam String targetNum) { + return CommonResult.success(aiTaskService.findLatest(type, targetNum)); + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/controller/ReviewController.java b/src/main/java/com/guo/learningprogresstracker/controller/ReviewController.java index 994a0c3..fcd7b6d 100644 --- a/src/main/java/com/guo/learningprogresstracker/controller/ReviewController.java +++ b/src/main/java/com/guo/learningprogresstracker/controller/ReviewController.java @@ -2,8 +2,6 @@ package com.guo.learningprogresstracker.controller; import com.guo.learningprogresstracker.dto.ReviewFeedItem; import com.guo.learningprogresstracker.dto.ReviewTaskStats; -import com.guo.learningprogresstracker.dto.ReviewTiming; -import com.guo.learningprogresstracker.dto.request.RecallCompareRequest; import com.guo.learningprogresstracker.dto.request.UpdateStandardMindMapRequest; import com.guo.learningprogresstracker.entity.CommonResult; import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity; @@ -88,26 +86,15 @@ public class ReviewController { // ============ 标准思维导图与回忆对比 ============ /** - * 获取或自动生成任务的标准思维导图 + * 获取任务的标准思维导图。 + * + *

读取不触发生成(AI-02):不存在时 data 为 null,由前端提交 + * {@code POST /ai/tasks}(type=MIND_MAP)后轮询结果。

*/ @GetMapping("/standard-mind-map/{taskNum}") public CommonResult getStandardMindMap( - @PathVariable String taskNum) throws NotFindEntitiesException, OperationFailedException { - return CommonResult.success(standardMindMapService.getOrGenerate(taskNum)); - } - - /** - * 强制重新生成任务的标准思维导图 - * @param mode 生成模式:full(全量覆盖,默认)或 incremental(增量合并) - */ - @PostMapping("/standard-mind-map/{taskNum}/regenerate") - public CommonResult regenerateStandardMindMap( - @PathVariable String taskNum, - @RequestParam(defaultValue = "full") String mode) throws NotFindEntitiesException, OperationFailedException { - if ("incremental".equals(mode)) { - return CommonResult.success(standardMindMapService.incrementalGenerate(taskNum)); - } - return CommonResult.success(standardMindMapService.regenerate(taskNum)); + @PathVariable String taskNum) throws NotFindEntitiesException { + return CommonResult.success(standardMindMapService.getExisting(taskNum)); } /** @@ -120,19 +107,6 @@ public class ReviewController { return CommonResult.success(standardMindMapService.updateByOutline(taskNum, request.getOutline())); } - /** - * 用户提交回忆大纲,与标准导图对比 - */ - @PostMapping("/standard-mind-map/{taskNum}/recall") - public CommonResult recallCompare( - @PathVariable String taskNum, - @Valid @RequestBody RecallCompareRequest request) throws NotFindEntitiesException, OperationFailedException { - return CommonResult.success(standardMindMapService.recallCompare( - taskNum, request.getRecallOutline(), request.getFocusPath(), - new ReviewTiming(request.getReviewStartedAt(), request.getReviewLastInteractionAt(), - request.getReviewDurationSeconds()))); - } - /** * 在标准导图中查找与给定内容最匹配的节点 */ diff --git a/src/main/java/com/guo/learningprogresstracker/controller/StudySessionController.java b/src/main/java/com/guo/learningprogresstracker/controller/StudySessionController.java index 08a465a..f31b256 100644 --- a/src/main/java/com/guo/learningprogresstracker/controller/StudySessionController.java +++ b/src/main/java/com/guo/learningprogresstracker/controller/StudySessionController.java @@ -114,14 +114,6 @@ public class StudySessionController { } - /** - * 生成学习报告草稿:AI 聚合残片(不可用时降级为拼接),返回给前端作为编辑起点 - */ - @GetMapping("/{sessionNum}/report-draft") - public CommonResult getReportDraft(@PathVariable("sessionNum") String sessionNum) throws ErrorParameterException { - return CommonResult.success("请求成功", studySessionsServiceImpl.generateReportDraft(sessionNum)); - } - /** 分页查询任务的残片历史 */ @GetMapping("/tasks/{taskNum}/fragments") public CommonResult> getTaskFragments( diff --git a/src/main/java/com/guo/learningprogresstracker/dto/AiTaskResponse.java b/src/main/java/com/guo/learningprogresstracker/dto/AiTaskResponse.java new file mode 100644 index 0000000..9eef487 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/AiTaskResponse.java @@ -0,0 +1,54 @@ +package com.guo.learningprogresstracker.dto; + +import com.guo.learningprogresstracker.entity.AiTaskEntity; +import io.swagger.v3.oas.annotations.media.Schema; +import lombok.Data; + +import java.time.LocalDateTime; +import java.util.Map; + +/** + * AI 任务对外视图(AI-02)。 + *

提交与查询都返回它:前端只依赖 {@code status} 与 {@code result}, + * 不需要在请求线程里等 AI(也就不会出现「AI 成功了但客户端已超时」)。

+ */ +@Data +public class AiTaskResponse { + + @Schema(description = "AI 任务编号") + private String taskNum; + + @Schema(description = "任务类型:RECALL_COMPARE / MIND_MAP / REPORT_DRAFT") + private String type; + + @Schema(description = "目标编号:学习任务编号或学习会话编号") + private String targetNum; + + @Schema(description = "状态:PENDING / RUNNING / SUCCEEDED / FAILED") + private String status; + + @Schema(description = "失败原因(用户可见文案)") + private String errorMessage; + + @Schema(description = "提交时间") + private LocalDateTime createdTime; + + @Schema(description = "结束时间") + private LocalDateTime finishedTime; + + @Schema(description = "成功结果,随任务类型不同;未完成时为 null") + private Map result; + + public static AiTaskResponse from(AiTaskEntity entity, Map result) { + AiTaskResponse response = new AiTaskResponse(); + response.setTaskNum(entity.getTaskNum()); + response.setType(entity.getAiType()); + response.setTargetNum(entity.getTargetNum()); + response.setStatus(entity.getStatus()); + response.setErrorMessage(entity.getErrorMessage()); + response.setCreatedTime(entity.getCreatedTime()); + response.setFinishedTime(entity.getFinishedTime()); + response.setResult(result); + return response; + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/RecallCompareOutcome.java b/src/main/java/com/guo/learningprogresstracker/dto/RecallCompareOutcome.java new file mode 100644 index 0000000..3911009 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/RecallCompareOutcome.java @@ -0,0 +1,30 @@ +package com.guo.learningprogresstracker.dto; + +/** + * 一次回忆对比的结果(AI-02)。 + * + *

对比在 AI 任务执行器里完成,因此不再把「标准导图实体」直接返回给提交接口; + * 这个结果写进 AI 任务的 {@code result_payload},由前端在轮询到成功后再取详情。

+ * + * @param standardMapId 对比所用的标准导图 ID + * @param recallRecordId 本次生成的回忆记录 ID + * @param recallRatio 覆盖率(0-1) + * @param matchedCount 命中节点数 + * @param missedCount 遗漏节点数 + * @param extraCount 额外节点数 + */ +public record RecallCompareOutcome(Integer standardMapId, Integer recallRecordId, Double recallRatio, + Integer matchedCount, Integer missedCount, Integer extraCount) { + + /** 转成 AI 任务结果载荷 */ + public java.util.Map toPayload() { + java.util.Map payload = new java.util.LinkedHashMap<>(); + payload.put("standardMapId", standardMapId); + payload.put("recallRecordId", recallRecordId); + payload.put("recallRatio", recallRatio); + payload.put("matchedCount", matchedCount); + payload.put("missedCount", missedCount); + payload.put("extraCount", extraCount); + return payload; + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/request/AiTaskSubmitRequest.java b/src/main/java/com/guo/learningprogresstracker/dto/request/AiTaskSubmitRequest.java new file mode 100644 index 0000000..50ffb5a --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/request/AiTaskSubmitRequest.java @@ -0,0 +1,43 @@ +package com.guo.learningprogresstracker.dto.request; + +import jakarta.validation.constraints.NotBlank; +import lombok.Data; + +import java.util.Map; + +/** + * 提交 AI 任务请求(AI-02)。 + */ +@Data +public class AiTaskSubmitRequest { + + @NotBlank(message = "请先指定要处理的类型") + private String type; + + @NotBlank(message = "请先指定要处理的对象") + private String targetNum; + + /** 类型相关的参数;无需参数时可为空 */ + private Map params; + + /** 阅读友好度:null 表示不关心 */ + public String paramAsString(String key) { + Object value = params == null ? null : params.get(key); + return value == null ? null : String.valueOf(value); + } + + public Integer paramAsInteger(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; + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/entity/AiTaskEntity.java b/src/main/java/com/guo/learningprogresstracker/entity/AiTaskEntity.java new file mode 100644 index 0000000..db702c3 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/entity/AiTaskEntity.java @@ -0,0 +1,79 @@ +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.enums.AiTaskStatusEnum; +import com.guo.learningprogresstracker.utils.GenerateNumTool; +import lombok.Data; + +import java.io.Serializable; +import java.time.LocalDateTime; + +/** + * AI 异步任务(AI-02):提交后立即返回任务标识,结果由执行器回写、按标识重复获取。 + */ +@TableName(value = "ai_tasks") +@Data +public class AiTaskEntity extends BaseEntity implements Serializable { + + @TableId(value = "id", type = IdType.AUTO) + private Integer id; + + /** 对外任务标识 */ + @TableField(value = "task_num") + private String taskNum; + + /** 任务类型,取值见 {@code AiTaskTypeEnum} */ + @TableField(value = "ai_type") + private String aiType; + + /** 目标编号:学习任务编号或学习会话编号 */ + @TableField(value = "target_num") + private String targetNum; + + /** 状态,取值见 {@code AiTaskStatusEnum} */ + @TableField(value = "status") + private String status; + + /** 提交时的请求参数 JSON */ + @TableField(value = "request_payload") + private String requestPayload; + + /** 成功结果 JSON */ + @TableField(value = "result_payload") + private String resultPayload; + + /** 失败原因(用户可见文案) */ + @TableField(value = "error_message") + private String errorMessage; + + @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 AiTaskEntity initNewTask(String aiType, String targetNum, String requestPayload) { + AiTaskEntity task = new AiTaskEntity(); + task.setTaskNum(GenerateNumTool.generateNum("AITASK")); + task.setAiType(aiType); + task.setTargetNum(targetNum); + task.setStatus(AiTaskStatusEnum.PENDING.name()); + task.setRequestPayload(requestPayload); + return task; + } + + public boolean isActive() { + return AiTaskStatusEnum.ACTIVE.contains(AiTaskStatusEnum.valueOf(status)); + } + + public boolean isFinished() { + return AiTaskStatusEnum.SUCCEEDED.name().equals(status) + || AiTaskStatusEnum.FAILED.name().equals(status); + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/enums/AiTaskStatusEnum.java b/src/main/java/com/guo/learningprogresstracker/enums/AiTaskStatusEnum.java new file mode 100644 index 0000000..74b98e7 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/enums/AiTaskStatusEnum.java @@ -0,0 +1,36 @@ +package com.guo.learningprogresstracker.enums; + +import lombok.AllArgsConstructor; +import lombok.Getter; + +import java.util.EnumSet; +import java.util.Set; + +/** + * AI 任务状态(AI-02)。 + */ +@Getter +@AllArgsConstructor +public enum AiTaskStatusEnum { + + /** 已提交,等待执行 */ + PENDING("正在准备"), + + /** 执行中 */ + RUNNING("正在生成"), + + /** 已完成,结果可重复获取 */ + SUCCEEDED("已完成"), + + /** 已失败,允许用户重新提交 */ + FAILED("失败了"); + + private final String description; + + /** 进行中的状态集合:用于「生成中」判定与防重复提交 */ + public static final Set ACTIVE = EnumSet.of(PENDING, RUNNING); + + public static Set activeNames() { + return ACTIVE.stream().map(Enum::name).collect(java.util.stream.Collectors.toSet()); + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/enums/AiTaskTypeEnum.java b/src/main/java/com/guo/learningprogresstracker/enums/AiTaskTypeEnum.java new file mode 100644 index 0000000..d79f33f --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/enums/AiTaskTypeEnum.java @@ -0,0 +1,35 @@ +package com.guo.learningprogresstracker.enums; + +import lombok.AllArgsConstructor; +import lombok.Getter; + +/** + * AI 任务类型(AI-02)。 + */ +@Getter +@AllArgsConstructor +public enum AiTaskTypeEnum { + + /** 回忆对比:把用户回忆大纲与标准导图对比 */ + RECALL_COMPARE("回忆对比"), + + /** 标准思维导图生成:全量、增量或按需生成 */ + MIND_MAP("思维导图生成"), + + /** 学习报告草稿聚合 */ + REPORT_DRAFT("学习报告草稿"); + + private final String description; + + /** 宽松解析:默认大小写不敏感,并用该类型的默认用户可见名称兜底 */ + public static AiTaskTypeEnum parse(String value) { + if (value == null || value.isBlank()) { + return null; + } + try { + return valueOf(value.trim().toUpperCase()); + } catch (IllegalArgumentException e) { + return null; + } + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/mapper/AiTaskMapper.java b/src/main/java/com/guo/learningprogresstracker/mapper/AiTaskMapper.java new file mode 100644 index 0000000..3524416 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/mapper/AiTaskMapper.java @@ -0,0 +1,99 @@ +package com.guo.learningprogresstracker.mapper; + +import com.baomidou.mybatisplus.annotation.InterceptorIgnore; +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.guo.learningprogresstracker.entity.AiTaskEntity; +import org.apache.ibatis.annotations.Mapper; +import org.apache.ibatis.annotations.Param; +import org.apache.ibatis.annotations.Select; +import org.apache.ibatis.annotations.Update; + +import java.time.LocalDateTime; +import java.util.List; + +/** + * AI 异步任务 Mapper(AI-02)。 + */ +@Mapper +public interface AiTaskMapper extends BaseMapper { + + /** + * 取待处理任务(执行器用)。 + * + *

执行器在请求之外运行,没有登录态供租户拦截器读取,因此显式忽略租户条件; + * 这是系统级后台处理,与请求路径的租户隔离互不影响。自定义 SQL 不会被 + * {@code @TableLogic} 自动追加条件,所以 {@code deleted = 0} 必须显式写出。

+ */ + @InterceptorIgnore(tenantLine = "true") + @Select(""" + SELECT * + FROM ai_tasks + WHERE deleted = 0 + AND status = 'PENDING' + ORDER BY created_time ASC + LIMIT #{limit} + """) + List selectPendingTasks(@Param("limit") int limit); + + /** + * 按主键取任务(执行器用)。 + * + *

执行器在请求之外运行,此时还不知道任务属于哪个租户,无法让租户拦截器注入条件; + * 因此这里显式忽略租户。读到任务后,执行器会以任务自己的 {@code created_by} 作为租户身份执行, + * 后续所有业务查询仍然受租户隔离约束。

+ */ + @InterceptorIgnore(tenantLine = "true") + @Select("SELECT * FROM ai_tasks WHERE id = #{id} AND deleted = 0") + AiTaskEntity selectTaskById(@Param("id") Integer id); + + /** + * 抢占任务:只有仍处于 PENDING 的任务才会被置为 RUNNING,保证多副本/多线程下不重复执行。 + * + * @return 受影响行数,0 表示已被其他执行者抢走 + */ + @InterceptorIgnore(tenantLine = "true") + @Update(""" + UPDATE ai_tasks + SET status = 'RUNNING', + started_time = #{startedTime}, + last_modified_time = #{startedTime} + WHERE id = #{id} + AND status = 'PENDING' + AND deleted = 0 + """) + int claimTask(@Param("id") Integer id, @Param("startedTime") LocalDateTime startedTime); + + /** + * 回收超时未回写的任务(执行器崩溃或进程被杀时,任务会永远停在 RUNNING)。 + * 置回 PENDING 让执行器重试;同时清掉开始时间,便于重新计时。 + */ + @InterceptorIgnore(tenantLine = "true") + @Update(""" + UPDATE ai_tasks + SET status = 'PENDING', + started_time = NULL, + last_modified_time = #{now} + WHERE status = 'RUNNING' + AND deleted = 0 + AND started_time IS NOT NULL + AND started_time <= #{cutoff} + """) + int reclaimStuckTasks(@Param("cutoff") LocalDateTime cutoff, @Param("now") LocalDateTime now); + + /** + * 回写结果:只有仍处于 RUNNING 的任务才会被写入,避免超时回收后与新执行者互相覆盖。 + */ + @InterceptorIgnore(tenantLine = "true") + @Update(""" + UPDATE ai_tasks + SET status = #{status}, + result_payload = #{resultPayload}, + error_message = #{errorMessage}, + finished_time = #{finishedTime}, + last_modified_time = #{finishedTime} + WHERE id = #{id} + AND status = 'RUNNING' + AND deleted = 0 + """) + int finishTask(AiTaskEntity task); +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/AiTaskService.java b/src/main/java/com/guo/learningprogresstracker/service/AiTaskService.java new file mode 100644 index 0000000..8597e2d --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/AiTaskService.java @@ -0,0 +1,68 @@ +package com.guo.learningprogresstracker.service; + +import com.guo.learningprogresstracker.dto.AiTaskResponse; +import com.guo.learningprogresstracker.dto.request.AiTaskSubmitRequest; +import com.guo.learningprogresstracker.entity.AiTaskEntity; +import com.guo.learningprogresstracker.exception.ErrorParameterException; +import com.guo.learningprogresstracker.exception.NotFindEntitiesException; + +import java.util.List; +import java.util.Map; + +/** + * AI 异步任务服务(AI-02)。 + * + *

提交与执行分离:提交只落一条 PENDING 记录并立刻返回任务标识;执行由请求线程之外 + * 的执行器完成。因此接口不再随 AI 耗时增长,刷新页面也不会丢失结果。

+ */ +public interface AiTaskService { + + /** + * 提交 AI 任务。 + * + *

同一用户 + 同一类型 + 同一目标若已有进行中任务,直接复用(AI-04 的「生成中」语义: + * 返回任务状态而不是可能为空的实体),不会重复触发生成。

+ */ + AiTaskResponse submit(AiTaskSubmitRequest request) throws ErrorParameterException, NotFindEntitiesException; + + /** + * 按任务标识查询任务状态与结果;结果可重复获取。 + */ + AiTaskResponse getByTaskNum(String taskNum) throws NotFindEntitiesException; + + /** + * 查询某目标最近的 AI 任务(用于离开页面再回来时恢复生成状态)。 + * + * @return 无任务时返回 null + */ + AiTaskResponse findLatest(String type, String targetNum); + + /** + * 取出并抢占待处理任务(执行器入口);没有可执行任务时返回空列表。 + */ + List claimPendingTasks(int limit); + + /** + * 抢占指定任务(提交后立即投递的入口)。 + * + * @return 抢占成功返回任务;已被其他执行者抢走或状态不允许时返回空 + */ + java.util.Optional claimTask(Integer id); + + /** + * 回写成功结果。 + */ + void markSucceeded(AiTaskEntity task, Map result); + + /** + * 回写失败结果(只记用户可见文案,技术细节由调用方写日志)。 + */ + void markFailed(AiTaskEntity task, String message); + + /** + * 回收因进程中断而卡在 RUNNING 的任务,使其可被重新执行。 + * + * @return 被回收的任务数 + */ + int reclaimStuckTasks(); +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/StandardMindMapService.java b/src/main/java/com/guo/learningprogresstracker/service/StandardMindMapService.java index 082cbaf..2e709cd 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/StandardMindMapService.java +++ b/src/main/java/com/guo/learningprogresstracker/service/StandardMindMapService.java @@ -1,5 +1,6 @@ package com.guo.learningprogresstracker.service; +import com.guo.learningprogresstracker.dto.RecallCompareOutcome; import com.guo.learningprogresstracker.dto.ReviewTiming; import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity; import com.guo.learningprogresstracker.entity.ReviewStandardMindMapEntity; @@ -16,9 +17,11 @@ import java.util.Map; public interface StandardMindMapService { /** - * 获取指定任务的标准思维导图,不存在时自动生成。 + * 获取指定任务已有的标准思维导图;不存在时返回 null。 + * + *

不在读取路径上触发生成:生成可能耗时数分钟(AI-02),应由 AI 任务异步完成。

*/ - ReviewStandardMindMapEntity getOrGenerate(String taskNum) throws NotFindEntitiesException, OperationFailedException; + ReviewStandardMindMapEntity getExisting(String taskNum) throws NotFindEntitiesException; /** * 强制重新生成指定任务的标准思维导图。 @@ -36,14 +39,16 @@ public interface StandardMindMapService { ReviewStandardMindMapEntity updateByOutline(String taskNum, String outline) throws NotFindEntitiesException; /** - * 用户提交回忆大纲,与标准导图对比并返回结果。 + * 用户提交回忆大纲,与标准导图对比。 + * + *

由 AI 任务执行器在请求线程之外调用;方法本身不持有事务,避免等待 AI 时占用数据库连接。

* * @param recallOutline 用户回忆的缩进大纲文本 * @param focusPath 可选:标准导图中的节点路径(/ 分隔),指定后仅对比该子树 * @param timing 可选:本次复习行为的计时信息(复习-07),为空时不计复习耗时 */ - ReviewStandardMindMapEntity recallCompare(String taskNum, String recallOutline, String focusPath, - ReviewTiming timing) throws NotFindEntitiesException, OperationFailedException; + RecallCompareOutcome recallCompare(String taskNum, String recallOutline, String focusPath, + ReviewTiming timing) throws NotFindEntitiesException, OperationFailedException; /** * 根据内容文本在标准导图中查找最匹配的节点,返回节点路径。 diff --git a/src/main/java/com/guo/learningprogresstracker/service/StudySessionsService.java b/src/main/java/com/guo/learningprogresstracker/service/StudySessionsService.java index 796414e..37b64a3 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/StudySessionsService.java +++ b/src/main/java/com/guo/learningprogresstracker/service/StudySessionsService.java @@ -41,6 +41,13 @@ public interface StudySessionsService extends IService { StudySessionResponse getActiveSession(String excludeTaskNum); + /** + * 生成学习报告草稿(AI 聚合残片,不可用时降级为按序拼接)。 + * + *

由 AI 任务执行器调用,不在请求线程内执行(AI-02)。

+ */ + String buildReportDraft(String sessionNum) throws ErrorParameterException; + /** * 惰性收敛(会话-04):把当前用户悬挂的进行中会话按硬兜底阈值强制暂停。 *

由读取路径调用(活跃会话、任务未结束会话),用户不访问时由定时扫描兜底。

diff --git a/src/main/java/com/guo/learningprogresstracker/service/event/AiTaskSubmittedEvent.java b/src/main/java/com/guo/learningprogresstracker/service/event/AiTaskSubmittedEvent.java new file mode 100644 index 0000000..a90f466 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/event/AiTaskSubmittedEvent.java @@ -0,0 +1,12 @@ +package com.guo.learningprogresstracker.service.event; + +/** + * AI 任务已提交事件(AI-02)。 + * + *

提交与执行解耦:提交方只负责落库并发出事件,执行由异步监听器在请求线程之外完成, + * 这样 {@code AiTaskService} 不必反过来依赖执行器,也不会形成循环依赖。

+ * + * @param taskId 任务主键 + */ +public record AiTaskSubmittedEvent(Integer taskId) { +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskFailedException.java b/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskFailedException.java new file mode 100644 index 0000000..a552ad9 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskFailedException.java @@ -0,0 +1,15 @@ +package com.guo.learningprogresstracker.service.impl; + +/** + * AI 任务执行失败(AI-02):{@code message} 是给用户看的文案,技术细节由抛出方写日志。 + */ +public class AiTaskFailedException extends RuntimeException { + + public AiTaskFailedException(String message) { + super(message); + } + + public AiTaskFailedException(String message, Throwable cause) { + super(message, cause); + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskHandler.java b/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskHandler.java new file mode 100644 index 0000000..84e0ab4 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskHandler.java @@ -0,0 +1,28 @@ +package com.guo.learningprogresstracker.service.impl; + +import com.guo.learningprogresstracker.entity.AiTaskEntity; +import com.guo.learningprogresstracker.enums.AiTaskTypeEnum; + +import java.util.Map; + +/** + * 一类 AI 任务的具体执行逻辑(AI-02)。 + * + *

实现类在请求线程之外被调用,因此可以放心地同步等待 AI;但不要在实现里开启长事务, + * 否则会把「等待 AI 时不占用数据库连接」这条约束重新破坏掉。

+ */ +public interface AiTaskHandler { + + /** 该实现负责的任务类型 */ + AiTaskTypeEnum type(); + + /** + * 执行任务。 + * + * @param task 任务实体(status 已是 RUNNING) + * @param params 提交时的参数(可能为空 Map) + * @return 写回 result_payload 的结果 + * @throws AiTaskFailedException 业务上可预期的失败,消息会展示给用户 + */ + Map execute(AiTaskEntity task, Map params); +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskHandlerRegistry.java b/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskHandlerRegistry.java new file mode 100644 index 0000000..274b7b7 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskHandlerRegistry.java @@ -0,0 +1,65 @@ +package com.guo.learningprogresstracker.service.impl; + +import com.fasterxml.jackson.core.type.TypeReference; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.guo.learningprogresstracker.entity.AiTaskEntity; +import com.guo.learningprogresstracker.enums.AiTaskTypeEnum; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Component; +import org.springframework.util.StringUtils; + +import java.util.EnumMap; +import java.util.List; +import java.util.Map; + +/** + * AI 任务处理器注册表(AI-02):按类型分发到具体实现。 + */ +@Slf4j +@Component +public class AiTaskHandlerRegistry { + + private final Map handlers = new EnumMap<>(AiTaskTypeEnum.class); + + private final ObjectMapper objectMapper; + + public AiTaskHandlerRegistry(List handlerList, ObjectMapper objectMapper) { + this.objectMapper = objectMapper; + for (AiTaskHandler handler : handlerList) { + AiTaskHandler previous = handlers.put(handler.type(), handler); + if (previous != null) { + log.warn("AI 任务类型 {} 有多个处理器,后注册的 {} 覆盖了 {}", + handler.type(), handler.getClass().getSimpleName(), previous.getClass().getSimpleName()); + } + } + log.info("AI 任务处理器已注册: {}", handlers.keySet()); + } + + /** + * 执行任务。 + * + * @throws AiTaskFailedException 类型无处理器或参数解析失败 + */ + public Map execute(AiTaskEntity task) { + AiTaskTypeEnum type = AiTaskTypeEnum.parse(task.getAiType()); + AiTaskHandler handler = type == null ? null : handlers.get(type); + if (handler == null) { + log.error("AI 任务类型[{}]没有对应的处理器", task.getAiType()); + throw new AiTaskFailedException("这个功能暂时不可用,请稍后再试"); + } + return handler.execute(task, parseParams(task)); + } + + private Map parseParams(AiTaskEntity task) { + if (!StringUtils.hasText(task.getRequestPayload())) { + return Map.of(); + } + try { + return objectMapper.readValue(task.getRequestPayload(), new TypeReference>() { + }); + } catch (Exception e) { + log.error("AI 任务[{}]参数解析失败", task.getTaskNum(), e); + throw new AiTaskFailedException("这次请求的参数丢了,请重新发起"); + } + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskRunner.java b/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskRunner.java new file mode 100644 index 0000000..5483f6a --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskRunner.java @@ -0,0 +1,95 @@ +package com.guo.learningprogresstracker.service.impl; + +import com.guo.learningprogresstracker.config.AiTaskConfig; +import com.guo.learningprogresstracker.config.AiTaskProperties; +import com.guo.learningprogresstracker.common.TenantContext; +import com.guo.learningprogresstracker.entity.AiTaskEntity; +import com.guo.learningprogresstracker.service.AiTaskService; +import com.guo.learningprogresstracker.service.event.AiTaskSubmittedEvent; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.context.event.EventListener; +import org.springframework.scheduling.annotation.Async; +import org.springframework.scheduling.annotation.Scheduled; +import org.springframework.stereotype.Component; +import org.springframework.transaction.event.TransactionPhase; +import org.springframework.transaction.event.TransactionalEventListener; + +import java.util.List; +import java.util.Map; + +/** + * AI 任务执行器(AI-02)。 + * + *

两条触发路径共用同一套「条件更新抢占」,因此不会重复执行:

+ *
    + *
  • 提交后立即投递:让「无需 AI 的降级路径」也能秒级完成,用户不必等一个扫描周期;
  • + *
  • 定时兜底扫描:进程重启、投递失败或事件丢失时接手待处理任务。
  • + *
+ */ +@Slf4j +@Component +@RequiredArgsConstructor +public class AiTaskRunner { + + private final AiTaskService aiTaskService; + private final AiTaskHandlerRegistry handlerRegistry; + private final AiTaskProperties properties; + + /** + * 提交后立即执行。事务提交后才触发,保证执行线程能读到刚插入的任务行; + * 无事务时(单条 insert 自动提交)由 {@code fallbackExecution} 直接执行。 + */ + @Async(AiTaskConfig.AI_TASK_EXECUTOR) + @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT, fallbackExecution = true) + public void onTaskSubmitted(AiTaskSubmittedEvent event) { + try { + aiTaskService.claimTask(event.taskId()).ifPresent(this::executeClaimed); + } catch (Exception e) { + // 不向外抛:定时扫描会重新接手这个任务 + log.error("[AI 任务] 立即执行失败,等待定时扫描接手: taskId={}", event.taskId(), e); + } + } + + /** + * 定时兜底扫描。异常只记录不抛出,避免一次失败导致调度停止。 + * + *

{@code initialDelayString} 让「立即投递」先跑:生产上延迟一个扫描周期即可, + * 测试环境把它调大,保证自动扫描不会与用例互相干扰(用例直接调本方法)。

+ */ + @Scheduled(fixedDelayString = "${lpt.ai-task.scan-interval-ms:3000}", + initialDelayString = "${lpt.ai-task.scan-initial-delay-ms:3000}") + public void scanPendingTasks() { + try { + List tasks = aiTaskService.claimPendingTasks(properties.getScanBatchSize()); + for (AiTaskEntity task : tasks) { + executeClaimed(task); + } + } catch (Exception e) { + log.error("[AI 任务] 定时扫描失败", e); + } + } + + /** + * 执行已抢占的任务并回写结果。 + * + *

执行线程没有 Web 上下文,租户拦截器与公共字段自动填充都取不到当前用户, + * 因此这里显式以任务所属用户的身份执行;后续业务查询与写入仍然受租户隔离约束。

+ */ + private void executeClaimed(AiTaskEntity task) { + try { + Map result = TenantContext.callAs(task.getCreatedBy(), task.getDeviceInfo(), + () -> handlerRegistry.execute(task)); + aiTaskService.markSucceeded(task, result); + log.info("[AI 任务] 完成: taskNum={}, type={}, targetNum={}", + task.getTaskNum(), task.getAiType(), task.getTargetNum()); + } catch (AiTaskFailedException e) { + log.warn("[AI 任务] 失败: taskNum={}, type={}, 原因={}", + task.getTaskNum(), task.getAiType(), e.getMessage()); + aiTaskService.markFailed(task, e.getMessage()); + } catch (Exception e) { + log.error("[AI 任务] 异常: taskNum={}, type={}", task.getTaskNum(), task.getAiType(), e); + aiTaskService.markFailed(task, "生成失败了,请稍后再试"); + } + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskServiceImpl.java b/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskServiceImpl.java new file mode 100644 index 0000000..f2d8e5a --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/AiTaskServiceImpl.java @@ -0,0 +1,217 @@ +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.config.AiTaskProperties; +import com.guo.learningprogresstracker.dto.AiTaskResponse; +import com.guo.learningprogresstracker.dto.request.AiTaskSubmitRequest; +import com.guo.learningprogresstracker.entity.AiTaskEntity; +import com.guo.learningprogresstracker.enums.AiTaskStatusEnum; +import com.guo.learningprogresstracker.enums.AiTaskTypeEnum; +import com.guo.learningprogresstracker.exception.ErrorParameterException; +import com.guo.learningprogresstracker.exception.NotFindEntitiesException; +import com.guo.learningprogresstracker.mapper.AiTaskMapper; +import com.guo.learningprogresstracker.service.AiTaskService; +import com.guo.learningprogresstracker.service.event.AiTaskSubmittedEvent; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.context.ApplicationEventPublisher; +import org.springframework.stereotype.Service; +import org.springframework.util.StringUtils; + +import java.time.LocalDateTime; +import java.util.ArrayList; +import java.util.Collections; +import java.util.List; +import java.util.Map; +import java.util.Optional; + +/** + * AI 异步任务服务实现(AI-02)。 + */ +@Slf4j +@Service +@RequiredArgsConstructor +public class AiTaskServiceImpl implements AiTaskService { + + private final AiTaskMapper aiTaskMapper; + private final ObjectMapper objectMapper; + private final AiTaskProperties properties; + private final ApplicationEventPublisher eventPublisher; + + @Override + public AiTaskResponse submit(AiTaskSubmitRequest request) + throws ErrorParameterException, NotFindEntitiesException { + AiTaskTypeEnum type = AiTaskTypeEnum.parse(request.getType()); + if (type == null) { + log.warn("不支持的 AI 任务类型: {}", request.getType()); + throw new ErrorParameterException("这个功能暂时不可用,请稍后再试"); + } + if (!StringUtils.hasText(request.getTargetNum())) { + throw new ErrorParameterException("请先指定要处理的对象"); + } + + String targetNum = request.getTargetNum().trim(); + + // AI-04:同一目标已有进行中任务时复用,不重复触发生成 + Optional active = findActiveTask(type, targetNum); + if (active.isPresent()) { + log.info("AI 任务复用进行中的任务: type={}, targetNum={}, taskNum={}", + type, targetNum, active.get().getTaskNum()); + return toResponse(active.get()); + } + + AiTaskEntity task = AiTaskEntity.initNewTask(type.name(), targetNum, writeJson(request.getParams())); + aiTaskMapper.insert(task); + log.info("AI 任务已提交: type={}, targetNum={}, taskNum={}", type, targetNum, task.getTaskNum()); + + // 立即投递执行(事件在事务提交后触发);投递失败也不影响正确性,定时兜底会接手 + eventPublisher.publishEvent(new AiTaskSubmittedEvent(task.getId())); + + return toResponse(task); + } + + @Override + public AiTaskResponse getByTaskNum(String taskNum) throws NotFindEntitiesException { + AiTaskEntity task = aiTaskMapper.selectOne(Wrappers.lambdaQuery() + .eq(AiTaskEntity::getTaskNum, taskNum) + .last("LIMIT 1")); + if (task == null) { + log.warn("AI 任务[{}]不存在", taskNum); + throw new NotFindEntitiesException("这个任务不存在或已被清理,请重新发起"); + } + return toResponse(task); + } + + @Override + public AiTaskResponse findLatest(String type, String targetNum) { + AiTaskTypeEnum taskType = AiTaskTypeEnum.parse(type); + if (taskType == null || !StringUtils.hasText(targetNum)) { + return null; + } + AiTaskEntity task = aiTaskMapper.selectOne(Wrappers.lambdaQuery() + .eq(AiTaskEntity::getAiType, taskType.name()) + .eq(AiTaskEntity::getTargetNum, targetNum.trim()) + .orderByDesc(AiTaskEntity::getCreatedTime) + .last("LIMIT 1")); + return task == null ? null : toResponse(task); + } + + @Override + public List claimPendingTasks(int limit) { + reclaimStuckTasks(); + + List pending = aiTaskMapper.selectPendingTasks(limit); + if (pending.isEmpty()) { + return Collections.emptyList(); + } + + List claimed = new ArrayList<>(); + for (AiTaskEntity task : pending) { + claimTask(task.getId()).ifPresent(claimed::add); + } + return claimed; + } + + @Override + public Optional claimTask(Integer id) { + if (id == null) { + return Optional.empty(); + } + // 抢占阶段还不知道租户,必须走忽略租户的读取(见 AiTaskMapper) + AiTaskEntity task = aiTaskMapper.selectTaskById(id); + if (task == null || !AiTaskStatusEnum.PENDING.name().equals(task.getStatus())) { + return Optional.empty(); + } + LocalDateTime now = LocalDateTime.now(); + // 条件更新抢占:多副本 / 立即投递与定时扫描并发时都只有一个执行者成功 + if (aiTaskMapper.claimTask(id, now) == 0) { + return Optional.empty(); + } + task.setStatus(AiTaskStatusEnum.RUNNING.name()); + task.setStartedTime(now); + return Optional.of(task); + } + + @Override + public void markSucceeded(AiTaskEntity task, Map result) { + task.setStatus(AiTaskStatusEnum.SUCCEEDED.name()); + task.setResultPayload(writeJson(result)); + task.setErrorMessage(null); + task.setFinishedTime(LocalDateTime.now()); + if (aiTaskMapper.finishTask(task) == 0) { + log.warn("AI 任务[{}]结果回写时已被回收或结束,本次结果丢弃", task.getTaskNum()); + } + } + + @Override + public void markFailed(AiTaskEntity task, String message) { + task.setStatus(AiTaskStatusEnum.FAILED.name()); + task.setResultPayload(null); + task.setErrorMessage(abbreviate(message)); + task.setFinishedTime(LocalDateTime.now()); + if (aiTaskMapper.finishTask(task) == 0) { + log.warn("AI 任务[{}]失败状态回写时已被回收或结束", task.getTaskNum()); + } + } + + @Override + public int reclaimStuckTasks() { + LocalDateTime now = LocalDateTime.now(); + LocalDateTime cutoff = now.minusSeconds(properties.getStuckTimeoutSeconds()); + int reclaimed = aiTaskMapper.reclaimStuckTasks(cutoff, now); + if (reclaimed > 0) { + log.warn("[AI 任务] 回收了 {} 个卡在执行中的任务(可能因进程中断)", reclaimed); + } + return reclaimed; + } + + /** 进行中任务:PENDING 或 RUNNING */ + private Optional findActiveTask(AiTaskTypeEnum type, String targetNum) { + return Optional.ofNullable(aiTaskMapper.selectOne(Wrappers.lambdaQuery() + .eq(AiTaskEntity::getAiType, type.name()) + .eq(AiTaskEntity::getTargetNum, targetNum) + .in(AiTaskEntity::getStatus, AiTaskStatusEnum.activeNames()) + .orderByDesc(AiTaskEntity::getCreatedTime) + .last("LIMIT 1"))); + } + + private AiTaskResponse toResponse(AiTaskEntity task) { + return AiTaskResponse.from(task, readResult(task)); + } + + /** 未完成的任务不返回结果,避免前端拿到半成品 */ + private Map readResult(AiTaskEntity task) { + if (!AiTaskStatusEnum.SUCCEEDED.name().equals(task.getStatus()) + || !StringUtils.hasText(task.getResultPayload())) { + return null; + } + try { + return objectMapper.readValue(task.getResultPayload(), new TypeReference>() { + }); + } catch (Exception e) { + log.error("AI 任务[{}]结果解析失败", task.getTaskNum(), e); + return null; + } + } + + private String writeJson(Map payload) { + if (payload == null || payload.isEmpty()) { + return null; + } + try { + return objectMapper.writeValueAsString(payload); + } catch (Exception e) { + log.warn("AI 任务参数序列化失败: {}", e.getMessage()); + return null; + } + } + + private String abbreviate(String message) { + if (message == null) { + return "生成失败,请稍后再试"; + } + return message.length() > 500 ? message.substring(0, 500) : message; + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/MindMapAiTaskHandler.java b/src/main/java/com/guo/learningprogresstracker/service/impl/MindMapAiTaskHandler.java new file mode 100644 index 0000000..3366efe --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/MindMapAiTaskHandler.java @@ -0,0 +1,72 @@ +package com.guo.learningprogresstracker.service.impl; + +import com.guo.learningprogresstracker.entity.AiTaskEntity; +import com.guo.learningprogresstracker.entity.ReviewStandardMindMapEntity; +import com.guo.learningprogresstracker.enums.AiTaskTypeEnum; +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; + +import java.util.LinkedHashMap; +import java.util.Map; + +/** + * 标准思维导图生成任务(AI-02)。 + * + *

支持三种模式:{@code full}(全量重新生成)、{@code incremental}(增量合并保留用户编辑)、 + * {@code ensure}(仅在缺失时生成,用于读取页面按需触发)。

+ */ +@Slf4j +@Component +@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; + + @Override + public AiTaskTypeEnum type() { + return AiTaskTypeEnum.MIND_MAP; + } + + @Override + public Map execute(AiTaskEntity task, Map params) { + String mode = params.get("mode") == null ? "full" : String.valueOf(params.get("mode")); + String taskNum = task.getTargetNum(); + + try { + // ensure 模式下已有导图就直接返回,不做无意义的重新生成(也不重复计费) + if (MODE_ENSURE.equalsIgnoreCase(mode)) { + ReviewStandardMindMapEntity existing = standardMindMapService.getExisting(taskNum); + if (existing != null) { + return toPayload(existing, "已存在,跳过生成"); + } + return toPayload(standardMindMapService.regenerate(taskNum), "按需生成"); + } + if (MODE_INCREMENTAL.equalsIgnoreCase(mode)) { + return toPayload(standardMindMapService.incrementalGenerate(taskNum), "增量更新"); + } + return toPayload(standardMindMapService.regenerate(taskNum), "全量生成"); + } catch (NotFindEntitiesException | OperationFailedException e) { + throw new AiTaskFailedException(e.getMessage()); + } + } + + private Map toPayload(ReviewStandardMindMapEntity entity, String summary) { + Map payload = new LinkedHashMap<>(); + payload.put("standardMapId", entity.getId()); + payload.put("generator", entity.getGenerator()); + payload.put("nodeCount", MindMapTreeTool.countNodes( + MindMapTreeTool.fromJson(entity.getContent(), objectMapper))); + payload.put("summary", summary); + return payload; + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/RecallCompareAiTaskHandler.java b/src/main/java/com/guo/learningprogresstracker/service/impl/RecallCompareAiTaskHandler.java new file mode 100644 index 0000000..45184c8 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/RecallCompareAiTaskHandler.java @@ -0,0 +1,93 @@ +package com.guo.learningprogresstracker.service.impl; + +import com.guo.learningprogresstracker.dto.RecallCompareOutcome; +import com.guo.learningprogresstracker.dto.ReviewTiming; +import com.guo.learningprogresstracker.entity.AiTaskEntity; +import com.guo.learningprogresstracker.enums.AiTaskTypeEnum; +import com.guo.learningprogresstracker.exception.NotFindEntitiesException; +import com.guo.learningprogresstracker.exception.OperationFailedException; +import com.guo.learningprogresstracker.service.StandardMindMapService; +import lombok.RequiredArgsConstructor; +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; + +/** + * 回忆对比任务(AI-02):把用户回忆大纲与标准导图对比并落回忆记录。 + * + *

这条链路原先在 {@code @Transactional} 里同步等待 AI 最长 10 分钟,会占满数据库连接池; + * 现在跑在 AI 任务执行器里,等待期间不持有任何请求期事务。

+ */ +@Slf4j +@Component +@RequiredArgsConstructor +public class RecallCompareAiTaskHandler implements AiTaskHandler { + + private final StandardMindMapService standardMindMapService; + + @Override + public AiTaskTypeEnum type() { + return AiTaskTypeEnum.RECALL_COMPARE; + } + + @Override + public Map execute(AiTaskEntity task, Map params) { + String recallOutline = asString(params, "recallOutline"); + if (!StringUtils.hasText(recallOutline)) { + throw new AiTaskFailedException("请先填写回忆大纲"); + } + String focusPath = asString(params, "focusPath"); + ReviewTiming timing = new ReviewTiming( + asTime(params, "reviewStartedAt"), + asTime(params, "reviewLastInteractionAt"), + asInteger(params, "reviewDurationSeconds")); + + try { + RecallCompareOutcome outcome = standardMindMapService.recallCompare( + task.getTargetNum(), recallOutline, focusPath, timing); + return outcome.toPayload(); + } catch (NotFindEntitiesException e) { + throw new AiTaskFailedException(e.getMessage()); + } catch (OperationFailedException e) { + throw new AiTaskFailedException(e.getMessage()); + } + } + + private static String asString(Map params, String key) { + Object value = params.get(key); + return value == null ? null : String.valueOf(value); + } + + private static Integer asInteger(Map 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 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; + } + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/ReportDraftAiTaskHandler.java b/src/main/java/com/guo/learningprogresstracker/service/impl/ReportDraftAiTaskHandler.java new file mode 100644 index 0000000..af0fd06 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/ReportDraftAiTaskHandler.java @@ -0,0 +1,43 @@ +package com.guo.learningprogresstracker.service.impl; + +import com.guo.learningprogresstracker.entity.AiTaskEntity; +import com.guo.learningprogresstracker.enums.AiTaskTypeEnum; +import com.guo.learningprogresstracker.exception.ErrorParameterException; +import com.guo.learningprogresstracker.service.StudySessionsService; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Component; + +import java.util.LinkedHashMap; +import java.util.Map; + +/** + * 学习报告草稿任务(AI-02)。 + * + *

报告草稿原先由 {@code GET /study-sessions/{sessionNum}/report-draft} 同步触发聚合, + * 一个 GET 就可能阻塞 10 分钟并按 AI 计费;现在改为异步任务,读取接口不再产生副作用。

+ */ +@Slf4j +@Component +@RequiredArgsConstructor +public class ReportDraftAiTaskHandler implements AiTaskHandler { + + private final StudySessionsService studySessionsService; + + @Override + public AiTaskTypeEnum type() { + return AiTaskTypeEnum.REPORT_DRAFT; + } + + @Override + public Map execute(AiTaskEntity task, Map params) { + try { + String draft = studySessionsService.buildReportDraft(task.getTargetNum()); + Map payload = new LinkedHashMap<>(); + payload.put("draft", draft); + return payload; + } catch (ErrorParameterException e) { + throw new AiTaskFailedException(e.getMessage()); + } + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImpl.java b/src/main/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImpl.java index 02a06ea..bb95893 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImpl.java +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImpl.java @@ -3,6 +3,7 @@ package com.guo.learningprogresstracker.service.impl; import com.baomidou.mybatisplus.core.toolkit.Wrappers; import com.fasterxml.jackson.databind.JsonNode; import com.fasterxml.jackson.databind.ObjectMapper; +import com.guo.learningprogresstracker.dto.RecallCompareOutcome; import com.guo.learningprogresstracker.dto.ReviewTiming; import com.guo.learningprogresstracker.entity.*; import com.guo.learningprogresstracker.exception.NotFindEntitiesException; @@ -22,8 +23,6 @@ import org.springframework.util.StringUtils; import java.time.LocalDateTime; import java.util.*; -import java.util.concurrent.ConcurrentHashMap; -import java.util.concurrent.atomic.AtomicBoolean; import java.util.stream.Collectors; /** @@ -51,38 +50,22 @@ public class StandardMindMapServiceImpl implements StandardMindMapService { private static final String MATCH_STATUS_MATCHED = "MATCHED"; private static final String MATCH_STATUS_MISSED = "MISSED"; - /** 防并发生成:taskNum → 是否正在生成中 */ - private final ConcurrentHashMap generatingTasks = new ConcurrentHashMap<>(); - // ============ 查询与生成 ============ @Override - public ReviewStandardMindMapEntity getOrGenerate(String taskNum) throws NotFindEntitiesException, OperationFailedException { + public ReviewStandardMindMapEntity getExisting(String taskNum) throws NotFindEntitiesException { ensureTaskExists(taskNum); - ReviewStandardMindMapEntity existing = queryByTaskNum(taskNum); - return existing != null ? existing : doGenerate(taskNum); + return queryByTaskNum(taskNum); } @Override public ReviewStandardMindMapEntity regenerate(String taskNum) throws NotFindEntitiesException, OperationFailedException { ensureTaskExists(taskNum); - // 防并发生成:同一任务正在生成时直接返回当前实体 - AtomicBoolean lock = generatingTasks.computeIfAbsent(taskNum, k -> new AtomicBoolean(false)); - if (!lock.compareAndSet(false, true)) { - ReviewStandardMindMapEntity existing = queryByTaskNum(taskNum); - log.warn("任务[{}]正在生成中,跳过重复请求", taskNum); - return existing; - } - try { - return doGenerate(taskNum); - } finally { - lock.set(false); - generatingTasks.remove(taskNum); - } + // 并发生成由 ai_tasks 的进行中任务判定拦截(AI-04),不再依赖 JVM 内存锁 + return doGenerate(taskNum); } @Override - @Transactional public ReviewStandardMindMapEntity incrementalGenerate(String taskNum) throws NotFindEntitiesException, OperationFailedException { ensureTaskExists(taskNum); ReviewStandardMindMapEntity existing = queryByTaskNum(taskNum); @@ -90,34 +73,24 @@ public class StandardMindMapServiceImpl implements StandardMindMapService { log.warn("任务[{}]标准思维导图尚不存在,无法增量更新", taskNum); throw new NotFindEntitiesException("还没有生成过标准思维导图,请先完整生成一次哦"); } - // 防并发生成 - AtomicBoolean lock = generatingTasks.computeIfAbsent(taskNum, k -> new AtomicBoolean(false)); - if (!lock.compareAndSet(false, true)) { - log.warn("任务[{}]正在生成中,跳过重复增量请求", taskNum); - return existing; - } - try { - ReviewStandardMindMapEntity fresh = doGenerate(taskNum); - // 合并新旧树:保留用户编辑过的节点,追加新节点 - MindMapNode oldRoot = MindMapTreeTool.fromJson(existing.getContent(), objectMapper); - MindMapNode newRoot = MindMapTreeTool.fromJson(fresh.getContent(), objectMapper); - MindMapNode merged = MindMapTreeTool.mergeTrees(oldRoot, newRoot); - String mergedJson = MindMapTreeTool.toJson(merged, objectMapper); - String mergedOutline = MindMapTreeTool.toFullOutline(merged); - existing.setContent(mergedJson); - existing.setOutline(mergedOutline); - existing.setTitle(merged.getTitle() != null ? merged.getTitle() : "思维导图"); - existing.setGenerator(GENERATOR_USER_MERGE); - existing.setGeneratorVersion(fresh.getGeneratorVersion()); - existing.setSummary("增量更新,共 " + MindMapTreeTool.countNodes(merged) + " 个节点"); - existing.setGeneratedTime(LocalDateTime.now()); - standardMindMapMapper.updateById(existing); - return existing; - } finally { - lock.set(false); - generatingTasks.remove(taskNum); - } + // 生成(可能调用 AI)不放在事务里:等待 AI 期间不应占用数据库连接(AI-01) + ReviewStandardMindMapEntity fresh = doGenerate(taskNum); + + // 合并新旧树:保留用户编辑过的节点,追加新节点 + 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.setGeneratedTime(LocalDateTime.now()); + standardMindMapMapper.updateById(existing); + return existing; } @Override @@ -153,14 +126,16 @@ public class StandardMindMapServiceImpl implements StandardMindMapService { // ============ 回忆对比 ============ @Override - @Transactional - public ReviewStandardMindMapEntity recallCompare(String taskNum, String recallOutline, String focusPath, - ReviewTiming timing) + public RecallCompareOutcome recallCompare(String taskNum, String recallOutline, String focusPath, + ReviewTiming timing) throws NotFindEntitiesException, OperationFailedException { ensureTaskExists(taskNum); - // 1. 获取标准导图(自动生成) - ReviewStandardMindMapEntity standard = getOrGenerate(taskNum); + // 1. 取标准导图;缺失时按需生成(可能调用 AI,故整个方法不持有事务) + ReviewStandardMindMapEntity standard = queryByTaskNum(taskNum); + if (standard == null) { + standard = doGenerate(taskNum); + } // 2. 解析标准树和用户回忆树 MindMapNode standardRoot = MindMapTreeTool.fromJson(standard.getContent(), objectMapper); @@ -230,7 +205,8 @@ public class StandardMindMapServiceImpl implements StandardMindMapService { taskNum, result.getRecallRatio(), result.getMatchedCount(), result.getMissedCount(), result.getExtraCount(), record.getReviewDurationSeconds()); - return standard; + return new RecallCompareOutcome(standard.getId(), record.getId(), result.getRecallRatio(), + result.getMatchedCount(), result.getMissedCount(), result.getExtraCount()); } // ============ 节点查找 ============ @@ -238,7 +214,15 @@ public class StandardMindMapServiceImpl implements StandardMindMapService { @Override public Map findNode(String taskNum, String content) throws NotFindEntitiesException, OperationFailedException { ensureTaskExists(taskNum); - ReviewStandardMindMapEntity standard = getOrGenerate(taskNum); + ReviewStandardMindMapEntity standard = queryByTaskNum(taskNum); + if (standard == null) { + // 还没有标准导图时无从匹配;由调用方决定是否先发起生成任务 + Map empty = new LinkedHashMap<>(); + empty.put("path", ""); + empty.put("nodeTitle", ""); + empty.put("score", 0.0); + return empty; + } MindMapNode root = MindMapTreeTool.fromJson(standard.getContent(), objectMapper); MindMapNode closest = MindMapTreeTool.findClosestNode(root, content); diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/StudySessionsServiceImpl.java b/src/main/java/com/guo/learningprogresstracker/service/impl/StudySessionsServiceImpl.java index 72a80ce..94e2320 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/impl/StudySessionsServiceImpl.java +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/StudySessionsServiceImpl.java @@ -234,8 +234,12 @@ public class StudySessionsServiceImpl extends ServiceImpl由 AI 任务执行器在请求线程之外调用(AI-02):聚合可能等待 AI 数分钟, + * 不能放在读取接口里,否则一个 GET 就会阻塞并按 AI 计费。

*/ - public String generateReportDraft(String sessionNum) throws ErrorParameterException { + @Override + public String buildReportDraft(String sessionNum) throws ErrorParameterException { StudySessionsEntity session = this.getOneOpt(Wrappers.lambdaQuery(StudySessionsEntity.class) .eq(StudySessionsEntity::getSessionNum, sessionNum)) .orElseThrow(() -> sessionNotFound(sessionNum)); diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml index e2df813..1320769 100644 --- a/src/main/resources/application.yml +++ b/src/main/resources/application.yml @@ -72,4 +72,17 @@ lpt: # 低频定时收敛扫描间隔(毫秒) scan-interval-ms: 600000 # 是否开启低频定时收敛 - scan-enabled: true \ No newline at end of file + scan-enabled: true + # AI 异步任务(AI-02):提交秒回任务标识,执行器在请求线程之外调用 AI + ai-task: + # 单个任务允许的最长执行时间(秒),超过视为进程中断并可回收重试 + stuck-timeout-seconds: 900 + # 兜底扫描间隔与首次延迟(毫秒) + scan-interval-ms: 3000 + scan-initial-delay-ms: 3000 + # 单次扫描处理的任务数上限 + scan-batch-size: 10 + # 立即投递线程池 + executor-core-size: 2 + executor-max-size: 4 + executor-queue-capacity: 50 \ No newline at end of file diff --git a/src/main/resources/db/migration/V20261009_6__add_ai_tasks.sql b/src/main/resources/db/migration/V20261009_6__add_ai_tasks.sql new file mode 100644 index 0000000..2d8b6da --- /dev/null +++ b/src/main/resources/db/migration/V20261009_6__add_ai_tasks.sql @@ -0,0 +1,31 @@ +-- AI 异步任务表(AI-02):把「提交 AI 任务」与「等待 AI 结果」拆开。 +-- 提交接口秒级返回任务标识,执行器在请求线程之外调用 AI 并回写结果; +-- 结果按任务标识可重复获取,刷新/离开页面不再丢失,AI 已消耗的 token 也不会白费。 +-- 同时承担 AI-04 的并发控制:同一用户 + 同一类型 + 同一目标已有进行中任务时, +-- 复用该任务而不是重复生成(「生成中」对外是任务状态,不再返回可能为空的实体)。 +CREATE TABLE ai_tasks +( + id INT AUTO_INCREMENT COMMENT 'id无业务含义' + PRIMARY KEY, + task_num VARCHAR(255) NOT NULL COMMENT 'AI 任务编号(对外标识)', + ai_type VARCHAR(50) NOT NULL COMMENT '任务类型:RECALL_COMPARE/MIND_MAP/REPORT_DRAFT', + target_num VARCHAR(255) NOT NULL COMMENT '目标编号:学习任务编号或学习会话编号', + status VARCHAR(20) NOT NULL COMMENT 'PENDING/RUNNING/SUCCEEDED/FAILED', + request_payload MEDIUMTEXT NULL COMMENT '提交时的请求参数 JSON', + result_payload MEDIUMTEXT NULL COMMENT '成功结果 JSON', + error_message VARCHAR(512) NULL COMMENT '失败原因(用户可见文案,技术细节只进日志)', + started_time DATETIME 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_ai_tasks_task_num (task_num), + -- 执行器取待处理任务(跨租户扫描,故不以 created_by 打头) + KEY idx_ai_tasks_status_created (status, created_time), + -- 请求侧查「某目标的进行中任务」与「某目标的最近任务」(数据-02 之后的新查询一律带租户前缀) + KEY idx_ai_tasks_target (created_by, ai_type, target_num, created_time) +) + COMMENT 'AI 异步任务:提交后立即返回任务标识,执行结果按标识重复获取'; diff --git a/src/test/java/com/guo/learningprogresstracker/controller/ReviewControllerUnitTest.java b/src/test/java/com/guo/learningprogresstracker/controller/ReviewControllerUnitTest.java index 33dc926..fb28cfa 100644 --- a/src/test/java/com/guo/learningprogresstracker/controller/ReviewControllerUnitTest.java +++ b/src/test/java/com/guo/learningprogresstracker/controller/ReviewControllerUnitTest.java @@ -2,8 +2,6 @@ package com.guo.learningprogresstracker.controller; import com.guo.learningprogresstracker.dto.ReviewFeedItem; import com.guo.learningprogresstracker.dto.ReviewTaskStats; -import com.guo.learningprogresstracker.dto.ReviewTiming; -import com.guo.learningprogresstracker.dto.request.RecallCompareRequest; import com.guo.learningprogresstracker.dto.request.UpdateStandardMindMapRequest; import com.guo.learningprogresstracker.entity.CommonResult; import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity; @@ -14,22 +12,19 @@ import com.guo.learningprogresstracker.service.ReviewService; import com.guo.learningprogresstracker.service.StandardMindMapService; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; -import org.mockito.ArgumentCaptor; import org.mockito.InjectMocks; import org.mockito.Mock; import org.mockito.junit.jupiter.MockitoExtension; -import java.time.LocalDateTime; import java.util.List; import java.util.Map; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertSame; -import static org.mockito.ArgumentMatchers.any; -import static org.mockito.ArgumentMatchers.eq; -import static org.mockito.ArgumentMatchers.isNull; +import static org.mockito.ArgumentMatchers.anyString; import static org.mockito.Mockito.verify; +import static org.mockito.Mockito.never; import static org.mockito.Mockito.when; /** @@ -114,38 +109,27 @@ class ReviewControllerUnitTest { } @Test - void getStandardMindMap_delegatesToService() throws Exception { + void getStandardMindMap_returnsExistingWithoutGenerating() throws Exception { ReviewStandardMindMapEntity mindMap = new ReviewStandardMindMapEntity(); - when(standardMindMapService.getOrGenerate("T003")).thenReturn(mindMap); + when(standardMindMapService.getExisting("T003")).thenReturn(mindMap); CommonResult result = controller.getStandardMindMap("T003"); assertEquals(200, result.getCode()); assertSame(mindMap, result.getData()); + // AI-02:读取路径不再触发生成,也就不会因为一个 GET 就阻塞并按 AI 计费 + verify(standardMindMapService).getExisting("T003"); + verify(standardMindMapService, never()).regenerate(anyString()); } @Test - void regenerateStandardMindMap_incrementalMode_usesIncrementalGenerate() throws Exception { - ReviewStandardMindMapEntity mindMap = new ReviewStandardMindMapEntity(); - when(standardMindMapService.incrementalGenerate("T004")).thenReturn(mindMap); + void getStandardMindMap_absentMap_returnsNullData() throws Exception { + when(standardMindMapService.getExisting("T013")).thenReturn(null); - CommonResult result = controller.regenerateStandardMindMap("T004", "incremental"); + CommonResult result = controller.getStandardMindMap("T013"); assertEquals(200, result.getCode()); - assertSame(mindMap, result.getData()); - verify(standardMindMapService).incrementalGenerate("T004"); - } - - @Test - void regenerateStandardMindMap_defaultMode_usesFullRegenerate() throws Exception { - ReviewStandardMindMapEntity mindMap = new ReviewStandardMindMapEntity(); - when(standardMindMapService.regenerate("T005")).thenReturn(mindMap); - - CommonResult result = controller.regenerateStandardMindMap("T005", "full"); - - assertEquals(200, result.getCode()); - assertSame(mindMap, result.getData()); - verify(standardMindMapService).regenerate("T005"); + assertNull(result.getData(), "没有导图时返回 null,由前端发起 MIND_MAP 任务"); } @Test @@ -161,45 +145,6 @@ class ReviewControllerUnitTest { assertSame(mindMap, result.getData()); } - @Test - void recallCompare_passesOutlineAndFocusPath() throws Exception { - RecallCompareRequest request = new RecallCompareRequest(); - request.setRecallOutline("- 回忆内容"); - request.setFocusPath("根/子"); - request.setReviewStartedAt(LocalDateTime.of(2026, 10, 9, 10, 0, 0)); - request.setReviewLastInteractionAt(LocalDateTime.of(2026, 10, 9, 10, 3, 0)); - request.setReviewDurationSeconds(180); - ReviewStandardMindMapEntity mindMap = new ReviewStandardMindMapEntity(); - ArgumentCaptor timingCaptor = ArgumentCaptor.forClass(ReviewTiming.class); - when(standardMindMapService.recallCompare(eq("T007"), eq("- 回忆内容"), eq("根/子"), any())) - .thenReturn(mindMap); - - CommonResult result = controller.recallCompare("T007", request); - - assertEquals(200, result.getCode()); - assertSame(mindMap, result.getData()); - verify(standardMindMapService).recallCompare(eq("T007"), eq("- 回忆内容"), eq("根/子"), timingCaptor.capture()); - assertEquals(LocalDateTime.of(2026, 10, 9, 10, 0, 0), timingCaptor.getValue().startedAt()); - assertEquals(180, timingCaptor.getValue().durationSeconds()); - } - - @Test - void recallCompare_withoutTiming_passesEmptyTiming() throws Exception { - RecallCompareRequest request = new RecallCompareRequest(); - request.setRecallOutline("- 回忆内容"); - ReviewStandardMindMapEntity mindMap = new ReviewStandardMindMapEntity(); - ArgumentCaptor timingCaptor = ArgumentCaptor.forClass(ReviewTiming.class); - when(standardMindMapService.recallCompare(eq("T012"), eq("- 回忆内容"), isNull(), any())) - .thenReturn(mindMap); - - CommonResult result = controller.recallCompare("T012", request); - - assertEquals(200, result.getCode()); - verify(standardMindMapService).recallCompare(eq("T012"), eq("- 回忆内容"), isNull(), timingCaptor.capture()); - assertNull(timingCaptor.getValue().startedAt()); - assertNull(timingCaptor.getValue().durationSeconds()); - } - @Test void findNode_nullBody_usesEmptyContent() throws Exception { Map matched = Map.of("id", "n1"); diff --git a/src/test/java/com/guo/learningprogresstracker/controller/StudySessionControllerUnitTest.java b/src/test/java/com/guo/learningprogresstracker/controller/StudySessionControllerUnitTest.java index 42789a8..5e8edab 100644 --- a/src/test/java/com/guo/learningprogresstracker/controller/StudySessionControllerUnitTest.java +++ b/src/test/java/com/guo/learningprogresstracker/controller/StudySessionControllerUnitTest.java @@ -146,16 +146,6 @@ class StudySessionControllerUnitTest { assertSame(fragments, result.getData()); } - @Test - void getReportDraft_returnsGeneratedDraft() throws Exception { - when(studySessionsServiceImpl.generateReportDraft("S010")).thenReturn("草稿内容"); - - CommonResult result = controller.getReportDraft("S010"); - - assertEquals(200, result.getCode()); - assertEquals("草稿内容", result.getData()); - } - @Test void getTaskFragments_passesPagingArguments() { Page page = new Page<>(); diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/AiTaskIntegrationTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/AiTaskIntegrationTest.java new file mode 100644 index 0000000..57c6de1 --- /dev/null +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/AiTaskIntegrationTest.java @@ -0,0 +1,264 @@ +package com.guo.learningprogresstracker.service.impl; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.guo.learningprogresstracker.dto.AiTaskResponse; +import com.guo.learningprogresstracker.dto.request.AiTaskSubmitRequest; +import com.guo.learningprogresstracker.entity.StudyReportsEntity; +import com.guo.learningprogresstracker.entity.StudySessionsEntity; +import com.guo.learningprogresstracker.entity.TaskEntity; +import com.guo.learningprogresstracker.enums.AiTaskStatusEnum; +import com.guo.learningprogresstracker.mapper.StudyReportsMapper; +import com.guo.learningprogresstracker.mapper.StudySessionsMapper; +import com.guo.learningprogresstracker.mapper.TasksMapper; +import com.guo.learningprogresstracker.service.AiTaskService; +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 org.springframework.transaction.support.TransactionSynchronizationManager; + +import java.util.List; +import java.util.Map; +import java.util.Optional; +import java.util.concurrent.atomic.AtomicBoolean; + +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; + +/** + * AI 链路的落库集成测试(AI-01 / AI-02 / AI-04)。 + * + *

核心验收:

+ *
    + *
  • AI-01:AI 调用发生时没有数据库事务在进行(等待 AI 期间不占用数据库连接);
  • + *
  • AI-02:提交后在请求线程之外完成任务,结果按任务标识可重复获取;
  • + *
  • AI-04:同一目标已有进行中任务时复用,不重复触发生成。
  • + *
+ */ +@SpringBootTest +class AiTaskIntegrationTest { + + @Autowired + private AiTaskService aiTaskService; + + @Autowired + private AiTaskRunner aiTaskRunner; + + @Autowired + private TasksMapper tasksMapper; + + @Autowired + private StudySessionsMapper studySessionsMapper; + + @Autowired + private StudyReportsMapper studyReportsMapper; + + /** 用假的 AI 客户端记录「调用 AI 时是否存在事务」,并让思维导图走 AI 分支 */ + @MockBean + private AiServiceClient aiServiceClient; + + private final ObjectMapper objectMapper = new ObjectMapper(); + + /** AI 调用被触发时是否存在活动事务 */ + private final AtomicBoolean transactionActiveDuringAiCall = new AtomicBoolean(false); + + private final AtomicBoolean aiCalled = new AtomicBoolean(false); + + /** AI 调用发生在哪个线程:用于证明「AI 不在请求线程里执行」 */ + private final java.util.concurrent.atomic.AtomicReference aiCallThread = new java.util.concurrent.atomic.AtomicReference<>(); + + private static final String USER = "AI 链路集成测试用户"; + + @BeforeEach + void setUp() { + // 多租户拦截器需要登录态 + cn.dev33.satoken.stp.StpUtil.login(USER, "test_device"); + transactionActiveDuringAiCall.set(false); + aiCalled.set(false); + aiCallThread.set(null); + + when(aiServiceClient.isConfigured()).thenReturn(true); + when(aiServiceClient.generateMindMap(anyString(), any(), any())).thenAnswer(invocation -> { + aiCalled.set(true); + aiCallThread.set(Thread.currentThread().getName()); + transactionActiveDuringAiCall.set(TransactionSynchronizationManager.isActualTransactionActive()); + // 模拟 AI 耗时:这段时间不应持有数据库连接 + Thread.sleep(80); + return Optional.of("- 根主题\n\t- 子知识点"); + }); + } + + private String createTaskWithReport() { + String taskNum = GenerateNumTool.generateNum("TASKAI"); + TaskEntity task = new TaskEntity(); + task.setTaskNum(taskNum); + task.setTaskName("AI 链路集成测试任务"); + tasksMapper.insert(task); + + StudySessionsEntity session = new StudySessionsEntity(); + session.setSessionNum(GenerateNumTool.generateNum("SESSIONAI")); + session.setTaskNum(taskNum); + session.setStartTime(java.time.LocalDateTime.now()); + session.setLastStartTime(java.time.LocalDateTime.now()); + session.setSessionState("ENDED"); + studySessionsMapper.insert(session); + + StudyReportsEntity report = new StudyReportsEntity(); + report.setSessionNum(session.getSessionNum()); + report.setContent("报告正文"); + studyReportsMapper.insert(report); + return taskNum; + } + + /** + * 轮询到终态(等价于前端的轮询行为)。不用手动调用扫描方法: + * 提交后已经立即投递,手工再扫会与异步执行竞争。 + */ + private AiTaskResponse awaitTerminal(String taskNum) throws Exception { + AiTaskResponse response = null; + for (int i = 0; i < 100; i++) { + response = aiTaskService.getByTaskNum(taskNum); + if (AiTaskStatusEnum.SUCCEEDED.name().equals(response.getStatus()) + || AiTaskStatusEnum.FAILED.name().equals(response.getStatus())) { + return response; + } + Thread.sleep(50); + } + fail("任务在 5 秒内未进入终态,最后状态: " + (response == null ? "null" : response.getStatus())); + return response; + } + + private static AiTaskSubmitRequest request(String type, String targetNum, Map params) { + AiTaskSubmitRequest request = new AiTaskSubmitRequest(); + request.setType(type); + request.setTargetNum(targetNum); + request.setParams(params); + return request; + } + + @Test + void mindMapTask_runsAiOffRequestThreadWithoutTransaction_andResultIsRepeatable() throws Exception { + String taskNum = createTaskWithReport(); + String requestThread = Thread.currentThread().getName(); + + // 提交:只落一条 PENDING 任务并立刻返回标识 + AiTaskResponse submitted = aiTaskService.submit(request("MIND_MAP", taskNum, Map.of("mode", "full"))); + assertEquals(AiTaskStatusEnum.PENDING.name(), submitted.getStatus()); + + AiTaskResponse done = awaitTerminal(submitted.getTaskNum()); + + assertTrue(aiCalled.get(), "AI 应被调用"); + assertNotEquals(requestThread, aiCallThread.get(), "AI 不应在请求线程里执行"); + assertTrue(aiCallThread.get().startsWith("ai-task-"), + "AI 应由 AI 任务线程池执行,实际线程: " + aiCallThread.get()); + assertFalse(transactionActiveDuringAiCall.get(), + "AI-01:调用 AI 时不应存在活动事务(否则会长时间占用数据库连接)"); + + AiTaskResponse again = aiTaskService.getByTaskNum(submitted.getTaskNum()); + assertEquals(AiTaskStatusEnum.SUCCEEDED.name(), done.getStatus(), done.getErrorMessage()); + assertNotNull(done.getResult().get("standardMapId")); + assertEquals(done.getResult(), again.getResult(), "任务结果必须可重复获取,无需重试"); + } + + @Test + void recallCompareTask_completesAndPersistsRecallRecord() throws Exception { + String taskNum = createTaskWithReport(); + // 先让标准导图存在,回忆对比才有基准 + AiTaskResponse mindMapTask = aiTaskService.submit(request("MIND_MAP", taskNum, Map.of("mode", "full"))); + awaitTerminal(mindMapTask.getTaskNum()); + + when(aiServiceClient.compareRecall(anyString(), anyString(), anyString())).thenAnswer(invocation -> { + aiCalled.set(true); + transactionActiveDuringAiCall.set(TransactionSynchronizationManager.isActualTransactionActive()); + Thread.sleep(50); + JsonNode json = objectMapper.readTree(""" + {"matches":[{"standardTitle":"子知识点"}],"missedTitles":[],"extraNodes":[],"evaluation":"不错"} + """); + return Optional.of(json); + }); + + AiTaskResponse submitted = aiTaskService.submit(request("RECALL_COMPARE", taskNum, + Map.of("recallOutline", "- 根主题\n\t- 子知识点", + "reviewStartedAt", java.time.LocalDateTime.now().minusMinutes(2).toString(), + "reviewDurationSeconds", 120))); + + AiTaskResponse done = awaitTerminal(submitted.getTaskNum()); + + assertFalse(transactionActiveDuringAiCall.get(), "AI-01:回忆对比的 AI 调用也必须在事务之外"); + assertEquals(AiTaskStatusEnum.SUCCEEDED.name(), done.getStatus(), done.getErrorMessage()); + assertNotNull(done.getResult().get("recallRecordId"), "回忆记录应已落库"); + assertNotNull(done.getResult().get("recallRatio"), "覆盖率应随结果返回"); + } + + @Test + void submittingSameTargetTwice_reusesActiveTask() throws Exception { + String taskNum = createTaskWithReport(); + + AiTaskResponse first = aiTaskService.submit(request("MIND_MAP", taskNum, Map.of("mode", "full"))); + AiTaskResponse second = aiTaskService.submit(request("MIND_MAP", taskNum, Map.of("mode", "full"))); + + assertEquals(first.getTaskNum(), second.getTaskNum(), + "AI-04:同一目标已有进行中任务时应返回该任务状态,而不是重复生成"); + } + + @Test + void failedTask_isQueryableWithReasonInsteadOfRetry() throws Exception { + // 没有任何学习报告的任务无法生成导图 + String taskNum = GenerateNumTool.generateNum("TASKAI"); + TaskEntity task = new TaskEntity(); + task.setTaskNum(taskNum); + task.setTaskName("没有学习报告的任务"); + tasksMapper.insert(task); + + AiTaskResponse submitted = aiTaskService.submit(request("MIND_MAP", taskNum, Map.of("mode", "full"))); + + AiTaskResponse done = awaitTerminal(submitted.getTaskNum()); + assertEquals(AiTaskStatusEnum.FAILED.name(), done.getStatus()); + assertNotNull(done.getErrorMessage(), "失败原因应可查询,而不是让用户重试"); + assertNull(done.getResult()); + } + + @Test + void unknownTaskNum_isReportedAsNotFound() { + assertThrows(com.guo.learningprogresstracker.exception.NotFindEntitiesException.class, + () -> aiTaskService.getByTaskNum("AITASK-NOT-EXIST")); + } + + @Test + void taskListIsScopedToCurrentUser() throws Exception { + String taskNum = createTaskWithReport(); + AiTaskResponse submitted = aiTaskService.submit(request("MIND_MAP", taskNum, Map.of("mode", "full"))); + + cn.dev33.satoken.stp.StpUtil.logout(); + cn.dev33.satoken.stp.StpUtil.login("AI 链路集成测试另一个用户", "test_device"); + assertThrows(com.guo.learningprogresstracker.exception.NotFindEntitiesException.class, + () -> aiTaskService.getByTaskNum(submitted.getTaskNum()), + "AI 任务同样受租户隔离约束"); + } + + /** 提交后立即投递:不需要等定时扫描,也不用用户手动重试 */ + @Test + void submittedTaskIsEventuallyExecutedWithoutManualScan() throws Exception { + String taskNum = createTaskWithReport(); + AiTaskResponse submitted = aiTaskService.submit(request("MIND_MAP", taskNum, Map.of("mode", "full"))); + + AiTaskResponse finalState = null; + for (int i = 0; i < 50; i++) { + Thread.sleep(100); + finalState = aiTaskService.getByTaskNum(submitted.getTaskNum()); + if (finalState.getStatus().equals(AiTaskStatusEnum.SUCCEEDED.name()) + || finalState.getStatus().equals(AiTaskStatusEnum.FAILED.name())) { + break; + } + } + assertNotNull(finalState); + List terminal = List.of(AiTaskStatusEnum.SUCCEEDED.name(), AiTaskStatusEnum.FAILED.name()); + assertTrue(terminal.contains(finalState.getStatus()), + "提交后应立即投递执行,无需等待定时扫描;实际状态: " + finalState.getStatus()); + } +} diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/AiTaskServiceImplTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/AiTaskServiceImplTest.java new file mode 100644 index 0000000..d7dfdc5 --- /dev/null +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/AiTaskServiceImplTest.java @@ -0,0 +1,229 @@ +package com.guo.learningprogresstracker.service.impl; + +import com.baomidou.mybatisplus.core.conditions.Wrapper; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.guo.learningprogresstracker.config.AiTaskProperties; +import com.guo.learningprogresstracker.dto.AiTaskResponse; +import com.guo.learningprogresstracker.dto.request.AiTaskSubmitRequest; +import com.guo.learningprogresstracker.entity.AiTaskEntity; +import com.guo.learningprogresstracker.enums.AiTaskStatusEnum; +import com.guo.learningprogresstracker.exception.ErrorParameterException; +import com.guo.learningprogresstracker.exception.NotFindEntitiesException; +import com.guo.learningprogresstracker.mapper.AiTaskMapper; +import com.guo.learningprogresstracker.service.event.AiTaskSubmittedEvent; +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.extension.ExtendWith; +import org.mockito.ArgumentCaptor; +import org.mockito.InjectMocks; +import org.mockito.Mock; +import org.mockito.junit.jupiter.MockitoExtension; +import org.mockito.junit.jupiter.MockitoSettings; +import org.mockito.quality.Strictness; +import org.springframework.context.ApplicationEventPublisher; + +import java.time.LocalDateTime; +import java.util.HashMap; +import java.util.List; +import java.util.Map; + +import static org.junit.jupiter.api.Assertions.*; +import static org.mockito.ArgumentMatchers.any; +import static org.mockito.ArgumentMatchers.anyInt; +import static org.mockito.Mockito.*; + +/** + * AI 异步任务服务单元测试(AI-02 / AI-04)。 + */ +@ExtendWith(MockitoExtension.class) +@MockitoSettings(strictness = Strictness.LENIENT) +class AiTaskServiceImplTest { + + @InjectMocks + private AiTaskServiceImpl service; + + @Mock + private AiTaskMapper aiTaskMapper; + + @Mock + private ApplicationEventPublisher eventPublisher; + + private final ObjectMapper objectMapper = new ObjectMapper(); + + private final AiTaskProperties properties = new AiTaskProperties(); + + private void injectDependencies() { + service = new AiTaskServiceImpl(aiTaskMapper, objectMapper, properties, eventPublisher); + } + + private static AiTaskSubmitRequest request(String type, String targetNum, Map params) { + AiTaskSubmitRequest request = new AiTaskSubmitRequest(); + request.setType(type); + request.setTargetNum(targetNum); + request.setParams(params); + return request; + } + + @Test + void submit_persistsPendingTaskAndReturnsIdentifierImmediately() throws Exception { + injectDependencies(); + when(aiTaskMapper.selectOne(any())).thenReturn(null); + + AiTaskResponse response = service.submit(request("MIND_MAP", "TASK-1", Map.of("mode", "full"))); + + assertNotNull(response.getTaskNum()); + assertTrue(response.getTaskNum().startsWith("AITASK-")); + assertEquals("MIND_MAP", response.getType()); + assertEquals("TASK-1", response.getTargetNum()); + assertEquals(AiTaskStatusEnum.PENDING.name(), response.getStatus()); + assertNull(response.getResult(), "未完成的任务不应返回结果"); + verify(aiTaskMapper).insert(any(AiTaskEntity.class)); + } + + @Test + void submit_publishesEventForImmediateExecution() throws Exception { + injectDependencies(); + when(aiTaskMapper.selectOne(any())).thenReturn(null); + + service.submit(request("REPORT_DRAFT", "SESSION-1", null)); + + ArgumentCaptor captor = ArgumentCaptor.forClass(AiTaskSubmittedEvent.class); + verify(eventPublisher).publishEvent(captor.capture()); + assertNull(captor.getValue().taskId(), "尚未落库时事件里的 id 为 null 也无妨,执行器会按 pending 扫描接手"); + } + + @Test + void submit_reusesActiveTaskForSameTargetInsteadOfGeneratingTwice() throws Exception { + injectDependencies(); + // AI-04:同一目标已有进行中任务 → 直接复用,返回任务状态而不是实体 + AiTaskEntity running = AiTaskEntity.initNewTask("MIND_MAP", "TASK-1", null); + running.setId(7); + running.setStatus(AiTaskStatusEnum.RUNNING.name()); + when(aiTaskMapper.selectOne(any(Wrapper.class))).thenReturn(running); + + AiTaskResponse response = service.submit(request("MIND_MAP", "TASK-1", null)); + + assertEquals(running.getTaskNum(), response.getTaskNum()); + assertEquals(AiTaskStatusEnum.RUNNING.name(), response.getStatus()); + verify(aiTaskMapper, never()).insert(any(AiTaskEntity.class)); + verify(eventPublisher, never()).publishEvent(any(AiTaskSubmittedEvent.class)); + } + + @Test + void submit_unknownType_isRejected() { + injectDependencies(); + assertThrows(ErrorParameterException.class, + () -> service.submit(request("NOT_A_TYPE", "TASK-1", null))); + } + + @Test + void submit_blankTarget_isRejected() { + injectDependencies(); + assertThrows(ErrorParameterException.class, () -> service.submit(request("MIND_MAP", " ", null))); + } + + @Test + void getByTaskNum_returnsSucceededResultRepeatedly() throws Exception { + injectDependencies(); + AiTaskEntity task = AiTaskEntity.initNewTask("RECALL_COMPARE", "TASK-1", null); + task.setStatus(AiTaskStatusEnum.SUCCEEDED.name()); + task.setFinishedTime(LocalDateTime.now()); + Map result = new HashMap<>(); + result.put("recallRecordId", 42); + result.put("recallRatio", 0.75); + task.setResultPayload(objectMapper.writeValueAsString(result)); + when(aiTaskMapper.selectOne(any())).thenReturn(task); + + AiTaskResponse first = service.getByTaskNum(task.getTaskNum()); + AiTaskResponse second = service.getByTaskNum(task.getTaskNum()); + + assertEquals(AiTaskStatusEnum.SUCCEEDED.name(), first.getStatus()); + assertEquals(42, first.getResult().get("recallRecordId")); + assertEquals(first.getResult(), second.getResult(), "结果必须可重复获取,不需要重试"); + // 查询不触发任何写操作 + verify(aiTaskMapper, never()).insert(any(AiTaskEntity.class)); + } + + @Test + void getByTaskNum_missingTask_throwsNotFind() { + injectDependencies(); + when(aiTaskMapper.selectOne(any())).thenReturn(null); + assertThrows(NotFindEntitiesException.class, () -> service.getByTaskNum("AITASK-NONE")); + } + + @Test + void getByTaskNum_failedTask_exposesUserFacingMessageAndNoResult() throws Exception { + injectDependencies(); + AiTaskEntity task = AiTaskEntity.initNewTask("MIND_MAP", "TASK-1", null); + task.setStatus(AiTaskStatusEnum.FAILED.name()); + task.setErrorMessage("这个任务还没开始学习哦"); + when(aiTaskMapper.selectOne(any())).thenReturn(task); + + AiTaskResponse response = service.getByTaskNum(task.getTaskNum()); + + assertEquals(AiTaskStatusEnum.FAILED.name(), response.getStatus()); + assertEquals("这个任务还没开始学习哦", response.getErrorMessage()); + assertNull(response.getResult()); + } + + @Test + void claimPendingTasks_skipsTasksAlreadyClaimedByAnotherWorker() { + injectDependencies(); + AiTaskEntity first = AiTaskEntity.initNewTask("MIND_MAP", "T1", null); + first.setId(1); + AiTaskEntity second = AiTaskEntity.initNewTask("MIND_MAP", "T2", null); + second.setId(2); + when(aiTaskMapper.selectPendingTasks(anyInt())).thenReturn(List.of(first, second)); + // 抢占阶段走忽略租户的读取(执行线程没有 Web 上下文) + when(aiTaskMapper.selectTaskById(1)).thenReturn(first); + when(aiTaskMapper.selectTaskById(2)).thenReturn(second); + // 第一个被别的实例抢走,第二个抢到 + when(aiTaskMapper.claimTask(eq(1), any())).thenReturn(0); + when(aiTaskMapper.claimTask(eq(2), any())).thenReturn(1); + + List claimed = service.claimPendingTasks(10); + + assertEquals(1, claimed.size()); + assertEquals(2, claimed.get(0).getId()); + assertEquals(AiTaskStatusEnum.RUNNING.name(), claimed.get(0).getStatus()); + } + + @Test + void markSucceeded_writesResultPayload() { + injectDependencies(); + AiTaskEntity task = AiTaskEntity.initNewTask("MIND_MAP", "T1", null); + task.setId(3); + when(aiTaskMapper.finishTask(any())).thenReturn(1); + + service.markSucceeded(task, Map.of("standardMapId", 9)); + + assertEquals(AiTaskStatusEnum.SUCCEEDED.name(), task.getStatus()); + assertNotNull(task.getResultPayload()); + assertTrue(task.getResultPayload().contains("standardMapId")); + verify(aiTaskMapper).finishTask(task); + } + + @Test + void markFailed_keepsMessageAndClearsResult() { + injectDependencies(); + AiTaskEntity task = AiTaskEntity.initNewTask("MIND_MAP", "T1", null); + task.setId(4); + task.setResultPayload("{}"); + when(aiTaskMapper.finishTask(any())).thenReturn(1); + + service.markFailed(task, "生成失败了,请稍后再试"); + + assertEquals(AiTaskStatusEnum.FAILED.name(), task.getStatus()); + assertEquals("生成失败了,请稍后再试", task.getErrorMessage()); + assertNull(task.getResultPayload()); + } + + @Test + void reclaimStuckTasks_delegatesWithConfiguredTimeout() { + injectDependencies(); + properties.setStuckTimeoutSeconds(60); + when(aiTaskMapper.reclaimStuckTasks(any(), any())).thenReturn(2); + + assertEquals(2, service.reclaimStuckTasks()); + verify(aiTaskMapper).reclaimStuckTasks(any(), any()); + } +} diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImplTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImplTest.java index 8548442..96b7eaf 100644 --- a/src/test/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImplTest.java +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/StandardMindMapServiceImplTest.java @@ -162,13 +162,13 @@ class StandardMindMapServiceImplTest { } @Test - void getOrGenerate_shouldThrowWhenTaskNotFound() { + void getExisting_shouldThrowWhenTaskNotFound() { when(tasksMapper.exists(any())).thenReturn(false); - assertThrows(NotFindEntitiesException.class, () -> service.getOrGenerate("NOT_EXIST")); + assertThrows(NotFindEntitiesException.class, () -> service.getExisting("NOT_EXIST")); } @Test - void getOrGenerate_shouldReturnExisting() throws Exception { + void getExisting_shouldReturnExisting() throws Exception { when(tasksMapper.exists(any())).thenReturn(true); ReviewStandardMindMapEntity existing = new ReviewStandardMindMapEntity(); @@ -177,7 +177,7 @@ class StandardMindMapServiceImplTest { existing.setTitle("已有导图"); when(standardMindMapMapper.selectOne(any())).thenReturn(existing); - ReviewStandardMindMapEntity result = service.getOrGenerate("T1"); + ReviewStandardMindMapEntity result = service.getExisting("T1"); assertEquals("已有导图", result.getTitle()); verify(standardMindMapMapper, never()).insert(any()); } diff --git a/src/test/resources/application.yml b/src/test/resources/application.yml index 9359f04..678c6b8 100644 --- a/src/test/resources/application.yml +++ b/src/test/resources/application.yml @@ -16,10 +16,13 @@ mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.nologging.NoLoggingImpl -# 测试环境关闭定时收敛:调度任务会与用例自己造的悬挂会话互相干扰 +# 测试环境推迟定时任务:调度会与用例自己造的数据互相干扰(用例直接调对应方法) lpt: study-time: scan-enabled: false + ai-task: + scan-interval-ms: 3600000 + scan-initial-delay-ms: 3600000 # 测试环境不激活 profile,而 src/test/resources/application.yml 会遮蔽 src/main/resources/application.yml, # 因此这里必须显式声明 cors 配置,否则 WebMvcConfig 会因 allowedOrigins 为 null 抛 NPE