feat(notification): 添加自定义系统通知内容列支持

csfwff · csfwff · commit b32405eb6bc5 · 2026-03-12T14:54:09.000+08:00
- 在 Notification 模型中新增 content 字段和最大长度常量
- 更新 UserProcessor 中的通知长度校验逻辑
- 在 NotificationMgmtService 中实现内容列可用性检测机制
- 添加 NotificationContents 工具类处理通知内容标准化和清理
- 支持 Markdown 链接解析和 HTML 内容安全过滤
- 更新数据库 schema 添加 content 列定义
- 修改通知查询服务支持从新字段读取内容
- 更新文档说明新的通知发送机制
diff --git a/AGENTS.md b/AGENTS.md
@@ -58,8 +58,8 @@
 - 积分变更统一走 `PointtransferMgmtService`：独立流程用 `transfer(...)`（方法内自带事务）；若外层已有事务，必须用 `transferInCurrentTransaction(...)` 避免事务冲突。
 - 发积分/扣积分约定：发积分用 `fromId=Pointtransfer.ID_C_SYS`、`toId=userId`；扣积分用 `fromId=userId`、`toId=Pointtransfer.ID_C_SYS`（常用类型 `Pointtransfer.TRANSFER_TYPE_C_ABUSE_DEDUCT`）。
 - 需要给用户发“系统转账通知”时：在转账成功拿到 `transferId` 后，调用 `NotificationMgmtService#addPointTransferNotification`，并设置 `Notification.NOTIFICATION_USER_ID` 与 `Notification.NOTIFICATION_DATA_ID=transferId`。
-- 通知金手指：`POST /user/edit/notification`（`UserProcessor#sendSystemNotification`），使用 `gold.finger.notification` 校验；请求体使用 `userName` + `notification` + `goldFingerKey`，其中 `notification` 最大 64 字符（对应 `notification.dataId` 字段长度）。
-- 定制系统通知渲染：`Notification.DATA_TYPE_C_CUSTOM_SYS` 在 `NotificationQueryService#getSysAnnounceNotifications` 处理；`dataId=1` 为固定“水贴提醒”模板，其他 `dataId` 走 HTML 转义并将换行转为 `<br>`。
+- 通知金手指：`POST /user/edit/notification`（`UserProcessor#sendSystemNotification`），使用 `gold.finger.notification` 校验；请求体使用 `userName` + `notification` + `goldFingerKey`，新正文优先写 `notification.content`（最大 4096），老库未补 `content` 列时仅兼容旧 64 字纯文本 `dataId` 链路。
+- 定制系统通知渲染：`Notification.DATA_TYPE_C_CUSTOM_SYS` 在 `NotificationQueryService#getSysAnnounceNotifications` 处理；`dataId=1` 为固定“水贴提醒”模板，`content` 支持 Markdown 链接 `[文本](http/https://...)` 与换行，原始 HTML 会被转义后再清洗。
 - VIP 管理页配置项不再手填 JSON：前端依据等级 `benefits` 模板自动生成可视化表单，再序列化为 `configJson` 提交。
 - VIP 管理页样式需注意 `home.css` 的 `.form--admin label { flex: 1; }` 会影响布局；配置项行在 `vip-admin.scss` 中需显式改为整行（label/builder 100%）并对 checkbox 使用类型选择器，避免控件被放大。
 - 有效期字段：勋章 `expireTime`（毫秒，`0`=永久）；会员 `expiresAt`（可回填勋章到期）。
diff --git a/src/main/java/org/b3log/symphony/model/Notification.java b/src/main/java/org/b3log/symphony/model/Notification.java
@@ -52,11 +52,21 @@ public final class Notification {
      */
     public static final String NOTIFICATION_DATA_TYPE = "dataType";
 
+    /**
+     * Key of content.
+     */
+    public static final String NOTIFICATION_CONTENT = "content";
+
     /**
      * Key of has read.
      */
     public static final String NOTIFICATION_HAS_READ = "hasRead";
 
+    /**
+     * Max length of custom system notification content.
+     */
+    public static final int MAX_LENGTH_C_CUSTOM_SYS_CONTENT = 4096;
+
     // Data type constants
     /**
      * Data type - article.
diff --git a/src/main/java/org/b3log/symphony/processor/UserProcessor.java b/src/main/java/org/b3log/symphony/processor/UserProcessor.java
@@ -570,9 +570,9 @@ public void sendSystemNotification(final RequestContext context) {
             context.renderMsg("发送失败：notification 不能为空。");
             return;
         }
-        if (notification.length() > 64) {
+        if (notification.length() > Notification.MAX_LENGTH_C_CUSTOM_SYS_CONTENT) {
             context.renderJSON(StatusCodes.ERR);
-            context.renderMsg("发送失败：notification 长度不能超过 64 个字符。");
+            context.renderMsg("发送失败：notification 长度不能超过 " + Notification.MAX_LENGTH_C_CUSTOM_SYS_CONTENT + " 个字符。");
             return;
         }
 
diff --git a/src/main/java/org/b3log/symphony/service/NotificationMgmtService.java b/src/main/java/org/b3log/symphony/service/NotificationMgmtService.java
@@ -18,13 +18,16 @@
  */
 package org.b3log.symphony.service;
 
+import org.apache.commons.lang.StringUtils;
 import org.apache.logging.log4j.Level;
 import org.apache.logging.log4j.LogManager;
 import org.apache.logging.log4j.Logger;
 import org.b3log.latke.Keys;
+import org.b3log.latke.Latkes;
 import org.b3log.latke.ioc.BeanManager;
 import org.b3log.latke.ioc.Inject;
 import org.b3log.latke.repository.*;
+import org.b3log.latke.repository.jdbc.util.Connections;
 import org.b3log.latke.repository.annotation.Transactional;
 import org.b3log.latke.service.ServiceException;
 import org.b3log.latke.service.annotation.Service;
@@ -34,9 +37,13 @@
 import org.b3log.symphony.processor.NotificationProcessor;
 import org.b3log.symphony.processor.channel.UserChannel;
 import org.b3log.symphony.repository.NotificationRepository;
+import org.b3log.symphony.util.NotificationContents;
 import org.b3log.symphony.util.Symphonys;
 import org.json.JSONObject;
 
+import java.sql.Connection;
+import java.sql.ResultSet;
+import java.sql.SQLException;
 import java.util.*;
 
 /**
@@ -54,6 +61,11 @@ public class NotificationMgmtService {
      */
     private static final Logger LOGGER = LogManager.getLogger(NotificationMgmtService.class);
 
+    /**
+     * Whether the custom notification content column is available.
+     */
+    private volatile Boolean customSysContentColumnReady;
+
     /**
      * Notification repository.
      */
@@ -432,12 +444,29 @@ public void addSysAnnounceArticleNotification(final JSONObject requestJSONObject
     @Transactional
     public void addSysAnnounceCustomNotification(String notification, String uid) throws ServiceException {
         try {
-            JSONObject requestJSONObject = new JSONObject();
+            final JSONObject requestJSONObject = new JSONObject();
             requestJSONObject.put(Notification.NOTIFICATION_USER_ID, uid);
-            requestJSONObject.put(Notification.NOTIFICATION_DATA_ID, notification);
+            if (isCustomSysContentColumnReady()) {
+                final String rawContent = NotificationContents.normalizeCustomSysContent(notification);
+                final String safeContent = NotificationContents.sanitizeCustomSysContent(rawContent);
+                if (StringUtils.isBlank(safeContent)) {
+                    throw new ServiceException("发送失败：notification 清洗后为空，请至少保留文本或 http/https 链接。");
+                }
+                requestJSONObject.put(Notification.NOTIFICATION_DATA_ID, StringUtils.EMPTY);
+                requestJSONObject.put(Notification.NOTIFICATION_CONTENT, rawContent);
+            } else {
+                if (NotificationContents.requiresDedicatedContentColumn(notification)) {
+                    throw new ServiceException("当前数据库缺少 notification.content 列，请先执行 SQL：ALTER TABLE `"
+                            + Latkes.getLocalProperty("jdbc.tablePrefix") + "_notification` ADD COLUMN `content` TEXT;");
+                }
+                requestJSONObject.put(Notification.NOTIFICATION_DATA_ID,
+                        NotificationContents.normalizeCustomSysContent(notification));
+            }
             requestJSONObject.put(Notification.NOTIFICATION_DATA_TYPE, Notification.DATA_TYPE_C_CUSTOM_SYS);
 
             addNotification(requestJSONObject);
+        } catch (final ServiceException e) {
+            throw e;
         } catch (final RepositoryException e) {
             final String msg = "Adds a notification [type=sys_announce_custom] failed";
             LOGGER.log(Level.ERROR, msg, e);
@@ -446,6 +475,27 @@ public void addSysAnnounceCustomNotification(String notification, String uid) th
         }
     }
 
+    /**
+     * Returns whether the custom system notification content column is ready.
+     *
+     * @return {@code true} if ready
+     * @throws ServiceException service exception
+     */
+    public boolean isCustomSysContentColumnReady() throws ServiceException {
+        if (null != customSysContentColumnReady) {
+            return customSysContentColumnReady;
+        }
+
+        synchronized (this) {
+            if (null != customSysContentColumnReady) {
+                return customSysContentColumnReady;
+            }
+
+            customSysContentColumnReady = detectCustomSysContentColumn();
+            return customSysContentColumnReady;
+        }
+    }
+
     /**
      * Adds a 'sys announce - new user' type notification with the specified request json object.
      *
@@ -988,6 +1038,9 @@ private void addNotification(final JSONObject requestJSONObject) throws Reposito
         notification.put(Notification.NOTIFICATION_USER_ID, requestJSONObject.optString(Notification.NOTIFICATION_USER_ID));
         notification.put(Notification.NOTIFICATION_DATA_ID, requestJSONObject.optString(Notification.NOTIFICATION_DATA_ID));
         notification.put(Notification.NOTIFICATION_DATA_TYPE, requestJSONObject.optInt(Notification.NOTIFICATION_DATA_TYPE));
+        if (requestJSONObject.has(Notification.NOTIFICATION_CONTENT)) {
+            notification.put(Notification.NOTIFICATION_CONTENT, requestJSONObject.optString(Notification.NOTIFICATION_CONTENT));
+        }
 
         notificationRepository.add(notification);
 
@@ -999,4 +1052,22 @@ private void addNotification(final JSONObject requestJSONObject) throws Reposito
             UserChannel.sendCmd(cmd);
         });
     }
+
+    /**
+     * Detects whether the custom content column exists on the notification table.
+     *
+     * @return {@code true} if the column exists
+     * @throws ServiceException service exception
+     */
+    private boolean detectCustomSysContentColumn() throws ServiceException {
+        final String tableName = Latkes.getLocalProperty("jdbc.tablePrefix") + "_" + Notification.NOTIFICATION;
+        try (Connection connection = Connections.getConnection();
+             ResultSet resultSet = connection.getMetaData()
+                     .getColumns(connection.getCatalog(), null, tableName, Notification.NOTIFICATION_CONTENT)) {
+            return resultSet.next();
+        } catch (final SQLException e) {
+            LOGGER.log(Level.ERROR, "Detects notification.content column failed", e);
+            throw new ServiceException("检测 notification.content 列失败，请检查数据库连接。");
+        }
+    }
 }
diff --git a/src/main/java/org/b3log/symphony/service/NotificationQueryService.java b/src/main/java/org/b3log/symphony/service/NotificationQueryService.java
@@ -36,6 +36,7 @@
 import org.b3log.symphony.repository.*;
 import org.b3log.symphony.util.Escapes;
 import org.b3log.symphony.util.Emotions;
+import org.b3log.symphony.util.NotificationContents;
 import org.b3log.symphony.util.Symphonys;
 import org.json.JSONObject;
 
@@ -278,7 +279,12 @@ public JSONObject getSysAnnounceNotifications(final String userId, final int cur
                         desTemplate = desTemplate.replace("{oldRole}", oldRole.optString(Role.ROLE_NAME));
                         desTemplate = desTemplate.replace("{newRole}", newRole.optString(Role.ROLE_NAME));
                         break;
-                    case Notification.DATA_TYPE_C_CUSTOM_SYS:
+                    case Notification.DATA_TYPE_C_CUSTOM_SYS: {
+                        final String customContent = notification.optString(Notification.NOTIFICATION_CONTENT);
+                        if (StringUtils.isNotBlank(customContent)) {
+                            desTemplate = NotificationContents.sanitizeCustomSysContent(customContent);
+                            break;
+                        }
                         switch (dataId) {
                             case "1":
                                 desTemplate = "亲爱的用户，您好！<br> 我们检测到您刚刚发布的内容可能属于“水贴”或无意义发言。虽然本次发帖不会被拦截，但频繁发布此类内容会破坏社区的交流氛围，影响其他用户的体验。请您尽量发表有价值、有内容的观点或讨论，让我们的社区更加温暖和有趣。<br>需要特别提醒的是，无论是否通过特殊方式绕过系统检测，所有水贴内容都会被系统或人工审核查处，账号也可能因此受到相应处理。同时，本次发帖不会计入您的活跃度统计。感谢您的理解与配合，让我们一起维护良好的社区环境！";
@@ -291,6 +297,7 @@ public JSONObject getSysAnnounceNotifications(final String userId, final int cur
                                 desTemplate = Escapes.escapeHTML(dataId).replace("\r\n", "<br>").replace("\n", "<br>").replace("\r", "<br>");
                         }
                         break;
+                    }
                     default:
                         throw new AssertionError();
                 }
diff --git a/src/main/java/org/b3log/symphony/util/NotificationContents.java b/src/main/java/org/b3log/symphony/util/NotificationContents.java
@@ -0,0 +1,167 @@
+/*
+ * Rhythm - A modern community (forum/BBS/SNS/blog) platform written in Java.
+ * Modified version from Symphony, Thanks Symphony :)
+ * Copyright (C) 2012-present, b3log.org
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+package org.b3log.symphony.util;
+
+import org.apache.commons.lang.StringUtils;
+import org.jsoup.Jsoup;
+import org.jsoup.nodes.Document;
+import org.jsoup.safety.Whitelist;
+
+import java.net.MalformedURLException;
+import java.net.URL;
+import java.util.regex.Pattern;
+
+/**
+ * Notification content utilities.
+ *
+ * @author <a href="https://fishpi.cn/member/admin">admin</a>
+ * @version 1.0.0.0, Mar 12, 2026
+ * @since 1.0.0
+ */
+public final class NotificationContents {
+
+    /**
+     * Legacy dataId length limit.
+     */
+    public static final int LEGACY_CUSTOM_SYS_DATA_ID_LENGTH = 64;
+
+    /**
+     * Whitelist for custom system notifications.
+     */
+    private static final Whitelist CUSTOM_SYS_WHITELIST = Whitelist.none()
+            .addTags("a", "br")
+            .addAttributes("a", "href", "target", "rel")
+            .addProtocols("a", "href", "http", "https");
+
+    /**
+     * Output settings.
+     */
+    private static final Document.OutputSettings OUTPUT_SETTINGS = new Document.OutputSettings().prettyPrint(false);
+
+    /**
+     * HTML tag detection pattern.
+     */
+    private static final Pattern HTML_TAG_PATTERN = Pattern.compile(".*<\\s*/?\\s*[a-zA-Z][^>]*>.*", Pattern.DOTALL);
+
+    /**
+     * Private constructor.
+     */
+    private NotificationContents() {
+    }
+
+    /**
+     * Normalizes custom system notification input.
+     *
+     * @param content the raw content
+     * @return normalized content
+     */
+    public static String normalizeCustomSysContent(final String content) {
+        return StringUtils.trimToEmpty(content)
+                .replace("\r\n", "\n")
+                .replace("\r", "\n");
+    }
+
+    /**
+     * Markdown link detection pattern.
+     */
+    private static final Pattern MARKDOWN_LINK_PATTERN = Pattern.compile("\\[([^\\]\\r\\n]+)]\\((https?://[^\\s)]+)\\)");
+
+    /**
+     * Sanitizes custom system notification content. Only markdown links and line breaks are kept.
+     *
+     * @param content the raw content
+     * @return sanitized HTML
+     */
+    public static String sanitizeCustomSysContent(final String content) {
+        if (StringUtils.isBlank(content)) {
+            return StringUtils.EMPTY;
+        }
+
+        final String normalized = normalizeCustomSysContent(content);
+        final String withLinks = replaceMarkdownLinks(Escapes.escapeHTML(normalized));
+        final String cleaned = Jsoup.clean(withLinks.replace("\n", "<br>"), StringUtils.EMPTY, CUSTOM_SYS_WHITELIST, OUTPUT_SETTINGS);
+        final Document document = Jsoup.parseBodyFragment(cleaned);
+        document.outputSettings(OUTPUT_SETTINGS);
+        return document.body().html();
+    }
+
+    /**
+     * Returns whether the content needs the dedicated content column.
+     *
+     * @param content the raw content
+     * @return {@code true} if the legacy dataId field is not enough
+     */
+    public static boolean requiresDedicatedContentColumn(final String content) {
+        if (StringUtils.length(content) > LEGACY_CUSTOM_SYS_DATA_ID_LENGTH) {
+            return true;
+        }
+
+        final String safeContent = StringUtils.defaultString(content);
+        return HTML_TAG_PATTERN.matcher(safeContent).matches() || MARKDOWN_LINK_PATTERN.matcher(safeContent).find();
+    }
+
+    /**
+     * Checks whether a link is a safe HTTP/HTTPS URL.
+     *
+     * @param href the href to check
+     * @return {@code true} if safe
+     */
+    private static boolean isSafeHttpUrl(final String href) {
+        if (StringUtils.isBlank(href)) {
+            return false;
+        }
+
+        try {
+            final URL url = new URL(href);
+            final String protocol = StringUtils.lowerCase(url.getProtocol());
+            return "http".equals(protocol) || "https".equals(protocol);
+        } catch (final MalformedURLException e) {
+            return false;
+        }
+    }
+
+    /**
+     * Replaces markdown links with safe anchor HTML.
+     *
+     * @param content the escaped content
+     * @return replaced content
+     */
+    private static String replaceMarkdownLinks(final String content) {
+        final StringBuilder builder = new StringBuilder();
+        final java.util.regex.Matcher matcher = MARKDOWN_LINK_PATTERN.matcher(content);
+        int lastEnd = 0;
+        while (matcher.find()) {
+            final String href = StringUtils.trimToEmpty(matcher.group(2));
+            if (!isSafeHttpUrl(href)) {
+                continue;
+            }
+
+            builder.append(content, lastEnd, matcher.start());
+            builder.append("<a href=\"")
+                    .append(href)
+                    .append("\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">")
+                    .append(matcher.group(1))
+                    .append("</a>");
+            lastEnd = matcher.end();
+        }
+
+        builder.append(content, lastEnd, content.length());
+        return builder.toString();
+    }
+}
diff --git a/src/main/resources/repository.json b/src/main/resources/repository.json
@@ -1019,6 +1019,12 @@
           "length": 64,
           "description": "数据实体 id"
         },
+        {
+          "name": "content",
+          "type": "String",
+          "length": 4096,
+          "description": "定制系统通知正文"
+        },
         {
           "name": "dataType",
           "type": "int",

Original file line number	Diff line number	Diff line change
`@@ -570,9 +570,9 @@ public void sendSystemNotification(final RequestContext context) {`
`570`	`570`	`context.renderMsg("发送失败：notification 不能为空。");`
`571`	`571`	`return;`
`572`	`572`	`}`
`573`		`- if (notification.length() > 64) {`
	`573`	`+ if (notification.length() > Notification.MAX_LENGTH_C_CUSTOM_SYS_CONTENT) {`
`574`	`574`	`context.renderJSON(StatusCodes.ERR);`
`575`		`- context.renderMsg("发送失败：notification 长度不能超过 64 个字符。");`
	`575`	`+ context.renderMsg("发送失败：notification 长度不能超过 " + Notification.MAX_LENGTH_C_CUSTOM_SYS_CONTENT + " 个字符。");`
`576`	`576`	`return;`
`577`	`577`	`}`
`578`	`578`