fix: 统一学习会话结算并修正结束幂等
This commit is contained in:
@@ -0,0 +1,36 @@
|
||||
package com.guo.learningprogresstracker.common;
|
||||
|
||||
/**
|
||||
* 学习会话的时间口径常量。
|
||||
*
|
||||
* <p>番茄钟长度、遗忘判定阈值与有效时间下限集中在此处定义,避免阈值散落在实体与服务的各个角落。
|
||||
* 修改口径时只改这里,不要就地写死数字。</p>
|
||||
*/
|
||||
public final class StudyTimePolicy {
|
||||
|
||||
/**
|
||||
* 番茄钟长度(分钟)。
|
||||
*/
|
||||
public static final int WORK_DURATION_MINUTES = 25;
|
||||
|
||||
/**
|
||||
* 番茄钟长度(毫秒)。
|
||||
*/
|
||||
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() {
|
||||
}
|
||||
}
|
||||
@@ -5,6 +5,7 @@ import com.baomidou.mybatisplus.annotation.TableField;
|
||||
import com.baomidou.mybatisplus.annotation.TableId;
|
||||
import com.baomidou.mybatisplus.annotation.TableName;
|
||||
import com.google.protobuf.ServiceException;
|
||||
import com.guo.learningprogresstracker.common.StudyTimePolicy;
|
||||
import com.guo.learningprogresstracker.enums.StudySessionStateEnum;
|
||||
import com.guo.learningprogresstracker.utils.GenerateNumTool;
|
||||
import lombok.Data;
|
||||
@@ -15,8 +16,6 @@ import java.io.Serializable;
|
||||
import java.time.Duration;
|
||||
import java.time.LocalDateTime;
|
||||
|
||||
import static com.guo.learningprogresstracker.service.impl.StudySessionsServiceImpl.WORK_DURATION;
|
||||
|
||||
/**
|
||||
* 记录每次学习会话的具体数据
|
||||
* @TableName study_sessions
|
||||
@@ -96,7 +95,7 @@ public class StudySessionsEntity extends BaseEntity implements Serializable {
|
||||
studySessionsEntity.setSessionNum(GenerateNumTool.generateNum("SESSION"));
|
||||
studySessionsEntity.setStartTime(LocalDateTime.now());
|
||||
studySessionsEntity.setLastStartTime(LocalDateTime.now());
|
||||
studySessionsEntity.setPointerPosition(WORK_DURATION * 60 * 1000L);
|
||||
studySessionsEntity.setPointerPosition(StudyTimePolicy.WORK_DURATION_MILLIS);
|
||||
studySessionsEntity.setLastModifiedTime(LocalDateTime.now());
|
||||
studySessionsEntity.setSessionState(StudySessionStateEnum.ONGOING.name());
|
||||
return studySessionsEntity;
|
||||
@@ -124,7 +123,8 @@ public class StudySessionsEntity extends BaseEntity implements Serializable {
|
||||
if (this.getSessionState().equals(StudySessionStateEnum.PAUSED.name())) {
|
||||
log.warn("不应出现的情况:暂停了一个状态为【{}】的学习会话({})", this.getSessionState(), this.getSessionNum());
|
||||
} else {
|
||||
this.setEndTime(ObjectUtils.isEmpty(endTime) ? LocalDateTime.now() : endTime);
|
||||
LocalDateTime settlementTime = this.resolveSettlementTime(endTime);
|
||||
this.setEndTime(settlementTime);
|
||||
this.setActualTime(Duration.between(this.startTime, this.endTime).toSeconds());
|
||||
this.setEffectiveTime(this.getEffectiveTime() + Duration.between(this.lastStartTime, this.endTime).toSeconds());
|
||||
this.setEffectivenessRatio(this.effectiveTime / this.actualTime);
|
||||
@@ -133,21 +133,37 @@ public class StudySessionsEntity extends BaseEntity implements Serializable {
|
||||
}
|
||||
|
||||
/**
|
||||
* 有效学习时间的最小阈值(秒),低于此值不计入总学习时间
|
||||
* 计算本次学习分段的结算时间:暂停、结束与超时收敛都必须走这里,避免同一行为产生两种统计结果。
|
||||
*
|
||||
* <p>{@code lastStartTime} 到候选结束时间超过遗忘判定阈值
|
||||
* ({@link StudyTimePolicy#FORGET_THRESHOLD_MINUTES})时,按「忘了点暂停/结束」处理,
|
||||
* 只结算一个番茄钟({@link StudyTimePolicy#WORK_DURATION_MINUTES} 分钟);否则按候选结束时间结算。</p>
|
||||
*/
|
||||
private static final double MIN_EFFECTIVE_TIME_SECONDS = 10 * 60;
|
||||
public LocalDateTime resolveSettlementTime(LocalDateTime candidateEndTime) {
|
||||
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) {
|
||||
log.info("会话[{}]本段学习已超过{}分钟无操作,按{}分钟结算",
|
||||
this.getSessionNum(), StudyTimePolicy.FORGET_THRESHOLD_MINUTES, StudyTimePolicy.WORK_DURATION_MINUTES);
|
||||
return this.lastStartTime.plusMinutes(StudyTimePolicy.WORK_DURATION_MINUTES);
|
||||
}
|
||||
return end;
|
||||
}
|
||||
|
||||
/**
|
||||
* 结束会话
|
||||
*/
|
||||
public void endedStudySession() {
|
||||
if (this.getSessionState().equals(StudySessionStateEnum.ENDED.name())){
|
||||
if (this.isEnded()){
|
||||
log.warn("不应出现的情况:结束了一个状态为【{}】的学习会话",this.getSessionState());
|
||||
}else {
|
||||
if (this.getSessionState().equals(StudySessionStateEnum.ONGOING.name())) {
|
||||
this.pausedStudySession(LocalDateTime.now());
|
||||
}
|
||||
if (this.getEffectiveTime() < MIN_EFFECTIVE_TIME_SECONDS) {
|
||||
if (this.getEffectiveTime() < StudyTimePolicy.MIN_EFFECTIVE_TIME_SECONDS) {
|
||||
log.info("会话[{}]有效学习时间({}秒)不足10分钟,不计入总学习时间", this.getSessionNum(), this.getEffectiveTime());
|
||||
this.setEffectiveTime(0);
|
||||
this.setEffectivenessRatio(0);
|
||||
@@ -178,7 +194,7 @@ public class StudySessionsEntity extends BaseEntity implements Serializable {
|
||||
*/
|
||||
public void calculatePointerPosition() throws ServiceException {
|
||||
if (isFirstRun()) {
|
||||
this.pointerPosition = WORK_DURATION * 60 * 1000L; // 毫秒
|
||||
this.pointerPosition = StudyTimePolicy.WORK_DURATION_MILLIS; // 毫秒
|
||||
return;
|
||||
}
|
||||
|
||||
@@ -193,12 +209,12 @@ public class StudySessionsEntity extends BaseEntity implements Serializable {
|
||||
case ONGOING:
|
||||
long elapsedMillis = Duration.between(lastStartTime, LocalDateTime.now()).toMillis();
|
||||
long basePointerPosition = ObjectUtils.isEmpty(pointerPosition)
|
||||
? WORK_DURATION * 60 * 1000L
|
||||
? StudyTimePolicy.WORK_DURATION_MILLIS
|
||||
: pointerPosition;
|
||||
long newPointerPosition = basePointerPosition - elapsedMillis;
|
||||
if (newPointerPosition <= 0) {
|
||||
// 如果循环已经结束,则需要重置指针位置
|
||||
this.pointerPosition = WORK_DURATION * 60 * 1000L;
|
||||
this.pointerPosition = StudyTimePolicy.WORK_DURATION_MILLIS;
|
||||
} else {
|
||||
this.pointerPosition = newPointerPosition;
|
||||
}
|
||||
@@ -218,9 +234,33 @@ public class StudySessionsEntity extends BaseEntity implements Serializable {
|
||||
}
|
||||
|
||||
|
||||
public boolean isOverTime() {
|
||||
LocalDateTime now = LocalDateTime.now();
|
||||
long minutes = Duration.between(ObjectUtils.isEmpty(lastStartTime) ? LocalDateTime.now() : lastStartTime, now).toMinutes();
|
||||
return minutes >= WORK_DURATION * 2;
|
||||
/**
|
||||
* 学习会话是否已经结束。
|
||||
*/
|
||||
public boolean isEnded() {
|
||||
return StudySessionStateEnum.ENDED.name().equals(this.sessionState);
|
||||
}
|
||||
|
||||
/**
|
||||
* 本段学习是否已判定为「忘了点暂停/结束」,即需要按遗忘规则截断。
|
||||
*
|
||||
* <p>只有进行中的会话才成立:暂停与已结束的会话,其时间已在结算时入账,再次截断会重复扣减。
|
||||
* 同时要求本段尚未结算过({@code end_time} 不早于 {@code last_start_time} 时视为已结算)。</p>
|
||||
*/
|
||||
public boolean isForgotten() {
|
||||
return isForgotten(LocalDateTime.now());
|
||||
}
|
||||
|
||||
public boolean isForgotten(LocalDateTime now) {
|
||||
if (!StudySessionStateEnum.ONGOING.name().equals(this.sessionState)) {
|
||||
return false;
|
||||
}
|
||||
if (ObjectUtils.isEmpty(this.lastStartTime)) {
|
||||
return false;
|
||||
}
|
||||
if (!ObjectUtils.isEmpty(this.endTime) && !this.endTime.isBefore(this.lastStartTime)) {
|
||||
return false;
|
||||
}
|
||||
return Duration.between(this.lastStartTime, now).toMinutes() >= StudyTimePolicy.FORGET_THRESHOLD_MINUTES;
|
||||
}
|
||||
}
|
||||
|
||||
+27
-7
@@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.core.toolkit.Wrappers;
|
||||
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
|
||||
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
|
||||
import com.google.protobuf.ServiceException;
|
||||
import com.guo.learningprogresstracker.common.StudyTimePolicy;
|
||||
import com.guo.learningprogresstracker.dto.StudySessionsDto;
|
||||
import com.guo.learningprogresstracker.dto.response.StudySessionResponse;
|
||||
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
|
||||
@@ -38,8 +39,6 @@ import java.util.stream.Collectors;
|
||||
public class StudySessionsServiceImpl extends ServiceImpl<StudySessionsMapper, StudySessionsEntity>
|
||||
implements StudySessionsService {
|
||||
|
||||
public static final int WORK_DURATION = 25;
|
||||
|
||||
/**
|
||||
* 误操作结束的确认语:用户必须输入完全一致的内容才能零数据关闭会话
|
||||
*/
|
||||
@@ -74,8 +73,10 @@ public class StudySessionsServiceImpl extends ServiceImpl<StudySessionsMapper, S
|
||||
|
||||
session.calculatePointerPosition();
|
||||
|
||||
if (session.isOverTime()) {
|
||||
session.pausedStudySession(session.getLastStartTime().plusMinutes(WORK_DURATION));
|
||||
// 只有进行中且本段尚未结算的会话才需要收敛;已暂停/已结束的会话不再重复截断
|
||||
boolean forgotten = session.isForgotten();
|
||||
if (forgotten) {
|
||||
session.pausedStudySession(null);
|
||||
this.updateById(session);
|
||||
}
|
||||
|
||||
@@ -84,8 +85,10 @@ public class StudySessionsServiceImpl extends ServiceImpl<StudySessionsMapper, S
|
||||
response.setMaterialUrl(taskEntity.getMaterialUrl());
|
||||
response.setTaskId(taskEntity.getId());
|
||||
|
||||
if (session.isOverTime()) {
|
||||
response.setSystemMessage("上段学习任务已经超时25分钟,将仅计算为25分钟的有效学习时间,请注意休息!");
|
||||
if (forgotten) {
|
||||
response.setSystemMessage(String.format(
|
||||
"上段学习已超过%d分钟没有任何操作,仅计算为%d分钟的有效学习时间,请注意休息!",
|
||||
StudyTimePolicy.FORGET_THRESHOLD_MINUTES, StudyTimePolicy.WORK_DURATION_MINUTES));
|
||||
}
|
||||
|
||||
return response;
|
||||
@@ -113,9 +116,26 @@ public class StudySessionsServiceImpl extends ServiceImpl<StudySessionsMapper, S
|
||||
StudySessionsEntity studySessionsEntity = this.getOneOpt(Wrappers.lambdaQuery(StudySessionsEntity.class)
|
||||
.eq(StudySessionsEntity::getSessionNum, sessionNum))
|
||||
.orElseThrow(() -> sessionNotFound(sessionNum));
|
||||
|
||||
// 幂等:已结束的会话不再重复结算,也不会重复生成学习报告
|
||||
if (studySessionsEntity.isEnded()) {
|
||||
log.warn("会话[{}]已结束,本次结束请求按幂等处理,不重复生成学习报告", sessionNum);
|
||||
return null;
|
||||
}
|
||||
|
||||
boolean wasOngoing = StudySessionStateEnum.ONGOING.name().equals(studySessionsEntity.getSessionState());
|
||||
studySessionsEntity.endedStudySession();
|
||||
this.updateById(studySessionsEntity);
|
||||
|
||||
// 条件更新:只有数据库中仍未结束的会话才会被写入结算结果,
|
||||
// 避免重复点击/网络重试等并发请求各自插入一条学习报告
|
||||
boolean ended = this.update(studySessionsEntity, Wrappers.<StudySessionsEntity>lambdaUpdate()
|
||||
.eq(StudySessionsEntity::getId, studySessionsEntity.getId())
|
||||
.ne(StudySessionsEntity::getSessionState, StudySessionStateEnum.ENDED.name()));
|
||||
if (!ended) {
|
||||
log.warn("会话[{}]已被其他请求结束,本次不重复生成学习报告", sessionNum);
|
||||
return null;
|
||||
}
|
||||
|
||||
StudyReportsEntity studyReportsEntity = new StudyReportsEntity();
|
||||
studyReportsEntity.setSessionNum(sessionNum);
|
||||
studyReportsEntity.setContent(content);
|
||||
|
||||
Reference in New Issue
Block a user