feat: 新增统一标记存储与单一标记筛选

This commit is contained in:
2026-10-09 19:25:34 +08:00
parent 63824b26a0
commit c6258fa6d7
12 changed files with 934 additions and 0 deletions
@@ -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)。
*
* <p>标记对用户全部可见;用户标签可增删改,系统标记只读。
* 检索只提供「单一标记筛选」,不做多标记组合——标签的唯一作用就是检索,而组合筛选目前没有真实场景。</p>
*/
@RequestMapping("/markers")
@RestController
@Validated
@RequiredArgsConstructor
public class MarkerController {
private final MarkerService markerService;
/**
* 列出某个对象上的全部标记(系统标记与用户标签一起返回,前端按 kind 区分展示)
*/
@GetMapping
public CommonResult<List<MarkerEntity>> listByObject(@RequestParam String objectType,
@RequestParam String objectNum) {
return CommonResult.success(markerService.listByObject(MarkerObjectTypeEnum.parse(objectType), objectNum));
}
/**
* 批量列出多个对象的标记(列表页一次取回一页,避免逐个请求)
*/
@PostMapping("/batch")
public CommonResult<Map<String, List<MarkerEntity>>> listByObjects(
@RequestParam String objectType,
@RequestBody Collection<String> objectNums) {
return CommonResult.success(
markerService.listByObjects(MarkerObjectTypeEnum.parse(objectType), objectNums));
}
/**
* 给对象打一个用户标签(幂等)
*/
@PostMapping
@Operation(summary = "打用户标签;系统标记只能由系统写入,不开放此接口")
public CommonResult<MarkerEntity> addUserTag(@RequestBody Map<String, String> 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<Void> deleteMarker(@PathVariable Integer id)
throws ErrorParameterException, NotFindEntitiesException {
markerService.deleteMarker(id);
return CommonResult.success();
}
/**
* 重命名一个用户标签(影响所有带该标签的对象)
*/
@PutMapping("/rename")
public CommonResult<Integer> renameUserTag(@RequestBody Map<String, String> 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<List<String>> 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<List<MarkerUsage>> listUserTagUsage() {
return CommonResult.success(markerService.listUserTagUsage());
}
}
@@ -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;
}
@@ -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):附加在对象上的一段轻量元信息。
*
* <p>标记不是状态,也不参与聚合口径:会话状态、报告可否修订、导图是否待更新这类流程判断
* 留在各自主体上;内容归属是唯一的结构归属,标记不能用来表达第二归属。</p>
*/
@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);
}
}
@@ -0,0 +1,20 @@
package com.guo.learningprogresstracker.enums;
import lombok.AllArgsConstructor;
import lombok.Getter;
/**
* 标记种类(标记-01)。
*
* <p>两类彻底分开:系统标记由系统按固定词表写入、用户只读;用户标签由用户自由增删改。
* 分开的理由是「找出所有来自 X 的内容」这类检索的可靠性依赖于系统标记没被改过。</p>
*/
@Getter
@AllArgsConstructor
public enum MarkerKindEnum {
SYSTEM("系统标记"),
USER("用户标签");
private final String description;
}
@@ -0,0 +1,31 @@
package com.guo.learningprogresstracker.enums;
import lombok.AllArgsConstructor;
import lombok.Getter;
/**
* 标记可挂的对象类型(标记-01)。
*
* <p>只允许知识碎片与学习任务:报告是会话的派生结果(且自身已有「按归属分组」这一维度,
* 再挂标记会出现两套分组语义),会话是时间轴对象(其流程性信息按边界要求留在主体上)。</p>
*/
@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;
}
}
}
@@ -0,0 +1,24 @@
package com.guo.learningprogresstracker.enums;
import lombok.AllArgsConstructor;
import lombok.Getter;
/**
* 系统标记的固定词表(标记-01)。
*
* <p>新增一种系统标记只改这里,不需要动各功能表结构——这正是「标记统一存放」的目的。
* 词表跟着代码走:系统标记由系统在产出时写入,用户只读、不可删改。</p>
*/
@Getter
@AllArgsConstructor
public enum SystemMarkerEnum {
/** 学习引导产出的知识碎片(复习-06) */
FROM_GUIDANCE("来源", "学习引导");
/** 标记名(成对表达中的「名」) */
private final String markerName;
/** 标记值(成对表达中的「值」) */
private final String markerValue;
}
@@ -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<MarkerEntity> {
/**
* 当前用户用过的标签及各自的对象数量(标记-01 的标签管理入口)。
* <p>只统计用户标签:系统标记不在用户的治理范围内。</p>
*/
@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<MarkerUsage> selectUserTagUsage(@Param("createdBy") String createdBy);
}
@@ -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)。
*
* <p>两类标记的能力刻意不同:</p>
* <ul>
* <li><b>用户标签</b>:可增加、可重命名、可删除。改名是安全的——标记不参与聚合口径,
* 批量改名不会像改内容归属那样污染统计与检索口径。</li>
* <li><b>系统标记</b>:只能由系统按 {@link SystemMarkerEnum} 词表写入,用户不可增删改。
* 这样「找出所有来自 X 的内容」这类检索才可靠。</li>
* </ul>
*/
public interface MarkerService {
/**
* 列出某个对象上的全部标记(系统标记与标签一起返回,前端按 kind 区分展示)。
*/
List<MarkerEntity> listByObject(MarkerObjectTypeEnum objectType, String objectNum);
/**
* 批量列出多个对象的标记,键为对象标识。
* <p>用于列表页一次取回一页对象的标记,避免逐个请求。</p>
*/
Map<String, List<MarkerEntity>> listByObjects(MarkerObjectTypeEnum objectType, Collection<String> 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<String> findObjectNumsByMarker(MarkerObjectTypeEnum objectType, String markerName, String markerValue,
String kind);
/**
* 当前用户用过的标签及使用情况(标签管理界面)。
*/
List<MarkerUsage> listUserTagUsage();
/**
* 写入一个系统标记,供系统在产出内容时调用(如学习引导产出的碎片)。
* <p>幂等;标记名与值必须来自 {@link SystemMarkerEnum} 词表。</p>
*/
void addSystemMarker(MarkerObjectTypeEnum objectType, String objectNum, SystemMarkerEnum marker);
/**
* 对象被删除时清理其标记(例如碎片被删除)。
*/
void removeAllMarkers(MarkerObjectTypeEnum objectType, String objectNum);
}
@@ -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<MarkerEntity> listByObject(MarkerObjectTypeEnum objectType, String objectNum) {
if (objectType == null || !StringUtils.hasText(objectNum)) {
return Collections.emptyList();
}
return markerMapper.selectList(Wrappers.<MarkerEntity>lambdaQuery()
.eq(MarkerEntity::getObjectType, objectType.name())
.eq(MarkerEntity::getObjectNum, objectNum.trim())
// 系统标记排在前面,用户标签随后
.orderByAsc(MarkerEntity::getKind)
.orderByAsc(MarkerEntity::getId));
}
@Override
public Map<String, List<MarkerEntity>> listByObjects(MarkerObjectTypeEnum objectType, Collection<String> objectNums) {
if (objectType == null || objectNums == null || objectNums.isEmpty()) {
return Collections.emptyMap();
}
List<MarkerEntity> markers = markerMapper.selectList(Wrappers.<MarkerEntity>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<MarkerEntity> existing = markerMapper.selectList(Wrappers.<MarkerEntity>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<MarkerEntity> targets = markerMapper.selectList(Wrappers.<MarkerEntity>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.<MarkerEntity>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<String> findObjectNumsByMarker(MarkerObjectTypeEnum objectType, String markerName, String markerValue,
String kind) {
if (objectType == null || !StringUtils.hasText(markerName)) {
return Collections.emptyList();
}
return markerMapper.selectList(Wrappers.<MarkerEntity>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<MarkerUsage> 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.<MarkerEntity>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.<MarkerEntity>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;
}
/**
* 校验标记对象存在,并规范化对象标识。
* <p>碎片的对象标识由数字 id 转成字符串,保证与查询时一致。</p>
*/
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.<TaskEntity>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;
}
}
}
@@ -42,6 +42,7 @@ public class StudyReportFragmentsServiceImpl extends ServiceImpl<StudyReportFrag
private final StudySessionsMapper studySessionsMapper;
private final TasksMapper tasksMapper;
private final ReviewStandardMindMapMapper reviewStandardMindMapMapper;
private final com.guo.learningprogresstracker.service.MarkerService markerService;
@Override
@Transactional
@@ -114,6 +115,9 @@ public class StudyReportFragmentsServiceImpl extends ServiceImpl<StudyReportFrag
}
// 软删除;所属任务的导图需要重建
this.removeById(id);
// 对象没了,它身上的标记也不再有意义(标记-01)
markerService.removeAllMarkers(
com.guo.learningprogresstracker.enums.MarkerObjectTypeEnum.FRAGMENT, String.valueOf(id));
markMindMapStale(existing.getOwnerTaskNum());
log.info("碎片[{}]已删除", id);
}