feat: 悬挂学习会话惰性收敛与定时兜底

This commit is contained in:
2026-10-09 12:32:11 +08:00
parent faaaa132c1
commit db552182ae
17 changed files with 712 additions and 65 deletions
@@ -1,36 +1,64 @@
package com.guo.learningprogresstracker.common;
import lombok.Getter;
/**
* 学习会话的时间口径常量。
* 学习会话的时间口径(会话-04 起改为可配置的值对象)。
*
* <p>番茄钟长度、遗忘判定阈值与有效时间下限集中在此处定义,避免阈值散落在实体与服务的各个角落。
* 修改口径时只改这里,不要就地写死数字。</p>
* <p>番茄钟长度、遗忘判定阈值、硬兜底阈值与有效时间下限集中在此处,避免阈值散落在实体与服务的各个角落。
* 生产路径由 Spring 从 {@code lpt.study-time} 配置构建并注入;{@link #DEFAULT} 只保留设计口径的默认值,
* 供实体自身的默认重载与单测使用,不要在服务里直接用它。</p>
*/
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 × 番茄钟。
*
* <p>最后一段学习在超过该时长后仍没有任何操作,判定为「忘了点暂停/结束」,
* 该段只按一个番茄钟结算(见 {@code StudySessionsEntity#resolveSettlementTime})。</p>
*/
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;
}
}