From 63824b26a00658e96411f2bf9910fc277d453c1f Mon Sep 17 00:00:00 2001 From: cat-shark <1716967236@qq.com> Date: Fri, 9 Oct 2026 19:21:26 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=E5=A4=8D=E4=B9=A0?= =?UTF-8?q?=E5=8F=8D=E9=A6=88=E5=8A=A8=E4=BD=9C=E4=B8=8E=E6=8E=92=E5=BA=8F?= =?UTF-8?q?=E4=B8=89=E6=A1=A3=E5=81=8F=E5=A5=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../controller/ReviewController.java | 39 +++++ .../dto/ReviewFeedItem.java | 13 ++ .../dto/ReviewSortPreference.java | 21 +++ .../dto/request/ReviewFeedbackRequest.java | 20 +++ .../entity/StudyReportFragmentsEntity.java | 19 +++ .../entity/UserReviewPreferencesEntity.java | 27 ++++ .../enums/ReviewSortPresetEnum.java | 51 +++++++ .../mapper/UserReviewPreferencesMapper.java | 9 ++ .../service/ReviewService.java | 22 +++ .../service/impl/ReviewServiceImpl.java | 142 ++++++++++++++++-- ...8__review_feedback_and_sort_preference.sql | 41 +++++ .../impl/ReviewFeedbackIntegrationTest.java | 140 +++++++++++++++++ .../service/impl/ReviewServiceImplTest.java | 6 + 13 files changed, 540 insertions(+), 10 deletions(-) create mode 100644 src/main/java/com/guo/learningprogresstracker/dto/ReviewSortPreference.java create mode 100644 src/main/java/com/guo/learningprogresstracker/dto/request/ReviewFeedbackRequest.java create mode 100644 src/main/java/com/guo/learningprogresstracker/entity/UserReviewPreferencesEntity.java create mode 100644 src/main/java/com/guo/learningprogresstracker/enums/ReviewSortPresetEnum.java create mode 100644 src/main/java/com/guo/learningprogresstracker/mapper/UserReviewPreferencesMapper.java create mode 100644 src/main/resources/db/migration/V20261009_8__review_feedback_and_sort_preference.sql create mode 100644 src/test/java/com/guo/learningprogresstracker/service/impl/ReviewFeedbackIntegrationTest.java diff --git a/src/main/java/com/guo/learningprogresstracker/controller/ReviewController.java b/src/main/java/com/guo/learningprogresstracker/controller/ReviewController.java index 30a7fd2..f50ae74 100644 --- a/src/main/java/com/guo/learningprogresstracker/controller/ReviewController.java +++ b/src/main/java/com/guo/learningprogresstracker/controller/ReviewController.java @@ -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):标记或取消「已掌握」「稍后再看」。 + *

只调整出现概率,不产生状态展示、不统计总数、不做待复习列表。

