feat: 新增复习反馈动作与排序三档偏好

This commit is contained in:
2026-10-09 19:21:26 +08:00
parent 1a99263876
commit 63824b26a0
13 changed files with 540 additions and 10 deletions
@@ -1,9 +1,11 @@
package com.guo.learningprogresstracker.controller;
import com.guo.learningprogresstracker.dto.ReviewFeedItem;
import com.guo.learningprogresstracker.dto.ReviewSortPreference;
import com.guo.learningprogresstracker.dto.ReviewTaskStats;
import com.guo.learningprogresstracker.dto.StudyReportDetail;
import com.guo.learningprogresstracker.dto.request.UpdateStandardMindMapRequest;
import com.guo.learningprogresstracker.dto.request.ReviewFeedbackRequest;
import com.guo.learningprogresstracker.dto.request.UpdateStudyReportRequest;
import com.guo.learningprogresstracker.entity.CommonResult;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
@@ -45,6 +47,43 @@ public class ReviewController {
return CommonResult.success(reviewService.getReviewFeed(limit, mode));
}
/**
* 提交复习反馈动作(复习-02):标记或取消「已掌握」「稍后再看」。
* <p>只调整出现概率,不产生状态展示、不统计总数、不做待复习列表。</p>
*/
@PutMapping("/feed/{fragmentId}/feedback")
public CommonResult<ReviewFeedbackRequest> submitFeedback(
@PathVariable Integer fragmentId,
@RequestBody ReviewFeedbackRequest request) throws NotFindEntitiesException {
return CommonResult.success(reviewService.submitFeedback(fragmentId, request));
}
/**
* 记录一次「接触」(展开查看 / 进入回忆对比时调用):刷新最近接触时间,作为排序的第三个信号。
*/
@PostMapping("/feed/{fragmentId}/touched")
public CommonResult<Void> touchFragment(@PathVariable Integer fragmentId) throws NotFindEntitiesException {
reviewService.touchFragment(fragmentId);
return CommonResult.success();
}
/**
* 读取复习排序偏好(复习-01)
*/
@GetMapping("/sort-preference")
public CommonResult<ReviewSortPreference> getSortPreference() {
return CommonResult.success(reviewService.getSortPreference());
}
/**
* 保存复习排序偏好(复习-01):三档预设,不做精确权重。
*/
@PutMapping("/sort-preference")
public CommonResult<ReviewSortPreference> saveSortPreference(@RequestBody Map<String, String> body) {
String preset = body == null ? null : body.get("preset");
return CommonResult.success(reviewService.saveSortPreference(preset));
}
/**
* 获取任务维度的复习统计汇总
*/
@@ -39,4 +39,17 @@ public class ReviewFeedItem {
/** 记录上下文编号:学习会话编号或复习行为编号 */
private String contextNum;
/**
* 反馈与接触时间只参与排序计算,<b>不用于列表展示</b>:
* 复习反馈刻意不产生状态展示,否则会把复习拖回清单模式(复习-02)。
*/
@com.fasterxml.jackson.annotation.JsonIgnore
private Boolean mastered;
@com.fasterxml.jackson.annotation.JsonIgnore
private Boolean revisit;
@com.fasterxml.jackson.annotation.JsonIgnore
private LocalDateTime lastReviewedTime;
}
@@ -0,0 +1,21 @@
package com.guo.learningprogresstracker.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
/**
* 复习排序偏好(复习-01):对外暴露档位与可选项,避免前端硬编码文案。
*/
@Data
@NoArgsConstructor
@AllArgsConstructor
public class ReviewSortPreference {
@Schema(description = "当前档位:TIME_FIRST / BALANCED / MASTERY_FIRST")
private String preset;
@Schema(description = "档位的中文说明")
private String description;
}
@@ -0,0 +1,20 @@
package com.guo.learningprogresstracker.dto.request;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
/**
* 复习反馈动作(复习-02)。
*
* <p>两个动作都只调整内容的出现概率,不产生状态展示、不统计总数、不做待复习列表。
* 传 null 表示本次不改该动作。</p>
*/
@Data
public class ReviewFeedbackRequest {
@Schema(description = "标记/取消「已掌握」:降低出现概率但不归零")
private Boolean mastered;
@Schema(description = "标记/取消「稍后再看」:提高出现概率")
private Boolean revisit;
}
@@ -45,6 +45,25 @@ public class StudyReportFragmentsEntity extends BaseEntity implements Serializab
@TableField(value = "owner_task_num")
private String ownerTaskNum;
/**
* 用户标记「已掌握」:降低出现概率但不归零(复习-02)。
* <p>刻意不进标记表——文档明确「标记不是状态」,流程性判断留在主体上。</p>
*/
@TableField(value = "mastered")
private Boolean mastered;
/**
* 用户标记「稍后再看」:提高出现概率(复习-02)
*/
@TableField(value = "revisit")
private Boolean revisit;
/**
* 最近一次接触时间(展开查看 / 进入回忆对比时刷新),智能排序的第三个信号(复习-02)
*/
@TableField(value = "last_reviewed_time")
private java.time.LocalDateTime lastReviewedTime;
@TableField(value = "content")
private String content;
@@ -0,0 +1,27 @@
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 lombok.Data;
import java.io.Serializable;
/**
* 复习排序偏好(复习-01):每个用户一条,保存三档预设之一。
*/
@TableName(value = "user_review_preferences")
@Data
public class UserReviewPreferencesEntity extends BaseEntity implements Serializable {
@TableId(value = "id", type = IdType.AUTO)
private Integer id;
/** 取值见 {@code ReviewSortPresetEnum} */
@TableField(value = "sort_preset")
private String sortPreset;
@TableField(exist = false)
private static final long serialVersionUID = 1L;
}
@@ -0,0 +1,51 @@
package com.guo.learningprogresstracker.enums;
import lombok.AllArgsConstructor;
import lombok.Getter;
/**
* 复习智能排序的信号强度预设(复习-01)。
*
* <p>排序把「多久没接触」与「任务掌握度」两个因子相乘。给用户精确百分比是假精度,
* 因此只提供三个语义档位,覆盖两种真实诉求:内容太旧、或总给自己看已经熟的。</p>
*
* <p>系数含义:</p>
* <ul>
* <li>{@code ageInfluence}:时间效应强度。时间因子 = (1 - 强度) + 进度 × 强度,故强度越大越区分新旧。</li>
* <li>{@code masteryInfluence}:掌握度强度。掌握度因子 = 1 - 覆盖率 × 强度,故强度越大越惩罚低覆盖率。</li>
* </ul>
*/
@Getter
@AllArgsConstructor
public enum ReviewSortPresetEnum {
/** 时间为主(默认):久未接触的内容更容易出现,符合「时间效应为主、掌握度为辅」的默认口径 */
TIME_FIRST("时间为主", 0.7, 0.5),
/** 均衡:两个信号影响相当 */
BALANCED("均衡", 0.5, 0.5),
/** 掌握度为主:回忆覆盖率低的任务内容明显更容易出现 */
MASTERY_FIRST("掌握度为主", 0.5, 0.9);
/** 默认档位 */
public static final ReviewSortPresetEnum DEFAULT = TIME_FIRST;
private final String description;
private final double ageInfluence;
private final double masteryInfluence;
/**
* 宽松解析:未知或空值一律回落到默认档位(避免因为一个存坏的配置让 Feed 直接报错)。
*/
public static ReviewSortPresetEnum parse(String value) {
if (value == null || value.isBlank()) {
return DEFAULT;
}
try {
return valueOf(value.trim().toUpperCase());
} catch (IllegalArgumentException e) {
return DEFAULT;
}
}
}
@@ -0,0 +1,9 @@
package com.guo.learningprogresstracker.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.guo.learningprogresstracker.entity.UserReviewPreferencesEntity;
import org.apache.ibatis.annotations.Mapper;
@Mapper
public interface UserReviewPreferencesMapper extends BaseMapper<UserReviewPreferencesEntity> {
}
@@ -57,6 +57,28 @@ public interface ReviewService {
*/
void deleteReport(int id) throws NotFindEntitiesException;
/**
* 提交复习反馈动作(复习-02):标记或取消「已掌握」「稍后再看」。
* <p>只调整出现概率,不产生状态展示。</p>
*
* @return 动作之后的反馈状态,供前端在本次浏览中切换按钮
*/
com.guo.learningprogresstracker.dto.request.ReviewFeedbackRequest submitFeedback(
Integer fragmentId, com.guo.learningprogresstracker.dto.request.ReviewFeedbackRequest request)
throws NotFindEntitiesException;
/**
* 记录一次「接触」:刷新最近接触时间,作为智能排序的第三个信号(复习-02)。
* <p>展开查看与进入回忆对比都会调用;本身不产生额外数据。</p>
*/
void touchFragment(Integer fragmentId) throws NotFindEntitiesException;
/** 读取复习排序偏好,未设置时返回默认档位(复习-01) */
com.guo.learningprogresstracker.dto.ReviewSortPreference getSortPreference();
/** 保存复习排序偏好(复习-01) */
com.guo.learningprogresstracker.dto.ReviewSortPreference saveSortPreference(String preset);
/**
* 获取残片详情
*/
@@ -10,17 +10,22 @@ import com.guo.learningprogresstracker.dto.TaskContentCount;
import com.guo.learningprogresstracker.dto.TaskReviewDuration;
import com.guo.learningprogresstracker.dto.TaskSessionStats;
import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity;
import com.guo.learningprogresstracker.entity.UserReviewPreferencesEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.StudyReportsEntity;
import com.guo.learningprogresstracker.entity.StudySessionsEntity;
import com.guo.learningprogresstracker.entity.TaskEntity;
import com.guo.learningprogresstracker.enums.FragmentContextTypeEnum;
import com.guo.learningprogresstracker.enums.ReviewSortPresetEnum;
import com.guo.learningprogresstracker.dto.ReviewSortPreference;
import com.guo.learningprogresstracker.dto.request.ReviewFeedbackRequest;
import com.guo.learningprogresstracker.exception.NotFindEntitiesException;
import com.guo.learningprogresstracker.mapper.ReviewRecallRecordMapper;
import com.guo.learningprogresstracker.mapper.StudyReportFragmentsMapper;
import com.guo.learningprogresstracker.mapper.StudyReportsMapper;
import com.guo.learningprogresstracker.mapper.StudySessionsMapper;
import com.guo.learningprogresstracker.mapper.TasksMapper;
import com.guo.learningprogresstracker.mapper.UserReviewPreferencesMapper;
import com.guo.learningprogresstracker.dto.request.UpdateStudyReportRequest;
import com.guo.learningprogresstracker.service.ReviewService;
import com.guo.learningprogresstracker.service.StudyExpectationsService;
@@ -54,6 +59,12 @@ public class ReviewServiceImpl implements ReviewService {
private static final String SOURCE_FRAGMENT = "FRAGMENT";
/** 待归类分组在内部的键名(不会作为任务编号出现在响应里,响应里 taskNum 为 null) */
private static final String PENDING_OWNERSHIP_KEY = "__PENDING__";
/** 时间效应封顶天数 */
private static final int AGE_CEILING_DAYS = 90;
/** 「稍后再看」的权重倍数(提高出现概率) */
private static final double REVISIT_FACTOR = 1.6;
/** 「已掌握」的权重倍数:降低但不归零,保留文档要求的随机性 */
private static final double MASTERED_FACTOR = 0.3;
private final StudyReportsMapper studyReportsMapper;
private final StudyReportFragmentsMapper studyReportFragmentsMapper;
@@ -61,6 +72,7 @@ public class ReviewServiceImpl implements ReviewService {
private final TasksMapper tasksMapper;
private final ReviewRecallRecordMapper reviewRecallRecordMapper;
private final StudyExpectationsService studyExpectationsService;
private final UserReviewPreferencesMapper userReviewPreferencesMapper;
@Override
public List<ReviewFeedItem> getReviewFeed(int limit, String mode) {
@@ -146,26 +158,50 @@ public class ReviewServiceImpl implements ReviewService {
.filter(Objects::nonNull).collect(Collectors.toSet()));
LocalDateTime now = LocalDateTime.now();
// 排序信号强度由用户的档位决定(复习-01)
ReviewSortPresetEnum preset = loadSortPreset();
List<Double> weights = new ArrayList<>(candidates.size());
for (ReviewFeedItem item : candidates) {
weights.add(reviewNeedWeight(item, taskRecallRatio, now));
weights.add(reviewNeedWeight(item, taskRecallRatio, now, preset));
}
return weightedSample(candidates, weights, safeLimit);
}
/** 单条内容的复习需求权重 */
private double reviewNeedWeight(ReviewFeedItem item, Map<String, Double> taskRecallRatio, LocalDateTime now) {
// 时间衰减:7 天内权重较低,之后随天数增长,90 天封顶
double ageDays = item.getCreatedTime() == null ? 30
: Math.max(0, java.time.Duration.between(item.getCreatedTime(), now).toDays());
double ageFactor = 0.3 + Math.min(ageDays, 90) / 90.0 * 0.7;
/**
* 单条内容的复习需求权重:三个信号相乘。
*
* <ol>
* <li><b>多久没接触</b>:从「最近接触时间」算起(没有则用创建时间),90 天封顶。</li>
* <li><b>任务掌握度</b>:最近一次回忆覆盖率越低权重越高。</li>
* <li><b>反馈动作</b>:「稍后再看」提高权重;「已掌握」降低但不归零——文档要求保留随机性,
* 「每条内容都有机会出现」。</li>
* </ol>
*
* <p>前两个信号的相对强度由用户的排序档位决定(复习-01)。</p>
*/
private double reviewNeedWeight(ReviewFeedItem item, Map<String, Double> taskRecallRatio,
LocalDateTime now, ReviewSortPresetEnum preset) {
// 信号一:时间效应。以「最近接触时间」为准,这样展开看过的内容会重新变「新」
LocalDateTime basis = item.getLastReviewedTime() != null ? item.getLastReviewedTime() : item.getCreatedTime();
double ageDays = basis == null ? 30
: Math.max(0, java.time.Duration.between(basis, now).toDays());
double ageProgress = Math.min(ageDays, AGE_CEILING_DAYS) / AGE_CEILING_DAYS;
double ageFactor = (1 - preset.getAgeInfluence()) + ageProgress * preset.getAgeInfluence();
// 掌握度:最近回忆覆盖率越低,权重越高
// 信号二:任务掌握度
double ratio = item.getTaskNum() == null ? 0
: taskRecallRatio.getOrDefault(item.getTaskNum(), 0D);
double masteryFactor = 1.0 - ratio * 0.7; // 覆盖率 100% 时权重降至 0.3
double masteryFactor = 1.0 - ratio * preset.getMasteryInfluence();
return ageFactor * masteryFactor;
// 信号三:反馈动作。「稍后再看」是明确的「想再看」,优先于「已掌握」
double feedbackFactor = 1.0;
if (Boolean.TRUE.equals(item.getRevisit())) {
feedbackFactor = REVISIT_FACTOR;
} else if (Boolean.TRUE.equals(item.getMastered())) {
feedbackFactor = MASTERED_FACTOR;
}
return ageFactor * masteryFactor * feedbackFactor;
}
/** 查询每个任务最近一次回忆对比的覆盖率 */
@@ -334,6 +370,88 @@ public class ReviewServiceImpl implements ReviewService {
}
/** 取任务名,任务不存在时返回 null(任务被删除后碎片会进入待归类,报告仍可能引用旧任务号) */
@Override
public ReviewFeedbackRequest submitFeedback(Integer fragmentId, ReviewFeedbackRequest request)
throws NotFindEntitiesException {
StudyReportFragmentsEntity existing = getFragmentForUpdate(fragmentId);
StudyReportFragmentsEntity patch = new StudyReportFragmentsEntity();
patch.setId(fragmentId);
boolean changed = false;
if (request.getMastered() != null) {
patch.setMastered(request.getMastered());
changed = true;
}
if (request.getRevisit() != null) {
patch.setRevisit(request.getRevisit());
changed = true;
}
if (changed) {
// 反馈动作同时算一次接触:用户刚刚看过这条内容
patch.setLastReviewedTime(LocalDateTime.now());
studyReportFragmentsMapper.updateById(patch);
}
ReviewFeedbackRequest result = new ReviewFeedbackRequest();
result.setMastered(request.getMastered() != null ? request.getMastered() : existing.getMastered());
result.setRevisit(request.getRevisit() != null ? request.getRevisit() : existing.getRevisit());
return result;
}
@Override
public void touchFragment(Integer fragmentId) throws NotFindEntitiesException {
getFragmentForUpdate(fragmentId);
StudyReportFragmentsEntity patch = new StudyReportFragmentsEntity();
patch.setId(fragmentId);
patch.setLastReviewedTime(LocalDateTime.now());
studyReportFragmentsMapper.updateById(patch);
}
/** 反馈与接触都要先确认碎片存在(属于当前用户由租户拦截器保证) */
private StudyReportFragmentsEntity getFragmentForUpdate(Integer fragmentId) throws NotFindEntitiesException {
StudyReportFragmentsEntity existing = studyReportFragmentsMapper.selectById(fragmentId);
if (existing == null) {
log.warn("未能找到知识碎片id[{}]", fragmentId);
throw new NotFindEntitiesException("这条知识碎片不存在或已被删除");
}
return existing;
}
@Override
public ReviewSortPreference getSortPreference() {
return toPreference(loadSortPreset());
}
@Override
public ReviewSortPreference saveSortPreference(String preset) {
ReviewSortPresetEnum parsed = ReviewSortPresetEnum.parse(preset);
UserReviewPreferencesEntity existing = userReviewPreferencesMapper.selectOne(
Wrappers.<UserReviewPreferencesEntity>lambdaQuery().last("LIMIT 1"));
if (existing == null) {
UserReviewPreferencesEntity created = new UserReviewPreferencesEntity();
created.setSortPreset(parsed.name());
userReviewPreferencesMapper.insert(created);
} else {
UserReviewPreferencesEntity patch = new UserReviewPreferencesEntity();
patch.setId(existing.getId());
patch.setSortPreset(parsed.name());
userReviewPreferencesMapper.updateById(patch);
}
log.info("复习排序偏好已更新为[{}]", parsed);
return toPreference(parsed);
}
/** 读取当前用户的排序档位;未设置或存坏时回落默认 */
private ReviewSortPresetEnum loadSortPreset() {
UserReviewPreferencesEntity preference = userReviewPreferencesMapper.selectOne(
Wrappers.<UserReviewPreferencesEntity>lambdaQuery().last("LIMIT 1"));
return preference == null
? ReviewSortPresetEnum.DEFAULT
: ReviewSortPresetEnum.parse(preference.getSortPreset());
}
private static ReviewSortPreference toPreference(ReviewSortPresetEnum preset) {
return new ReviewSortPreference(preset.name(), preset.getDescription());
}
private String loadTaskName(String taskNum) {
if (!StringUtils.hasText(taskNum)) {
return null;
@@ -419,6 +537,10 @@ public class ReviewServiceImpl implements ReviewService {
item.setContextNum(f.getContextNum());
// 内容归属:为空即「待归类」,前端据此打标并提供就地归类入口
item.setPendingOwnership(f.isPendingOwnership());
// 反馈状态与最近接触时间只参与排序计算,不用于列表展示(复习-02:不产生状态展示)
item.setMastered(f.getMastered());
item.setRevisit(f.getRevisit());
item.setLastReviewedTime(f.getLastReviewedTime());
item.setTaskNum(f.getOwnerTaskNum());
item.setTaskName(StringUtils.hasText(f.getOwnerTaskNum())
? taskNameMap.get(f.getOwnerTaskNum()) : null);