From db552182ae3c7375468db4ac5d9b81b357145a09 Mon Sep 17 00:00:00 2001 From: cat-shark <1716967236@qq.com> Date: Fri, 9 Oct 2026 12:31:52 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=82=AC=E6=8C=82=E5=AD=A6=E4=B9=A0?= =?UTF-8?q?=E4=BC=9A=E8=AF=9D=E6=83=B0=E6=80=A7=E6=94=B6=E6=95=9B=E4=B8=8E?= =?UTF-8?q?=E5=AE=9A=E6=97=B6=E5=85=9C=E5=BA=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 2 +- .../common/StudyTimePolicy.java | 70 ++++++--- .../config/StudyTimeConfig.java | 24 +++ .../config/StudyTimeProperties.java | 35 +++++ .../dto/StudySessionsDto.java | 5 + .../dto/response/StudySessionResponse.java | 3 + .../entity/StudySessionsEntity.java | 143 ++++++++++++++---- .../mapper/StudySessionsMapper.java | 54 ++++++- .../service/StudySessionsService.java | 15 ++ .../StudySessionConvergenceScheduler.java | 39 +++++ .../impl/StudySessionsServiceImpl.java | 85 +++++++++-- src/main/resources/application.yml | 18 ++- ...__add_auto_converged_to_study_sessions.sql | 8 + .../entity/StudySessionsEntityTest.java | 83 ++++++++++ ...tudySessionConvergenceIntegrationTest.java | 118 +++++++++++++++ .../impl/StudySessionsServiceImplTest.java | 70 +++++++++ src/test/resources/application.yml | 5 + 17 files changed, 712 insertions(+), 65 deletions(-) create mode 100644 src/main/java/com/guo/learningprogresstracker/config/StudyTimeConfig.java create mode 100644 src/main/java/com/guo/learningprogresstracker/config/StudyTimeProperties.java create mode 100644 src/main/java/com/guo/learningprogresstracker/service/impl/StudySessionConvergenceScheduler.java create mode 100644 src/main/resources/db/migration/V20261009_4__add_auto_converged_to_study_sessions.sql create mode 100644 src/test/java/com/guo/learningprogresstracker/service/impl/StudySessionConvergenceIntegrationTest.java diff --git a/AGENTS.md b/AGENTS.md index d4b0430..4f86955 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -181,7 +181,7 @@ mvn spring-boot:run # 启动(默认 profile: local) - MyBatis 对 Map 结果直接用 JDBC 列名作 key,不做属性映射:`map-underscore-to-camel-case` 与「属性名大小写不敏感」只对类结果生效。而数据库的标识符大小写规则各不相同(MySQL 保留别名、H2/PostgreSQL 转小写、Oracle 转大写),`row.get("taskNum")` 会在部分库上静默取到 null,表现为「数据莫名变 0」而不是报错 - 单列聚合用 `selectObjs`,多列聚合用下面的自定义 Mapper 方法 - **`Wrapper` 表达不了的查询(`SUM`/`GROUP BY`/多表 `JOIN`)收敛到 Mapper 层**,用自定义方法 + **显式结果类**(`dto/` 下的类或实体),参考 `ReviewRecallRecordMapper.sumReviewDurationByTask` → `dto/TaskReviewDuration` + `resources/mapper/ReviewRecallRecordMapper.xml` - - 结果映射优先写显式 ``(`property` ↔ `column` 一一对应),不依赖 `map-underscore-to-camel-case` 的默认值,也不依赖列名大小写 + - 结果映射:列名与属性能对应时可用自动映射,但 `map-underscore-to-camel-case` 必须在 `application.yml` 里显式声明(已配置),不要依赖框架默认值;出现别名、计算列或列名与属性不一致时必须写显式 `` - **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加 - 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`) - 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串 diff --git a/src/main/java/com/guo/learningprogresstracker/common/StudyTimePolicy.java b/src/main/java/com/guo/learningprogresstracker/common/StudyTimePolicy.java index 90b7bca..fd5db91 100644 --- a/src/main/java/com/guo/learningprogresstracker/common/StudyTimePolicy.java +++ b/src/main/java/com/guo/learningprogresstracker/common/StudyTimePolicy.java @@ -1,36 +1,64 @@ package com.guo.learningprogresstracker.common; +import lombok.Getter; + /** - * 学习会话的时间口径常量。 + * 学习会话的时间口径(会话-04 起改为可配置的值对象)。 * - *

番茄钟长度、遗忘判定阈值与有效时间下限集中在此处定义,避免阈值散落在实体与服务的各个角落。 - * 修改口径时只改这里,不要就地写死数字。

+ *

