diff --git a/AGENTS.md b/AGENTS.md index 8f083bc..ba974fc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -173,5 +173,14 @@ mvn spring-boot:run # 启动(默认 profile: local) ## 编码规范 ### 数据访问层 + - **优先使用纯 MyBatis-Plus Java API**(`Wrappers.lambdaQuery()`、`selectList`、`selectById` 等),避免手写 XML SQL - 复杂查询通过 `Wrappers` 链式构建条件,必要时使用 `.apply()` 拼接原生 SQL 片段 +- **查询结果一律用类承载,禁止 `selectMaps` + 字符串 key 取值** + - MyBatis 对 Map 结果直接用 JDBC 列名作 key,不做属性映射:`map-underscore-to-camel-case` 与「属性名大小写不敏感」只对类结果生效。而数据库的标识符大小写规则各不相同(MySQL 保留别名、H2/PostgreSQL 转小写、Oracle 转大写),`row.get("taskNum")` 会在部分库上静默取到 null,表现为「数据莫名变 0」而不是报错 + - 单列聚合用 `selectObjs`,多列聚合用下面的自定义 Mapper 方法 +- **`Wrapper` 表达不了的查询(`SUM`/`GROUP BY`/多表 `JOIN`)收敛到 Mapper 层**,用自定义方法 + **显式结果类**(`dto/` 下的类或实体),参考 `ReviewRecallRecordMapper.sumReviewDurationByTask` → `dto/TaskReviewDuration` + `resources/mapper/ReviewRecallRecordMapper.xml` + - 结果映射优先写显式 ``(`property` ↔ `column` 一一对应),不依赖 `map-underscore-to-camel-case` 的默认值,也不依赖列名大小写 + - **自定义 SQL 不会被 `@TableLogic` 自动追加逻辑删除条件**,必须显式写 `deleted = 0`;租户条件 `created_by = ?` 仍由 `TenantLineInnerInterceptor` 自动追加 + - 上述两条不能只靠 mock 单测,需落库集成测试守住(参考 `ReviewDurationIntegrationTest`) + - 反向约束:`Wrapper` 能表达的查询不要为「类型安全」提前下沉为自定义 SQL;确实要下沉时,SQL 只留在 Mapper 层,不要在 service 里拼字符串 diff --git a/src/main/java/com/guo/learningprogresstracker/dto/TaskReviewDuration.java b/src/main/java/com/guo/learningprogresstracker/dto/TaskReviewDuration.java new file mode 100644 index 0000000..74c6c14 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/TaskReviewDuration.java @@ -0,0 +1,16 @@ +package com.guo.learningprogresstracker.dto; + +import lombok.Data; + +/** + * 任务维度的复习耗时聚合结果(复习-07)。 + *

由 Mapper 层的聚合查询直接映射,避免用 Map 承载查询结果。

+ */ +@Data +public class TaskReviewDuration { + + private String taskNum; + + /** 该任务累计复习耗时(秒) */ + private Long reviewDurationSeconds; +} diff --git a/src/main/java/com/guo/learningprogresstracker/mapper/ReviewRecallRecordMapper.java b/src/main/java/com/guo/learningprogresstracker/mapper/ReviewRecallRecordMapper.java index 4098a2b..04bda90 100644 --- a/src/main/java/com/guo/learningprogresstracker/mapper/ReviewRecallRecordMapper.java +++ b/src/main/java/com/guo/learningprogresstracker/mapper/ReviewRecallRecordMapper.java @@ -1,9 +1,24 @@ package com.guo.learningprogresstracker.mapper; import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.guo.learningprogresstracker.dto.TaskReviewDuration; import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity; import org.apache.ibatis.annotations.Mapper; +import org.apache.ibatis.annotations.Param; + +import java.util.Collection; +import java.util.List; @Mapper public interface ReviewRecallRecordMapper extends BaseMapper { + + /** + * 按任务汇总复习耗时(秒,复习-07)。 + *

Wrapper 无法表达 SUM + GROUP BY,因此放在 Mapper 层用自定义 SQL + 显式结果类; + * 语句见 {@code resources/mapper/ReviewRecallRecordMapper.xml}(逻辑删除条件已显式写出, + * 租户条件由拦截器自动追加)。

+ * + * @param taskNums 需要汇总的任务编号;为空时返回空列表 + */ + List sumReviewDurationByTask(@Param("taskNums") Collection taskNums); } 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 cccfad4..6055cf9 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImpl.java +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImpl.java @@ -3,6 +3,7 @@ package com.guo.learningprogresstracker.service.impl; import com.baomidou.mybatisplus.core.toolkit.Wrappers; import com.guo.learningprogresstracker.dto.ReviewFeedItem; import com.guo.learningprogresstracker.dto.ReviewTaskStats; +import com.guo.learningprogresstracker.dto.TaskReviewDuration; import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity; import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity; import com.guo.learningprogresstracker.entity.StudyReportsEntity; @@ -382,43 +383,19 @@ public class ReviewServiceImpl implements ReviewService { } /** - * 按任务汇总复习行为累计耗时(复习-07)。在 SQL 侧聚合,只把任务数量的行拉回内存, - * 不随回忆记录条数增长。 + * 按任务汇总复习行为累计耗时(复习-07)。聚合在 SQL 侧完成,只把任务数量的行拉回内存, + * 不随回忆记录条数增长;结果由 {@code TaskReviewDuration} 承载,不走 Map。 */ private void fillReviewDuration(Map statsByTaskNum) { - List> rows = reviewRecallRecordMapper.selectMaps( - Wrappers.query() - .select("task_num AS taskNum", - "COALESCE(SUM(review_duration_seconds), 0) AS reviewDurationSeconds") - .in("task_num", statsByTaskNum.keySet()) - .groupBy("task_num")); - - for (Map 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()); + List rows = reviewRecallRecordMapper.sumReviewDurationByTask(statsByTaskNum.keySet()); + for (TaskReviewDuration row : rows) { + ReviewTaskStats stats = statsByTaskNum.get(row.getTaskNum()); + if (stats != null && row.getReviewDurationSeconds() != null) { + stats.setReviewDurationSeconds(row.getReviewDurationSeconds()); } } } - /** - * 取聚合结果的列:别名大小写随数据库实现不同(MySQL 保留、H2 会转为小写),这里统一不区分大小写。 - */ - private static Object columnValue(Map row, String column) { - Object direct = row.get(column); - if (direct != null) { - return direct; - } - for (Map.Entry entry : row.entrySet()) { - if (entry.getKey() != null && entry.getKey().equalsIgnoreCase(column)) { - return entry.getValue(); - } - } - return null; - } - private void fillReportAndFragmentCount(Map sessionToTaskNum, Map statsByTaskNum) { if (sessionToTaskNum.isEmpty()) { diff --git a/src/main/resources/mapper/ReviewRecallRecordMapper.xml b/src/main/resources/mapper/ReviewRecallRecordMapper.xml new file mode 100644 index 0000000..08f9bd9 --- /dev/null +++ b/src/main/resources/mapper/ReviewRecallRecordMapper.xml @@ -0,0 +1,31 @@ + + + + + + + + + + + + + diff --git a/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewDurationIntegrationTest.java b/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewDurationIntegrationTest.java index 59ce661..36be7f6 100644 --- a/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewDurationIntegrationTest.java +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewDurationIntegrationTest.java @@ -10,32 +10,38 @@ import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; +import java.util.concurrent.atomic.AtomicInteger; + import static org.junit.jupiter.api.Assertions.assertEquals; /** * 复习耗时的落库与聚合集成测试(复习-07):在真实 SQL(含租户条件、逻辑删除与 GROUP BY 聚合)下验证。 + *

聚合走自定义 Mapper SQL,因此这里同时守住两个容易漏的条件:租户隔离与逻辑删除。

*/ @SpringBootTest class ReviewDurationIntegrationTest { + private static final String USER_A = "复习耗时集成测试用户A"; + private static final String USER_B = "复习耗时集成测试用户B"; + + /** GenerateNumTool 在同毫秒内会生成相同编号(数据-03),集成测试自己保证任务编号唯一。 */ + private static final AtomicInteger SEQ = new AtomicInteger(); + @Autowired private ReviewService reviewService; @Autowired private ReviewRecallRecordMapper recallRecordMapper; - /** GenerateNumTool 在同毫秒内会生成相同编号(数据-03),集成测试自己保证任务编号唯一。 */ - private static final java.util.concurrent.atomic.AtomicInteger SEQ = new java.util.concurrent.atomic.AtomicInteger(); + @BeforeEach + void setUp() { + StpUtil.login(USER_A, "test_device"); + } private static String uniqueTaskNum() { return "TASKRD-IT-" + System.nanoTime() + "-" + SEQ.incrementAndGet(); } - @BeforeEach - void setUp() { - StpUtil.login("复习耗时集成测试用户", "test_device"); - } - @Test void reviewDuration_isPersistedAndAggregatedPerTask() { String taskNum = uniqueTaskNum(); @@ -45,26 +51,48 @@ class ReviewDurationIntegrationTest { insertRecall(taskNum, 120); insertRecall(otherTaskNum, 60); - ReviewTaskStats stats = reviewService.getReviewTaskStats(taskNum); - assertEquals(420L, stats.getReviewDurationSeconds(), "同一任务应累计 300+120 秒"); - - ReviewTaskStats otherStats = reviewService.getReviewTaskStats(otherTaskNum); - assertEquals(60L, otherStats.getReviewDurationSeconds(), "不同任务之间不应串数据"); + assertEquals(420L, reviewService.getReviewTaskStats(taskNum).getReviewDurationSeconds(), + "同一任务应累计 300+120 秒"); + assertEquals(60L, reviewService.getReviewTaskStats(otherTaskNum).getReviewDurationSeconds(), + "不同任务之间不应串数据"); } @Test void reviewDuration_databaseDefaultIsZero() { - ReviewRecallRecordEntity record = new ReviewRecallRecordEntity(); - record.setTaskNum(uniqueTaskNum()); - record.setRecallContent("- 未计时回忆"); - record.setRecallRatio(0.0); - recallRecordMapper.insert(record); + ReviewRecallRecordEntity saved = insertRecall(uniqueTaskNum(), null); - ReviewRecallRecordEntity reloaded = recallRecordMapper.selectById(record.getId()); - assertEquals(0, reloaded.getReviewDurationSeconds(), "未上报耗时时应落库为 0,而不是 null"); + assertEquals(0, recallRecordMapper.selectById(saved.getId()).getReviewDurationSeconds(), + "未上报耗时时应落库为 0,而不是 null"); } - private void insertRecall(String taskNum, int durationSeconds) { + @Test + void reviewDuration_customSqlStillIsolatedByTenant() { + String taskNum = uniqueTaskNum(); + insertRecall(taskNum, 300); + + StpUtil.login(USER_B, "test_device"); + insertRecall(taskNum, 999); + assertEquals(999L, reviewService.getReviewTaskStats(taskNum).getReviewDurationSeconds(), + "用户 B 只应看到自己的记录"); + + StpUtil.login(USER_A, "test_device"); + assertEquals(300L, reviewService.getReviewTaskStats(taskNum).getReviewDurationSeconds(), + "自定义 SQL 也必须被租户拦截器追加 created_by 条件"); + } + + @Test + void reviewDuration_excludesLogicallyDeletedRecords() { + String taskNum = uniqueTaskNum(); + ReviewRecallRecordEntity deleted = insertRecall(taskNum, 300); + insertRecall(taskNum, 120); + + recallRecordMapper.deleteById(deleted.getId()); + + assertEquals(120L, reviewService.getReviewTaskStats(taskNum).getReviewDurationSeconds(), + "自定义 SQL 未被 @TableLogic 自动追加条件,必须显式过滤 deleted = 0"); + } + + private ReviewRecallRecordEntity insertRecall(String taskNum, Integer durationSeconds) { ReviewRecallRecordEntity record = new ReviewRecallRecordEntity(); record.setTaskNum(taskNum); record.setRecallContent("- 集成测试回忆"); @@ -74,5 +102,6 @@ class ReviewDurationIntegrationTest { record.setExtraCount(0); record.setReviewDurationSeconds(durationSeconds); recallRecordMapper.insert(record); + return record; } } 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 141b7bd..be6bb40 100644 --- a/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImplTest.java +++ b/src/test/java/com/guo/learningprogresstracker/service/impl/ReviewServiceImplTest.java @@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.core.MybatisConfiguration; import com.baomidou.mybatisplus.core.metadata.TableInfoHelper; import com.guo.learningprogresstracker.dto.ReviewFeedItem; import com.guo.learningprogresstracker.dto.ReviewTaskStats; +import com.guo.learningprogresstracker.dto.TaskReviewDuration; import com.guo.learningprogresstracker.entity.ReviewRecallRecordEntity; import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity; import com.guo.learningprogresstracker.entity.StudyReportsEntity; @@ -24,7 +25,6 @@ import org.mockito.junit.jupiter.MockitoExtension; import java.time.LocalDateTime; import java.util.List; -import java.util.Map; import static org.junit.jupiter.api.Assertions.assertEquals; import static org.mockito.ArgumentMatchers.any; @@ -161,9 +161,9 @@ class ReviewServiceImplTest { when(studyReportsMapper.selectList(any())).thenReturn(List.of()); when(studyReportFragmentsMapper.selectList(any())).thenReturn(List.of()); // 聚合结果里出现了不在任务列表中的 taskNum,应被忽略 - when(reviewRecallRecordMapper.selectMaps(any())).thenReturn(List.of( - Map.of("taskNum", "T1", "reviewDurationSeconds", 420L), - Map.of("taskNum", "T_UNKNOWN", "reviewDurationSeconds", 100L))); + when(reviewRecallRecordMapper.sumReviewDurationByTask(any())).thenReturn(List.of( + reviewDuration("T1", 420L), + reviewDuration("T_UNKNOWN", 100L))); List stats = reviewService.getReviewTaskStats(); @@ -171,4 +171,11 @@ class ReviewServiceImplTest { assertEquals(600, stats.get(0).getEffectiveTime()); assertEquals(420L, stats.get(0).getReviewDurationSeconds()); } + + private static TaskReviewDuration reviewDuration(String taskNum, Long seconds) { + TaskReviewDuration row = new TaskReviewDuration(); + row.setTaskNum(taskNum); + row.setReviewDurationSeconds(seconds); + return row; + } }