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
@@ -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);