feat(通知): task_failed 带 ref_json 定位锚点,明细可点直达任务详情

用户原话「都没体现哪个任务id/店铺/用户,咋排查」:通知表只有 title/content,
失败任务又按「用户×模块×自然日」聚合成一条,明细被 5 个 taskNo 预览 + 512 字截断吃掉。

- V162 给 biz_user_notification 加 ref_json(TEXT,可重跑迁移,存量不回填)
- 扫描器把桶内每个失败任务写成锚点(taskId/taskNo/moduleType/reason/updatedAt/
  deviceId),上限 20 条;品牌任务无 task_no 用 #<id> 兜底,保证至少一条可定位
- 详情接口回传 refs;同键刷新时锚点变化也更新,且不重新点亮已读
- 后台铃铛「展开明细」渲染成可点行,跳任务中心 ?taskNo= 自动开详情抽屉
- 新增判据 taskFailedAdminNotificationCarriesUidAndTaskNoAnchor:管理端正文必须含
  uid、每个桶的 ref_json 至少一条非空 taskNo
This commit is contained in:
2026-10-22 10:28:12 +08:00
parent 78be0f02e2
commit d268ecdf6b
15 changed files with 361 additions and 36 deletions
@@ -23,6 +23,8 @@ public class UserNotificationEntity {
private String severity;
private String title;
private String content;
/** 结构化定位锚点 JSON(V162);null=该通知没有可点对象(存量行、服务级告警)。 */
private String refJson;
private String dedupeKey;
private LocalDateTime readAt;
private LocalDateTime createdAt;
@@ -3,6 +3,7 @@ package com.nanri.aiimage.modules.notification.model.vo;
import lombok.Data;
import java.time.LocalDateTime;
import java.util.List;
/** 单条通知(桌面端与后台共用结构)。 */
@Data
@@ -19,6 +20,8 @@ public class NotificationItemVo {
private String severity;
private String title;
private String content;
/** 可点击的定位锚点(task_failed=桶内失败任务);null/空=该条没有可点对象。 */
private List<NotificationRefVo> refs;
/** 是否已读(前端展示用,等价于 readAt 非空) */
private Boolean read;
private LocalDateTime readAt;
@@ -0,0 +1,29 @@
package com.nanri.aiimage.modules.notification.model.vo;
import lombok.Data;
/**
* 通知的结构化定位锚点(ref_json 里的一项)。
*
* <p>当前只有 task_failed 使用:桶内每个失败任务一项。它是「点一下能跳到任务详情」
* 的唯一依据,正文里的自然语言只负责让人看懂,不承担定位职责。
*
* <p>字段全部按 JSON 原样回给前端;不认识的字段由反序列化层忽略——后续加锚点类型时
* 不至于让老 jar 读不出来。
*/
@Data
public class NotificationRefVo {
/** 失败任务主键(biz_file_task.id / brand_crawl_tasks.id)。 */
private Long taskId;
/** 任务号(品牌任务无 task_no 列,用 #&lt;id&gt; 兜底),任务详情接口按它查。 */
private String taskNo;
/** 模块类型原码(DELETE_BRAND / PRICE_TRACK / BRAND …)。 */
private String moduleType;
/** 该任务的失败原因(已压缩空白,最长 120 字)。 */
private String reason;
/** 任务进入失败终态的时间(yyyy-MM-dd HH:mm:ss)。 */
private String updatedAt;
/** 执行任务的客户端设备 id(历史任务为空)。 */
private String deviceId;
}
@@ -57,6 +57,15 @@ public class NotificationDispatchService {
*/
public int pushToAdmins(AdminAudience audience, String scene, String level, String title, String content,
String dedupeKeyBase, Long subjectUserId) {
return pushToAdmins(audience, scene, level, title, content, dedupeKeyBase, subjectUserId, null);
}
/**
* 同 {@link #pushToAdmins(AdminAudience, String, String, String, String, String, Long)},
* 额外带一份结构化定位锚点(任务失败桶的明细),供后台「展开明细」渲染成可点行。
*/
public int pushToAdmins(AdminAudience audience, String scene, String level, String title, String content,
String dedupeKeyBase, Long subjectUserId, String refJson) {
int pushed = 0;
int filtered = 0;
for (AdminUserEntity admin : audience.admins()) {
@@ -66,7 +75,7 @@ public class NotificationDispatchService {
}
String key = dedupeKeyBase + ":" + admin.getId();
if (notificationService.pushOrRefresh(admin.getId(), NotificationService.AUDIENCE_ADMIN,
scene, level, title, content, key, subjectUserId)) {
scene, level, title, content, key, subjectUserId, refJson)) {
pushed++;
}
}
@@ -1,5 +1,6 @@
package com.nanri.aiimage.modules.notification.service;
import cn.hutool.json.JSONUtil;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.nanri.aiimage.config.HttpClientPool;
import com.nanri.aiimage.config.NotificationProperties;
@@ -51,8 +52,11 @@ public class NotificationScanScheduler {
private static final String BRAND_MODULE_TYPE = "BRAND";
private static final int MAX_TASK_NO_PREVIEW = 5;
/** 锚点条数上限:正文只放 5 个任务号,结构化锚点要能覆盖同桶多数失败,但不能让积压把行撑爆。 */
private static final int MAX_TASK_REF = 20;
private static final int REASON_MAX_LENGTH = 120;
private static final int PROBE_READ_TIMEOUT_MILLIS = 8_000;
private static final DateTimeFormatter REF_TIME_FORMAT = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
/**
* 18960 的探针路径。根路径没有路由,恒 404 ⇒ 这一格只能读成「未验证」,
@@ -117,7 +121,8 @@ public class NotificationScanScheduler {
List<FailedTask> failed = new ArrayList<>();
List<FileTaskEntity> fileTasks = fileTaskMapper.selectList(new LambdaQueryWrapper<FileTaskEntity>()
.select(FileTaskEntity::getId, FileTaskEntity::getTaskNo, FileTaskEntity::getModuleType,
FileTaskEntity::getUserId, FileTaskEntity::getErrorMessage, FileTaskEntity::getUpdatedAt)
FileTaskEntity::getUserId, FileTaskEntity::getErrorMessage, FileTaskEntity::getUpdatedAt,
FileTaskEntity::getDeviceId)
.eq(FileTaskEntity::getStatus, STATUS_FAILED)
.gt(FileTaskEntity::getUpdatedAt, cutoff)
.orderByDesc(FileTaskEntity::getId)
@@ -127,7 +132,8 @@ public class NotificationScanScheduler {
continue;
}
failed.add(new FailedTask(task.getId(), displayTaskNo(task.getTaskNo(), task.getId()),
task.getModuleType(), task.getUserId(), task.getErrorMessage(), task.getUpdatedAt()));
task.getModuleType(), task.getUserId(), task.getErrorMessage(), task.getUpdatedAt(),
task.getDeviceId()));
}
List<BrandCrawlTaskEntity> brandTasks = brandCrawlTaskMapper.selectList(new LambdaQueryWrapper<BrandCrawlTaskEntity>()
.select(BrandCrawlTaskEntity::getId, BrandCrawlTaskEntity::getUserId,
@@ -141,7 +147,7 @@ public class NotificationScanScheduler {
continue;
}
failed.add(new FailedTask(task.getId(), "#" + task.getId(),
BRAND_MODULE_TYPE, task.getUserId(), task.getErrorMessage(), task.getUpdatedAt()));
BRAND_MODULE_TYPE, task.getUserId(), task.getErrorMessage(), task.getUpdatedAt(), null));
}
if (failed.isEmpty()) {
log.info("[notification-scan] 近 {} 分钟无失败任务", properties.getTaskFailedWindowMinutes());
@@ -170,9 +176,10 @@ public class NotificationScanScheduler {
+ (preview.isEmpty() ? "" : "(" + preview + ")")
+ (reason.isEmpty() ? "" : ";最近失败原因:" + reason)
+ ",详情请查看对应工具页的「历史任务」。";
String refJson = refJsonOf(tasks);
if (notificationService.pushOrRefresh(key.userId(), NotificationService.AUDIENCE_USER,
NotificationService.SCENE_TASK_FAILED, NotificationService.LEVEL_WARNING,
label + "任务失败", userContent, dedupeKeyOf(key))) {
label + "任务失败", userContent, dedupeKeyOf(key), null, refJson)) {
userPushed++;
}
@@ -185,7 +192,7 @@ public class NotificationScanScheduler {
NotificationService.SCENE_TASK_FAILED, NotificationService.LEVEL_WARNING,
"用户任务失败:" + username, adminContent,
"task_failed_admin:" + key.userId() + ":" + key.moduleType() + ":" + key.day(),
key.userId());
key.userId(), refJson);
}
log.info("[notification-scan] 任务失败扫描完成 窗口={}分钟 失败任务={} 聚合桶={} 用户通知={} 管理员通知={}",
properties.getTaskFailedWindowMinutes(), failed.size(), buckets.size(), userPushed, adminPushed);
@@ -390,14 +397,45 @@ public class NotificationScanScheduler {
private String latestReason(List<FailedTask> tasks) {
for (FailedTask task : tasks) {
if (task.errorMessage() != null && !task.errorMessage().isBlank()) {
String reason = task.errorMessage().trim().replaceAll("\\s+", " ");
return reason.length() <= REASON_MAX_LENGTH ? reason : reason.substring(0, REASON_MAX_LENGTH) + "…";
String reason = shortReason(task.errorMessage());
if (reason != null) {
return reason;
}
}
return "";
}
/**
* 桶内失败任务的结构化锚点(ref_json):每个任务一项,最多 {@link #MAX_TASK_REF} 条。
* 正文里的 taskNo 预览只有 5 个且会被 512 字截断,锚点是「点一下到任务详情」的唯一依据,
* 所以 taskNo 必须非空——fileTask 由 displayTaskNo 兜底,品牌任务用 #&lt;id&gt;。
*/
String refJsonOf(List<FailedTask> tasks) {
List<Map<String, Object>> refs = new ArrayList<>(Math.min(tasks.size(), MAX_TASK_REF));
for (FailedTask task : tasks) {
if (refs.size() >= MAX_TASK_REF) {
break;
}
Map<String, Object> ref = new LinkedHashMap<>();
ref.put("taskId", task.id());
ref.put("taskNo", task.taskNo());
ref.put("moduleType", task.moduleType());
ref.put("reason", shortReason(task.errorMessage()));
ref.put("updatedAt", task.updatedAt() == null ? null : task.updatedAt().format(REF_TIME_FORMAT));
ref.put("deviceId", task.deviceId());
refs.add(ref);
}
return JSONUtil.toJsonStr(refs);
}
private String shortReason(String raw) {
if (raw == null || raw.isBlank()) {
return null;
}
String reason = raw.trim().replaceAll("\\s+", " ");
return reason.length() <= REASON_MAX_LENGTH ? reason : reason.substring(0, REASON_MAX_LENGTH) + "…";
}
private String displayTaskNo(String taskNo, Long id) {
return taskNo == null || taskNo.isBlank() ? "#" + id : taskNo;
}
@@ -446,7 +484,7 @@ public class NotificationScanScheduler {
/** 统一视图的失败任务(两类表归一);updatedAt 即失败终态时间,决定落入哪一天的桶。 */
record FailedTask(Long id, String taskNo, String moduleType, Long userId, String errorMessage,
LocalDateTime updatedAt) {
LocalDateTime updatedAt, String deviceId) {
}
/** 探测三态:ALIVE=业务可用;UNVERIFIED=服务回了话但证不了业务可用;DOWN=故障。 */
@@ -1,5 +1,6 @@
package com.nanri.aiimage.modules.notification.service;
import cn.hutool.json.JSONUtil;
import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper;
@@ -10,6 +11,7 @@ import com.nanri.aiimage.modules.notification.model.vo.NotificationGroupPageVo;
import com.nanri.aiimage.modules.notification.model.vo.NotificationGroupVo;
import com.nanri.aiimage.modules.notification.model.vo.NotificationItemVo;
import com.nanri.aiimage.modules.notification.model.vo.NotificationPageVo;
import com.nanri.aiimage.modules.notification.model.vo.NotificationRefVo;
import com.nanri.aiimage.modules.notification.model.vo.NotificationSummaryVo;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
@@ -86,6 +88,8 @@ public class NotificationService {
private static final int TITLE_MAX_LENGTH = 128;
private static final int CONTENT_MAX_LENGTH = 512;
private static final int DEDUPE_KEY_MAX_LENGTH = 160;
/** ref_json 的安全上限:TEXT 能装 64KB,但一条通知的锚点超过这个量级说明聚合失控,整条丢弃。 */
private static final int REF_JSON_MAX_LENGTH = 4000;
/** 严重度排序表达式:与 {@link #severityRank} 同一口径,数据库侧分页必须同序。 */
private static final String SEVERITY_ORDER_SQL =
@@ -111,6 +115,18 @@ public class NotificationService {
*/
public boolean push(Long userId, String audience, String scene, String level,
String title, String content, String dedupeKey, Long subjectUserId) {
return push(userId, audience, scene, level, title, content, dedupeKey, subjectUserId, null);
}
/**
* 推送一条通知(带结构化定位锚点)。
*
* @param refJson 可点的定位对象(JSON 数组字符串,见 {@link NotificationRefVo});null=没有。
* 超长时整条丢弃而不是截断:截断后的 JSON 前端解析不出来,比没有更糟。
*/
public boolean push(Long userId, String audience, String scene, String level,
String title, String content, String dedupeKey, Long subjectUserId,
String refJson) {
if (userId == null || userId <= 0) {
log.warn("[notification] 推送被跳过:接收者无效 userId={} scene={}", userId, scene);
return false;
@@ -133,6 +149,7 @@ public class NotificationService {
row.setSeverity(severityOf(normalizedScene, normalizedLevel));
row.setTitle(truncate(title, TITLE_MAX_LENGTH));
row.setContent(truncate(content == null ? "" : content, CONTENT_MAX_LENGTH));
row.setRefJson(normalizeRefJson(refJson));
row.setDedupeKey(truncate(key, DEDUPE_KEY_MAX_LENGTH));
row.setCreatedAt(LocalDateTime.now());
try {
@@ -162,17 +179,25 @@ public class NotificationService {
public boolean pushOrRefresh(Long userId, String audience, String scene, String level,
String title, String content, String dedupeKey, Long subjectUserId) {
return pushOrRefresh(userId, audience, scene, level, title, content, dedupeKey, subjectUserId, null);
}
public boolean pushOrRefresh(Long userId, String audience, String scene, String level,
String title, String content, String dedupeKey, Long subjectUserId,
String refJson) {
String key = normalize(dedupeKey);
if (key.isEmpty()) {
return push(userId, audience, scene, level, title, content, key, subjectUserId);
return push(userId, audience, scene, level, title, content, key, subjectUserId, refJson);
}
UserNotificationEntity existing = selectByDedupeKey(key);
if (existing == null) {
return push(userId, audience, scene, level, title, content, key, subjectUserId);
return push(userId, audience, scene, level, title, content, key, subjectUserId, refJson);
}
String nextTitle = truncate(title, TITLE_MAX_LENGTH);
String nextContent = truncate(content == null ? "" : content, CONTENT_MAX_LENGTH);
if (nextContent.equals(existing.getContent()) && nextTitle.equals(existing.getTitle())) {
String nextRefJson = normalizeRefJson(refJson);
if (nextContent.equals(existing.getContent()) && nextTitle.equals(existing.getTitle())
&& java.util.Objects.equals(nextRefJson, existing.getRefJson())) {
return false;
}
String normalizedScene = normalize(scene).isEmpty() ? SCENE_SYSTEM : normalize(scene);
@@ -181,6 +206,7 @@ public class NotificationService {
.eq(UserNotificationEntity::getId, existing.getId())
.set(UserNotificationEntity::getTitle, nextTitle)
.set(UserNotificationEntity::getContent, nextContent)
.set(UserNotificationEntity::getRefJson, nextRefJson)
.set(UserNotificationEntity::getLevel, normalizedLevel)
.set(UserNotificationEntity::getSeverity, severityOf(normalizedScene, normalizedLevel)));
log.info("[notification] 同键通知已刷新 id={} userId={} scene={} dedupeKey={}",
@@ -623,6 +649,7 @@ public class NotificationService {
vo.setSeverity(normalizeSeverity(row.getSeverity(), row.getScene(), row.getLevel()));
vo.setTitle(row.getTitle());
vo.setContent(row.getContent());
vo.setRefs(parseRefs(row.getRefJson()));
vo.setRead(row.getReadAt() != null);
vo.setReadAt(row.getReadAt());
vo.setCreatedAt(row.getCreatedAt());
@@ -637,4 +664,26 @@ public class NotificationService {
String normalized = value == null ? "" : value.trim();
return normalized.length() <= maxLength ? normalized : normalized.substring(0, maxLength);
}
/** 锚点落库前的唯一口径:空串归一成 NULL,超长整条丢弃(截断会产出不可解析的 JSON)。 */
private static String normalizeRefJson(String refJson) {
String value = normalize(refJson);
if (value.isEmpty()) {
return null;
}
if (value.length() > REF_JSON_MAX_LENGTH) {
log.warn("[notification] 定位锚点超长已丢弃 长度={} 上限={}", value.length(), REF_JSON_MAX_LENGTH);
return null;
}
return value;
}
/** 读取时解析锚点:ref_json 只由本服务写入(且超长整条丢弃),不存在解析失败的分支。 */
private List<NotificationRefVo> parseRefs(String refJson) {
String value = normalize(refJson);
if (value.isEmpty()) {
return null;
}
return JSONUtil.toList(value, NotificationRefVo.class);
}
}
@@ -0,0 +1,51 @@
-- =============================================================
-- 迁移 V162__notification_ref_json
--
-- 1. 变更目的:给站内通知补「结构化定位锚点」列(2026-10-21 需求)。
-- 用户原话:「都没体现 哪个任务id 或者 店铺 或用户啥的关键信息 咋排查」。
-- 现状:biz_user_notification 只有 title(128)/content(512),task_failed 又按
-- 「用户 × 模块 × 自然日」聚合成一条,明细被 taskNoPreview(最多 5 个) + 最近
-- 一条原因(截 120) 压缩,且 content 再截 512 ⇒ 同桶其余任务连任务号都看不到。
-- 加这一列后,扫描器把桶内每个失败任务写成 JSON(taskId/taskNo/moduleType/
-- reason/updatedAt/deviceId),后台「展开明细」渲染成可点行、直达任务详情。
--
-- 2. 为什么不是把正文放宽:content 是给桌面用户看的自然语言,长度由 UI 决定;
-- 结构化定位信息要能被程序消费(跳转、对齐),混在一段文本里只能靠正则捞。
--
-- 3. 为什么用 TEXT 不用 JSON 类型:MySQL JSON 列在 JDBC 侧同样回字符串,
-- 但会给「老的 jar 不认识这一列」的回滚场景多绑一个数据库版本前提;
-- TEXT 与 V116 既有风格一致,可重跑、可直接 SHOW。
--
-- 4. 存量行:ref_json 保持 NULL(不回填)。历史 task_failed 通知的明细在聚合时
-- 就已丢弃,回填只能靠正则解析文案,正是本项目一直拒绝的做法。
--
-- 5. 锁表风险:低。TEXT NULL ADD COLUMN 在 MySQL 8 走 INSTANT(不重建表)。
-- 刻意不加索引:这一列只随明细行整体读出,从不做条件筛选。
--
-- 6. 验证 SQL(迁移后跑):
-- SHOW COLUMNS FROM `biz_user_notification` LIKE 'ref_json';
-- -> 期望 1 行:Type=text,Null=YES
-- SELECT id, scene, LEFT(ref_json, 120) FROM biz_user_notification
-- WHERE scene='task_failed' ORDER BY id DESC LIMIT 3;
-- -> 新产生的行应能看到 [{"taskId":...,"taskNo":"...
--
-- 7. 可重跑性:照 V146/V155/V157/V158/V161 惯例,加列前先查 information_schema;
-- 迁移中途失败时 flyway repair + 重启会从第一条语句重跑,裸 ADD COLUMN 会撞 1060。
--
-- 8. 回滚(人工补丁,写成注释以免被 Flyway 当迁移执行):
-- ALTER TABLE `biz_user_notification` DROP COLUMN `ref_json`;
-- 仅回滚 jar 不需要 DROP:旧 jar 的实体没有这一列,INSERT 不会写它。
-- =============================================================
SET @has_col := (
SELECT COUNT(*) FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA = DATABASE()
AND TABLE_NAME = 'biz_user_notification'
AND COLUMN_NAME = 'ref_json'
);
SET @ddl := IF(@has_col = 0,
'ALTER TABLE `biz_user_notification` ADD COLUMN `ref_json` TEXT NULL COMMENT ''结构化定位锚点 JSON(task_failed=桶内失败任务清单)'' AFTER `content`',
'SELECT ''biz_user_notification.ref_json already exists, skipped'' AS note');
PREPARE stmt FROM @ddl;
EXECUTE stmt;
DEALLOCATE PREPARE stmt;