+ */ + @PutMapping("/feed/{fragmentId}/feedback") + public CommonResult submitFeedback( + @PathVariable Integer fragmentId, + @RequestBody ReviewFeedbackRequest request) throws NotFindEntitiesException { + return CommonResult.success(reviewService.submitFeedback(fragmentId, request)); + } + + /** + * 记录一次「接触」(展开查看 / 进入回忆对比时调用):刷新最近接触时间,作为排序的第三个信号。 + */ + @PostMapping("/feed/{fragmentId}/touched") + public CommonResult touchFragment(@PathVariable Integer fragmentId) throws NotFindEntitiesException { + reviewService.touchFragment(fragmentId); + return CommonResult.success(); + } + + /** + * 读取复习排序偏好(复习-01) + */ + @GetMapping("/sort-preference") + public CommonResult getSortPreference() { + return CommonResult.success(reviewService.getSortPreference()); + } + + /** + * 保存复习排序偏好(复习-01):三档预设,不做精确权重。 + */ + @PutMapping("/sort-preference") + public CommonResult saveSortPreference(@RequestBody Map body) { + String preset = body == null ? null : body.get("preset"); + return CommonResult.success(reviewService.saveSortPreference(preset)); + } + /** * 获取任务维度的复习统计汇总 */ diff --git a/src/main/java/com/guo/learningprogresstracker/dto/ReviewFeedItem.java b/src/main/java/com/guo/learningprogresstracker/dto/ReviewFeedItem.java index 660bd9e..08fac2f 100644 --- a/src/main/java/com/guo/learningprogresstracker/dto/ReviewFeedItem.java +++ b/src/main/java/com/guo/learningprogresstracker/dto/ReviewFeedItem.java @@ -39,4 +39,17 @@ public class ReviewFeedItem { /** 记录上下文编号:学习会话编号或复习行为编号 */ private String contextNum; + + /** + * 反馈与接触时间只参与排序计算,不用于列表展示: + * 复习反馈刻意不产生状态展示,否则会把复习拖回清单模式(复习-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; } diff --git a/src/main/java/com/guo/learningprogresstracker/dto/ReviewSortPreference.java b/src/main/java/com/guo/learningprogresstracker/dto/ReviewSortPreference.java new file mode 100644 index 0000000..4452171 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/ReviewSortPreference.java @@ -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; +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/request/ReviewFeedbackRequest.java b/src/main/java/com/guo/learningprogresstracker/dto/request/ReviewFeedbackRequest.java new file mode 100644 index 0000000..c08df36 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/request/ReviewFeedbackRequest.java @@ -0,0 +1,20 @@ +package com.guo.learningprogresstracker.dto.request; + +import io.swagger.v3.oas.annotations.media.Schema; +import lombok.Data; + +/** + * 复习反馈动作(复习-02)。 + * + *

两个动作都只调整内容的出现概率,不产生状态展示、不统计总数、不做待复习列表。 + * 传 null 表示本次不改该动作。

+ */ +@Data +public class ReviewFeedbackRequest { + + @Schema(description = "标记/取消「已掌握」:降低出现概率但不归零") + private Boolean mastered; + + @Schema(description = "标记/取消「稍后再看」:提高出现概率") + private Boolean revisit; +} diff --git a/src/main/java/com/guo/learningprogresstracker/entity/StudyReportFragmentsEntity.java b/src/main/java/com/guo/learningprogresstracker/entity/StudyReportFragmentsEntity.java index d7e3fa6..11d629a 100644 --- a/src/main/java/com/guo/learningprogresstracker/entity/StudyReportFragmentsEntity.java +++ b/src/main/java/com/guo/learningprogresstracker/entity/StudyReportFragmentsEntity.java @@ -45,6 +45,25 @@ public class StudyReportFragmentsEntity extends BaseEntity implements Serializab @TableField(value = "owner_task_num") private String ownerTaskNum; + /** + * 用户标记「已掌握」:降低出现概率但不归零(复习-02)。 + *

刻意不进标记表——文档明确「标记不是状态」,流程性判断留在主体上。

+ */ + @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; diff --git a/src/main/java/com/guo/learningprogresstracker/entity/UserReviewPreferencesEntity.java b/src/main/java/com/guo/learningprogresstracker/entity/UserReviewPreferencesEntity.java new file mode 100644 index 0000000..f7ce558 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/entity/UserReviewPreferencesEntity.java @@ -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; +} diff --git a/src/main/java/com/guo/learningprogresstracker/enums/ReviewSortPresetEnum.java b/src/main/java/com/guo/learningprogresstracker/enums/ReviewSortPresetEnum.java new file mode 100644 index 0000000..1b42eae --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/enums/ReviewSortPresetEnum.java @@ -0,0 +1,51 @@ +package com.guo.learningprogresstracker.enums; + +import lombok.AllArgsConstructor; +import lombok.Getter; + +/** + * 复习智能排序的信号强度预设(复习-01)。 + * + *

排序把「多久没接触」与「任务掌握度」两个因子相乘。给用户精确百分比是假精度, + * 因此只提供三个语义档位,覆盖两种真实诉求:内容太旧、或总给自己看已经熟的。

+ * + *

系数含义:

+ *
    + *
  • {@code ageInfluence}:时间效应强度。时间因子 = (1 - 强度) + 进度 × 强度,故强度越大越区分新旧。
  • + *
  • {@code masteryInfluence}:掌握度强度。掌握度因子 = 1 - 覆盖率 × 强度,故强度越大越惩罚低覆盖率。
  • + *
+ */ +@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; + } + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/mapper/UserReviewPreferencesMapper.java b/src/main/java/com/guo/learningprogresstracker/mapper/UserReviewPreferencesMapper.java new file mode 100644 index 0000000..188a380 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/mapper/UserReviewPreferencesMapper.java @@ -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 { +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/ReviewService.java b/src/main/java/com/guo/learningprogresstracker/service/ReviewService.java index f6e1e00..ed2e04c 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/ReviewService.java +++ b/src/main/java/com/guo/learningprogresstracker/service/ReviewService.java @@ -57,6 +57,28 @@ public interface ReviewService { */ void deleteReport(int id) throws NotFindEntitiesException; + /** + * 提交复习反馈动作(复习-02):标记或取消「已掌握」「稍后再看」。 + *

只调整出现概率,不产生状态展示。

+ * + * @return 动作之后的反馈状态,供前端在本次浏览中切换按钮 + */ + com.guo.learningprogresstracker.dto.request.ReviewFeedbackRequest submitFeedback( + Integer fragmentId, com.guo.learningprogresstracker.dto.request.ReviewFeedbackRequest request) + throws NotFindEntitiesException; + + /** + * 记录一次「接触」:刷新最近接触时间,作为智能排序的第三个信号(复习-02)。 + *

展开查看与进入回忆对比都会调用;本身不产生额外数据。

+ */ + void touchFragment(Integer fragmentId) throws NotFindEntitiesException; + + /** 读取复习排序偏好,未设置时返回默认档位(复习-01) */ + com.guo.learningprogresstracker.dto.ReviewSortPreference getSortPreference(); + + /** 保存复习排序偏好(复习-01) */ + com.guo.learningprogresstracker.dto.ReviewSortPreference saveSortPreference(String preset); + /** * 获取残片详情 */ diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImpl.java b/src/main/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImpl.java index b281d5e..2d435ab 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImpl.java +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImpl.java @@ -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 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 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 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; + /** + * 单条内容的复习需求权重:三个信号相乘。 + * + *
    + *
  1. 多久没接触:从「最近接触时间」算起(没有则用创建时间),90 天封顶。
  2. + *
  3. 任务掌握度:最近一次回忆覆盖率越低权重越高。
  4. + *
  5. 反馈动作:「稍后再看」提高权重;「已掌握」降低但不归零——文档要求保留随机性, + * 「每条内容都有机会出现」。
  6. + *
+ * + *

前两个信号的相对强度由用户的排序档位决定(复习-01)。

+ */ + private double reviewNeedWeight(ReviewFeedItem item, Map 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.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.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); diff --git a/src/main/resources/db/migration/V20261009_8__review_feedback_and_sort_preference.sql b/src/main/resources/db/migration/V20261009_8__review_feedback_and_sort_preference.sql new file mode 100644 index 0000000..83b3c55 --- /dev/null +++ b/src/main/resources/db/migration/V20261009_8__review_feedback_and_sort_preference.sql @@ -0,0 +1,41 @@ +-- 复习-02(反馈动作)与复习-01(排序三档)。 + +-- ============ 1. 知识碎片的复习反馈状态 ============ +-- +-- 反馈动作只调整内容的「出现概率」,不产生状态展示、不统计总数、不做待复习列表。 +-- 也不进标记表:lpt-docs 明确「标记不是状态」,流程性判断留在主体上。 +ALTER TABLE study_report_fragments + ADD COLUMN mastered TINYINT(1) NOT NULL DEFAULT 0 + COMMENT '用户标记「已掌握」:降低出现概率,但不归零(随机性保留)' AFTER owner_task_num; + +ALTER TABLE study_report_fragments + ADD COLUMN revisit TINYINT(1) NOT NULL DEFAULT 0 + COMMENT '用户标记「稍后再看」:提高出现概率' AFTER mastered; + +ALTER TABLE study_report_fragments + ADD COLUMN last_reviewed_time DATETIME NULL + COMMENT '最近一次接触时间(展开查看 / 进入回忆对比时刷新),复习排序的第三个信号' AFTER revisit; + +-- 注:反馈状态与最近接触时间只在智能排序已取样出的候选行上读取,不需要额外索引; +-- 取样本身走主键区间(复习-03)。 + +-- ============ 2. 复习排序偏好(三档预设) ============ +-- +-- 每个用户一条。三档而非精确数值:排序是两个因子相乘而非加权求和,给百分比是假精度, +-- 而三个档位已经覆盖真实意图(「怎么老给我看旧内容」与「怎么总给我看熟的」)。 +CREATE TABLE user_review_preferences +( + id INT AUTO_INCREMENT COMMENT 'id无业务含义' + PRIMARY KEY, + sort_preset VARCHAR(30) NOT NULL DEFAULT 'TIME_FIRST' + COMMENT '复习排序偏好:TIME_FIRST(时间为主,默认)/ BALANCED(均衡)/ MASTERY_FIRST(掌握度为主)', + created_time DATETIME NOT NULL COMMENT '创建时间', + created_by VARCHAR(255) NULL, + last_modified_time DATETIME NULL, + last_modified_by VARCHAR(255) NULL, + device_info VARCHAR(50) NULL COMMENT '操作者设备类型', + deleted INT DEFAULT 0 NOT NULL COMMENT '逻辑删除符', + -- 每个用户一条;created_by 同时是租户键,因此该唯一约束天然按用户生效 + UNIQUE KEY uk_user_review_preferences_created_by (created_by) +) + COMMENT '复习排序偏好:按用户保存三档预设之一'; diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewFeedbackIntegrationTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewFeedbackIntegrationTest.java new file mode 100644 index 0000000..2ed5412 --- /dev/null +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewFeedbackIntegrationTest.java @@ -0,0 +1,140 @@ +package com.guo.learningprogresstracker.service.impl; + +import cn.dev33.satoken.stp.StpUtil; +import com.guo.learningprogresstracker.dto.ReviewSortPreference; +import com.guo.learningprogresstracker.dto.request.ReviewFeedbackRequest; +import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity; +import com.guo.learningprogresstracker.entity.StudySessionsEntity; +import com.guo.learningprogresstracker.mapper.StudyReportFragmentsMapper; +import com.guo.learningprogresstracker.mapper.StudySessionsMapper; +import com.guo.learningprogresstracker.service.ReviewService; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.boot.test.context.SpringBootTest; + +import java.time.LocalDateTime; +import java.util.concurrent.atomic.AtomicInteger; + +import static org.junit.jupiter.api.Assertions.*; + +/** + * 复习反馈动作与排序偏好的落库集成测试(复习-02 / 复习-01)。 + */ +@SpringBootTest +class ReviewFeedbackIntegrationTest { + + private static final String USER = "复习反馈集成测试用户"; + + private static final AtomicInteger SEQ = new AtomicInteger(); + + @Autowired + private ReviewService reviewService; + + @Autowired + private StudyReportFragmentsMapper fragmentsMapper; + + @Autowired + private StudySessionsMapper studySessionsMapper; + + @BeforeEach + void setUp() { + StpUtil.login(USER, "test_device"); + } + + private StudyReportFragmentsEntity saveFragment() { + StudySessionsEntity session = new StudySessionsEntity(); + String taskNum = "TASKFB-IT-" + System.nanoTime() + "-" + SEQ.incrementAndGet(); + session.setSessionNum("SESSIONFB-IT-" + System.nanoTime() + "-" + SEQ.incrementAndGet()); + session.setTaskNum(taskNum); + session.setStartTime(LocalDateTime.now()); + session.setLastStartTime(LocalDateTime.now()); + session.setSessionState("ENDED"); + studySessionsMapper.insert(session); + + StudyReportFragmentsEntity fragment = new StudyReportFragmentsEntity(); + fragment.setContextType("SESSION"); + fragment.setContextNum(session.getSessionNum()); + fragment.setOwnerTaskNum(taskNum); + fragment.setContent("反馈动作测试碎片"); + fragmentsMapper.insert(fragment); + return fragment; + } + + @Test + void feedback_togglesMasteredAndRevisit() throws Exception { + StudyReportFragmentsEntity fragment = saveFragment(); + + ReviewFeedbackRequest markMastered = new ReviewFeedbackRequest(); + markMastered.setMastered(true); + ReviewFeedbackRequest afterMastered = reviewService.submitFeedback(fragment.getId(), markMastered); + assertEquals(Boolean.TRUE, afterMastered.getMastered()); + + StudyReportFragmentsEntity reloaded = fragmentsMapper.selectById(fragment.getId()); + assertEquals(Boolean.TRUE, reloaded.getMastered()); + assertNotNull(reloaded.getLastReviewedTime(), "反馈动作同时算一次接触"); + + // 撤销:传 false + ReviewFeedbackRequest unmark = new ReviewFeedbackRequest(); + unmark.setMastered(false); + reviewService.submitFeedback(fragment.getId(), unmark); + assertEquals(Boolean.FALSE, fragmentsMapper.selectById(fragment.getId()).getMastered()); + } + + @Test + void feedback_onlyTouchesProvidedAction() throws Exception { + StudyReportFragmentsEntity fragment = saveFragment(); + + ReviewFeedbackRequest revisit = new ReviewFeedbackRequest(); + revisit.setRevisit(true); + reviewService.submitFeedback(fragment.getId(), revisit); + + StudyReportFragmentsEntity reloaded = fragmentsMapper.selectById(fragment.getId()); + assertEquals(Boolean.TRUE, reloaded.getRevisit()); + // 没有传 mastered,不应被改写 + assertNotEquals(Boolean.TRUE, reloaded.getMastered()); + } + + @Test + void touch_refreshesLastReviewedTime() throws Exception { + StudyReportFragmentsEntity fragment = saveFragment(); + assertNull(fragmentsMapper.selectById(fragment.getId()).getLastReviewedTime()); + + reviewService.touchFragment(fragment.getId()); + + assertNotNull(fragmentsMapper.selectById(fragment.getId()).getLastReviewedTime(), + "展开查看应刷新最近接触时间,成为排序的第三个信号"); + } + + @Test + void feedback_onMissingFragment_throws() { + ReviewFeedbackRequest request = new ReviewFeedbackRequest(); + request.setMastered(true); + assertThrows(com.guo.learningprogresstracker.exception.NotFindEntitiesException.class, + () -> reviewService.submitFeedback(999_999, request)); + } + + @Test + void sortPreference_defaultsThenPersists() { + ReviewSortPreference initial = reviewService.getSortPreference(); + assertEquals("TIME_FIRST", initial.getPreset(), "默认档位是「时间为主」"); + assertNotNull(initial.getDescription()); + + reviewService.saveSortPreference("MASTERY_FIRST"); + assertEquals("MASTERY_FIRST", reviewService.getSortPreference().getPreset()); + + // 未知值回落默认,避免一个坏值让 Feed 报错 + reviewService.saveSortPreference("NOT_A_PRESET"); + assertEquals("TIME_FIRST", reviewService.getSortPreference().getPreset()); + } + + @Test + void sortPreference_isScopedPerUser() { + reviewService.saveSortPreference("BALANCED"); + assertEquals("BALANCED", reviewService.getSortPreference().getPreset()); + + StpUtil.login("复习反馈集成测试另一个用户", "test_device"); + assertEquals("TIME_FIRST", reviewService.getSortPreference().getPreset(), + "排序偏好按用户隔离,另一个用户仍是默认档位"); + } +} diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImplTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImplTest.java index f9292ee..b4eb10d 100644 --- a/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImplTest.java +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImplTest.java @@ -19,6 +19,7 @@ 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 org.apache.ibatis.builder.MapperBuilderAssistant; import org.junit.jupiter.api.BeforeAll; import org.junit.jupiter.api.Test; @@ -64,6 +65,9 @@ class ReviewServiceImplTest { @Mock private ReviewRecallRecordMapper reviewRecallRecordMapper; + @Mock + private UserReviewPreferencesMapper userReviewPreferencesMapper; + @Test void getReviewFeed_smartMode_prefersLowRecallRatioContent() { LocalDateTime now = LocalDateTime.now(); @@ -95,6 +99,8 @@ class ReviewServiceImplTest { when(studyReportFragmentsMapper.selectIdRange()).thenReturn(idRange(1, 2)); when(studyReportFragmentsMapper.selectList(any())).thenReturn(List.of(oldLowMastery, freshHighMastery)); when(tasksMapper.selectList(any())).thenReturn(List.of(taskLow, taskHigh)); + // 复习-01:排序档位从偏好表读取,未设置时回落默认 + when(userReviewPreferencesMapper.selectOne(any())).thenReturn(null); // 复习-04:覆盖率改由 SQL 按任务分组取最新 TaskRecallRatio highRatio = new TaskRecallRatio(); highRatio.setTaskNum("T_HIGH");