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);
}
@@ -0,0 +1,34 @@
-- 标记-01:统一标记存储。
--
-- 口径来源(2026-10-09 维护者确认,结论见 lpt-docs/docs/concepts/marker.md):
-- 可挂对象:知识碎片与学习任务(报告是会话的派生结果、会话是时间轴对象,都不挂)
-- 两类彻底分开:系统标记走代码固定词表、用户只读;用户标签自由输入、可增删改
-- 系统标记成对(名 = 值),用户标签只有名
-- 检索只做单一标记筛选
-- 标记对用户全部可见;用户标签可改名、可删除,不做「废弃」状态
--
-- 标记不是状态:会话状态、报告可否修订、导图是否待更新这类流程判断留在各自主体上。
CREATE TABLE markers
(
id INT AUTO_INCREMENT COMMENT 'id无业务含义'
PRIMARY KEY,
object_type VARCHAR(20) NOT NULL COMMENT '标记对象类型:FRAGMENT=知识碎片 / TASK=学习任务',
object_num VARCHAR(255) NOT NULL COMMENT '对象标识:碎片 id 或 任务编号',
kind VARCHAR(20) NOT NULL COMMENT '标记种类:SYSTEM=系统标记(用户只读)/ USER=用户标签',
marker_name VARCHAR(100) NOT NULL COMMENT '标记名:系统标记来自固定词表;用户标签自由输入',
marker_value VARCHAR(255) NULL COMMENT '标记值:系统标记成对使用(如 来源=学习引导);用户标签留空',
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 '逻辑删除符',
-- 同一对象上「同类 + 同名 + 同值」只保留一条(重复打标是幂等的)。
-- 值参与唯一键,因为系统标记是「名 = 值」成对表达的。
UNIQUE KEY uk_markers_object_marker (created_by, object_type, object_num, kind, marker_name, marker_value),
-- 按标记找对象(点标签即筛选)
KEY idx_markers_lookup (created_by, marker_name, object_type, object_num),
-- 列出某对象的全部标记
KEY idx_markers_object (created_by, object_type, object_num)
)
COMMENT '统一标记:附加在对象上的轻量元信息(来源、标签),不参与聚合口径与流程判断';
@@ -0,0 +1,264 @@
package com.guo.learningprogresstracker.service.impl;
import cn.dev33.satoken.stp.StpUtil;
import com.guo.learningprogresstracker.dto.MarkerUsage;
import com.guo.learningprogresstracker.entity.MarkerEntity;
import com.guo.learningprogresstracker.entity.StudyReportFragmentsEntity;
import com.guo.learningprogresstracker.entity.StudySessionsEntity;
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.StudyReportFragmentsMapper;
import com.guo.learningprogresstracker.mapper.StudySessionsMapper;
import com.guo.learningprogresstracker.mapper.TasksMapper;
import com.guo.learningprogresstracker.service.MarkerService;
import com.guo.learningprogresstracker.utils.GenerateNumTool;
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.List;
import java.util.Map;
import java.util.concurrent.atomic.AtomicInteger;
import static org.junit.jupiter.api.Assertions.*;
/**
* 统一标记的落库集成测试(标记-01)。
*/
@SpringBootTest
class MarkerServiceIntegrationTest {
private static final String USER = "标记集成测试用户";
private static final AtomicInteger SEQ = new AtomicInteger();
@Autowired
private MarkerService markerService;
@Autowired
private StudyReportFragmentsMapper fragmentsMapper;
@Autowired
private StudySessionsMapper studySessionsMapper;
@Autowired
private TasksMapper tasksMapper;
@BeforeEach
void setUp() {
StpUtil.login(USER, "test_device");
}
private StudyReportFragmentsEntity saveFragment(String ownerTaskNum) {
StudySessionsEntity session = new StudySessionsEntity();
session.setSessionNum(GenerateNumTool.generateNum("SESSIONMK"));
session.setTaskNum(ownerTaskNum);
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(ownerTaskNum);
fragment.setContent("标记测试碎片");
fragmentsMapper.insert(fragment);
return fragment;
}
private String saveTask() {
String taskNum = "TASKMK-IT-" + System.nanoTime() + "-" + SEQ.incrementAndGet();
TaskEntity task = new TaskEntity();
task.setTaskNum(taskNum);
task.setTaskName("标记测试任务");
tasksMapper.insert(task);
return taskNum;
}
@Test
void userTag_isIdempotentAndListedOnObject() throws Exception {
String taskNum = saveTask();
StudyReportFragmentsEntity fragment = saveFragment(taskNum);
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(fragment.getId()), "英语");
// 重复打同一标签应幂等
markerService.addUserTag(MarkerObjectTypeEnum.FRAGMENT, String.valueOf(fragment.getId()), " 英语 ");
List<MarkerEntity> 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<MarkerEntity> 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<MarkerEntity> 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<String> 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<String, List<MarkerEntity>> 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<MarkerUsage> 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(),
"对象删除后其标记不应再出现在列表里");
}
}