番茄钟长度、遗忘判定阈值、硬兜底阈值与有效时间下限集中在此处,避免阈值散落在实体与服务的各个角落。 + * 生产路径由 Spring 从 {@code lpt.study-time} 配置构建并注入;{@link #DEFAULT} 只保留设计口径的默认值, + * 供实体自身的默认重载与单测使用,不要在服务里直接用它。

*/ -public final class StudyTimePolicy { +@Getter +public class StudyTimePolicy { + + /** 与 lpt-docs 设计口径一致的默认值 */ + public static final StudyTimePolicy DEFAULT = new StudyTimePolicy(25, 50, 120, 600); /** * 番茄钟长度(分钟)。 */ - public static final int WORK_DURATION_MINUTES = 25; + private final int workDurationMinutes; + + /** + * 遗忘判定阈值(分钟):通常为 2 × 番茄钟。 + */ + private final int forgetThresholdMinutes; + + /** + * 硬兜底阈值(分钟):进行中的会话超过该时长未收敛,服务端强制暂停。 + */ + private final int forcePauseMinutes; + + /** + * 有效学习时间下限(秒)。 + */ + private final long minEffectiveTimeSeconds; + + public StudyTimePolicy(int workDurationMinutes, int forgetThresholdMinutes, + int forcePauseMinutes, long minEffectiveTimeSeconds) { + if (workDurationMinutes <= 0) { + throw new IllegalArgumentException("番茄钟长度必须大于 0 分钟"); + } + if (forgetThresholdMinutes < workDurationMinutes) { + throw new IllegalArgumentException("遗忘判定阈值不能小于番茄钟长度"); + } + if (forcePauseMinutes < forgetThresholdMinutes) { + throw new IllegalArgumentException("硬兜底阈值不能小于遗忘判定阈值"); + } + if (minEffectiveTimeSeconds < 0) { + throw new IllegalArgumentException("有效学习时间下限不能为负数"); + } + this.workDurationMinutes = workDurationMinutes; + this.forgetThresholdMinutes = forgetThresholdMinutes; + this.forcePauseMinutes = forcePauseMinutes; + this.minEffectiveTimeSeconds = minEffectiveTimeSeconds; + } /** * 番茄钟长度(毫秒)。 */ - public static final long WORK_DURATION_MILLIS = WORK_DURATION_MINUTES * 60_000L; - - /** - * 遗忘判定阈值(分钟):2 × 番茄钟。 - * - *

最后一段学习在超过该时长后仍没有任何操作,判定为「忘了点暂停/结束」, - * 该段只按一个番茄钟结算(见 {@code StudySessionsEntity#resolveSettlementTime})。

- */ - public static final int FORGET_THRESHOLD_MINUTES = WORK_DURATION_MINUTES * 2; - - /** - * 有效学习时间下限(秒):低于该值的一次学习不计入总学习时间。 - */ - public static final long MIN_EFFECTIVE_TIME_SECONDS = 10 * 60L; - - private StudyTimePolicy() { + public long workDurationMillis() { + return workDurationMinutes * 60_000L; } } diff --git a/src/main/java/com/guo/learningprogresstracker/config/StudyTimeConfig.java b/src/main/java/com/guo/learningprogresstracker/config/StudyTimeConfig.java new file mode 100644 index 0000000..1c6734b --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/config/StudyTimeConfig.java @@ -0,0 +1,24 @@ +package com.guo.learningprogresstracker.config; + +import com.guo.learningprogresstracker.common.StudyTimePolicy; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.scheduling.annotation.EnableScheduling; + +/** + * 学习会话的时间口径装配(会话-04)。 + *

阈值来自 {@link StudyTimeProperties};非法组合在启动时直接失败,避免运行期出现「兜底阈值比遗忘阈值还小」这类矛盾配置。

+ */ +@Configuration +@EnableScheduling +public class StudyTimeConfig { + + @Bean + public StudyTimePolicy studyTimePolicy(StudyTimeProperties properties) { + return new StudyTimePolicy( + properties.getWorkDurationMinutes(), + properties.getForgetThresholdMinutes(), + properties.getForcePauseMinutes(), + properties.getMinEffectiveTimeSeconds()); + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/config/StudyTimeProperties.java b/src/main/java/com/guo/learningprogresstracker/config/StudyTimeProperties.java new file mode 100644 index 0000000..10166d8 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/config/StudyTimeProperties.java @@ -0,0 +1,35 @@ +package com.guo.learningprogresstracker.config; + +import lombok.Data; +import org.springframework.boot.context.properties.ConfigurationProperties; +import org.springframework.context.annotation.Configuration; + +/** + * 学习会话的时间口径配置(会话-04)。 + * + *

番茄钟长度、遗忘判定阈值、硬兜底阈值与有效时间下限集中在这里,改口径不需要改代码。 + * 默认值与 `lpt-docs` 的设计口径一致:25 分钟番茄钟、50 分钟遗忘判定、2 小时硬兜底。

+ */ +@Data +@Configuration +@ConfigurationProperties(prefix = "lpt.study-time") +public class StudyTimeProperties { + + /** 番茄钟长度(分钟):单个学习段落的上限 */ + private int workDurationMinutes = 25; + + /** 遗忘判定阈值(分钟):超过该时长无操作,按「忘了点暂停/结束」只结算一个番茄钟 */ + private int forgetThresholdMinutes = 50; + + /** 硬兜底阈值(分钟):进行中的会话超过该时长仍未结算,由服务端强制收敛 */ + private int forcePauseMinutes = 120; + + /** 有效学习时间下限(秒):低于该值的一次学习不计入总学习时间 */ + private long minEffectiveTimeSeconds = 600; + + /** 低频定时收敛扫描的间隔(毫秒) */ + private long scanIntervalMs = 600_000; + + /** 是否开启低频定时收敛(测试环境可关掉,避免与用例互相干扰) */ + private boolean scanEnabled = true; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/StudySessionsDto.java b/src/main/java/com/guo/learningprogresstracker/dto/StudySessionsDto.java index 49d8b37..3acc2c1 100644 --- a/src/main/java/com/guo/learningprogresstracker/dto/StudySessionsDto.java +++ b/src/main/java/com/guo/learningprogresstracker/dto/StudySessionsDto.java @@ -50,4 +50,9 @@ public class StudySessionsDto { * 学习会话的状态(进行中、暂停、已结束) */ private String sessionState; + + /** + * 是否由服务端自动收敛(疑似忘记结束,会话-04) + */ + private Boolean autoConverged; } diff --git a/src/main/java/com/guo/learningprogresstracker/dto/response/StudySessionResponse.java b/src/main/java/com/guo/learningprogresstracker/dto/response/StudySessionResponse.java index 1cdbcaf..c7e8050 100644 --- a/src/main/java/com/guo/learningprogresstracker/dto/response/StudySessionResponse.java +++ b/src/main/java/com/guo/learningprogresstracker/dto/response/StudySessionResponse.java @@ -54,4 +54,7 @@ public class StudySessionResponse { @Schema(description = "系统提示") private String systemMessage; + + @Schema(description = "是否由服务端自动收敛(疑似忘记结束,会话-04)") + private Boolean autoConverged; } diff --git a/src/main/java/com/guo/learningprogresstracker/entity/StudySessionsEntity.java b/src/main/java/com/guo/learningprogresstracker/entity/StudySessionsEntity.java index 553f457..898c503 100644 --- a/src/main/java/com/guo/learningprogresstracker/entity/StudySessionsEntity.java +++ b/src/main/java/com/guo/learningprogresstracker/entity/StudySessionsEntity.java @@ -76,6 +76,13 @@ public class StudySessionsEntity extends BaseEntity implements Serializable { @TableField(value = "session_state") private String sessionState; + /** + * 是否由服务端自动收敛(会话-04):为 true 表示这段学习疑似忘记点暂停/结束, + * 由惰性收敛或定时扫描强制结算,前端据此给出提示。 + */ + @TableField(value = "auto_converged") + private Boolean autoConverged; + /** * 计时器指针位置,时间戳形式存储(毫秒) @@ -87,28 +94,42 @@ public class StudySessionsEntity extends BaseEntity implements Serializable { private static final long serialVersionUID = 1L; /** - * 初始化新会话 - * @return + * 初始化新会话(使用默认时间口径) */ public static StudySessionsEntity initNewSession(){ + return initNewSession(StudyTimePolicy.DEFAULT); + } + + /** + * 初始化新会话 + */ + public static StudySessionsEntity initNewSession(StudyTimePolicy policy){ StudySessionsEntity studySessionsEntity = new StudySessionsEntity(); studySessionsEntity.setSessionNum(GenerateNumTool.generateNum("SESSION")); studySessionsEntity.setStartTime(LocalDateTime.now()); studySessionsEntity.setLastStartTime(LocalDateTime.now()); - studySessionsEntity.setPointerPosition(StudyTimePolicy.WORK_DURATION_MILLIS); + studySessionsEntity.setPointerPosition(policy.workDurationMillis()); studySessionsEntity.setLastModifiedTime(LocalDateTime.now()); studySessionsEntity.setSessionState(StudySessionStateEnum.ONGOING.name()); + studySessionsEntity.setAutoConverged(false); return studySessionsEntity; } + /** + * 继续会话(使用默认时间口径) + */ + public void continueStudySession() throws ServiceException { + continueStudySession(StudyTimePolicy.DEFAULT); + } + /** * 继续会话 */ - public void continueStudySession() throws ServiceException { + public void continueStudySession(StudyTimePolicy policy) throws ServiceException { if (this.getSessionState().equals(StudySessionStateEnum.PAUSED.name())){ this.setSessionState(StudySessionStateEnum.ONGOING.name()); this.setLastStartTime(LocalDateTime.now()); - this.calculatePointerPosition(); + this.calculatePointerPosition(policy); } else if (this.getSessionState().equals(StudySessionStateEnum.ONGOING.name())) { log.info("进行中的学习会话({})被重新开始",this.getSessionNum()); } else{ @@ -117,13 +138,20 @@ public class StudySessionsEntity extends BaseEntity implements Serializable { } /** - * 暂停会话 + * 暂停会话(使用默认时间口径) */ public void pausedStudySession(LocalDateTime endTime){ + pausedStudySession(endTime, StudyTimePolicy.DEFAULT); + } + + /** + * 暂停会话 + */ + public void pausedStudySession(LocalDateTime endTime, StudyTimePolicy policy){ if (this.getSessionState().equals(StudySessionStateEnum.PAUSED.name())) { log.warn("不应出现的情况:暂停了一个状态为【{}】的学习会话({})", this.getSessionState(), this.getSessionNum()); } else { - LocalDateTime settlementTime = this.resolveSettlementTime(endTime); + LocalDateTime settlementTime = this.resolveSettlementTime(endTime, policy); this.setEndTime(settlementTime); this.setActualTime(Duration.between(this.startTime, this.endTime).toSeconds()); this.setEffectiveTime(this.getEffectiveTime() + Duration.between(this.lastStartTime, this.endTime).toSeconds()); @@ -132,39 +160,54 @@ public class StudySessionsEntity extends BaseEntity implements Serializable { } } + /** + * 计算本次学习分段的结算时间(使用默认时间口径)。 + */ + public LocalDateTime resolveSettlementTime(LocalDateTime candidateEndTime) { + return resolveSettlementTime(candidateEndTime, StudyTimePolicy.DEFAULT); + } + /** * 计算本次学习分段的结算时间:暂停、结束与超时收敛都必须走这里,避免同一行为产生两种统计结果。 * *

{@code lastStartTime} 到候选结束时间超过遗忘判定阈值 - * ({@link StudyTimePolicy#FORGET_THRESHOLD_MINUTES})时,按「忘了点暂停/结束」处理, - * 只结算一个番茄钟({@link StudyTimePolicy#WORK_DURATION_MINUTES} 分钟);否则按候选结束时间结算。

+ * ({@link StudyTimePolicy#getForgetThresholdMinutes()})时,按「忘了点暂停/结束」处理, + * 只结算一个番茄钟({@link StudyTimePolicy#getWorkDurationMinutes()} 分钟);否则按候选结束时间结算。

*/ - public LocalDateTime resolveSettlementTime(LocalDateTime candidateEndTime) { + public LocalDateTime resolveSettlementTime(LocalDateTime candidateEndTime, StudyTimePolicy policy) { LocalDateTime end = ObjectUtils.isEmpty(candidateEndTime) ? LocalDateTime.now() : candidateEndTime; if (ObjectUtils.isEmpty(this.lastStartTime)) { return end; } long minutes = Duration.between(this.lastStartTime, end).toMinutes(); - if (minutes >= StudyTimePolicy.FORGET_THRESHOLD_MINUTES) { + if (minutes >= policy.getForgetThresholdMinutes()) { log.info("会话[{}]本段学习已超过{}分钟无操作,按{}分钟结算", - this.getSessionNum(), StudyTimePolicy.FORGET_THRESHOLD_MINUTES, StudyTimePolicy.WORK_DURATION_MINUTES); - return this.lastStartTime.plusMinutes(StudyTimePolicy.WORK_DURATION_MINUTES); + this.getSessionNum(), policy.getForgetThresholdMinutes(), policy.getWorkDurationMinutes()); + return this.lastStartTime.plusMinutes(policy.getWorkDurationMinutes()); } return end; } /** - * 结束会话 + * 结束会话(使用默认时间口径) */ public void endedStudySession() { + endedStudySession(StudyTimePolicy.DEFAULT); + } + + /** + * 结束会话 + */ + public void endedStudySession(StudyTimePolicy policy) { if (this.isEnded()){ log.warn("不应出现的情况:结束了一个状态为【{}】的学习会话",this.getSessionState()); }else { if (this.getSessionState().equals(StudySessionStateEnum.ONGOING.name())) { - this.pausedStudySession(LocalDateTime.now()); + this.pausedStudySession(LocalDateTime.now(), policy); } - if (this.getEffectiveTime() < StudyTimePolicy.MIN_EFFECTIVE_TIME_SECONDS) { - log.info("会话[{}]有效学习时间({}秒)不足10分钟,不计入总学习时间", this.getSessionNum(), this.getEffectiveTime()); + if (this.getEffectiveTime() < policy.getMinEffectiveTimeSeconds()) { + log.info("会话[{}]有效学习时间({}秒)不足{}分钟,不计入总学习时间", + this.getSessionNum(), this.getEffectiveTime(), policy.getMinEffectiveTimeSeconds() / 60); this.setEffectiveTime(0); this.setEffectivenessRatio(0); } @@ -172,6 +215,36 @@ public class StudySessionsEntity extends BaseEntity implements Serializable { } } + /** + * 服务端强制收敛悬挂会话(会话-04):进行中且超过硬兜底阈值时, + * 按遗忘规则结算为暂停并打上「自动收敛」标记,供前端提示「本次学习疑似忘记结束」。 + * + * @return 是否发生了收敛(未满足条件时返回 false,便于调用方幂等处理) + */ + public boolean forceConverge(LocalDateTime now, StudyTimePolicy policy) { + if (!isForcePausable(now, policy)) { + return false; + } + log.warn("会话[{}]已悬挂超过{}分钟,服务端强制收敛为暂停", this.getSessionNum(), policy.getForcePauseMinutes()); + this.setAutoConverged(true); + this.pausedStudySession(now, policy); + this.setLastModifiedTime(LocalDateTime.now()); + return true; + } + + /** + * 是否属于「长时间无人操作」的进行中会话:只有进行中且本段开始时间早于硬兜底阈值才成立。 + */ + public boolean isForcePausable(LocalDateTime now, StudyTimePolicy policy) { + if (!StudySessionStateEnum.ONGOING.name().equals(this.sessionState)) { + return false; + } + if (ObjectUtils.isEmpty(this.lastStartTime)) { + return false; + } + return Duration.between(this.lastStartTime, now).toMinutes() >= policy.getForcePauseMinutes(); + } + /** * 第一次运行 * @return @@ -181,20 +254,27 @@ public class StudySessionsEntity extends BaseEntity implements Serializable { } + /** + * 计算当前倒计时指针的位置(使用默认时间口径) + */ + public void calculatePointerPosition() throws ServiceException { + calculatePointerPosition(StudyTimePolicy.DEFAULT); + } + /** * 计算当前倒计时指针的位置(单位:毫秒) * * 规则说明: - * - 如果是第一次运行(lastStartTime为null),则倒计时从25分钟开始 + * - 如果是第一次运行(lastStartTime为null),则倒计时从番茄钟长度开始 * - 如果是暂停状态,返回上次保存的pointerPosition * - 如果是进行中状态,返回 pointerPosition -(当前时间 - lastStartTime) * 即从上次开始后经历的时间,从之前保存的pointerPosition中扣除 * * @return 指针当前位置,单位为毫秒 */ - public void calculatePointerPosition() throws ServiceException { + public void calculatePointerPosition(StudyTimePolicy policy) throws ServiceException { if (isFirstRun()) { - this.pointerPosition = StudyTimePolicy.WORK_DURATION_MILLIS; // 毫秒 + this.pointerPosition = policy.workDurationMillis(); return; } @@ -209,12 +289,12 @@ public class StudySessionsEntity extends BaseEntity implements Serializable { case ONGOING: long elapsedMillis = Duration.between(lastStartTime, LocalDateTime.now()).toMillis(); long basePointerPosition = ObjectUtils.isEmpty(pointerPosition) - ? StudyTimePolicy.WORK_DURATION_MILLIS + ? policy.workDurationMillis() : pointerPosition; long newPointerPosition = basePointerPosition - elapsedMillis; if (newPointerPosition <= 0) { // 如果循环已经结束,则需要重置指针位置 - this.pointerPosition = StudyTimePolicy.WORK_DURATION_MILLIS; + this.pointerPosition = policy.workDurationMillis(); } else { this.pointerPosition = newPointerPosition; } @@ -241,17 +321,24 @@ public class StudySessionsEntity extends BaseEntity implements Serializable { return StudySessionStateEnum.ENDED.name().equals(this.sessionState); } + /** + * 本段学习是否已判定为「忘了点暂停/结束」(使用默认时间口径)。 + */ + public boolean isForgotten() { + return isForgotten(LocalDateTime.now(), StudyTimePolicy.DEFAULT); + } + + public boolean isForgotten(LocalDateTime now) { + return isForgotten(now, StudyTimePolicy.DEFAULT); + } + /** * 本段学习是否已判定为「忘了点暂停/结束」,即需要按遗忘规则截断。 * *

只有进行中的会话才成立:暂停与已结束的会话,其时间已在结算时入账,再次截断会重复扣减。 * 同时要求本段尚未结算过({@code end_time} 不早于 {@code last_start_time} 时视为已结算)。

*/ - public boolean isForgotten() { - return isForgotten(LocalDateTime.now()); - } - - public boolean isForgotten(LocalDateTime now) { + public boolean isForgotten(LocalDateTime now, StudyTimePolicy policy) { if (!StudySessionStateEnum.ONGOING.name().equals(this.sessionState)) { return false; } @@ -261,6 +348,6 @@ public class StudySessionsEntity extends BaseEntity implements Serializable { if (!ObjectUtils.isEmpty(this.endTime) && !this.endTime.isBefore(this.lastStartTime)) { return false; } - return Duration.between(this.lastStartTime, now).toMinutes() >= StudyTimePolicy.FORGET_THRESHOLD_MINUTES; + return Duration.between(this.lastStartTime, now).toMinutes() >= policy.getForgetThresholdMinutes(); } } diff --git a/src/main/java/com/guo/learningprogresstracker/mapper/StudySessionsMapper.java b/src/main/java/com/guo/learningprogresstracker/mapper/StudySessionsMapper.java index c793f4f..2575767 100644 --- a/src/main/java/com/guo/learningprogresstracker/mapper/StudySessionsMapper.java +++ b/src/main/java/com/guo/learningprogresstracker/mapper/StudySessionsMapper.java @@ -1,8 +1,15 @@ package com.guo.learningprogresstracker.mapper; import com.guo.learningprogresstracker.entity.StudySessionsEntity; +import com.baomidou.mybatisplus.annotation.InterceptorIgnore; import com.baomidou.mybatisplus.core.mapper.BaseMapper; 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; /** * @author guo @@ -13,8 +20,47 @@ import org.apache.ibatis.annotations.Mapper; @Mapper public interface StudySessionsMapper extends BaseMapper { + /** + * 找出所有租户中「进行中且悬挂超过硬兜底阈值」的会话(会话-04)。 + * + *

定时任务在请求之外执行,没有登录态,而租户拦截器会读取当前登录用户,因此这里显式忽略租户条件。 + * 这是系统级的后台收敛,只用于定时扫描;请求内的惰性收敛走 {@code Wrappers} 的租户隔离路径。 + * 自定义 SQL 不会被 {@code @TableLogic} 自动追加条件,所以 {@code deleted = 0} 必须显式写出。

+ */ + @InterceptorIgnore(tenantLine = "true") + @Select(""" + SELECT * + FROM study_sessions + WHERE deleted = 0 + AND session_state = 'ONGOING' + AND last_start_time <= #{cutoff} + ORDER BY last_start_time ASC + LIMIT #{limit} + """) + List selectForcePausableSessions(@Param("cutoff") LocalDateTime cutoff, + @Param("limit") int limit); + + /** + * 条件写入收敛结果(会话-04):只有仍然处于 ONGOING 的会话才会被写入,保证并发下不会重复结算。 + * + *

按主键更新(主键全局唯一),因此忽略租户条件是安全的:定时任务在请求之外执行, + * 没有登录态可供租户拦截器读取。

+ * + * @return 受影响行数,0 表示已被其他请求收敛 + */ + @InterceptorIgnore(tenantLine = "true") + @Update(""" + UPDATE study_sessions + SET end_time = #{endTime}, + actual_time = #{actualTime}, + effective_time = #{effectiveTime}, + effectiveness_ratio = #{effectivenessRatio}, + session_state = #{sessionState}, + auto_converged = #{autoConverged}, + last_modified_time = #{lastModifiedTime} + WHERE id = #{id} + AND session_state = 'ONGOING' + AND deleted = 0 + """) + int convergeStaleSession(StudySessionsEntity session); } - - - - diff --git a/src/main/java/com/guo/learningprogresstracker/service/StudySessionsService.java b/src/main/java/com/guo/learningprogresstracker/service/StudySessionsService.java index 74c367e..796414e 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/StudySessionsService.java +++ b/src/main/java/com/guo/learningprogresstracker/service/StudySessionsService.java @@ -40,4 +40,19 @@ public interface StudySessionsService extends IService { Page getTaskReports(String taskNum, int page, int size, String keyword); StudySessionResponse getActiveSession(String excludeTaskNum); + + /** + * 惰性收敛(会话-04):把当前用户悬挂的进行中会话按硬兜底阈值强制暂停。 + *

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

+ * + * @return 本次实际收敛的会话数 + */ + int convergeStaleSessionsOfCurrentUser(); + + /** + * 定时收敛(会话-04):扫描所有用户悬挂的进行中会话并强制暂停。 + * + * @return 本次实际收敛的会话数 + */ + int scanAndConvergeStaleSessions(); } diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/StudySessionConvergenceScheduler.java b/src/main/java/com/guo/learningprogresstracker/service/impl/StudySessionConvergenceScheduler.java new file mode 100644 index 0000000..970177e --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/StudySessionConvergenceScheduler.java @@ -0,0 +1,39 @@ +package com.guo.learningprogresstracker.service.impl; + +import com.guo.learningprogresstracker.service.StudySessionsService; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; +import org.springframework.scheduling.annotation.Scheduled; +import org.springframework.stereotype.Component; + +/** + * 悬挂会话的低频定时收敛(会话-04)。 + * + *

惰性收敛只在用户访问时生效;用户不回来时「今日有效学习时间」等统计会一直滞后, + * 悬挂会话也会一直挡住新任务,因此增加这条定时兜底。扫描间隔由 + * {@code lpt.study-time.scan-interval-ms} 配置,测试环境用 {@code lpt.study-time.scan-enabled=false} 关闭。

+ */ +@Slf4j +@Component +@RequiredArgsConstructor +@ConditionalOnProperty(prefix = "lpt.study-time", name = "scan-enabled", havingValue = "true", matchIfMissing = true) +public class StudySessionConvergenceScheduler { + + private final StudySessionsService studySessionsService; + + /** + * 定时扫描并收敛悬挂会话;异常只记录不抛出,避免一次失败导致调度任务停止。 + */ + @Scheduled(fixedDelayString = "${lpt.study-time.scan-interval-ms:600000}") + public void convergeStaleSessions() { + try { + int converged = studySessionsService.scanAndConvergeStaleSessions(); + if (converged > 0) { + log.info("[会话收敛] 定时扫描收敛了 {} 个悬挂会话", converged); + } + } catch (Exception e) { + log.error("[会话收敛] 定时扫描失败", e); + } + } +} 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 e6bb768..72a80ce 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/impl/StudySessionsServiceImpl.java +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/StudySessionsServiceImpl.java @@ -27,6 +27,7 @@ import org.springframework.transaction.annotation.Transactional; import java.time.LocalDateTime; import java.util.ArrayList; +import java.util.List; import java.util.Optional; import java.util.stream.Collectors; @@ -44,12 +45,16 @@ public class StudySessionsServiceImpl extends ServiceImpl { // 如果没有则创建新会话 - StudySessionsEntity newSession = StudySessionsEntity.initNewSession(); + StudySessionsEntity newSession = StudySessionsEntity.initNewSession(studyTimePolicy); newSession.setTaskNum(taskNum); newSession.setLastStartTime(LocalDateTime.now()); this.save(newSession); return newSession; }); - session.calculatePointerPosition(); + LocalDateTime now = LocalDateTime.now(); + session.calculatePointerPosition(studyTimePolicy); // 只有进行中且本段尚未结算的会话才需要收敛;已暂停/已结束的会话不再重复截断 - boolean forgotten = session.isForgotten(); + boolean forgotten = session.isForgotten(now, studyTimePolicy); if (forgotten) { - session.pausedStudySession(null); + session.pausedStudySession(null, studyTimePolicy); this.updateById(session); } @@ -88,7 +94,7 @@ public class StudySessionsServiceImpl extends ServiceImpl taskNotFound(taskNum)); @@ -209,7 +217,7 @@ public class StudySessionsServiceImpl extends ServiceImpl staleSessions = this.list(Wrappers.lambdaQuery() + .eq(StudySessionsEntity::getSessionState, StudySessionStateEnum.ONGOING.name()) + .le(StudySessionsEntity::getLastStartTime, cutoff) + .orderByAsc(StudySessionsEntity::getLastStartTime)); + + int converged = 0; + for (StudySessionsEntity session : staleSessions) { + if (convergeOne(session, now)) { + converged++; + } + } + return converged; + } + + @Override + public int scanAndConvergeStaleSessions() { + LocalDateTime now = LocalDateTime.now(); + LocalDateTime cutoff = now.minusMinutes(studyTimePolicy.getForcePauseMinutes()); + + // 定时任务在请求之外执行,没有登录态,走忽略租户条件的扫描(系统级兜底) + List staleSessions = baseMapper.selectForcePausableSessions(cutoff, SCAN_BATCH_SIZE); + + int converged = 0; + for (StudySessionsEntity session : staleSessions) { + if (convergeOne(session, now)) { + converged++; + } + } + return converged; + } + + /** + * 收敛单个悬挂会话:先按硬兜底阈值复核,再用「状态仍为 ONGOING」的条件更新写入。 + * + *

条件更新保证惰性收敛与定时扫描并发时只结算一次(与结束会话的幂等处理同一思路), + * 写入按主键定位,所以定时扫描分支可以安全地忽略租户条件。

+ * + * @return 是否由本次调用完成收敛 + */ + private boolean convergeOne(StudySessionsEntity session, LocalDateTime now) { + if (!session.forceConverge(now, studyTimePolicy)) { + return false; + } + return baseMapper.convergeStaleSession(session) > 0; + } + } diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml index 6637a05..e2df813 100644 --- a/src/main/resources/application.yml +++ b/src/main/resources/application.yml @@ -25,6 +25,8 @@ mybatis-plus: configuration: # 使用 Slf4j 输出 SQL:由各环境的 logging.level 决定是否打印,生产默认不打印 log-impl: org.apache.ibatis.logging.slf4j.Slf4jImpl + # 显式声明下划线转驼峰:实体与聚合结果都依赖它,不要依赖框架默认值 + map-underscore-to-camel-case: true ############## Sa-Token 配置 (文档: https://sa-token.cc) ############## sa-token: @@ -56,4 +58,18 @@ management: lpt: ai-service: url: http://localhost:5199 - timeout-seconds: 600 \ No newline at end of file + timeout-seconds: 600 + # 学习会话的时间口径(会话-04):三类阈值集中在这里,改口径不需要改代码 + study-time: + # 番茄钟长度(分钟) + work-duration-minutes: 25 + # 遗忘判定阈值(分钟):超过该时长无操作按「忘了点暂停/结束」只结算一个番茄钟 + forget-threshold-minutes: 50 + # 硬兜底阈值(分钟):进行中的会话超过该时长仍未结算,由服务端强制收敛 + force-pause-minutes: 120 + # 有效学习时间下限(秒) + min-effective-time-seconds: 600 + # 低频定时收敛扫描间隔(毫秒) + scan-interval-ms: 600000 + # 是否开启低频定时收敛 + scan-enabled: true \ No newline at end of file diff --git a/src/main/resources/db/migration/V20261009_4__add_auto_converged_to_study_sessions.sql b/src/main/resources/db/migration/V20261009_4__add_auto_converged_to_study_sessions.sql new file mode 100644 index 0000000..6b3a157 --- /dev/null +++ b/src/main/resources/db/migration/V20261009_4__add_auto_converged_to_study_sessions.sql @@ -0,0 +1,8 @@ +-- 悬挂会话的服务端自动收敛(会话-04)。 +-- auto_converged=1 表示这段学习疑似「忘记点暂停/结束」,由惰性收敛或低频定时扫描强制结算, +-- 前端据此给出提示;正常暂停/结束的会话保持 0。 +ALTER TABLE study_sessions + ADD COLUMN auto_converged TINYINT(1) DEFAULT 0 NOT NULL COMMENT '是否由服务端自动收敛(疑似忘记结束)' AFTER session_state; + +-- 定时扫描的查询条件:状态 + 最后一段开始时间(跨租户扫描,故不以 created_by 打头) +CREATE INDEX idx_study_sessions_state_last_start ON study_sessions (session_state, last_start_time); diff --git a/src/test/java/com/guo/learningprogresstracker/entity/StudySessionsEntityTest.java b/src/test/java/com/guo/learningprogresstracker/entity/StudySessionsEntityTest.java index 9400494..efd8ca7 100644 --- a/src/test/java/com/guo/learningprogresstracker/entity/StudySessionsEntityTest.java +++ b/src/test/java/com/guo/learningprogresstracker/entity/StudySessionsEntityTest.java @@ -1,5 +1,6 @@ package com.guo.learningprogresstracker.entity; +import com.guo.learningprogresstracker.common.StudyTimePolicy; import com.guo.learningprogresstracker.enums.StudySessionStateEnum; import org.junit.jupiter.api.Test; @@ -399,4 +400,86 @@ class StudySessionsEntityTest { assertTrue(session.isForgotten(), "进行中超过 50 分钟无操作应判定为遗忘"); } + + // ============ 会话-04:硬兜底收敛(惰性 + 定时共用)============ + + /** + * 场景25:悬挂 3 小时的进行中会话被强制收敛为暂停,按遗忘规则截断并打标记 + */ + @Test + void forceConverge_staleOngoingSession_shouldPauseTruncateAndMark() { + StudySessionsEntity session = createOngoingSession(180); + LocalDateTime expectedEnd = session.getLastStartTime().plusMinutes(25); + + boolean converged = session.forceConverge(LocalDateTime.now(), StudyTimePolicy.DEFAULT); + + assertTrue(converged, "超过硬兜底阈值应完成收敛"); + assertEquals(StudySessionStateEnum.PAUSED.name(), session.getSessionState()); + assertEquals(expectedEnd, session.getEndTime(), "应收敛到 last_start_time + 25 分钟"); + assertEquals(25 * 60, session.getEffectiveTime(), "3 小时无人操作只应计入 25 分钟"); + assertEquals(Boolean.TRUE, session.getAutoConverged(), "应打上自动收敛标记以便前端提示"); + } + + /** + * 场景26:正常进行中的会话不受收敛逻辑影响 + */ + @Test + void forceConverge_freshOngoingSession_shouldBeNoop() { + StudySessionsEntity session = createOngoingSession(10); + + boolean converged = session.forceConverge(LocalDateTime.now(), StudyTimePolicy.DEFAULT); + + assertFalse(converged, "未超过硬兜底阈值不应收敛"); + assertEquals(StudySessionStateEnum.ONGOING.name(), session.getSessionState()); + assertNull(session.getEndTime()); + assertNull(session.getAutoConverged()); + } + + /** + * 场景27:已暂停/已结束的会话不是「进行中」,不参与收敛 + */ + @Test + void forceConverge_pausedSession_shouldBeNoop() { + StudySessionsEntity session = createOngoingSession(180); + session.pausedStudySession(null, StudyTimePolicy.DEFAULT); + double effectiveTimeAfterPause = session.getEffectiveTime(); + + boolean converged = session.forceConverge(LocalDateTime.now(), StudyTimePolicy.DEFAULT); + + assertFalse(converged); + assertEquals(StudySessionStateEnum.PAUSED.name(), session.getSessionState()); + assertEquals(effectiveTimeAfterPause, session.getEffectiveTime(), "已入账的时间不应被二次结算"); + } + + /** + * 场景28:慎忘判定用配置口径而不是写死的 50 分钟 + */ + @Test + void isForcePausable_usesConfiguredThreshold() { + StudySessionsEntity session = createOngoingSession(40); + // 收紧口径:番茄钟 10 分钟、遗忘判定 20 分钟、硬兜底 30 分钟 + StudyTimePolicy tightened = new StudyTimePolicy(10, 20, 30, 600); + + assertTrue(session.isForcePausable(LocalDateTime.now(), tightened), "40 分钟 > 配置的 30 分钟应可收敛"); + assertFalse(session.isForcePausable(LocalDateTime.now(), StudyTimePolicy.DEFAULT), "默认 120 分钟阈值下不应收敛"); + + session.forceConverge(LocalDateTime.now(), tightened); + assertEquals(10 * 60, session.getEffectiveTime(), "截断长度应取自配置的番茄钟长度"); + } + + /** + * 场景29:自定义口径的最小有效时间只在结束时生效,收敛本身不清零 + */ + @Test + void endedStudySession_usesConfiguredMinEffectiveTime() { + StudyTimePolicy tightened = new StudyTimePolicy(10, 20, 30, 5 * 60L); + // 已暂停的会话不再结算本段,只验证结束时的最小有效时间下限取自配置 + StudySessionsEntity session = createOngoingSession(12); + session.setSessionState(StudySessionStateEnum.PAUSED.name()); + session.setEffectiveTime(6 * 60); + + session.endedStudySession(tightened); + + assertEquals(6 * 60, session.getEffectiveTime(), "6 分钟高于配置的 5 分钟下限,不应清零"); + } } diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/StudySessionConvergenceIntegrationTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/StudySessionConvergenceIntegrationTest.java new file mode 100644 index 0000000..24c4d1a --- /dev/null +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/StudySessionConvergenceIntegrationTest.java @@ -0,0 +1,118 @@ +package com.guo.learningprogresstracker.service.impl; + +import cn.dev33.satoken.stp.StpUtil; +import com.baomidou.mybatisplus.core.toolkit.Wrappers; +import com.guo.learningprogresstracker.entity.StudySessionsEntity; +import com.guo.learningprogresstracker.enums.StudySessionStateEnum; +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 java.time.LocalDateTime; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertTrue; + +/** + * 悬挂会话收敛的落库集成测试(会话-04):验证惰性收敛与定时扫描在真实 SQL 下都成立, + * 并且正常进行中的会话与其他租户的会话不受影响。 + */ +@SpringBootTest +class StudySessionConvergenceIntegrationTest { + + private static final String USER_A = "会话收敛集成测试用户A"; + private static final String USER_B = "会话收敛集成测试用户B"; + + @Autowired + private StudySessionsServiceImpl studySessionsService; + + @BeforeEach + void setUp() { + StpUtil.login(USER_A, "test_device"); + } + + private StudySessionsEntity saveOngoingSession(int minutesAgo) { + StudySessionsEntity session = new StudySessionsEntity(); + session.setSessionNum(GenerateNumTool.generateNum("SESSIONCV")); + session.setTaskNum(GenerateNumTool.generateNum("TASKCV")); + session.setStartTime(LocalDateTime.now().minusMinutes(minutesAgo)); + session.setLastStartTime(LocalDateTime.now().minusMinutes(minutesAgo)); + session.setEffectiveTime(0); + session.setActualTime(0); + session.setSessionState(StudySessionStateEnum.ONGOING.name()); + assertTrue(studySessionsService.save(session), "测试会话应保存成功"); + return session; + } + + private StudySessionsEntity reload(String sessionNum) { + return studySessionsService.getOneOpt(Wrappers.lambdaQuery() + .eq(StudySessionsEntity::getSessionNum, sessionNum)).orElseThrow(); + } + + @Test + void lazyConvergence_threeHoursOngoing_shouldPauseTruncateAndMark() { + StudySessionsEntity session = saveOngoingSession(180); + + // 不访问该任务页面,只走「活跃会话」这个读取入口 + studySessionsService.getActiveSession(null); + + StudySessionsEntity reloaded = reload(session.getSessionNum()); + assertEquals(StudySessionStateEnum.PAUSED.name(), reloaded.getSessionState()); + assertEquals(1500, reloaded.getEffectiveTime(), 0.001, "3 小时无人操作只应计入 25 分钟"); + // 与落库后的 last_start_time 对齐比较(datetime 精度低于 LocalDateTime) + assertEquals(reloaded.getLastStartTime().plusMinutes(25), reloaded.getEndTime(), + "结算时间应截断为 last_start_time + 25 分钟"); + assertEquals(Boolean.TRUE, reloaded.getAutoConverged(), "应收敛为自动收敛以便前端提示"); + } + + @Test + void lazyConvergence_normalOngoingSession_shouldNotBeTouched() { + StudySessionsEntity session = saveOngoingSession(10); + + studySessionsService.getActiveSession(null); + + StudySessionsEntity reloaded = reload(session.getSessionNum()); + assertEquals(StudySessionStateEnum.ONGOING.name(), reloaded.getSessionState(), "正常进行中的会话不应被收敛"); + assertNull(reloaded.getEndTime()); + assertEquals(0, reloaded.getEffectiveTime(), 0.001); + } + + @Test + void lazyConvergence_shouldNotTouchOtherTenantSessions() { + StudySessionsEntity mine = saveOngoingSession(180); + + StpUtil.login(USER_B, "test_device"); + StudySessionsEntity others = saveOngoingSession(180); + studySessionsService.convergeStaleSessionsOfCurrentUser(); + + // 以自己的身份回看:自己的会话保持原样,别人的会话已被别人收敛 + StpUtil.login(USER_A, "test_device"); + assertEquals(StudySessionStateEnum.ONGOING.name(), reload(mine.getSessionNum()).getSessionState(), + "惰性收敛不能跨租户生效"); + + StpUtil.login(USER_B, "test_device"); + assertEquals(StudySessionStateEnum.PAUSED.name(), reload(others.getSessionNum()).getSessionState()); + } + + @Test + void scheduledScan_convergesWithoutAnyUserVisitAndIsIdempotent() { + StudySessionsEntity session = saveOngoingSession(300); + + assertTrue(studySessionsService.scanAndConvergeStaleSessions() >= 1, "定时扫描应至少收敛本用例的会话"); + + StudySessionsEntity afterFirstScan = reload(session.getSessionNum()); + assertEquals(StudySessionStateEnum.PAUSED.name(), afterFirstScan.getSessionState()); + assertEquals(1500, afterFirstScan.getEffectiveTime(), 0.001); + assertEquals(Boolean.TRUE, afterFirstScan.getAutoConverged()); + + // 再扫一次:该会话已不是 ONGOING,不应被重复结算 + studySessionsService.scanAndConvergeStaleSessions(); + StudySessionsEntity afterSecondScan = reload(session.getSessionNum()); + assertEquals(afterFirstScan.getEffectiveTime(), afterSecondScan.getEffectiveTime(), 0.001, + "重复扫描不应重复计入有效时间"); + assertEquals(afterFirstScan.getEndTime(), afterSecondScan.getEndTime()); + } +} diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/StudySessionsServiceImplTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/StudySessionsServiceImplTest.java index 3b1496e..4622e6c 100644 --- a/src/test/java/com/guo/learningprogresstracker/service/impl/StudySessionsServiceImplTest.java +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/StudySessionsServiceImplTest.java @@ -1,6 +1,7 @@ package com.guo.learningprogresstracker.service.impl; import com.baomidou.mybatisplus.core.conditions.Wrapper; +import com.guo.learningprogresstracker.common.StudyTimePolicy; import com.guo.learningprogresstracker.entity.StudyReportsEntity; import com.guo.learningprogresstracker.entity.StudySessionsEntity; import com.guo.learningprogresstracker.entity.TaskEntity; @@ -19,9 +20,11 @@ import org.mockito.Spy; import org.mockito.junit.jupiter.MockitoSettings; import org.mockito.quality.Strictness; import org.mockito.junit.jupiter.MockitoExtension; +import org.springframework.test.util.ReflectionTestUtils; import java.io.Serializable; import java.time.LocalDateTime; +import java.util.List; import java.util.Optional; import static org.junit.jupiter.api.Assertions.*; @@ -55,6 +58,10 @@ class StudySessionsServiceImplTest { @Mock private AiServiceClient aiServiceClient; + /** 时间口径用真实默认值,避免测试里出现 null 策略;需要改口径时换成自建实例即可 */ + @Spy + private StudyTimePolicy studyTimePolicy = StudyTimePolicy.DEFAULT; + @BeforeEach void setUp() { // stub updateById,避免调用真实的 getBaseMapper() @@ -63,6 +70,8 @@ class StudySessionsServiceImplTest { doReturn(true).when(studySessionsService).update(any(StudySessionsEntity.class), any(Wrapper.class)); // stub removeById,避免调用真实的 getBaseMapper() doReturn(true).when(studySessionsService).removeById(any(Serializable.class)); + // 收敛路径直接使用 ServiceImpl 的 baseMapper 字段,必须显式注入(Mockito 不会填父类字段) + ReflectionTestUtils.setField(studySessionsService, "baseMapper", studySessionsMapper); } private StudySessionsEntity createSession(String state, int minutesAgo) { @@ -411,4 +420,65 @@ class StudySessionsServiceImplTest { assertNull(message); verify(studyReportsMapper, never()).insert(any(StudyReportsEntity.class)); } + + // ============ 会话-04:悬挂会话收敛 ============ + + @Test + void convergeStaleSessionsOfCurrentUser_staleOngoing_shouldPauseTruncateAndMark() { + StudySessionsEntity stale = createSession(StudySessionStateEnum.ONGOING.name(), 180); + doReturn(List.of(stale)).when(studySessionsService).list(any(Wrapper.class)); + when(studySessionsMapper.convergeStaleSession(any())).thenReturn(1); + + int converged = studySessionsService.convergeStaleSessionsOfCurrentUser(); + + assertEquals(1, converged); + assertEquals(StudySessionStateEnum.PAUSED.name(), stale.getSessionState()); + assertEquals(25 * 60, stale.getEffectiveTime(), "悬挂 3 小时只应计入一个番茄钟"); + assertEquals(Boolean.TRUE, stale.getAutoConverged()); + } + + @Test + void convergeStaleSessionsOfCurrentUser_freshOngoing_shouldNotWrite() { + StudySessionsEntity fresh = createSession(StudySessionStateEnum.ONGOING.name(), 10); + doReturn(List.of(fresh)).when(studySessionsService).list(any(Wrapper.class)); + + int converged = studySessionsService.convergeStaleSessionsOfCurrentUser(); + + assertEquals(0, converged, "未超过硬兜底阈值不应收敛"); + assertEquals(StudySessionStateEnum.ONGOING.name(), fresh.getSessionState()); + verify(studySessionsMapper, never()).convergeStaleSession(any()); + } + + @Test + void convergeStaleSessionsOfCurrentUser_concurrentClaimLost_shouldCountZero() { + StudySessionsEntity stale = createSession(StudySessionStateEnum.ONGOING.name(), 180); + doReturn(List.of(stale)).when(studySessionsService).list(any(Wrapper.class)); + // 条件更新未命中:说明已被其他请求收敛 + when(studySessionsMapper.convergeStaleSession(any())).thenReturn(0); + + assertEquals(0, studySessionsService.convergeStaleSessionsOfCurrentUser()); + } + + @Test + void scanAndConvergeStaleSessions_shouldUseCrossTenantScan() { + StudySessionsEntity stale = createSession(StudySessionStateEnum.ONGOING.name(), 200); + when(studySessionsMapper.selectForcePausableSessions(any(), anyInt())).thenReturn(List.of(stale)); + when(studySessionsMapper.convergeStaleSession(any())).thenReturn(1); + + int converged = studySessionsService.scanAndConvergeStaleSessions(); + + assertEquals(1, converged); + assertEquals(Boolean.TRUE, stale.getAutoConverged()); + verify(studySessionsMapper).selectForcePausableSessions(any(), anyInt()); + } + + @Test + void getActiveSession_shouldRunLazyConvergenceFirst() { + when(studySessionsMapper.selectList(any())).thenReturn(List.of()); + + assertNull(studySessionsService.getActiveSession(null)); + + // 惰性收敛先按状态 + last_start_time 查一次悬挂会话 + verify(studySessionsMapper, atLeastOnce()).selectList(any()); + } } diff --git a/src/test/resources/application.yml b/src/test/resources/application.yml index e6aafe0..9359f04 100644 --- a/src/test/resources/application.yml +++ b/src/test/resources/application.yml @@ -16,6 +16,11 @@ mybatis-plus: configuration: log-impl: org.apache.ibatis.logging.nologging.NoLoggingImpl +# 测试环境关闭定时收敛:调度任务会与用例自己造的悬挂会话互相干扰 +lpt: + study-time: + scan-enabled: false + # 测试环境不激活 profile,而 src/test/resources/application.yml 会遮蔽 src/main/resources/application.yml, # 因此这里必须显式声明 cors 配置,否则 WebMvcConfig 会因 allowedOrigins 为 null 抛 NPE cors: