feat: 新增复习耗时统计与按任务汇总

This commit is contained in:
2026-10-09 11:12:37 +08:00
parent af13bd57b7
commit 3b33cd8396
14 changed files with 373 additions and 6 deletions
@@ -2,6 +2,7 @@ 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;
@@ -126,7 +127,10 @@ public class ReviewController {
public CommonResult<ReviewStandardMindMapEntity> recallCompare(
@PathVariable String taskNum,
@Valid @RequestBody RecallCompareRequest request) throws NotFindEntitiesException, OperationFailedException {
return CommonResult.success(standardMindMapService.recallCompare(taskNum, request.getRecallOutline(), request.getFocusPath()));
return CommonResult.success(standardMindMapService.recallCompare(
taskNum, request.getRecallOutline(), request.getFocusPath(),
new ReviewTiming(request.getReviewStartedAt(), request.getReviewLastInteractionAt(),
request.getReviewDurationSeconds())));
}
/**
@@ -17,4 +17,6 @@ public class ReviewTaskStats {
private double weekEffectiveTime;
private double avgEffectiveTime;
private double avgEffectivenessRatio;
/** 该任务累计复习耗时(秒):来自回忆对比等复习行为,与学习时长独立统计 */
private long reviewDurationSeconds;
}
@@ -0,0 +1,15 @@
package com.guo.learningprogresstracker.dto;
import java.time.LocalDateTime;
/**
* 一次复习行为的计时信息(复习-07)。
* <p>由前端上报:复习行为开始时刻、最近一次交互时刻、以及按 5 分钟空闲截断后的净耗时。
* 三个字段都可空;服务端会用 {@code utils.ReviewDurationTool} 统一结算并落库。</p>
*
* @param startedAt 行为开始时刻
* @param lastInteractionAt 最近一次交互时刻
* @param durationSeconds 前端结算出的净耗时(秒)
*/
public record ReviewTiming(LocalDateTime startedAt, LocalDateTime lastInteractionAt, Integer durationSeconds) {
}
@@ -1,8 +1,11 @@
package com.guo.learningprogresstracker.dto.request;
import com.fasterxml.jackson.annotation.JsonFormat;
import jakarta.validation.constraints.NotBlank;
import lombok.Data;
import java.time.LocalDateTime;
/**
* 用户回忆对比请求
*/
@@ -14,4 +17,15 @@ public class RecallCompareRequest {
/** 复习起点节点路径(以 / 分隔),null 为任务维度 */
private String focusPath;
/** 本次回忆复习开始时刻(本地时间),复习-07 */
@JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss")
private LocalDateTime reviewStartedAt;
/** 最近一次交互时刻(本地时间),供服务端按 5 分钟空闲截断,复习-07 */
@JsonFormat(pattern = "yyyy-MM-dd'T'HH:mm:ss")
private LocalDateTime reviewLastInteractionAt;
/** 前端按 5 分钟空闲截断后的净耗时(秒),复习-07 */
private Integer reviewDurationSeconds;
}
@@ -57,6 +57,12 @@ public class ReviewRecallRecordEntity extends BaseEntity implements Serializable
@TableField(value = "extra_count")
private Integer extraCount;
/**
* 本次复习耗时(秒),已按「超过 5 分钟无交互则截断」规则结算
*/
@TableField(value = "review_duration_seconds")
private Integer reviewDurationSeconds;
@TableField(exist = false)
private static final long serialVersionUID = 1L;
}
@@ -1,5 +1,6 @@
package com.guo.learningprogresstracker.service;
import com.guo.learningprogresstracker.dto.ReviewTiming;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.ReviewStandardMindMapEntity;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
@@ -39,8 +40,10 @@ public interface StandardMindMapService {
*
* @param recallOutline 用户回忆的缩进大纲文本
* @param focusPath 可选:标准导图中的节点路径(/ 分隔),指定后仅对比该子树
* @param timing 可选:本次复习行为的计时信息(复习-07),为空时不计复习耗时
*/
ReviewStandardMindMapEntity recallCompare(String taskNum, String recallOutline, String focusPath) throws NotFindEntitiesException, OperationFailedException;
ReviewStandardMindMapEntity recallCompare(String taskNum, String recallOutline, String focusPath,
ReviewTiming timing) throws NotFindEntitiesException, OperationFailedException;
/**
* 根据内容文本在标准导图中查找最匹配的节点,返回节点路径。
@@ -378,6 +378,45 @@ public class ReviewServiceImpl implements ReviewService {
});
fillReportAndFragmentCount(sessionToTaskNum, statsByTaskNum);
fillReviewDuration(statsByTaskNum);
}
/**
* 按任务汇总复习行为累计耗时(复习-07)。在 SQL 侧聚合,只把任务数量的行拉回内存,
* 不随回忆记录条数增长。
*/
private void fillReviewDuration(Map<String, ReviewTaskStats> statsByTaskNum) {
List<Map<String, Object>> rows = reviewRecallRecordMapper.selectMaps(
Wrappers.<ReviewRecallRecordEntity>query()
.select("task_num AS taskNum",
"COALESCE(SUM(review_duration_seconds), 0) AS reviewDurationSeconds")
.in("task_num", statsByTaskNum.keySet())
.groupBy("task_num"));
for (Map<String, Object> row : rows) {
Object taskNum = columnValue(row, "taskNum");
Object duration = columnValue(row, "reviewDurationSeconds");
ReviewTaskStats stats = taskNum == null ? null : statsByTaskNum.get(taskNum.toString());
if (stats != null && duration instanceof Number number) {
stats.setReviewDurationSeconds(number.longValue());
}
}
}
/**
* 取聚合结果的列:别名大小写随数据库实现不同(MySQL 保留、H2 会转为小写),这里统一不区分大小写。
*/
private static Object columnValue(Map<String, Object> row, String column) {
Object direct = row.get(column);
if (direct != null) {
return direct;
}
for (Map.Entry<String, Object> entry : row.entrySet()) {
if (entry.getKey() != null && entry.getKey().equalsIgnoreCase(column)) {
return entry.getValue();
}
}
return null;
}
private void fillReportAndFragmentCount(Map<String, String> sessionToTaskNum,
@@ -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.ReviewTiming;
import com.guo.learningprogresstracker.entity.*;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.exception.OperationFailedException;
@@ -12,6 +13,7 @@ import com.guo.learningprogresstracker.service.StandardMindMapService;
import com.guo.learningprogresstracker.utils.CompareResult;
import com.guo.learningprogresstracker.utils.MindMapNode;
import com.guo.learningprogresstracker.utils.MindMapTreeTool;
import com.guo.learningprogresstracker.utils.ReviewDurationTool;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
@@ -152,7 +154,8 @@ public class StandardMindMapServiceImpl implements StandardMindMapService {
@Override
@Transactional
public ReviewStandardMindMapEntity recallCompare(String taskNum, String recallOutline, String focusPath)
public ReviewStandardMindMapEntity recallCompare(String taskNum, String recallOutline, String focusPath,
ReviewTiming timing)
throws NotFindEntitiesException, OperationFailedException {
ensureTaskExists(taskNum);
@@ -216,11 +219,16 @@ public class StandardMindMapServiceImpl implements StandardMindMapService {
record.setMatchedCount(result.getMatchedCount());
record.setMissedCount(result.getMissedCount());
record.setExtraCount(result.getExtraCount());
record.setReviewDurationSeconds(ReviewDurationTool.resolveSeconds(
timing == null ? null : timing.startedAt(),
timing == null ? null : timing.lastInteractionAt(),
timing == null ? null : timing.durationSeconds(),
LocalDateTime.now()));
recallRecordMapper.insert(record);
log.info("回忆对比: taskNum={}, recallRatio={}, matched={}, missed={}, extra={}",
log.info("回忆对比: taskNum={}, recallRatio={}, matched={}, missed={}, extra={}, 复习耗时={}秒",
taskNum, result.getRecallRatio(), result.getMatchedCount(),
result.getMissedCount(), result.getExtraCount());
result.getMissedCount(), result.getExtraCount(), record.getReviewDurationSeconds());
return standard;
}
@@ -0,0 +1,51 @@
package com.guo.learningprogresstracker.utils;
import java.time.Duration;
import java.time.LocalDateTime;
/**
* 复习耗时结算工具(复习-07)。
* <p>口径见 lpt-docs/docs/concepts/time-and-efficiency.md:复习耗时从复习行为开始结算到结束,
* 超过 {@link #IDLE_WINDOW_SECONDS} 没有交互则截断到上一次交互时间;复习没有暂停动作,
* 也不套用学习会话的 10 分钟最小阈值。</p>
*/
public final class ReviewDurationTool {
/** 空闲截断窗口:超过该时长无交互,之后的时间不计入本次复习耗时 */
public static final long IDLE_WINDOW_SECONDS = 5 * 60L;
private ReviewDurationTool() {
}
/**
* 结算一次复习行为的净耗时(秒)。
*
* @param startedAt 行为开始时刻,为空表示前端未计时,返回 0
* @param lastInteractionAt 最近一次交互时刻,为空表示无法判断是否挂机
* @param reportedSeconds 前端按空闲截断后上报的耗时,为空时用服务端按墙钟推算的值
* @param now 服务端当前时刻
* @return 净耗时秒数,恒 &gt;= 0,且不超过「开始时刻到 now」的墙钟跨度
*/
public static int resolveSeconds(LocalDateTime startedAt, LocalDateTime lastInteractionAt,
Integer reportedSeconds, LocalDateTime now) {
if (startedAt == null || now == null) {
return 0;
}
long elapsedSeconds = Duration.between(startedAt, now).getSeconds();
if (elapsedSeconds <= 0) {
return 0;
}
long maxSeconds = elapsedSeconds;
if (lastInteractionAt != null && lastInteractionAt.isAfter(startedAt) && !lastInteractionAt.isAfter(now)) {
long idleSeconds = Duration.between(lastInteractionAt, now).getSeconds();
if (idleSeconds > IDLE_WINDOW_SECONDS) {
// 挂机超过窗口:耗时截断到上一次交互时间
maxSeconds = Math.min(maxSeconds, Duration.between(startedAt, lastInteractionAt).getSeconds());
}
}
long reported = reportedSeconds == null ? maxSeconds : Math.max(0L, reportedSeconds);
return (int) Math.min(Math.min(reported, maxSeconds), Integer.MAX_VALUE);
}
}
@@ -0,0 +1,10 @@
-- 复习耗时(复习-07):回忆对比行为记录本次净耗时,单位秒。
-- 口径见 lpt-docs/docs/concepts/time-and-efficiency.md:耗时只覆盖复习行为(回忆对比、学习引导),
-- 超过 5 分钟无交互则截断到上一次交互时间;学习引导复用同一字段。
-- 对应清单条目:复习-07。
ALTER TABLE review_recall_records
ADD COLUMN review_duration_seconds INT DEFAULT 0 NOT NULL COMMENT '本次复习耗时(秒),已按 5 分钟空闲截断' AFTER extra_count;
-- 复习总览按任务聚合复习耗时:WHERE created_by = ? AND task_num IN (...) GROUP BY task_num
CREATE INDEX idx_recall_records_created_by_task ON review_recall_records (created_by, task_num);