From c6258fa6d74287a3798861a32f108e26e547beb5 Mon Sep 17 00:00:00 2001 From: cat-shark <1716967236@qq.com> Date: Fri, 9 Oct 2026 19:25:34 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B0=E5=A2=9E=E7=BB=9F=E4=B8=80?= =?UTF-8?q?=E6=A0=87=E8=AE=B0=E5=AD=98=E5=82=A8=E4=B8=8E=E5=8D=95=E4=B8=80?= =?UTF-8?q?=E6=A0=87=E8=AE=B0=E7=AD=9B=E9=80=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../controller/MarkerController.java | 107 +++++++ .../dto/MarkerUsage.java | 18 ++ .../entity/MarkerEntity.java | 50 ++++ .../enums/MarkerKindEnum.java | 20 ++ .../enums/MarkerObjectTypeEnum.java | 31 ++ .../enums/SystemMarkerEnum.java | 24 ++ .../mapper/MarkerMapper.java | 31 ++ .../service/MarkerService.java | 79 +++++ .../service/impl/MarkerServiceImpl.java | 272 ++++++++++++++++++ .../impl/StudyReportFragmentsServiceImpl.java | 4 + .../db/migration/V20261009_9__add_markers.sql | 34 +++ .../impl/MarkerServiceIntegrationTest.java | 264 +++++++++++++++++ 12 files changed, 934 insertions(+) create mode 100644 src/main/java/com/guo/learningprogresstracker/controller/MarkerController.java create mode 100644 src/main/java/com/guo/learningprogresstracker/dto/MarkerUsage.java create mode 100644 src/main/java/com/guo/learningprogresstracker/entity/MarkerEntity.java create mode 100644 src/main/java/com/guo/learningprogresstracker/enums/MarkerKindEnum.java create mode 100644 src/main/java/com/guo/learningprogresstracker/enums/MarkerObjectTypeEnum.java create mode 100644 src/main/java/com/guo/learningprogresstracker/enums/SystemMarkerEnum.java create mode 100644 src/main/java/com/guo/learningprogresstracker/mapper/MarkerMapper.java create mode 100644 src/main/java/com/guo/learningprogresstracker/service/MarkerService.java create mode 100644 src/main/java/com/guo/learningprogresstracker/service/impl/MarkerServiceImpl.java create mode 100644 src/main/resources/db/migration/V20261009_9__add_markers.sql create mode 100644 src/test/java/com/guo/learningprogresstracker/service/impl/MarkerServiceIntegrationTest.java diff --git a/src/main/java/com/guo/learningprogresstracker/controller/MarkerController.java b/src/main/java/com/guo/learningprogresstracker/controller/MarkerController.java new file mode 100644 index 0000000..ab11de3 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/controller/MarkerController.java @@ -0,0 +1,107 @@ +package com.guo.learningprogresstracker.controller; + +import com.guo.learningprogresstracker.dto.MarkerUsage; +import com.guo.learningprogresstracker.entity.CommonResult; +import com.guo.learningprogresstracker.entity.MarkerEntity; +import com.guo.learningprogresstracker.enums.MarkerObjectTypeEnum; +import com.guo.learningprogresstracker.exception.ErrorParameterException; +import com.guo.learningprogresstracker.exception.NotFindEntitiesException; +import com.guo.learningprogresstracker.service.MarkerService; +import io.swagger.v3.oas.annotations.Operation; +import lombok.RequiredArgsConstructor; +import org.springframework.validation.annotation.Validated; +import org.springframework.web.bind.annotation.*; + +import java.util.Collection; +import java.util.List; +import java.util.Map; + +/** + * 统一标记控制层(标记-01)。 + * + *

标记对用户全部可见;用户标签可增删改,系统标记只读。 + * 检索只提供「单一标记筛选」,不做多标记组合——标签的唯一作用就是检索,而组合筛选目前没有真实场景。

+ */ +@RequestMapping("/markers") +@RestController +@Validated +@RequiredArgsConstructor +public class MarkerController { + + private final MarkerService markerService; + + /** + * 列出某个对象上的全部标记(系统标记与用户标签一起返回,前端按 kind 区分展示) + */ + @GetMapping + public CommonResult> listByObject(@RequestParam String objectType, + @RequestParam String objectNum) { + return CommonResult.success(markerService.listByObject(MarkerObjectTypeEnum.parse(objectType), objectNum)); + } + + /** + * 批量列出多个对象的标记(列表页一次取回一页,避免逐个请求) + */ + @PostMapping("/batch") + public CommonResult>> listByObjects( + @RequestParam String objectType, + @RequestBody Collection objectNums) { + return CommonResult.success( + markerService.listByObjects(MarkerObjectTypeEnum.parse(objectType), objectNums)); + } + + /** + * 给对象打一个用户标签(幂等) + */ + @PostMapping + @Operation(summary = "打用户标签;系统标记只能由系统写入,不开放此接口") + public CommonResult addUserTag(@RequestBody Map body) + throws ErrorParameterException, NotFindEntitiesException { + String objectType = body == null ? null : body.get("objectType"); + String objectNum = body == null ? null : body.get("objectNum"); + String markerName = body == null ? null : body.get("markerName"); + return CommonResult.success( + markerService.addUserTag(MarkerObjectTypeEnum.parse(objectType), objectNum, markerName)); + } + + /** + * 删除一个用户标签;系统标记不可删除 + */ + @DeleteMapping("/{id}") + public CommonResult deleteMarker(@PathVariable Integer id) + throws ErrorParameterException, NotFindEntitiesException { + markerService.deleteMarker(id); + return CommonResult.success(); + } + + /** + * 重命名一个用户标签(影响所有带该标签的对象) + */ + @PutMapping("/rename") + public CommonResult renameUserTag(@RequestBody Map body) + throws ErrorParameterException { + String from = body == null ? null : body.get("oldName"); + String to = body == null ? null : body.get("newName"); + return CommonResult.success(markerService.renameUserTag(from, to)); + } + + /** + * 按标记筛选对象(点标签即筛选):返回带该标记的对象标识列表 + */ + @GetMapping("/filter") + public CommonResult> filterByMarker(@RequestParam String objectType, + @RequestParam String markerName, + @RequestParam(required = false) String markerValue, + @RequestParam(required = false) String kind) { + return CommonResult.success(markerService.findObjectNumsByMarker( + MarkerObjectTypeEnum.parse(objectType), markerName, markerValue, kind)); + } + + /** + * 当前用户用过的标签及使用情况(标签管理入口) + */ + @GetMapping("/tags") + public CommonResult> listUserTagUsage() { + return CommonResult.success(markerService.listUserTagUsage()); + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/dto/MarkerUsage.java b/src/main/java/com/guo/learningprogresstracker/dto/MarkerUsage.java new file mode 100644 index 0000000..c4ee4de --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/dto/MarkerUsage.java @@ -0,0 +1,18 @@ +package com.guo.learningprogresstracker.dto; + +import lombok.Data; + +/** + * 用户标签的使用情况(标记-01 的标签管理入口)。 + */ +@Data +public class MarkerUsage { + + private String markerName; + + /** 该标签一共被打了多少次 */ + private Long markerCount; + + /** 该标签覆盖了多少个对象 */ + private Long objectCount; +} diff --git a/src/main/java/com/guo/learningprogresstracker/entity/MarkerEntity.java b/src/main/java/com/guo/learningprogresstracker/entity/MarkerEntity.java new file mode 100644 index 0000000..5754060 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/entity/MarkerEntity.java @@ -0,0 +1,50 @@ +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 = "markers") +@Data +public class MarkerEntity extends BaseEntity implements Serializable { + + @TableId(value = "id", type = IdType.AUTO) + private Integer id; + + /** FRAGMENT | TASK,取值见 {@code MarkerObjectTypeEnum} */ + @TableField(value = "object_type") + private String objectType; + + /** 对象标识:碎片 id 或 任务编号 */ + @TableField(value = "object_num") + private String objectNum; + + /** SYSTEM | USER,取值见 {@code MarkerKindEnum} */ + @TableField(value = "kind") + private String kind; + + /** 标记名:系统标记来自固定词表;用户标签自由输入 */ + @TableField(value = "marker_name") + private String markerName; + + /** 标记值:系统标记成对使用;用户标签留空(标签名本身就是全部信息) */ + @TableField(value = "marker_value") + private String markerValue; + + @TableField(exist = false) + private static final long serialVersionUID = 1L; + + public boolean isSystemMarker() { + return com.guo.learningprogresstracker.enums.MarkerKindEnum.SYSTEM.name().equals(kind); + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/enums/MarkerKindEnum.java b/src/main/java/com/guo/learningprogresstracker/enums/MarkerKindEnum.java new file mode 100644 index 0000000..9a4fc55 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/enums/MarkerKindEnum.java @@ -0,0 +1,20 @@ +package com.guo.learningprogresstracker.enums; + +import lombok.AllArgsConstructor; +import lombok.Getter; + +/** + * 标记种类(标记-01)。 + * + *

两类彻底分开:系统标记由系统按固定词表写入、用户只读;用户标签由用户自由增删改。 + * 分开的理由是「找出所有来自 X 的内容」这类检索的可靠性依赖于系统标记没被改过。

+ */ +@Getter +@AllArgsConstructor +public enum MarkerKindEnum { + + SYSTEM("系统标记"), + USER("用户标签"); + + private final String description; +} diff --git a/src/main/java/com/guo/learningprogresstracker/enums/MarkerObjectTypeEnum.java b/src/main/java/com/guo/learningprogresstracker/enums/MarkerObjectTypeEnum.java new file mode 100644 index 0000000..11527e0 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/enums/MarkerObjectTypeEnum.java @@ -0,0 +1,31 @@ +package com.guo.learningprogresstracker.enums; + +import lombok.AllArgsConstructor; +import lombok.Getter; + +/** + * 标记可挂的对象类型(标记-01)。 + * + *

只允许知识碎片与学习任务:报告是会话的派生结果(且自身已有「按归属分组」这一维度, + * 再挂标记会出现两套分组语义),会话是时间轴对象(其流程性信息按边界要求留在主体上)。

+ */ +@Getter +@AllArgsConstructor +public enum MarkerObjectTypeEnum { + + FRAGMENT("知识碎片"), + TASK("学习任务"); + + private final String description; + + public static MarkerObjectTypeEnum parse(String value) { + if (value == null || value.isBlank()) { + return null; + } + try { + return valueOf(value.trim().toUpperCase()); + } catch (IllegalArgumentException e) { + return null; + } + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/enums/SystemMarkerEnum.java b/src/main/java/com/guo/learningprogresstracker/enums/SystemMarkerEnum.java new file mode 100644 index 0000000..5c73fcb --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/enums/SystemMarkerEnum.java @@ -0,0 +1,24 @@ +package com.guo.learningprogresstracker.enums; + +import lombok.AllArgsConstructor; +import lombok.Getter; + +/** + * 系统标记的固定词表(标记-01)。 + * + *

新增一种系统标记只改这里,不需要动各功能表结构——这正是「标记统一存放」的目的。 + * 词表跟着代码走:系统标记由系统在产出时写入,用户只读、不可删改。

+ */ +@Getter +@AllArgsConstructor +public enum SystemMarkerEnum { + + /** 学习引导产出的知识碎片(复习-06) */ + FROM_GUIDANCE("来源", "学习引导"); + + /** 标记名(成对表达中的「名」) */ + private final String markerName; + + /** 标记值(成对表达中的「值」) */ + private final String markerValue; +} diff --git a/src/main/java/com/guo/learningprogresstracker/mapper/MarkerMapper.java b/src/main/java/com/guo/learningprogresstracker/mapper/MarkerMapper.java new file mode 100644 index 0000000..257263e --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/mapper/MarkerMapper.java @@ -0,0 +1,31 @@ +package com.guo.learningprogresstracker.mapper; + +import com.baomidou.mybatisplus.core.mapper.BaseMapper; +import com.guo.learningprogresstracker.dto.MarkerUsage; +import com.guo.learningprogresstracker.entity.MarkerEntity; +import org.apache.ibatis.annotations.Mapper; +import org.apache.ibatis.annotations.Param; +import org.apache.ibatis.annotations.Select; + +import java.util.List; + +@Mapper +public interface MarkerMapper extends BaseMapper { + + /** + * 当前用户用过的标签及各自的对象数量(标记-01 的标签管理入口)。 + *

只统计用户标签:系统标记不在用户的治理范围内。

+ */ + @Select(""" + SELECT marker_name AS marker_name, + COUNT(*) AS marker_count, + COUNT(DISTINCT object_num) AS object_count + FROM markers + WHERE deleted = 0 + AND kind = 'USER' + AND created_by = #{createdBy} + GROUP BY marker_name + ORDER BY marker_count DESC, marker_name ASC + """) + List selectUserTagUsage(@Param("createdBy") String createdBy); +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/MarkerService.java b/src/main/java/com/guo/learningprogresstracker/service/MarkerService.java new file mode 100644 index 0000000..b770fef --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/MarkerService.java @@ -0,0 +1,79 @@ +package com.guo.learningprogresstracker.service; + +import com.guo.learningprogresstracker.dto.MarkerUsage; +import com.guo.learningprogresstracker.entity.MarkerEntity; +import com.guo.learningprogresstracker.enums.MarkerObjectTypeEnum; +import com.guo.learningprogresstracker.enums.SystemMarkerEnum; +import com.guo.learningprogresstracker.exception.ErrorParameterException; +import com.guo.learningprogresstracker.exception.NotFindEntitiesException; + +import java.util.Collection; +import java.util.List; +import java.util.Map; + +/** + * 统一标记服务(标记-01)。 + * + *

两类标记的能力刻意不同:

+ *
    + *
  • 用户标签:可增加、可重命名、可删除。改名是安全的——标记不参与聚合口径, + * 批量改名不会像改内容归属那样污染统计与检索口径。
  • + *
  • 系统标记:只能由系统按 {@link SystemMarkerEnum} 词表写入,用户不可增删改。 + * 这样「找出所有来自 X 的内容」这类检索才可靠。
  • + *
+ */ +public interface MarkerService { + + /** + * 列出某个对象上的全部标记(系统标记与标签一起返回,前端按 kind 区分展示)。 + */ + List listByObject(MarkerObjectTypeEnum objectType, String objectNum); + + /** + * 批量列出多个对象的标记,键为对象标识。 + *

用于列表页一次取回一页对象的标记,避免逐个请求。

+ */ + Map> listByObjects(MarkerObjectTypeEnum objectType, Collection objectNums); + + /** + * 给对象打一个用户标签(幂等:重复打同一标签不产生重复数据)。 + */ + MarkerEntity addUserTag(MarkerObjectTypeEnum objectType, String objectNum, String markerName) + throws ErrorParameterException, NotFindEntitiesException; + + /** + * 删除一个用户标签;系统标记不可删除。 + */ + void deleteMarker(Integer id) throws ErrorParameterException, NotFindEntitiesException; + + /** + * 重命名一个用户标签:影响所有带该标签的对象;系统标记不可重命名。 + * + * @return 被改写的标记条数 + */ + int renameUserTag(String oldName, String newName) throws ErrorParameterException; + + /** + * 按标记筛选对象:返回带该标记的对象标识列表(单一标记筛选,不做组合)。 + * + * @param kind 可传 SYSTEM / USER 限定种类,null 表示不限 + */ + List findObjectNumsByMarker(MarkerObjectTypeEnum objectType, String markerName, String markerValue, + String kind); + + /** + * 当前用户用过的标签及使用情况(标签管理界面)。 + */ + List listUserTagUsage(); + + /** + * 写入一个系统标记,供系统在产出内容时调用(如学习引导产出的碎片)。 + *

幂等;标记名与值必须来自 {@link SystemMarkerEnum} 词表。

+ */ + void addSystemMarker(MarkerObjectTypeEnum objectType, String objectNum, SystemMarkerEnum marker); + + /** + * 对象被删除时清理其标记(例如碎片被删除)。 + */ + void removeAllMarkers(MarkerObjectTypeEnum objectType, String objectNum); +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/MarkerServiceImpl.java b/src/main/java/com/guo/learningprogresstracker/service/impl/MarkerServiceImpl.java new file mode 100644 index 0000000..3b1f355 --- /dev/null +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/MarkerServiceImpl.java @@ -0,0 +1,272 @@ +package com.guo.learningprogresstracker.service.impl; + +import com.baomidou.mybatisplus.core.toolkit.Wrappers; +import com.guo.learningprogresstracker.dto.MarkerUsage; +import com.guo.learningprogresstracker.entity.MarkerEntity; +import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity; +import com.guo.learningprogresstracker.entity.TaskEntity; +import com.guo.learningprogresstracker.enums.MarkerKindEnum; +import com.guo.learningprogresstracker.enums.MarkerObjectTypeEnum; +import com.guo.learningprogresstracker.enums.SystemMarkerEnum; +import com.guo.learningprogresstracker.exception.ErrorParameterException; +import com.guo.learningprogresstracker.exception.NotFindEntitiesException; +import com.guo.learningprogresstracker.mapper.MarkerMapper; +import com.guo.learningprogresstracker.mapper.StudyReportFragmentsMapper; +import com.guo.learningprogresstracker.mapper.TasksMapper; +import com.guo.learningprogresstracker.service.MarkerService; +import lombok.RequiredArgsConstructor; +import lombok.extern.slf4j.Slf4j; +import org.springframework.stereotype.Service; +import org.springframework.transaction.annotation.Transactional; +import org.springframework.util.StringUtils; + +import java.util.Collection; +import java.util.Collections; +import java.util.LinkedHashMap; +import java.util.List; +import java.util.Map; +import java.util.Optional; +import java.util.stream.Collectors; + +/** + * 统一标记服务实现(标记-01)。 + */ +@Slf4j +@Service +@RequiredArgsConstructor +public class MarkerServiceImpl implements MarkerService { + + /** 用户标签名的长度上限,与表结构一致 */ + private static final int MAX_MARKER_NAME_LENGTH = 100; + + private final MarkerMapper markerMapper; + private final StudyReportFragmentsMapper studyReportFragmentsMapper; + private final TasksMapper tasksMapper; + + @Override + public List listByObject(MarkerObjectTypeEnum objectType, String objectNum) { + if (objectType == null || !StringUtils.hasText(objectNum)) { + return Collections.emptyList(); + } + return markerMapper.selectList(Wrappers.lambdaQuery() + .eq(MarkerEntity::getObjectType, objectType.name()) + .eq(MarkerEntity::getObjectNum, objectNum.trim()) + // 系统标记排在前面,用户标签随后 + .orderByAsc(MarkerEntity::getKind) + .orderByAsc(MarkerEntity::getId)); + } + + @Override + public Map> listByObjects(MarkerObjectTypeEnum objectType, Collection objectNums) { + if (objectType == null || objectNums == null || objectNums.isEmpty()) { + return Collections.emptyMap(); + } + List markers = markerMapper.selectList(Wrappers.lambdaQuery() + .eq(MarkerEntity::getObjectType, objectType.name()) + .in(MarkerEntity::getObjectNum, objectNums) + .orderByAsc(MarkerEntity::getKind) + .orderByAsc(MarkerEntity::getId)); + return markers.stream().collect(Collectors.groupingBy( + MarkerEntity::getObjectNum, LinkedHashMap::new, Collectors.toList())); + } + + @Override + @Transactional + public MarkerEntity addUserTag(MarkerObjectTypeEnum objectType, String objectNum, String markerName) + throws ErrorParameterException, NotFindEntitiesException { + String name = normalizeTagName(markerName); + String num = normalizeObjectNum(objectNum, objectType); + + // 幂等:同一对象上同名同类同值的标记只保留一条 + Optional existing = markerMapper.selectList(Wrappers.lambdaQuery() + .eq(MarkerEntity::getObjectType, objectType.name()) + .eq(MarkerEntity::getObjectNum, num) + .eq(MarkerEntity::getKind, MarkerKindEnum.USER.name()) + .eq(MarkerEntity::getMarkerName, name) + .last("LIMIT 1")) + .stream().findFirst(); + if (existing.isPresent()) { + return existing.get(); + } + + MarkerEntity marker = new MarkerEntity(); + marker.setObjectType(objectType.name()); + marker.setObjectNum(num); + marker.setKind(MarkerKindEnum.USER.name()); + marker.setMarkerName(name); + // 用户标签只有名,没有值:标签名本身就是全部信息 + marker.setMarkerValue(null); + markerMapper.insert(marker); + return marker; + } + + @Override + public void deleteMarker(Integer id) throws ErrorParameterException, NotFindEntitiesException { + MarkerEntity existing = requireMarker(id); + if (existing.isSystemMarker()) { + log.warn("系统标记[{}]不允许用户删除", existing.getMarkerName()); + throw new ErrorParameterException("这是系统标记,不能删除"); + } + markerMapper.deleteById(existing.getId()); + } + + @Override + @Transactional + public int renameUserTag(String oldName, String newName) throws ErrorParameterException { + String from = normalizeTagName(oldName); + String to = normalizeTagName(newName); + if (from.equals(to)) { + return 0; + } + + List targets = markerMapper.selectList(Wrappers.lambdaQuery() + .eq(MarkerEntity::getKind, MarkerKindEnum.USER.name()) + .eq(MarkerEntity::getMarkerName, from)); + if (targets.isEmpty()) { + log.warn("标签[{}]不存在,无需重命名", from); + throw new ErrorParameterException("这个标签不存在"); + } + + int renamed = 0; + for (MarkerEntity marker : targets) { + // 目标标签已存在于同一对象时,这条改名后的记录会与既有记录重复,直接清掉 + boolean duplicateExists = markerMapper.exists(Wrappers.lambdaQuery() + .eq(MarkerEntity::getObjectType, marker.getObjectType()) + .eq(MarkerEntity::getObjectNum, marker.getObjectNum()) + .eq(MarkerEntity::getKind, MarkerKindEnum.USER.name()) + .eq(MarkerEntity::getMarkerName, to)); + if (duplicateExists) { + markerMapper.deleteById(marker.getId()); + continue; + } + MarkerEntity patch = new MarkerEntity(); + patch.setId(marker.getId()); + patch.setMarkerName(to); + markerMapper.updateById(patch); + renamed++; + } + log.info("标签[{}]重命名为[{}],影响 {} 条标记", from, to, renamed); + return renamed; + } + + @Override + public List findObjectNumsByMarker(MarkerObjectTypeEnum objectType, String markerName, String markerValue, + String kind) { + if (objectType == null || !StringUtils.hasText(markerName)) { + return Collections.emptyList(); + } + return markerMapper.selectList(Wrappers.lambdaQuery() + .eq(MarkerEntity::getObjectType, objectType.name()) + .eq(MarkerEntity::getMarkerName, markerName.trim()) + .eq(StringUtils.hasText(markerValue), MarkerEntity::getMarkerValue, markerValue) + .eq(StringUtils.hasText(kind), MarkerEntity::getKind, kind) + .select(MarkerEntity::getObjectNum)) + .stream() + .map(MarkerEntity::getObjectNum) + .distinct() + .collect(Collectors.toList()); + } + + @Override + public List listUserTagUsage() { + String createdBy = currentUser(); + if (!StringUtils.hasText(createdBy)) { + return Collections.emptyList(); + } + return markerMapper.selectUserTagUsage(createdBy); + } + + @Override + public void addSystemMarker(MarkerObjectTypeEnum objectType, String objectNum, SystemMarkerEnum marker) { + if (objectType == null || !StringUtils.hasText(objectNum) || marker == null) { + return; + } + String num = objectNum.trim(); + boolean exists = markerMapper.exists(Wrappers.lambdaQuery() + .eq(MarkerEntity::getObjectType, objectType.name()) + .eq(MarkerEntity::getObjectNum, num) + .eq(MarkerEntity::getKind, MarkerKindEnum.SYSTEM.name()) + .eq(MarkerEntity::getMarkerName, marker.getMarkerName())); + if (exists) { + return; + } + MarkerEntity entity = new MarkerEntity(); + entity.setObjectType(objectType.name()); + entity.setObjectNum(num); + entity.setKind(MarkerKindEnum.SYSTEM.name()); + entity.setMarkerName(marker.getMarkerName()); + entity.setMarkerValue(marker.getMarkerValue()); + markerMapper.insert(entity); + } + + @Override + public void removeAllMarkers(MarkerObjectTypeEnum objectType, String objectNum) { + if (objectType == null || !StringUtils.hasText(objectNum)) { + return; + } + int removed = markerMapper.delete(Wrappers.lambdaQuery() + .eq(MarkerEntity::getObjectType, objectType.name()) + .eq(MarkerEntity::getObjectNum, objectNum.trim())); + if (removed > 0) { + log.info("对象[{}/{}]的 {} 条标记已随对象删除", objectType, objectNum, removed); + } + } + + private MarkerEntity requireMarker(Integer id) throws NotFindEntitiesException { + MarkerEntity existing = id == null ? null : markerMapper.selectById(id); + if (existing == null) { + log.warn("未能找到标记id[{}]", id); + throw new NotFindEntitiesException("这个标记不存在或已被删除"); + } + return existing; + } + + /** 标签名规范化:去首尾空白并限制长度 */ + private String normalizeTagName(String markerName) throws ErrorParameterException { + if (!StringUtils.hasText(markerName)) { + throw new ErrorParameterException("标签名不能为空"); + } + String name = markerName.trim(); + if (name.length() > MAX_MARKER_NAME_LENGTH) { + throw new ErrorParameterException("标签名太长了,请控制在 " + MAX_MARKER_NAME_LENGTH + " 个字符以内"); + } + return name; + } + + /** + * 校验标记对象存在,并规范化对象标识。 + *

碎片的对象标识由数字 id 转成字符串,保证与查询时一致。

+ */ + private String normalizeObjectNum(String objectNum, MarkerObjectTypeEnum objectType) + throws ErrorParameterException, NotFindEntitiesException { + if (!StringUtils.hasText(objectNum)) { + throw new ErrorParameterException("请先指定要打标记的对象"); + } + String num = objectNum.trim(); + if (objectType == MarkerObjectTypeEnum.FRAGMENT) { + Integer fragmentId; + try { + fragmentId = Integer.valueOf(num); + } catch (NumberFormatException e) { + throw new ErrorParameterException("知识碎片的标识不正确"); + } + if (studyReportFragmentsMapper.selectById(fragmentId) == null) { + throw new NotFindEntitiesException("这条知识碎片不存在或已被删除"); + } + return num; + } + if (!tasksMapper.exists(Wrappers.lambdaQuery().eq(TaskEntity::getTaskNum, num))) { + throw new NotFindEntitiesException("这个任务不存在或已被删除"); + } + return num; + } + + /** 当前登录用户,用于标签使用情况的统计(该查询不走拦截器,需显式传入) */ + private String currentUser() { + try { + return cn.dev33.satoken.stp.StpUtil.getLoginIdAsString(); + } catch (Exception e) { + return null; + } + } +} diff --git a/src/main/java/com/guo/learningprogresstracker/service/impl/StudyReportFragmentsServiceImpl.java b/src/main/java/com/guo/learningprogresstracker/service/impl/StudyReportFragmentsServiceImpl.java index 8a5856e..f7bcbf7 100644 --- a/src/main/java/com/guo/learningprogresstracker/service/impl/StudyReportFragmentsServiceImpl.java +++ b/src/main/java/com/guo/learningprogresstracker/service/impl/StudyReportFragmentsServiceImpl.java @@ -42,6 +42,7 @@ public class StudyReportFragmentsServiceImpl extends ServiceImpl markers = markerService.listByObject( + MarkerObjectTypeEnum.FRAGMENT, String.valueOf(fragment.getId())); + assertEquals(1, markers.size()); + assertEquals("英语", markers.get(0).getMarkerName()); + assertEquals(MarkerKindEnum.USER.name(), markers.get(0).getKind()); + assertNull(markers.get(0).getMarkerValue(), "用户标签只有名,没有值"); + } + + @Test + void taskCanBeTaggedToo() throws Exception { + String taskNum = saveTask(); + markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, "考研"); + + List markers = markerService.listByObject(MarkerObjectTypeEnum.TASK, taskNum); + assertEquals(1, markers.size()); + assertEquals("考研", markers.get(0).getMarkerName()); + } + + @Test + void taggingMissingObject_isRejected() { + assertThrows(NotFindEntitiesException.class, + () -> markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, "999999", "英语")); + assertThrows(NotFindEntitiesException.class, + () -> markerService.addUserTag(MarkerObjectTypeEnum.TASK, "TASK-NOT-EXIST", "英语")); + } + + @Test + void blankTagName_isRejected() { + String taskNum = saveTask(); + assertThrows(ErrorParameterException.class, + () -> markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, " ")); + } + + @Test + void renameUserTag_affectsAllObjects() throws Exception { + String taskNum = saveTask(); + StudyReportFragmentsEntity first = saveFragment(taskNum); + StudyReportFragmentsEntity second = saveFragment(taskNum); + markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(first.getId()), "英文"); + markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(second.getId()), "英文"); + markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, "英文"); + + int renamed = markerService.renameUserTag("英文", "英语"); + + assertEquals(3, renamed); + assertTrue(markerService.findObjectNumsByMarker( + MarkerObjectTypeEnum.FRAGMENT, "英文", null, null).isEmpty()); + assertEquals(2, markerService.findObjectNumsByMarker( + MarkerObjectTypeEnum.FRAGMENT, "英语", null, null).size()); + } + + @Test + void renameIntoExistingTag_doesNotCreateDuplicate() throws Exception { + String taskNum = saveTask(); + StudyReportFragmentsEntity fragment = saveFragment(taskNum); + String id = String.valueOf(fragment.getId()); + markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, "英文"); + markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, "英语"); + + markerService.renameUserTag("英文", "英语"); + + assertEquals(1, markerService.listByObject(MarkerObjectTypeEnum.FRAGMENT, id).size(), + "同一对象上合并同名标签时不应产生重复"); + } + + @Test + void deleteUserTag_removesIt() throws Exception { + String taskNum = saveTask(); + MarkerEntity tag = markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, "待看"); + + markerService.deleteMarker(tag.getId()); + + assertTrue(markerService.listByObject(MarkerObjectTypeEnum.TASK, taskNum).isEmpty()); + } + + @Test + void systemMarker_isVisibleButNotEditable() throws Exception { + String taskNum = saveTask(); + StudyReportFragmentsEntity fragment = saveFragment(taskNum); + String id = String.valueOf(fragment.getId()); + + markerService.addSystemMarker(MarkerObjectTypeEnum.FRAGMENT, id, SystemMarkerEnum.FROM_GUIDANCE); + + List markers = markerService.listByObject(MarkerObjectTypeEnum.FRAGMENT, id); + assertEquals(1, markers.size(), "系统标记对用户可见"); + assertEquals(MarkerKindEnum.SYSTEM.name(), markers.get(0).getKind()); + assertEquals("来源", markers.get(0).getMarkerName()); + assertEquals("学习引导", markers.get(0).getMarkerValue()); + + // 用户不能删除系统标记 + assertThrows(ErrorParameterException.class, () -> markerService.deleteMarker(markers.get(0).getId())); + } + + @Test + void systemMarker_isIdempotentAndSearchable() { + String taskNum = saveTask(); + StudyReportFragmentsEntity fragment = saveFragment(taskNum); + String id = String.valueOf(fragment.getId()); + + markerService.addSystemMarker(MarkerObjectTypeEnum.FRAGMENT, id, SystemMarkerEnum.FROM_GUIDANCE); + markerService.addSystemMarker(MarkerObjectTypeEnum.FRAGMENT, id, SystemMarkerEnum.FROM_GUIDANCE); + + // 幂等:同一对象上不产生重复的系统标记 + long onThisFragment = markerService.listByObject(MarkerObjectTypeEnum.FRAGMENT, id).stream() + .filter(MarkerEntity::isSystemMarker) + .count(); + assertEquals(1, onThisFragment); + + // 可被可靠检索:本用例的对象出现在筛选结果里(同类其它用例也写过同名标记,故不断言总数) + List found = markerService.findObjectNumsByMarker( + MarkerObjectTypeEnum.FRAGMENT, "来源", "学习引导", MarkerKindEnum.SYSTEM.name()); + assertTrue(found.contains(id), "系统标记可被可靠检索"); + } + + @Test + void batchListing_groupsMarkersByObject() throws Exception { + String taskNum = saveTask(); + StudyReportFragmentsEntity first = saveFragment(taskNum); + StudyReportFragmentsEntity second = saveFragment(taskNum); + markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(first.getId()), "英语"); + markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(second.getId()), "数学"); + + Map> grouped = markerService.listByObjects( + MarkerObjectTypeEnum.FRAGMENT, + List.of(String.valueOf(first.getId()), String.valueOf(second.getId()))); + + assertEquals(2, grouped.size()); + assertEquals("英语", grouped.get(String.valueOf(first.getId())).get(0).getMarkerName()); + assertEquals("数学", grouped.get(String.valueOf(second.getId())).get(0).getMarkerName()); + } + + @Test + void tagUsage_listsUserTagsOnly() throws Exception { + String taskNum = saveTask(); + StudyReportFragmentsEntity fragment = saveFragment(taskNum); + String id = String.valueOf(fragment.getId()); + markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, "集成测试标签A"); + markerService.addSystemMarker(MarkerObjectTypeEnum.FRAGMENT, id, SystemMarkerEnum.FROM_GUIDANCE); + + List usage = markerService.listUserTagUsage(); + + assertTrue(usage.stream().anyMatch(u -> "集成测试标签A".equals(u.getMarkerName())), + "用户标签应出现在使用情况里"); + assertTrue(usage.stream().noneMatch(u -> "来源".equals(u.getMarkerName())), + "系统标记不在用户的治理范围内"); + } + + @Test + void markersAreScopedPerUser() throws Exception { + String taskNum = saveTask(); + markerService.addUserTag(MarkerObjectTypeEnum.TASK, taskNum, "我的标签"); + + StpUtil.login("标记集成测试另一个用户", "test_device"); + assertTrue(markerService.listByObject(MarkerObjectTypeEnum.TASK, taskNum).isEmpty(), + "标记同样受租户隔离约束,看不到别人的标签"); + } + + @Test + void markersAreRemovedWithObject() throws Exception { + String taskNum = saveTask(); + StudyReportFragmentsEntity fragment = saveFragment(taskNum); + String id = String.valueOf(fragment.getId()); + markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, id, "英语"); + markerService.addSystemMarker(MarkerObjectTypeEnum.FRAGMENT, id, SystemMarkerEnum.FROM_GUIDANCE); + + markerService.removeAllMarkers(MarkerObjectTypeEnum.FRAGMENT, id); + + assertTrue(markerService.listByObject(MarkerObjectTypeEnum.FRAGMENT, id).isEmpty(), + "对象删除后其标记不应再出现在列表里"); + } +}