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();
    }
}