1

ruoyi-system/src/main/java/com/ruoyi/jarvis/wecom/WeComConvention.java

@@ -0,0 +1,47 @@
+package com.ruoyi.jarvis.wecom;
+
+/**
+ * 企微自建应用：会话空间与 Jarvis 桥接的<strong>唯一约定身份字段</strong>说明与 Redis 键规范。
+ * <p>
+ * <b>锚定字段（存在且稳定）</b>：企业微信成员 <b>UserID</b>，在接收到自建应用的明文 XML 中与节点
+ * {@code FromUserName} 对应。该 ID 由管理员在「管理后台—通讯录」中设定，
+ * 企业内唯一；一般<strong>不随</strong>成员对外昵称修改而变化。
+ * </p>
+ * <p>
+ * 下列场景<strong>必须</strong>使用同一值（trim 后）：
+ * <ul>
+ *   <li>wxSend → Jarvis {@code /jarvis/wecom/inbound} 请求体 {@code fromUserName}</li>
+ *   <li>Redis 多轮会话键后缀（见 {@link #sessionRedisKey(String)}）</li>
+ *   <li>与「超级管理员」中登记的企微账号比对时，应与该行用于识别操作者的 UserID 一致（wxid 或 touser 等配置的比对目标均应对齐此 ID）</li>
+ * </ul>
+ * </p>
+ * <p>
+ * <b>禁止</b>使用 MsgId、消息正文、CorpId+AgentId 单独、或其它逐条变化的量作为会话主键（会导致会话无法连续）。
+ * AgentId 仅作业务旁路信息；若未来多应用共用同一回调入口，可在会话 JSON 内记录 agentId，但<strong>会话键仍以成员 UserID 为主</strong>。
+ * </p>
+ */
+public final class WeComConvention {
+
+    private WeComConvention() {
+    }
+
+    /**
+     * 多轮会话在 Redis 中的键前缀。完整键 = 此前缀 + 成员 UserID（trim）。
+     */
+    public static final String SESSION_REDIS_KEY_PREFIX = "interaction_state:wecom:";
+
+    /**
+     * 企微推送明文 XML 中表示「发送方成员 UserID」的节点名（供解析端对照，值为成员 UserID 字符串）。
+     */
+    public static final String XML_FROM_USERNAME = "FromUserName";
+
+    /**
+     * @param wecomMemberUserId 成员 UserID，须与明文 XML 中 FromUserName 一致
+     */
+    public static String sessionRedisKey(String wecomMemberUserId) {
+        if (wecomMemberUserId == null || wecomMemberUserId.trim().isEmpty()) {
+            throw new IllegalArgumentException("wecomMemberUserId 不能为空（应为企业微信 FromUserName / 成员 UserID）");
+        }
+        return SESSION_REDIS_KEY_PREFIX + wecomMemberUserId.trim();
+    }
+}