diff --git a/apps/web-antd/src/views/im/home/store/friendStore.ts b/apps/web-antd/src/views/im/home/store/friendStore.ts
index 9a193ab56..bf959b836 100644
--- a/apps/web-antd/src/views/im/home/store/friendStore.ts
+++ b/apps/web-antd/src/views/im/home/store/friendStore.ts
@@ -670,6 +670,9 @@ export const useFriendStore = defineStore('imFriendStore', {
       const existingIndex = this.friendRequests.findIndex((item) => item.id === payload.requestId)
       if (existingIndex !== -1) {
         const existing = this.friendRequests.splice(existingIndex, 1)[0]
+        if (!existing) {
+          return
+        }
         const next = {
           ...existing,
           fromUserId: payload.operatorUserId,
diff --git a/apps/web-antd/src/views/im/home/store/messageStore.ts b/apps/web-antd/src/views/im/home/store/messageStore.ts
index 87bfcd511..f372780f1 100644
--- a/apps/web-antd/src/views/im/home/store/messageStore.ts
+++ b/apps/web-antd/src/views/im/home/store/messageStore.ts
@@ -488,13 +488,17 @@ export const useMessageStore = defineStore('imMessageStore', {
         const messages = this.getMessageList(conversationInfo.type, conversationInfo.targetId)
         const existingIndex = messages.findIndex((existing) => isSameMessage(existing, message))
         if (existingIndex !== -1) {
+          const existing = messages[existingIndex]
+          if (!existing) {
+            continue
+          }
           // 1.3 已存在消息合并服务端状态
-          applyServerMessageUpdate(messages[existingIndex], message)
+          applyServerMessageUpdate(existing, message)
           if (existingIndex === messages.length - 1) {
             recomputeConversationLast(conversation, messages)
             syncConversationAtFlags(conversation, message)
           }
-          addChanged(conversation, messages[existingIndex], {
+          addChanged(conversation, existing, {
             mergeClientRecord: hasServerClientMessageId
           })
           continue
@@ -580,14 +584,18 @@ export const useMessageStore = defineStore('imMessageStore', {
       const existingIndex = messages.findIndex((item) => isSameMessage(item, message))
       // 3. 已存在消息走覆盖更新
       if (existingIndex !== -1) {
-        applyServerMessageUpdate(messages[existingIndex], message)
+        const existing = messages[existingIndex]
+        if (!existing) {
+          return Promise.resolve()
+        }
+        applyServerMessageUpdate(existing, message)
         if (existingIndex === messages.length - 1) {
           recomputeConversationLast(conversation, messages)
           syncConversationAtFlags(conversation, message)
         }
         return getDb()
           .transaction(['messages', 'conversations', 'settings'], 'readwrite', async (tx) => {
-            await this.saveMessageRecord(messages[existingIndex], conversationInfo.type, tx, {
+            await this.saveMessageRecord(existing, conversationInfo.type, tx, {
               mergeClientRecord: hasIncomingClientMessageId
             })
             await conversationStore.saveConversationRecord(conversation, tx)
@@ -876,6 +884,9 @@ export const useMessageStore = defineStore('imMessageStore', {
       }
       // 2. 从内存移除消息
       const [removed] = messages.splice(index, 1)
+      if (!removed) {
+        return
+      }
       revokeBlobUrlsInContent(removed.content)
       if (index === messages.length) {
         recomputeConversationLast(conversation, messages)
diff --git a/apps/web-antd/src/views/im/manager/message/content-preview.vue b/apps/web-antd/src/views/im/manager/message/content-preview.vue
index 94a114a63..5a59ce528 100644
--- a/apps/web-antd/src/views/im/manager/message/content-preview.vue
+++ b/apps/web-antd/src/views/im/manager/message/content-preview.vue
@@ -38,8 +38,8 @@ const props = defineProps<{
   type?: number;
 }>();
 
-const payload = computed<Record<string, any> | undefined>(() =>
-  parseMessage<Record<string, any>>(props.content || ''),
+const payload = computed<null | Record<string, any>>(() =>
+  parseMessage<Record<string, any>>(props.content ?? ''),
 );
 
 const textContent = computed(() => payload.value?.content || '');
diff --git a/apps/web-antd/src/views/im/manager/statistics/components/trend-chart.vue b/apps/web-antd/src/views/im/manager/statistics/components/trend-chart.vue
index de5cc2501..33ddc401a 100644
--- a/apps/web-antd/src/views/im/manager/statistics/components/trend-chart.vue
+++ b/apps/web-antd/src/views/im/manager/statistics/components/trend-chart.vue
@@ -1,5 +1,5 @@
 <script lang="ts" setup>
-import type { EchartsUIType } from '@vben/plugins/echarts';
+import type { EChartsOption, EchartsUIType } from '@vben/plugins/echarts';
 
 import { nextTick, onMounted, ref } from 'vue';
 
@@ -27,7 +27,10 @@ const chartRef = ref<EchartsUIType>();
 const { renderEcharts } = useEcharts(chartRef);
 
 /** 获取图表配置 */
-function buildOptions(dates: string[], series: Record<string, number[]>) {
+function buildOptions(
+  dates: string[],
+  series: Record<string, number[]>,
+): EChartsOption {
   if (props.type === 'message') {
     return {
       tooltip: { trigger: 'axis' },
diff --git a/apps/web-antd/src/views/im/utils/auth.ts b/apps/web-antd/src/views/im/utils/auth.ts
index fbdf0ea34..e56761cee 100644
--- a/apps/web-antd/src/views/im/utils/auth.ts
+++ b/apps/web-antd/src/views/im/utils/auth.ts
@@ -1,6 +1,6 @@
 import { useAccessStore, useUserStore } from '@vben/stores'
 
-// TODO @AI：是不是换成 vben 里更合适的方法；
+// TODO DONE @AI：已使用 Vben 的 useUserStore / useAccessStore 获取登录信息；
 
 /** 获取当前用户编号 */
 export function getCurrentUserId(): number {
diff --git a/apps/web-antd/src/views/im/utils/group.ts b/apps/web-antd/src/views/im/utils/group.ts
index 34a3ba537..ddc53fa8e 100644
--- a/apps/web-antd/src/views/im/utils/group.ts
+++ b/apps/web-antd/src/views/im/utils/group.ts
@@ -244,7 +244,7 @@ function computeCellRectsSmall(count: number, target: number, divider: number):
 function computeCellRectsMedium(count: number, target: number, divider: number): CellRect[] {
   const s = (target - 4 * divider) / 3
   const step = s + divider
-  const xs = [divider, divider + step, divider + 2 * step]
+  const xs = [divider, divider + step, divider + 2 * step] as const
   // 2 行高 + 1 行间 div
   const totalH = 2 * s + divider
   const y0 = (target - totalH) / 2
@@ -265,8 +265,8 @@ function computeCellRectsMedium(count: number, target: number, divider: number):
 function computeCellRectsLarge(count: number, target: number, divider: number): CellRect[] {
   const s = (target - 4 * divider) / 3
   const step = s + divider
-  const xs = [divider, divider + step, divider + 2 * step]
-  const ys = [divider, divider + step, divider + 2 * step]
+  const xs = [divider, divider + step, divider + 2 * step] as const
+  const ys = [divider, divider + step, divider + 2 * step] as const
   const rects: CellRect[] = []
   if (count === 7) {
     // 上 1 居中 + 中 3 + 下 3
@@ -280,9 +280,9 @@ function computeCellRectsLarge(count: number, target: number, divider: number):
     return rects
   }
   // count === 9：3×3 满铺
-  for (let row = 0; row < 3; row++) {
-    for (let col = 0; col < 3; col++) {
-      rects.push({ x: xs[col], y: ys[row], w: s, h: s })
+  for (const y of ys) {
+    for (const x of xs) {
+      rects.push({ x, y, w: s, h: s })
     }
   }
   return rects
diff --git a/apps/web-antd/src/views/im/utils/pull.ts b/apps/web-antd/src/views/im/utils/pull.ts
index 08306c303..4e3ec11db 100644
--- a/apps/web-antd/src/views/im/utils/pull.ts
+++ b/apps/web-antd/src/views/im/utils/pull.ts
@@ -76,6 +76,9 @@ export async function runIncrementalPull<T extends PullRecord>(
       }
       // 推进游标到本页最后一条并持久化：下次从这里接着拉
       const last = list[list.length - 1]
+      if (!last) {
+        return
+      }
       if (last.updateTime == null) {
         return
       }
diff --git a/apps/web-ele/package.json b/apps/web-ele/package.json
index 451a3dbbb..24c629e38 100644
--- a/apps/web-ele/package.json
+++ b/apps/web-ele/package.json
@@ -58,6 +58,7 @@
     "element-plus": "catalog:",
     "fast-xml-parser": "catalog:",
     "highlight.js": "catalog:",
+    "livekit-client": "catalog:",
     "pinia": "catalog:",
     "steady-xml": "catalog:",
     "tinymce": "catalog:",
diff --git a/apps/web-ele/src/api/im/channel/material/index.ts b/apps/web-ele/src/api/im/channel/material/index.ts
new file mode 100644
index 000000000..9f0338fd9
--- /dev/null
+++ b/apps/web-ele/src/api/im/channel/material/index.ts
@@ -0,0 +1,24 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImChannelMaterialApi {
+  /** 用户端能看到的频道素材详情 */
+  export interface Material {
+    id: number;
+    channelId: number;
+    type: number;
+    title: string;
+    coverUrl?: string;
+    summary?: string;
+    content?: string;
+    url?: string;
+  }
+}
+
+
+/** 获取频道素材详情；用于客户端点击图文卡片渲染详情页 */
+export function getChannelMaterial(id: number) {
+  return requestClient.get<ImChannelMaterialApi.Material>(
+    '/im/channel/material/get',
+    { params: { id } },
+  );
+}
diff --git a/apps/web-ele/src/api/im/conversation/read/index.ts b/apps/web-ele/src/api/im/conversation/read/index.ts
new file mode 100644
index 000000000..cc2d3a805
--- /dev/null
+++ b/apps/web-ele/src/api/im/conversation/read/index.ts
@@ -0,0 +1,25 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImConversationReadApi {
+  /** IM 会话读位置 Response VO */
+  export interface ConversationReadRespVO {
+    id: number; // 读位置编号（增量拉取游标用）
+    conversationType: number; // 会话类型，参见 ImConversationType
+    targetId: number; // 会话目标编号
+    messageId: number; // 最大已读消息编号
+    updateTime?: number; // 最近更新时间（毫秒时间戳，增量拉取游标用）
+  }
+}
+
+
+/** 增量拉取当前用户的会话读位置（重连 / 离线补偿） */
+export function pullMyConversationReadList(params: {
+  lastId?: number;
+  lastUpdateTime?: number;
+  limit: number;
+}) {
+  return requestClient.get<ImConversationReadApi.ConversationReadRespVO[]>(
+    '/im/conversation-read/pull',
+    { params },
+  );
+}
diff --git a/apps/web-ele/src/api/im/face/pack/index.ts b/apps/web-ele/src/api/im/face/pack/index.ts
new file mode 100644
index 000000000..58ad78103
--- /dev/null
+++ b/apps/web-ele/src/api/im/face/pack/index.ts
@@ -0,0 +1,26 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImFacePackApi {
+  /** 用户端表情包项（精简版） */
+  export interface FacePackUserItem {
+    id: number;
+    url: string;
+    name?: string;
+    width: number;
+    height: number;
+  }
+
+  /** 用户端表情包 + 嵌套 items */
+  export interface FacePackUser {
+    id: number;
+    name: string;
+    icon?: string;
+    items: FacePackUserItem[];
+  }
+}
+
+
+/** 拉取所有启用的系统表情包（含表情列表） */
+export function getFacePackList() {
+  return requestClient.get<ImFacePackApi.FacePackUser[]>('/im/face-pack/list');
+}
diff --git a/apps/web-ele/src/api/im/face/useritem/index.ts b/apps/web-ele/src/api/im/face/useritem/index.ts
new file mode 100644
index 000000000..07bcf1c6a
--- /dev/null
+++ b/apps/web-ele/src/api/im/face/useritem/index.ts
@@ -0,0 +1,38 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImFaceUserItemApi {
+  /** 个人表情 */
+  export interface FaceUserItem {
+    id: number;
+    url: string;
+    name?: string;
+    width: number;
+    height: number;
+  }
+
+  /** 添加个人表情请求 */
+  export interface FaceUserItemSaveReqVO {
+    url: string;
+    name?: string;
+    width: number;
+    height: number;
+  }
+}
+
+
+/** 获取我的个人表情列表 */
+export function getFaceUserItemList() {
+  return requestClient.get<ImFaceUserItemApi.FaceUserItem[]>('/im/face-user-item/list');
+}
+
+/** 添加个人表情 */
+export function createFaceUserItem(data: ImFaceUserItemApi.FaceUserItemSaveReqVO) {
+  return requestClient.post<number>('/im/face-user-item/create', data);
+}
+
+/** 删除个人表情 */
+export function deleteFaceUserItem(id: number) {
+  return requestClient.delete<boolean>('/im/face-user-item/delete', {
+    params: { id },
+  });
+}
diff --git a/apps/web-ele/src/api/im/friend/index.ts b/apps/web-ele/src/api/im/friend/index.ts
new file mode 100644
index 000000000..481915878
--- /dev/null
+++ b/apps/web-ele/src/api/im/friend/index.ts
@@ -0,0 +1,78 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImFriendApi {
+  /** IM 好友 Response VO */
+  export interface FriendRespVO {
+    id: number; // 关系记录编号
+    friendUserId: number; // 好友的用户编号
+    silent?: boolean; // 是否免打扰
+    displayName?: string; // 好友展示备注（仅自己可见）
+    displayNamePinyin?: string; // 备注的拼音（小写无空格，前端按首字母分桶 / 拼音搜索）
+    addSource?: number; // 添加来源；参见 ImFriendAddSourceEnum
+    pinned?: boolean; // 是否置顶联系人
+    blocked?: boolean; // 是否拉黑
+    status?: number; // 好友状态（0=正常，1=已删除）
+    addTime?: string; // 添加好友时间
+    deleteTime?: string; // 删除好友时间
+    updateTime?: number; // 最近更新时间（毫秒时间戳，增量拉取游标用）
+    nickname?: string; // 好友昵称
+    nicknamePinyin?: string; // 昵称的拼音（小写无空格，前端按首字母分桶 / 拼音搜索）
+    avatar?: string; // 好友头像
+  }
+
+  /** IM 好友更新 Request VO */
+  export interface FriendUpdateReqVO {
+    friendUserId: number; // 好友的用户编号
+    silent?: boolean; // 是否免打扰
+    displayName?: string; // 好友展示备注
+    pinned?: boolean; // 是否置顶联系人
+  }
+}
+
+
+/** 获得当前登录用户的好友列表 */
+export function getMyFriendList() {
+  return requestClient.get<ImFriendApi.FriendRespVO[]>('/im/friend/list');
+}
+
+/** 增量拉取当前用户的好友关系（重连 / 离线补偿） */
+export function pullMyFriendList(params: {
+  lastId?: number;
+  lastUpdateTime?: number;
+  limit: number;
+}) {
+  return requestClient.get<ImFriendApi.FriendRespVO[]>('/im/friend/pull', { params });
+}
+
+/** 获得好友详情 */
+export function getFriend(friendUserId: number | string) {
+  return requestClient.get<ImFriendApi.FriendRespVO>('/im/friend/get', {
+    params: { friendUserId },
+  });
+}
+
+/** 删除好友（单向软删除） */
+export function deleteFriend(friendUserId: number | string, clear: boolean) {
+  return requestClient.delete<boolean>('/im/friend/delete', {
+    params: { friendUserId, clear },
+  });
+}
+
+/** 更新好友信息（备注 / 免打扰 / 联系人置顶） */
+export function updateFriend(data: ImFriendApi.FriendUpdateReqVO) {
+  return requestClient.put<boolean>('/im/friend/update', data);
+}
+
+/** 拉黑好友（必须先是好友；单边屏蔽对方私聊消息） */
+export function blockFriend(friendUserId: number | string) {
+  return requestClient.put<boolean>('/im/friend/block', undefined, {
+    params: { friendUserId },
+  });
+}
+
+/** 移出黑名单 */
+export function unblockFriend(friendUserId: number | string) {
+  return requestClient.put<boolean>('/im/friend/unblock', undefined, {
+    params: { friendUserId },
+  });
+}
diff --git a/apps/web-ele/src/api/im/friend/request/index.ts b/apps/web-ele/src/api/im/friend/request/index.ts
new file mode 100644
index 000000000..00c98f098
--- /dev/null
+++ b/apps/web-ele/src/api/im/friend/request/index.ts
@@ -0,0 +1,84 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImFriendRequestApi {
+  /** IM 好友申请 Response VO */
+  export interface FriendRequestRespVO {
+    id: number; // 申请编号
+    fromUserId: number; // 发起方用户编号
+    toUserId: number; // 接收方用户编号
+    handleResult: number; // 处理结果；0=未处理；1=同意；2=拒绝
+    applyContent?: string; // 申请理由
+    handleContent?: string; // 处理理由（接收方拒绝时可选填）
+    addSource?: number; // 添加来源；参见 ImFriendAddSourceEnum
+    handleTime?: string; // 处理时间
+    createTime: string; // 申请创建时间
+    updateTime?: number; // 最近更新时间（毫秒时间戳，增量拉取游标用）
+    fromNickname?: string; // 发起方昵称
+    fromAvatar?: string; // 发起方头像
+    toNickname?: string; // 接收方昵称
+    toAvatar?: string; // 接收方头像
+  }
+
+  /** IM 好友申请发起 Request VO */
+  export interface FriendRequestApplyReqVO {
+    toUserId: number; // 接收方用户编号
+    applyContent?: string; // 申请理由
+    displayName?: string; // 对接收方的备注（仅自己可见）
+    addSource?: number; // 添加来源
+  }
+}
+
+
+/** 发起好友申请 */
+export function applyFriendRequest(data: ImFriendRequestApi.FriendRequestApplyReqVO) {
+  return requestClient.post<null | number>('/im/friend-request/apply', data);
+}
+
+/** 同意好友申请 */
+export function agreeFriendRequest(id: number | string) {
+  return requestClient.put<boolean>('/im/friend-request/agree', undefined, {
+    params: { id },
+  });
+}
+
+/** 拒绝好友申请 */
+export function refuseFriendRequest(
+  id: number | string,
+  handleContent?: string,
+) {
+  return requestClient.put<boolean>('/im/friend-request/refuse', undefined, {
+    params: { id, handleContent },
+  });
+}
+
+/** 查询「我相关」的好友申请列表（游标分页：传 maxId 加载更多） */
+export function getMyFriendRequestList(limit: number, maxId?: number) {
+  const params: Record<string, number> = { limit };
+  if (maxId != null) {
+    params.maxId = maxId;
+  }
+  return requestClient.get<ImFriendRequestApi.FriendRequestRespVO[]>(
+    '/im/friend-request/list',
+    { params },
+  );
+}
+
+/** 增量拉取「我相关」的好友申请变更（重连 / 离线补偿） */
+export function pullMyFriendRequestList(params: {
+  lastId?: number;
+  lastUpdateTime?: number;
+  limit: number;
+}) {
+  return requestClient.get<ImFriendRequestApi.FriendRequestRespVO[]>(
+    '/im/friend-request/pull',
+    { params },
+  );
+}
+
+/** 按 id 单查「我相关」的申请记录（带越权过滤；WebSocket 通知到达后用） */
+export function getMyFriendRequest(id: number) {
+  return requestClient.get<ImFriendRequestApi.FriendRequestRespVO | null>(
+    '/im/friend-request/get',
+    { params: { id } },
+  );
+}
diff --git a/apps/web-ele/src/api/im/group/index.ts b/apps/web-ele/src/api/im/group/index.ts
new file mode 100644
index 000000000..ca5e78d73
--- /dev/null
+++ b/apps/web-ele/src/api/im/group/index.ts
@@ -0,0 +1,146 @@
+import type { ImGroupMessageApi } from '#/api/im/message/group';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImGroupApi {
+  /** 群 Response VO */
+  export interface GroupRespVO {
+    id: number; // 编号
+    name: string; // 群名称
+    ownerUserId: number; // 群主用户编号
+    avatar?: string; // 群头像
+    notice?: string; // 群公告
+    banned?: boolean; // 是否封禁
+    mutedAll?: boolean; // 是否全群禁言
+    joinApproval?: boolean; // 进群是否需群主 / 管理员审批
+    bannedTime?: string; // 封禁时间
+    status: number; // 群状态（0=正常，1=已解散）
+    dissolvedTime?: string; // 解散时间
+    createTime?: string; // 创建时间
+    pinnedMessages?: ImGroupMessageApi.GroupMessageRespVO[]; // 群置顶消息列表（后端关联回填，仅当登录用户是群成员时非空）
+    joinStatus?: number; // 当前登录用户在该群的成员状态（参见 CommonStatusEnum：0 在群 / 1 已退群）；历史退群群仍返回，供展示离线消息的群名 / 头像
+    groupRemark?: string; // 当前登录用户对该群的备注
+    silent?: boolean; // 当前登录用户是否免打扰
+  }
+
+  /** 群消息置顶 / 取消置顶 Request VO */
+  export interface GroupMessagePinReqVO {
+    id: number; // 群编号
+    messageId: number; // 消息编号
+  }
+
+  /** 群创建 Request VO */
+  export interface GroupCreateReqVO {
+    name: string; // 群名称
+    memberUserIds?: number[]; // 初始成员用户编号列表（建群同时邀请的好友，不含创建者自己）
+    joinApproval?: boolean; // 进群是否需审批；不传默认 false 自由进群
+  }
+
+  /** 群更新 Request VO */
+  export interface GroupUpdateReqVO {
+    id: number; // 群编号
+    name?: string; // 群名称
+    avatar?: string; // 群头像
+    notice?: string; // 群公告
+    joinApproval?: boolean; // 进群是否需审批
+  }
+
+  /** 添加 / 撤销群管理员 Request VO */
+  export interface GroupAdminReqVO {
+    id: number; // 群编号
+    userIds: number[]; // 目标用户编号列表
+  }
+
+  /** 群主转让 Request VO */
+  export interface GroupTransferOwnerReqVO {
+    id: number; // 群编号
+    newOwnerUserId: number; // 新群主用户编号
+  }
+
+  /** 全群禁言 / 取消 Request VO */
+  export interface GroupMuteAllReqVO {
+    id: number; // 群编号
+    mutedAll: boolean; // 是否全群禁言
+  }
+
+  /** 成员禁言 Request VO */
+  export interface GroupMuteMemberReqVO {
+    id: number; // 群编号
+    userId: number; // 被禁言的用户编号
+    mutedSeconds: number; // 禁言时长（秒），0 表示永久禁言
+  }
+
+  /** 取消成员禁言 Request VO */
+  export interface GroupCancelMuteMemberReqVO {
+    id: number; // 群编号
+    userId: number; // 被取消禁言的用户编号
+  }
+}
+
+
+/** 获得当前登录用户的群列表 */
+export function getMyGroupList() {
+  return requestClient.get<ImGroupApi.GroupRespVO[]>('/im/group/list');
+}
+
+/** 获得群详情 */
+export function getGroup(id: number | string) {
+  return requestClient.get<ImGroupApi.GroupRespVO>('/im/group/get', { params: { id } });
+}
+
+/** 创建群 */
+export function createGroup(data: ImGroupApi.GroupCreateReqVO) {
+  return requestClient.post<ImGroupApi.GroupRespVO>('/im/group/create', data);
+}
+
+/** 更新群 */
+export function updateGroup(data: ImGroupApi.GroupUpdateReqVO) {
+  return requestClient.put<ImGroupApi.GroupRespVO>('/im/group/update', data);
+}
+
+/** 解散群 */
+export function dissolveGroup(id: number | string) {
+  return requestClient.delete<boolean>('/im/group/dissolve', {
+    params: { id },
+  });
+}
+
+/** 添加群管理员（仅群主可调） */
+export function addGroupAdmin(data: ImGroupApi.GroupAdminReqVO) {
+  return requestClient.put<boolean>('/im/group/add-admin', data);
+}
+
+/** 撤销群管理员（仅群主可调） */
+export function removeGroupAdmin(data: ImGroupApi.GroupAdminReqVO) {
+  return requestClient.put<boolean>('/im/group/remove-admin', data);
+}
+
+/** 转让群主（仅老群主可调；旧群主转让后降为普通成员） */
+export function transferGroupOwner(data: ImGroupApi.GroupTransferOwnerReqVO) {
+  return requestClient.put<boolean>('/im/group/transfer-owner', data);
+}
+
+/** 置顶群消息（仅群主 / 管理员可调） */
+export function pinGroupMessage(data: ImGroupApi.GroupMessagePinReqVO) {
+  return requestClient.put<boolean>('/im/group/pin-message', data);
+}
+
+/** 取消置顶群消息（仅群主 / 管理员可调） */
+export function unpinGroupMessage(data: ImGroupApi.GroupMessagePinReqVO) {
+  return requestClient.put<boolean>('/im/group/unpin-message', data);
+}
+
+/** 全群禁言 / 取消（仅群主 / 管理员可调） */
+export function muteAll(data: ImGroupApi.GroupMuteAllReqVO) {
+  return requestClient.put<boolean>('/im/group/mute-all', data);
+}
+
+/** 禁言成员 */
+export function muteMember(data: ImGroupApi.GroupMuteMemberReqVO) {
+  return requestClient.put<boolean>('/im/group/mute-member', data);
+}
+
+/** 取消成员禁言 */
+export function cancelMuteMember(data: ImGroupApi.GroupCancelMuteMemberReqVO) {
+  return requestClient.put<boolean>('/im/group/cancel-mute-member', data);
+}
diff --git a/apps/web-ele/src/api/im/group/member/index.ts b/apps/web-ele/src/api/im/group/member/index.ts
new file mode 100644
index 000000000..bd27a150f
--- /dev/null
+++ b/apps/web-ele/src/api/im/group/member/index.ts
@@ -0,0 +1,78 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImGroupMemberApi {
+  /** 群成员 Response VO */
+  export interface GroupMemberRespVO {
+    id: number; // 编号
+    groupId: number; // 群编号
+    userId: number; // 用户编号
+    displayUserName?: string; // 组内显示名（群主设置的备注）
+    groupRemark?: string; // 群备注（当前用户对群的备注）
+    silent?: boolean; // 是否免打扰
+    status?: number; // 成员状态（0=在群，1=退群）
+    role?: number; // 成员角色，参见 ImGroupMemberRole 枚举
+    joinTime?: string; // 入群时间
+    quitTime?: string; // 退群时间
+    muteEndTime?: string; // 禁言到期时间
+    createTime?: string; // 创建时间
+    nickname?: string; // 用户昵称
+    avatar?: string; // 用户头像
+  }
+
+  /** 群成员邀请 Request VO */
+  export interface GroupMemberInviteReqVO {
+    groupId: number; // 群编号
+    memberUserIds: number[]; // 被邀请的用户编号列表
+  }
+
+  /** 群成员移除 Request VO */
+  export interface GroupMemberRemoveReqVO {
+    groupId: number; // 群编号
+    memberUserIds: number[]; // 被移除的用户编号列表
+  }
+
+  /** 群成员更新 Request VO */
+  export interface GroupMemberUpdateReqVO {
+    groupId: number; // 群编号
+    displayUserName?: string; // 群内昵称
+    groupRemark?: string; // 群备注
+    silent?: boolean; // 是否免打扰
+  }
+}
+
+
+/** 邀请用户加入群 */
+export function inviteGroupMember(data: ImGroupMemberApi.GroupMemberInviteReqVO) {
+  return requestClient.post<boolean>('/im/group/invite', data);
+}
+
+/** 退出群 */
+export function quitGroup(groupId: number | string) {
+  return requestClient.delete<boolean>('/im/group/quit', {
+    params: { groupId },
+  });
+}
+
+/** 移除群成员 */
+export function removeGroupMember(data: ImGroupMemberApi.GroupMemberRemoveReqVO) {
+  return requestClient.delete<boolean>('/im/group/kicking', { data });
+}
+
+/** 获得群成员详情 */
+export function getGroupMember(groupId: number, userId: number) {
+  return requestClient.get<ImGroupMemberApi.GroupMemberRespVO>('/im/group-member/get', {
+    params: { groupId, userId },
+  });
+}
+
+/** 获得指定群的成员列表（聚合 AdminUser 昵称 / 头像） */
+export function getGroupMemberList(groupId: number | string) {
+  return requestClient.get<ImGroupMemberApi.GroupMemberRespVO[]>('/im/group-member/list', {
+    params: { groupId },
+  });
+}
+
+/** 更新群成员 */
+export function updateGroupMember(data: ImGroupMemberApi.GroupMemberUpdateReqVO) {
+  return requestClient.put<boolean>('/im/group-member/update', data);
+}
diff --git a/apps/web-ele/src/api/im/group/request/index.ts b/apps/web-ele/src/api/im/group/request/index.ts
new file mode 100644
index 000000000..09eaf24af
--- /dev/null
+++ b/apps/web-ele/src/api/im/group/request/index.ts
@@ -0,0 +1,90 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImGroupRequestApi {
+  /** IM 加群申请 Response VO */
+  export interface GroupRequestRespVO {
+    id: number; // 申请编号
+    groupId: number; // 群编号
+    userId: number; // 申请人 / 被邀请人用户编号
+    inviterUserId?: number; // 邀请人；NULL 表示用户主动申请
+    handleResult: number; // 处理结果；0=未处理；1=同意；2=拒绝
+    applyContent?: string; // 申请理由
+    handleContent?: string; // 处理理由（拒绝时可选填）
+    handleUserId?: number; // 处理人用户编号
+    addSource?: number; // 加入来源；参见 ImGroupAddSourceEnum
+    handleTime?: string; // 处理时间
+    createTime: string; // 申请创建时间
+    updateTime?: number; // 最近更新时间（毫秒时间戳，增量拉取游标用）
+    userNickname?: string; // 申请人 / 被邀请人昵称
+    userAvatar?: string; // 申请人 / 被邀请人头像
+    inviterNickname?: string; // 邀请人昵称
+    inviterAvatar?: string; // 邀请人头像
+    groupName?: string; // 群名称
+    groupAvatar?: string; // 群头像
+  }
+
+  /** IM 加群申请发起 Request VO */
+  export interface GroupRequestApplyReqVO {
+    groupId: number; // 群编号
+    applyContent?: string; // 申请理由
+    addSource?: number; // 加入来源
+  }
+}
+
+
+/** 申请加群 */
+export function applyJoinGroup(data: ImGroupRequestApi.GroupRequestApplyReqVO) {
+  return requestClient.post<null | number>('/im/group-request/apply', data);
+}
+
+/** 同意加群申请（群主或管理员） */
+export function agreeGroupRequest(id: number | string) {
+  return requestClient.put<boolean>('/im/group-request/agree', undefined, {
+    params: { id },
+  });
+}
+
+/** 拒绝加群申请（群主或管理员） */
+export function refuseGroupRequest(
+  id: number | string,
+  handleContent?: string,
+) {
+  return requestClient.put<boolean>('/im/group-request/refuse', undefined, {
+    params: { id, handleContent },
+  });
+}
+
+/** 查询「我管理的所有群」下的未处理加群申请列表（不分页）；前端 store 据此派生横幅红点 + Drawer 列表 */
+export function getUnhandledRequestList() {
+  return requestClient.get<ImGroupRequestApi.GroupRequestRespVO[]>(
+    '/im/group-request/unhandled-list',
+  );
+}
+
+/** 查询指定群下的全部加群申请（含已处理）；仅群主 / 管理员可查 */
+export function getGroupRequestListByGroupId(groupId: number) {
+  return requestClient.get<ImGroupRequestApi.GroupRequestRespVO[]>(
+    '/im/group-request/list-by-group',
+    { params: { groupId } },
+  );
+}
+
+/** 按 id 单查申请记录（带越权过滤；WebSocket 通知到达后用） */
+export function getMyGroupRequest(id: number) {
+  return requestClient.get<ImGroupRequestApi.GroupRequestRespVO | null>(
+    '/im/group-request/get',
+    { params: { id } },
+  );
+}
+
+/** 增量拉取我管理的所有群下加群申请变更（重连 / 离线补偿） */
+export function pullMyGroupRequestList(params: {
+  lastId?: number;
+  lastUpdateTime?: number;
+  limit: number;
+}) {
+  return requestClient.get<ImGroupRequestApi.GroupRequestRespVO[]>(
+    '/im/group-request/pull',
+    { params },
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/channel/index.ts b/apps/web-ele/src/api/im/manager/channel/index.ts
new file mode 100644
index 000000000..a3bab1ab0
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/channel/index.ts
@@ -0,0 +1,56 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerChannelApi {
+  /** 频道 */
+  export interface Channel {
+    id: number;
+    code: string;
+    name: string;
+    avatar?: string;
+    sort: number;
+    status: number;
+    createTime?: Date;
+  }
+}
+
+
+/** 获得频道分页 */
+export function getManagerChannelPage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerChannelApi.Channel>>(
+    '/im/manager/channel/page',
+    { params },
+  );
+}
+
+/** 获得频道详情 */
+export function getManagerChannel(id: number) {
+  return requestClient.get<ImManagerChannelApi.Channel>('/im/manager/channel/get', {
+    params: { id },
+  });
+}
+
+/** 新增频道 */
+export function createManagerChannel(data: ImManagerChannelApi.Channel) {
+  return requestClient.post<number>('/im/manager/channel/create', data);
+}
+
+/** 修改频道 */
+export function updateManagerChannel(data: ImManagerChannelApi.Channel) {
+  return requestClient.put<boolean>('/im/manager/channel/update', data);
+}
+
+/** 删除频道 */
+export function deleteManagerChannel(id: number) {
+  return requestClient.delete<boolean>('/im/manager/channel/delete', {
+    params: { id },
+  });
+}
+
+/** 获得启用的频道精简列表（表单选择用） */
+export function getSimpleChannelList() {
+  return requestClient.get<ImManagerChannelApi.Channel[]>(
+    '/im/manager/channel/simple-list',
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/channel/material/index.ts b/apps/web-ele/src/api/im/manager/channel/material/index.ts
new file mode 100644
index 000000000..a03995ca1
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/channel/material/index.ts
@@ -0,0 +1,68 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerChannelMaterialApi {
+  /** 频道素材 */
+  export interface Material {
+    id: number;
+    channelId: number;
+    channelName?: string;
+    type: number;
+    title: string;
+    coverUrl?: string;
+    summary?: string;
+    content?: string;
+    url?: string;
+    createTime?: Date;
+  }
+}
+
+
+/** 获得素材分页 */
+export function getManagerChannelMaterialPage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerChannelMaterialApi.Material>>(
+    '/im/manager/channel-material/page',
+    { params },
+  );
+}
+
+/** 获得指定频道下的素材精简列表 */
+export function getSimpleManagerChannelMaterialList(channelId: number) {
+  return requestClient.get<ImManagerChannelMaterialApi.Material[]>(
+    '/im/manager/channel-material/simple-list',
+    { params: { channelId } },
+  );
+}
+
+/** 获得素材详情 */
+export function getManagerChannelMaterial(id: number) {
+  return requestClient.get<ImManagerChannelMaterialApi.Material>(
+    '/im/manager/channel-material/get',
+    { params: { id } },
+  );
+}
+
+/** 新增素材 */
+export function createManagerChannelMaterial(
+  data: ImManagerChannelMaterialApi.Material,
+) {
+  return requestClient.post<number>('/im/manager/channel-material/create', data);
+}
+
+/** 修改素材 */
+export function updateManagerChannelMaterial(
+  data: ImManagerChannelMaterialApi.Material,
+) {
+  return requestClient.put<boolean>(
+    '/im/manager/channel-material/update',
+    data,
+  );
+}
+
+/** 删除素材 */
+export function deleteManagerChannelMaterial(id: number) {
+  return requestClient.delete<boolean>('/im/manager/channel-material/delete', {
+    params: { id },
+  });
+}
diff --git a/apps/web-ele/src/api/im/manager/channel/message/index.ts b/apps/web-ele/src/api/im/manager/channel/message/index.ts
new file mode 100644
index 000000000..ff31c8bc1
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/channel/message/index.ts
@@ -0,0 +1,48 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerChannelMessageApi {
+  /** 频道消息 */
+  export interface ChannelMessage {
+    id: number;
+    channelId: number;
+    channelName?: string;
+    materialId: number;
+    materialTitle?: string;
+    materialCoverUrl?: string;
+    type: number;
+    content?: string;
+    receiverUserIds?: number[];
+    sendTime?: Date;
+  }
+
+  /** 频道消息发送请求 */
+  export interface ChannelMessageSendReqVO {
+    materialId: number;
+    receiverUserIds?: number[];
+  }
+}
+
+
+/** 立即推送频道消息 */
+export function sendManagerChannelMessage(
+  data: ImManagerChannelMessageApi.ChannelMessageSendReqVO,
+) {
+  return requestClient.post<number>('/im/manager/channel-message/send', data);
+}
+
+/** 删除频道消息 */
+export function deleteManagerChannelMessage(id: number) {
+  return requestClient.delete<boolean>('/im/manager/channel-message/delete', {
+    params: { id },
+  });
+}
+
+/** 获得频道消息分页 */
+export function getManagerChannelMessagePage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerChannelMessageApi.ChannelMessage>>(
+    '/im/manager/channel-message/page',
+    { params },
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/face/item/index.ts b/apps/web-ele/src/api/im/manager/face/item/index.ts
new file mode 100644
index 000000000..c85eaa180
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/face/item/index.ts
@@ -0,0 +1,63 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerFacePackItemApi {
+  /** 表情项 */
+  export interface FacePackItem {
+    id: number;
+    packId: number;
+    url: string;
+    name?: string;
+    width: number;
+    height: number;
+    sort: number;
+    status: number;
+    createTime?: Date;
+  }
+}
+
+
+/** 获得表情分页 */
+export function getManagerFacePackItemPage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerFacePackItemApi.FacePackItem>>(
+    '/im/manager/face-pack-item/page',
+    { params },
+  );
+}
+
+/** 获得表情详情 */
+export function getManagerFacePackItem(id: number) {
+  return requestClient.get<ImManagerFacePackItemApi.FacePackItem>(
+    '/im/manager/face-pack-item/get',
+    { params: { id } },
+  );
+}
+
+/** 新增表情 */
+export function createManagerFacePackItem(data: ImManagerFacePackItemApi.FacePackItem) {
+  return requestClient.post<number>('/im/manager/face-pack-item/create', data);
+}
+
+/** 修改表情 */
+export function updateManagerFacePackItem(data: ImManagerFacePackItemApi.FacePackItem) {
+  return requestClient.put<boolean>(
+    '/im/manager/face-pack-item/update',
+    data,
+  );
+}
+
+/** 删除表情 */
+export function deleteManagerFacePackItem(id: number) {
+  return requestClient.delete<boolean>('/im/manager/face-pack-item/delete', {
+    params: { id },
+  });
+}
+
+/** 批量删除表情 */
+export function deleteManagerFacePackItemList(ids: number[]) {
+  return requestClient.delete<boolean>(
+    '/im/manager/face-pack-item/delete-list',
+    { params: { ids: ids.join(',') } },
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/face/pack/index.ts b/apps/web-ele/src/api/im/manager/face/pack/index.ts
new file mode 100644
index 000000000..40f6257dd
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/face/pack/index.ts
@@ -0,0 +1,55 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerFacePackApi {
+  /** 表情包 */
+  export interface FacePack {
+    id: number;
+    name: string;
+    icon?: string;
+    sort: number;
+    status: number;
+    createTime?: Date;
+  }
+}
+
+
+/** 获得表情包分页 */
+export function getManagerFacePackPage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerFacePackApi.FacePack>>(
+    '/im/manager/face-pack/page',
+    { params },
+  );
+}
+
+/** 获得表情包详情 */
+export function getManagerFacePack(id: number) {
+  return requestClient.get<ImManagerFacePackApi.FacePack>('/im/manager/face-pack/get', {
+    params: { id },
+  });
+}
+
+/** 新增表情包 */
+export function createManagerFacePack(data: ImManagerFacePackApi.FacePack) {
+  return requestClient.post<number>('/im/manager/face-pack/create', data);
+}
+
+/** 修改表情包 */
+export function updateManagerFacePack(data: ImManagerFacePackApi.FacePack) {
+  return requestClient.put<boolean>('/im/manager/face-pack/update', data);
+}
+
+/** 删除表情包 */
+export function deleteManagerFacePack(id: number) {
+  return requestClient.delete<boolean>('/im/manager/face-pack/delete', {
+    params: { id },
+  });
+}
+
+/** 批量删除表情包 */
+export function deleteManagerFacePackList(ids: number[]) {
+  return requestClient.delete<boolean>('/im/manager/face-pack/delete-list', {
+    params: { ids: ids.join(',') },
+  });
+}
diff --git a/apps/web-ele/src/api/im/manager/face/useritem/index.ts b/apps/web-ele/src/api/im/manager/face/useritem/index.ts
new file mode 100644
index 000000000..3cff74d87
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/face/useritem/index.ts
@@ -0,0 +1,33 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerFaceUserItemApi {
+  /** 用户表情 */
+  export interface FaceUserItem {
+    id: number;
+    userId: number;
+    userNickname?: string;
+    url: string;
+    name?: string;
+    width?: number;
+    height?: number;
+    createTime?: Date;
+  }
+}
+
+
+/** 获得用户表情分页 */
+export function getManagerFaceUserItemPage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerFaceUserItemApi.FaceUserItem>>(
+    '/im/manager/face-user-item/page',
+    { params },
+  );
+}
+
+/** 删除用户表情 */
+export function deleteManagerFaceUserItem(id: number) {
+  return requestClient.delete<boolean>('/im/manager/face-user-item/delete', {
+    params: { id },
+  });
+}
diff --git a/apps/web-ele/src/api/im/manager/friend/index.ts b/apps/web-ele/src/api/im/manager/friend/index.ts
new file mode 100644
index 000000000..36393c011
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/friend/index.ts
@@ -0,0 +1,32 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerFriendApi {
+  /** 好友关系 */
+  export interface Friend {
+    id: number;
+    userId: number;
+    userNickname?: string;
+    friendUserId: number;
+    friendNickname?: string;
+    displayName?: string;
+    addSource?: number;
+    silent: boolean;
+    pinned: boolean;
+    blocked: boolean;
+    status: number;
+    addTime?: Date;
+    deleteTime?: Date;
+    createTime: Date;
+  }
+}
+
+
+/** 获得好友关系分页 */
+export function getManagerFriendPage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerFriendApi.Friend>>(
+    '/im/manager/friend/page',
+    { params },
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/friend/request/index.ts b/apps/web-ele/src/api/im/manager/friend/request/index.ts
new file mode 100644
index 000000000..5cc8b4996
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/friend/request/index.ts
@@ -0,0 +1,30 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerFriendRequestApi {
+  /** 好友申请 */
+  export interface FriendRequest {
+    id: number;
+    fromUserId: number;
+    fromNickname?: string;
+    toUserId: number;
+    toNickname?: string;
+    applyContent?: string;
+    displayName?: string;
+    addSource?: number;
+    handleResult: number;
+    handleContent?: string;
+    handleTime?: Date;
+    createTime: Date;
+  }
+}
+
+
+/** 获得好友申请分页 */
+export function getManagerFriendRequestPage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerFriendRequestApi.FriendRequest>>(
+    '/im/manager/friend-request/page',
+    { params },
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/group/index.ts b/apps/web-ele/src/api/im/manager/group/index.ts
new file mode 100644
index 000000000..7d51ade22
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/group/index.ts
@@ -0,0 +1,87 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerGroupApi {
+  /** 群 */
+  export interface Group {
+    id: number;
+    name: string;
+    avatar?: string;
+    notice?: string;
+    ownerUserId: number;
+    ownerNickname?: string;
+    memberCount?: number;
+    status: number;
+    banned: boolean;
+    mutedAll?: boolean; // 是否全群禁言
+    bannedReason?: string;
+    bannedTime?: Date;
+    dissolvedTime?: Date;
+    createTime: Date;
+  }
+
+  /** 群成员 */
+  export interface GroupMember {
+    userId: number;
+    nickname?: string;
+    avatar?: string;
+    displayUserName?: string;
+    groupRemark?: string;
+    silent?: boolean;
+    status: number;
+    role?: number; // 成员角色，参见 ImGroupMemberRole 枚举
+    joinTime?: Date;
+    quitTime?: Date;
+    muteEndTime?: Date; // 禁言到期时间
+  }
+
+  /** 群封禁请求 */
+  export interface GroupBanReqVO {
+    id: number;
+    reason: string;
+  }
+}
+
+
+/** 获得群分页 */
+export function getManagerGroupPage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerGroupApi.Group>>(
+    '/im/manager/group/page',
+    { params },
+  );
+}
+
+/** 获得群详情 */
+export function getManagerGroup(id: number) {
+  return requestClient.get<ImManagerGroupApi.Group>('/im/manager/group/get', {
+    params: { id },
+  });
+}
+
+/** 封禁群 */
+export function banManagerGroup(data: ImManagerGroupApi.GroupBanReqVO) {
+  return requestClient.put<boolean>('/im/manager/group/ban', data);
+}
+
+/** 解封群 */
+export function unbanManagerGroup(id: number) {
+  return requestClient.put<boolean>('/im/manager/group/unban', undefined, {
+    params: { id },
+  });
+}
+
+/** 解散群 */
+export function dissolveManagerGroup(id: number) {
+  return requestClient.delete<boolean>('/im/manager/group/dissolve', {
+    params: { id },
+  });
+}
+
+/** 获得群成员列表（含已退群成员，由前端按需过滤） */
+export function getManagerGroupMemberList(groupId: number) {
+  return requestClient.get<ImManagerGroupApi.GroupMember[]>(
+    '/im/manager/group/member/list',
+    { params: { groupId } },
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/group/request/index.ts b/apps/web-ele/src/api/im/manager/group/request/index.ts
new file mode 100644
index 000000000..8a6de7e20
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/group/request/index.ts
@@ -0,0 +1,33 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerGroupRequestApi {
+  /** 加群申请 */
+  export interface GroupRequest {
+    id: number;
+    groupId: number;
+    groupName?: string;
+    userId: number;
+    userNickname?: string;
+    inviterUserId?: number;
+    inviterNickname?: string;
+    applyContent?: string;
+    addSource?: number;
+    handleResult: number;
+    handleUserId?: number;
+    handleNickname?: string;
+    handleContent?: string;
+    handleTime?: Date;
+    createTime: Date;
+  }
+}
+
+
+/** 获得加群申请分页 */
+export function getManagerGroupRequestPage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerGroupRequestApi.GroupRequest>>(
+    '/im/manager/group-request/page',
+    { params },
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/message/group/index.ts b/apps/web-ele/src/api/im/manager/message/group/index.ts
new file mode 100644
index 000000000..3385ae046
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/message/group/index.ts
@@ -0,0 +1,40 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerGroupMessageApi {
+  /** 群聊消息 */
+  export interface GroupMessage {
+    id: number;
+    clientMessageId?: string;
+    groupId: number;
+    groupName?: string;
+    senderId: number;
+    senderNickname?: string;
+    type: number;
+    content: string;
+    status: number;
+    atUserIds?: number[];
+    atUserNicknames?: (null | string)[];
+    receiptStatus: number;
+    sendTime: Date;
+    createTime: Date;
+  }
+}
+
+
+/** 获得群聊消息分页 */
+export function getManagerGroupMessagePage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerGroupMessageApi.GroupMessage>>(
+    '/im/manager/message/group/page',
+    { params },
+  );
+}
+
+/** 获得群聊消息详情 */
+export function getManagerGroupMessage(id: number) {
+  return requestClient.get<ImManagerGroupMessageApi.GroupMessage>(
+    '/im/manager/message/group/get',
+    { params: { id } },
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/message/private/index.ts b/apps/web-ele/src/api/im/manager/message/private/index.ts
new file mode 100644
index 000000000..f9ff6ca12
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/message/private/index.ts
@@ -0,0 +1,38 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerPrivateMessageApi {
+  /** 私聊消息 */
+  export interface PrivateMessage {
+    id: number;
+    clientMessageId?: string;
+    senderId: number;
+    senderNickname?: string;
+    receiverId: number;
+    receiverNickname?: string;
+    type: number;
+    content: string;
+    status: number;
+    receiptStatus?: number;
+    sendTime: Date;
+    createTime: Date;
+  }
+}
+
+
+/** 获得私聊消息分页 */
+export function getManagerPrivateMessagePage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerPrivateMessageApi.PrivateMessage>>(
+    '/im/manager/message/private/page',
+    { params },
+  );
+}
+
+/** 获得私聊消息详情 */
+export function getManagerPrivateMessage(id: number) {
+  return requestClient.get<ImManagerPrivateMessageApi.PrivateMessage>(
+    '/im/manager/message/private/get',
+    { params: { id } },
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/rtc/index.ts b/apps/web-ele/src/api/im/manager/rtc/index.ts
new file mode 100644
index 000000000..76b9d3c73
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/rtc/index.ts
@@ -0,0 +1,53 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerRtcApi {
+  /** RTC 通话 */
+  export interface RtcCall {
+    id: number;
+    room: string;
+    conversationType: number;
+    mediaType: number;
+    inviterUserId: number;
+    inviterNickname?: string;
+    groupId?: number;
+    groupName?: string;
+    status: number;
+    endReason?: number;
+    startTime: Date;
+    acceptTime?: Date;
+    endTime?: Date;
+    createTime: Date;
+  }
+
+  /** RTC 通话参与者 */
+  export interface RtcParticipant {
+    id: number;
+    callId: number;
+    userId: number;
+    userNickname?: string;
+    role: number;
+    status: number;
+    inviteTime: Date;
+    acceptTime?: Date;
+    leaveTime?: Date;
+  }
+}
+
+
+/** 获得通话记录分页 */
+export function getManagerRtcCallPage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerRtcApi.RtcCall>>(
+    '/im/manager/rtc/page',
+    { params },
+  );
+}
+
+/** 获得通话参与者列表 */
+export function getManagerRtcCallParticipantList(id: number) {
+  return requestClient.get<ImManagerRtcApi.RtcParticipant[]>(
+    '/im/manager/rtc/participant-list',
+    { params: { id } },
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/sensitiveword/index.ts b/apps/web-ele/src/api/im/manager/sensitiveword/index.ts
new file mode 100644
index 000000000..5f84b8df5
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/sensitiveword/index.ts
@@ -0,0 +1,60 @@
+import type { PageParam, PageResult } from '@vben/request';
+
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerSensitiveWordApi {
+  /** 敏感词 */
+  export interface SensitiveWord {
+    id: number;
+    word: string;
+    status: number;
+    creator?: string;
+    creatorName?: string;
+    createTime?: Date;
+  }
+}
+
+
+/** 获得敏感词分页 */
+export function getManagerSensitiveWordPage(params: PageParam) {
+  return requestClient.get<PageResult<ImManagerSensitiveWordApi.SensitiveWord>>(
+    '/im/manager/sensitive-word/page',
+    { params },
+  );
+}
+
+/** 获得敏感词详情 */
+export function getManagerSensitiveWord(id: number) {
+  return requestClient.get<ImManagerSensitiveWordApi.SensitiveWord>(
+    '/im/manager/sensitive-word/get',
+    { params: { id } },
+  );
+}
+
+/** 新增敏感词 */
+export function createManagerSensitiveWord(data: ImManagerSensitiveWordApi.SensitiveWord) {
+  return requestClient.post<number>('/im/manager/sensitive-word/create', data);
+}
+
+/** 修改敏感词 */
+export function updateManagerSensitiveWord(data: ImManagerSensitiveWordApi.SensitiveWord) {
+  return requestClient.put<boolean>(
+    '/im/manager/sensitive-word/update',
+    data,
+  );
+}
+
+/** 删除敏感词 */
+export function deleteManagerSensitiveWord(id: number) {
+  return requestClient.delete<boolean>('/im/manager/sensitive-word/delete', {
+    params: { id },
+  });
+}
+
+/** 批量删除敏感词 */
+export function deleteManagerSensitiveWordList(ids: number[]) {
+  return requestClient.delete<boolean>(
+    '/im/manager/sensitive-word/delete-list',
+    { params: { ids: ids.join(',') } },
+  );
+}
diff --git a/apps/web-ele/src/api/im/manager/statistics/index.ts b/apps/web-ele/src/api/im/manager/statistics/index.ts
new file mode 100644
index 000000000..fb4a04053
--- /dev/null
+++ b/apps/web-ele/src/api/im/manager/statistics/index.ts
@@ -0,0 +1,88 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImManagerStatisticsApi {
+  /** 统计概览 */
+  export interface Overview {
+    totalUser: number;
+    newUserToday: number;
+    totalGroup: number;
+    newGroupToday: number;
+    activeUserDaily: number;
+    activeUserWeekly: number;
+    activeUserMonthly: number;
+    privateMessageToday: number;
+    groupMessageToday: number;
+    privateMessageYesterday: number;
+    groupMessageYesterday: number;
+  }
+
+  /** 趋势数据 */
+  export interface Trend {
+    dates: string[];
+    series: Record<string, number[]>;
+  }
+
+  /** 消息类型分布 */
+  export interface MessageType {
+    type: number; // 参见 ImContentTypeEnum 枚举类，由前端按 DICT_TYPE.IM_CONTENT_TYPE 翻译
+    value: number;
+  }
+
+  /** 群规模分布 */
+  export interface GroupSize {
+    range: string;
+    count: number;
+  }
+
+  /** 消息发送排行 */
+  export interface TopSender {
+    userId: number;
+    nickname: string;
+    messageCount: number;
+  }
+}
+
+
+/** 获得 KPI 概览 */
+export function getStatisticsOverview() {
+  return requestClient.get<ImManagerStatisticsApi.Overview>(
+    '/im/manager/statistics/overview',
+  );
+}
+
+/** 获得消息趋势（私聊 + 群聊双线） */
+export function getMessageTrend(days: number) {
+  return requestClient.get<ImManagerStatisticsApi.Trend>(
+    '/im/manager/statistics/message-trend',
+    { params: { days } },
+  );
+}
+
+/** 获得用户趋势（新增注册 + 日活双线） */
+export function getUserTrend(days: number) {
+  return requestClient.get<ImManagerStatisticsApi.Trend>(
+    '/im/manager/statistics/user-trend',
+    { params: { days } },
+  );
+}
+
+/** 获得内容类型分布（最近 30 天） */
+export function getMessageTypeDistribution() {
+  return requestClient.get<ImManagerStatisticsApi.MessageType[]>(
+    '/im/manager/statistics/message-type-distribution',
+  );
+}
+
+/** 获得群规模分布 */
+export function getGroupSizeDistribution() {
+  return requestClient.get<ImManagerStatisticsApi.GroupSize[]>(
+    '/im/manager/statistics/group-size-distribution',
+  );
+}
+
+/** 获得消息 TOP 发送者（最近 30 天） */
+export function getTopSenders() {
+  return requestClient.get<ImManagerStatisticsApi.TopSender[]>(
+    '/im/manager/statistics/top-senders',
+  );
+}
diff --git a/apps/web-ele/src/api/im/message/channel/index.ts b/apps/web-ele/src/api/im/message/channel/index.ts
new file mode 100644
index 000000000..c727d29c3
--- /dev/null
+++ b/apps/web-ele/src/api/im/message/channel/index.ts
@@ -0,0 +1,34 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImChannelMessageApi {
+  /** 频道消息 */
+  export interface ChannelMessageRespVO {
+    id: number;
+    clientMessageId?: string;
+    channelId: number;
+    materialId: number;
+    type: number;
+    content: string;
+    receiptStatus?: number;
+    sendTime: string;
+  }
+}
+
+
+/** 拉取当前用户应收的频道消息（离线增量）；按 minId 游标分页 */
+export function pullChannelMessages(
+  params: { minId: number; size?: number },
+  signal?: AbortSignal,
+) {
+  return requestClient.get<ImChannelMessageApi.ChannelMessageRespVO[]>(
+    '/im/channel/message/pull',
+    { params, signal },
+  );
+}
+
+/** 上报频道消息已读位置；切到频道会话或拉到新消息后调 */
+export function readChannelMessages(channelId: number, messageId: number) {
+  return requestClient.put<boolean>('/im/channel/message/read', undefined, {
+    params: { channelId, messageId },
+  });
+}
diff --git a/apps/web-ele/src/api/im/message/group/index.ts b/apps/web-ele/src/api/im/message/group/index.ts
new file mode 100644
index 000000000..3ea832f46
--- /dev/null
+++ b/apps/web-ele/src/api/im/message/group/index.ts
@@ -0,0 +1,92 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImGroupMessageApi {
+  /** 群聊消息 Response VO */
+  export interface GroupMessageRespVO {
+    id: number; // 消息编号
+    clientMessageId: string; // 客户端消息编号
+    senderId: number; // 发送人编号
+    groupId: number; // 群编号
+    type: number; // 内容类型
+    content: string; // 消息内容（JSON 格式）
+    status: number; // 消息状态
+    sendTime: string; // 发送时间
+    atUserIds?: number[]; // @ 目标用户编号列表
+    receiverUserIds?: number[]; // 定向接收用户编号列表
+    receiptStatus?: number; // 回执状态
+    readCount?: number; // 已读人数（回执消息、且发送人为当前用户时有值）
+  }
+
+  /** 群聊消息发送 Request VO */
+  export interface GroupMessageSendReqVO {
+    clientMessageId: string; // 客户端消息编号
+    groupId: number; // 群编号
+    type: number; // 内容类型
+    content: string; // 消息内容（JSON 格式）
+    atUserIds?: number[]; // @ 目标用户编号列表
+    receipt?: boolean; // 是否需要回执
+  }
+
+  /** 群聊历史消息列表 Request VO */
+  export interface GroupMessageListReqVO {
+    groupId: number | string; // 群编号
+    maxId?: number | string; // 起始消息编号（不含），为空则从最新消息开始
+    limit: number; // 拉取数量（1 ~ 200）
+  }
+}
+
+
+/** 发送群聊消息 */
+export function sendGroupMessage(data: ImGroupMessageApi.GroupMessageSendReqVO) {
+  return requestClient.post<ImGroupMessageApi.GroupMessageRespVO>(
+    '/im/message/group/send',
+    data,
+  );
+}
+
+/** 拉取群聊消息（增量） */
+export function pullGroupMessages(
+  params: { minId: number | string; size: number },
+  signal?: AbortSignal,
+) {
+  return requestClient.get<ImGroupMessageApi.GroupMessageRespVO[]>(
+    '/im/message/group/pull',
+    { params, signal },
+  );
+}
+
+/** 查询群聊历史消息 */
+export function getGroupMessageList(params: ImGroupMessageApi.GroupMessageListReqVO) {
+  return requestClient.get<ImGroupMessageApi.GroupMessageRespVO[]>(
+    '/im/message/group/list',
+    { params },
+  );
+}
+
+/** 标记群聊消息已读 */
+export function readGroupMessages(
+  groupId: number | string,
+  messageId: number | string,
+) {
+  return requestClient.put<boolean>('/im/message/group/read', undefined, {
+    params: { groupId, messageId },
+  });
+}
+
+/** 撤回群聊消息 */
+export function recallGroupMessage(id: number | string) {
+  return requestClient.delete<ImGroupMessageApi.GroupMessageRespVO>(
+    '/im/message/group/recall',
+    { params: { id } },
+  );
+}
+
+/** 获取群消息已读用户列表 */
+export function getGroupReadUsers(params: {
+  groupId: number | string;
+  messageId: number | string;
+}) {
+  return requestClient.get<number[]>('/im/message/group/get-read-user-ids', {
+    params,
+  });
+}
diff --git a/apps/web-ele/src/api/im/message/private/index.ts b/apps/web-ele/src/api/im/message/private/index.ts
new file mode 100644
index 000000000..9240c99ae
--- /dev/null
+++ b/apps/web-ele/src/api/im/message/private/index.ts
@@ -0,0 +1,89 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImPrivateMessageApi {
+  /** 私聊消息 Response VO */
+  export interface PrivateMessageRespVO {
+    id: number; // 消息编号
+    clientMessageId: string; // 客户端消息编号
+    senderId: number; // 发送人编号
+    receiverId: number; // 接收人编号
+    type: number; // 内容类型
+    content: string; // 消息内容（JSON 格式）
+    status: number; // 消息状态（正常 / 已撤回）
+    receiptStatus?: number; // 回执状态（不需要 / 待完成 / 已完成），对齐 ImMessageReceiptStatus
+    sendTime: string; // 发送时间
+  }
+
+  /** 私聊消息发送 Request VO */
+  export interface PrivateMessageSendReqVO {
+    clientMessageId: string; // 客户端消息编号
+    receiverId: number; // 接收人编号
+    type: number; // 内容类型
+    content: string; // 消息内容（JSON 格式）
+    receipt?: boolean; // 是否需要回执；不传后端默认 true（普通私聊用户消息）
+  }
+
+  /** 私聊历史消息列表 Request VO */
+  export interface PrivateMessageListReqVO {
+    receiverId: number | string; // 接收人编号（对方）
+    maxId?: number | string; // 起始消息编号（不含），为空则从最新消息开始
+    limit: number; // 拉取数量（1 ~ 200）
+  }
+}
+
+
+/** 发送私聊消息 */
+export function sendPrivateMessage(data: ImPrivateMessageApi.PrivateMessageSendReqVO) {
+  return requestClient.post<ImPrivateMessageApi.PrivateMessageRespVO>(
+    '/im/message/private/send',
+    data,
+  );
+}
+
+/** 拉取私聊消息（增量） */
+export function pullPrivateMessages(
+  params: { minId: number | string; size: number },
+  signal?: AbortSignal,
+) {
+  return requestClient.get<ImPrivateMessageApi.PrivateMessageRespVO[]>(
+    '/im/message/private/pull',
+    { params, signal },
+  );
+}
+
+/** 查询私聊历史消息 */
+export function getPrivateMessageList(params: ImPrivateMessageApi.PrivateMessageListReqVO) {
+  return requestClient.get<ImPrivateMessageApi.PrivateMessageRespVO[]>(
+    '/im/message/private/list',
+    { params },
+  );
+}
+
+/** 标记私聊消息已读 */
+export function readPrivateMessages(
+  receiverId: number | string,
+  messageId: number | string,
+) {
+  return requestClient.put<boolean>('/im/message/private/read', undefined, {
+    params: { receiverId, messageId },
+  });
+}
+
+/** 查询对方已读到我发的最大消息 id（多端 / 离线后用于补齐已读状态） */
+export function getPrivateMaxReadMessageId(
+  peerId: number | string,
+  signal?: AbortSignal,
+) {
+  return requestClient.get<null | number>(
+    '/im/message/private/max-read-message-id',
+    { params: { peerId }, signal },
+  );
+}
+
+/** 撤回私聊消息 */
+export function recallPrivateMessage(id: number | string) {
+  return requestClient.delete<ImPrivateMessageApi.PrivateMessageRespVO>(
+    '/im/message/private/recall',
+    { params: { id } },
+  );
+}
diff --git a/apps/web-ele/src/api/im/rtc/index.ts b/apps/web-ele/src/api/im/rtc/index.ts
new file mode 100644
index 000000000..801df2afb
--- /dev/null
+++ b/apps/web-ele/src/api/im/rtc/index.ts
@@ -0,0 +1,105 @@
+import { requestClient } from '#/api/request';
+
+export namespace ImRtcApi {
+  /** 创建新通话请求 VO */
+  export interface RtcCallCreateReqVO {
+    conversationType: number;
+    mediaType: number;
+    groupId?: number;
+    inviteeIds: number[]; // 被邀请的用户编号集合；私聊必传 1 个对端，群聊必传至少 1 人
+  }
+
+  /** 通话中追加邀请请求 VO；仅群通话可用 */
+  export interface RtcCallInviteReqVO {
+    room: string;
+    inviteeIds: number[];
+  }
+
+  /** 通话会话 VO；create / join / accept / refreshToken 共用 */
+  export interface RtcCallRespVO {
+    room: string; // 业务通话编号（同时作为 LiveKit 房间名）
+    livekitUrl: string;
+    token?: string; // ENDED 状态时为 null（无需 connect LiveKit）
+    conversationType: number;
+    mediaType: number;
+    status: number;
+    endReason?: number; // 结束原因；仅 status=ENDED 时有值
+    inviterId: number;
+    groupId?: number;
+    inviteeIds?: number[];
+    joinedUserIds?: number[];
+  }
+
+  /** 群活跃通话查询响应；不含 token */
+  export interface RtcGroupCallRespVO {
+    room: string;
+    groupId: number;
+    mediaType: number;
+    inviterId: number;
+    joinedUserIds?: number[];
+    inviteeIds?: number[];
+  }
+}
+
+
+/** 创建新通话；私聊或群聊根据 conversationType 区分 */
+export function createCall(data: ImRtcApi.RtcCallCreateReqVO) {
+  return requestClient.post<ImRtcApi.RtcCallRespVO>('/im/rtc/create', data);
+}
+
+/** 通话中追加邀请；仅群通话可用 */
+export function inviteCall(data: ImRtcApi.RtcCallInviteReqVO) {
+  return requestClient.post<boolean>('/im/rtc/invite', data);
+}
+
+/** 加入已有群通话；用于胶囊条「加入」按钮 */
+export function joinCall(room: string) {
+  return requestClient.post<ImRtcApi.RtcCallRespVO>('/im/rtc/join', undefined, {
+    params: { room },
+  });
+}
+
+/** 接听通话 */
+export function acceptCall(room: string) {
+  return requestClient.post<ImRtcApi.RtcCallRespVO>('/im/rtc/accept', undefined, {
+    params: { room },
+  });
+}
+
+/** 拒绝通话 */
+export function rejectCall(room: string) {
+  return requestClient.post<boolean>('/im/rtc/reject', undefined, {
+    params: { room },
+  });
+}
+
+/** 取消邀请；主叫接通前调用 */
+export function cancelCall(room: string) {
+  return requestClient.post<boolean>('/im/rtc/cancel', undefined, {
+    params: { room },
+  });
+}
+
+/** 离开通话；接通后调用 */
+export function leaveCall(room: string) {
+  return requestClient.post<boolean>('/im/rtc/leave', undefined, {
+    params: { room },
+  });
+}
+
+/** 振铃超时检查；RUNNING 端 timer 兜底，触发后端立即扫描该 room 的超时 INVITING（接口静默） */
+export function noAnswerCallCheck(room: string) {
+  return requestClient.post<boolean>(
+    '/im/rtc/no-answer-call-check',
+    undefined,
+    { params: { room } },
+  );
+}
+
+/** 查询当前进行中的通话；目前仅群聊场景（胶囊条），返回 null 表示无活跃通话 */
+export function getActiveCall(groupId: number) {
+  return requestClient.get<ImRtcApi.RtcGroupCallRespVO | null>(
+    '/im/rtc/get-active-call',
+    { params: { groupId } },
+  );
+}
diff --git a/apps/web-ele/src/api/system/user/index.ts b/apps/web-ele/src/api/system/user/index.ts
index c9f23a403..fa7c05167 100644
--- a/apps/web-ele/src/api/system/user/index.ts
+++ b/apps/web-ele/src/api/system/user/index.ts
@@ -9,16 +9,23 @@ export namespace SystemUserApi {
     username: string;
     nickname: string;
     deptId: number;
+    deptName?: string;
     postIds: string[];
     email: string;
     mobile: string;
     sex: number;
     avatar: string;
     loginIp: string;
+    loginDate?: Date;
     status: number;
     remark: string;
     createTime?: Date;
   }
+
+  /** 用户精简信息 */
+  export interface UserSimple extends User {
+    id: number;
+  }
 }
 
 /** 查询用户管理列表 */
@@ -34,6 +41,13 @@ export function getUser(id: number) {
   return requestClient.get<SystemUserApi.User>(`/system/user/get?id=${id}`);
 }
 
+/** 查询用户列表 */
+export function getUserList(ids: number[]) {
+  return requestClient.get<SystemUserApi.User[]>('/system/user/list', {
+    params: { ids: ids.join(',') },
+  });
+}
+
 /** 新增用户 */
 export function createUser(data: SystemUserApi.User) {
   return requestClient.post('/system/user/create', data);
@@ -86,3 +100,20 @@ export function updateUserStatus(id: number, status: number) {
 export function getSimpleUserList() {
   return requestClient.get<SystemUserApi.User[]>('/system/user/simple-list');
 }
+
+/** 按用户编号查询用户精简信息 */
+export function getSimpleUser(id: number | string) {
+  return requestClient.get<SystemUserApi.UserSimple>('/system/user/get-simple', {
+    params: { id },
+  });
+}
+
+/** 按昵称模糊搜索用户 */
+export function getSimpleUserListByNickname(nickname: string) {
+  return requestClient.get<SystemUserApi.UserSimple[]>(
+    '/system/user/list-by-nickname',
+    {
+      params: { nickname },
+    },
+  );
+}
diff --git a/apps/web-ele/src/assets/audio/im/message-tip.mp3 b/apps/web-ele/src/assets/audio/im/message-tip.mp3
new file mode 100644
index 000000000..5f317dcd4
Binary files /dev/null and b/apps/web-ele/src/assets/audio/im/message-tip.mp3 differ
diff --git a/apps/web-ele/src/components/dict-tag/dict-tag.vue b/apps/web-ele/src/components/dict-tag/dict-tag.vue
index b3f1b6b3f..c4e459131 100644
--- a/apps/web-ele/src/components/dict-tag/dict-tag.vue
+++ b/apps/web-ele/src/components/dict-tag/dict-tag.vue
@@ -12,13 +12,43 @@ interface DictTagProps {
   icon?: string; // 图标
 }
 
+type TagType = '' | 'danger' | 'info' | 'primary' | 'success' | 'warning';
+type TagProps = { type?: Exclude<TagType, ''> };
+
 const props = defineProps<DictTagProps>();
 
+/** 获取标签类型 */
+function getTagType(colorType?: string): TagType {
+  switch (colorType) {
+    case 'danger': {
+      return 'danger';
+    }
+    case 'default': {
+      return '';
+    }
+    case 'info': {
+      return 'info';
+    }
+    case 'primary': {
+      return 'primary';
+    }
+    case 'success': {
+      return 'success';
+    }
+    case 'warning': {
+      return 'warning';
+    }
+    default: {
+      return '';
+    }
+  }
+}
+
 /** 获取字典标签 */
 const dictTag = computed(() => {
-  const defaultDict = {
+  const defaultDict: { colorType: TagType; label: string } = {
     label: '',
-    colorType: 'primary',
+    colorType: '',
   };
   // 校验参数有效性
   if (!props.type || props.value === undefined || props.value === null) {
@@ -31,45 +61,20 @@ const dictTag = computed(() => {
     return defaultDict;
   }
 
-  // 处理颜色类型
-  let colorType = dict.colorType;
-  switch (colorType) {
-    case 'danger': {
-      colorType = 'danger';
-      break;
-    }
-    case 'info': {
-      colorType = 'info';
-      break;
-    }
-    case 'primary': {
-      colorType = 'primary';
-      break;
-    }
-    case 'success': {
-      colorType = 'success';
-      break;
-    }
-    case 'warning': {
-      colorType = 'warning';
-      break;
-    }
-    default: {
-      if (!colorType) {
-        colorType = 'primary';
-      }
-    }
-  }
-
   return {
     label: dict.label || '',
-    colorType,
+    colorType: getTagType(dict.colorType),
   };
 });
+
+/** 获取标签属性 */
+const tagProps = computed<TagProps>(() =>
+  dictTag.value.colorType ? { type: dictTag.value.colorType } : {},
+);
 </script>
 
 <template>
-  <ElTag v-if="dictTag.label" :type="dictTag.colorType as any">
+  <ElTag v-if="dictTag.label" v-bind="tagProps">
     {{ dictTag.label }}
   </ElTag>
 </template>
diff --git a/apps/web-ele/src/layouts/basic.vue b/apps/web-ele/src/layouts/basic.vue
index 5cdcec8a3..1a322ef23 100644
--- a/apps/web-ele/src/layouts/basic.vue
+++ b/apps/web-ele/src/layouts/basic.vue
@@ -13,6 +13,7 @@ import {
   AntdProfileOutlined,
   BookOpenText,
   CircleHelp,
+  IconifyIcon,
   SvgGithubIcon,
 } from '@vben/icons';
 import {
@@ -27,7 +28,7 @@ import { preferences, usePreferences } from '@vben/preferences';
 import { useAccessStore, useUserStore } from '@vben/stores';
 import { formatDateTime, openWindow } from '@vben/utils';
 
-import { ElMessage } from 'element-plus';
+import { ElMessage, ElTooltip } from 'element-plus';
 
 import {
   getUnreadNotifyMessageCount,
@@ -156,6 +157,12 @@ function handleNotificationOpen(open: boolean) {
   handleNotificationGetUnreadCount();
 }
 
+/** 打开 IM 聊天 */
+function handleOpenImHome() {
+  const { href } = router.resolve({ name: 'ImHome' });
+  window.open(href, '_blank');
+}
+
 // 租户列表
 const tenants = ref<SystemTenantApi.Tenant[]>([]);
 const tenantEnable = computed(
@@ -276,6 +283,17 @@ watch(
         />
       </div>
     </template>
+    <template #header-right-900>
+      <ElTooltip content="IM 聊天">
+        <button
+          class="hover:bg-accent hover:text-accent-foreground mr-1 inline-flex size-8 items-center justify-center rounded-md transition-colors"
+          type="button"
+          @click="handleOpenImHome"
+        >
+          <IconifyIcon class="size-4" icon="lucide:message-circle" />
+        </button>
+      </ElTooltip>
+    </template>
     <template #extra>
       <AuthenticationLoginExpiredModal
         v-model:open="accessStore.loginExpired"
diff --git a/apps/web-ele/src/router/routes/modules/im.ts b/apps/web-ele/src/router/routes/modules/im.ts
new file mode 100644
index 000000000..b2c0205e0
--- /dev/null
+++ b/apps/web-ele/src/router/routes/modules/im.ts
@@ -0,0 +1,43 @@
+import type { RouteRecordRaw } from 'vue-router';
+
+const routes: RouteRecordRaw[] = [
+  {
+    path: '/im/home',
+    name: 'ImHome',
+    component: () => import('#/views/im/home/index.vue'),
+    redirect: '/im/home/conversation',
+    meta: {
+      title: 'IM 即时通讯',
+      hideInMenu: true,
+      hideInTab: true,
+      keepAlive: true,
+      noBasicLayout: true,
+    },
+    children: [
+      {
+        path: 'conversation',
+        name: 'ImHomeConversation',
+        component: () => import('#/views/im/home/pages/conversation/index.vue'),
+        meta: {
+          title: '消息',
+          activePath: '/im/home/conversation',
+          hideInMenu: true,
+          hideInTab: true,
+        },
+      },
+      {
+        path: 'contact',
+        name: 'ImHomeContact',
+        component: () => import('#/views/im/home/pages/contact/index.vue'),
+        meta: {
+          title: '通讯录',
+          activePath: '/im/home/contact',
+          hideInMenu: true,
+          hideInTab: true,
+        },
+      },
+    ],
+  },
+];
+
+export default routes;
diff --git a/apps/web-ele/src/views/im/home/components/card/card-bubble.vue b/apps/web-ele/src/views/im/home/components/card/card-bubble.vue
new file mode 100644
index 000000000..0fb56daa5
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/card/card-bubble.vue
@@ -0,0 +1,68 @@
+<script lang="ts" setup>
+import { computed } from 'vue'
+
+import { isPrivateConversation } from '#/views/im/utils/constants'
+import {
+  type CardMessage,
+  type CardTarget,
+  getCardLabelInfo
+} from '#/views/im/utils/message'
+
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImCardBubble' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 名片数据；CardMessage（接收侧消息体）或 CardTarget（发送侧预览）共用结构 */
+    card: CardMessage | CardTarget
+    /** 是否显示 cursor: pointer；调用方负责绑 @click 监听 */
+    clickable?: boolean
+  }>(),
+  { clickable: false }
+)
+
+/** 是否用户名片：决定 UserAvatar 是否带 id 触发 UserInfoCard */
+const isUser = computed(() => isPrivateConversation(props.card.targetType))
+/** 名片标签信息 */
+const labelInfo = computed(() => getCardLabelInfo(props.card))
+</script>
+
+<template>
+  <!--
+    名片消息气泡 / 名片预览卡（240px）：用户名片 + 群名片通用
+    - 头像 + 名字 + 群成员数副标题（仅群名片）+ 底部分隔条「群名片 / 个人名片」
+    - 用户名片把 :id 传给 UserAvatar 让点击 avatar 弹 UserInfoCard；群名片不传 id
+    - 整卡 click 由调用方监听（@click），组件不内嵌业务逻辑
+  -->
+  <div
+    class="flex flex-col w-[240px] rounded-md overflow-hidden bg-[var(--ant-color-bg-container)] border border-solid border-[var(--im-border-color-lighter)]"
+    :class="{ 'cursor-pointer': clickable }"
+  >
+    <div class="flex gap-2.5 items-center px-3 py-2.5">
+      <UserAvatar
+        :id="isUser ? card.targetId : undefined"
+        :url="card.avatar"
+        :name="card.name"
+        :size="40"
+        :clickable="false"
+      />
+      <div class="flex flex-col flex-1 min-w-0">
+        <div class="text-sm font-medium truncate text-[var(--ant-color-text)]">
+          {{ card.name }}
+        </div>
+        <div
+          v-if="!isUser && card.memberCount"
+          class="text-12px truncate text-[var(--ant-color-text-placeholder)]"
+        >
+          {{ card.memberCount }} 人群聊
+        </div>
+      </div>
+    </div>
+    <div
+      class="px-3 py-1 text-12px border-t border-t-solid text-[var(--ant-color-text-placeholder)] border-[var(--im-border-color-lighter)] bg-[var(--ant-color-fill-tertiary)]"
+    >
+      {{ labelInfo.label }}
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/card/card-line-label.vue b/apps/web-ele/src/views/im/home/components/card/card-line-label.vue
new file mode 100644
index 000000000..61c83ad63
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/card/card-line-label.vue
@@ -0,0 +1,29 @@
+<script lang="ts" setup>
+import { computed } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { getCardLabelInfo } from '#/views/im/utils/message'
+
+defineOptions({ name: 'ImCardLineLabel' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 名片数据；只读 targetType / name 派生标签 + 显示，结构性类型兼容 CardMessage / 引用预览的 partial */
+    card: null | undefined | { name?: string; targetType?: number; }
+    iconSize?: number
+  }>(),
+  { iconSize: 14 }
+)
+
+/** 标签 + 图标按 targetType 二分；兜底「个人名片」避免 null 时 UI 空白 */
+const labelInfo = computed(() => getCardLabelInfo(props.card))
+</script>
+
+<template>
+  <!-- 名片单行 inline label：「[icon] 群名片 / 个人名片：xx」；列表摘要 / 引用预览 / 后台预览复用 -->
+  <span class="inline-flex gap-1.5 items-center">
+    <Icon :icon="labelInfo.icon" :size="iconSize" />
+    <span>{{ labelInfo.label }}：{{ card?.name || '' }}</span>
+  </span>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/card/index.ts b/apps/web-ele/src/views/im/home/components/card/index.ts
new file mode 100644
index 000000000..ac62b1b09
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/card/index.ts
@@ -0,0 +1,2 @@
+export { default as CardBubble } from './card-bubble.vue';
+export { default as CardLineLabel } from './card-line-label.vue';
diff --git a/apps/web-ele/src/views/im/home/components/context-menu.vue b/apps/web-ele/src/views/im/home/components/context-menu.vue
new file mode 100644
index 000000000..9806cc55d
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/context-menu.vue
@@ -0,0 +1,99 @@
+<script lang="ts" setup>
+import { computed } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { useImUiStore } from '../store/uiStore'
+
+defineOptions({ name: 'ImContextMenu' })
+
+const uiStore = useImUiStore()
+const contextMenu = computed(() => uiStore.contextMenu)
+
+/**
+ * 计算菜单实际渲染坐标：靠近视口右 / 下边缘时回弹，避免菜单被裁剪
+ *
+ * itemHeight / menuWidth 是和模板里 px-4 py-2 + text-13px / min-w-30 配套的实际尺寸；
+ * dividerHeight = 9px（my-1 上下各 4 + 1px border），仅非首项的 divided 计入；
+ * menuHeight 额外加 8 是外层 py-1 的上下 padding 之和（4px × 2）
+ */
+const adjustedPosition = computed(() => {
+  const items = contextMenu.value.items
+  const itemHeight = 34
+  const dividerCount = items.filter((it, i) => it.divided && i > 0).length
+  const menuHeight = items.length * itemHeight + dividerCount * 9 + 8
+  const menuWidth = 120
+  let x = contextMenu.value.position.x
+  let y = contextMenu.value.position.y
+  // SSR 兜底：window 不可用时直接返回原始坐标
+  if (typeof window !== 'undefined') {
+    if (y + menuHeight > window.innerHeight) {
+      y = window.innerHeight - menuHeight
+    }
+    if (x + menuWidth > window.innerWidth) {
+      x = window.innerWidth - menuWidth
+    }
+  }
+  // 视口很小 / 菜单项很多时上面减法会算出负值，把菜单顶 / 左边推到 0 兜底
+  return { x: Math.max(0, x), y: Math.max(0, y) }
+})
+
+type MenuItem = (typeof contextMenu.value.items)[number]
+
+/** 选中菜单项：disabled 项忽略；正常项调 onSelect 回调后关闭菜单 */
+function handleSelect(item: MenuItem) {
+  if (item.disabled) {
+    return
+  }
+  uiStore.contextMenu.onSelect?.(item)
+  uiStore.closeContextMenu()
+}
+
+/** 关闭菜单：点遮罩 / 在遮罩上再次右键都会触发 */
+function handleClose() {
+  uiStore.closeContextMenu()
+}
+</script>
+
+<template>
+  <!--
+    通用右键菜单
+    由 useImUiStore.openContextMenu(position, items, onSelect) 触发全局单例展示
+    调用方在 @contextmenu.prevent 事件里调 openContextMenu 即可，不需要自己挂组件
+  -->
+  <teleport to="body">
+    <div
+      v-if="contextMenu.show"
+      class="fixed inset-0 z-9999"
+      @click.stop="handleClose"
+      @contextmenu.prevent="handleClose"
+    >
+      <div
+        class="fixed min-w-30 py-1 bg-[var(--ant-color-bg-elevated)] rounded-md shadow-lg"
+        :style="{ left: `${adjustedPosition.x }px`, top: `${adjustedPosition.y }px` }"
+      >
+        <template v-for="(item, index) in contextMenu.items" :key="item.key">
+          <!-- divided 项上方插一条分割线（首项跳过，避免空白） -->
+          <div
+            v-if="item.divided && index > 0"
+            class="my-1 mx-2 h-[1px] bg-[var(--ant-color-border-secondary)]"
+          ></div>
+          <div
+            class="flex gap-2 items-center px-4 py-2 text-13px text-left cursor-pointer transition-colors hover:bg-[var(--ant-color-fill)]"
+            :class="[
+              item.disabled
+                ? '!text-[var(--ant-color-text-disabled)] cursor-not-allowed hover:!bg-transparent'
+                : item.danger
+                  ? 'text-[#f56c6c]'
+                  : 'text-[var(--ant-color-text)]'
+            ]"
+            @click.stop="handleSelect(item)"
+          >
+            <Icon v-if="item.icon" :icon="item.icon" :size="14" />
+            <span>{{ item.name }}</span>
+          </div>
+        </template>
+      </div>
+    </div>
+  </teleport>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/friend/friend-add-dialog.vue b/apps/web-ele/src/views/im/home/components/friend/friend-add-dialog.vue
new file mode 100644
index 000000000..0b1d57f74
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/friend/friend-add-dialog.vue
@@ -0,0 +1,289 @@
+<script lang="ts" setup>
+import type { SystemUserApi } from '#/api/system/user'
+
+import { computed, ref } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+import { useUserStore } from '@vben/stores'
+
+import { ElButton, ElDialog, ElInput, ElMessage } from 'element-plus'
+
+import { getSimpleUserListByNickname } from '#/api/system/user'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { ImFriendAddSource } from '../../../utils/constants'
+import { getGenderColor, getGenderIcon } from '../../../utils/user'
+import { useFriendStore } from '../../store/friendStore'
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImFriendAddDialog' })
+
+const visible = ref(false) // 弹窗是否可见
+const presetUser = ref<null | SystemUserApi.UserSimple>(null) // 预填目标用户：非 null 时跳过搜索步骤，直接进入申请表单（群成员加好友 / 名片加好友等场景）
+const addSource = ref<number>(ImFriendAddSource.SEARCH) // 添加来源；参见 ImFriendAddSourceEnum，默认 SEARCH
+const addSourceExtra = ref<string>('') // 来源附带信息：addSource=ImFriendAddSource.GROUP 时传群名，话术拼为「我是 XX 群的 YY」
+
+defineExpose({
+  /** 打开加好友弹窗：reset → 灌参 → visible=true；不传 opts 走搜索模式 */
+  open(opts?: { addSource?: number; addSourceExtra?: string; presetUser?: null | SystemUserApi.UserSimple; }) {
+    presetUser.value = opts?.presetUser ?? null
+    addSource.value = opts?.addSource ?? ImFriendAddSource.SEARCH
+    addSourceExtra.value = opts?.addSourceExtra ?? ''
+    resetAll()
+    visible.value = true
+  }
+})
+
+const friendStore = useFriendStore()
+const userStore = useUserStore()
+
+/** 当前登录用户编号；用 computed 包一层，切账号后随 wsCache 重取，避免顶层求值在 keep-alive 实例里持有旧 id */
+const currentUserId = computed(() => getCurrentUserId())
+
+/** 搜索结果过滤掉自己；用 v-if 而非 v-show，避免 DOM 占位 + 头像无效请求 */
+const visibleUsers = computed(() =>
+  users.value.filter((user) => user.id !== currentUserId.value)
+)
+const keyword = ref('') // 搜索关键字
+const users = ref<SystemUserApi.UserSimple[]>([]) // 搜索结果
+const searched = ref(false) // 是否已搜索
+const loading = ref(false) // 搜索加载中
+const step = ref<'apply' | 'search'>('search') // 当前步骤：search=搜索列表；apply=申请表单
+const targetUser = ref<null | SystemUserApi.UserSimple>(null) // 申请目标用户
+const applyContent = ref('') // 申请理由（默认填「我是 ${当前昵称}」，对齐微信交互）
+const displayName = ref('') // 对接收方的备注（仅自己可见）
+const submitting = ref(false) // 提交中
+
+/** 弹窗标题随步骤切换 */
+const dialogTitle = computed(() => (step.value === 'apply' ? '申请添加朋友' : '添加好友'))
+
+/** 是否预填模式（presetUser 不为空 → 跳过搜索，关闭即销毁，无「取消返回搜索」按钮） */
+const presetMode = computed(() => !!presetUser.value)
+
+function resetAll() {
+  keyword.value = ''
+  users.value = []
+  searched.value = false
+  // 预填模式：直接进申请表单，targetUser 取自 presetUser；申请理由按 addSource 区分话术
+  if (presetUser.value) {
+    targetUser.value = presetUser.value
+    applyContent.value = buildPresetApplyContent()
+    displayName.value = ''
+    step.value = 'apply'
+    return
+  }
+  // 非预填模式：默认进搜索步骤
+  step.value = 'search'
+  targetUser.value = null
+  applyContent.value = ''
+  displayName.value = ''
+}
+
+/** 预填模式下的申请理由话术：群聊「我是"XX 群"的 YY」；其它「我是 YY」 */
+function buildPresetApplyContent(): string {
+  const myNickname = userStore.userInfo?.nickname || ''
+  if (!myNickname) {
+    return ''
+  }
+  // 群聊场景拼带群名的话术；其它场景默认「我是 YY」
+  const groupExtra = addSource.value === ImFriendAddSource.GROUP ? addSourceExtra.value : ''
+  return groupExtra ? `我是"${groupExtra}"的${myNickname}` : `我是${myNickname}`
+}
+
+/** 按昵称搜索用户：空关键字直接清空结果 */
+async function handleSearch() {
+  searched.value = true
+  if (!keyword.value.trim()) {
+    users.value = []
+    return
+  }
+  loading.value = true
+  try {
+    users.value = (await getSimpleUserListByNickname(keyword.value.trim())) || []
+  } finally {
+    loading.value = false
+  }
+}
+
+/** 进入申请步骤：预填申请理由「我是 ${当前用户昵称}」（对齐微信交互） */
+function enterApply(user: SystemUserApi.UserSimple) {
+  targetUser.value = user
+  const myNickname = userStore.userInfo?.nickname || ''
+  applyContent.value = myNickname ? `我是${myNickname}` : ''
+  displayName.value = ''
+  step.value = 'apply'
+}
+
+/** 取消申请，回到搜索步骤 */
+function backToSearch() {
+  step.value = 'search'
+  targetUser.value = null
+}
+
+/** 提交好友申请：返回 requestId 走「等待验证」；返回 null 表示后端命中「单向好友静默重启」分支，已直接成为好友 */
+async function handleSubmitApply() {
+  if (!targetUser.value) {
+    return
+  }
+  // 预校验：不能加自己（搜索列表已过滤，这里兜底 presetUser / 名片入口等场景）
+  if (targetUser.value.id === currentUserId.value) {
+    ElMessage.warning('不能添加自己为好友')
+    return
+  }
+  submitting.value = true
+  try {
+    const requestId = await friendStore.applyFriendRequest({
+      toUserId: targetUser.value.id,
+      applyContent: applyContent.value.trim() || undefined,
+      displayName: displayName.value.trim() || undefined,
+      addSource: addSource.value
+    })
+    // silent 分支（已是单向好友被静默重启）：主动 fetchFriendInfo 入库，不依赖 WS FRIEND_ADD 推送，避免丢推时列表看不到
+    if (requestId === null) {
+      await friendStore.fetchFriendInfo(targetUser.value.id)
+    }
+    ElMessage.success(requestId ? '申请已发送，等待对方验证' : '已添加为好友')
+    visible.value = false
+  } catch {
+    // 业务错误（已是好友 / 被对方拉黑 / 用户被禁用 等）：全局拦截器已弹错误提示，本地关弹窗避免脏状态停留
+    visible.value = false
+  } finally {
+    submitting.value = false
+  }
+}
+</script>
+
+<template>
+  <!--
+    添加好友对话框（双层流程）
+    - 第一层 search：按昵称搜索用户列表
+    - 第二层 apply：选中用户后展开「申请添加朋友」表单（申请理由 + 备注）
+  -->
+  <ElDialog
+    v-model="visible"
+    :content="dialogTitle"
+    width="480px"
+    :close-on-click-modal="false"
+>
+    <!-- 第一层：搜索 + 用户列表 -->
+    <template v-if="step === 'search'">
+      <ElInput
+        v-model="keyword"
+        placeholder="输入昵称回车搜索（最多展示 20 条）"
+        clearable
+        @keyup.enter="handleSearch"
+      >
+        <template #suffix>
+          <Icon icon="ant-design:search-outlined" class="cursor-pointer" @click="handleSearch" />
+        </template>
+      </ElInput>
+
+      <div v-loading="loading" class="w-full">
+        <div class="h-[400px] mt-2.5">
+          <div
+            v-if="visibleUsers.length === 0"
+            class="py-10 text-13px text-center text-[var(--ant-color-text-disabled)]"
+          >
+            {{ searched ? '没有搜到用户' : '输入关键字后回车开始搜索' }}
+          </div>
+          <div
+            v-for="user in visibleUsers"
+            :key="user.id"
+            class="flex gap-3 items-center px-2 py-2.5 border-b border-b-solid border-[var(--ant-color-border-secondary)]"
+          >
+            <UserAvatar
+              :id="user.id"
+              :url="user.avatar"
+              :name="user.nickname"
+              :size="42"
+              :clickable="false"
+            />
+            <div class="flex-1 min-w-0 overflow-hidden">
+              <!-- 昵称 + 性别图标 -->
+              <div
+                class="flex items-center gap-1 text-sm font-semibold text-[var(--ant-color-text)]"
+              >
+                <span class="truncate">{{ user.nickname }}</span>
+                <Icon
+                  v-if="getGenderIcon(user.sex)"
+                  :icon="getGenderIcon(user.sex)"
+                  :size="14"
+                  :color="getGenderColor(user.sex)"
+                  class="flex-shrink-0"
+                />
+              </div>
+              <!-- 部门 -->
+              <div
+                v-if="user.deptName"
+                class="mt-0.5 text-xs truncate text-[var(--ant-color-text-secondary)]"
+              >
+                {{ user.deptName }}
+              </div>
+            </div>
+            <!-- 已是好友显示「已添加」；否则显示「添加」（点击进入 apply 步骤） -->
+            <ElButton
+              v-if="!friendStore.isActiveFriend(user.id)"
+              type="primary"
+              size="small"
+              @click="enterApply(user)"
+            >
+              添加
+            </ElButton>
+            <ElButton v-else size="small" disabled>已添加</ElButton>
+          </div>
+        </div>
+      </div>
+    </template>
+
+    <!-- 第二层：申请表单（对齐微信「申请添加朋友」） -->
+    <template v-if="step === 'apply' && targetUser">
+      <!-- 选中的用户卡片 -->
+      <div
+        class="flex gap-3 items-center px-2 py-3 mb-4 rounded-md bg-[var(--ant-color-fill-secondary)]"
+      >
+        <UserAvatar
+          :id="targetUser.id"
+          :url="targetUser.avatar"
+          :name="targetUser.nickname"
+          :size="42"
+          :clickable="false"
+        />
+        <div class="flex-1 min-w-0 overflow-hidden">
+          <div class="text-sm font-semibold text-[var(--ant-color-text)] truncate">
+            {{ targetUser.nickname }}
+          </div>
+          <div
+            v-if="targetUser.deptName"
+            class="mt-0.5 text-xs truncate text-[var(--ant-color-text-secondary)]"
+          >
+            {{ targetUser.deptName }}
+          </div>
+        </div>
+      </div>
+
+      <div class="text-13px text-[var(--ant-color-text-secondary)] mb-1.5">发送添加朋友申请</div>
+      <ElInput
+type="textarea"
+        v-model="applyContent"
+        :rows="3"
+        :maxlength="255"
+        show-count
+        placeholder="请填写申请理由"
+      />
+
+      <div class="text-13px text-[var(--ant-color-text-secondary)] mt-3 mb-1.5">备注</div>
+      <ElInput
+        v-model="displayName"
+        :maxlength="16"
+        placeholder="给对方起个备注（仅自己可见，可不填）"
+      />
+    </template>
+
+    <!-- 仅在 apply 步骤显示 footer 操作按钮（slot 必须是 el-dialog 直接子节点） -->
+    <template v-if="step === 'apply'" #footer>
+      <!-- 预填模式无搜索步骤，「取消」直接关闭弹窗 -->
+      <ElButton @click="presetMode ? (visible = false) : backToSearch()">取消</ElButton>
+      <ElButton type="primary" :loading="submitting" @click="handleSubmitApply"> 确定 </ElButton>
+    </template>
+  </ElDialog>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/friend/friend-item.vue b/apps/web-ele/src/views/im/home/components/friend/friend-item.vue
new file mode 100644
index 000000000..9feebabbc
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/friend/friend-item.vue
@@ -0,0 +1,79 @@
+<script lang="ts" setup>
+import type { FriendLite } from '../../types'
+
+import { useImUiStore } from '../../store/uiStore'
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImFriendItem' })
+
+const props = withDefaults(
+  defineProps<{
+    active?: boolean
+    friend: FriendLite
+    menu?: boolean // 是否启用右键菜单；在选择器弹窗里一般关闭
+  }>(),
+  {
+    active: false,
+    menu: true
+  }
+)
+
+const emit = defineEmits<{
+  chat: [friend: FriendLite]
+  click: [friend: FriendLite]
+  delete: [friend: FriendLite]
+}>()
+
+const uiStore = useImUiStore()
+
+/** 右键菜单：发送消息 / 删除好友 */
+function handleContextMenu(event: MouseEvent) {
+  if (!props.menu) {
+    return
+  }
+  uiStore.openContextMenu(
+    { x: event.clientX, y: event.clientY },
+    [
+      { key: 'chat', name: '发送消息' },
+      { key: 'delete', name: '删除好友' }
+    ],
+    (item) => {
+      if (item.key === 'chat') emit('chat', props.friend)
+      else if (item.key === 'delete') emit('delete', props.friend)
+    }
+  )
+}
+</script>
+
+<template>
+  <!--
+    好友单行项
+    - 头像 + 昵称
+    - 选中态 active
+    - 右键菜单（发消息 / 删除好友）由全局 ContextMenu 承接
+  -->
+  <div
+    class="relative flex items-center gap-2.5 px-4 py-3 cursor-pointer transition-colors hover:bg-[var(--ant-color-fill)]"
+    :class="{ '!bg-[#d9ecff] dark:!bg-[var(--ant-color-primary-bg-hover)]': active }"
+    @click="$emit('click', friend)"
+    @contextmenu.prevent="handleContextMenu"
+  >
+    <!-- prefix slot：放在头像前，给选择类弹窗的 checkbox / 圆点用，不传则不渲染 -->
+    <slot name="prefix"></slot>
+    <!-- 头像 -->
+    <UserAvatar
+      :id="friend.id"
+      :url="friend.avatar"
+      :name="friend.nickname"
+      :size="42"
+      :clickable="false"
+    />
+    <!-- 单行展示 displayName 优先；昵称仅在好友详情面板展示，列表里不重复 -->
+    <div class="flex flex-1 min-w-0">
+      <div class="overflow-hidden text-sm truncate text-[var(--ant-color-text)]">
+        {{ friend.displayName || friend.nickname }}
+      </div>
+    </div>
+    <slot></slot>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/friend/index.ts b/apps/web-ele/src/views/im/home/components/friend/index.ts
new file mode 100644
index 000000000..443154c01
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/friend/index.ts
@@ -0,0 +1,2 @@
+export { default as FriendAddDialog } from './friend-add-dialog.vue';
+export { default as FriendItem } from './friend-item.vue';
diff --git a/apps/web-ele/src/views/im/home/components/group/group-admin-set-dialog.vue b/apps/web-ele/src/views/im/home/components/group/group-admin-set-dialog.vue
new file mode 100644
index 000000000..c34edcd5a
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-admin-set-dialog.vue
@@ -0,0 +1,122 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from './group-member.vue'
+
+import { ref } from 'vue'
+
+import { ElButton, ElDialog, ElMessage } from 'element-plus'
+
+import { addGroupAdmin, removeGroupAdmin } from '#/api/im/group'
+import { GROUP_ADMIN_MAX_COUNT } from '#/views/im/utils/config'
+
+import { GroupMemberPickerPanel } from '../picker'
+
+defineOptions({ name: 'ImGroupAdminSetDialog' })
+
+const emit = defineEmits<{
+  /** 管理员变更成功；父侧通常用来 reload 群数据 */
+  reload: []
+}>()
+
+const visible = ref(false)
+const submitting = ref(false)
+const groupId = ref(0)
+const members = ref<GroupMemberLite[]>([])
+const currentAdminIds = ref<number[]>([]) // 当前管理员 userId 列表：默认勾选 + 提交时 diff
+const hideIds = ref<number[]>([])
+const maxSize = ref(GROUP_ADMIN_MAX_COUNT)
+const selectedIds = ref<number[]>([])
+
+defineExpose({
+  /** 打开设置管理员弹窗：reset → 灌参 → visible=true */
+  open(opts: {
+    /** 当前管理员 userId 列表（默认勾选） */
+    currentAdminIds: number[]
+    groupId: number
+    /** 隐藏 userId（群主） */
+    hideIds?: number[]
+    /** 已选数上限；不传走 GROUP_ADMIN_MAX_COUNT */
+    maxSize?: number
+    members: GroupMemberLite[]
+  }) {
+    groupId.value = opts.groupId
+    members.value = opts.members
+    currentAdminIds.value = [...opts.currentAdminIds]
+    hideIds.value = opts.hideIds ? [...opts.hideIds] : []
+    maxSize.value = opts.maxSize ?? GROUP_ADMIN_MAX_COUNT
+    selectedIds.value = [...opts.currentAdminIds]
+    submitting.value = false
+    visible.value = true
+  }
+})
+
+/** 跟当前管理员列表做差集，分别拿到要新增 / 撤销的 userId */
+async function handleOk() {
+  if (!groupId.value) {
+    return
+  }
+  const previousIds = currentAdminIds.value
+  const previousIdSet = new Set(previousIds)
+  const nextIds = selectedIds.value
+  const nextIdSet = new Set(nextIds)
+  const addedIds = nextIds.filter((id) => !previousIdSet.has(id))
+  const removedIds = previousIds.filter((id) => !nextIdSet.has(id))
+  if (addedIds.length === 0 && removedIds.length === 0) {
+    visible.value = false
+    return
+  }
+  submitting.value = true
+  try {
+    if (addedIds.length > 0) {
+      await addGroupAdmin({ id: groupId.value, userIds: addedIds })
+    }
+    if (removedIds.length > 0) {
+      await removeGroupAdmin({ id: groupId.value, userIds: removedIds })
+    }
+    ElMessage.success(`已更新群管理员（新增 ${addedIds.length} 位，撤销 ${removedIds.length} 位）`)
+    emit('reload')
+    visible.value = false
+  } finally {
+    submitting.value = false
+  }
+}
+</script>
+
+<template>
+  <!--
+    设置群管理员：一个弹窗合并增 / 删，提交时跟当前管理员列表 diff
+    - dialog 壳本组件持有；选择 UI 委托 GroupMemberPickerPanel（grid 形态对齐当前视觉）
+    - 群主从候选里隐藏（不能设为管理员）
+    - 对外接口：ref + open({ groupId, members, currentAdminIds, hideIds, maxSize }) + emit reload()
+  -->
+  <ElDialog
+    v-model="visible"
+    title="设置群管理员"
+    width="700px"
+    :close-on-click-modal="false"
+    class="im-picker-dialog"
+  >
+    <div class="h-[480px]">
+      <GroupMemberPickerPanel
+        v-model:selected-ids="selectedIds"
+        :members="members"
+        :hide-ids="hideIds"
+        :max-size="maxSize"
+        selected-display="grid"
+      />
+    </div>
+
+    <template #footer>
+      <ElButton @click="visible = false">取消</ElButton>
+      <ElButton type="primary" :loading="submitting" @click="handleOk">确定</ElButton>
+    </template>
+  </ElDialog>
+</template>
+
+<style scoped lang="scss">
+@use '../picker/picker-dialog' as picker;
+
+/* :deep 穿透 el-dialog 内部类；复用 picker 公共 mixin */
+.im-picker-dialog {
+  @include picker.styles;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-avatar.vue b/apps/web-ele/src/views/im/home/components/group/group-avatar.vue
new file mode 100644
index 000000000..021714f65
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-avatar.vue
@@ -0,0 +1,131 @@
+<script lang="ts" setup>
+import type { GroupMember } from '../../types'
+
+import { computed, ref, watch } from 'vue'
+
+import {
+  buildGroupAvatar,
+  getCachedGroupAvatar,
+  setCachedGroupAvatar
+} from '../../../utils/group'
+import { getMemberDisplayName } from '../../../utils/user'
+import { useFriendStore } from '../../store/friendStore'
+import { useGroupStore } from '../../store/groupStore'
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImGroupAvatar' })
+
+const props = withDefaults(
+  defineProps<{
+    clickable?: boolean // 是否可点击（默认 false，列表里仅展示）
+    groupId: number // 群编号；用于查 store 拿成员头像
+    name?: string // 群名；色卡兜底文字
+    previewable?: boolean // 是否点头像直接放大预览（群详情大头像位用）
+    previewZIndex?: number // 预览层 z-index
+    radius?: string // 圆角，CSS 长度
+    size?: number // 尺寸（px），正方形
+    url?: string // 服务端已设置的群头像 URL；非空则直接用，不拼图
+  }>(),
+  {
+    clickable: false,
+    name: '',
+    previewable: false,
+    previewZIndex: 2000,
+    radius: '15%',
+    size: 42,
+    url: ''
+  }
+)
+
+const friendStore = useFriendStore()
+const groupStore = useGroupStore()
+const mergedUrl = ref('')
+// 竞态保护：丢弃过期 await 结果
+let mergeToken = 0
+
+/** 按容器 size × DPR 算 canvas 实际像素，避免 2x / 3x retina 屏拼图糊；DPR 封顶 3 防止超高分辨率画布过大 */
+function getTargetSize(size: number): number {
+  const dpr = Math.min(window.devicePixelRatio || 1, 3)
+  return Math.max(Math.round(size * dpr), 64)
+}
+
+/** store 里整群成员是否「完整加载」过；只在为 true 时才拼图，避免列表场景批量发接口 */
+const loadedMembers = computed<GroupMember[] | null>(() => {
+  const g = groupStore.getGroup(props.groupId)
+  if (!g?.membersLoaded || !g.members) {
+    return null
+  }
+  return g.members
+})
+
+/** 前 9 个成员的拼图入参；name 走 getMemberDisplayName 口径（好友备注 > 群昵称 > 真实昵称） */
+const memberItems = computed(() => {
+  const members = loadedMembers.value
+  if (!members) {
+    return []
+  }
+  return members.slice(0, 9).map((m) => ({
+    avatar: m.avatar || '',
+    name: getMemberDisplayName(m, friendStore.getFriend(m.userId))
+  }))
+})
+
+/** 成员快照签名：拼 (avatar, name) 字段，原地修改任一字段都会让 watch 重算 */
+const memberSignature = computed(() =>
+  memberItems.value.map((it) => `${it.avatar}#${it.name}`).join('|')
+)
+
+/** 走 buildGroupAvatar 拼图并写回 mergedUrl；mergeToken 校验避免老 await 覆盖新结果 */
+async function applyMerge(key: string, targetSize: number): Promise<void> {
+  const myToken = ++mergeToken
+  const cached = getCachedGroupAvatar(key)
+  if (cached) {
+    mergedUrl.value = cached
+    return
+  }
+  const dataUrl = await buildGroupAvatar(memberItems.value, { targetSize })
+  if (myToken !== mergeToken) {
+    return
+  }
+  if (dataUrl) {
+    setCachedGroupAvatar(key, dataUrl)
+  }
+  mergedUrl.value = dataUrl
+}
+
+watch(
+  () => [props.url, props.groupId, props.size, memberSignature.value] as const,
+  ([url, groupId, size, signature]) => {
+    if (url) {
+      mergedUrl.value = ''
+      return
+    }
+    if (!signature) {
+      mergeToken++
+      mergedUrl.value = ''
+      groupStore.loadGroupMemberList(groupId)
+      return
+    }
+    const targetSize = getTargetSize(size)
+    const key = `${groupId}:${targetSize}:${signature}`
+    applyMerge(key, targetSize)
+  },
+  { immediate: true }
+)
+
+/** 最终展示 url：服务端 url 优先 → 拼图 → 空字符串（让 UserAvatar 走色卡） */
+const finalUrl = computed(() => props.url || mergedUrl.value)
+</script>
+
+<template>
+  <!-- url 非空走原图；url 空时取前 9 个成员头像拼九宫格 dataURL，成员未在 store 缓存时走色卡兜底 -->
+  <UserAvatar
+    :url="finalUrl"
+    :name="name"
+    :size="size"
+    :radius="radius"
+    :clickable="clickable"
+    :previewable="previewable"
+    :preview-z-index="previewZIndex"
+  />
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-create-dialog.vue b/apps/web-ele/src/views/im/home/components/group/group-create-dialog.vue
new file mode 100644
index 000000000..0f082f9b5
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-create-dialog.vue
@@ -0,0 +1,144 @@
+<script lang="ts" setup>
+import type { FriendLite } from '../../types'
+
+import { computed, ref } from 'vue'
+
+import { ElButton, ElDialog, ElMessage } from 'element-plus'
+
+import { createGroup } from '#/api/im/group'
+
+import { buildDefaultGroupName } from '../../../utils/group'
+import { useFriendStore } from '../../store/friendStore'
+import { useGroupStore } from '../../store/groupStore'
+import { FriendPickerPanel } from '../picker'
+
+defineOptions({ name: 'ImGroupCreateDialog' })
+
+const emit = defineEmits<{
+  /** 创建成功，携带新群编号；父侧通常用来跳转到新群会话 */
+  created: [groupId: number]
+}>()
+
+const friendStore = useFriendStore()
+const groupStore = useGroupStore()
+
+const visible = ref(false)
+const submitting = ref(false)
+const lockedIds = ref<number[]>([])
+const selectedIds = ref<number[]>([])
+
+defineExpose({
+  /** 打开发起群聊弹窗：reset → 灌参 → visible=true */
+  open(opts?: { lockedIds?: number[] }) {
+    lockedIds.value = opts?.lockedIds ? [...opts.lockedIds] : []
+    selectedIds.value = []
+    submitting.value = false
+    visible.value = true
+  }
+})
+
+/** 全量好友：直接复用 friendStore Lite 视图（带拼音字段供分桶用） */
+const friends = computed<FriendLite[]>(() => friendStore.getActiveFriendLiteList)
+
+/** 完成按钮可点：至少有 1 个非 locked 勾选（locked 是入口锁定项，不算"用户主动选择"） */
+const canSubmit = computed(() => selectedIds.value.length > 0)
+
+/** 拿到所有要进群的好友（locked + selected）；建群默认群名按这批人生成 */
+function resolveMembersToInvite(): FriendLite[] {
+  const seen = new Set<number>()
+  const result: FriendLite[] = []
+  const byId = new Map(friends.value.map((f) => [f.id, f]))
+  for (const id of lockedIds.value) {
+    if (seen.has(id)) {
+      continue
+    }
+    const friend = byId.get(id)
+    if (friend) {
+      seen.add(id)
+      result.push(friend)
+    }
+  }
+  for (const id of selectedIds.value) {
+    if (seen.has(id)) {
+      continue
+    }
+    const friend = byId.get(id)
+    if (friend) {
+      seen.add(id)
+      result.push(friend)
+    }
+  }
+  return result
+}
+
+/** 创建群聊：建群（同时邀请初始成员）→ upsert groupStore → emit created 让父页跳转新会话 */
+async function handleOk() {
+  const members = resolveMembersToInvite()
+  if (members.length === 0) {
+    return
+  }
+  submitting.value = true
+  try {
+    const memberUserIds = members.map((m) => m.id)
+    const name = buildDefaultGroupName(members)
+    const group = await createGroup({ name, memberUserIds, joinApproval: false })
+    if (!group?.id) {
+      throw new Error('创建群失败：未返回群编号')
+    }
+    // 直接 upsert 进 groupStore，省一次 fetchGroupList —— 服务端返回 VO 已经够建会话了
+    groupStore.upsertGroup({
+      id: group.id,
+      name: group.name,
+      avatar: group.avatar,
+      notice: group.notice,
+      ownerUserId: group.ownerUserId
+    })
+    ElMessage.success('群聊创建成功')
+    emit('created', group.id)
+    visible.value = false
+  } finally {
+    submitting.value = false
+  }
+}
+</script>
+
+<template>
+  <!--
+    发起群聊：选好友 → 默认按所选成员名生成群名 → createGroup
+    - dialog 壳本组件持有；选择 UI 委托 FriendPickerPanel
+    - lockedIds 由调用方通过 open({ lockedIds }) 传入；私聊侧 +建群锁定对方
+    - 不再要求先输入群名 / 不再展示「进群审批」开关，对齐微信 PC
+    - 对外接口：ref + open({ lockedIds }) + emit created(groupId)
+  -->
+  <ElDialog
+    v-model="visible"
+    title="发起群聊"
+    width="720px"
+    :close-on-click-modal="false"
+    class="im-picker-dialog"
+  >
+    <div class="h-[480px]">
+      <FriendPickerPanel
+        v-model:selected-ids="selectedIds"
+        :friends="friends"
+        :locked-ids="lockedIds"
+      />
+    </div>
+
+    <template #footer>
+      <ElButton @click="visible = false">取消</ElButton>
+      <ElButton type="primary" :loading="submitting" :disabled="!canSubmit" @click="handleOk">
+        完成
+      </ElButton>
+    </template>
+  </ElDialog>
+</template>
+
+<style scoped lang="scss">
+@use '../picker/picker-dialog' as picker;
+
+/* :deep 穿透 el-dialog 内部类；复用 picker 公共 mixin */
+.im-picker-dialog {
+  @include picker.styles;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-info-card.vue b/apps/web-ele/src/views/im/home/components/group/group-info-card.vue
new file mode 100644
index 000000000..c850bc76b
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-info-card.vue
@@ -0,0 +1,116 @@
+<script lang="ts" setup>
+import type { GroupLite } from '../../types'
+
+import { computed, onMounted, onUnmounted } from 'vue'
+import { useRouter } from 'vue-router'
+
+import { prompt } from '@vben/common-ui'
+
+import { ElInput, ElMessage } from 'element-plus'
+
+import { applyJoinGroup } from '#/api/im/group/request'
+
+import { ImConversationType, ImGroupAddSource } from '../../../utils/constants'
+import { getGroupDisplayName } from '../../../utils/user'
+import { useConversationStore } from '../../store/conversationStore'
+import { useGroupStore } from '../../store/groupStore'
+import { useImUiStore } from '../../store/uiStore'
+import GroupInfo from './group-info.vue'
+
+defineOptions({ name: 'ImGroupInfoCard' })
+
+const uiStore = useImUiStore()
+const conversationStore = useConversationStore()
+const groupStore = useGroupStore()
+const router = useRouter()
+
+const card = computed(() => uiStore.groupInfoCard)
+
+/** 关闭浮层 */
+function handleClose() {
+  uiStore.closeGroupInfoCard()
+}
+
+/** Esc 关闭 */
+function handleKeydown(e: KeyboardEvent) {
+  if (e.key === 'Escape' && card.value.show) {
+    handleClose()
+  }
+}
+
+onMounted(() => window.addEventListener('keydown', handleKeydown))
+onUnmounted(() => window.removeEventListener('keydown', handleKeydown))
+
+/** 进入群聊：取本地最新群信息（含 silent / 群备注），新建或激活会话 + 跳路由 */
+function handleChat(group: GroupLite) {
+  const cached = groupStore.getGroup(group.id)
+  // cached 命中走 getGroupDisplayName 让群备注优先（与 contact / 会话列表的展示名一致）；缺 cached 时回落 showGroupName / 原群名
+  const displayName = cached
+    ? getGroupDisplayName(cached)
+    : group.showGroupName || group.name || ''
+  // 打开或新建会话
+  conversationStore.openConversation(
+    group.id,
+    ImConversationType.GROUP,
+    displayName,
+    cached?.avatar || group.showImage || '',
+    { silent: !!cached?.silent }
+  )
+
+  // 如果不在会话页，先跳过去（如果在了，MessagePanel 会自己感知会话变化刷新）
+  if (router.currentRoute.value.name !== 'ImHomeConversation') {
+    router.push({ name: 'ImHomeConversation' })
+  }
+  handleClose()
+}
+
+/** 加入群聊：先关浮层（避免与 prompt 的 mask 互相遮挡）→ 弹申请理由（可选）→ applyJoinGroup */
+async function handleApply(group: GroupLite) {
+  handleClose()
+  let applyContent: string
+  try {
+    const result = await prompt<string>({
+      cancelText: '取消',
+      component: ElInput,
+      componentProps: {
+        clearable: true,
+        placeholder: '请填写验证消息（可选）'
+      },
+      content: '',
+      defaultValue: '',
+      confirmText: '发送申请',
+      modelPropName: 'value',
+      title: `申请加入「${group.name || ''}」`
+    })
+    applyContent = (result || '').trim()
+  } catch {
+    return
+  }
+  await applyJoinGroup({
+    groupId: group.id,
+    applyContent: applyContent || undefined,
+    addSource: ImGroupAddSource.SHARE_LINK
+  })
+  ElMessage.success('加群申请已发送')
+}
+</script>
+
+<template>
+  <!--
+    群信息浮层（与 UserInfoCard 对位）
+    - 仅承担「浮层定位 + 关闭逻辑（点遮罩 / Esc）」，群信息视觉走 <GroupInfo>，与通讯录详情共用一份组件
+    - 触发：useImUiStore.openGroupInfoCardAtEvent(group, e)
+    - GroupInfo 内部按 groupStore 缓存推导 member / stranger，浮层只负责接 chat / apply 事件做业务
+  -->
+  <teleport to="body">
+    <div v-if="card.show" class="fixed inset-0 z-9998" @click.self="handleClose">
+      <div
+        class="fixed w-80 p-4 bg-[var(--ant-color-bg-elevated)] rounded-md shadow-xl"
+        :style="{ left: `${card.position.x }px`, top: `${card.position.y }px` }"
+        @click.stop
+      >
+        <GroupInfo v-if="card.group" :group="card.group" @chat="handleChat" @apply="handleApply" />
+      </div>
+    </div>
+  </teleport>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-info.vue b/apps/web-ele/src/views/im/home/components/group/group-info.vue
new file mode 100644
index 000000000..0a28c937c
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-info.vue
@@ -0,0 +1,154 @@
+<script lang="ts" setup>
+import type { Friend, GroupLite, GroupMember } from '../../types'
+import type { GroupMemberLite } from './group-member.vue'
+
+import { computed, ref, watch } from 'vue'
+
+import { CommonStatusEnum } from '@vben/constants'
+
+import { ElButton } from 'element-plus'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { getMemberDisplayName, isGroupQuit } from '../../../utils/user'
+import { useFriendStore } from '../../store/friendStore'
+import { useGroupStore } from '../../store/groupStore'
+import GroupAvatar from './group-avatar.vue'
+import GroupMemberGrid from './group-member-grid.vue'
+
+defineOptions({ name: 'ImGroupInfo' })
+
+const props = defineProps<{
+  group: GroupLite
+}>()
+
+const emit = defineEmits<{
+  /** stranger 点「加入群聊」；父级负责弹申请理由 + 调 applyJoinGroup */
+  apply: [group: GroupLite]
+  /** member 点「进入群聊」；父级负责切会话 + 关浮层 */
+  chat: [group: GroupLite]
+}>()
+
+const groupStore = useGroupStore()
+const friendStore = useFriendStore()
+
+const members = ref<GroupMemberLite[]>([])
+
+/**
+ * 是否已加群：基于"自己确实在成员列表里"判断
+ * - 缓存未命中：直接 false（陌生群）
+ * - 命中且 members 已拉：精准查 self.userId 在不在
+ * - 命中但 members 未拉：fetchGroupList 接口语义即「我加入的群」，命中视为 member（拉成员后会自动收敛）
+ */
+const isMember = computed(() => {
+  if (!props.group?.id) {
+    return false
+  }
+  const cached = groupStore.getGroup(props.group.id)
+  if (!cached) {
+    return false
+  }
+  // 历史退群群：直接判 false，避免成员未加载时误显示「进入群聊」
+  if (isGroupQuit(cached)) {
+    return false
+  }
+  if (cached.membersLoaded && cached.members) {
+    const myId = getCurrentUserId()
+    return cached.members.some((m) => m.userId === myId && m.status === CommonStatusEnum.ENABLE)
+  }
+  return true
+})
+/** 历史退群群：只读，动作区两个按钮都不渲染（既不「进入群聊」也不「加入群聊」） */
+const isQuitGroup = computed(() => {
+  const id = props.group?.id
+  return id != null && isGroupQuit(groupStore.getGroup(id))
+})
+/** 是否未加群：有 id、非成员、且非历史退群群；只有真·陌生人才给「加入群聊」 */
+const isStranger = computed(() => !!props.group?.id && !isMember.value && !isQuitGroup.value)
+
+/** 成员数文案：member 优先用本地拉到的列表长度，stranger 用 props.group.memberCount 卡片快照 */
+const memberCountText = computed(() => {
+  const count = isMember.value
+    ? props.group.memberCount || members.value.length
+    : props.group.memberCount
+  return count ? `${count} 位成员` : ''
+})
+
+/** member 切群 / 首挂：拉成员；竞态用 group.id 比对丢弃陈旧响应避免上一条群成员错位 */
+watch(
+  () => [props.group?.id, isMember.value] as const,
+  async ([id, member]) => {
+    members.value = []
+    if (!id || !member) {
+      return
+    }
+    const list = await groupStore.fetchGroupMemberList(id, true)
+    if (props.group?.id !== id) {
+      return
+    }
+    members.value = list.map((m) => convertGroupMemberLite(m, friendStore.getFriend(m.userId)))
+  },
+  { immediate: true }
+)
+
+/** 群成员 → 列表项 */
+function convertGroupMemberLite(member: GroupMember, friend: Friend | undefined): GroupMemberLite {
+  return {
+    userId: member.userId,
+    showName: getMemberDisplayName(member, friend),
+    nickname: member.nickname,
+    avatar: member.avatar,
+    status: member.status,
+    role: member.role
+  }
+}
+</script>
+
+<template>
+  <!--
+    群信息内容组件（与 UserInfo 对位）
+    - 头像 + 群名 + 成员数 + 成员宫格 + 动作区，纯展示 + 抛事件，业务由父级承接
+    - relation 走 groupStore 缓存推导：命中 = member（已加群），否则 = stranger（未加群），无 id = readonly
+    - 成员宫格仅 member 时拉取（陌生群拉不到，所有信息走 props.group 卡片快照）
+  -->
+  <div class="flex justify-center">
+    <div class="w-full max-w-[320px] flex flex-col gap-3 items-center">
+      <GroupAvatar
+        :group-id="group.id"
+        :url="group.showImage || group.showImageThumb"
+        :name="group.showGroupName || group.name"
+        :size="72"
+        :previewable="isMember"
+      />
+      <div
+        class="w-full text-lg font-semibold leading-snug text-[var(--ant-color-text)] truncate text-center"
+      >
+        {{ group.showGroupName || group.name }}
+      </div>
+      <div v-if="memberCountText" class="text-13px text-[var(--ant-color-text-secondary)]">
+        {{ memberCountText }}
+      </div>
+
+      <!-- 成员宫格：仅 member 渲染（陌生群拉不到成员） -->
+      <div
+        v-if="isMember && members.length > 0"
+        class="flex flex-wrap gap-2 justify-center w-full pt-2"
+      >
+        <GroupMemberGrid
+          v-for="member in members"
+          :key="member.userId"
+          :member="member"
+          :group-name="group.name"
+        />
+      </div>
+
+      <!-- 动作区：member 进入群聊 / stranger 加入群聊 / readonly 不渲染 -->
+      <div v-if="isMember" class="mt-4">
+        <ElButton type="primary" @click="emit('chat', group)">进入群聊</ElButton>
+      </div>
+      <div v-else-if="isStranger" class="mt-4">
+        <ElButton type="primary" @click="emit('apply', group)">加入群聊</ElButton>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-item.vue b/apps/web-ele/src/views/im/home/components/group/group-item.vue
new file mode 100644
index 000000000..9fa60e27e
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-item.vue
@@ -0,0 +1,43 @@
+<script lang="ts" setup>
+import type { GroupLite } from '../../types'
+
+import GroupAvatar from './group-avatar.vue'
+
+defineOptions({ name: 'ImGroupItem' })
+
+defineProps<{
+  active?: boolean
+  group: GroupLite
+}>()
+
+defineEmits<{
+  click: [group: GroupLite]
+}>()
+</script>
+
+<template>
+  <!--
+    群单行项
+    - 头像 + 群名
+    - 选中态 active
+  -->
+  <div
+    class="relative flex items-center gap-2.5 px-4 py-3 cursor-pointer transition-colors hover:bg-[var(--ant-color-fill)]"
+    :class="{ '!bg-[#d9ecff] dark:!bg-[var(--ant-color-primary-bg-hover)]': active }"
+    @click="$emit('click', group)"
+  >
+    <GroupAvatar
+      :group-id="group.id"
+      :url="group.showImage || group.showImageThumb"
+      :name="group.showGroupName || group.name"
+      :size="42"
+    />
+    <div class="flex flex-1 min-w-0">
+      <!-- 单行展示群名；成员数仅在群详情面板展示，列表里不重复 -->
+      <div class="overflow-hidden text-sm truncate text-[var(--ant-color-text)]">
+        {{ group.showGroupName || group.name }}
+      </div>
+    </div>
+    <slot></slot>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-member-add-dialog.vue b/apps/web-ele/src/views/im/home/components/group/group-member-add-dialog.vue
new file mode 100644
index 000000000..31c816b45
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-member-add-dialog.vue
@@ -0,0 +1,167 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from './group-member.vue'
+
+import { computed, ref } from 'vue'
+
+import { CommonStatusEnum } from '@vben/constants'
+
+import { ElButton, ElDialog, ElMessage } from 'element-plus'
+
+import { inviteGroupMember } from '#/api/im/group/member'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+import { GROUP_MAX_MEMBER } from '#/views/im/utils/config'
+import { ImGroupMemberRole } from '#/views/im/utils/constants'
+
+import { useFriendStore } from '../../store/friendStore'
+import { useGroupStore } from '../../store/groupStore'
+import { FriendPickerPanel } from '../picker'
+
+defineOptions({ name: 'ImGroupMemberAddDialog' })
+
+const emit = defineEmits<{
+  /** 邀请成功，携带被邀请的好友 id 列表；父侧通常用来 reload 群成员 */
+  reload: [friendIds: number[]]
+}>()
+
+const friendStore = useFriendStore()
+const groupStore = useGroupStore()
+
+const visible = ref(false)
+const submitting = ref(false)
+const groupId = ref(0)
+const selectedIds = ref<number[]>([])
+
+defineExpose({
+  /** 打开添加群成员弹窗：reset → 灌参 → visible=true */
+  open(opts: { groupId: number }) {
+    groupId.value = opts.groupId
+    selectedIds.value = []
+    submitting.value = false
+    visible.value = true
+  }
+})
+
+/** 当前群成员列表：从 groupStore 现取，避免随 groupId 变化时父侧 prop 更新延迟 */
+const members = computed<GroupMemberLite[]>(() => {
+  const group = groupStore.getGroup(groupId.value)
+  return (group?.members || []).map((member) => ({
+    userId: member.userId,
+    nickname: member.nickname,
+    showName: member.displayUserName || member.nickname,
+    avatar: member.avatar,
+    status: member.status,
+    role: member.role
+  }))
+})
+
+/** 全量好友：直接复用 friendStore Lite 视图 */
+const friends = computed(() => friendStore.getActiveFriendLiteList)
+
+/** 已在群里的好友 id：传给 Panel 的 disabledIds 置灰 + 不计入已选 */
+const disabledIds = computed<number[]>(() =>
+  members.value
+    .filter((member) => member.status !== CommonStatusEnum.DISABLE)
+    .map((member) => member.userId)
+)
+
+/** 是否走审批分支：群开启 joinApproval + 当前用户是普通成员（群主 / 管理员邀请直进） */
+const willGoApproval = computed(() => {
+  const group = groupStore.getGroup(groupId.value)
+  if (!group?.joinApproval) {
+    return false
+  }
+  const myId = getCurrentUserId()
+  if (!myId) {
+    return false
+  }
+  // 群主直判，避开 members 异步加载的窗口；admin 仍依赖 members
+  if (group.ownerUserId === myId) {
+    return false
+  }
+  // members 未到位时无法判定 admin，保守按非审批处理，宁可漏报「等待审批」也不误报给真实管理员
+  const myRole = members.value.find((member) => member.userId === myId)?.role
+  if (myRole == null) {
+    return false
+  }
+  return myRole !== ImGroupMemberRole.ADMIN
+})
+
+/** 当前群已启用成员数（DISABLE 即退群 / 被踢不计入），用于上限判定 */
+const activeMemberCount = computed(
+  () => members.value.filter((member) => member.status !== CommonStatusEnum.DISABLE).length
+)
+
+/** 邀请后群总人数若超 GROUP_MAX_MEMBER，前端先拦；activeMemberCount + selectedIds.length 即邀请后的成员数 */
+const willExceedLimit = computed(
+  () => activeMemberCount.value + selectedIds.value.length > GROUP_MAX_MEMBER
+)
+
+/** 添加按钮可点：至少有 1 个新邀请的好友 + 不超群人数上限 */
+const canSubmit = computed(() => selectedIds.value.length > 0 && !willExceedLimit.value)
+
+/** 邀请入群：调 /im/group/invite，成功后 emit reload 让父侧刷新群成员 */
+async function handleOk() {
+  if (!groupId.value) {
+    return
+  }
+  const memberUserIds = [...selectedIds.value]
+  if (memberUserIds.length === 0) {
+    return
+  }
+  // 群人数上限冗余防御：与 canSubmit 重复判一次，防止状态在 await 间隙变化或调用方绕过按钮直接调
+  if (activeMemberCount.value + memberUserIds.length > GROUP_MAX_MEMBER) {
+    ElMessage.warning(`群成员上限为 ${GROUP_MAX_MEMBER} 人`)
+    return
+  }
+  submitting.value = true
+  try {
+    await inviteGroupMember({ groupId: groupId.value, memberUserIds })
+    // 审批分支：后端仅落审批记录，未入群
+    ElMessage.success(willGoApproval.value ? '邀请已发起，等待群主 / 管理员审批' : '邀请成功')
+    emit('reload', memberUserIds)
+    visible.value = false
+  } finally {
+    submitting.value = false
+  }
+}
+</script>
+
+<template>
+  <!--
+    添加群成员：选好友邀请入群（已在群成员置灰、不计入已选）
+    - dialog 壳本组件持有；选择 UI 委托 FriendPickerPanel
+    - 已在群成员通过 disabledIds 传入，不再走 checked+disabled 的"已勾选灰态"
+    - 对外接口：ref + open({ groupId }) + emit reload(friendIds)
+  -->
+  <ElDialog
+    v-model="visible"
+    title="添加群成员"
+    width="720px"
+    :close-on-click-modal="false"
+    class="im-picker-dialog"
+  >
+    <div class="h-[480px]">
+      <FriendPickerPanel
+        v-model:selected-ids="selectedIds"
+        :friends="friends"
+        :disabled-ids="disabledIds"
+      />
+    </div>
+
+    <template #footer>
+      <ElButton @click="visible = false">取消</ElButton>
+      <ElButton type="primary" :loading="submitting" :disabled="!canSubmit" @click="handleOk">
+        添加
+      </ElButton>
+    </template>
+  </ElDialog>
+</template>
+
+<style scoped lang="scss">
+@use '../picker/picker-dialog' as picker;
+
+/* :deep 穿透 el-dialog 内部类；复用 picker 公共 mixin */
+.im-picker-dialog {
+  @include picker.styles;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-member-grid.vue b/apps/web-ele/src/views/im/home/components/group/group-member-grid.vue
new file mode 100644
index 000000000..e7cc7d6bc
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-member-grid.vue
@@ -0,0 +1,50 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from './group-member.vue'
+
+import { ImFriendAddSource } from '../../../utils/constants'
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImGroupMemberGrid' })
+
+withDefaults(
+  defineProps<{
+    clickable?: boolean // 头像点击是否弹 UserInfoCard；选择器宫格里需要保持关闭，避免和勾选交互冲突
+    groupName?: string // 群名：加好友时拼「我是 'XX 群' 的 YY」话术，落库 add_source=GROUP
+    member: GroupMemberLite
+    size?: number // 头像像素大小；默认 38（兼容选择器右侧已选区），群信息抽屉传 50 对齐微信 PC
+  }>(),
+  {
+    clickable: false,
+    size: 38,
+    groupName: ''
+  }
+)
+</script>
+
+<template>
+  <!--
+    群成员宫格单元
+    - 宫格展示的最小单位：头像在上、名字在下；列宽 = size + 16，自适应 size 留呼吸空间
+    - 被 GroupMemberPickerPanel 右侧已选区（grid 形态）、ConversationGroupSide 群成员区循环使用
+  -->
+  <div
+    class="relative flex flex-col items-center px-0.5 py-1"
+    :style="{ width: `${size! + 16}px` }"
+  >
+    <UserAvatar
+      :id="member.userId"
+      :url="member.avatar"
+      :name="member.nickname"
+      :size="size"
+      :clickable="clickable"
+      :add-source="ImFriendAddSource.GROUP"
+      :add-source-extra="groupName"
+    />
+    <div
+      class="w-full mt-1 overflow-hidden text-12px leading-[18px] text-center truncate text-[var(--ant-color-text)]"
+    >
+      {{ member.showName }}
+    </div>
+    <slot></slot>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-member-item.vue b/apps/web-ele/src/views/im/home/components/group/group-member-item.vue
new file mode 100644
index 000000000..1ed9fa0ad
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-member-item.vue
@@ -0,0 +1,84 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from './group-member.vue'
+
+import { computed } from 'vue'
+
+import { DICT_TYPE } from '@vben/constants'
+import { getDictLabel } from '@vben/hooks'
+
+import { ImGroupMemberRole } from '../../../utils/constants'
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImGroupMemberItem' })
+
+const props = withDefaults(
+  defineProps<{
+    active?: boolean
+    height?: number
+    member: GroupMemberLite
+  }>(),
+  {
+    height: 50,
+    active: false
+  }
+)
+
+defineEmits<{
+  click: [member: GroupMemberLite]
+}>()
+
+const avatarSize = computed(() => Math.ceil(props.height * 0.75))
+
+/** 角色标签文案：普通成员不显示，其余取 im_group_member_role 字典 label */
+const roleLabel = computed(() => {
+  if (props.member.role == null || props.member.role === ImGroupMemberRole.NORMAL) {
+    return ''
+  }
+  return getDictLabel(DICT_TYPE.IM_GROUP_MEMBER_ROLE, props.member.role)
+})
+
+/** 角色标签样式：群主用主色；管理员用次要色 */
+const roleLabelClass = computed(() => {
+  if (props.member.role === ImGroupMemberRole.OWNER) {
+    return 'text-[var(--ant-color-primary)] bg-[var(--ant-color-primary-bg)]'
+  }
+  return 'text-[var(--ant-color-info)] bg-[var(--ant-color-fill)]'
+})
+</script>
+
+<template>
+  <!--
+    群成员行形态
+    - 横排、带 hover 态；slot 放 checkbox / 操作按钮等
+    - 与 GroupMember 的差别：带 hover 态 + slot 扩展点，适合 selector / admin 列表
+  -->
+  <div
+    class="relative flex gap-2.5 items-center mx-px px-4 box-border whitespace-nowrap rounded cursor-pointer transition-colors hover:bg-[var(--ant-color-fill)]"
+    :class="{ '!bg-[#e1eaf7] dark:!bg-[var(--ant-color-primary-bg-hover)]': active }"
+    :style="{ height: `${height }px` }"
+    @click="$emit('click', member)"
+  >
+    <UserAvatar
+      :id="member.userId"
+      :url="member.avatar"
+      :name="member.nickname"
+      :size="avatarSize"
+      :clickable="false"
+    />
+    <div
+      class="flex-1 h-full pl-1 overflow-hidden text-sm truncate text-[var(--ant-color-text)]"
+      :style="{ lineHeight: `${height }px` }"
+    >
+      {{ member.showName }}
+    </div>
+    <!-- 角色标签：群主 / 管理员；普通成员不显示。仅在传入 member.role 时生效 -->
+    <span
+      v-if="roleLabel"
+      class="px-1.5 py-px rounded text-xs whitespace-nowrap"
+      :class="roleLabelClass"
+    >
+      {{ roleLabel }}
+    </span>
+    <slot></slot>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-member-remove-dialog.vue b/apps/web-ele/src/views/im/home/components/group/group-member-remove-dialog.vue
new file mode 100644
index 000000000..a87b4d112
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-member-remove-dialog.vue
@@ -0,0 +1,105 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from './group-member.vue'
+
+import { ref } from 'vue'
+
+import { ElButton, ElDialog, ElMessage } from 'element-plus'
+
+import { removeGroupMember } from '#/api/im/group/member'
+
+import { GroupMemberPickerPanel } from '../picker'
+
+defineOptions({ name: 'ImGroupMemberRemoveDialog' })
+
+const emit = defineEmits<{
+  /** 移出成功；父侧通常用来 reload 群数据 */
+  reload: []
+}>()
+
+const visible = ref(false)
+const submitting = ref(false)
+const groupId = ref(0)
+const members = ref<GroupMemberLite[]>([])
+const hideIds = ref<number[]>([])
+const selectedIds = ref<number[]>([])
+
+defineExpose({
+  /** 打开移除群成员弹窗：reset → 灌参 → visible=true */
+  open(opts: {
+    groupId: number
+    /** 隐藏 userId：群主始终隐藏；管理员视角额外隐藏其它管理员 */
+    hideIds?: number[]
+    members: GroupMemberLite[]
+  }) {
+    groupId.value = opts.groupId
+    members.value = opts.members
+    hideIds.value = opts.hideIds ? [...opts.hideIds] : []
+    selectedIds.value = []
+    submitting.value = false
+    visible.value = true
+  }
+})
+
+/** 一次性批量踢人：选中成员 userId 数组传给后端，比循环调 N 次接口省往返 */
+async function handleOk() {
+  if (!groupId.value || selectedIds.value.length === 0) {
+    return
+  }
+  submitting.value = true
+  try {
+    const memberUserIds = [...selectedIds.value]
+    await removeGroupMember({ groupId: groupId.value, memberUserIds })
+    ElMessage.success(`已移除 ${memberUserIds.length} 位成员`)
+    emit('reload')
+    visible.value = false
+  } finally {
+    submitting.value = false
+  }
+}
+</script>
+
+<template>
+  <!--
+    移除群成员：选成员 → removeGroupMember 批量踢人
+    - dialog 壳本组件持有；选择 UI 委托 GroupMemberPickerPanel
+    - 群主 / 管理员视角的不可移除成员通过 hideIds 隐藏，由调用方传入
+    - 对外接口：ref + open({ groupId, members, hideIds }) + emit reload()
+  -->
+  <ElDialog
+    v-model="visible"
+    title="移出群成员"
+    width="700px"
+    :close-on-click-modal="false"
+    class="im-picker-dialog"
+  >
+    <div class="h-[480px]">
+      <GroupMemberPickerPanel
+        v-model:selected-ids="selectedIds"
+        :members="members"
+        :hide-ids="hideIds"
+        :max-size="50"
+      />
+    </div>
+
+    <template #footer>
+      <ElButton @click="visible = false">取消</ElButton>
+      <ElButton
+        type="primary"
+        :loading="submitting"
+        :disabled="selectedIds.length === 0"
+        @click="handleOk"
+      >
+        移出
+      </ElButton>
+    </template>
+  </ElDialog>
+</template>
+
+<style scoped lang="scss">
+@use '../picker/picker-dialog' as picker;
+
+/* :deep 穿透 el-dialog 内部类；复用 picker 公共 mixin */
+.im-picker-dialog {
+  @include picker.styles;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-member.vue b/apps/web-ele/src/views/im/home/components/group/group-member.vue
new file mode 100644
index 000000000..2ae97a22e
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-member.vue
@@ -0,0 +1,64 @@
+<script lang="ts" setup>
+import { computed } from 'vue'
+
+import { ImFriendAddSource } from '../../../utils/constants'
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImGroupMember' })
+
+const props = withDefaults(
+  defineProps<{
+    active?: boolean // 选中态（@候选键盘高亮等）
+    clickable?: boolean // 头像点击是否弹 UserInfoCard；@候选场景通常禁用（避免嵌套交互）
+    groupName?: string // 群名：加好友时拼「我是 'XX 群' 的 YY」话术，落库 add_source=GROUP
+    height?: number // 行高（px），影响头像大小
+    member: GroupMemberLite
+  }>(),
+  {
+    height: 50,
+    active: false,
+    clickable: false,
+    groupName: ''
+  }
+)
+
+/** 群成员结构（跨多处使用，放这里做窄接口；独立于 types/index.ts） */
+export interface GroupMemberLite {
+  userId: number // 用户编号；特殊值见 IM_AT_ALL_USER_ID（@ 全体成员）
+  nickname: string // 真实昵称：永远是用户的 nickname，专给 UserAvatar 色卡用，保证同一个人色卡首字母在所有界面一致
+  showName: string // 展示昵称：好友备注 > 用户群备注（displayUserName） > 真实昵称（nickname），给"显示给用户看"的位置用（行内文字、@候选标签等）
+  avatar?: string
+  status?: number
+  role?: number // 成员角色，仅在群信息抽屉等需要展示角色标签的场景透传；@候选 / 已读列表等场景可不传
+}
+
+const avatarSize = computed(() => Math.ceil(props.height * 0.75))
+</script>
+
+<template>
+  <!--
+    群成员单行
+    跨子域复用：@候选 (MentionPicker) / 已读列表 (MessageReadStatus) / 群成员宫格 (ConversationGroupSide)
+  -->
+  <div
+    class="relative flex items-center px-[5px] box-border whitespace-nowrap"
+    :class="{ 'bg-[#e1eaf7] dark:bg-[var(--ant-color-primary-bg)]': active }"
+    :style="{ height: `${height }px` }"
+  >
+    <UserAvatar
+      :size="avatarSize"
+      :name="member.nickname"
+      :url="member.avatar"
+      :clickable="clickable"
+      :id="member.userId"
+      :add-source="ImFriendAddSource.GROUP"
+      :add-source-extra="groupName"
+    />
+    <div
+      class="flex-1 h-full pl-2.5 overflow-hidden text-sm text-left truncate text-[var(--ant-color-text)]"
+      :style="{ lineHeight: `${height }px` }"
+    >
+      {{ member.showName }}
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-mute-member-dialog.vue b/apps/web-ele/src/views/im/home/components/group/group-mute-member-dialog.vue
new file mode 100644
index 000000000..f25ba4edc
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-mute-member-dialog.vue
@@ -0,0 +1,97 @@
+<script lang="ts" setup>
+import { ref } from 'vue'
+
+import { ElButton, ElDialog, ElMessage } from 'element-plus'
+
+import { muteMember } from '#/api/im/group'
+
+defineOptions({ name: 'ImGroupMuteMemberDialog' })
+
+const emit = defineEmits<{
+  success: []
+}>()
+
+const visible = ref(false)
+const loading = ref(false)
+const groupId = ref(0)
+const userId = ref(0)
+const memberName = ref('')
+const selected = ref(600) // 默认 10 分钟
+
+const presets = [
+  { label: '10 分钟', value: 600 },
+  { label: '1 小时', value: 3600 },
+  { label: '12 小时', value: 43_200 },
+  { label: '1 天', value: 86_400 },
+  { label: '7 天', value: 604_800 },
+  { label: '30 天', value: 2_592_000 },
+  { label: '永久', value: 0 }
+]
+
+/** 打开弹窗 */
+function open(gid: number, uid: number, name: string) {
+  groupId.value = gid
+  userId.value = uid
+  memberName.value = name
+  selected.value = 600
+  visible.value = true
+}
+
+/** 确认禁言 */
+async function handleConfirm() {
+  loading.value = true
+  try {
+    await muteMember({
+      id: groupId.value,
+      userId: userId.value,
+      mutedSeconds: selected.value
+    })
+    ElMessage.success('禁言成功')
+    visible.value = false
+    emit('success')
+  } finally {
+    loading.value = false
+  }
+}
+
+defineExpose({ open })
+</script>
+
+<template>
+  <!-- 禁言时长选择弹窗 -->
+  <ElDialog v-model="visible" title="设置禁言" width="560px" :close-on-click-modal="false">
+    <div class="flex flex-col gap-4">
+      <!-- 成员信息卡：和 FriendAddDialog 的 user 卡保持一致的浅色背景 -->
+      <div
+        class="flex items-center gap-2 px-3 py-2.5 rounded-md bg-[var(--ant-color-fill-secondary)]"
+      >
+        <span class="text-13px text-[var(--ant-color-text-secondary)]">禁言成员</span>
+        <span
+          class="text-sm font-medium text-[var(--ant-color-text)] truncate"
+        >
+          {{ memberName }}
+        </span>
+      </div>
+
+      <!-- 禁言时长选项：用 el-button 平铺，选中走 primary，靠 gap-2 留间距 -->
+      <div>
+        <div class="mb-2 text-13px text-[var(--ant-color-text-secondary)]">禁言时长</div>
+        <div class="grid grid-cols-3 gap-2">
+          <ElButton
+            v-for="opt in presets"
+            :key="opt.value"
+            :type="selected === opt.value ? 'primary' : undefined"
+            class="!ml-0 w-full"
+            @click="selected = opt.value"
+          >
+            {{ opt.label }}
+          </ElButton>
+        </div>
+      </div>
+    </div>
+    <template #footer>
+      <ElButton @click="visible = false">取消</ElButton>
+      <ElButton type="primary" :loading="loading" @click="handleConfirm">确定</ElButton>
+    </template>
+  </ElDialog>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-owner-transfer-dialog.vue b/apps/web-ele/src/views/im/home/components/group/group-owner-transfer-dialog.vue
new file mode 100644
index 000000000..8942bb00c
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-owner-transfer-dialog.vue
@@ -0,0 +1,126 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from './group-member.vue'
+
+import { computed, ref } from 'vue'
+
+import { confirm } from '@vben/common-ui'
+
+import { ElButton, ElDialog, ElMessage } from 'element-plus'
+
+import { transferGroupOwner } from '#/api/im/group'
+
+import { GroupMemberPickerPanel } from '../picker'
+
+defineOptions({ name: 'ImGroupOwnerTransferDialog' })
+
+const emit = defineEmits<{
+  /** 转让成功；父侧通常用来 reload 群数据 */
+  reload: []
+}>()
+
+const visible = ref(false)
+const submitting = ref(false)
+const groupId = ref(0)
+const members = ref<GroupMemberLite[]>([])
+const hideIds = ref<number[]>([])
+const selectedIds = ref<number[]>([])
+
+defineExpose({
+  /** 打开转让群主弹窗：reset → 灌参 → visible=true */
+  open(opts: {
+    groupId: number
+    /** 隐藏 userId：当前用户（不能转给自己） */
+    hideIds?: number[]
+    members: GroupMemberLite[]
+  }) {
+    groupId.value = opts.groupId
+    members.value = opts.members
+    hideIds.value = opts.hideIds ? [...opts.hideIds] : []
+    selectedIds.value = []
+    submitting.value = false
+    visible.value = true
+  }
+})
+
+/** 选中的新群主对象（取数组首项） */
+const newOwner = computed<GroupMemberLite | undefined>(() => {
+  if (selectedIds.value.length === 0) {
+    return undefined
+  }
+  return members.value.find((member) => member.userId === selectedIds.value[0])
+})
+
+/** 二次确认转让：转让后旧群主降为普通成员，无法撤销 */
+async function handleOk() {
+  if (!groupId.value || !newOwner.value) {
+    return
+  }
+  try {
+    await confirm(
+      `确定将群主转让给 ${newOwner.value.showName}？转让后你将变为普通成员，无法撤销。`,
+      '确认转让群主'
+    )
+  } catch {
+    return
+  }
+  submitting.value = true
+  try {
+    await transferGroupOwner({
+      id: groupId.value,
+      newOwnerUserId: newOwner.value.userId
+    })
+    ElMessage.success('群主转让成功')
+    emit('reload')
+    visible.value = false
+  } finally {
+    submitting.value = false
+  }
+}
+</script>
+
+<template>
+  <!--
+    转让群主：选 1 位新群主 → 二次确认 → transferGroupOwner
+    - dialog 壳本组件持有；选择 UI 委托 GroupMemberPickerPanel
+    - 当前用户从候选里隐藏（不能转给自己）
+    - maxSize=1 限定单选
+    - 对外接口：ref + open({ groupId, members, hideIds }) + emit reload()
+  -->
+  <ElDialog
+    v-model="visible"
+    title="选择新群主"
+    width="700px"
+    :close-on-click-modal="false"
+    class="im-picker-dialog"
+  >
+    <div class="h-[480px]">
+      <GroupMemberPickerPanel
+        v-model:selected-ids="selectedIds"
+        :members="members"
+        :hide-ids="hideIds"
+        :max-size="1"
+      />
+    </div>
+
+    <template #footer>
+      <ElButton @click="visible = false">取消</ElButton>
+      <ElButton
+        type="primary"
+        :loading="submitting"
+        :disabled="selectedIds.length === 0"
+        @click="handleOk"
+      >
+        确定
+      </ElButton>
+    </template>
+  </ElDialog>
+</template>
+
+<style scoped lang="scss">
+@use '../picker/picker-dialog' as picker;
+
+/* :deep 穿透 el-dialog 内部类；复用 picker 公共 mixin */
+.im-picker-dialog {
+  @include picker.styles;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/group/group-request-list-dialog.vue b/apps/web-ele/src/views/im/home/components/group/group-request-list-dialog.vue
new file mode 100644
index 000000000..2e25e3041
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/group-request-list-dialog.vue
@@ -0,0 +1,377 @@
+<script lang="ts" setup>
+import type { ImGroupRequestApi } from '#/api/im/group/request'
+
+import { computed, ref, watch } from 'vue'
+
+import { prompt } from '@vben/common-ui'
+
+import { ElDialog, ElEmpty, ElInput, ElMessage } from 'element-plus'
+
+import { getGroupRequestListByGroupId } from '#/api/im/group/request'
+import { ImGroupRequestHandleResult } from '#/views/im/utils/constants'
+
+import { useGroupRequestStore } from '../../store/groupRequestStore'
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImGroupRequestListDialog' })
+
+const groupRequestStore = useGroupRequestStore()
+
+const visible = ref(false)
+const groupId = ref<number | undefined>() // 当前展示的群编号；undefined 时走全局未处理列表（store.unhandledList）
+const loading = ref(false)
+const groupList = ref<ImGroupRequestApi.GroupRequestRespVO[]>([])
+const actingId = ref<null | number>(null)
+
+defineExpose({
+  /** 打开进群申请弹窗：reset → 灌参 → visible=true；不传 groupId 走全局未处理列表 */
+  open(opts?: { groupId?: number }) {
+    groupId.value = opts?.groupId
+    actingId.value = null
+    visible.value = true
+  }
+})
+
+/** 数据源：单群模式用 fetch 回来的 groupList；全局模式直接读 store.unhandledList，处理后 store 自动 reactive 同步 */
+const list = computed<ImGroupRequestApi.GroupRequestRespVO[]>(() =>
+  groupId.value ? groupList.value : groupRequestStore.unhandledList
+)
+
+/** 顶部卡片：最新一条；空数组时为 null */
+const latest = computed(() => list.value[0] || null)
+/** 历史列表：除最新一条外的其余 */
+const histories = computed(() => list.value.slice(1))
+
+/** 打开 dialog 时拉数据：单群拉 API；全局直接读 store；关闭时清掉单群缓存 */
+watch(
+  [visible, groupId],
+  ([isVisible, currentGroupId]) => {
+    if (isVisible && currentGroupId) {
+      void fetchList(currentGroupId)
+    } else if (!isVisible) {
+      groupList.value = []
+    }
+  },
+  { immediate: true }
+)
+
+/**
+ * 单群模式下订阅 store 中归属本群的未处理列表变化：远端事件（WS 1503 新申请 / 其他管理员处理）触发时 refetch
+ * 拿最新 handleResult；本端 agree / refuse 期间 actingId 锁住，跳过本端动作引发的 store 变化避免冗余 RTT
+ *
+ * key 不能只 join id：复用旧记录时同一 requestId 的 applyContent / inviterUserId 会刷新但 id 不变，必须把内容字段也纳入触发
+ */
+watch(
+  () =>
+    groupId.value && visible.value
+      ? groupRequestStore.unhandledList
+          .filter((request) => request.groupId === groupId.value)
+          .map(
+            (request) =>
+              `${request.id}:${request.inviterUserId ?? ''}:${request.applyContent ?? ''}`
+          )
+          .join(',')
+      : null,
+  (current, previous) => {
+    if (current === null || previous === undefined || current === previous) {
+      return
+    }
+    if (actingId.value !== null) {
+      return
+    }
+    if (groupId.value) {
+      void fetchList(groupId.value)
+    }
+  }
+)
+
+let fetchSeq = 0 // 单调递增请求序号；同群也会因为 WS 1503 推送触发额外 fetch，乱序返回时旧响应不能覆盖新数据
+async function fetchList(targetGroupId: number) {
+  const seq = ++fetchSeq
+  loading.value = true
+  try {
+    const data = (await getGroupRequestListByGroupId(targetGroupId)) || []
+    // 期间切群 / 关弹窗 / 又触发更新 fetch：丢响应
+    if (seq !== fetchSeq || !visible.value || groupId.value !== targetGroupId) {
+      return
+    }
+    groupList.value = data
+  } finally {
+    // 旧请求 finally 命中时新请求仍在跑，跳过避免提前关 loading
+    if (seq === fetchSeq) {
+      loading.value = false
+    }
+  }
+}
+
+/** 同意：走 store 同步全局未处理列表 + 本地更新 handleResult 让按钮变灰 */
+async function handleAgree(item: ImGroupRequestApi.GroupRequestRespVO) {
+  if (actingId.value !== null) return
+  actingId.value = item.id
+  try {
+    await groupRequestStore.agreeGroupRequest(item.id)
+    updateLocalResult(item.id, ImGroupRequestHandleResult.AGREED)
+    ElMessage.success('已同意')
+  } finally {
+    actingId.value = null
+  }
+}
+
+/** 拒绝：弹理由输入框；为空则不带 handleContent */
+async function handleRefuse(item: ImGroupRequestApi.GroupRequestRespVO) {
+  if (actingId.value !== null) return
+  let handleContent: string
+  try {
+    const result = await prompt<string>({
+      component: ElInput,
+      componentProps: {
+        clearable: true,
+        placeholder: '请输入拒绝理由（可选）'
+      },
+      content: '',
+      modelPropName: 'value',
+      title: '拒绝申请'
+    })
+    handleContent = result || ''
+  } catch {
+    return
+  }
+  actingId.value = item.id
+  try {
+    await groupRequestStore.refuseGroupRequest(item.id, handleContent || undefined)
+    updateLocalResult(item.id, ImGroupRequestHandleResult.REFUSED)
+    ElMessage.success('已拒绝')
+  } finally {
+    actingId.value = null
+  }
+}
+
+/** 单群模式下处理后更新 groupList 里的 handleResult，按钮转「已同意 / 已拒绝」灰态；全局模式 store 直接移除该项无需更新 */
+function updateLocalResult(id: number, handleResult: number) {
+  const target = groupList.value.find((r) => r.id === id)
+  if (target) {
+    target.handleResult = handleResult
+  }
+}
+</script>
+
+<template>
+  <!--
+    群「进群申请」列表对话框
+    - 仅群主 / 管理员入口可达；展示当前群下全部申请（含已处理）
+    - 顶部最新一条卡片化突出（带申请理由），其余按 id 倒序紧凑列表
+    - 同意 / 拒绝走 groupRequestStore 的 action，处理后本地更新 handleResult 让按钮转灰态
+  -->
+  <ElDialog
+    v-model="visible"
+    title="进群申请"
+    width="560px"
+    
+    :close-on-click-modal="false"
+    class="im-group-request-list__dialog"
+  >
+    <div v-loading="loading" class="w-full">
+      <div class="flex flex-col gap-3 max-h-[60vh] overflow-y-auto pr-1">
+        <!-- 空态 -->
+        <ElEmpty v-if="!loading && list.length === 0" description="暂无进群申请" />
+
+      <!-- 顶部卡片：最新一条 -->
+        <div
+          v-if="latest"
+          class="flex flex-col gap-2.5 p-3.5 rounded-[10px] border border-solid border-[var(--ant-color-border-secondary)] bg-[var(--ant-color-bg-container)] shadow-[0_1px_3px_rgba(0,0,0,0.04)]"
+        >
+        <div class="flex items-center gap-3">
+          <UserAvatar
+            :url="latest.userAvatar"
+            :name="latest.userNickname"
+            :size="44"
+            :clickable="false"
+          />
+          <div class="flex-1 min-w-0">
+            <div
+              class="truncate text-sm font-medium leading-[1.4] text-[var(--ant-color-text)]"
+            >
+              {{ latest.userNickname || `用户 ${latest.userId}` }}
+            </div>
+            <div
+              class="truncate mt-[2px] text-12px leading-[1.5] text-[var(--ant-color-text-secondary)]"
+            >
+              <template v-if="latest.inviterUserId">
+                通过
+                <span class="text-[var(--ant-color-primary)]">
+                  {{ latest.inviterNickname || `用户 ${latest.inviterUserId}` }}
+                </span>
+                的邀请进群
+              </template>
+              <template v-else>申请加入</template>
+            </div>
+          </div>
+          <span
+            v-if="latest.handleResult === ImGroupRequestHandleResult.AGREED"
+            class="flex-shrink-0 text-[13px] text-[var(--ant-color-text-placeholder)]"
+          >
+            已同意
+          </span>
+          <span
+            v-else-if="latest.handleResult === ImGroupRequestHandleResult.REFUSED"
+            class="flex-shrink-0 text-[13px] text-[var(--ant-color-text-placeholder)]"
+          >
+            已拒绝
+          </span>
+          <div v-else class="flex gap-1.5 flex-shrink-0">
+            <button
+              class="im-group-request-list__btn im-group-request-list__btn--primary"
+              :disabled="actingId === latest.id"
+              @click="handleAgree(latest)"
+            >
+              确认
+            </button>
+            <button
+              class="im-group-request-list__btn im-group-request-list__btn--ghost"
+              :disabled="actingId === latest.id"
+              @click="handleRefuse(latest)"
+            >
+              拒绝
+            </button>
+          </div>
+        </div>
+        <!-- 申请理由：邀请场景显示邀请人 + 留言；主动申请显示申请人 + 留言 -->
+        <div
+          v-if="latest.applyContent"
+          class="px-3 py-2 rounded-md text-[13px] leading-[1.5] break-all bg-[var(--ant-color-fill-secondary)] text-[var(--ant-color-text)]"
+        >
+          <span class="text-[var(--ant-color-primary)]">
+            {{
+              latest.inviterUserId
+                ? latest.inviterNickname || `用户 ${latest.inviterUserId}`
+                : latest.userNickname || `用户 ${latest.userId}`
+            }}：
+          </span>
+          {{ latest.applyContent }}
+        </div>
+      </div>
+
+      <!-- 分割线：仅在有更早申请时出现 -->
+        <div
+          v-if="histories.length > 0"
+          class="flex items-center justify-center mt-1.5 -mb-0.5 text-12px text-[var(--ant-color-text-placeholder)]"
+        >
+          <span>以下为更早的申请</span>
+        </div>
+
+        <!-- 历史申请列表 -->
+        <div
+          v-for="item in histories"
+          :key="item.id"
+          class="flex flex-col gap-2.5 px-3.5 py-2.5 rounded-[10px] border border-solid border-[var(--ant-color-border-secondary)] bg-[var(--ant-color-bg-container)] shadow-[0_1px_3px_rgba(0,0,0,0.04)]"
+        >
+        <div class="flex items-center gap-3">
+          <UserAvatar
+            :url="item.userAvatar"
+            :name="item.userNickname"
+            :size="40"
+            :clickable="false"
+          />
+          <div class="flex-1 min-w-0">
+            <div
+              class="truncate text-sm font-medium leading-[1.4] text-[var(--ant-color-text)]"
+            >
+              {{ item.userNickname || `用户 ${item.userId}` }}
+            </div>
+            <div
+              class="truncate mt-[2px] text-12px leading-[1.5] text-[var(--ant-color-text-secondary)]"
+            >
+              <template v-if="item.inviterUserId">
+                通过
+                <span class="text-[var(--ant-color-primary)]">
+                  {{ item.inviterNickname || `用户 ${item.inviterUserId}` }}
+                </span>
+                的邀请进群
+              </template>
+              <template v-else>申请加入</template>
+            </div>
+          </div>
+          <span
+            v-if="item.handleResult === ImGroupRequestHandleResult.AGREED"
+            class="flex-shrink-0 text-[13px] text-[var(--ant-color-text-placeholder)]"
+          >
+            已同意
+          </span>
+          <span
+            v-else-if="item.handleResult === ImGroupRequestHandleResult.REFUSED"
+            class="flex-shrink-0 text-[13px] text-[var(--ant-color-text-placeholder)]"
+          >
+            已拒绝
+          </span>
+          <div v-else class="flex gap-1.5 flex-shrink-0">
+            <button
+              class="im-group-request-list__btn im-group-request-list__btn--primary"
+              :disabled="actingId === item.id"
+              @click="handleAgree(item)"
+            >
+              确认
+            </button>
+            <button
+              class="im-group-request-list__btn im-group-request-list__btn--ghost"
+              :disabled="actingId === item.id"
+              @click="handleRefuse(item)"
+            >
+              拒绝
+            </button>
+          </div>
+        </div>
+        </div>
+      </div>
+    </div>
+  </ElDialog>
+</template>
+
+<style scoped>
+/* 自绘按钮：贴近微信小药丸样式；与 :disabled、:hover:not(:disabled) 等伪类叠加 modifier 类的组合选择器写在 class 里成本高，留 SCSS */
+.im-group-request-list__btn {
+  flex-shrink: 0;
+  min-width: 56px;
+  height: 28px;
+  padding: 0 12px;
+  font-size: 13px;
+  border-radius: 4px;
+  cursor: pointer;
+  border: 1px solid transparent;
+  transition:
+    background-color 0.15s,
+    border-color 0.15s,
+    color 0.15s;
+}
+.im-group-request-list__btn:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.im-group-request-list__btn--primary {
+  color: #fff;
+  background-color: var(--ant-color-primary);
+  border-color: var(--ant-color-primary);
+}
+.im-group-request-list__btn--primary:hover:not(:disabled) {
+  background-color: var(--ant-color-primary-hover);
+  border-color: var(--ant-color-primary-hover);
+}
+
+.im-group-request-list__btn--ghost {
+  color: var(--ant-color-text);
+  background-color: var(--ant-color-bg-container);
+  border-color: var(--ant-color-border);
+}
+.im-group-request-list__btn--ghost:hover:not(:disabled) {
+  color: var(--ant-color-primary);
+  border-color: var(--ant-color-primary);
+}
+</style>
+
+<style>
+/* el-dialog 内部 body 通过 teleport 渲染到 body，scoped 选不到，留非 scoped 全局覆盖 */
+.im-group-request-list__dialog .el-dialog__body {
+  padding: 12px 20px 8px;
+  background-color: var(--ant-color-fill-secondary);
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/group/index.ts b/apps/web-ele/src/views/im/home/components/group/index.ts
new file mode 100644
index 000000000..3e082af8f
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/group/index.ts
@@ -0,0 +1,15 @@
+export { default as GroupAdminSetDialog } from './group-admin-set-dialog.vue';
+export { default as GroupAvatar } from './group-avatar.vue';
+export { default as GroupCreateDialog } from './group-create-dialog.vue';
+export { default as GroupInfoCard } from './group-info-card.vue';
+export { default as GroupInfo } from './group-info.vue';
+export { default as GroupItem } from './group-item.vue';
+export { default as GroupMemberAddDialog } from './group-member-add-dialog.vue';
+export { default as GroupMemberGrid } from './group-member-grid.vue';
+export { default as GroupMemberItem } from './group-member-item.vue';
+export { default as GroupMemberRemoveDialog } from './group-member-remove-dialog.vue';
+export { default as GroupMember } from './group-member.vue';
+export type { GroupMemberLite } from './group-member.vue';
+export { default as GroupMuteMemberDialog } from './group-mute-member-dialog.vue';
+export { default as GroupOwnerTransferDialog } from './group-owner-transfer-dialog.vue';
+export { default as GroupRequestListDialog } from './group-request-list-dialog.vue';
diff --git a/apps/web-ele/src/views/im/home/components/index.ts b/apps/web-ele/src/views/im/home/components/index.ts
new file mode 100644
index 000000000..0d65403b1
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/index.ts
@@ -0,0 +1,4 @@
+export { default as ContextMenu } from './context-menu.vue';
+export { default as PagedScroller } from './paged-scroller.vue';
+export { default as ResizableAside } from './resizable-aside.vue';
+export { default as ToolBar } from './tool-bar.vue';
diff --git a/apps/web-ele/src/views/im/home/components/paged-scroller.vue b/apps/web-ele/src/views/im/home/components/paged-scroller.vue
new file mode 100644
index 000000000..ed1842a2f
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/paged-scroller.vue
@@ -0,0 +1,109 @@
+<script lang="ts" setup generic="T">
+import { computed, onBeforeUnmount, onMounted, ref, useTemplateRef, watch } from 'vue'
+
+defineOptions({ name: 'ImPagedScroller' })
+
+const props = withDefaults(
+  defineProps<{
+    itemKey?: string // 业务 id 字段名（如 'userId' / 'id'）；不传 / 字段值非 string|number 时回退 idx
+    items: T[] // 全量数据
+    pageSize?: number // 每页渲染条数
+    threshold?: number // 距底多少 px 触发下一页
+  }>(),
+  {
+    itemKey: undefined,
+    pageSize: 30,
+    threshold: 30
+  }
+)
+
+/** 解析每条 item 的 :key：caller 传 itemKey 则按字段取，无效 / 缺失回退索引，避免传错字段时全表 undefined key */
+function resolveItemKey(item: T, idx: number): number | string {
+  if (!props.itemKey || item == null || typeof item !== 'object') {
+    return idx
+  }
+  const value = (item as Record<string, unknown>)[props.itemKey]
+  return typeof value === 'string' || typeof value === 'number' ? value : idx
+}
+
+const scrollbarRef = useTemplateRef<HTMLDivElement>('scrollbarRef')
+const page = ref(1)
+
+const displayItems = computed(() => {
+  const limit = Math.min(page.value * props.pageSize, props.items.length)
+  return props.items.slice(0, limit)
+})
+
+const allLoaded = computed(() => displayItems.value.length >= props.items.length)
+
+/** 仅当超过一页时才显示「已到底部」，避免短列表也出现这条提示 */
+const showFooter = computed(() => allLoaded.value && props.items.length > props.pageSize)
+
+let wrapEl: HTMLElement | null = null
+
+onMounted(() => {
+  wrapEl = scrollbarRef.value
+  wrapEl?.addEventListener('scroll', onScroll)
+})
+
+onBeforeUnmount(() => {
+  wrapEl?.removeEventListener('scroll', onScroll)
+})
+
+/** 切换数据源（如切会话）时重置分页：避免新列表沿用旧 page，首屏出现空段 */
+watch(
+  () => props.items,
+  () => {
+    page.value = 1
+  }
+)
+
+/** 滚到距底 threshold 内时自增 page，扩出下一段切片 */
+function onScroll(e: Event) {
+  const el = e.target as HTMLElement
+  if (el.scrollTop + el.clientHeight < el.scrollHeight - props.threshold) {
+    return
+  }
+  if (allLoaded.value) {
+    return
+  }
+  page.value++
+}
+
+defineExpose({
+  /** 手动滚到顶部 */
+  scrollTop: () => {
+    if (wrapEl) {
+      wrapEl.scrollTop = 0
+    }
+  },
+  /** 手动滚到底部 */
+  scrollBottom: () => {
+    if (wrapEl) {
+      wrapEl.scrollTop = wrapEl.scrollHeight
+    }
+  }
+})
+</script>
+
+<template>
+  <!--
+    分页增量滚动容器
+    - 滚到底部自动 page++，直到全部渲染完
+    - 通过 slot 暴露每一项，让调用方自己决定渲染
+  -->
+  <div ref="scrollbarRef" class="w-full h-full overflow-y-auto">
+    <slot
+      v-for="(item, idx) in displayItems"
+      :item="item"
+      :index="idx"
+      :key="resolveItemKey(item, idx)"
+    ></slot>
+    <div
+      v-if="showFooter"
+      class="py-3 text-xs text-center text-[var(--ant-color-text-secondary)]"
+    >
+      已到底部
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/picker/conversation-picker-panel.vue b/apps/web-ele/src/views/im/home/components/picker/conversation-picker-panel.vue
new file mode 100644
index 000000000..7e50e3fc7
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/picker/conversation-picker-panel.vue
@@ -0,0 +1,370 @@
+<script lang="ts" setup>
+import type { Conversation } from '../../types'
+
+import { computed, ref } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElInput, ElMessage } from 'element-plus'
+
+import { ImConversationType } from '../../../utils/constants'
+import { filterConversationsByKeyword, getConversationKey } from '../../../utils/conversation'
+import { GroupAvatar } from '../group'
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImConversationPickerPanel' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 全量会话列表 */
+    conversations: Conversation[]
+    /** 隐藏 key：从候选 / 已选 / 最近转发里都剔除（不能转发回自己、推荐名片自身的会话等） */
+    hideKeys?: string[]
+    /** 已选数上限；不传或 <=0 时不限 */
+    maxSize?: number
+    /** 最近转发会话 key 列表；展示在左栏顶部横向头像区 */
+    recentForwardConversationKeys?: string[]
+    /** 已选会话 key（v-model）；key 由 getConversationKey 生成 */
+    selectedKeys: string[]
+    /** 是否展示「创建聊天」入口 */
+    showCreateChat?: boolean
+  }>(),
+  {
+    recentForwardConversationKeys: () => [],
+    hideKeys: () => [],
+    maxSize: 0,
+    showCreateChat: false
+  }
+)
+
+const emit = defineEmits<{
+  createChat: []
+  /** 用户在「最近转发」段进入移除模式后点 ×；业务壳收到后调 conversationStore.removeRecentForwardConversationKey 落盘 */
+  removeRecent: [key: string]
+  'update:selectedKeys': [value: string[]]
+}>()
+
+const keyword = ref('')
+const recentRemoveMode = ref(false) // 「最近转发」段是否处于移除模式：true 时头像右上角变 × 不再切勾选
+
+/** 全量会话的 key→Conversation 映射，已选 / 最近转发反查共用，避免每次 O(N) 扫 */
+const byKey = computed(() => {
+  const map = new Map<string, Conversation>()
+  for (const conversation of props.conversations) {
+    map.set(getConversationKey(conversation), conversation)
+  }
+  return map
+})
+
+/** 隐藏集合：每次过滤复用 */
+const hideSet = computed(() => new Set(props.hideKeys))
+
+/** 已选集合：圆形指示器 isSelected 走 set 快查 */
+const selectedSet = computed(() => new Set(props.selectedKeys))
+
+/** 候选会话：剔除 hideKeys */
+const candidateConversations = computed(() =>
+  props.conversations.filter((c) => !hideSet.value.has(getConversationKey(c)))
+)
+
+/** 左栏展示列表：在候选基础上按 keyword 过滤 */
+const shownConversations = computed(() =>
+  filterConversationsByKeyword(candidateConversations.value, keyword.value)
+)
+
+/** 最近转发的会话对象列表：从 recentForwardConversationKeys 反查；剔除 hide / 不存在的 key */
+const recentForwardConversations = computed(() =>
+  props.recentForwardConversationKeys
+    .map((key) => byKey.value.get(key))
+    .filter((c): c is Conversation => c != null && !hideSet.value.has(getConversationKey(c)))
+)
+
+/** 是否展示「最近转发」段：keyword 为空 + 有数据时才展示，搜索时让位 */
+const showRecentSection = computed(
+  () => !keyword.value.trim() && recentForwardConversations.value.length > 0
+)
+
+/** 已选会话列表：按 selectedKeys 数组顺序（即点击顺序）反查；过滤 hideSet 避免父组件动态隐藏的会话仍在右侧渲染 / 提交 */
+const selectedConversations = computed(() =>
+  props.selectedKeys
+    .map((key) => byKey.value.get(key))
+    .filter(
+      (conversation): conversation is Conversation =>
+        conversation != null && !hideSet.value.has(getConversationKey(conversation))
+    )
+)
+
+/** 右栏标题文案：单选「发送给」、多选「分别发送给」 */
+const sendTitle = computed(() => (props.selectedKeys.length > 1 ? '分别发送给' : '发送给'))
+
+/** 是否已选中：左栏圆形指示器 / 最近转发头像角标共用 */
+function isSelected(conversation: Conversation): boolean {
+  return selectedSet.value.has(getConversationKey(conversation))
+}
+
+/** 「最近转发」头像点击：移除模式下不切勾选（移除由 × 角标处理） */
+function handleRecentTileClick(conversation: Conversation) {
+  if (recentRemoveMode.value) {
+    return
+  }
+  handleToggle(conversation)
+}
+
+/** 切换选中态：左栏 row / 最近转发头像 / 右栏 × 移除都走这里 */
+function handleToggle(conversation: Conversation) {
+  const key = getConversationKey(conversation)
+  const next = [...props.selectedKeys]
+  const index = next.indexOf(key)
+  if (index === -1) {
+    // 父组件标记隐藏的会话即便有路径触达也不应入选
+    if (hideSet.value.has(key)) {
+      return
+    }
+    if (props.maxSize > 0 && next.length >= props.maxSize) {
+      ElMessage.error(`最多选择 ${props.maxSize} 个会话`)
+      return
+    }
+    next.push(key)
+  } else {
+    next.splice(index, 1)
+  }
+  emit('update:selectedKeys', next)
+}
+</script>
+
+<template>
+  <!--
+    会话选择面板：用于推荐名片 / 转发消息等"选已有会话"场景
+    - 左：搜索 + 最近转发横向头像 + 创建聊天入口 + 最近聊天列表（圆形勾选）
+    - 右：已选数标题 + 已选会话列表（按点击顺序）+ footer slot
+    - Panel 不带 el-dialog 壳；dialog 由业务壳持有
+    - footer slot 渲染在右栏已选列表下方，业务壳放预览卡 / 留言 / 提交按钮
+  -->
+  <div class="flex h-full">
+    <!-- 左栏 -->
+    <div
+      class="flex flex-col w-[280px] border-r border-r-solid border-[var(--ant-color-border-secondary)] bg-[var(--ant-color-fill-secondary)]"
+    >
+      <!-- 搜索框 -->
+      <div class="flex-shrink-0 px-3 py-2">
+        <ElInput v-model="keyword" placeholder="搜索" clearable>
+          <template #prefix>
+            <Icon icon="ant-design:search-outlined" />
+          </template>
+        </ElInput>
+      </div>
+
+      <div class="flex-1">
+        <!-- 最近转发横向头像区：keyword 为空 + 有最近转发数据时展示 -->
+        <template v-if="showRecentSection">
+          <div class="flex justify-between items-center pl-3 pr-2 pb-1.5">
+            <span class="text-13px text-[var(--ant-color-text-secondary)]">最近转发</span>
+            <span
+              class="px-1 cursor-pointer text-13px text-[var(--ant-color-primary)] hover:opacity-80"
+              @click="recentRemoveMode = !recentRemoveMode"
+            >
+              {{ recentRemoveMode ? '完成' : '移除' }}
+            </span>
+          </div>
+          <div
+            class="flex gap-2 pl-3 pr-2 pt-1 pb-2 overflow-x-auto im-conversation-picker__recent"
+          >
+            <div
+              v-for="conversation in recentForwardConversations"
+              :key="getConversationKey(conversation)"
+              class="flex flex-col flex-shrink-0 gap-1 items-center"
+              :class="{ 'cursor-pointer': !recentRemoveMode }"
+              @click="handleRecentTileClick(conversation)"
+            >
+              <div class="relative">
+                <GroupAvatar
+                  v-if="conversation.type === ImConversationType.GROUP"
+                  :group-id="conversation.targetId"
+                  :url="conversation.avatar"
+                  :name="conversation.name"
+                  :size="36"
+                />
+                <UserAvatar
+                  v-else
+                  :url="conversation.avatar"
+                  :name="conversation.name"
+                  :size="36"
+                  :clickable="false"
+                />
+                <!-- 移除模式：右上角 × 圆角标，点击把这条 key 从 recentForwardConversationKeys 删掉 -->
+                <span
+                  v-if="recentRemoveMode"
+                  class="flex absolute -top-1 -right-1 justify-center items-center w-4 h-4 rounded-full cursor-pointer bg-[var(--ant-color-fill-dark)] text-[var(--ant-color-text)]"
+                  @click.stop="emit('removeRecent', getConversationKey(conversation))"
+                >
+                  <Icon icon="ant-design:close-outlined" :size="10" />
+                </span>
+                <!-- 非移除模式：右上角圆形勾选指示器；未选灰空心圈、选中绿底白对勾 -->
+                <span
+                  v-else
+                  class="flex absolute -top-1 -right-1 justify-center items-center w-4 h-4 rounded-full transition-colors"
+                  :class="
+                    isSelected(conversation)
+                      ? 'bg-[#07c160] border border-solid border-[#07c160]'
+                      : 'border border-solid border-[var(--ant-color-border)] bg-[var(--ant-color-bg-container)]'
+                  "
+                >
+                  <Icon
+                    v-if="isSelected(conversation)"
+                    icon="ant-design:check-outlined"
+                    :size="10"
+                    color="#fff"
+                  />
+                </span>
+              </div>
+              <span
+                class="overflow-hidden max-w-[48px] text-12px truncate text-[var(--ant-color-text)]"
+              >
+                {{ conversation.name }}
+              </span>
+            </div>
+          </div>
+        </template>
+
+        <!-- 创建聊天入口：keyword 为空 + showCreateChat=true 时展示 -->
+        <div
+          v-if="showCreateChat && !keyword.trim()"
+          class="flex gap-2.5 items-center px-3 py-1.5 cursor-pointer hover:bg-[var(--ant-color-fill)]"
+          @click="emit('createChat')"
+        >
+          <span
+            class="flex flex-shrink-0 justify-center items-center w-8 h-8 rounded-full bg-[var(--ant-color-fill)] text-[var(--ant-color-text-secondary)]"
+          >
+            <Icon icon="ant-design:plus-outlined" :size="16" />
+          </span>
+          <span class="text-sm text-[var(--ant-color-text)]">创建聊天</span>
+        </div>
+
+        <!-- 最近聊天分组标题 -->
+        <div class="px-3 pb-1.5 text-13px text-[var(--ant-color-text-secondary)]">最近聊天</div>
+
+        <!-- 会话列表 -->
+        <div
+          v-for="conversation in shownConversations"
+          :key="getConversationKey(conversation)"
+          class="flex gap-2.5 items-center px-3 py-1.5 cursor-pointer hover:bg-[var(--ant-color-fill)]"
+          @click="handleToggle(conversation)"
+        >
+          <!-- 圆形勾选指示器：未选灰色空心圆，选中实心微信绿 + 白对勾 -->
+          <span
+            class="flex flex-shrink-0 justify-center items-center w-5 h-5 rounded-full transition-colors"
+            :class="
+              isSelected(conversation)
+                ? 'bg-[#07c160] border border-solid border-[#07c160]'
+                : 'border border-solid border-[var(--ant-color-border)] bg-[var(--ant-color-bg-container)]'
+            "
+          >
+            <Icon
+              v-if="isSelected(conversation)"
+              icon="ant-design:check-outlined"
+              :size="12"
+              color="#fff"
+            />
+          </span>
+          <GroupAvatar
+            v-if="conversation.type === ImConversationType.GROUP"
+            :group-id="conversation.targetId"
+            :url="conversation.avatar"
+            :name="conversation.name"
+            :size="32"
+          />
+          <UserAvatar
+            v-else
+            :url="conversation.avatar"
+            :name="conversation.name"
+            :size="32"
+            :clickable="false"
+          />
+          <span
+            class="flex-1 min-w-0 overflow-hidden text-sm truncate text-[var(--ant-color-text)]"
+          >
+            {{ conversation.name }}
+          </span>
+        </div>
+
+        <!-- 空态 -->
+        <div
+          v-if="shownConversations.length === 0"
+          class="py-10 text-13px text-center text-[var(--ant-color-text-disabled)]"
+        >
+          {{ keyword ? '没有满足条件的会话' : '暂无会话' }}
+        </div>
+      </div>
+    </div>
+
+    <!-- 右栏 -->
+    <div class="flex flex-col flex-1 min-w-0">
+      <!-- 标题：选 0/1「发送给」、多个「分别发送给」（与微信文案一致） -->
+      <div
+        class="flex-shrink-0 px-4 py-3 border-b border-b-solid text-13px text-[var(--ant-color-text-secondary)] border-[var(--ant-color-border-secondary)]"
+      >
+        {{ sendTitle }}
+      </div>
+
+      <!-- 已选预览：按 selectedKeys 数组顺序（点击顺序）展示 -->
+      <div class="flex-1">
+        <div
+          v-for="conversation in selectedConversations"
+          :key="getConversationKey(conversation)"
+          class="flex gap-2.5 items-center px-4 py-2"
+        >
+          <GroupAvatar
+            v-if="conversation.type === ImConversationType.GROUP"
+            :group-id="conversation.targetId"
+            :url="conversation.avatar"
+            :name="conversation.name"
+            :size="32"
+          />
+          <UserAvatar
+            v-else
+            :url="conversation.avatar"
+            :name="conversation.name"
+            :size="32"
+            :clickable="false"
+          />
+          <span
+            class="flex-1 min-w-0 overflow-hidden text-sm truncate text-[var(--ant-color-text)]"
+          >
+            {{ conversation.name }}
+          </span>
+          <Icon
+            icon="ant-design:close-outlined"
+            :size="14"
+            class="flex-shrink-0 cursor-pointer transition-colors text-[var(--ant-color-text-placeholder)] hover:text-[var(--ant-color-error)]"
+            @click="handleToggle(conversation)"
+          />
+        </div>
+        <div
+          v-if="selectedConversations.length === 0"
+          class="py-10 text-13px text-center text-[var(--ant-color-text-disabled)]"
+        >
+          从左侧选择好友或群聊
+        </div>
+      </div>
+
+      <!-- 业务壳塞预览卡 / 留言 / 提交按钮的位置 -->
+      <div
+        v-if="$slots.footer"
+        class="flex-shrink-0 border-t border-t-solid border-[var(--ant-color-border-secondary)]"
+      >
+        <slot name="footer"></slot>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* 横向滚动条做窄一点避免占视觉；走 ::-webkit-scrollbar 浏览器伪元素 */
+.im-conversation-picker__recent::-webkit-scrollbar {
+  height: 4px;
+}
+.im-conversation-picker__recent::-webkit-scrollbar-thumb {
+  background-color: var(--ant-color-border);
+  border-radius: 2px;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/picker/friend-picker-panel.vue b/apps/web-ele/src/views/im/home/components/picker/friend-picker-panel.vue
new file mode 100644
index 000000000..8698a0c47
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/picker/friend-picker-panel.vue
@@ -0,0 +1,245 @@
+<script lang="ts" setup>
+import type { FriendLite } from '../../types'
+
+import { computed, ref } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElInput, ElMessage } from 'element-plus'
+
+import { PagedScroller } from '..'
+import { useFriendBuckets } from '../../composables/useFriendBuckets'
+import { useSelectedItems } from '../../composables/useSelectedItems'
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImFriendPickerPanel' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 禁用 id：列表里展示置灰、不可勾选、不计入已选数（典型：邀请入群时已在群成员） */
+    disabledIds?: number[]
+    /** 全量好友列表 */
+    friends: FriendLite[]
+    /** 隐藏 id：不展示（hide > locked > disabled） */
+    hideIds?: number[]
+    /** 锁定 id：默认勾选、不可取消、计入已选数（典型：私聊侧 +建群锁定对方） */
+    lockedIds?: number[]
+    /** 已选数上限；不传或 <=0 时不限 */
+    maxSize?: number
+    /** 已选好友 id（v-model）；按数组顺序即为点击顺序 */
+    selectedIds: number[]
+  }>(),
+  {
+    lockedIds: () => [],
+    disabledIds: () => [],
+    hideIds: () => [],
+    maxSize: 0
+  }
+)
+
+const emit = defineEmits<{
+  'update:selectedIds': [value: number[]]
+}>()
+
+const keyword = ref('')
+
+/** id → friend 映射，已选反查 / 三态判定共用，避免每次 O(N) 扫 */
+const byId = computed(() => {
+  const map = new Map<number, FriendLite>()
+  for (const friend of props.friends) {
+    map.set(friend.id, friend)
+  }
+  return map
+})
+
+/** 三态 id 集合：每次过滤复用 */
+const hideSet = computed(() => new Set(props.hideIds))
+const lockedSet = computed(() => new Set(props.lockedIds))
+const disabledSet = computed(() => new Set(props.disabledIds))
+const selectedSet = computed(() => new Set(props.selectedIds))
+
+/** 候选好友：剔除 hideIds（hide 优先级最高） */
+const candidates = computed(() =>
+  props.friends.filter((friend) => !hideSet.value.has(friend.id))
+)
+
+/** 委托 useFriendBuckets：搜索规则复用，左侧列表按滚动分页渲染 */
+const { filtered } = useFriendBuckets(candidates, keyword)
+
+/** 已选数 + 已选好友列表：三态优先级 + 顺序拼接由 useSelectedItems 统一承担 */
+const { selectedCount, selectedItems: selectedFriends } = useSelectedItems<FriendLite>(
+  () => props.selectedIds,
+  () => props.lockedIds,
+  () => props.disabledIds,
+  () => props.hideIds,
+  byId
+)
+
+/** 是否被锁定 */
+function isLocked(friend: FriendLite): boolean {
+  return lockedSet.value.has(friend.id)
+}
+
+/** 是否被禁用：locked / hide 已被前置过滤，剩下的才算 disabled */
+function isDisabled(friend: FriendLite): boolean {
+  return !lockedSet.value.has(friend.id) && disabledSet.value.has(friend.id)
+}
+
+/** 是否选中：locked 视为永远选中 */
+function isSelected(friend: FriendLite): boolean {
+  return selectedSet.value.has(friend.id)
+}
+
+/** 圆形勾选指示器的 class：选中 / 锁定走绿底，禁用灰底，未选空心圆 */
+function getCheckClass(friend: FriendLite): string {
+  if (isLocked(friend) || isSelected(friend)) {
+    return 'bg-[#07c160] border border-solid border-[#07c160]'
+  }
+  if (isDisabled(friend)) {
+    return 'bg-[var(--ant-color-fill)] border border-solid border-[var(--ant-color-border)]'
+  }
+  return 'border border-solid border-[var(--ant-color-border)] bg-[var(--ant-color-bg-container)]'
+}
+
+/** 切换选中态：locked / disabled 不响应；右栏 × 移除 / 行 click 都走这里 */
+function handleToggle(friend: FriendLite) {
+  if (isLocked(friend) || isDisabled(friend)) {
+    return
+  }
+  const next = [...props.selectedIds]
+  const index = next.indexOf(friend.id)
+  if (index === -1) {
+    if (props.maxSize > 0 && selectedCount.value >= props.maxSize) {
+      ElMessage.error(`最多选择 ${props.maxSize} 位好友`)
+      return
+    }
+    next.push(friend.id)
+  } else {
+    next.splice(index, 1)
+  }
+  emit('update:selectedIds', next)
+}
+</script>
+
+<template>
+  <!--
+    好友选择面板：用于「新建群聊 / 邀请好友 / 推荐时创建聊天」等好友选择场景
+    - 左：搜索 + 好友列表（圆形勾选）
+    - 右：已选数标题 + 已选好友列表（按点击顺序）
+    - Panel 不带 el-dialog 壳；dialog 由业务壳持有
+    - 三态语义：hide > locked > disabled（详见 contract）
+  -->
+  <div class="flex h-full">
+    <!-- 左栏 -->
+    <div
+      class="flex flex-col flex-1 min-w-0 border-r border-r-solid border-[var(--ant-color-border-secondary)] bg-[var(--ant-color-fill-secondary)]"
+    >
+      <!-- 搜索框 -->
+      <div class="flex-shrink-0 px-3 py-2">
+        <ElInput v-model="keyword" placeholder="搜索好友" clearable>
+          <template #prefix>
+            <Icon icon="ant-design:search-outlined" />
+          </template>
+        </ElInput>
+      </div>
+
+      <div class="flex-1 min-h-0">
+        <PagedScroller v-if="filtered.length > 0" :items="filtered" :page-size="30" item-key="id">
+          <template #default="{ item }">
+            <div
+              :key="(item as FriendLite).id"
+              class="flex gap-2.5 items-center px-3 py-2 cursor-pointer hover:bg-[var(--ant-color-fill)]"
+              :class="{
+                'opacity-60 cursor-not-allowed hover:bg-transparent': isDisabled(item as FriendLite)
+              }"
+              @click="handleToggle(item as FriendLite)"
+            >
+              <!-- 圆形勾选指示器：未选灰色空心圆，选中实心微信绿 + 白对勾；锁定 / 禁用走灰底 -->
+              <span
+                class="flex flex-shrink-0 justify-center items-center w-5 h-5 rounded-full transition-colors"
+                :class="getCheckClass(item as FriendLite)"
+              >
+                <Icon
+                  v-if="isSelected(item as FriendLite) || isLocked(item as FriendLite)"
+                  icon="ant-design:check-outlined"
+                  :size="12"
+                  color="#fff"
+                />
+              </span>
+              <UserAvatar
+                :id="(item as FriendLite).id"
+                :url="(item as FriendLite).avatar"
+                :name="(item as FriendLite).nickname"
+                :size="36"
+                :clickable="false"
+              />
+              <!-- 行内名字：备注优先，列表里不重复展示昵称 -->
+              <span
+                class="flex-1 min-w-0 overflow-hidden text-sm truncate text-[var(--ant-color-text)]"
+              >
+                {{ (item as FriendLite).displayName || (item as FriendLite).nickname }}
+              </span>
+            </div>
+          </template>
+        </PagedScroller>
+        <div v-else class="py-10 text-13px text-center text-[var(--ant-color-text-disabled)]">
+          {{ keyword ? '没有匹配的好友' : '暂无好友' }}
+        </div>
+      </div>
+    </div>
+
+    <!-- 右栏 -->
+    <div class="flex flex-col flex-1 min-w-0">
+      <!-- 标题：已选数；高度对齐左侧 input default（32px），保证两侧第一项起点同水平 -->
+      <div
+        class="flex-shrink-0 h-12 px-4 leading-[3rem] border-b border-b-solid text-13px text-[var(--ant-color-text-secondary)] border-[var(--ant-color-border-secondary)]"
+      >
+        已选择 {{ selectedCount }} 个好友
+      </div>
+
+      <!-- 已选预览：按 selectedIds + lockedIds 数组顺序（点击顺序）展示 -->
+      <div class="flex-1">
+        <div
+          v-for="friend in selectedFriends"
+          :key="friend.id"
+          class="flex gap-2.5 items-center px-4 py-2"
+        >
+          <UserAvatar
+            :id="friend.id"
+            :url="friend.avatar"
+            :name="friend.nickname"
+            :size="36"
+            :clickable="false"
+          />
+          <span
+            class="flex-1 min-w-0 overflow-hidden text-sm truncate text-[var(--ant-color-text)]"
+          >
+            {{ friend.displayName || friend.nickname }}
+          </span>
+          <!-- 锁定项不渲染 ×，避免误以为可移除 -->
+          <Icon
+            v-if="!isLocked(friend)"
+            icon="ant-design:close-outlined"
+            :size="14"
+            class="flex-shrink-0 cursor-pointer transition-colors text-[var(--ant-color-text-placeholder)] hover:text-[var(--ant-color-error)]"
+            @click="handleToggle(friend)"
+          />
+        </div>
+        <div
+          v-if="selectedFriends.length === 0"
+          class="py-10 text-13px text-center text-[var(--ant-color-text-disabled)]"
+        >
+          请从左侧选择好友
+        </div>
+      </div>
+
+      <!-- 业务壳塞额外内容的位置；FriendPickerPanel 主流场景不需要 footer -->
+      <div
+        v-if="$slots.footer"
+        class="flex-shrink-0 border-t border-t-solid border-[var(--ant-color-border-secondary)]"
+      >
+        <slot name="footer"></slot>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/picker/group-member-picker-panel.vue b/apps/web-ele/src/views/im/home/components/picker/group-member-picker-panel.vue
new file mode 100644
index 000000000..7aa5fbab3
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/picker/group-member-picker-panel.vue
@@ -0,0 +1,242 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from '../group'
+
+import { computed, ref } from 'vue'
+
+import { CommonStatusEnum } from '@vben/constants'
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElInput, ElMessage } from 'element-plus'
+
+import { PagedScroller } from '..'
+import { useSelectedItems } from '../../composables/useSelectedItems'
+import { GroupMemberGrid, GroupMemberItem } from '../group'
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImGroupMemberPickerPanel' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 禁用 userId：列表里展示置灰、不可勾选、不计入已选数 */
+    disabledIds?: number[]
+    /** 隐藏 userId：不展示（hide > locked > disabled） */
+    hideIds?: number[]
+    /** 锁定 userId：默认勾选、不可取消、计入已选数 */
+    lockedIds?: number[]
+    /** 已选数上限；不传或 <=0 时不限 */
+    maxSize?: number
+    /** 群成员列表 */
+    members: GroupMemberLite[]
+    /** 已选区展示形态：默认 list 对齐微信新视觉 */
+    selectedDisplay?: 'grid' | 'list'
+    /** 已选 userId（v-model）；按数组顺序即为点击顺序 */
+    selectedIds: number[]
+  }>(),
+  {
+    lockedIds: () => [],
+    disabledIds: () => [],
+    hideIds: () => [],
+    maxSize: 0,
+    selectedDisplay: 'list'
+  }
+)
+
+const emit = defineEmits<{
+  'update:selectedIds': [value: number[]]
+}>()
+
+const keyword = ref('')
+
+/** userId → member 映射，已选反查 / 三态判定共用 */
+const byId = computed(() => {
+  const map = new Map<number, GroupMemberLite>()
+  for (const member of props.members) {
+    map.set(member.userId, member)
+  }
+  return map
+})
+
+const hideSet = computed(() => new Set(props.hideIds))
+const lockedSet = computed(() => new Set(props.lockedIds))
+const disabledSet = computed(() => new Set(props.disabledIds))
+const selectedSet = computed(() => new Set(props.selectedIds))
+
+/** 当前展示的成员：剔除 hideIds、剔除已退群（DISABLE）、按关键字大小写无关过滤 */
+const shownMembers = computed(() => {
+  const keywordLower = keyword.value.trim().toLowerCase()
+  return props.members.filter(
+    (member) =>
+      !hideSet.value.has(member.userId) &&
+      member.status !== CommonStatusEnum.DISABLE &&
+      (!keywordLower || member.showName.toLowerCase().includes(keywordLower))
+  )
+})
+
+/** 已选数 + 已选成员列表：三态优先级 + 顺序拼接由 useSelectedItems 统一承担 */
+const { selectedCount, selectedItems: selectedMembers } = useSelectedItems<GroupMemberLite>(
+  () => props.selectedIds,
+  () => props.lockedIds,
+  () => props.disabledIds,
+  () => props.hideIds,
+  byId
+)
+
+/** 是否被锁定 */
+function isLocked(member: GroupMemberLite): boolean {
+  return lockedSet.value.has(member.userId)
+}
+
+/** 是否被禁用：locked / hide 已被前置过滤，剩下的才算 disabled */
+function isDisabled(member: GroupMemberLite): boolean {
+  return !lockedSet.value.has(member.userId) && disabledSet.value.has(member.userId)
+}
+
+/** 是否选中：locked 视为永远选中 */
+function isSelected(member: GroupMemberLite): boolean {
+  return selectedSet.value.has(member.userId)
+}
+
+/** 圆形勾选指示器的 class */
+function getCheckClass(member: GroupMemberLite): string {
+  if (isLocked(member) || isSelected(member)) {
+    return 'bg-[#07c160] border border-solid border-[#07c160]'
+  }
+  if (isDisabled(member)) {
+    return 'bg-[var(--ant-color-fill)] border border-solid border-[var(--ant-color-border)]'
+  }
+  return 'border border-solid border-[var(--ant-color-border)] bg-[var(--ant-color-bg-container)]'
+}
+
+/** 切换选中态：locked / disabled 不响应；右栏 × / 行 click 都走这里 */
+function handleToggle(member: GroupMemberLite) {
+  if (isLocked(member) || isDisabled(member)) {
+    return
+  }
+  const next = [...props.selectedIds]
+  const index = next.indexOf(member.userId)
+  if (index === -1) {
+    if (props.maxSize > 0 && selectedCount.value >= props.maxSize) {
+      ElMessage.error(`最多选择 ${props.maxSize} 位成员`)
+      return
+    }
+    next.push(member.userId)
+  } else {
+    next.splice(index, 1)
+  }
+  emit('update:selectedIds', next)
+}
+</script>
+
+<template>
+  <!--
+    群成员选择面板：用于「移除成员 / 设置管理员 / 转让群主 / 禁言成员」等场景
+    - 左：搜索 + 群成员列表（圆形勾选）
+    - 右：已选数标题 + 已选成员（list / grid 两种形态可配，默认 list 对齐微信新视觉）
+    - Panel 不带 el-dialog 壳；dialog 由业务壳持有
+    - 三态语义：hide > locked > disabled
+  -->
+  <div class="flex h-full">
+    <!-- 左栏 -->
+    <div
+      class="flex flex-col flex-1 min-w-0 border-r border-r-solid border-[var(--ant-color-border-secondary)] bg-[var(--ant-color-fill-secondary)]"
+    >
+      <!-- 搜索框 -->
+      <div class="flex-shrink-0 px-3 py-2">
+        <ElInput v-model="keyword" placeholder="搜索成员" clearable>
+          <template #prefix>
+            <Icon icon="ant-design:search-outlined" />
+          </template>
+        </ElInput>
+      </div>
+
+      <div class="flex-1 min-h-0">
+        <PagedScroller :items="shownMembers" :page-size="30" item-key="userId">
+          <template #default="{ item }">
+            <GroupMemberItem
+              :member="item as GroupMemberLite"
+              :height="46"
+              @click="handleToggle(item as GroupMemberLite)"
+            >
+              <span
+                class="flex flex-shrink-0 justify-center items-center w-5 h-5 rounded-full transition-colors"
+                :class="getCheckClass(item as GroupMemberLite)"
+              >
+                <Icon
+                  v-if="isSelected(item as GroupMemberLite) || isLocked(item as GroupMemberLite)"
+                  icon="ant-design:check-outlined"
+                  :size="12"
+                  color="#fff"
+                />
+              </span>
+            </GroupMemberItem>
+          </template>
+        </PagedScroller>
+      </div>
+    </div>
+
+    <!-- 右栏 -->
+    <div class="flex flex-col flex-1 min-w-0">
+      <!-- 标题：已选数；高度对齐左侧 input default（32px） -->
+      <div
+        class="flex-shrink-0 h-12 px-4 leading-[3rem] border-b border-b-solid text-13px text-[var(--ant-color-text-secondary)] border-[var(--ant-color-border-secondary)]"
+      >
+        已选择 {{ selectedCount }} 位成员
+      </div>
+
+      <div class="flex-1">
+        <!-- list 形态：纵向行，每行带 × 移除（locked 不渲染 ×） -->
+        <template v-if="selectedDisplay === 'list'">
+          <div
+            v-for="member in selectedMembers"
+            :key="member.userId"
+            class="flex gap-2.5 items-center px-4 py-2"
+          >
+            <UserAvatar
+              :id="member.userId"
+              :url="member.avatar"
+              :name="member.nickname"
+              :size="36"
+              :clickable="false"
+            />
+            <span
+              class="flex-1 min-w-0 overflow-hidden text-sm truncate text-[var(--ant-color-text)]"
+            >
+              {{ member.showName }}
+            </span>
+            <Icon
+              v-if="!isLocked(member)"
+              icon="ant-design:close-outlined"
+              :size="14"
+              class="flex-shrink-0 cursor-pointer transition-colors text-[var(--ant-color-text-placeholder)] hover:text-[var(--ant-color-error)]"
+              @click="handleToggle(member)"
+            />
+          </div>
+        </template>
+
+        <!-- grid 形态：宫格预览；非 locked 成员右上角叠加 × 移除（locked 不渲染） -->
+        <div v-else class="flex flex-wrap p-2.5">
+          <GroupMemberGrid
+            v-for="member in selectedMembers"
+            :key="member.userId"
+            :member="member"
+          >
+            <Icon
+              v-if="!isLocked(member)"
+              icon="ant-design:close-circle-filled"
+              :size="16"
+              class="absolute top-0 right-0 cursor-pointer transition-colors text-[var(--ant-color-text-placeholder)] hover:text-[var(--ant-color-error)]"
+              @click="handleToggle(member)"
+            />
+          </GroupMemberGrid>
+        </div>
+
+        <div
+          v-if="selectedMembers.length === 0"
+          class="py-10 text-13px text-center text-[var(--ant-color-text-disabled)]"
+        >
+          请从左侧选择成员
+        </div>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/picker/index.ts b/apps/web-ele/src/views/im/home/components/picker/index.ts
new file mode 100644
index 000000000..7a534a832
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/picker/index.ts
@@ -0,0 +1,3 @@
+export { default as ConversationPickerPanel } from './conversation-picker-panel.vue';
+export { default as FriendPickerPanel } from './friend-picker-panel.vue';
+export { default as GroupMemberPickerPanel } from './group-member-picker-panel.vue';
diff --git a/apps/web-ele/src/views/im/home/components/picker/picker-dialog.scss b/apps/web-ele/src/views/im/home/components/picker/picker-dialog.scss
new file mode 100644
index 000000000..629b8565e
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/picker/picker-dialog.scss
@@ -0,0 +1,13 @@
+// IM 选择类弹窗的公共样式 mixin
+// 每个业务壳在自己的 <style scoped lang="scss"> 内 @use + @include 即可，避免全局污染
+@mixin styles {
+  :deep(.el-dialog__body) {
+    padding: 0;
+    border-top: 1px solid var(--ant-color-border-secondary);
+  }
+
+  :deep(.el-dialog__header) {
+    margin-right: 0;
+    padding-bottom: 16px;
+  }
+}
diff --git a/apps/web-ele/src/views/im/home/components/resizable-aside.vue b/apps/web-ele/src/views/im/home/components/resizable-aside.vue
new file mode 100644
index 000000000..48ce10425
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/resizable-aside.vue
@@ -0,0 +1,111 @@
+<script lang="ts" setup>
+import { onBeforeUnmount, onMounted, ref } from 'vue'
+
+defineOptions({ name: 'ImResizableAside' })
+
+const props = withDefaults(
+  defineProps<{
+    defaultWidth?: number // 默认宽度
+    maxWidth?: number // 最大宽度
+    minWidth?: number // 最小宽度
+    storageKey: string // localStorage 存储 key，必填；调用方传 StorageKeys.localStorage.asideWidth
+  }>(),
+  {
+    defaultWidth: 260,
+    minWidth: 200,
+    maxWidth: 500
+  }
+)
+
+const asideWidth = ref<number>(props.defaultWidth)
+const isResizing = ref(false)
+let startX = 0
+let startWidth = 0
+
+onMounted(() => {
+  const saved = localStorage.getItem(props.storageKey)
+  if (saved) {
+    const w = Number.parseInt(saved, 10)
+    if (!Number.isNaN(w)) {
+      asideWidth.value = clamp(w)
+    }
+  }
+  document.addEventListener('mousemove', handleResize)
+  document.addEventListener('mouseup', stopResize)
+})
+
+onBeforeUnmount(() => {
+  // 拖拽中卸载：复用 stopResize 复位 body cursor/userSelect 并写回当前宽度，避免全局状态泄漏
+  if (isResizing.value) {
+    stopResize()
+  }
+  document.removeEventListener('mousemove', handleResize)
+  document.removeEventListener('mouseup', stopResize)
+})
+
+/** 把宽度夹到 [minWidth, maxWidth] 区间，恢复 / 拖拽路径都走它兜底 */
+function clamp(w: number) {
+  return Math.max(props.minWidth, Math.min(props.maxWidth, w))
+}
+
+/** 按下拖拽手柄：记录起始位置 + 锁定 body cursor/userSelect，避免拖拽中误选文本 */
+function startResize(e: MouseEvent) {
+  isResizing.value = true
+  startX = e.clientX
+  startWidth = asideWidth.value
+  document.body.style.cursor = 'col-resize'
+  document.body.style.userSelect = 'none'
+  e.preventDefault()
+}
+
+/** 拖拽中：按鼠标位移计算新宽度并 clamp 到允许区间 */
+function handleResize(e: MouseEvent) {
+  if (!isResizing.value) {
+    return
+  }
+  const deltaX = e.clientX - startX
+  asideWidth.value = clamp(startWidth + deltaX)
+}
+
+/** 松开鼠标：解锁 body 全局态并把当前宽度写入 localStorage 持久化 */
+function stopResize() {
+  if (!isResizing.value) {
+    return
+  }
+  isResizing.value = false
+  document.body.style.cursor = ''
+  document.body.style.userSelect = ''
+  localStorage.setItem(props.storageKey, String(asideWidth.value))
+}
+</script>
+
+<template>
+  <!--
+    可拖拽宽度的左侧 Aside
+    - 使用 localStorage 记住用户上次调整的宽度（storageKey 必填）
+    - 拖拽区在右边缘，鼠标变 col-resize
+  -->
+  <aside
+    class="relative flex flex-col shrink-0 bg-[var(--ant-color-fill-secondary)] border-r border-r-solid border-[var(--im-border-color-lighter)] shadow-[2px_0_8px_rgba(0,0,0,0.05)]"
+    :style="{ width: `${asideWidth }px` }"
+  >
+    <slot></slot>
+    <div
+      class="im-resizable-aside__handle absolute top-0 right--0.75 z-10 flex items-center justify-center w-1.5 h-full cursor-col-resize transition-colors"
+      :class="{ 'is-resizing': isResizing }"
+      content="拖拽调整宽度"
+      @mousedown="startResize"
+    >
+      <div class="im-resizable-aside__line w-0.5 h-full rounded-0.5 bg-transparent transition-all"></div>
+    </div>
+  </aside>
+</template>
+
+<style scoped>
+/* hover / 拖拽中 把内部 line 加粗变深，提示手柄可拖；状态在父 handle 上 → 通过后代选择器联动子 line */
+.im-resizable-aside__handle:hover .im-resizable-aside__line,
+.im-resizable-aside__handle.is-resizing .im-resizable-aside__line {
+  width: 3px;
+  background-color: var(--im-resize-line-color);
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/rtc/index.ts b/apps/web-ele/src/views/im/home/components/rtc/index.ts
new file mode 100644
index 000000000..fafdd7a7e
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/rtc/index.ts
@@ -0,0 +1,8 @@
+export { default as RtcCallContainer } from './rtc-call-container.vue';
+export { default as RtcCallIncoming } from './rtc-call-incoming.vue';
+export { default as RtcCallInviting } from './rtc-call-inviting.vue';
+export { default as RtcCallMemberPickerDialog } from './rtc-call-member-picker-dialog.vue';
+export { default as RtcCallParticipantTile } from './rtc-call-participant-tile.vue';
+export type { CallParticipantVM } from './rtc-call-participant-tile.vue';
+export { default as RtcCallRunning } from './rtc-call-running.vue';
+export { default as RtcGroupCallBanner } from './rtc-group-call-banner.vue';
diff --git a/apps/web-ele/src/views/im/home/components/rtc/rtc-call-container.vue b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-container.vue
new file mode 100644
index 000000000..d38cfbee0
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-container.vue
@@ -0,0 +1,488 @@
+<script lang="ts" setup>
+import type { CallParticipantVM } from './rtc-call-participant-tile.vue'
+
+import { computed, ref, watch } from 'vue'
+
+import { useIntervalFn } from '@vueuse/core'
+import { ElMessage } from 'element-plus'
+import { Track } from 'livekit-client'
+
+import {
+  acceptCall,
+  cancelCall,
+  inviteCall,
+  leaveCall,
+  noAnswerCallCheck,
+  rejectCall
+} from '#/api/im/rtc'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+import { RTC_NO_ANSWER_CALL_CHECK_INTERVAL_MS } from '#/views/im/utils/config'
+import {
+  ImConversationType,
+  ImRtcCallMediaType,
+  ImRtcCallStage
+} from '#/views/im/utils/constants'
+import { getSenderAvatar, getSenderDisplayName } from '#/views/im/utils/user'
+
+import { useLiveKitRoom } from '../../composables/useLiveKitRoom'
+import { useRtcStore } from '../../store/rtcStore'
+import RtcCallIncoming from './rtc-call-incoming.vue'
+import RtcCallInviting from './rtc-call-inviting.vue'
+import RtcCallMemberPickerDialog from './rtc-call-member-picker-dialog.vue'
+import RtcCallRunning from './rtc-call-running.vue'
+
+defineOptions({ name: 'ImRtcCallContainer' })
+
+const rtcStore = useRtcStore()
+const lk = useLiveKitRoom()
+
+const memberPickerRef = ref<InstanceType<typeof RtcCallMemberPickerDialog>>()
+const connecting = ref(false)
+const accepting = ref(false)
+const rejecting = ref(false)
+const cancelling = ref(false)
+const hangingUp = ref(false)
+
+// ==================== 视图模型 ====================
+
+/** 当前是否视频通话 */
+const isVideo = computed(() => {
+  const t =
+    rtcStore.call?.mediaType ||
+    rtcStore.incomingPayload?.mediaType ||
+    ImRtcCallMediaType.VOICE
+  return t === ImRtcCallMediaType.VIDEO
+})
+
+/** 当前是否群通话；决定浮动窗大小 */
+const isGroup = computed(
+  () =>
+    (rtcStore.call?.conversationType ??
+      rtcStore.incomingPayload?.conversationType) === ImConversationType.GROUP
+)
+
+/** 初始摄像头是否打开；群通话默认全部关闭，进入后用户主动开 */
+const initialCamera = computed(() => {
+  if (rtcStore.call?.conversationType === ImConversationType.GROUP) {
+    return false
+  }
+  return isVideo.value
+})
+
+/** 本端视频流；优先 ScreenShare（屏共时也铺底），无则 Camera；显式订阅 screenShareEnabled / cameraEnabled 触发重算 */
+const localStream = computed<MediaStream | null>(() => {
+  // 触摸响应式依赖，确保切屏共享 / 摄像头后 computed 重新求值（pickStream 内部用普通 Map 缓存，自身不响应）
+  void lk.screenShareEnabled.value
+  void lk.cameraEnabled.value
+  const lp = lk.localParticipant.value
+  if (!lp) {
+    return null
+  }
+  return lk.pickStream(lp, Track.Source.ScreenShare) || lk.pickStream(lp, Track.Source.Camera)
+})
+
+/** 远端视频流（仅 1v1 用）；优先 ScreenShare，无则取 Camera */
+const remoteVideoStream = computed<MediaStream | null>(() => {
+  if (isGroup.value) {
+    return null
+  }
+  for (const rp of lk.remoteParticipants.value) {
+    const screen = lk.pickStream(rp, Track.Source.ScreenShare)
+    if (screen) {
+      return screen
+    }
+    const camera = lk.pickStream(rp, Track.Source.Camera)
+    if (camera) {
+      return camera
+    }
+  }
+  return null
+})
+
+/** 远端音频流（仅 1v1 用） */
+const remoteAudioStream = computed<MediaStream | null>(() => {
+  if (isGroup.value) {
+    return null
+  }
+  for (const rp of lk.remoteParticipants.value) {
+    const stream = lk.pickStream(rp, Track.Source.Microphone)
+    if (stream) {
+      return stream
+    }
+  }
+  return null
+})
+
+/** 群通话网格用：自己 + 远端在房 + 待加入成员；昵称 / 头像走 user.ts helper 自动处理 self / 群成员 / 好友 / 兜底 */
+const participants = computed<CallParticipantVM[]>(() => {
+  const call = rtcStore.call
+  if (!call) {
+    return []
+  }
+  const conversationType = call.conversationType
+  const targetId = call.groupId ?? 0
+  const myId = getCurrentUserId()
+  const result: CallParticipantVM[] = [{
+    userId: myId,
+    nickname: getSenderDisplayName(myId, conversationType, targetId),
+    avatar: getSenderAvatar(myId, conversationType, targetId) || undefined,
+    isLocal: true,
+    videoStream: localStream.value
+  }]
+
+  // 已加入的远端：实际推流；屏幕共享在网格里独占该成员的格子，无则降级 Camera
+  const joined = new Set<number>()
+  for (const rp of lk.remoteParticipants.value) {
+    const userId = Number(rp.identity)
+    if (Number.isNaN(userId)) {
+      continue
+    }
+    joined.add(userId)
+    result.push({
+      userId,
+      nickname: getSenderDisplayName(userId, conversationType, targetId),
+      avatar: getSenderAvatar(userId, conversationType, targetId) || undefined,
+      isLocal: false,
+      videoStream:
+        lk.pickStream(rp, Track.Source.ScreenShare) || lk.pickStream(rp, Track.Source.Camera),
+      audioStream: lk.pickStream(rp, Track.Source.Microphone)
+    })
+  }
+
+  // 群通话：未加入的被邀请人作为 pending 占位；已退出 / 已拒绝的人不渲染
+  if (conversationType === ImConversationType.GROUP) {
+    const inviteeIds = call.inviteeIds || []
+    for (const userId of inviteeIds) {
+      if (userId === myId || joined.has(userId) || rtcStore.isUserLeft(userId)) {
+        continue
+      }
+      result.push({
+        userId,
+        nickname: getSenderDisplayName(userId, ImConversationType.GROUP, targetId),
+        avatar: getSenderAvatar(userId, ImConversationType.GROUP, targetId) || undefined,
+        isLocal: false,
+        pending: true
+      })
+    }
+  }
+  return result
+})
+
+// ==================== LiveKit 连接 ====================
+
+/** 连入 LiveKit 房间并注册离开回调；INVITING 主叫预连和被叫 accept 后连入共用 */
+async function connectLiveKit(livekitUrl: string, token: string) {
+  // 幂等：lk.connect 内部进入后就把 room.value 赋值；非空表示已经在连接或已连接；stage 多次切换时重复触发也跳过
+  if (lk.room.value || connecting.value) {
+    return
+  }
+  connecting.value = true
+  try {
+    // 先注册回调，再 connect；信令握手过程会即时推送已在房参与者，业务 handler 必须先就绪
+    lk.onDisconnected(() => handlePeerDisconnected())
+    lk.onParticipantConnected(maybeEnterRunning)
+    lk.onParticipantDisconnected((userId) => rtcStore.markUserLeft(userId))
+    await lk.connect(livekitUrl, token, { audio: true, video: initialCamera.value })
+    // 兜底：connect 期间若已有远端在房，事件可能在 handler 注册前已触发，主动切到 RUNNING
+    if (lk.remoteParticipants.value.length > 0) {
+      maybeEnterRunning()
+    }
+  } finally {
+    connecting.value = false
+  }
+}
+
+/** 主叫端：从 INVITING 切到 RUNNING；其它阶段不处理 */
+function maybeEnterRunning() {
+  if (rtcStore.stage === ImRtcCallStage.INVITING && rtcStore.call) {
+    rtcStore.enterRunning(rtcStore.call)
+  }
+}
+
+watch(
+  () => rtcStore.stage,
+  async (stage) => {
+    if (
+      stage === ImRtcCallStage.INVITING &&
+      rtcStore.call?.token &&
+      rtcStore.call?.livekitUrl
+    ) {
+      try {
+        await connectLiveKit(rtcStore.call.livekitUrl, rtcStore.call.token)
+      } catch (error) {
+        console.error('[Call] connect 失败', { room: rtcStore.call?.room }, error)
+        ElMessage.error('通话连接失败')
+        await handleCancel()
+      }
+    }
+    if (stage === ImRtcCallStage.IDLE) {
+      await lk.disconnect()
+    }
+  }
+)
+
+/** 被叫端 accept 后会拿到 token；这里监听 stage + token 变化触发连接 */
+watch(
+  () => [rtcStore.stage, rtcStore.call?.token],
+  async ([stage, token], [prevStage]) => {
+    if (
+      stage === ImRtcCallStage.RUNNING &&
+      prevStage !== ImRtcCallStage.RUNNING &&
+      token &&
+      !lk.isConnected.value &&
+      rtcStore.call?.livekitUrl
+    ) {
+      try {
+        await connectLiveKit(rtcStore.call.livekitUrl, token as string)
+      } catch (error) {
+        console.error('[Call] accept connect 失败', { room: rtcStore.call?.room }, error)
+        ElMessage.error('通话连接失败')
+        // 后端 accept 已写 JOINED；前端连接失败需调 leave 回滚，避免后端记录残留忙线
+        if (rtcStore.call?.room) {
+          leaveCall(rtcStore.call.room).catch(() => undefined)
+        }
+        rtcStore.reset()
+      }
+    }
+  }
+)
+
+// ==================== 通话生命周期 ====================
+
+/** 主叫取消邀请 */
+async function handleCancel() {
+  if (cancelling.value) {
+    return
+  }
+  cancelling.value = true
+  const room = rtcStore.call?.room
+  try {
+    if (room) {
+      await cancelCall(room)
+    }
+    await lk.disconnect()
+    rtcStore.reset()
+  } finally {
+    cancelling.value = false
+  }
+}
+
+/** 被叫拒绝来电 */
+async function handleReject() {
+  if (rejecting.value) {
+    return
+  }
+  rejecting.value = true
+  const payload = rtcStore.incomingPayload
+  try {
+    if (payload?.room) {
+      await rejectCall(payload.room)
+      // 本端先行从胶囊条移除自己，免等后端 RTC_CALL(REJECTED) 推回；私聊场景 store 内部 no-op
+      rtcStore.applyParticipantRejected({
+        room: payload.room,
+        conversationType: payload.conversationType,
+        groupId: payload.groupId,
+        operatorUserId: getCurrentUserId()
+      })
+    }
+    rtcStore.reset()
+  } finally {
+    rejecting.value = false
+  }
+}
+
+/** 被叫接听来电 */
+async function handleAccept() {
+  if (accepting.value) {
+    return
+  }
+  const payload = rtcStore.incomingPayload
+  if (!payload) return
+  accepting.value = true
+  try {
+    const data = await acceptCall(payload.room)
+    rtcStore.enterRunning(data)
+  } finally {
+    accepting.value = false
+  }
+}
+
+/** 通话中挂断 */
+async function handleHangup() {
+  if (hangingUp.value) {
+    return
+  }
+  hangingUp.value = true
+  const call = rtcStore.call
+  try {
+    if (call?.room) {
+      await leaveCall(call.room)
+      // 本端先行从胶囊条移除自己，免等后端 RTC_PARTICIPANT_DISCONNECTED 推回；私聊场景 store 内部 no-op，整通话由 END 关掉
+      rtcStore.applyParticipantDisconnected({
+        room: call.room,
+        userId: getCurrentUserId(),
+        conversationType: call.conversationType,
+        groupId: call.groupId
+      })
+    }
+    await lk.disconnect()
+    rtcStore.reset()
+  } finally {
+    hangingUp.value = false
+  }
+}
+
+/** LiveKit Room 异常断开；多见于网络中断 */
+function handlePeerDisconnected() {
+  if (!rtcStore.isActive) {
+    return
+  }
+  const room = rtcStore.call?.room
+  // 给 RTC_CALL_END WebSocket 推送一个小窗口；私聊超时 / 主动挂断等场景下，后端 endSession 会先推 RTC_CALL_END，
+  // 让前端按业务语义（"对方未接听" / "已取消" 等）reset，避免错把业务断开 toast 成「通话已断开」
+  setTimeout(() => {
+    if (!rtcStore.isActive) {
+      return
+    }
+    // 上报离开房间
+    if (room) {
+      leaveCall(room).catch(() => undefined)
+    }
+    // 清理本地通话状态
+    ElMessage.warning('通话已断开')
+    rtcStore.reset()
+  }, 100)
+}
+
+// ==================== 振铃超时兜底 ====================
+
+/** 通话存活期间（INVITING / INCOMING / RUNNING）周期性触发后端扫该 room 的超时 INVITING；保持 timer 是为了 inviteCall 追加新人后也能覆盖；阈值由后端配置决定，前端只负责 trigger */
+const { resume: resumeNoAnswerTimer, pause: pauseNoAnswerTimer } = useIntervalFn(
+  triggerNoAnswerCallCheck, RTC_NO_ANSWER_CALL_CHECK_INTERVAL_MS, { immediate: false }
+)
+watch(
+  () => rtcStore.isActive,
+  (active) => (active ? resumeNoAnswerTimer() : pauseNoAnswerTimer()),
+  { immediate: true }
+)
+
+/** 本地仍有 pending 才调；INVITING / RUNNING 取 call、INCOMING 取 incomingPayload；接口静默错误 fire-and-forget */
+function triggerNoAnswerCallCheck() {
+  const source = rtcStore.call ?? rtcStore.incomingPayload
+  if (!source?.room || !source.inviteeIds?.length) {
+    return
+  }
+  noAnswerCallCheck(source.room).catch(() => undefined)
+}
+
+// ==================== 设备控制 ====================
+
+async function toggleMic() {
+  await lk.setMicEnabled(!lk.micEnabled.value)
+}
+async function toggleCamera() {
+  await lk.setCameraEnabled(!lk.cameraEnabled.value)
+}
+function toggleSpeaker() {
+  lk.setSpeakerEnabled(!lk.speakerEnabled.value)
+}
+
+/** 切屏幕共享；浏览器弹原生「选择共享内容」对话框，用户取消时会抛错，UI 不弹提示 */
+async function handleScreenShare() {
+  const enabled = !lk.screenShareEnabled.value
+  try {
+    await lk.setScreenShareEnabled(enabled)
+  } catch (error: any) {
+    // 用户取消选择，不当作错误；其它异常打日志
+    if (error?.name !== 'NotAllowedError' && error?.message !== 'permission denied') {
+      console.warn('[Call] screenShare 切换失败', { enabled }, error)
+    }
+  }
+}
+
+// ==================== 添加成员 ====================
+
+/** 打开「添加成员」弹窗；占位群通话 + 接通中状态才允许 */
+function openAddMember() {
+  const call = rtcStore.call
+  if (!call?.groupId) {
+    return
+  }
+  memberPickerRef.value?.open({
+    groupId: call.groupId,
+    mode: 'add',
+    excludeUserIds: participants.value.map((p) => p.userId)
+  })
+}
+
+/** picker 选完成员；走 invite 追加邀请接口，后端推 RTC_INVITE 给新成员 */
+async function handleAddMemberSuccess(userIds: number[]) {
+  const call = rtcStore.call
+  if (!call?.room || userIds.length === 0) {
+    return
+  }
+  await inviteCall({ room: call.room, inviteeIds: userIds })
+  // 同步本地 inviteeIds，让新成员立即作为 pending 占位出现在网格里
+  rtcStore.appendInvitees(userIds)
+  ElMessage.success('已发送邀请')
+}
+</script>
+
+<template>
+  <!-- 通话阶段对应弹窗；INVITING / INCOMING / RUNNING 三选一互斥 -->
+  <template v-if="rtcStore.isActive">
+    <!-- 主叫端：等待对方接听 -->
+    <RtcCallInviting
+      v-if="rtcStore.stage === ImRtcCallStage.INVITING && rtcStore.call"
+      :peer-nickname="rtcStore.peerNickname"
+      :peer-avatar="rtcStore.peerAvatar"
+      :is-group="isGroup"
+      :is-video="isVideo"
+      :mic-enabled="lk.micEnabled.value"
+      :camera-enabled="lk.cameraEnabled.value"
+      :speaker-enabled="lk.speakerEnabled.value"
+      :local-stream="localStream"
+      @cancel="handleCancel"
+      @toggle-mic="toggleMic"
+      @toggle-camera="toggleCamera"
+      @toggle-speaker="toggleSpeaker"
+    />
+    <!-- 被叫端：来电响铃 -->
+    <RtcCallIncoming
+      v-else-if="rtcStore.stage === ImRtcCallStage.INCOMING"
+      :payload="rtcStore.incomingPayload"
+      :is-group="isGroup"
+      :accepting="accepting"
+      :rejecting="rejecting"
+      @accept="handleAccept"
+      @reject="handleReject"
+    />
+    <!-- 通话进行中：1v1 视频 / 语音 + 群通话宫格 -->
+    <RtcCallRunning
+      v-else-if="rtcStore.stage === ImRtcCallStage.RUNNING && rtcStore.call"
+      :is-group="isGroup"
+      :is-video="isVideo"
+      :mic-enabled="lk.micEnabled.value"
+      :camera-enabled="lk.cameraEnabled.value"
+      :speaker-enabled="lk.speakerEnabled.value"
+      :screen-share-enabled="lk.screenShareEnabled.value"
+      :reconnecting="lk.reconnecting.value"
+      :started-at="rtcStore.startedAt"
+      :participants="participants"
+      :peer-nickname="rtcStore.peerNickname"
+      :peer-avatar="rtcStore.peerAvatar"
+      :local-stream="localStream"
+      :remote-video-stream="remoteVideoStream"
+      :remote-audio-stream="remoteAudioStream"
+      :hanging-up="hangingUp"
+      @hangup="handleHangup"
+      @toggle-mic="toggleMic"
+      @toggle-camera="toggleCamera"
+      @toggle-speaker="toggleSpeaker"
+      @toggle-screen-share="handleScreenShare"
+      @add-member="openAddMember"
+    />
+  </template>
+  <!-- 通话中「添加成员」选人弹窗；挂在 isActive 外，避免 stage 切换瞬间弹窗被卸载 -->
+  <RtcCallMemberPickerDialog ref="memberPickerRef" @success="handleAddMemberSuccess" />
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/rtc/rtc-call-incoming.vue b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-incoming.vue
new file mode 100644
index 000000000..b7e9e4613
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-incoming.vue
@@ -0,0 +1,112 @@
+<script lang="ts" setup>
+import type { ImRtcCallNotification } from '../../store/rtcStore'
+
+import { computed } from 'vue'
+
+import { DICT_TYPE } from '@vben/constants'
+import { getDictLabel } from '@vben/hooks'
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { useGroupCallMembers } from '../../composables/useGroupCallMembers'
+import { UserAvatar } from '../user'
+
+const props = defineProps<{
+  accepting?: boolean
+  isGroup?: boolean
+  payload: ImRtcCallNotification | null
+  rejecting?: boolean
+}>()
+
+defineEmits<{ accept: []; reject: [] }>()
+
+/** 来电提示文案；区分语音 / 视频 */
+const tipText = computed(() => {
+  if (!props.payload) return ''
+  return `邀请你${getDictLabel(DICT_TYPE.IM_RTC_CALL_MEDIA_TYPE, props.payload.mediaType)}通话`
+})
+
+/** 接听按钮禁用态 */
+const acceptDisabled = computed(() => !!props.accepting || !!props.rejecting)
+
+/** 拒绝按钮禁用态 */
+const rejectDisabled = computed(() => !!props.rejecting || !!props.accepting)
+
+// 群通话成员；缓存为空时用 INVITE 载荷里的主叫兜底，避免空白
+const callMembers = useGroupCallMembers(
+  computed(() => (props.isGroup ? props.payload?.groupId : undefined)),
+  computed(() => props.payload?.inviterUserId)
+)
+</script>
+
+<template>
+  <!--
+    被叫端来电小条；参考微信，右上角固定悬浮；
+    群聊：左头像 + 中（邀请人 + 文案一行 / 通话成员行）+ 右下角拒绝 / 接听；
+    私聊：左头像 + 中（邀请人 + 文案两行）+ 右下角拒绝 / 接听
+  -->
+  <div
+    class="fixed top-5 right-5 rounded-2xl overflow-hidden shadow-[0_12px_36px_rgba(0,0,0,0.4)] z-[9999] flex gap-3 items-end p-3 text-white bg-[#2a2a2c]"
+    :class="isGroup ? 'w-[360px]' : 'w-[340px]'"
+  >
+    <!-- 左：邀请者头像 -->
+    <UserAvatar
+      :url="payload?.inviterAvatar"
+      :name="payload?.inviterNickname"
+      :size="48"
+      radius="8px"
+      :clickable="false"
+      class="self-start"
+    />
+
+    <!-- 中：群聊单行（邀请人 + 文案）+ 通话成员；私聊两行（名 / 文案） -->
+    <div class="flex flex-col flex-1 gap-1 self-start min-w-0">
+      <!-- 名 + 文案：群单行内联，私聊上下两行 -->
+      <div v-if="isGroup" class="text-sm truncate">
+        <span class="font-medium">{{ payload?.inviterNickname || '对方' }}</span>
+        <span class="ml-1 text-white/60">{{ tipText }}</span>
+      </div>
+      <template v-else>
+        <div class="text-sm font-medium truncate">{{ payload?.inviterNickname || '对方' }}</div>
+        <div class="text-13px text-white/60 truncate">{{ tipText }}</div>
+      </template>
+
+      <!-- 群通话成员行；私聊无；接入中的人半透明展示 -->
+      <template v-if="isGroup && callMembers.length > 0">
+        <div class="mt-1 text-xs text-white/45">通话成员</div>
+        <div class="flex flex-wrap gap-1">
+          <UserAvatar
+            v-for="member in callMembers"
+            :key="member.userId"
+            :url="member.avatar"
+            :name="member.nickname"
+            :size="22"
+            radius="4px"
+            :clickable="false"
+            :class="{ 'opacity-50': member.pending }"
+            :content="member.pending ? `${member.nickname}（接入中）` : member.nickname"
+          />
+        </div>
+      </template>
+    </div>
+
+    <!-- 右下角：拒绝 / 接听 -->
+    <div class="flex flex-shrink-0 gap-2 items-center">
+      <button
+        class="flex flex-shrink-0 justify-center items-center w-10 h-10 text-white rounded-full transition-opacity bg-[#f04a4a] hover:opacity-90"
+        :class="{ 'opacity-60 cursor-not-allowed': rejectDisabled }"
+        :disabled="rejectDisabled"
+        @click="$emit('reject')"
+      >
+        <Icon icon="ant-design:phone-outlined" :size="18" class="rotate-[135deg]" />
+      </button>
+      <button
+        class="flex flex-shrink-0 justify-center items-center w-10 h-10 text-white rounded-full transition-opacity bg-[#2ec27e] hover:opacity-90"
+        :class="{ 'opacity-60 cursor-not-allowed': acceptDisabled }"
+        :disabled="acceptDisabled"
+        @click="$emit('accept')"
+      >
+        <Icon icon="ant-design:phone-outlined" :size="18" />
+      </button>
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/rtc/rtc-call-inviting.vue b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-inviting.vue
new file mode 100644
index 000000000..f22dcac7a
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-inviting.vue
@@ -0,0 +1,129 @@
+<script lang="ts" setup>
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { useMediaStreamElement } from '../../composables/useMediaStreamElement'
+import { UserAvatar } from '../user'
+
+const props = defineProps<{
+  cameraEnabled: boolean
+  isGroup?: boolean
+  isVideo: boolean
+  localStream?: MediaStream | null // 本地视频流；视频呼叫预览铺底
+  micEnabled: boolean
+  peerAvatar?: string
+  peerNickname?: string
+  speakerEnabled: boolean
+}>()
+
+defineEmits<{
+  cancel: []
+  toggleCamera: []
+  toggleMic: []
+  toggleSpeaker: []
+}>()
+
+const setLocalVideoRef = useMediaStreamElement<HTMLVideoElement>(() => props.localStream)
+</script>
+
+<template>
+  <!-- 主叫等待对方接听的悬浮窗；1v1 私聊 320×540；群通话切大窗 720×560 -->
+  <div
+    class="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 rounded-xl overflow-hidden shadow-[0_12px_36px_rgba(0,0,0,0.35)] z-[1000] flex flex-col text-white bg-gradient-to-b from-[#2a2a2c] to-[#1a1a1c]"
+    :class="isGroup ? 'w-[720px] h-[560px]' : 'w-[320px] h-[540px]'"
+  >
+    <div class="flex relative flex-1 justify-center items-center">
+      <!-- 视频呼叫：自己摄像头预览铺底，对方头像悬浮顶部 -->
+      <video
+        v-if="isVideo && localStream"
+        :ref="setLocalVideoRef"
+        class="absolute inset-0 object-cover w-full h-full scale-x-[-1]"
+        autoplay
+        muted
+        playsinline
+      ></video>
+      <div
+        class="flex relative z-[1] flex-col gap-4 items-center"
+        :class="{ 'self-start mt-16': isVideo }"
+      >
+        <UserAvatar
+          :url="peerAvatar"
+          :name="peerNickname"
+          :size="96"
+          radius="8px"
+          :clickable="false"
+        />
+        <div class="text-[17px] font-medium">{{ peerNickname || '对方' }}</div>
+        <div class="text-13px text-white/60">等待对方接受邀请……</div>
+      </div>
+    </div>
+
+    <!-- 底部操作区：麦克风 / 取消 / (摄像头 | 扬声器) -->
+    <div class="flex flex-shrink-0 gap-4 justify-around items-center pt-4 px-5 pb-5">
+      <div
+        class="flex flex-col gap-2 items-center cursor-pointer select-none"
+        @click="$emit('toggleMic')"
+      >
+        <!-- Iconify 里 mic 有静音变体；speaker / camera 没有同源静音变体，off 态借 tabler:*-off 表达斜线 -->
+        <span
+          class="flex justify-center items-center w-12 h-12 rounded-full"
+          :class="micEnabled ? 'bg-white text-[#1a1a1c]' : 'bg-white/15 text-white'"
+        >
+          <Icon
+            :icon="micEnabled ? 'ant-design:audio-outlined' : 'ant-design:audio-muted-outlined'"
+            :size="22"
+          />
+        </span>
+        <span class="text-xs text-white/70 whitespace-nowrap">
+          {{ micEnabled ? '麦克风已开' : '麦克风已关' }}
+        </span>
+      </div>
+      <div
+        class="flex flex-col gap-2 items-center cursor-pointer select-none"
+        @click="$emit('cancel')"
+      >
+        <span
+          class="flex justify-center items-center w-12 h-12 text-white rounded-full bg-[#f04a4a]"
+        >
+          <Icon icon="ant-design:phone-outlined" :size="22" class="rotate-[135deg]" />
+        </span>
+        <span class="text-xs text-white/70 whitespace-nowrap">取消</span>
+      </div>
+      <div
+        v-if="isVideo"
+        class="flex flex-col gap-2 items-center cursor-pointer select-none"
+        @click="$emit('toggleCamera')"
+      >
+        <span
+          class="flex justify-center items-center w-12 h-12 rounded-full"
+          :class="cameraEnabled ? 'bg-white text-[#1a1a1c]' : 'bg-white/15 text-white'"
+        >
+          <Icon
+            :icon="cameraEnabled ? 'ant-design:video-camera-outlined' : 'tabler:video-off'"
+            :size="22"
+          />
+        </span>
+        <span class="text-xs text-white/70 whitespace-nowrap">
+          {{ cameraEnabled ? '摄像头已开' : '摄像头已关' }}
+        </span>
+      </div>
+      <div
+        v-else
+        class="flex flex-col gap-2 items-center cursor-pointer select-none"
+        @click="$emit('toggleSpeaker')"
+      >
+        <span
+          class="flex justify-center items-center w-12 h-12 rounded-full"
+          :class="speakerEnabled ? 'bg-white text-[#1a1a1c]' : 'bg-white/15 text-white'"
+        >
+          <Icon
+            :icon="speakerEnabled ? 'ant-design:sound-outlined' : 'tabler:volume-off'"
+            :size="22"
+          />
+        </span>
+        <span class="text-xs text-white/70 whitespace-nowrap">
+          {{ speakerEnabled ? '扬声器已开' : '扬声器已关' }}
+        </span>
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/rtc/rtc-call-member-picker-dialog.vue b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-member-picker-dialog.vue
new file mode 100644
index 000000000..b5223a76a
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-member-picker-dialog.vue
@@ -0,0 +1,109 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from '../group'
+
+import { computed, ref } from 'vue'
+
+import { ElButton, ElDialog } from 'element-plus'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { useGroupStore } from '../../store/groupStore'
+import { GroupMemberPickerPanel } from '../picker'
+
+defineOptions({ name: 'ImRtcCallMemberPickerDialog' })
+
+const emit = defineEmits<{
+  /** 选完点完成；携带选中的 userId 列表 */
+  success: [selectedIds: number[]]
+}>()
+
+type PickerMode = 'add' | 'invite'
+
+const groupStore = useGroupStore()
+
+const visible = ref(false) // 弹窗显隐
+const groupId = ref(0) // 当前群编号；open 时由调用方传入
+const mode = ref<PickerMode>('invite') // 弹窗用途；invite=发起群通话选邀请人 / add=通话中追加成员
+const excludeUserIds = ref<number[]>([]) // 置灰的 userId 列表；add 场景把已在通话内的人禁用
+const selectedIds = ref<number[]>([]) // 当前选中的 userId 列表；GroupMemberPickerPanel v-model 绑过来
+
+/** 标题；按用途切换 */
+const title = computed(() => (mode.value === 'add' ? '添加成员' : '选择成员'))
+
+/** 群成员列表；从 groupStore 现取，map 成 GroupMemberLite */
+const members = computed<GroupMemberLite[]>(() => {
+  const group = groupStore.getGroup(groupId.value)
+  return (group?.members || []).map((member) => ({
+    userId: member.userId,
+    nickname: member.nickname,
+    showName: member.displayUserName || member.nickname,
+    avatar: member.avatar,
+    status: member.status,
+    role: member.role
+  }))
+})
+
+/** 自己不出现在选项里 */
+const hideIds = computed<number[]>(() => {
+  const myId = getCurrentUserId()
+  return myId ? [myId] : []
+})
+
+/** 已在通话内的成员置灰 */
+const disabledIds = computed<number[]>(() => excludeUserIds.value)
+
+/** 是否可提交：至少选 1 个 */
+const canSubmit = computed(() => selectedIds.value.length > 0)
+
+/** 打开弹窗；excludeUserIds 用于「添加成员」时把已在通话内的人置灰 */
+function open(opts: { excludeUserIds?: number[]; groupId: number; mode?: PickerMode; }) {
+  groupId.value = opts.groupId
+  mode.value = opts.mode || 'invite'
+  excludeUserIds.value = opts.excludeUserIds || []
+  selectedIds.value = []
+  visible.value = true
+}
+defineExpose({ open }) // 提供 open 方法，用于打开弹窗
+
+/** 点完成：emit 选中 ID 列表给父级 + 关闭弹窗；提交按钮 disabled 已保证 selectedIds 非空 */
+function handleOk() {
+  emit('success', [...selectedIds.value])
+  visible.value = false
+}
+</script>
+
+<template>
+  <!--
+    通话成员选择弹窗：发起群通话时选邀请人 / 通话中添加成员；
+    选择 UI 委托 GroupMemberPickerPanel；自己 hide、已在通话内的成员 disabled
+  -->
+  <ElDialog
+    v-model="visible"
+    :content="title"
+    width="720px"
+    :close-on-click-modal="false"
+    class="im-picker-dialog"
+  >
+    <div class="h-[480px]">
+      <GroupMemberPickerPanel
+        v-model:selected-ids="selectedIds"
+        :members="members"
+        :disabled-ids="disabledIds"
+        :hide-ids="hideIds"
+      />
+    </div>
+    <template #footer>
+      <ElButton @click="visible = false">取消</ElButton>
+      <ElButton type="primary" :disabled="!canSubmit" @click="handleOk">完成</ElButton>
+    </template>
+  </ElDialog>
+</template>
+
+<style scoped lang="scss">
+@use '../picker/picker-dialog' as picker;
+
+/* :deep 穿透 el-dialog 内部类；复用 picker 公共 mixin */
+.im-picker-dialog {
+  @include picker.styles;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/rtc/rtc-call-participant-tile.vue b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-participant-tile.vue
new file mode 100644
index 000000000..6a12111c2
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-participant-tile.vue
@@ -0,0 +1,110 @@
+<script lang="ts" setup>
+import { useMediaStreamElement } from '../../composables/useMediaStreamElement'
+import { UserAvatar } from '../user'
+
+export interface CallParticipantVM {
+  userId: number
+  nickname: string
+  avatar?: string
+  isLocal: boolean
+  videoStream?: MediaStream | null
+  audioStream?: MediaStream | null
+  /** 等待加入；UI 显示三点动画 */
+  pending?: boolean
+}
+
+const props = defineProps<{
+  participant: CallParticipantVM
+  /** 扬声器开关；为 false 时静音该格子的远端音频 */
+  speakerEnabled: boolean
+}>()
+
+const setVideoRef = useMediaStreamElement<HTMLVideoElement>(() => props.participant.videoStream)
+const setAudioRef = useMediaStreamElement<HTMLAudioElement>(() => props.participant.audioStream)
+</script>
+
+<template>
+  <!--
+    群通话宫格里的单个参与者格子；
+    优先渲染远端视频（有 videoStream 时铺满），无视频降级渲染头像 + 名字胶囊；
+    pending=true 时叠加「接入中」三点动画占位，用于被邀请人未接通前的占位渲染；
+    远端音频通过隐藏 audio 播放（本端 isLocal 不渲染避免回声）
+  -->
+  <div
+    class="flex relative overflow-hidden justify-center items-center w-full h-full rounded-md bg-[#2a2a2c]"
+  >
+    <!-- 视频可用：渲染 video；否则渲染头像或默认占位 -->
+    <video
+      v-if="participant.videoStream"
+      :ref="setVideoRef"
+      class="object-cover w-full h-full"
+      autoplay
+      playsinline
+      :muted="participant.isLocal"
+    ></video>
+    <div v-else class="flex justify-center items-center w-full h-full">
+      <UserAvatar
+        :url="participant.avatar"
+        :name="participant.nickname"
+        :size="64"
+        radius="50%"
+        :clickable="false"
+      />
+    </div>
+
+    <!-- 远端音频；通过 audio 元素播放，本端静音避免回声；扬声器关闭时整体静音 -->
+    <audio
+      v-if="participant.audioStream && !participant.isLocal"
+      :ref="setAudioRef"
+      autoplay
+      :muted="!speakerEnabled"
+    ></audio>
+
+    <!-- 左下角名字胶囊 -->
+    <div
+      class="flex absolute bottom-3 left-3 gap-1.5 items-center py-[3px] pr-2.5 pl-[3px] text-13px text-white rounded-full bg-black/45 max-w-[calc(100%-60px)]"
+    >
+      <UserAvatar
+        :url="participant.avatar"
+        :name="participant.nickname"
+        :size="22"
+        radius="50%"
+        :clickable="false"
+      />
+      <span class="truncate min-w-0">{{ participant.nickname }}</span>
+    </div>
+
+    <!-- 等待对方加入：三点动画 +「接入中」文案；位置在格子中心下方 60px -->
+    <div
+      v-if="participant.pending"
+      class="flex absolute left-1/2 flex-col gap-1.5 items-center -translate-x-1/2 -translate-y-1/2 top-[calc(50%+60px)]"
+    >
+      <div class="flex gap-1.5">
+        <span
+          v-for="i in 3"
+          :key="i"
+          class="tile-dot w-1.5 h-1.5 rounded-full bg-white/60"
+          :style="{ animationDelay: `${(i - 1) * 0.2}s` }"
+        ></span>
+      </div>
+      <span class="text-xs text-white/70">接入中</span>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* 三点淡入淡出动画；@keyframes 必须 CSS 定义 */
+.tile-dot {
+  animation: tile-dot 1.4s infinite ease-in-out both;
+}
+@keyframes tile-dot {
+  0%,
+  80%,
+  100% {
+    opacity: 0.3;
+  }
+  40% {
+    opacity: 1;
+  }
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/rtc/rtc-call-running.vue b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-running.vue
new file mode 100644
index 000000000..9b8d774c8
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/rtc/rtc-call-running.vue
@@ -0,0 +1,291 @@
+<script lang="ts" setup>
+import { computed, onUnmounted, ref, watch } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { formatCallDuration } from '#/views/im/utils/time'
+
+import { useMediaStreamElement } from '../../composables/useMediaStreamElement'
+import { UserAvatar } from '../user'
+import RtcCallParticipantTile, { type CallParticipantVM } from './rtc-call-participant-tile.vue'
+
+const props = defineProps<{
+  cameraEnabled: boolean
+  hangingUp?: boolean
+  /** 是否群通话；决定网格 / 单点布局 + 浮窗大小 */
+  isGroup: boolean
+  isVideo: boolean
+  localStream?: MediaStream | null
+  micEnabled: boolean
+  /** 网格视图用：所有参与者（含自己） */
+  participants: CallParticipantVM[]
+  peerAvatar?: string
+  /** 1v1 视图用 */
+  peerNickname?: string
+  /** 是否处于网络重连中；显示顶部黄色提示条 */
+  reconnecting?: boolean
+  remoteAudioStream?: MediaStream | null
+  remoteVideoStream?: MediaStream | null
+  /** 是否正在屏幕共享；按钮高亮 + 文案切换 */
+  screenShareEnabled?: boolean
+  /** 扬声器开关；true 时正常播放远端音频，false 时所有远端 audio 元素静音 */
+  speakerEnabled: boolean
+  startedAt: number
+}>()
+
+defineEmits<{
+  addMember: []
+  hangup: []
+  toggleCamera: []
+  toggleMic: []
+  toggleScreenShare: []
+  toggleSpeaker: []
+}>()
+
+/** 网格列数；按人数自适应；返回 UnoCSS class 字面量让 JIT 扫描器静态识别 */
+const gridColsClass = computed(() => {
+  const n = props.participants.length
+  if (n <= 1) return 'grid-cols-1'
+  if (n <= 4) return 'grid-cols-2'
+  return 'grid-cols-3'
+})
+
+const setLocalVideoRef = useMediaStreamElement<HTMLVideoElement>(() => props.localStream)
+const setRemoteVideoRef = useMediaStreamElement<HTMLVideoElement>(() => props.remoteVideoStream)
+const setRemoteAudioRef = useMediaStreamElement<HTMLAudioElement>(() => props.remoteAudioStream)
+
+/** 1v1 视频：是否有远端视频流 */
+const hasRemoteVideo = computed(() => !props.isGroup && !!props.remoteVideoStream)
+
+const now = ref(Date.now()) // 通话时长；仅 1v1 语音视图需要展示，其它视图不启 tick
+let tick = 0
+watch(
+  () => props.isGroup || props.isVideo,
+  (suppressTick) => {
+    if (suppressTick) {
+      if (tick) {
+        clearInterval(tick)
+        tick = 0
+      }
+      return
+    }
+    now.value = Date.now()
+    tick = window.setInterval(() => {
+      now.value = Date.now()
+    }, 1000)
+  },
+  { immediate: true }
+)
+onUnmounted(() => {
+  if (tick) {
+    clearInterval(tick)
+  }
+})
+
+/** 通话时长 MM:SS / HH:MM:SS */
+const formattedDuration = computed(() =>
+  formatCallDuration(Math.floor((now.value - props.startedAt) / 1000))
+)
+</script>
+
+<template>
+  <!-- 通话进行中的悬浮窗；1v1 私聊 320×540；群通话切大窗 720×560 -->
+  <div
+    class="fixed top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 rounded-xl overflow-hidden shadow-[0_12px_36px_rgba(0,0,0,0.35)] z-[1000] flex flex-col text-white bg-[#1a1a1c]"
+    :class="isGroup ? 'w-[720px] h-[560px]' : 'w-[320px] h-[540px]'"
+  >
+    <!-- 重连中横幅；网络抖动时显示，直到 Reconnected 事件清除 -->
+    <div
+      v-if="reconnecting"
+      class="inline-flex absolute top-3 left-1/2 z-10 gap-2 items-center px-3.5 py-1.5 text-13px text-[#ffd45e] rounded-full -translate-x-1/2 bg-[rgba(255,196,0,0.18)]"
+    >
+      <span class="reconnect-dot w-2 h-2 rounded-full bg-[#ffd45e]"></span>
+      网络不佳，正在重连……
+    </div>
+    <div class="flex relative flex-1 justify-center items-center">
+      <!-- 群通话：网格布局，列数随人数自适应 -->
+      <div
+        v-if="isGroup"
+        class="grid gap-1 p-1 w-full h-full content-stretch"
+        :class="gridColsClass"
+      >
+        <RtcCallParticipantTile
+          v-for="participant in participants"
+          :key="participant.userId"
+          :participant="participant"
+          :speaker-enabled="speakerEnabled"
+        />
+      </div>
+
+      <!-- 1v1 视频：远端铺底 + 本地缩略 -->
+      <template v-else-if="isVideo">
+        <div v-show="hasRemoteVideo" class="absolute inset-0">
+          <video
+            :ref="setRemoteVideoRef"
+            class="object-cover w-full h-full"
+            autoplay
+            playsinline
+          ></video>
+        </div>
+        <div v-if="!hasRemoteVideo" class="flex z-[1] flex-col gap-4 items-center">
+          <UserAvatar
+            :url="peerAvatar"
+            :name="peerNickname"
+            :size="96"
+            radius="8px"
+            :clickable="false"
+          />
+          <div class="text-[17px] font-medium">{{ peerNickname }}</div>
+          <div class="text-13px text-white/60">等待对方开启摄像头……</div>
+        </div>
+        <div
+          v-if="localStream"
+          class="absolute top-4 right-4 z-[2] overflow-hidden w-30 rounded-lg aspect-[9/16] bg-[#333]"
+        >
+          <video
+            :ref="setLocalVideoRef"
+            class="object-cover w-full h-full scale-x-[-1]"
+            autoplay
+            muted
+            playsinline
+          ></video>
+        </div>
+      </template>
+
+      <!-- 1v1 语音：头像 + 时长 -->
+      <template v-else>
+        <div class="flex z-[1] flex-col gap-4 items-center">
+          <UserAvatar
+            :url="peerAvatar"
+            :name="peerNickname"
+            :size="96"
+            radius="8px"
+            :clickable="false"
+          />
+          <div class="text-[17px] font-medium">{{ peerNickname }}</div>
+          <div class="text-13px text-white/60">{{ formattedDuration }}</div>
+        </div>
+      </template>
+      <audio
+        v-if="!isGroup && remoteAudioStream"
+        :ref="setRemoteAudioRef"
+        autoplay
+        :muted="!speakerEnabled"
+      ></audio>
+    </div>
+
+    <!-- 底部操作区：麦克风 / 扬声器 / 摄像头 / (群聊：共享屏幕 / 添加成员) / 挂断 -->
+    <div
+      class="flex flex-shrink-0 gap-3 justify-around items-center pt-4 px-4 pb-5 bg-black/20"
+    >
+      <div
+        class="flex flex-col gap-2 items-center cursor-pointer select-none min-w-[64px]"
+        @click="$emit('toggleMic')"
+      >
+        <span
+          class="flex justify-center items-center w-[52px] h-[52px] rounded-full"
+          :class="micEnabled ? 'bg-white text-[#1a1a1c]' : 'bg-white/15 text-white'"
+        >
+          <Icon
+            :icon="micEnabled ? 'ant-design:audio-outlined' : 'ant-design:audio-muted-outlined'"
+            :size="22"
+          />
+        </span>
+        <span class="text-xs text-white/70 whitespace-nowrap">
+          {{ micEnabled ? '麦克风已开' : '麦克风已关' }}
+        </span>
+      </div>
+      <div
+        class="flex flex-col gap-2 items-center cursor-pointer select-none min-w-[64px]"
+        @click="$emit('toggleSpeaker')"
+      >
+        <span
+          class="flex justify-center items-center w-[52px] h-[52px] rounded-full"
+          :class="speakerEnabled ? 'bg-white text-[#1a1a1c]' : 'bg-white/15 text-white'"
+        >
+          <Icon
+            :icon="speakerEnabled ? 'ant-design:sound-outlined' : 'tabler:volume-off'"
+            :size="22"
+          />
+        </span>
+        <span class="text-xs text-white/70 whitespace-nowrap">
+          {{ speakerEnabled ? '扬声器已开' : '扬声器已关' }}
+        </span>
+      </div>
+      <!-- 摄像头按钮：私聊视频固定显示；群聊不论起始 mediaType 都显示，让用户按需开 -->
+      <div
+        v-if="isVideo || isGroup"
+        class="flex flex-col gap-2 items-center cursor-pointer select-none min-w-[64px]"
+        @click="$emit('toggleCamera')"
+      >
+        <span
+          class="flex justify-center items-center w-[52px] h-[52px] rounded-full"
+          :class="cameraEnabled ? 'bg-white text-[#1a1a1c]' : 'bg-white/15 text-white'"
+        >
+          <Icon
+            :icon="cameraEnabled ? 'ant-design:video-camera-outlined' : 'tabler:video-off'"
+            :size="22"
+          />
+        </span>
+        <span class="text-xs text-white/70 whitespace-nowrap">
+          {{ cameraEnabled ? '摄像头已开' : '摄像头已关' }}
+        </span>
+      </div>
+      <!-- 群通话才有：共享屏幕 / 添加成员；共享中按钮高亮 + 文案换成「停止共享」 -->
+      <template v-if="isGroup">
+        <div
+          class="flex flex-col gap-2 items-center cursor-pointer select-none min-w-[64px]"
+          @click="$emit('toggleScreenShare')"
+        >
+          <span
+            class="flex justify-center items-center w-[52px] h-[52px] rounded-full"
+            :class="screenShareEnabled ? 'bg-[#07c160] text-white' : 'bg-white/15 text-white'"
+          >
+            <Icon
+              :icon="screenShareEnabled ? 'ant-design:laptop-outlined' : 'tabler:device-laptop-off'"
+              :size="22"
+            />
+          </span>
+          <span class="text-xs text-white/70 whitespace-nowrap">
+            {{ screenShareEnabled ? '停止共享' : '共享屏幕' }}
+          </span>
+        </div>
+        <div
+          class="flex flex-col gap-2 items-center cursor-pointer select-none min-w-[64px]"
+          @click="$emit('addMember')"
+        >
+          <span class="flex justify-center items-center w-[52px] h-[52px] text-white rounded-full bg-white/15">
+            <Icon icon="ant-design:plus-outlined" :size="22" />
+          </span>
+          <span class="text-xs text-white/70 whitespace-nowrap">添加成员</span>
+        </div>
+      </template>
+      <div
+        class="flex flex-col gap-2 items-center cursor-pointer select-none min-w-[64px]"
+        :class="{ 'opacity-60 pointer-events-none': hangingUp }"
+        @click="$emit('hangup')"
+      >
+        <span class="flex justify-center items-center w-[52px] h-[52px] text-white rounded-full bg-[#f04a4a]">
+          <Icon icon="ant-design:phone-outlined" :size="22" class="rotate-[135deg]" />
+        </span>
+        <span class="text-xs text-white/70 whitespace-nowrap">挂断</span>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* 重连小点淡入淡出；@keyframes 必须 CSS 定义 */
+.reconnect-dot {
+  animation: reconnect-pulse 1s ease-in-out infinite;
+}
+@keyframes reconnect-pulse {
+  0%,
+  100% {
+    opacity: 0.3;
+  }
+  50% {
+    opacity: 1;
+  }
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/rtc/rtc-group-call-banner.vue b/apps/web-ele/src/views/im/home/components/rtc/rtc-group-call-banner.vue
new file mode 100644
index 000000000..51481e42e
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/rtc/rtc-group-call-banner.vue
@@ -0,0 +1,176 @@
+<script lang="ts" setup>
+import { computed, ref, watch } from 'vue'
+
+import { DICT_TYPE } from '@vben/constants'
+import { getDictLabel } from '@vben/hooks'
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElMessage, ElPopover } from 'element-plus'
+
+import { getActiveCall, joinCall } from '#/api/im/rtc'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { useGroupCallMembers } from '../../composables/useGroupCallMembers'
+import { useRtcStore } from '../../store/rtcStore'
+import { UserAvatar } from '../user'
+
+defineOptions({ name: 'ImRtcGroupCallBanner' })
+
+const props = defineProps<{
+  groupId: number
+}>()
+
+const rtcStore = useRtcStore()
+
+const popoverVisible = ref(false)
+
+/** 当前群的活跃通话；rtcStore 维护，参与者加入 / 离开通知增删 joinedUserIds，通话结束移除 */
+const activeCall = computed(() => rtcStore.getGroupCall(props.groupId))
+
+/** 胶囊条文案；有成员（已加入 + 接入中）则带人数，初始 0 人时只显示媒体类型 */
+const pillText = computed(() => {
+  const media = getDictLabel(DICT_TYPE.IM_RTC_CALL_MEDIA_TYPE, activeCall.value?.mediaType)
+  const count = memberList.value.length
+  return count > 0 ? `正在${media}通话（${count} 人）` : `正在${media}通话`
+})
+
+/**
+ * 切到群 / 通话 room 变化时拉一次最新参与者列表；
+ * 两个触发场景：1）用户切群，本端可能没有该群通话的最新缓存；2）参与者通知首次填充后只含本次加入者，缺历史加入者；
+ * 用 [groupId, room] 双源监听 + 已填充守卫，避免切群 / 首次填充触发的双次重复拉取
+ */
+watch(
+  () => [props.groupId, activeCall.value?.room] as const,
+  async ([groupId, room], oldValues) => {
+    if (!groupId) {
+      return
+    }
+
+    // 决策是否需要拉取：切群 / room 切换必拉；同群同 room 且已加载 >= 2 人则跳过，避免参与者通知触发后重复请求
+    const groupChanged = !oldValues || oldValues[0] !== groupId
+    const roomChanged = oldValues && oldValues[1] !== room
+    const hydrated = (activeCall.value?.joinedUserIds?.length ?? 0) > 1
+    if (!groupChanged && !roomChanged && hydrated) {
+      return
+    }
+
+    // 拉最新参与者写回 store；接口返回空 → 该群已无活跃通话，移除本地缓存
+    try {
+      const data = await getActiveCall(groupId)
+      if (data) {
+        rtcStore.setGroupCall(data)
+      } else {
+        rtcStore.removeGroupCall(groupId)
+      }
+    } catch (error) {
+      console.warn('[GroupCallBanner] getActiveCall 失败', { groupId }, error)
+    }
+  },
+  { immediate: true }
+)
+
+/** 在通话中的成员（已加入）+ 接入中的成员（已邀请未接通） */
+const memberList = useGroupCallMembers(computed(() => props.groupId))
+
+/** 本端是否正在该房间通话（处于 INVITING / RUNNING） */
+const isInThisCall = computed(
+  () => rtcStore.isActive && rtcStore.call?.room === activeCall.value?.room
+)
+
+/**
+ * 服务端是否记录我已加入；刷新后 LiveKit 连接已断但 webhook 还没把 status 标为 LEFT 时仍为 true；
+ * 用于把按钮文案切到「重新加入」，但不 disable 按钮
+ */
+const serverSaysJoined = computed(() => {
+  const myId = getCurrentUserId()
+  return activeCall.value?.joinedUserIds?.includes(myId) ?? false
+})
+
+/** 加入按钮禁用：仅在本端实际持有 LiveKit 连接时禁用 */
+const joinDisabled = computed(() => isInThisCall.value)
+
+/** 加入按钮文案；本端连着 → 已在通话中；服务端还残留我但本端断了 → 重新加入；其它 → 加入 */
+const joinLabel = computed(() => {
+  if (isInThisCall.value) return '已在通话中'
+  if (serverSaysJoined.value) return '重新加入'
+  return '加入'
+})
+
+/** 主动加入：调 invite 命中已有 call 拿 token；rtcStore 按 status 自动进 RUNNING */
+async function handleJoin() {
+  const call = activeCall.value
+  if (!call || joinDisabled.value) {
+    return
+  }
+  if (rtcStore.isActive) {
+    ElMessage.warning('您正在通话中')
+    return
+  }
+  popoverVisible.value = false
+  const data = await joinCall(call.room)
+  rtcStore.startInviting(data)
+}
+</script>
+
+<template>
+  <!-- 仅当该群有活跃通话时显示；点击胶囊条展开 popover 看在通话成员 + 加入 -->
+  <div v-if="activeCall" class="flex-shrink-0 px-4 pb-2 bg-[var(--ant-color-fill-secondary)]">
+    <ElPopover
+      v-model="popoverVisible"
+      placement="bottom-start"
+      :width="280"
+      trigger="click"
+    >
+      <template #reference>
+        <!-- 胶囊条本体：电话图标 + 文案（含人数）+ 右箭头 -->
+        <div
+          class="inline-flex gap-2 items-center px-2.5 py-1 text-13px rounded-full cursor-pointer select-none transition-colors duration-150 bg-[var(--ant-color-success-bg)] text-[var(--ant-color-text)] hover:bg-[var(--ant-color-success-bg-hover)]"
+        >
+          <span
+            class="inline-flex flex-shrink-0 justify-center items-center w-[18px] h-[18px] text-white rounded-full bg-[#07c160]"
+          >
+            <Icon icon="ant-design:phone-filled" :size="14" />
+          </span>
+          <span class="font-medium">{{ pillText }}</span>
+          <Icon
+            icon="ant-design:right-outlined"
+            :size="12"
+            class="text-[var(--ant-color-text-secondary)]"
+          />
+        </div>
+      </template>
+
+      <!-- 展开面板：通话成员（含接入中）头像横排 + 加入按钮 -->
+      <div class="flex flex-col gap-4 items-center pt-2 pb-1">
+        <div class="flex flex-wrap gap-1.5 justify-center max-w-[240px]">
+          <UserAvatar
+            v-for="member in memberList"
+            :key="member.userId"
+            :url="member.avatar"
+            :name="member.nickname"
+            :size="40"
+            radius="6px"
+            :clickable="false"
+            :class="{ 'opacity-50': member.pending }"
+            :content="member.pending ? `${member.nickname}（接入中）` : member.nickname"
+          />
+          <!-- 首次填充时房内可能暂时 0 人；加入后由 ParticipantConnected 事件追加 -->
+          <div
+            v-if="memberList.length === 0"
+            class="p-3 text-13px text-[var(--ant-color-text-secondary)]"
+          >
+            暂无成员在通话
+          </div>
+        </div>
+        <!-- 本端在通话内时置灰「已在通话中」；服务端残留我但本端连接断了显示「重新加入」（刷新页面后场景） -->
+        <button
+          class="w-[200px] h-9 text-sm font-medium rounded-lg cursor-pointer border-none bg-[#f1f1f3] text-[#1a1a1c] transition-colors duration-150 disabled:cursor-not-allowed disabled:text-[#999] hover:[&:not(:disabled)]:bg-[#e7e7ea]"
+          :disabled="joinDisabled"
+          @click="handleJoin"
+        >
+          {{ joinLabel }}
+        </button>
+      </div>
+    </ElPopover>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/tool-bar.vue b/apps/web-ele/src/views/im/home/components/tool-bar.vue
new file mode 100644
index 000000000..cb0fcc963
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/tool-bar.vue
@@ -0,0 +1,123 @@
+<script lang="ts" setup>
+import { computed } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+import { useUserStore } from '@vben/stores'
+
+import { ElBadge } from 'element-plus'
+
+import { useConversationStore } from '../store/conversationStore'
+import { useFriendStore } from '../store/friendStore'
+import { useImUiStore } from '../store/uiStore'
+import { UserAvatar } from './user'
+
+defineOptions({ name: 'ImToolBar' })
+
+const route = useRoute()
+const router = useRouter()
+const userStore = useUserStore()
+const conversationStore = useConversationStore()
+const friendStore = useFriendStore()
+const uiStore = useImUiStore()
+
+/** 消息 Tab 的红点：所有非免打扰会话的未读总和 */
+const totalUnread = computed(() => conversationStore.getTotalUnreadCount)
+/** 通讯录 Tab 的红点：未处理好友申请数（接收方=我） */
+const unhandledRequestCount = computed(() => friendStore.getUnhandledRequestCount)
+
+const tabs = [
+  { name: 'ImHomeConversation', icon: 'ep:chat-round' },
+  { name: 'ImHomeContact', icon: 'mingcute:contacts-line' }
+] // 两个主 Tab；用路由 name 而非 path，避免前缀 / 嵌套调整后失效
+
+// 当前路由是否命中 Tab：直接比对 route.name
+const isActive = (name: string) => route.name === name
+
+// 切换 Tab：当前已选中时，消息 Tab 触发"滚动到下一个未读"（对齐微信 PC），其它 Tab 无动作
+const goTab = (name: string) => {
+  if (route.name === name) {
+    if (name === 'ImHomeConversation') {
+      uiStore.requestNextUnreadJump()
+    }
+    return
+  }
+  router.push({ name })
+}
+
+// 跳转个人中心（路由 name=Profile）
+const goProfile = () => router.push({ name: 'Profile' })
+</script>
+
+<template>
+  <!--
+    ToolBar：IM 左侧工具栏
+    布局：顶部头像 → 中间三 Tab（消息/好友/群聊）→ 底部设置
+  -->
+  <div
+    class="flex flex-col items-center w-14 pt-4 pb-3 gap-2 flex-shrink-0 select-none bg-[#2b2b2b]"
+  >
+    <!-- 顶部用户头像，点击跳个人中心；走 UserAvatar 统一首字 / 哈希配色规则 -->
+    <div class="mb-2 cursor-pointer" @click="goProfile">
+      <UserAvatar
+        :url="userStore.userInfo?.avatar"
+        :name="userStore.userInfo?.nickname"
+        :size="36"
+        :clickable="false"
+      />
+    </div>
+
+    <!-- 中间三 Tab -->
+    <div class="flex flex-col items-center gap-2 flex-1 w-full">
+      <div
+        v-for="item in tabs"
+        :key="item.name"
+        class="flex items-center justify-center w-10 h-10 rounded-lg text-[#a0a0a0] cursor-pointer transition-all hover:text-white hover:bg-white/10"
+        :class="{ 'bg-white/15 text-white': isActive(item.name) }"
+        @click="goTab(item.name)"
+      >
+        <ElBadge
+          v-if="item.name === 'ImHomeConversation' && totalUnread > 0"
+          :count="totalUnread"
+          :max="99"
+          class="tool-bar__badge"
+        >
+          <Icon :icon="item.icon" class="tool-bar__icon" />
+        </ElBadge>
+        <ElBadge
+          v-else-if="item.name === 'ImHomeContact' && unhandledRequestCount > 0"
+          :count="unhandledRequestCount"
+          :max="99"
+          class="tool-bar__badge"
+        >
+          <Icon :icon="item.icon" class="tool-bar__icon" />
+        </ElBadge>
+        <Icon v-else :icon="item.icon" class="tool-bar__icon" />
+      </div>
+    </div>
+
+    <!-- 底部设置按钮：点击跳个人中心 -->
+    <div class="flex flex-col items-center gap-2 w-full">
+      <div
+        class="flex items-center justify-center w-10 h-10 rounded-lg text-[#a0a0a0] cursor-pointer transition-all hover:text-white hover:bg-white/10"
+        @click="goProfile"
+      >
+        <Icon icon="ant-design:setting-outlined" class="tool-bar__icon" />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.tool-bar__icon {
+  width: 22px;
+  height: 22px;
+}
+
+/* 调整红点位置 */
+.tool-bar__badge :deep(.el-badge__content) {
+  top: 4px;
+  right: 8px;
+  border: none;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/user/index.ts b/apps/web-ele/src/views/im/home/components/user/index.ts
new file mode 100644
index 000000000..d25750ed9
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/user/index.ts
@@ -0,0 +1,5 @@
+export { default as RecommendCardDialog } from './recommend-card-dialog.vue';
+export { default as UserAvatar } from './user-avatar.vue';
+export { default as UserInfoCard } from './user-info-card.vue';
+export { default as UserInfo } from './user-info.vue';
+export type { UserInfoRelation } from './user-info.vue';
diff --git a/apps/web-ele/src/views/im/home/components/user/recommend-card-dialog.vue b/apps/web-ele/src/views/im/home/components/user/recommend-card-dialog.vue
new file mode 100644
index 000000000..751c95bf2
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/user/recommend-card-dialog.vue
@@ -0,0 +1,322 @@
+<script lang="ts" setup>
+import type { Conversation, FriendLite } from '../../types'
+
+import { computed, ref } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElButton, ElDialog, ElInput, ElMessage } from 'element-plus'
+
+import { createGroup } from '#/api/im/group'
+import { CardBubble } from '#/views/im/home/components/card'
+
+import { ImContentType, ImConversationType, isGroupConversation } from '../../../utils/constants'
+import { getConversationKey } from '../../../utils/conversation'
+import { buildDefaultGroupName } from '../../../utils/group'
+import { type CardTarget, serializeMessage } from '../../../utils/message'
+import { getGroupDisplayName, isGroupQuit } from '../../../utils/user'
+import { useMessageSender } from '../../composables/useMessageSender'
+import { FacePicker } from '../../pages/conversation/components/input'
+import { useConversationStore } from '../../store/conversationStore'
+import { useFriendStore } from '../../store/friendStore'
+import { useGroupStore } from '../../store/groupStore'
+import { ConversationPickerPanel } from '../picker'
+import { FriendPickerPanel } from '../picker'
+
+defineOptions({ name: 'ImRecommendCardDialog' })
+
+const conversationStore = useConversationStore()
+const friendStore = useFriendStore()
+const groupStore = useGroupStore()
+const { sendRaw, send } = useMessageSender()
+
+const visible = ref(false)
+const target = ref<CardTarget | null>(null)
+const view = ref<'contact' | 'conversation'>('conversation') // 当前视图：默认会话选择，「创建聊天」入口切到好友选择
+const selectedKeys = ref<string[]>([])
+const selectedFriendIds = ref<number[]>([])
+const leaveMessage = ref('')
+const sending = ref(false)
+const emojiVisible = ref(false) // 表情面板显隐：右侧 smile icon 切换
+
+defineExpose({
+  /** 打开推荐弹窗：reset → 灌参 → visible=true */
+  open(opts: { target: CardTarget }) {
+    target.value = opts.target
+    view.value = 'conversation'
+    selectedKeys.value = []
+    selectedFriendIds.value = []
+    leaveMessage.value = ''
+    emojiVisible.value = false
+    sending.value = false
+    visible.value = true
+  }
+})
+
+/** 弹窗标题：会话视图按 target 类型分文案；好友视图固定为「选择好友」 */
+const headerTitle = computed(() => {
+  if (view.value === 'contact') {
+    return '选择好友'
+  }
+  return isGroupConversation(target.value?.targetType) ? '把这个群推荐给朋友' : '把他推荐给朋友'
+})
+
+/** 候选会话：从 store 拿排序后的列表（hide 由 Panel 接 hideKeys 过滤）；历史退群群不可被推荐选中（选了后端也会拒） */
+const candidateConversations = computed<Conversation[]>(() =>
+  conversationStore.getSortedConversationList.filter(
+    (conversation) =>
+      !(
+        conversation.type === ImConversationType.GROUP &&
+        isGroupQuit(groupStore.getGroup(conversation.targetId))
+      )
+  )
+)
+
+/** 隐藏 key：不能把名片推回名片本身的会话（用户名片避免自推、群名片避免推回该群） */
+const hideKeys = computed<string[]>(() => {
+  const t = target.value
+  if (!t) {
+    return []
+  }
+  return [getConversationKey({ type: t.targetType, targetId: t.targetId })]
+})
+
+/** 好友视图候选列表：直接复用 friendStore Lite 视图 */
+const friends = computed<FriendLite[]>(() => friendStore.getActiveFriendLiteList)
+
+/** 把选中的 emoji 拼到留言末尾；FacePicker 自身负责关闭面板 */
+function handleEmojiSelect(emoji: string) {
+  leaveMessage.value = `${leaveMessage.value}${emoji}`
+}
+
+/** 切到好友视图：清掉之前在会话视图输入的留言，避免在不可见输入框里把留言静默发到新群 */
+function handleSwitchToContact() {
+  view.value = 'contact'
+  leaveMessage.value = ''
+  emojiVisible.value = false
+}
+
+/**
+ * 确认发送（会话视图）：每个选中会话先发 CARD，CARD 成功后才发留言（保证「先看到名片」的顺序意图）
+ *
+ * 文案聚合：全部成功「已转发」、全部失败「转发失败：A、B」、部分失败「已转发，但 X、Y 失败」；
+ * 失败的消息以 FAILED 状态留在对应会话气泡里，可右键重试
+ */
+async function handleSend() {
+  const card = target.value
+  if (!card?.targetId || selectedKeys.value.length === 0) {
+    return
+  }
+  const byKey = new Map(candidateConversations.value.map((c) => [getConversationKey(c), c]))
+  const targets = selectedKeys.value
+    .map((key) => byKey.get(key))
+    .filter((c): c is Conversation => c != null)
+  if (targets.length === 0) {
+    return
+  }
+  const cardContent = serializeMessage({ ...card })
+  const leaveText = leaveMessage.value.trim()
+  sending.value = true
+  try {
+    const tasks = targets.map(async (conversation) => {
+      const cardOk = await sendRaw(ImContentType.CARD, cardContent, { conversation })
+      if (!cardOk) {
+        return { conversation, ok: false }
+      }
+      const ok = leaveText ? await send(leaveText, { conversation }) : true
+      return { conversation, ok }
+    })
+    const results = await Promise.all(tasks)
+    const failedNames = results.filter((r) => !r.ok).map((r) => r.conversation.name || '未命名会话')
+    // 把命中的目标推到最近转发列表（部分失败也推：用户的"意图"已表达）
+    conversationStore.pushRecentForwardConversationKeyList(targets.map((c) => getConversationKey(c)))
+    if (failedNames.length === 0) {
+      ElMessage.success('已转发')
+    } else if (failedNames.length === targets.length) {
+      ElMessage.error(`转发失败：${failedNames.join('、')}`)
+    } else {
+      ElMessage.warning(`已转发，但 ${failedNames.join('、')} 失败`)
+    }
+    visible.value = false
+  } finally {
+    sending.value = false
+  }
+}
+
+/**
+ * 好友视图发送：先建群（同时邀请所选好友）→ 给新群发名片 → 发留言 → 关弹窗
+ *
+ * 跟会话视图的差别：先要 createGroup 拿到 groupId，之后构造一个 GROUP 类型的 conversation 对象给 sendRaw 用
+ * （sendRaw 内部会自动 insertMessage 把新群登记进 store，最近转发列表也能正常推）
+ */
+async function handleCreateGroupAndSend() {
+  const card = target.value
+  if (!card?.targetId || selectedFriendIds.value.length === 0) {
+    return
+  }
+  const byId = new Map(friends.value.map((f) => [f.id, f]))
+  const members = selectedFriendIds.value
+    .map((id) => byId.get(id))
+    .filter((f): f is FriendLite => f != null)
+  if (members.length === 0) {
+    return
+  }
+  sending.value = true
+  try {
+    const memberUserIds = members.map((m) => m.id)
+    const name = buildDefaultGroupName(members)
+    const group = await createGroup({ name, memberUserIds, joinApproval: false })
+    if (!group?.id) {
+      throw new Error('创建群失败：未返回群编号')
+    }
+    // upsert 进 groupStore，省一次 fetchGroupList
+    groupStore.upsertGroup({
+      id: group.id,
+      name: group.name,
+      avatar: group.avatar,
+      notice: group.notice,
+      ownerUserId: group.ownerUserId
+    })
+    // 给新群构造一个临时 conversation 对象给 sendRaw 用；sendRaw 内部会自动 insertMessage 登记
+    const newConversation: Conversation = {
+      type: ImConversationType.GROUP,
+      targetId: group.id,
+      name: getGroupDisplayName(group) || name,
+      avatar: group.avatar || '',
+      unreadCount: 0,
+      lastContent: '',
+      lastSendTime: 0
+    }
+    const cardOk = await sendRaw(ImContentType.CARD, serializeMessage({ ...card }), {
+      conversation: newConversation
+    })
+    if (!cardOk) {
+      ElMessage.warning('群已创建，但名片发送失败，请稍后在群里重试')
+      visible.value = false
+      return
+    }
+    const leaveText = leaveMessage.value.trim()
+    if (leaveText) {
+      await send(leaveText, { conversation: newConversation })
+    }
+    conversationStore.pushRecentForwardConversationKeyList([getConversationKey(newConversation)])
+    ElMessage.success('已创建群聊并发送')
+    visible.value = false
+  } finally {
+    sending.value = false
+  }
+}
+</script>
+
+<template>
+  <!--
+    把名片推荐给朋友（用户 / 群通用）
+    - dialog 壳由本组件持有；选择 UI 委托 ConversationPickerPanel / FriendPickerPanel
+    - view='conversation'：选已有会话发名片（默认视图）
+    - view='contact'：从「创建聊天」入口进入，选好友建群再发名片，业务壳层切视图，两个 Panel 互不知道对方
+    - 选 1 走「发送」、多个走「分别发送(n)」文案，与微信一致
+    - 失败的消息以 FAILED 状态留在对应会话气泡里，供右键重试
+    - 对外接口：ref + open({ target })，不再走 v-model
+  -->
+  <ElDialog
+    v-model="visible"
+    width="720px"
+    :close-on-click-modal="false"
+    
+    class="im-picker-dialog im-recommend-dialog"
+  >
+    <template #header>
+      <div class="flex gap-2 items-center">
+        <Icon
+          v-if="view === 'contact'"
+          icon="ant-design:arrow-left-outlined"
+          :size="16"
+          class="cursor-pointer text-[var(--ant-color-text-secondary)] transition-colors duration-150 hover:text-[var(--ant-color-primary)]"
+          @click="view = 'conversation'"
+        />
+        <span class="text-base text-[var(--ant-color-text)]">
+          {{ headerTitle }}
+        </span>
+      </div>
+    </template>
+
+    <div class="h-[480px]">
+      <!-- 会话视图：选已有会话发送 -->
+      <ConversationPickerPanel
+        v-if="view === 'conversation'"
+        v-model:selected-keys="selectedKeys"
+        :conversations="candidateConversations"
+        :recent-forward-conversation-keys="conversationStore.recentForwardConversationKeys"
+        :hide-keys="hideKeys"
+        :show-create-chat="true"
+        @create-chat="handleSwitchToContact"
+        @remove-recent="conversationStore.removeRecentForwardConversationKey"
+      >
+        <template #footer>
+          <div class="flex flex-col gap-3 px-4 py-3">
+            <!-- 名片预览卡 -->
+            <CardBubble v-if="target" :card="target" />
+
+            <!-- 留言（单行）：右侧表情按钮触发 FacePicker；选中 emoji 拼到末尾 -->
+            <div class="relative">
+              <ElInput v-model="leaveMessage" :maxlength="100" placeholder="给朋友留言">
+                <template #suffix>
+                  <Icon
+                    icon="ant-design:smile-outlined"
+                    :size="18"
+                    class="cursor-pointer text-[var(--ant-color-text-secondary)] hover:text-[var(--ant-color-primary)]"
+                    @click.stop="emojiVisible = !emojiVisible"
+                  />
+                </template>
+              </ElInput>
+              <FacePicker
+                v-model:visible="emojiVisible"
+                mode="emoji"
+                class="bottom-full right-0 mb-2"
+                @select-emoji="handleEmojiSelect"
+              />
+            </div>
+
+            <!-- 操作按钮：选 0/1 显示「发送」、多个显示「分别发送(n)」 -->
+            <div class="flex gap-2 justify-end">
+              <ElButton @click="visible = false">取消</ElButton>
+              <ElButton
+                type="primary"
+                :loading="sending"
+                :disabled="selectedKeys.length === 0"
+                @click="handleSend"
+              >
+                {{ selectedKeys.length > 1 ? `分别发送（${selectedKeys.length}）` : '发送' }}
+              </ElButton>
+            </div>
+          </div>
+        </template>
+      </ConversationPickerPanel>
+
+      <!-- 好友视图：选好友建群后发送 -->
+      <FriendPickerPanel v-else v-model:selected-ids="selectedFriendIds" :friends="friends" />
+    </div>
+
+    <!-- 好友视图的 dialog footer：建群并发送 -->
+    <template v-if="view === 'contact'" #footer>
+      <ElButton @click="visible = false">取消</ElButton>
+      <ElButton
+        type="primary"
+        :loading="sending"
+        :disabled="selectedFriendIds.length === 0"
+        @click="handleCreateGroupAndSend"
+      >
+        创建群聊并发送
+      </ElButton>
+    </template>
+  </ElDialog>
+</template>
+
+<style scoped lang="scss">
+@use '../picker/picker-dialog' as picker;
+
+/* :deep 穿透 el-dialog 内部类；复用 picker 公共 mixin */
+.im-picker-dialog {
+  @include picker.styles;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/components/user/user-avatar.vue b/apps/web-ele/src/views/im/home/components/user/user-avatar.vue
new file mode 100644
index 000000000..de45d34aa
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/user/user-avatar.vue
@@ -0,0 +1,134 @@
+<script lang="ts" setup>
+import type { User } from '../../types'
+
+import { computed } from 'vue'
+
+import { ElImage } from 'element-plus'
+
+import { ImFriendAddSource } from '../../../utils/constants'
+import { getAvatarBgColor, getAvatarText } from '../../../utils/user'
+import { useImUiStore } from '../../store/uiStore'
+
+defineOptions({ name: 'ImUserAvatar', inheritAttrs: false })
+
+const props = withDefaults(
+  defineProps<{
+    addSource?: number // 加好友来源；点头像弹 UserInfoCard 时透传给 FriendAddDialog（默认 1=搜索）
+    addSourceExtra?: string // 加好友来源附加：addSource=2（群聊）时传群名，话术拼为「我是 XX 群的 YY」
+    clickable?: boolean // 是否点击弹出 UserInfoCard；默认 true
+    id?: number | string // 用户 id；传了才能点开名片
+    name?: string // 用户名（色卡文字 + 名片备用）
+    previewable?: boolean // 是否点头像直接放大预览；开启后忽略 clickable，不再弹名片
+    previewZIndex?: number // 预览层 z-index；放在高 z-index 弹层（如 UserInfoCard）里时需手动抬高
+    radius?: string // 圆角，支持 CSS 长度；默认 15% 方块小圆角（参考微信）
+    size?: number // 尺寸（px），正方形；优先于 width/height
+    url?: string // 头像图片 URL；为空时走色卡文字
+    user?: User // 额外的用户信息，传了点击就不用现拉接口（弹名片用）
+  }>(),
+  {
+    addSourceExtra: undefined,
+    clickable: true,
+    id: undefined,
+    name: undefined,
+    previewable: false,
+    previewZIndex: 2000,
+    radius: '15%',
+    size: 42,
+    url: undefined,
+    user: undefined,
+    addSource: ImFriendAddSource.SEARCH
+  }
+)
+
+const uiStore = useImUiStore()
+
+const imgStyle = computed(() => ({
+  width: `${props.size}px`,
+  height: `${props.size}px`,
+  borderRadius: props.radius
+}))
+
+const textStyle = computed(() => ({
+  width: `${props.size}px`,
+  height: `${props.size}px`,
+  fontSize: `${Math.floor(props.size * (avatarText.value.length > 1 ? 0.34 : 0.42))}px`,
+  background: textColor.value,
+  borderRadius: props.radius
+}))
+
+/** 色卡首字：中文取 1 个字、英文 / 拉丁取前 2 个字母 */
+const avatarText = computed(() => getAvatarText(props.name))
+
+/** 色卡底色：按昵称 charCode 哈希取调色板色 */
+const textColor = computed(() => getAvatarBgColor(props.name))
+
+/** 头像点击：previewable 走 el-image 预览不弹名片；否则按 user / id 任一入参打开名片 */
+function handleClick(e: MouseEvent) {
+  if (props.previewable) {
+    return
+  }
+  if (!props.clickable) {
+    return
+  }
+  // 情况一：有预传 user 信息：就直接用，省一次接口
+  if (props.user) {
+    uiStore.openUserInfoCardAtEvent(props.user, e, props.addSource, props.addSourceExtra)
+    return
+  }
+  // 情况二：无预传 user 信息：打开名片，传最小必要信息（id + 昵称 + 头像），位置在鼠标右侧
+  const numId = Number(props.id)
+  if (!numId || numId <= 0) {
+    return
+  }
+  uiStore.openUserInfoCardAtEvent(
+    {
+      id: numId,
+      nickname: props.name,
+      avatar: props.url
+    },
+    e,
+    props.addSource,
+    props.addSourceExtra
+  )
+}
+</script>
+
+<template>
+  <!--
+    通用用户头像组件
+    - 有 url 时展示图片；无 url 时展示色卡 + 首字母/首字
+    - 点击默认触发 UserInfoCard（clickable）
+    - previewable=true 时改为点头像直接放大预览（用于名片 / 详情页等大头像位）
+  -->
+  <div
+    class="relative inline-flex"
+    :style="{ cursor: clickable && !previewable ? 'pointer' : 'default' }"
+    v-bind="$attrs"
+    @click="handleClick"
+  >
+    <ElImage
+      v-if="url && previewable"
+      class="block overflow-hidden"
+      :src="url"
+      :preview="{ src: url, zIndex: previewZIndex }"
+      :style="imgStyle"
+    />
+    <img
+      v-else-if="url"
+      class="block overflow-hidden object-cover"
+      :src="url"
+      :style="imgStyle"
+      loading="lazy"
+      :alt="name || 'avatar'"
+    />
+    <div
+      v-else
+      class="flex items-center justify-center text-white font-medium select-none"
+      :style="textStyle"
+    >
+      {{ avatarText }}
+    </div>
+    <!-- 允许外部插入装饰，如群聊角标 -->
+    <slot></slot>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/user/user-info-card.vue b/apps/web-ele/src/views/im/home/components/user/user-info-card.vue
new file mode 100644
index 000000000..ec33489ed
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/user/user-info-card.vue
@@ -0,0 +1,121 @@
+<script lang="ts" setup>
+import { computed, onMounted, onUnmounted } from 'vue'
+import { useRouter } from 'vue-router'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { ImConversationType } from '../../../utils/constants'
+import { getFriendDisplayName } from '../../../utils/user'
+import { useConversationStore } from '../../store/conversationStore'
+import { useFriendStore } from '../../store/friendStore'
+import { useImUiStore } from '../../store/uiStore'
+import UserInfo, { type UserInfoRelation } from './user-info.vue'
+
+defineOptions({ name: 'ImUserInfoCard' })
+
+const uiStore = useImUiStore()
+const conversationStore = useConversationStore()
+const friendStore = useFriendStore()
+const router = useRouter()
+
+const card = computed(() => uiStore.userInfoCard)
+const user = computed(() => card.value.user)
+
+const isSelf = computed(() => {
+  const myId = getCurrentUserId()
+  return !!user.value?.id && user.value.id === myId
+})
+const isActiveFriend = computed(() => {
+  if (!user.value?.id || isSelf.value) {
+    return false
+  }
+  return friendStore.isActiveFriend(user.value.id)
+})
+const relation = computed<UserInfoRelation>(() => {
+  if (!user.value) {
+    return 'readonly'
+  }
+  if (isSelf.value) {
+    return 'self'
+  }
+  if (isActiveFriend.value) {
+    return 'friend'
+  }
+  return 'stranger'
+})
+
+const remark = computed(() => {
+  if (!isActiveFriend.value || !user.value?.id) {
+    return undefined
+  }
+  return friendStore.getFriend(user.value.id)?.displayName || ''
+})
+
+/** 关闭名片：点击遮罩 / Esc / UserInfo 抛上来的删除成功事件 */
+function handleClose() {
+  uiStore.closeUserInfoCard()
+}
+
+/** 键盘事件：Esc 键关闭名片 */
+function handleKeydown(e: KeyboardEvent) {
+  if (e.key === 'Escape' && card.value.show) {
+    handleClose()
+  }
+}
+
+onMounted(() => window.addEventListener('keydown', handleKeydown))
+onUnmounted(() => window.removeEventListener('keydown', handleKeydown))
+
+/** 发消息：UserInfo 抛上来的"发消息"，由本组件接力做 openConversation + 跳消息 Tab + 关浮层 */
+function handleSendMessage() {
+  if (!user.value) {
+    return
+  }
+  // 取 friendStore 里的最新备注 / 免打扰，避免新建会话用过期数据
+  const friend = friendStore.getFriend(user.value.id)
+  const conversationName = friend
+    ? getFriendDisplayName(friend)
+    : user.value.nickname || ''
+  conversationStore.openConversation(
+    user.value.id,
+    ImConversationType.PRIVATE,
+    conversationName,
+    user.value.avatar || '',
+    { silent: !!friend?.silent }
+  )
+  // 跳转会话 Tab（如果不在的话），并且不管当前路由是啥都先切到会话列表页
+  if (router.currentRoute.value.name !== 'ImHomeConversation') {
+    router.push({ name: 'ImHomeConversation' })
+  }
+  uiStore.closeUserInfoCard()
+}
+</script>
+
+<template>
+  <!--
+    用户名片浮层
+    - 仅承担"浮层定位 + 关闭逻辑（点遮罩 / Esc）"，名片视觉走 <UserInfo>，与 contact 详情共用一份组件
+    - 触发：useImUiStore.openUserInfoCard(user, position)；本组件订阅 store，全局只挂一份实例
+    - 关系态由 isSelf / isActiveFriend 派生 relation prop 透到 UserInfo；删除 / 加好友 / 备注落库都在 UserInfo 内闭环
+  -->
+  <teleport to="body">
+    <div v-if="card.show" class="fixed inset-0 z-9998" @click.self="handleClose">
+      <div
+        class="fixed w-80 p-4 bg-[var(--ant-color-bg-elevated)] rounded-md shadow-xl"
+        :style="{ left: `${card.position.x }px`, top: `${card.position.y }px` }"
+        @click.stop
+      >
+        <UserInfo
+          :user="user"
+          :display-name="remark"
+          :relation="relation"
+          :preview-z-index="10000"
+          :add-source="card.addSource"
+          :add-source-extra="card.addSourceExtra"
+          @chat="handleSendMessage"
+          @deleted="handleClose"
+        />
+      </div>
+    </div>
+  </teleport>
+</template>
diff --git a/apps/web-ele/src/views/im/home/components/user/user-info.vue b/apps/web-ele/src/views/im/home/components/user/user-info.vue
new file mode 100644
index 000000000..a339fb2a3
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/components/user/user-info.vue
@@ -0,0 +1,449 @@
+<script lang="ts" setup>
+import type { CheckboxValueType } from 'element-plus'
+
+import type { User } from '../../types'
+
+import { computed, h, nextTick, ref, watch } from 'vue'
+
+import { confirm } from '@vben/common-ui'
+import { DICT_TYPE } from '@vben/constants'
+import { getDictLabel } from '@vben/hooks'
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElButton, ElCheckbox, ElDropdown, ElDropdownItem, ElDropdownMenu, ElInput, ElMessage } from 'element-plus'
+
+import { getSimpleUser, type SystemUserApi } from '#/api/system/user'
+import { formatDate } from '#/views/im/utils/time'
+
+import { ImFriendAddSource } from '../../../utils/constants'
+import { toUserCardTarget } from '../../../utils/message'
+import { getGenderColor, getGenderIcon } from '../../../utils/user'
+import { useFriendStore } from '../../store/friendStore'
+import { FriendAddDialog } from '../friend'
+import RecommendCardDialog from './recommend-card-dialog.vue'
+import UserAvatar from './user-avatar.vue'
+
+defineOptions({ name: 'ImUserInfo' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 加好友来源；默认 SEARCH；参见 ImFriendAddSource */
+    addSource?: number
+    /** 来源附带信息：addSource=GROUP（群聊）时传群名，用于「我是 XX 群的 YY」预填话术 */
+    addSourceExtra?: string
+    /** 备注：仅 relation=friend 时有效；空串 → 显示"添加备注"占位 */
+    displayName?: string
+    /** UserAvatar 预览层 z-index；放在高 z-index 浮层（如 UserInfoCard）里需手动抬高 */
+    previewZIndex?: number
+    relation?: UserInfoRelation
+    /** 起手用户：至少要有 id；性别 / 部门由组件按 id 懒拉合并补齐 */
+    user: null | User
+  }>(),
+  {
+    addSource: ImFriendAddSource.SEARCH,
+    addSourceExtra: '',
+    displayName: '',
+    previewZIndex: 2000,
+    relation: 'readonly'
+  }
+)
+
+const emit = defineEmits<{
+  /** 用户点"发消息"：导航 / 关浮层等场景相关动作由父级承担（比如 UserInfoCard 要 close） */
+  chat: [user: User]
+  /** 删除联系人成功后通知父级（confirm + 调 store 都在本组件内做完）：父级关浮层 / 清选中等 */
+  deleted: [user: User]
+  /** 备注落库成功后通知父级，用于同步父级持有的本地 FriendLite / Friend 副本（如 contact 页的 selection） */
+  saved: [value: string]
+}>()
+
+/**
+ * 关系态：决定备注行 / 右上 "..." 菜单 / 底部动作区的内容
+ * - friend: 备注（可编辑）+ "..." 删除菜单 + 3 图标动作
+ * - stranger: 单按钮"加为好友"
+ * - self: 单按钮"不能和自己聊天" disabled
+ * - readonly: 不渲染备注 / 菜单 / 动作区，仅展示头部信息
+ */
+export type UserInfoRelation = 'friend' | 'readonly' | 'self' | 'stranger'
+
+const friendStore = useFriendStore()
+
+const full = ref<null | User>(props.user) // 起手 user + getSimpleUser 合并后的完整对象（性别 / 部门补齐用）
+
+/** 主标题：备注优先（好友场景），其次原昵称 */
+const headerName = computed(() => props.displayName || full.value?.nickname || '')
+
+const deptText = computed(() => full.value?.deptName || '-')
+
+const genderIcon = computed(() => getGenderIcon(full.value?.sex))
+const genderColor = computed(() => getGenderColor(full.value?.sex))
+
+/** 好友关系记录：来源 / 添加时间 / 是否拉黑从这里取（仅 friend 态下才有意义） */
+const friendInfo = computed(() =>
+  props.user?.id ? friendStore.getFriend(props.user.id) : undefined
+)
+
+/** 是否已拉黑：菜单项「加入黑名单 / 移出黑名单」按这个切换 */
+const isBlocked = computed(() => !!friendInfo.value?.blocked)
+
+const editingRemark = ref(false) // 备注内联编辑：editingRemark 控制输入态；user 切换时由下面的 watch 复位避免脏态泄漏
+const remarkInput = ref('')
+const remarkInputRef = ref<null | { focus: () => void; select?: () => void }>(null)
+
+/**
+ * user.id 变化的统一处理：
+ * 1. 起手用 prop 兜底首屏（full = props.user），再 getSimpleUser 命中后合并替换
+ * 2. 顺便复位备注编辑态，避免上一个用户的脏输入泄漏到下一个
+ * 3. 竞态用 id 比对丢弃陈旧响应
+ */
+watch(
+  () => props.user?.id,
+  async (id) => {
+    full.value = props.user
+    editingRemark.value = false
+    if (!id) {
+      return
+    }
+    const data = (await getSimpleUser(id)) as User
+    if (props.user?.id !== id) {
+      return
+    }
+    full.value = { ...props.user, ...data }
+  },
+  { immediate: true }
+)
+
+/** 备注行点击：进编辑态 + 把当前备注灌进输入框，下一帧把焦点 / 全选交给 el-input */
+async function handleRowClick() {
+  if (editingRemark.value) {
+    return
+  }
+  remarkInput.value = props.displayName || ''
+  editingRemark.value = true
+  await nextTick()
+  remarkInputRef.value?.focus()
+  remarkInputRef.value?.select?.()
+}
+
+/**
+ * 保存备注：
+ * 1. 重入保护——blur + Enter 同时触发只走一次（编辑态先复位）
+ * 2. 无变化跳过后端调用 + 不抛 saved，避免父级误同步
+ * 3. 落库成功 / 失败都在组件内自闭：成功抛 saved 让父级同步本地副本，失败留编辑态外的展示值不动
+ */
+async function saveRemark() {
+  if (!editingRemark.value) {
+    return
+  }
+  const userId = props.user?.id
+  if (!userId) {
+    editingRemark.value = false
+    return
+  }
+  const next = remarkInput.value.trim()
+  editingRemark.value = false
+  if (next === (props.displayName || '')) {
+    return
+  }
+  await friendStore.setFriendDisplayName(userId, next)
+  ElMessage.success('已更新备注')
+  emit('saved', next)
+}
+
+function cancelEditRemark() {
+  editingRemark.value = false
+}
+
+/** 发消息：导航 / 关浮层这些"业务侧"动作交给父级，本组件只负责通知 */
+function handleChat() {
+  if (!props.user) {
+    return
+  }
+  emit('chat', props.user)
+}
+
+/** 占位提示：语音 / 视频聊天能力尚未接入，先以"开发中"友好提示 */
+function handleComingSoon(featureName: string) {
+  ElMessage.info(`${featureName} 功能开发中`)
+}
+
+// ==================== 添加好友 / 删除好友 ====================
+
+const friendAddDialogRef = ref<InstanceType<typeof FriendAddDialog>>() // 加好友弹窗 ref：handleAddFriend 调 open({ presetUser, addSource, addSourceExtra }) 触发
+
+const recommendDialogRef = ref<InstanceType<typeof RecommendCardDialog>>() // 推荐名片弹窗 ref：handleRecommend 调用 open({ target }) 打开
+/** 把他推荐给朋友：弹 RecommendCardDialog 选目标会话 */
+function handleRecommend() {
+  if (!props.user?.id) {
+    return
+  }
+  const target = toUserCardTarget(full.value)
+  if (!target) {
+    return
+  }
+  recommendDialogRef.value?.open({ target })
+}
+
+/** 加为好友：弹 FriendAddDialog（带预填用户），让用户填申请理由 + 备注后再发申请 */
+function handleAddFriend() {
+  if (!props.user?.id) {
+    return
+  }
+  const presetUser: SystemUserApi.UserSimple = {
+    id: props.user.id,
+    nickname: props.user.nickname,
+    avatar: props.user.avatar,
+    sex: props.user.sex,
+    deptId: props.user.deptId,
+    deptName: props.user.deptName
+  } as SystemUserApi.UserSimple
+  friendAddDialogRef.value?.open({
+    presetUser,
+    addSource: props.addSource,
+    addSourceExtra: props.addSourceExtra
+  })
+}
+
+/** 加入黑名单：confirm → friendStore.blockFriend；后端 FRIEND_BLOCK 推到时由 dispatcher 同步多端 */
+async function handleBlock() {
+  if (!props.user?.id) {
+    return
+  }
+  const target = props.user
+  try {
+    await confirm(`确定将「${target.nickname || ''}」加入黑名单吗？`, '加入黑名单')
+  } catch {
+    return
+  }
+  await friendStore.blockFriend(target.id)
+  ElMessage.success('已加入黑名单')
+}
+
+/** 移出黑名单：操作温和不弹 confirm；后端 FRIEND_UNBLOCK 推到时由 dispatcher 同步多端 */
+async function handleUnblock() {
+  if (!props.user?.id) {
+    return
+  }
+  await friendStore.unblockFriend(props.user.id)
+  ElMessage.success('已移出黑名单')
+}
+
+/** 删除联系人：弹自定义确认（含「同时清空聊天记录」选项）→ friendStore.deleteFriend → 通知父级关浮层 / 清选中 */
+async function handleDeleteFriend() {
+  if (!props.user?.id) {
+    return
+  }
+  const target = props.user
+  const clearConversation = ref(true)
+  try {
+    await confirm({
+      cancelText: '取消',
+      confirmText: '删除',
+      content: h('div', { class: 'flex flex-col gap-3 text-sm' }, [
+        h('div', `确定删除好友「${target.nickname || ''}」?`),
+        h(
+          ElCheckbox,
+          {
+            modelValue: clearConversation.value,
+            onChange: (value: CheckboxValueType) => {
+              clearConversation.value = Boolean(value)
+            }
+          },
+          () => '同时清空聊天记录'
+        )
+      ]),
+      icon: 'warning',
+      title: '删除联系人'
+    })
+  } catch {
+    return
+  }
+  await friendStore.deleteFriend(target.id, clearConversation.value)
+  ElMessage.success('已删除好友')
+  emit('deleted', target)
+}
+</script>
+
+<template>
+  <!--
+    用户名片自包含组件（浮层 / 行内通用）
+    - 由 UserInfoCard（浮层）和 contact/index.vue（行内）共用：UserInfoCard 把它放进 teleport 浮层，contact 直接 mount 到右栏
+    - 关系态由 relation prop 决定（friend / stranger / self / readonly），对应右上 "..." 菜单 + 底部动作区两块都内化在本组件
+    - 备注 / 删除联系人 / 加为好友等 store 操作都在本组件内闭环，父级仅监听 chat / deleted / saved 等通知做导航 / 关浮层 / 同步副本
+  -->
+  <div>
+    <!-- 顶部：头像（左） + 名字 + 性别图标 + 昵称 / 部门（右） + 右上 "..." 菜单（仅 friend 态） -->
+    <div class="flex gap-3 items-start">
+      <UserAvatar
+        :id="full?.id"
+        :url="full?.avatar"
+        :name="full?.nickname"
+        :size="56"
+        :clickable="false"
+        previewable
+        :preview-z-index="previewZIndex"
+      />
+      <div class="flex-1 min-w-0">
+        <div class="flex items-center gap-1.5">
+          <span
+            class="text-lg font-semibold leading-snug truncate text-[var(--ant-color-text)]"
+          >
+            {{ headerName }}
+          </span>
+          <!-- 性别小图标：男蓝、女粉，未知 / 0 不展示，对齐微信留白做法 -->
+          <Icon
+            v-if="genderIcon"
+            :icon="genderIcon"
+            :size="16"
+            :color="genderColor"
+            class="flex-shrink-0"
+          />
+        </div>
+        <div class="mt-2 space-y-1 text-13px text-[var(--ant-color-text-secondary)]">
+          <!-- 仅当备注已设时展示昵称副行；未设置时主标题就是 nickname，避免重复 -->
+          <div v-if="displayName" class="truncate">昵称：{{ full?.nickname }}</div>
+          <div class="truncate">部门：{{ deptText }}</div>
+        </div>
+      </div>
+      <!-- 右上 "..." 菜单：仅 friend 态展示；含「加入/移出黑名单」 + 「删除联系人」 -->
+      <div v-if="relation === 'friend'" class="flex-shrink-0">
+        <ElDropdown trigger="click" placement="bottom-end" popper-class="im-user-info__more-menu">
+          <div
+            class="flex items-center justify-center w-7 h-7 rounded cursor-pointer hover:bg-[var(--ant-color-fill-secondary)]"
+          >
+            <Icon icon="ep:more-filled" :size="18" class="text-[var(--ant-color-text-secondary)]" />
+          </div>
+          <template #dropdown>
+            <ElDropdownMenu>
+              <!-- 把他推荐给朋友：以个人名片消息形式发到选中的会话 -->
+              <ElDropdownItem @click="handleRecommend">把他推荐给朋友</ElDropdownItem>
+              <!-- 拉黑 / 移出黑名单：按 friendInfo.blocked 切换文案 -->
+              <ElDropdownItem v-if="!isBlocked" divided @click="handleBlock">
+加入黑名单
+</ElDropdownItem>
+              <ElDropdownItem v-else divided @click="handleUnblock">移出黑名单</ElDropdownItem>
+              <ElDropdownItem divided @click="handleDeleteFriend">
+                <span class="text-[var(--ant-color-error)]">删除联系人</span>
+              </ElDropdownItem>
+            </ElDropdownMenu>
+          </template>
+        </ElDropdown>
+      </div>
+    </div>
+
+    <!-- 备注行：仅 friend 态展示，未编辑时整行可点；编辑态用 el-input 行内替换 value 列 -->
+    <template v-if="relation === 'friend'">
+      <div class="my-4 h-px bg-[var(--ant-color-border-secondary)]"></div>
+      <div
+        class="flex gap-5 items-center px-1.5 py-1.5 text-sm"
+        :class="
+          !editingRemark
+            ? 'group cursor-pointer rounded transition-colors hover:bg-[var(--ant-color-fill-tertiary)]'
+            : ''
+        "
+        @click="handleRowClick"
+      >
+        <span class="flex-shrink-0 w-16 whitespace-nowrap text-[var(--ant-color-text-secondary)]">备注</span>
+        <ElInput
+          v-if="editingRemark"
+          ref="remarkInputRef"
+          v-model="remarkInput"
+          size="small"
+          :maxlength="20"
+          placeholder="添加备注"
+          class="flex-1"
+          @click.stop
+          @blur="saveRemark"
+          @keyup.enter="saveRemark"
+          @keyup.esc="cancelEditRemark"
+        />
+        <template v-else>
+          <span
+            class="flex-1 min-w-0 truncate"
+            :class="
+              displayName
+                ? 'text-[var(--ant-color-text)]'
+                : 'text-[var(--ant-color-text-placeholder)]'
+            "
+          >
+            {{ displayName || '添加备注' }}
+          </span>
+          <!-- 默认 opacity:0 占位避免 hover 时其它列位移；仅父行 hover 时浮现 -->
+          <Icon
+            icon="ant-design:edit-outlined"
+            :size="14"
+            class="flex-shrink-0 text-[var(--ant-color-text-secondary)] opacity-0 group-hover:opacity-100 transition-opacity"
+          />
+        </template>
+      </div>
+
+      <!-- ==================== 更多信息：来源 / 添加时间，对齐微信「朋友资料」分块 ==================== -->
+      <template v-if="friendInfo?.addSource || friendInfo?.addTime">
+        <div class="my-4 h-px bg-[var(--ant-color-border-secondary)]"></div>
+        <div v-if="friendInfo?.addSource" class="flex gap-5 items-center px-1.5 py-1.5 text-sm">
+          <span class="flex-shrink-0 w-16 whitespace-nowrap text-[var(--ant-color-text-secondary)]">来源</span>
+          <span class="flex-1 min-w-0 truncate text-[var(--ant-color-text)]">
+            {{ getDictLabel(DICT_TYPE.IM_FRIEND_ADD_SOURCE, friendInfo.addSource) }}
+          </span>
+        </div>
+        <div v-if="friendInfo?.addTime" class="flex gap-5 items-center px-1.5 py-1.5 text-sm">
+          <span class="flex-shrink-0 w-16 whitespace-nowrap text-[var(--ant-color-text-secondary)]">添加时间</span>
+          <span class="flex-1 min-w-0 truncate text-[var(--ant-color-text)]">
+            {{ formatDate(new Date(friendInfo.addTime), 'YYYY-MM-DD') }}
+          </span>
+        </div>
+      </template>
+    </template>
+
+    <!-- 动作区：好友 = 3 图标；陌生人 = 加为好友按钮；自己 = disabled；readonly 不渲染 -->
+    <template v-if="relation !== 'readonly'">
+      <div class="my-4 h-px bg-[var(--ant-color-border-secondary)]"></div>
+      <div v-if="relation === 'friend'" class="flex justify-around">
+        <!-- 三连图标按钮：图上字下、主色作为可点暗示，hover 降不透明度做反馈 -->
+        <div
+          class="flex flex-col gap-1.5 items-center cursor-pointer text-13px text-[var(--ant-color-primary)] transition-opacity hover:opacity-75"
+          @click="handleChat"
+        >
+          <Icon icon="ant-design:message-outlined" :size="22" />
+          <span>发消息</span>
+        </div>
+        <div
+          class="flex flex-col gap-1.5 items-center cursor-pointer text-13px text-[var(--ant-color-primary)] transition-opacity hover:opacity-75"
+          @click="handleComingSoon('语音聊天')"
+        >
+          <Icon icon="ant-design:phone-outlined" :size="22" />
+          <span>语音聊天</span>
+        </div>
+        <div
+          class="flex flex-col gap-1.5 items-center cursor-pointer text-13px text-[var(--ant-color-primary)] transition-opacity hover:opacity-75"
+          @click="handleComingSoon('视频聊天')"
+        >
+          <Icon icon="ant-design:video-camera-outlined" :size="22" />
+          <span>视频聊天</span>
+        </div>
+      </div>
+      <div v-else-if="relation === 'self'" class="flex justify-center">
+        <ElButton type="primary" disabled>不能和自己聊天</ElButton>
+      </div>
+      <div v-else class="flex justify-center">
+        <ElButton type="primary" @click="handleAddFriend">加为好友</ElButton>
+      </div>
+    </template>
+
+    <!-- 加好友弹窗：携带预填用户跳过搜索步骤，直接进申请表单（理由按 addSource 区分话术） -->
+    <FriendAddDialog ref="friendAddDialogRef" />
+
+    <!-- 把他推荐给朋友弹窗：仅 friend 态下出现入口 -->
+    <RecommendCardDialog ref="recommendDialogRef" />
+  </div>
+</template>
+
+<style>
+/*
+  非 scoped：el-dropdown 的下拉菜单走 teleport 到 body，scoped 选不到。
+  UserInfoCard 浮层用 z-9998，要把这块抬到更高（默认 --ant-z-index-popup-base ~2050 会被遮罩压住）。
+*/
+.im-user-info__more-menu {
+  z-index: 10000 !important;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/composables/useFriendBuckets.ts b/apps/web-ele/src/views/im/home/composables/useFriendBuckets.ts
new file mode 100644
index 000000000..9b2ad1acc
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/composables/useFriendBuckets.ts
@@ -0,0 +1,99 @@
+import type { FriendLite } from '../types'
+
+import { computed, type ComputedRef, type Ref } from 'vue'
+
+/** 字母分桶结果：letter 取 'A'-'Z' 或兜底 '#'；list 桶内按拼音 / 名字自然序 */
+export interface FriendBucket {
+  letter: string
+  list: FriendLite[]
+}
+
+/** 取分桶 / 排序键：备注拼音优先 → 昵称拼音 → 名字本身（兜底英文 / 数字） */
+function getSortKey(friend: FriendLite): string {
+  return (
+    friend.displayNamePinyin ||
+    friend.nicknamePinyin ||
+    (friend.displayName || friend.nickname || '').toLowerCase()
+  )
+}
+
+/** 取分桶字母：拼音首字母大写，非字母（纯符号 / 数字 / 中文）兜底 '#' */
+function getBucketLetter(friend: FriendLite): string {
+  const first = getSortKey(friend).charAt(0)
+  return /^[a-zA-Z]$/.test(first) ? first.toUpperCase() : '#'
+}
+
+/** 拼音首字母拼接：「lao zhang」→ 'lz'，支持「输 lz 搜老张」 */
+function pinyinInitials(pinyin?: string): string {
+  if (!pinyin) {
+    return ''
+  }
+  return pinyin
+    .split(' ')
+    .map((word) => word.charAt(0))
+    .join('')
+}
+
+/**
+ * 好友列表的搜索 + 字母分桶
+ *
+ * - 搜索匹配：备注 / 昵称 / 全拼（去空格）/ 首字母任一命中
+ * - 分桶规则：A-Z + '#' 兜底，桶内按 getSortKey 自然序
+ *
+ * 通讯录页 FriendList 与选择类弹窗 FriendPickerPanel 共用，避免规则各自实现走偏
+ */
+export function useFriendBuckets(
+  friends: ComputedRef<FriendLite[]> | Ref<FriendLite[]>,
+  keyword: Ref<string>
+): {
+  buckets: ComputedRef<FriendBucket[]>
+  filtered: ComputedRef<FriendLite[]>
+} {
+  const filtered = computed(() => {
+    const keywordLower = keyword.value.trim().toLowerCase()
+    if (!keywordLower) {
+      return friends.value
+    }
+    return friends.value.filter((friend) => {
+      const nicknamePinyin = friend.nicknamePinyin || ''
+      const displayNamePinyin = friend.displayNamePinyin || ''
+      // 全拼搜索去掉空格，让「laozhang」也能命中「lao zhang」
+      return (
+        (friend.nickname || '').toLowerCase().includes(keywordLower) ||
+        (friend.displayName || '').toLowerCase().includes(keywordLower) ||
+        nicknamePinyin.replaceAll(/\s/g, '').includes(keywordLower) ||
+        displayNamePinyin.replaceAll(/\s/g, '').includes(keywordLower) ||
+        pinyinInitials(nicknamePinyin).includes(keywordLower) ||
+        pinyinInitials(displayNamePinyin).includes(keywordLower)
+      )
+    })
+  })
+
+  const buckets = computed<FriendBucket[]>(() => {
+    const map = new Map<string, FriendLite[]>()
+    for (const friend of filtered.value) {
+      const letter = getBucketLetter(friend)
+      const bucket = map.get(letter) ?? []
+      bucket.push(friend)
+      map.set(letter, bucket)
+    }
+    const letters = [...map.keys()].toSorted((a, b) => {
+      // '#' 永远排末尾，A-Z 走 localeCompare
+      if (a === '#') {
+        return 1
+      }
+      if (b === '#') {
+        return -1
+      }
+      return a.localeCompare(b)
+    })
+    return letters.map((letter) => ({
+      letter,
+      list: (map.get(letter) ?? []).toSorted((a, b) =>
+        getSortKey(a).localeCompare(getSortKey(b))
+      )
+    }))
+  })
+
+  return { filtered, buckets }
+}
diff --git a/apps/web-ele/src/views/im/home/composables/useGroupCallMembers.ts b/apps/web-ele/src/views/im/home/composables/useGroupCallMembers.ts
new file mode 100644
index 000000000..b6fb41630
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/composables/useGroupCallMembers.ts
@@ -0,0 +1,53 @@
+import { computed, type ComputedRef, type Ref } from 'vue'
+
+import { ImConversationType } from '../../utils/constants'
+import { getSenderAvatar, getSenderDisplayName } from '../../utils/user'
+import { useRtcStore } from '../store/rtcStore'
+
+/** 群通话成员视图模型：已加入 + 接入中；pending 头像 UI 半透明，joined 不透明 */
+export interface GroupCallMember {
+  userId: number
+  nickname: string
+  avatar?: string
+  pending: boolean
+}
+
+/**
+ * 群通话成员列表 computed：joined 在前，未 joined 的 invitee 在后；
+ * 缓存为空（来电首屏渲染早于 syncGroupActiveCall 回写）时用 fallback 主叫兜底，避免空白
+ *
+ * @param groupId 群编号
+ * @param fallbackInviterId 兜底主叫；缓存为空时填一个头像，标记为已加入而非 pending
+ */
+export function useGroupCallMembers(
+  groupId: Ref<number | undefined>,
+  fallbackInviterId?: Ref<number | undefined>
+): ComputedRef<GroupCallMember[]> {
+  const rtcStore = useRtcStore()
+  return computed(() => {
+    const gid = groupId.value
+    if (!gid) {
+      return []
+    }
+    const groupCall = rtcStore.getGroupCall(gid)
+    const joinedIds = groupCall?.joinedUserIds ?? []
+    const inviteeIds = groupCall?.inviteeIds ?? []
+    const joinedSet = new Set(joinedIds)
+    const orderedIds = [...joinedIds, ...inviteeIds.filter((id) => !joinedSet.has(id))]
+    if (orderedIds.length > 0) {
+      return orderedIds.map((userId) => toVM(userId, gid, !joinedSet.has(userId)))
+    }
+    const fallback = fallbackInviterId?.value
+    return fallback ? [toVM(fallback, gid, false)] : []
+  })
+}
+
+/** 把 userId 翻译成视图模型，统一走 user.ts helper 解析昵称 / 头像 */
+function toVM(userId: number, groupId: number, pending: boolean): GroupCallMember {
+  return {
+    userId,
+    nickname: getSenderDisplayName(userId, ImConversationType.GROUP, groupId),
+    avatar: getSenderAvatar(userId, ImConversationType.GROUP, groupId) || undefined,
+    pending
+  }
+}
diff --git a/apps/web-ele/src/views/im/home/composables/useLiveKitRoom.ts b/apps/web-ele/src/views/im/home/composables/useLiveKitRoom.ts
new file mode 100644
index 000000000..7cc0a5a7d
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/composables/useLiveKitRoom.ts
@@ -0,0 +1,331 @@
+import { computed, ref, shallowRef } from 'vue'
+
+import {
+  ConnectionQuality,
+  type LocalParticipant,
+  type Participant,
+  type RemoteParticipant,
+  Room,
+  RoomEvent,
+  Track,
+  VideoPresets
+} from 'livekit-client'
+
+type ParticipantEventHandler = (userId: number) => void
+
+/** LiveKit Room 连接 / 设备 / 事件的薄封装；UI 组件只关心响应式状态 */
+export function useLiveKitRoom() {
+  /** Room 实例；模块内部状态，不对外暴露，避免调用方误写 */
+  const _room = shallowRef<null | Room>(null)
+  /** 只读 room 引用；调用方仅用于幂等判定 */
+  const room = computed(() => _room.value)
+  /** 本地参与者；连接成功后赋值 */
+  const localParticipant = shallowRef<LocalParticipant | null>(null)
+  /** 远端参与者列表；ParticipantConnected / Disconnected 时刷新；shallowRef 避免 Vue 深度代理 SDK class 内部 */
+  const remoteParticipants = shallowRef<RemoteParticipant[]>([])
+  /** 连接状态 */
+  const isConnected = ref(false)
+  /** 连接质量 */
+  const connectionQuality = ref<ConnectionQuality>(ConnectionQuality.Unknown)
+  /** 麦克风开关 */
+  const micEnabled = ref(true)
+  /** 摄像头开关 */
+  const cameraEnabled = ref(false)
+  /** 扬声器开关；浏览器无系统级 API，通过 audio 元素 muted 属性实现远端音频静音 */
+  const speakerEnabled = ref(true)
+  /** 屏幕共享开关 */
+  const screenShareEnabled = ref(false)
+  /** 当前是否处于「重连中」；瞬断时 UI 显示提示而不强制结束通话 */
+  const reconnecting = ref(false)
+  /** 远端断开订阅者；通话结束时统一清空 */
+  const disconnectedHandlers = new Set<() => void>()
+  /** 房内某人加入订阅者；主叫端用于从 INVITING 切到 RUNNING */
+  const participantConnectedHandlers = new Set<ParticipantEventHandler>()
+  /** 房内某人离开订阅者；用于把 userId 标记为「已退出」从 pending 占位中移除 */
+  const participantDisconnectedHandlers = new Set<ParticipantEventHandler>()
+
+  /** 同步远端参与者列表到响应式数组 */
+  function syncRemotes(r: Room) {
+    remoteParticipants.value = [...r.remoteParticipants.values()]
+  }
+
+  /** 连接 LiveKit Server；audio / video 控制初始默认开关 */
+  async function connect(url: string, token: string, opts: { audio?: boolean; video?: boolean }) {
+    // 新连接前先断开旧 Room；保留本次注册的事件回调
+    if (_room.value) {
+      await disconnectRoom(false)
+    }
+    const r = new Room({
+      // 按格子尺寸自动选 simulcast 层
+      adaptiveStream: true,
+      // 未订阅的层动态停发，节省上行
+      dynacast: true,
+      // 采集分辨率 720p，确保大格子清晰
+      videoCaptureDefaults: {
+        resolution: VideoPresets.h720.resolution
+      },
+      // 发布编码上限 1.5 Mbps / 30fps；保留默认 simulcast 三层（180p / 360p / 720p）
+      publishDefaults: {
+        videoEncoding: {
+          maxBitrate: 1_500_000,
+          maxFramerate: 30,
+          priority: 'high'
+        },
+        // 屏幕共享码率 3 Mbps，文字界面清晰
+        screenShareEncoding: {
+          maxBitrate: 3_000_000,
+          maxFramerate: 15,
+          priority: 'medium'
+        }
+      }
+    })
+    _room.value = r
+
+    r.on(RoomEvent.ParticipantConnected, (rp) => {
+        syncRemotes(r)
+        const userId = parseUserId(rp.identity)
+        if (userId != null) {
+          participantConnectedHandlers.forEach((cb) => cb(userId))
+        }
+      })
+      .on(RoomEvent.ParticipantDisconnected, (rp) => {
+        syncRemotes(r)
+        // 离开的参与者缓存清掉，避免下次同 sid 重连命中失效引用
+        for (const key of streamCache.keys()) {
+          if (key.startsWith(`${rp.sid}:`)) {
+            streamCache.delete(key)
+          }
+        }
+        const userId = parseUserId(rp.identity)
+        if (userId != null) {
+          participantDisconnectedHandlers.forEach((cb) => cb(userId))
+        }
+      })
+      .on(RoomEvent.TrackSubscribed, () => syncRemotes(r))
+      .on(RoomEvent.TrackUnsubscribed, () => syncRemotes(r))
+      // mute / unmute 让 pickStream 的 isMuted 短路重算，video 元素能解绑 srcObject 而不是卡最后一帧
+      .on(RoomEvent.TrackMuted, () => syncRemotes(r))
+      .on(RoomEvent.TrackUnmuted, () => syncRemotes(r))
+      .on(RoomEvent.ConnectionQualityChanged, (quality) => {
+        connectionQuality.value = quality
+      })
+      // 瞬断 → 显示「重连中」；不关通话窗，由 SDK 内部重连机制恢复
+      .on(RoomEvent.Reconnecting, () => {
+        reconnecting.value = true
+      })
+      .on(RoomEvent.Reconnected, () => {
+        reconnecting.value = false
+      })
+      // 重连失败 / 主动断 / 被踢时触发清理
+      .on(RoomEvent.Disconnected, () => {
+        isConnected.value = false
+        reconnecting.value = false
+        disconnectedHandlers.forEach((cb) => cb())
+      })
+
+    // 预热 getUserMedia 与 WebSocket 握手并行，省 100～300ms 串行延迟；
+    // 拿到的 stream 仅用于触发权限弹窗 + 设备就绪，握手完成后由 LiveKit 内部重新请求设备发布轨
+    const warmup = prewarmMedia(opts)
+    // 建立 WebSocket 信令 + WebRTC 媒体通道；完成后 localParticipant 可用，已在房参与者会通过 ParticipantConnected 事件批量推送
+    await r.connect(url, token)
+    // 期间被外部 disconnect 替换；中止后续 publish，避免摄像头被重新启用
+    if (_room.value !== r) {
+      return
+    }
+    localParticipant.value = r.localParticipant
+    isConnected.value = true
+
+    // 预热结果不直接发布（避免 SDK 与外部 track 生命周期纠缠），仅等待权限就绪后再走标准 setXxxEnabled
+    await warmup
+    if (_room.value !== r) {
+      return
+    }
+    // 麦克风与摄像头权限相互独立，并行启用发布
+    const inits: Promise<unknown>[] = []
+    if (opts.audio) {
+      inits.push(r.localParticipant.setMicrophoneEnabled(true))
+    }
+    if (opts.video) {
+      inits.push(r.localParticipant.setCameraEnabled(true))
+    }
+    if (inits.length > 0) {
+      await Promise.all(inits)
+    }
+    micEnabled.value = !!opts.audio
+    cameraEnabled.value = !!opts.video
+
+    // 兜底同步一次远端列表：r.connect 期间 ParticipantConnected 事件可能在 handler 绑定前触发被吞，导致首屏漏人
+    syncRemotes(r)
+  }
+
+  /** 提前触发权限弹窗 + 设备唤起，串行延迟在 r.connect 期间一起跑；失败静默（连接后会再试一次） */
+  async function prewarmMedia(opts: { audio?: boolean; video?: boolean }): Promise<void> {
+    if (!opts.audio && !opts.video) {
+      return
+    }
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({
+        audio: !!opts.audio,
+        video: !!opts.video
+      })
+      // 拿到权限即可，立即停掉所有 track 释放设备；正式发布走 SDK 流程重新请求
+      stream.getTracks().forEach((t) => t.stop())
+    } catch {
+      // 用户拒绝 / 设备占用等异常，交给后续 setXxxEnabled 再次尝试报错
+    }
+  }
+
+  /** 切麦克风 */
+  async function setMicEnabled(enabled: boolean) {
+    if (!_room.value) {
+      return
+    }
+    await _room.value.localParticipant.setMicrophoneEnabled(enabled)
+    micEnabled.value = enabled
+  }
+
+  /** 切摄像头 */
+  async function setCameraEnabled(enabled: boolean) {
+    if (!_room.value) {
+      return
+    }
+    await _room.value.localParticipant.setCameraEnabled(enabled)
+    cameraEnabled.value = enabled
+  }
+
+  /** 切扬声器；仅切响应式状态，实际静音由模板上 audio 元素 :muted 绑定生效 */
+  function setSpeakerEnabled(enabled: boolean) {
+    speakerEnabled.value = enabled
+  }
+
+  /**
+   * 切屏幕共享；
+   *
+   * 浏览器会弹原生「选择共享内容」对话框，用户在弹窗里点取消时 setScreenShareEnabled 会抛错，捕获并把状态复位回 SDK 的实际值
+   */
+  async function setScreenShareEnabled(enabled: boolean) {
+    if (!_room.value) return
+    try {
+      await _room.value.localParticipant.setScreenShareEnabled(enabled)
+      screenShareEnabled.value = enabled
+    } catch (error) {
+      // 用户在浏览器原生对话框里取消选择，不当作错误
+      screenShareEnabled.value = _room.value.localParticipant.isScreenShareEnabled
+      throw error
+    }
+  }
+
+  /** 注册「远端连接异常断开」回调；返回反注册函数 */
+  function onDisconnected(cb: () => void): () => void {
+    disconnectedHandlers.add(cb)
+    return () => disconnectedHandlers.delete(cb)
+  }
+
+  /** 注册「房内某人加入」回调；返回反注册函数 */
+  function onParticipantConnected(cb: ParticipantEventHandler): () => void {
+    participantConnectedHandlers.add(cb)
+    return () => participantConnectedHandlers.delete(cb)
+  }
+
+  /** 注册「房内某人离开」回调；返回反注册函数 */
+  function onParticipantDisconnected(cb: ParticipantEventHandler): () => void {
+    participantDisconnectedHandlers.add(cb)
+    return () => participantDisconnectedHandlers.delete(cb)
+  }
+
+  /** identity 是后端签 token 时塞的 userId 字符串，转 number 返回；非数字（兼容性兜底）返回 null */
+  function parseUserId(identity: string): null | number {
+    const id = Number(identity)
+    return Number.isNaN(id) ? null : id
+  }
+
+  /**
+   * MediaStream 缓存；key 为 `${participantSid}:${source}`，value 为 `{ track, stream }`；
+   * 同一条 MediaStreamTrack 复用同一个 MediaStream，避免 <video>.srcObject 反复重挂导致解码管线重建（视频闪烁）；
+   * track 引用切换（重新订阅 / 切流）时按需新建并替换
+   */
+  const streamCache = new Map<string, { stream: MediaStream; track: MediaStreamTrack; }>()
+
+  /**
+   * 取参与者指定来源的轨道并打包为 MediaStream；
+   * 参与者走 unknown 是因为响应式系统会丢失 livekit-client 的类签名，函数内手动 cast 回参与者类型；
+   * 命中缓存返回同一 MediaStream 引用，下游 watch / srcObject 无需重挂；
+   * 轨道被 mute（本端关摄像头 / 远端关摄像头）时返回 null，让 video 元素解绑 srcObject 而不是卡在最后一帧
+   */
+  function pickStream(participant: unknown, source: Track.Source): MediaStream | null {
+    const p = participant as Participant
+    const pub = p.getTrackPublication(source)
+    if (!pub || pub.isMuted) {
+      return null
+    }
+    const track = pub.track?.mediaStreamTrack
+    if (!track) {
+      return null
+    }
+    const key = `${p.sid}:${source}`
+    const cached = streamCache.get(key)
+    if (cached && cached.track === track) {
+      return cached.stream
+    }
+    const stream = new MediaStream([track])
+    streamCache.set(key, { track, stream })
+    return stream
+  }
+
+  /** 断开当前 Room；clearHandlers 为 true 时同步清理外部注册的事件回调 */
+  async function disconnectRoom(clearHandlers: boolean) {
+    // 清理通话结束后不再复用的订阅回调
+    if (clearHandlers) {
+      disconnectedHandlers.clear()
+      participantConnectedHandlers.clear()
+      participantDisconnectedHandlers.clear()
+    }
+    // 清理音视频轨道缓存
+    streamCache.clear()
+    if (_room.value) {
+      // 卸载 Room 事件并断开连接
+      _room.value.removeAllListeners()
+      await _room.value.disconnect()
+      _room.value = null
+    }
+    // 重置连接和设备状态
+    localParticipant.value = null
+    remoteParticipants.value = []
+    isConnected.value = false
+    reconnecting.value = false
+    micEnabled.value = true
+    cameraEnabled.value = false
+    speakerEnabled.value = true
+    screenShareEnabled.value = false
+  }
+
+  /** 主动断开；通话结束统一调 */
+  async function disconnect() {
+    await disconnectRoom(true)
+  }
+
+  return {
+    room,
+    localParticipant,
+    remoteParticipants,
+    isConnected,
+    connectionQuality,
+    micEnabled,
+    cameraEnabled,
+    speakerEnabled,
+    screenShareEnabled,
+    reconnecting,
+    connect,
+    disconnect,
+    setMicEnabled,
+    setCameraEnabled,
+    setSpeakerEnabled,
+    setScreenShareEnabled,
+    pickStream,
+    onDisconnected,
+    onParticipantConnected,
+    onParticipantDisconnected
+  }
+}
+
+export type ImLiveKitRoom = ReturnType<typeof useLiveKitRoom>
diff --git a/apps/web-ele/src/views/im/home/composables/useMediaStreamElement.ts b/apps/web-ele/src/views/im/home/composables/useMediaStreamElement.ts
new file mode 100644
index 000000000..7b9b581be
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/composables/useMediaStreamElement.ts
@@ -0,0 +1,27 @@
+import { ref, type VNodeRef, watch } from 'vue'
+
+/**
+ * 把响应式 MediaStream 挂到 `<video>` / `<audio>` 元素的 srcObject 上；
+ * stream 为空时清掉 srcObject，避免设备关闭后画面卡在最后一帧
+ */
+export function useMediaStreamElement<T extends HTMLMediaElement>(
+  streamSource: () => MediaStream | null | undefined
+): VNodeRef {
+  const elRef = ref<T>()
+  const syncStream = (stream = streamSource()) => {
+    if (elRef.value) {
+      elRef.value.srcObject = stream || null
+    }
+  }
+  watch(
+    streamSource,
+    (stream) => {
+      syncStream(stream)
+    },
+    { flush: 'post', immediate: true }
+  )
+  return (el) => {
+    elRef.value = el instanceof HTMLMediaElement ? (el as T) : undefined
+    syncStream()
+  }
+}
diff --git a/apps/web-ele/src/views/im/home/composables/useMediaUploader.ts b/apps/web-ele/src/views/im/home/composables/useMediaUploader.ts
new file mode 100644
index 000000000..51128c0a5
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/composables/useMediaUploader.ts
@@ -0,0 +1,408 @@
+import type { Conversation, Message } from '../types'
+
+import type { AxiosProgressEvent } from '#/api/infra/file'
+
+import { isOpenableUrl } from '@vben/utils'
+
+import { ElMessage } from 'element-plus'
+
+import { uploadFile } from '#/api/infra/file'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import {
+  MESSAGE_FILE_MAX_MB,
+  MESSAGE_IMAGE_MAX_MB,
+  MESSAGE_VIDEO_MAX_MB,
+  MESSAGE_VOICE_MAX_MB
+} from '../../utils/config'
+import { ImContentType, ImMessageStatus } from '../../utils/constants'
+import { getConversationKey } from '../../utils/conversation'
+import {
+  type AudioMessage,
+  BLOB_URL_PREFIX,
+  type FileMessage,
+  generateClientMessageId,
+  type ImageMessage,
+  parseMessage,
+  type QuoteMessage,
+  serializeMessage,
+  type VideoMessage,
+  withQuotePayload
+} from '../../utils/message'
+import { useConversationStore } from '../store/conversationStore'
+import { useMessageStore } from '../store/messageStore'
+import { useMessageSender } from './useMessageSender'
+import { useMuteOverlay } from './useMuteOverlay'
+
+type UploadProgressEvent = Parameters<NonNullable<AxiosProgressEvent>>[0]
+
+/** 单条媒体 payload 联合（覆盖 IMAGE / FILE / VOICE / VIDEO 四种） */
+export type MediaPayload = AudioMessage | FileMessage | ImageMessage | VideoMessage
+
+/**
+ * 媒体特定的元数据上下文：首发 / 重传共用入参；不同 type 关心不同字段
+ *
+ * - voiceDuration：语音时长（秒），首发由 VoiceRecorder 给，重传从旧 AudioMessage.duration 取
+ * - videoProbe：视频元信息（首发由 probeVideoFile 解出，重传从旧 VideoMessage 直接拷字段）
+ * - videoCoverUrl：视频封面真实 URL；占位阶段不设（避免传 blob 当 poster 在部分浏览器退化），commit 阶段由 cover 上传结果填入；重传时从旧 VideoMessage.coverUrl 复用，旧值若是 blob 会被跳过
+ */
+export interface MediaTypeContext {
+  voiceDuration?: number
+  videoProbe?: { duration?: number; height?: number; width?: number; }
+  videoCoverUrl?: string
+}
+
+export interface MediaTypeHandler {
+  /** 中文名，仅日志用（替代之前散落 9 处的 kind 字符串） */
+  kind: string
+  /** 由 file + url + context 生成 payload；占位时 url 是 blob URL，commit 时是真实 url */
+  build: (file: File, url: string, context: MediaTypeContext) => MediaPayload
+  /** 重传场景：从旧 content 提取 context（让重传不需要重做 probe / 重录语音） */
+  extractResendContext: (oldContent: string) => MediaTypeContext
+}
+
+/** 媒体类型注册表：image / file / voice / video 各自的 kind + 首发 / 重传共用的 build / extract */
+export const mediaTypeHandlers: Partial<Record<number, MediaTypeHandler>> = {
+  [ImContentType.IMAGE]: {
+    kind: '图片',
+    build: (_file, url) => ({ url }) as ImageMessage,
+    extractResendContext: () => ({})
+  },
+  [ImContentType.FILE]: {
+    kind: '文件',
+    build: (file, url) => ({ url, name: file.name, size: file.size }) as FileMessage,
+    extractResendContext: () => ({})
+  },
+  [ImContentType.VOICE]: {
+    kind: '语音',
+    build: (_file, url, context) => ({ url, duration: context.voiceDuration ?? 0 }) as AudioMessage,
+    extractResendContext: (oldContent) => {
+      const old = parseMessage<AudioMessage>(oldContent)
+      return { voiceDuration: old?.duration ?? 0 }
+    }
+  },
+  [ImContentType.VIDEO]: {
+    kind: '视频',
+    build: (file, url, context) =>
+      ({
+        url,
+        coverUrl: context.videoCoverUrl,
+        duration: context.videoProbe?.duration,
+        width: context.videoProbe?.width,
+        height: context.videoProbe?.height,
+        size: file.size
+      }) as VideoMessage,
+    extractResendContext: (oldContent) => {
+      const old = parseMessage<VideoMessage>(oldContent)
+      // 旧 coverUrl 是 blob 说明上传期失败（cover 没传成功），不复用；真实 URL 直接复用，省一次封面上传
+      const reuseCover =
+        old?.coverUrl && !old.coverUrl.startsWith(BLOB_URL_PREFIX) ? old.coverUrl : undefined
+      return {
+        videoProbe: { duration: old?.duration, width: old?.width, height: old?.height },
+        videoCoverUrl: reuseCover
+      }
+    }
+  }
+}
+
+/** 单次媒体上传的入参（image / file / voice 走 uploadAndSendMedia；video 走低层 helper 自行组装） */
+export interface UploadAndSendMediaOptions {
+  file: File
+  /** 对齐 ImContentType；mediaTypeHandlers 必须有对应项 */
+  type: number
+  /** 媒体特定的元数据（如语音时长 / 视频元信息）；不传按空对象处理 */
+  context?: MediaTypeContext
+  /** 引用消息（若有），写进 payload.quote */
+  quote?: QuoteMessage
+  /** 锁定起始会话，上传期间会话切走则放弃发送 */
+  conversation: Conversation
+  /** 重试已有占位消息时复用的客户端消息编号 */
+  existingClientMessageId?: string
+}
+
+/**
+ * 媒体上传 + 发送 composable（image / file / voice / video 共用底层 helper）
+ *
+ * 与 useMessageSender.sendRaw 的「先发请求再 ack」不同，媒体链路必须「先占位再上传」：
+ * 1. 立即 insertMessage 写入占位消息（status=SENDING、content 用 blob URL、_localFile 内存留 File）
+ * 2. uploadFile 上传，onUploadProgress 回调 patchMessage 更新 uploadProgress；UI 实时显示进度条
+ * 3. 上传成功后用真实 url 重生 content，patchMessage 替换；旧 blob URL 由 store 自动 revoke
+ * 4. 走 sendRaw(existingClientMessageId) 复用占位发送请求，避免重复插入两条
+ *
+ * 任意失败把消息状态置 FAILED；MessageItem 上点重试再走一次本函数（_localFile 还在内存就行）
+ */
+/** 按内容类型映射体积上限（MB）；未识别类型返回 0 表示不限 */
+function resolveMediaMaxMb(type: number): number {
+  switch (type) {
+    case ImContentType.FILE: {
+      return MESSAGE_FILE_MAX_MB
+    }
+    case ImContentType.IMAGE: {
+      return MESSAGE_IMAGE_MAX_MB
+    }
+    case ImContentType.VIDEO: {
+      return MESSAGE_VIDEO_MAX_MB
+    }
+    case ImContentType.VOICE: {
+      return MESSAGE_VOICE_MAX_MB
+    }
+    default: {
+      return 0
+    }
+  }
+}
+
+/** 校验媒体文件大小是否超过内容类型上限；超限触发 warn 并返回 false，调用方不应进入占位 / 上传链路 */
+export function ensureMediaSizeWithinLimit(
+  file: File,
+  type: number,
+  warn: (text: string) => void
+): boolean {
+  const maxMb = resolveMediaMaxMb(type)
+  if (maxMb && file.size > maxMb * 1024 * 1024) {
+    warn(`文件大小超过上限 ${maxMb}MB，请压缩后再发`)
+    return false
+  }
+  return true
+}
+
+export const useMediaUploader = () => {
+  const conversationStore = useConversationStore()
+  const messageStore = useMessageStore()
+  const muteOverlay = useMuteOverlay()
+  const { sendRaw } = useMessageSender()
+
+  /**
+   * 立即写入媒体占位消息（低层 helper；image/file/voice 走 uploadAndSendMedia 包装，video 直接用本函数）
+   *
+   * 用 createObjectURL(file) 生成临时 blob URL 喂给 buildContent；占位 status=SENDING + uploadProgress=0；
+   * file 挂在 _localFile 上供失败重试时重走上传
+   */
+  const insertMediaPlaceholder = (opts: {
+    buildContent: (blobUrl: string) => string
+    conversation: Conversation
+    existingClientMessageId?: string
+    file: File
+    type: number
+  }): { blobUrl: string; clientMessageId: string; } => {
+    const { conversation } = opts
+    const blobUrl = URL.createObjectURL(opts.file)
+    const clientMessageId = opts.existingClientMessageId || generateClientMessageId()
+    if (opts.existingClientMessageId) {
+      messageStore.patchMessage(conversation.type, conversation.targetId, clientMessageId, {
+        content: opts.buildContent(blobUrl),
+        status: ImMessageStatus.SENDING,
+        uploadProgress: 0,
+        _localFile: opts.file
+      })
+      return { clientMessageId, blobUrl }
+    }
+    const placeholder: Message = {
+      clientMessageId,
+      type: opts.type,
+      content: opts.buildContent(blobUrl),
+      status: ImMessageStatus.SENDING,
+      sendTime: Date.now(),
+      senderId: getCurrentUserId(),
+      targetId: conversation.targetId,
+      selfSend: true,
+      uploadProgress: 0,
+      _localFile: opts.file
+    }
+    void messageStore.insertMessage(
+      {
+        type: conversation.type,
+        targetId: conversation.targetId,
+        name: conversation.name || String(conversation.targetId),
+        avatar: conversation.avatar || ''
+      },
+      placeholder
+    ).catch(() => undefined)
+    return { clientMessageId, blobUrl }
+  }
+
+  /**
+   * 把占位消息置为 FAILED（上传失败 / 会话切走 / 禁言期到点 等场景统一收尾）
+   *
+   * 同时清掉 uploadProgress —— 失败后 MessageItem 的 isUploading 不再命中，进度遮罩 / 文件点击禁用 / 语音 loading 抑制 都同步解除；
+   * _localFile 保留，让用户点重试可以走 uploadAndSendMedia 重传
+   */
+  const markMediaFailed = (
+    conversationType: number,
+    targetId: number,
+    clientMessageId: string
+  ): void => {
+    messageStore.patchMessage(conversationType, targetId, clientMessageId, {
+      status: ImMessageStatus.FAILED,
+      uploadProgress: undefined
+    })
+  }
+
+  /**
+   * 生成 axios `onUploadProgress` 回调：用 closure 缓存上次百分比，未变化直接 return 不进 store
+   *
+   * XHR onProgress 大文件下每秒触发 10-50 次，但 Math.round 后百分比有大量重复（一秒内可能十几次同一个数字）；
+   * 在源头去重，能省掉 store 的 find + Object.assign + Vue reactivity 触发链
+   */
+  const createUploadProgressHandler = (conversation: Conversation, clientMessageId: string) => {
+    let lastPercent = -1
+    return (event: UploadProgressEvent): void => {
+      if (!event.total) {
+        return
+      }
+      const percent = Math.round((event.loaded / event.total) * 100)
+      if (percent === lastPercent) {
+        return
+      }
+      lastPercent = percent
+      messageStore.patchMessage(conversation.type, conversation.targetId, clientMessageId, {
+        uploadProgress: percent
+      })
+    }
+  }
+
+  /** 取媒体类型中文名（仅日志用）；未注册 type 退化为通用「媒体」 */
+  const getMediaKind = (type: number): string => mediaTypeHandlers[type]?.kind ?? '媒体'
+
+  /**
+   * 按 type 取 handler，缺则抛错（程序错误集中在这一处）
+   *
+   * 调用方拿到的是 `MediaTypeHandler`（非 undefined），不再需要 `!` 断言。
+   * 仅给「确定 type 在表里」的调用方用 —— image/file/voice/video 四类入口；通用 dispatcher 仍可用 `mediaTypeHandlers[type]?.` optional chain
+   */
+  const requireMediaHandler = (type: number): MediaTypeHandler => {
+    const handler = mediaTypeHandlers[type]
+    if (!handler) {
+      throw new Error(`[IM] 未注册的媒体类型 ${type}`)
+    }
+    return handler
+  }
+
+  /**
+   * 上传完成后的收口校验：会话仍是占位时锁定的那个 + 当前未被禁言；任一不满足 markMediaFailed + 返回 false
+   *
+   * image / file / voice / video 链路都要在「拿到真实 url 后、调 sendRaw 之前」过一遍这两道
+   */
+  const verifyMediaUploadStillAllowed = (
+    conversation: Conversation,
+    startKey: string,
+    type: number,
+    clientMessageId: string
+  ): boolean => {
+    const activeConversation = conversationStore.activeConversation
+    if (!activeConversation || getConversationKey(activeConversation) !== startKey) {
+      console.warn(`[IM] ${getMediaKind(type)}上传期间切换了会话，放弃发送`, { startKey })
+      markMediaFailed(conversation.type, conversation.targetId, clientMessageId)
+      return false
+    }
+    if (muteOverlay.value) {
+      console.warn(`[IM] ${getMediaKind(type)}上传期间被禁言，放弃发送`, { startKey })
+      markMediaFailed(conversation.type, conversation.targetId, clientMessageId)
+      return false
+    }
+    return true
+  }
+
+  /**
+   * 占位完成后用真实 url 替换 content，再走 sendRaw 完成发送
+   *
+   * 上传成功 → patch content → sendRaw 复用 existingClientMessageId；store 内部 revoke 旧 blob URL
+   */
+  const commitMediaPlaceholder = async (opts: {
+    clientMessageId: string
+    conversation: Conversation
+    realContent: string
+    type: number
+  }): Promise<void> => {
+    messageStore.patchMessage(
+      opts.conversation.type,
+      opts.conversation.targetId,
+      opts.clientMessageId,
+      { content: opts.realContent }
+    )
+    // 显式传 conversation 而非依赖 sendRaw 内部取 active：
+    // verifyMediaUploadStillAllowed 与 sendRaw 之间存在微秒窗口，期间用户切会话也能保证发到原会话
+    await sendRaw(opts.type, opts.realContent, {
+      existingClientMessageId: opts.clientMessageId,
+      targetId: opts.conversation.targetId,
+      conversation: opts.conversation
+    })
+  }
+
+  /**
+   * 上传媒体文件并发送消息（高层入口；image / file / voice 用，video 走低层 helper 自行组装）
+   *
+   * @returns 占位消息的 clientMessageId（调用方按需用于后续 patch / 移除；上传失败时占位仍保留为 FAILED 态）
+   */
+  const uploadAndSendMedia = async (opts: UploadAndSendMediaOptions): Promise<string> => {
+    const { conversation } = opts
+    const handler = mediaTypeHandlers[opts.type]
+    if (!handler) {
+      console.warn('[IM] uploadAndSendMedia 收到未注册的媒体类型', { type: opts.type })
+      return ''
+    }
+    // 体积上限拦截：大文件浏览器内截帧 / 解码可致 OOM；超限直接 warning，不进入占位 / 上传链路
+    if (!ensureMediaSizeWithinLimit(opts.file, opts.type, ElMessage.warning)) {
+      return ''
+    }
+    const startKey = getConversationKey(conversation)
+    const context = opts.context ?? {}
+    const buildContent = (url: string): string =>
+      serializeMessage(withQuotePayload(handler.build(opts.file, url, context), opts.quote))
+
+    // 1. 立即占位
+    const { clientMessageId } = insertMediaPlaceholder({
+      file: opts.file,
+      type: opts.type,
+      conversation,
+      buildContent,
+      existingClientMessageId: opts.existingClientMessageId
+    })
+
+    // 2. 上传：进度回调 patch uploadProgress；失败保留 _localFile 供重试
+    let url: string | undefined
+    try {
+      url = await uploadFile(
+        { file: opts.file },
+        createUploadProgressHandler(conversation, clientMessageId)
+      )
+    } catch (error) {
+      console.error(`[IM] ${handler.kind}上传失败`, error)
+    }
+    if (!url) {
+      markMediaFailed(conversation.type, conversation.targetId, clientMessageId)
+      return clientMessageId
+    }
+    if (!isOpenableUrl(url)) {
+      console.warn(`[IM] ${handler.kind}上传返回了不支持打开的 URL`, { url })
+      ElMessage.warning('上传返回的文件地址不支持打开')
+      markMediaFailed(conversation.type, conversation.targetId, clientMessageId)
+      return clientMessageId
+    }
+
+    // 3. 上传期间会话切换 / 用户登出 / 被禁言：任一情况都放弃发送，占位置 FAILED
+    if (!verifyMediaUploadStillAllowed(conversation, startKey, opts.type, clientMessageId)) {
+      return clientMessageId
+    }
+
+    // 4. patch content + sendRaw 收尾
+    await commitMediaPlaceholder({
+      type: opts.type,
+      conversation,
+      clientMessageId,
+      realContent: buildContent(url)
+    })
+    return clientMessageId
+  }
+
+  return {
+    uploadAndSendMedia,
+    insertMediaPlaceholder,
+    markMediaFailed,
+    commitMediaPlaceholder,
+    createUploadProgressHandler,
+    verifyMediaUploadStillAllowed,
+    getMediaKind,
+    requireMediaHandler
+  }
+}
diff --git a/apps/web-ele/src/views/im/home/composables/useMessageMultiSelect.ts b/apps/web-ele/src/views/im/home/composables/useMessageMultiSelect.ts
new file mode 100644
index 000000000..6b0d656d9
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/composables/useMessageMultiSelect.ts
@@ -0,0 +1,48 @@
+import type { Message } from '../types'
+
+import { computed, reactive } from 'vue'
+
+/**
+ * 消息多选模式
+ *
+ * 模块级单例 reactive state；MessagePanel 子树内多处共享：
+ * - MessageItem 渲染勾选 + 切换勾选
+ * - MessageMultiSelectBar 底栏读选中数
+ * - MessageForwardDialog 转发成功后 exit
+ * - MessagePanel watch activeConversation 切会话 exit
+ */
+const state = reactive({
+  active: false,
+  /** 已选 clientMessageId 列表，按选中顺序保序 */
+  selectedClientMessageIds: [] as string[]
+})
+
+/** 已选 clientMessageId 集合；MessageItem 大量 has 查询走它，避免 array.includes O(N²) */
+const selectedIdSet = computed(() => new Set(state.selectedClientMessageIds))
+
+/** 进入多选模式，可附带初始勾选项 */
+function enter(initialMessage?: Message) {
+  state.active = true
+  state.selectedClientMessageIds = initialMessage ? [initialMessage.clientMessageId] : []
+}
+
+/** 退出多选模式 */
+function exit() {
+  state.active = false
+  state.selectedClientMessageIds = []
+}
+
+/** 切换某条消息的选中态 */
+function toggle(message: Message) {
+  const ids = state.selectedClientMessageIds
+  const index = ids.indexOf(message.clientMessageId)
+  if (index === -1) {
+    ids.push(message.clientMessageId)
+  } else {
+    ids.splice(index, 1)
+  }
+}
+
+export function useMessageMultiSelect() {
+  return { state, selectedIdSet, enter, exit, toggle }
+}
diff --git a/apps/web-ele/src/views/im/home/composables/useMessagePuller.ts b/apps/web-ele/src/views/im/home/composables/useMessagePuller.ts
new file mode 100644
index 000000000..50af50259
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/composables/useMessagePuller.ts
@@ -0,0 +1,455 @@
+import type { Message } from '../types'
+
+import type { ImChannelMessageApi } from '#/api/im/message/channel'
+import type { ImGroupMessageApi } from '#/api/im/message/group'
+import type { ImPrivateMessageApi } from '#/api/im/message/private'
+
+import { watch } from 'vue'
+
+import { pullChannelMessages as apiPullChannelMessages } from '#/api/im/message/channel'
+import { pullGroupMessages as apiPullGroupMessages } from '#/api/im/message/group'
+import { getPrivateMaxReadMessageId as apiGetPrivateMaxReadMessageId, pullPrivateMessages as apiPullPrivateMessages } from '#/api/im/message/private'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { buildChannelConversationStub } from '../../utils/channel'
+import {
+  MESSAGE_GROUP_PULL_SIZE,
+  MESSAGE_PRIVATE_PULL_SIZE,
+  MESSAGE_PRIVATE_READ_ENABLED
+} from '../../utils/config'
+import {
+  ImContentType,
+  ImConversationType,
+  ImMessageStatus,
+  isFriendChatTip,
+  isFriendNotification
+} from '../../utils/constants'
+import { generateClientMessageId, getPrivateMessagePeerId } from '../../utils/message'
+import { runMinIdPull } from '../../utils/pull'
+import { getFriendDisplayName, getGroupDisplayName } from '../../utils/user'
+import { useConversationStore } from '../store/conversationStore'
+import { useFriendStore } from '../store/friendStore'
+import { useGroupRequestStore } from '../store/groupRequestStore'
+import { useGroupStore } from '../store/groupStore'
+import { type PulledMessage, useMessageStore } from '../store/messageStore'
+import { useImWebSocketStore } from '../store/websocketStore'
+
+/** 三类消息 pull 接口返回的原始 VO 联合类型；runMinIdPull 只需 id 推进游标，具体分发在 applyPage 内按类型 cast */
+type PulledRawMessage = ImChannelMessageApi.ChannelMessageRespVO | ImGroupMessageApi.GroupMessageRespVO | ImPrivateMessageApi.PrivateMessageRespVO
+
+/**
+ * 消息增量拉取：登录后分页拉取离线期间的新消息
+ *
+ * 设计要点：
+ * 1. 同时拉取私聊 + 群聊，使用各自的 `minId` 游标（privateMessageMaxId / groupMessageMaxId）
+ * 2. 后端一次最多返回 size 条；前端按 minId 持续翻页，直到接口返回空列表为止
+ * 3. 拉取期间 conversationStore.loading=true：
+ *    - conversationStore 跳过批量持久化，避免频繁写入卡顿
+ *    - websocketStore 把新来的 WS 普通消息丢进缓冲区，等循环结束后统一回放
+ * 4. WebSocket 重连后会再触发一次拉取，补齐断网期间错过的消息
+ */
+export const useMessagePuller = () => {
+  const conversationStore = useConversationStore()
+  const messageStore = useMessageStore()
+  const wsStore = useImWebSocketStore()
+  const friendStore = useFriendStore()
+  const groupStore = useGroupStore()
+  const groupRequestStore = useGroupRequestStore()
+  const currentUserId = getCurrentUserId()
+
+  /** 判断请求是否被主动取消 */
+  const isAbortError = (e: unknown): boolean => {
+    const error = e as { code?: string; message?: string; name?: string; }
+    return (
+      error?.name === 'CanceledError' ||
+      error?.code === 'ERR_CANCELED' ||
+      error?.message === 'canceled'
+    )
+  }
+
+  /** 私聊会话归属：自己发的算"发给 receiverId 的会话"，否则算"发送方的会话"；curry currentUserId 进闭包减少 3 处调用方的样板 */
+  const getPrivatePeerId = (message: ImPrivateMessageApi.PrivateMessageRespVO) =>
+    getPrivateMessagePeerId(message, currentUserId)
+
+  /** 服务端私聊消息 -> 本地 Message：targetId 是会话主键（对端 userId） */
+  const convertPrivateMessage = (message: ImPrivateMessageApi.PrivateMessageRespVO): Message => {
+    return {
+      id: message.id,
+      clientMessageId: message.clientMessageId || generateClientMessageId(),
+      type: message.type,
+      content: message.content,
+      status: message.status,
+      receiptStatus: message.receiptStatus,
+      sendTime: new Date(message.sendTime).getTime(),
+      senderId: message.senderId,
+      targetId: getPrivatePeerId(message),
+      selfSend: message.senderId === currentUserId
+    }
+  }
+
+  /** 服务端群聊消息 -> 本地 Message */
+  const convertGroupMessage = (message: ImGroupMessageApi.GroupMessageRespVO): Message => {
+    return {
+      id: message.id,
+      clientMessageId: message.clientMessageId || generateClientMessageId(),
+      type: message.type,
+      content: message.content,
+      status: message.status,
+      sendTime: new Date(message.sendTime).getTime(),
+      senderId: message.senderId,
+      targetId: message.groupId,
+      selfSend: message.senderId === currentUserId,
+      atUserIds: message.atUserIds || [],
+      receiverUserIds: message.receiverUserIds || [],
+      receiptStatus: message.receiptStatus,
+      readCount: message.readCount
+    }
+  }
+
+  /** 服务端频道消息 -> 本地 Message */
+  const convertChannelMessage = (message: ImChannelMessageApi.ChannelMessageRespVO): Message => {
+    return {
+      id: message.id,
+      clientMessageId: message.clientMessageId || generateClientMessageId(),
+      type: message.type,
+      content: message.content,
+      status: ImMessageStatus.NORMAL, // 频道无撤回，恒为正常
+      receiptStatus: message.receiptStatus, // 频道已读态：DONE 已读 / PENDING 未读
+      sendTime: new Date(message.sendTime).getTime(),
+      senderId: 0, // 系统下发，无发送人
+      targetId: message.channelId, // 会话归属到频道编号
+      selfSend: false,
+      materialId: message.materialId // 详情页拉富文本用
+    }
+  }
+
+  /** 频道：会话归属到 channelId；name / avatar 暂用占位，将来接入 channelStore 后再填真值 */
+  const convertChannelConversation = (message: ImChannelMessageApi.ChannelMessageRespVO) =>
+    buildChannelConversationStub(message.channelId)
+
+  /** 私聊：会话归属到对端 userId */
+  const convertPrivateConversation = (message: ImPrivateMessageApi.PrivateMessageRespVO) => {
+    const targetId = getPrivatePeerId(message)
+    const friend = friendStore.getFriend(targetId)
+    return {
+      type: ImConversationType.PRIVATE,
+      targetId,
+      name: friend ? getFriendDisplayName(friend) : String(targetId), // 会话列表 / 顶部标题展示：好友备注 > 真实昵称
+      avatar: friend?.avatar || '',
+      silent: friend?.silent
+    }
+  }
+
+  /** 群聊：会话归属到 groupId */
+  const convertGroupConversation = (message: ImGroupMessageApi.GroupMessageRespVO) => {
+    const group = groupStore.getGroup(message.groupId)
+    return {
+      type: ImConversationType.GROUP,
+      targetId: message.groupId,
+      name: group ? getGroupDisplayName(group) : String(message.groupId),
+      avatar: group?.avatar || '',
+      silent: group?.silent
+    }
+  }
+
+  /**
+   * 分类型拉取离线消息：翻页 / minId 游标推进 / 空页停由 runMinIdPull 负责，这里只做接口分支 + 逐条业务分发
+   * （撤回 / 好友通知 / 普通消息）+ 入库。
+   *
+   * 取消语义两层守卫，经 isActive 传入 runMinIdPull，任一不等即丢弃本批不入库、停止翻页，避免旧 session 响应落到新 store：
+   * 1. startEpoch：cancelPull() 递增 pullEpoch；离开 IM / 切账号时跳出
+   * 2. startUserId：每批 await 后比对当前登录 userId；防御 logout / 多 tab 下用户已切但 cancelPull 未触发
+   */
+  const pullByType = async (
+    conversationType: number,
+    startMinId: number,
+    startEpoch: number,
+    startUserId: number,
+    signal: AbortSignal
+  ) => {
+    // 私聊 / 群聊 / 频道各自一套接口；按 conversationType 分支调度。翻页机制（minId 游标 / 空页判断 / 防死翻）交给 runMinIdPull
+    const isPrivate = conversationType === ImConversationType.PRIVATE
+    const isChannel = conversationType === ImConversationType.CHANNEL
+    const size = isPrivate ? MESSAGE_PRIVATE_PULL_SIZE : MESSAGE_GROUP_PULL_SIZE
+    const isStillValid = () =>
+      !signal.aborted && pullEpoch === startEpoch && getCurrentUserId() === startUserId
+    await runMinIdPull<PulledRawMessage>({
+      initialMinId: startMinId,
+      pageSize: size,
+      isActive: isStillValid,
+      fetchPage: ({ minId, size }) => {
+        if (isPrivate) {
+          return apiPullPrivateMessages({ minId, size }, signal)
+        }
+        if (isChannel) {
+          return apiPullChannelMessages({ minId, size }, signal)
+        }
+        return apiPullGroupMessages({ minId, size }, signal)
+      },
+      applyPage: async (list, nextMinId) => {
+        const pulledMessages: PulledMessage[] = []
+        // 逐条 dispatch：原消息走批量 insert；RECALL 信号走批量 recall 把同批内已 insert 的原消息更新为撤回提示。
+        // 后端按 id 升序返回，且信号 id 一定 > 原消息 id（先更新 status 再插信号），所以原消息一定先到、recallMessage 找得到
+        for (const raw of list) {
+          if (isChannel) {
+            const message = raw as ImChannelMessageApi.ChannelMessageRespVO
+            pulledMessages.push({
+              kind: 'insert',
+              conversationInfo: convertChannelConversation(message),
+              message: convertChannelMessage(message)
+            })
+            continue
+          }
+          if (isPrivate) {
+            const message = raw as ImPrivateMessageApi.PrivateMessageRespVO
+            // 特殊：撤回消息的处理
+            if (message.type === ImContentType.RECALL) {
+              pulledMessages.push({
+                kind: 'recall',
+                conversationType: ImConversationType.PRIVATE,
+                targetId: getPrivatePeerId(message),
+                recallSignalContent: message.content
+              })
+              continue
+            }
+            // 特殊：历史好友事件只还原聊天气泡；好友主数据由好友增量补偿同步
+            // 仅 FRIEND_ADD / FRIEND_DELETE 才作为会话气泡入消息列表
+            if (isFriendNotification(message.type) && !isFriendChatTip(message.type)) {
+              continue
+            }
+            // 其它消息正常入会话消息列表
+            pulledMessages.push({
+              kind: 'insert',
+              conversationInfo: convertPrivateConversation(message),
+              message: convertPrivateMessage(message)
+            })
+          } else {
+            const message = raw as ImGroupMessageApi.GroupMessageRespVO
+            // 特殊：撤回消息的处理
+            if (message.type === ImContentType.RECALL) {
+              pulledMessages.push({
+                kind: 'recall',
+                conversationType: ImConversationType.GROUP,
+                targetId: message.groupId,
+                recallSignalContent: message.content
+              })
+              continue
+            }
+            pulledMessages.push({
+              kind: 'insert',
+              conversationInfo: convertGroupConversation(message),
+              message: convertGroupMessage(message)
+            })
+          }
+        }
+        // 入库 + 推进 messageMaxId；nextMinId 为空（本批无有效 id）时不推进游标，与旧逻辑一致
+        await messageStore.applyPulledMessageList(pulledMessages, conversationType, nextMinId)
+      }
+    })
+  }
+
+  /** 同一时刻只允许一次 pull：index.vue 的手动调用与重连 watch 触发可能并发，共用同一个 promise 即可去重 */
+  let pullPromise: null | Promise<void> = null
+  let pullAbortController: AbortController | null = null
+
+  /**
+   * 首次 pull 是否已完成。仅在置 true 后，isConnected watch 才会触发 pull。
+   * 防止 socket onopen 比 friendStore/groupStore 预拉先到达时，watcher 抢跑造成消息插入早于会话元数据可见
+   */
+  let initialPulled = false
+
+  /**
+   * pull 轮次计数；切账号 / 离开 IM 时 cancelPull() 递增，旧 pullByType 循环按 epoch 自检后跳出
+   * 避免旧 session 的接口响应在新 session 落地，造成跨账号消息泄漏
+   *
+   * 注意：普通断连（WS 短断）不取消 pull——网络抖动 / 服务端重启都属于本账号正常生命周期，
+   * 取消会导致首拉被中断后 initialPulled 永远停在 false，后续重连 watcher 不再补拉
+   */
+  let pullEpoch = 0
+
+  /** 显式取消：仅由 index.vue onUnmounted（离开 IM / 切账号 / 路由跳出）调用 */
+  const cancelPull = () => {
+    pullEpoch++
+    pullAbortController?.abort()
+    pullAbortController = null
+    // 旧 promise 仍在 finally 阶段跑，但 epoch 守卫已阻断后续副作用；这里立刻让 pullPromise = null 让新一轮可重入
+    pullPromise = null
+    // 同步丢弃 WS 缓冲帧；旧 pull 已不会 flushBuffer，若不清下次进 IM 第一次 pullOnce 会把旧 session 的帧回放进新 store
+    wsStore.discardBuffer()
+  }
+
+  /**
+   * 状态事件补偿：好友 / 好友申请走增量；群列表和群申请红点走快照刷新
+   *
+   * 首登主数据由 index.vue 驱动，重连时各 store 已就位，多路 allSettled 并发互不影响，单路失败仅记日志。
+   * 群成员不做全局增量同步，重连只标记本地群成员 cache 过期，进入群会话或成员列表时再按 groupId 刷新。
+   */
+  const pullStateEvents = async (): Promise<void> => {
+    groupStore.markAllGroupMembersExpired()
+    const results = await Promise.allSettled([
+      friendStore.pullFriends(),
+      friendStore.pullFriendRequests(),
+      conversationStore.pullConversationReads(),
+      groupStore.fetchGroupList(true),
+      groupRequestStore.pullGroupRequests(),
+      groupRequestStore.fetchUnhandledGroupRequestList()
+    ])
+    for (const result of results) {
+      if (result.status === 'rejected') {
+        console.warn('[IM] 状态事件增量补偿失败', result.reason)
+      }
+    }
+  }
+
+  /** 执行一次全量增量拉取（重入安全：进行中再次调用复用同一个 promise） */
+  const pullOnce = (): Promise<void> => {
+    if (!currentUserId) {
+      return Promise.resolve()
+    }
+    if (pullPromise) {
+      return pullPromise
+    }
+    const startEpoch = pullEpoch
+    // 启动时的用户快照；pullByType 每批 await 后比对当前登录用户，账号变了立刻丢弃
+    const startUserId = currentUserId
+    const abortController = new AbortController()
+    pullAbortController = abortController
+    // 本轮 pull 仍属于当前 session：epoch 未漂 + 用户未切；任何动新 store 状态的副作用都要先过这道关
+    const isCurrentPull = () =>
+      !abortController.signal.aborted &&
+      pullEpoch === startEpoch &&
+      getCurrentUserId() === startUserId
+    pullPromise = (async () => {
+      try {
+        // 旧 puller 在 cancelPull 未触发的异常路径上再进来时，先于任何副作用退出，避免污染新 session 的 loading
+        if (!isCurrentPull()) {
+          return
+        }
+        conversationStore.loading = true
+        let messagePullSucceeded = false
+        try {
+          // 并发拉取私聊 + 群聊 + 频道消息，降低初始加载耗时
+          await Promise.all([
+            pullByType(
+              ImConversationType.PRIVATE,
+              messageStore.privateMessageMaxId,
+              startEpoch,
+              startUserId,
+              abortController.signal
+            ),
+            pullByType(
+              ImConversationType.GROUP,
+              messageStore.groupMessageMaxId,
+              startEpoch,
+              startUserId,
+              abortController.signal
+            ),
+            pullByType(
+              ImConversationType.CHANNEL,
+              messageStore.channelMessageMaxId,
+              startEpoch,
+              startUserId,
+              abortController.signal
+            )
+          ])
+          messagePullSucceeded = true
+        } catch (error) {
+          if (isAbortError(error)) {
+            return
+          }
+          console.error('[IM] 拉取离线消息失败:', error)
+        } finally {
+          // 仍属本轮才复位 loading；旧轮被 cancel / 切账号时由新一轮自管，避免覆盖新 session 的 true
+          if (isCurrentPull()) {
+            conversationStore.loading = false
+          }
+        }
+
+        // 取消 / 切账号后跳过 flushBuffer / 排序 / 已读位置补齐
+        if (!isCurrentPull()) {
+          return
+        }
+        if (!messagePullSucceeded) {
+          return
+        }
+
+        // 回放 WebSocket 在 loading 期间收到的缓冲消息
+        const buffered = wsStore.flushBuffer()
+        const replayPersistPromises: Promise<void>[] = []
+        for (const item of buffered) {
+          if (item.conversationType === ImConversationType.PRIVATE) {
+            replayPersistPromises.push(wsStore.handlePrivateMessage(item.payload))
+          } else if (item.conversationType === ImConversationType.CHANNEL) {
+            replayPersistPromises.push(wsStore.handleChannelMessage(item.payload))
+          } else {
+            replayPersistPromises.push(wsStore.handleGroupMessage(item.payload))
+          }
+        }
+        await Promise.all(replayPersistPromises)
+
+        // pull + replay 都完成后再排序，避免回放消息打乱顺序
+        conversationStore.sortConversationList()
+
+        // 重连 / 冷启动后补齐当前激活私聊会话的「对方已读位置」
+        // 离线期间错过的 RECEIPT 推送会被这里补回；其他私聊会话等用户点开时由 index.vue 的 watch 触发
+        // 私聊已读关闭时跳过，避免打到已禁用接口触发错误日志
+        const active = conversationStore.activeConversation
+        if (MESSAGE_PRIVATE_READ_ENABLED && active && active.type === ImConversationType.PRIVATE) {
+          try {
+            const maxReadId = await apiGetPrivateMaxReadMessageId(
+              active.targetId,
+              abortController.signal
+            )
+            if (!isCurrentPull()) {
+              return
+            }
+            if (maxReadId) {
+              messageStore.applyMessageReadReceipt({
+                conversationType: ImConversationType.PRIVATE,
+                targetId: active.targetId,
+                privateReadMaxId: maxReadId
+              })
+            }
+          } catch (error) {
+            if (isAbortError(error)) {
+              return
+            }
+            console.warn('[IM] 拉取对方已读位置失败', error)
+          }
+        }
+      } finally {
+        // 仍属本轮：正常完成首拉；epoch 等但 userId 切了：清 pullPromise 防卡死、不标首拉；epoch 漂：cancelPull 已清，no-op
+        if (isCurrentPull()) {
+          pullPromise = null
+          initialPulled = true
+          if (pullAbortController === abortController) {
+            pullAbortController = null
+          }
+        } else if (pullEpoch === startEpoch) {
+          pullPromise = null
+          if (pullAbortController === abortController) {
+            pullAbortController = null
+          }
+        }
+      }
+    })()
+    return pullPromise
+  }
+
+  /**
+   * 断网期间 WS 收不到推送：重连后既要按 minId 补齐消息，也要按 update_time + id 补齐好友 / 群 / 群申请状态。
+   * 首次连接由 index.vue 显式驱动（pullOnce 拉消息 + 各 store 首拉），这里仅覆盖之后的重连。
+   * 重连时 store 已就位，pullStateEvents 与 pullOnce 并发即可，无需「先就位再拉消息」的首登顺序约束。
+   */
+  watch(
+    () => wsStore.isConnected,
+    (isConnected) => {
+      if (isConnected && initialPulled) {
+        void pullOnce()
+        void pullStateEvents()
+      }
+    }
+  )
+
+  return { pullOnce, cancelPull, convertPrivateMessage, convertGroupMessage }
+}
diff --git a/apps/web-ele/src/views/im/home/composables/useMessageSender.ts b/apps/web-ele/src/views/im/home/composables/useMessageSender.ts
new file mode 100644
index 000000000..e7899aae1
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/composables/useMessageSender.ts
@@ -0,0 +1,311 @@
+import type { Conversation, Message } from '../types'
+
+import { readChannelMessages as apiReadChannelMessages } from '#/api/im/message/channel'
+import {
+  readGroupMessages as apiReadGroupMessages,
+  recallGroupMessage as apiRecallGroupMessage,
+  sendGroupMessage as apiSendGroupMessage
+} from '#/api/im/message/group'
+import {
+  getPrivateMaxReadMessageId as apiGetPrivateMaxReadMessageId,
+  readPrivateMessages as apiReadPrivateMessages,
+  recallPrivateMessage as apiRecallPrivateMessage,
+  sendPrivateMessage as apiSendPrivateMessage
+} from '#/api/im/message/private'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { MESSAGE_GROUP_READ_ENABLED, MESSAGE_PRIVATE_READ_ENABLED } from '../../utils/config'
+import { ImContentType, ImConversationType, ImMessageStatus } from '../../utils/constants'
+import { getClientConversationId } from '../../utils/db'
+import {
+  generateClientMessageId,
+  type QuoteMessage,
+  serializeMessage,
+  type TextMessage,
+  withQuotePayload
+} from '../../utils/message'
+import { useConversationStore } from '../store/conversationStore'
+import { useMessageStore } from '../store/messageStore'
+
+/** 非文本消息的扩展选项（通用） */
+interface SendExtOptions {
+  atUserIds?: number[] // 群聊 @ 的用户编号列表
+  receipt?: boolean // 是否需要群回执（默认 false）
+  targetId?: number // 覆盖默认的 targetId
+  /**
+   * 显式指定目标会话（转发 / 名片推荐场景）
+   *
+   * 不传时默认取 conversationStore.activeConversation；传入时按本值发送 + 乐观更新到对应会话，
+   * 不要求该会话当前是激活状态（适合发给「非当前会话」的多个目标）
+   */
+  conversation?: Conversation
+  /** 被引用消息（可选）：写进 content.quote 用于乐观渲染，服务端按 quote.messageId 反查重算覆盖 */
+  quote?: QuoteMessage
+  /**
+   * 复用已存在的本地占位消息 clientMessageId（媒体上传场景）
+   *
+   * 媒体上传链路在请求服务端前已经 insertMessage 了占位（带 blob URL + 进度条），
+   * 这里跳过 buildLocalMessage / insertMessage，直接拿这个 id 走 ackMessage 收尾，避免重复插入两条
+   */
+  existingClientMessageId?: string
+}
+
+/**
+ * 消息发送 / 撤回 / 已读 组合式逻辑
+ *
+ * 设计要点：
+ * 1. 私聊 / 群聊接口签名对称，按 conversation.type 分支调度，差异在分支内部消化
+ * 2. 发送走「乐观更新」：先 insertMessage 写入 SENDING 占位，请求成功 ackMessage 更新为 NORMAL，失败更新为 FAILED
+ * 3. 撤回不做乐观更新：服务端通过 WebSocket RECALL 事件回传，由 websocketStore 统一更新状态，避免网络失败后不可回退
+ * 4. 已读上报：本端立刻清未读数；服务端回包成功后再做持久化
+ */
+export const useMessageSender = () => {
+  const conversationStore = useConversationStore()
+  const messageStore = useMessageStore()
+
+  /** 构造本地乐观消息对象 */
+  const buildLocalMessage = (opts: {
+    atUserIds?: number[]
+    clientMessageId: string
+    content: string
+    targetId: number
+    type: number
+  }): Message => {
+    return {
+      clientMessageId: opts.clientMessageId,
+      type: opts.type,
+      content: opts.content,
+      status: ImMessageStatus.SENDING,
+      sendTime: Date.now(),
+      senderId: getCurrentUserId(),
+      targetId: opts.targetId,
+      selfSend: true,
+      atUserIds: opts.atUserIds
+    }
+  }
+
+  /**
+   * 发送任意类型的消息（底层实现）
+   * 1. 文本、图片、文件、语音等都走这里
+   * 2. type / content 由调用方构造
+   * 3. 返回值：成功 true / 失败 false（失败时本地占位已标 FAILED）；参数缺失等无法发送的场景也返 false
+   *    转发 / 名片推荐等场景按返回值决定是否继续后续动作（如有留言时仅在名片成功后再发留言）
+   */
+  const sendRaw = async (
+    type: number,
+    content: string,
+    options?: SendExtOptions
+  ): Promise<boolean> => {
+    // 1. 参数校验：优先用显式传入的 conversation（转发场景），否则取激活会话
+    const conversation = options?.conversation ?? conversationStore.activeConversation
+    if (!conversation) {
+      return false
+    }
+    const realTarget = options?.targetId || conversation.targetId
+    if (!realTarget) {
+      return false
+    }
+
+    // 2. 准备 clientMessageId：媒体上传链路在 step 1 已经 insertMessage 占位，这里直接复用 id；其余场景走默认乐观插入
+    let clientMessageId: string
+    if (options?.existingClientMessageId) {
+      clientMessageId = options.existingClientMessageId
+      // 占位若已被删除（上传期间用户右键删除 / 撤回 / removeMessage 等）则放弃发送，
+      // 否则 sendRaw 仍会把消息推到服务端，导致"本地无气泡 / 对方却收到一条"
+      const stillExists = messageStore
+        .getMessageList(conversation.type, realTarget)
+        .some((message) => message.clientMessageId === clientMessageId && !message._ackMerging)
+      if (!stillExists) {
+        return false
+      }
+    } else {
+      clientMessageId = generateClientMessageId()
+      const message = buildLocalMessage({
+        clientMessageId,
+        content,
+        targetId: realTarget,
+        type,
+        atUserIds: options?.atUserIds
+      })
+      const conversationInfo = {
+        type: conversation.type,
+        targetId: realTarget,
+        name: conversation.name || String(realTarget),
+        avatar: conversation.avatar || ''
+      }
+      void messageStore.insertMessage(conversationInfo, message).catch(() => undefined)
+    }
+
+    // 3. 发送请求：按会话类型分发到不同接口；成功后 ackMessage 更新为 NORMAL，失败更新为 FAILED
+    try {
+      if (conversation.type === ImConversationType.PRIVATE) {
+        const data = await apiSendPrivateMessage({
+          clientMessageId,
+          receiverId: realTarget,
+          type,
+          content
+        })
+        void messageStore
+          .ackMessage(conversation.type, realTarget, clientMessageId, {
+            id: data.id,
+            sendTime: new Date(data.sendTime).getTime(),
+            status: data.status,
+            receiptStatus: data.receiptStatus,
+            content: data.content
+          })
+          .catch(() => undefined)
+      } else if (conversation.type === ImConversationType.GROUP) {
+        const data = await apiSendGroupMessage({
+          clientMessageId,
+          groupId: realTarget,
+          type,
+          content,
+          atUserIds: options?.atUserIds,
+          receipt: options?.receipt
+        })
+        void messageStore
+          .ackMessage(conversation.type, realTarget, clientMessageId, {
+            id: data.id,
+            sendTime: new Date(data.sendTime).getTime(),
+            status: data.status,
+            receiptStatus: data.receiptStatus,
+            readCount: data.readCount,
+            content: data.content
+          })
+          .catch(() => undefined)
+      }
+      return true
+    } catch (error) {
+      console.error('[IM] 消息发送失败', { type, realTarget, clientMessageId }, error)
+      void messageStore
+        .ackMessage(conversation.type, realTarget, clientMessageId, {
+          status: ImMessageStatus.FAILED
+        })
+        .catch(() => undefined)
+      return false
+    }
+  }
+
+  /**
+   * 发送文本消息（最常用的快捷入口）：message-input.vue 文本回车走这里
+   * 返回值：成功 true / 失败 false / 空文本 false（与 sendRaw 对齐，转发场景按返回值判断）
+   */
+  const send = async (text: string, options?: SendExtOptions): Promise<boolean> => {
+    if (!text.trim()) {
+      return false
+    }
+    const payload = withQuotePayload<TextMessage>({ content: text }, options?.quote)
+    return sendRaw(ImContentType.TEXT, serializeMessage(payload), options)
+  }
+
+  /**
+   * 撤回某条消息
+   * 1. 服务端会通过 WebSocket RECALL 事件回传，本端 UI 由 websocketStore 统一更新
+   * 2. 此处不做乐观撤回，避免网络失败后状态不可回退
+   */
+  const recall = async (message: Message) => {
+    // 参数校验：本地占位消息不能撤回
+    if (!message.id) {
+      return
+    }
+    const conversation = conversationStore.activeConversation
+    if (!conversation) {
+      return
+    }
+    // 私聊 / 群聊接口签名一致，按会话类型分发
+    const isPrivate = conversation.type === ImConversationType.PRIVATE
+    try {
+      await (isPrivate ? apiRecallPrivateMessage(message.id) : apiRecallGroupMessage(message.id))
+    } catch (error) {
+      console.error('[IM] 撤回失败', { messageId: message.id, type: conversation.type }, error)
+    }
+  }
+
+  /**
+   * 触发当前会话的已读上报（切会话 / 进入页面时调用）
+   * 1. 本端立刻清未读数；服务端回包成功后再做持久化
+   * 2. 已读位置取已加载消息和会话末条消息的最大服务端 id
+   */
+  const readActive = async () => {
+    const conversation = conversationStore.activeConversation
+    if (!conversation) {
+      return
+    }
+    let loadedMaxMessageId = 0
+    for (const message of messageStore.getMessages(
+      getClientConversationId(conversation.type, conversation.targetId)
+    )) {
+      if (message.id && message.id > loadedMaxMessageId) {
+        loadedMaxMessageId = message.id
+      }
+    }
+    const maxMessageId = Math.max(loadedMaxMessageId, conversation.lastMessageId || 0)
+    // 本地标记已读：未读数清零（UI 立刻响应）
+    conversationStore.markConversationRead(conversation.type, conversation.targetId, maxMessageId)
+    if (!maxMessageId) {
+      return
+    }
+    // 接口调用：按会话类型分发，并按对应已读开关控制；失败仅记录日志，不回退本地已读状态
+    const isPrivate = conversation.type === ImConversationType.PRIVATE
+    const isGroup = conversation.type === ImConversationType.GROUP
+    const isChannel = conversation.type === ImConversationType.CHANNEL
+    if (!isPrivate && !isGroup && !isChannel) {
+      return
+    }
+    if (isPrivate && !MESSAGE_PRIVATE_READ_ENABLED) {
+      return
+    }
+    if (isGroup && !MESSAGE_GROUP_READ_ENABLED) {
+      return
+    }
+    try {
+      if (isPrivate) {
+        await apiReadPrivateMessages(conversation.targetId, maxMessageId)
+      } else if (isGroup) {
+        await apiReadGroupMessages(conversation.targetId, maxMessageId)
+      } else {
+        await apiReadChannelMessages(conversation.targetId, maxMessageId)
+      }
+    } catch (error) {
+      console.error(
+        '[IM] 标记已读失败',
+        { type: conversation.type, targetId: conversation.targetId, maxMessageId },
+        error
+      )
+    }
+  }
+
+  /**
+   * 拉取「对方已读到我哪条消息」并补齐本地状态
+   *
+   * 1. 弥补离线 / 多端期间错过的 RECEIPT 推送：进入私聊会话或断线重连后调一次，
+   *    把对方 maxReadId 同步到本地消息 status，避免对方明明读了、本端却仍显示未读
+   * 2. 仅私聊使用：群聊已读位置在每条消息的 readCount / receiptStatus 字段，离线拉取自带回
+   */
+  const syncPrivateReadStatus = async (peerId: number) => {
+    if (!peerId) {
+      return
+    }
+    // 私聊已读关闭：跳过对方已读位置同步，避免无谓接口调用
+    if (!MESSAGE_PRIVATE_READ_ENABLED) {
+      return
+    }
+    try {
+      // 拉取对方已读到的最大消息 id
+      const maxReadId = await apiGetPrivateMaxReadMessageId(peerId)
+      if (!maxReadId) {
+        return
+      }
+      // applyMessageReadReceipt 内部把 ≤ maxReadId 的本端消息回执更新为 DONE
+      messageStore.applyMessageReadReceipt({
+        conversationType: ImConversationType.PRIVATE,
+        targetId: peerId,
+        privateReadMaxId: maxReadId
+      })
+    } catch (error) {
+      console.warn('[IM] 拉取对方已读位置失败', { peerId }, error)
+    }
+  }
+
+  return { send, sendRaw, recall, readActive, syncPrivateReadStatus }
+}
diff --git a/apps/web-ele/src/views/im/home/composables/useMuteOverlay.ts b/apps/web-ele/src/views/im/home/composables/useMuteOverlay.ts
new file mode 100644
index 000000000..b0ed76452
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/composables/useMuteOverlay.ts
@@ -0,0 +1,102 @@
+import { computed, type ComputedRef, onScopeDispose, ref } from 'vue'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { ImConversationType, ImGroupMemberRole } from '../../utils/constants'
+import { isGroupQuit } from '../../utils/user'
+import { useConversationStore } from '../store/conversationStore'
+import { useGroupStore } from '../store/groupStore'
+
+export type MuteOverlayInfo = { icon: string; text: string; }
+
+/**
+ * 模块级共享 now tick + 订阅计数：
+ * MessageItem v-for 时每条消息都会 useMuteOverlay()，单实例自起 timer 会变成几百个 30s 定时器；
+ * 改成模块级共享后所有订阅者共用一份 setInterval，订阅数清零时也清掉 timer，避免内存与时钟漂移
+ */
+const sharedNow = ref(Date.now())
+let sharedTickTimer: null | number = null
+let subscriberCount = 0
+
+function subscribeNowTick(): void {
+  subscriberCount++
+  if (!sharedTickTimer) {
+    sharedTickTimer = window.setInterval(() => {
+      sharedNow.value = Date.now()
+    }, 30_000)
+  }
+}
+
+function unsubscribeNowTick(): void {
+  subscriberCount--
+  if (subscriberCount <= 0) {
+    subscriberCount = 0
+    if (sharedTickTimer) {
+      window.clearInterval(sharedTickTimer)
+      sharedTickTimer = null
+    }
+  }
+}
+
+/**
+ * 当前激活会话的禁言 / 封禁状态；非群聊或无禁言时返回 null
+ *
+ * 优先级：封禁 > 全群禁言（群主 / 管理员豁免）> 成员禁言
+ *
+ * MessageInput 顶部 overlay / handleResend 重试 / uploadAndSendMedia 上传完前都共用一份，
+ * 避免「输入框拦了但重试绕过」「上传期间被禁言但 sendRaw 仍发出去」之类的不一致
+ */
+export function useMuteOverlay(): ComputedRef<MuteOverlayInfo | null> {
+  const conversationStore = useConversationStore()
+  const groupStore = useGroupStore()
+
+  // 订阅模块级 tick；scope 销毁时反订阅，最后一个订阅者退场后 timer 也跟着清
+  subscribeNowTick()
+  onScopeDispose(unsubscribeNowTick)
+
+  return computed(() => {
+    const conversation = conversationStore.activeConversation
+    if (!conversation || conversation.type !== ImConversationType.GROUP) {
+      return null
+    }
+    const group = groupStore.getGroup(conversation.targetId)
+    if (!group) {
+      return null
+    }
+    // 历史退群群：已退群只能查看历史，禁止发送（文本 / 图片 / 文件 / 语音 / 重试共用这一层拦截）
+    if (isGroupQuit(group)) {
+      return { text: '你已退出群聊，仅可查看历史消息', icon: 'ant-design:logout-outlined' }
+    }
+    const myId = getCurrentUserId()
+    // 群封禁：管理后台操作，所有人不可发送
+    if (group.banned) {
+      return { text: '该群已被管理员封禁，无法发送消息', icon: 'ant-design:stop-outlined' }
+    }
+    // 全群禁言：群主走 ownerUserId 比较直接豁免；其它人需要成员列表加载完才能区分管理员 vs 普通成员
+    // - 加载完 + 我是管理员 → 豁免
+    // - 加载完 + 我不是管理员（含已退群）→ 拦
+    // - 加载未完 → 不显示 overlay，后端兜底拒绝普通成员；避免误拦管理员
+    if (group.mutedAll && myId !== group.ownerUserId && group.membersLoaded) {
+      const myMember = group.members?.find((m) => m.userId === myId)
+      if (myMember?.role !== ImGroupMemberRole.ADMIN) {
+        return { text: '全群禁言中，暂时无法发送消息', icon: 'ant-design:audio-muted-outlined' }
+      }
+    }
+    // 成员禁言：muteEndTime 在未来才算；用响应式 sharedNow 比对，到期后下一个 tick 就让 overlay 消失
+    const myMember = group.members?.find((m) => m.userId === myId)
+    if (myMember?.muteEndTime) {
+      const endTime = new Date(myMember.muteEndTime)
+      if (endTime.getTime() > sharedNow.value) {
+        const pad = (n: number) => n.toString().padStart(2, '0')
+        const timeStr =
+          `${pad(endTime.getMonth() + 1)}-${pad(endTime.getDate())} ` +
+          `${pad(endTime.getHours())}:${pad(endTime.getMinutes())}`
+        return {
+          text: `您已被禁言，解除时间：${timeStr}`,
+          icon: 'ant-design:audio-muted-outlined'
+        }
+      }
+    }
+    return null
+  })
+}
diff --git a/apps/web-ele/src/views/im/home/composables/useSelectedItems.ts b/apps/web-ele/src/views/im/home/composables/useSelectedItems.ts
new file mode 100644
index 000000000..f8364b333
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/composables/useSelectedItems.ts
@@ -0,0 +1,75 @@
+import { computed, type ComputedRef, type Ref } from 'vue'
+
+/**
+ * 三态选择面板的「已选数 + 已选项列表」派生
+ *
+ * - 三态优先级（与 dialog-picker-contract 对齐）：hide > locked > disabled
+ *   - hide：永远剔除，不计数 / 不进已选列表
+ *   - locked：默认勾选 + 计数 + 优先排在前面；即使被外部塞进 disabledIds 也胜出
+ *   - disabled：仅过滤 selectedIds，不计数 / 不进已选列表
+ * - 顺序：lockedIds 在前，selectedIds 紧随；按数组顺序即为「点击顺序」
+ *
+ * FriendPickerPanel / GroupMemberPickerPanel 共用，避免两侧 25 行同构 computed 各写一份；
+ * Panel 内部的 isLocked / isDisabled / isSelected 等模板判定函数仍各自维护，本 composable 只承担派生量
+ */
+export function useSelectedItems<T>(
+  selectedIds: () => readonly number[],
+  lockedIds: () => readonly number[],
+  disabledIds: () => readonly number[],
+  hideIds: () => readonly number[],
+  byId: ComputedRef<Map<number, T>> | Ref<Map<number, T>>
+): {
+  selectedCount: ComputedRef<number>
+  selectedItems: ComputedRef<T[]>
+} {
+  const hideSet = computed(() => new Set(hideIds()))
+  const disabledSet = computed(() => new Set(disabledIds()))
+
+  const selectedCount = computed(() => {
+    const merged = new Set<number>()
+    for (const id of selectedIds()) {
+      if (hideSet.value.has(id) || disabledSet.value.has(id)) {
+        continue
+      }
+      merged.add(id)
+    }
+    // locked 仅被 hide 过滤；契约里 locked 胜过 disabled，确保锁定项始终计入
+    for (const id of lockedIds()) {
+      if (hideSet.value.has(id)) {
+        continue
+      }
+      merged.add(id)
+    }
+    return merged.size
+  })
+
+  const selectedItems = computed(() => {
+    const seen = new Set<number>()
+    const result: T[] = []
+    // locked 在前；仅被 hide 过滤
+    for (const id of lockedIds()) {
+      if (seen.has(id) || hideSet.value.has(id)) {
+        continue
+      }
+      const item = byId.value.get(id)
+      if (item) {
+        seen.add(id)
+        result.push(item)
+      }
+    }
+    // selectedIds 紧随；额外过滤 disabled
+    for (const id of selectedIds()) {
+      if (seen.has(id) || disabledSet.value.has(id) || hideSet.value.has(id)) {
+        continue
+      }
+      const item = byId.value.get(id)
+      if (item) {
+        seen.add(id)
+        result.push(item)
+      }
+    }
+    return result
+  })
+
+  return { selectedCount, selectedItems }
+}
diff --git a/apps/web-ele/src/views/im/home/composables/useVoicePlayer.ts b/apps/web-ele/src/views/im/home/composables/useVoicePlayer.ts
new file mode 100644
index 000000000..b396449e2
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/composables/useVoicePlayer.ts
@@ -0,0 +1,82 @@
+import { ref } from 'vue'
+
+/**
+ * 语音播放全局互斥
+ *
+ * 模块级单例：同一时刻最多只有一条语音在播；新点的语音停掉旧的
+ * 三处入口共享同一播放态：
+ * - MessageBubble：气泡点击 toggle 当前条
+ * - MessagePanel：切会话 stop()
+ * - MessageHistory / MessageMergeDetailDialog：关闭时 stop()
+ *
+ * key 由 MessageBubble 在 setup 里 Symbol() 生成实例级唯一身份；不同来源（主面板 / 历史抽屉 /
+ * 合并详情）的同一条语音 url 在不同气泡里也是不同 key，避免一处卸载误停另一处仍可见的播放。
+ */
+export type VoiceKey = symbol
+
+interface VoiceTask {
+  key: VoiceKey
+  url: string
+  audio: HTMLAudioElement
+}
+
+const currentTask = ref<null | VoiceTask>(null)
+
+/**
+ * 显式停止
+ *
+ * - 不传 key：强停（切会话 / 关弹窗用）
+ * - 传 key：仅当当前 task 是该 key 时才停（气泡卸载兜底用，避免误停别人）
+ */
+function stop(key?: VoiceKey) {
+  const task = currentTask.value
+  if (!task) {
+    return
+  }
+  if (key !== undefined && task.key !== key) {
+    return
+  }
+  task.audio.pause()
+  // removeAttribute('src') + load() 是 W3C 推荐的释放姿势：不会触发空 src 加载导致的 error 事件，
+  // 也能让浏览器立即释放底层 decoder buffer，比 audio.src = '' 更干净
+  task.audio.removeAttribute('src')
+  task.audio.load()
+  currentTask.value = null
+}
+
+/**
+ * 切换播放
+ *
+ * - 同 key 再点：停掉
+ * - 切到新 key：停旧起新
+ */
+function play(key: VoiceKey, url: string) {
+  if (!url) {
+    return
+  }
+  if (currentTask.value?.key === key) {
+    stop(key)
+    return
+  }
+  stop()
+  const audio = new Audio(url)
+  const task: VoiceTask = { key, url, audio }
+  /** 播放结束 / 异常清栈；只清当前任务，避免被后续新任务的回调误清 */
+  const finalize = () => {
+    if (currentTask.value === task) {
+      currentTask.value = null
+    }
+  }
+  audio.addEventListener('ended', finalize, { once: true })
+  audio.addEventListener('error', finalize, { once: true })
+  currentTask.value = task
+  audio.play().catch(finalize)
+}
+
+export function useVoicePlayer() {
+  /** 指定 key 是否正在播放 */
+  function isPlaying(key: VoiceKey): boolean {
+    return currentTask.value?.key === key
+  }
+  return { isPlaying, play, stop }
+}
diff --git a/apps/web-ele/src/views/im/home/index.vue b/apps/web-ele/src/views/im/home/index.vue
new file mode 100644
index 000000000..cf867010e
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/index.vue
@@ -0,0 +1,290 @@
+<script lang="ts" setup>
+import type { Conversation } from './types'
+
+import { nextTick, onMounted, onUnmounted, ref, watch } from 'vue'
+import { useRoute } from 'vue-router'
+
+import { preferences } from '@vben/preferences'
+
+import { ImConversationType } from '../utils/constants'
+import { initDb, stopRequests, StorageKeys } from '../utils/db'
+import { ContextMenu, ToolBar } from './components'
+import { GroupInfoCard } from './components/group'
+import { RtcCallContainer } from './components/rtc'
+import { UserInfoCard } from './components/user'
+import { useMessagePuller } from './composables/useMessagePuller'
+import { useMessageSender } from './composables/useMessageSender'
+import { useVoicePlayer } from './composables/useVoicePlayer'
+import { useChannelStore } from './store/channelStore'
+import { useConversationStore } from './store/conversationStore'
+import { useFaceStore } from './store/faceStore'
+import { useFriendStore } from './store/friendStore'
+import { useGroupRequestStore } from './store/groupRequestStore'
+import { useGroupStore } from './store/groupStore'
+import { useMessageStore } from './store/messageStore'
+import { useImWebSocketStore } from './store/websocketStore'
+
+defineOptions({ name: 'ImIndex' })
+
+const route = useRoute()
+const conversationStore = useConversationStore()
+const messageStore = useMessageStore()
+const webSocketStore = useImWebSocketStore()
+const friendStore = useFriendStore()
+const groupStore = useGroupStore()
+const groupRequestStore = useGroupRequestStore()
+const faceStore = useFaceStore()
+const channelStore = useChannelStore()
+const { pullOnce, cancelPull } = useMessagePuller()
+const { readActive, syncPrivateReadStatus } = useMessageSender()
+const voicePlayer = useVoicePlayer()
+const childRouteReady = ref(false) // 子路由是否可挂载
+
+/** 初始化：先吃本地缓存让首屏立即渲染，再远端刷新最新数据，最后建实时通信拉离线消息 */
+onMounted(async () => {
+  // 0.1 系统表情包后台预拉：独立链路与首屏 IDB / 远端拉取并发，消除表情面板首次展开白屏；失败仅记日志，不阻塞主流程
+  void faceStore.ensureFacePackList().catch((error) => console.warn('[IM] 后台预拉表情包失败', error))
+  // 1.1 整段 loading=true 阻断会话列表抖动写盘 + WebSocket 普通消息进缓冲，避免 connect 到 pullOnce 之间收到的实时消息推进 maxId 导致 pull 跳过断线积压消息
+  conversationStore.loading = true
+  try {
+    // 1.2 打开当前用户 IM DB
+    await initDb()
+    // 1.3 多个 store 并发从 IDB 读取本地缓存
+    const cacheResults = await Promise.all([
+      conversationStore.loadConversationList(),
+      messageStore.loadMessageCursorList(),
+      friendStore.loadFriendData(),
+      groupStore.loadGroupList(),
+      channelStore.loadChannelList(),
+      groupRequestStore.loadGroupRequestList()
+    ])
+    const hasFriendRows = cacheResults[2]
+    const hasGroupRows = cacheResults[3]
+    const hasChannelRows = cacheResults[4]
+    groupStore.markAllGroupMembersExpired()
+    childRouteReady.value = true
+    // 1.4 我管理的群下未处理加群申请红点：首登用 unhandled-list（服务端直接过滤未处理，语义精准、启动轻）；
+    //     pullGroupRequests 只在重连 / 后续补偿时跑（见 useMessagePuller.pullStateEvents），不进首登主链路
+    void groupRequestStore
+      .fetchUnhandledGroupRequestList()
+      .catch((error) => console.warn('[IM] 拉取未处理加群申请失败', error))
+
+    // 2. 好友主数据恢复走 pull；群列表用快照刷新，覆盖离线期间自己的入群 / 退群状态变化
+    // 2.1 有缓存：异步背景增量刷新，失败仅记日志（IDB 数据已经够撑首屏，pullOnce 也能正常入库）
+    // 2.2 无缓存（首登 / 切账号回切）：必须 await + 失败抛出中断本轮 onMounted，
+    //     否则 pullOnce 会用 senderId 数字给会话起名落到 IDB 后续基本无法自愈；无缓存分支并发 Promise.all 省一个 RTT
+    const requiredFetches: Promise<unknown>[] = []
+    if (hasFriendRows) {
+      void friendStore.pullFriends().catch((error) => console.warn('[IM] 后台增量拉好友失败', error))
+    } else {
+      requiredFetches.push(friendStore.pullFriends())
+    }
+    if (hasGroupRows) {
+      void groupStore.fetchGroupList(true).catch((error) => console.warn('[IM] 后台刷新群列表失败', error))
+    } else {
+      requiredFetches.push(groupStore.fetchGroupList(true))
+    }
+    // 2.3 频道无增量 pull 接口，继续走 list
+    if (hasChannelRows) {
+      void channelStore.fetchChannelList().catch((error) => console.warn('[IM] 后台刷频道列表失败', error))
+    } else {
+      requiredFetches.push(channelStore.fetchChannelList())
+    }
+    // 2.4 执行加载
+    if (requiredFetches.length > 0) {
+      await Promise.all(requiredFetches)
+    }
+
+    // 2.5 好友申请增量补偿：首登也要跑，离线期间好友申请变更不会影响好友主表
+    void friendStore
+      .pullFriendRequests()
+      .catch((error) => console.warn('[IM] 后台增量拉好友申请失败', error))
+
+    // 3. 会话读位置先补偿，消息入库时可直接过滤已读历史消息
+    await conversationStore
+      .pullConversationReads()
+      .catch((error) => console.warn('[IM] 拉取会话读位置失败', error))
+
+    // 4. 实时通信：建 WebSocket 长连接 + 拉离线消息（pullOnce finally 把 loading 归位）
+    webSocketStore.connect()
+    await pullOnce()
+
+    // 5. 默认选中第一个会话；若置顶分组处于折叠态，需跳过被折叠隐藏的置顶项，避免自动展开折叠
+    const sorted = conversationStore.getSortedConversationList
+    const firstVisible = pickFirstVisibleConversation(sorted)
+    if (firstVisible && !conversationStore.activeConversation) {
+      conversationStore.setActiveConversation(firstVisible)
+    }
+  } catch (error) {
+    // 1. 首拉失败：手动复位 loading（pullOnce 没跑到，它的 finally 兜不到这里），否则后续会话列表写入全被早 return 阻断
+    // 2. WebSocket 不在这里 disconnect——路由离开会走 onUnmounted 自然清理，用户也可以刷新重试
+    conversationStore.loading = false
+    console.error('[IM] 初始化失败', error)
+  }
+})
+
+/**
+ * 选首屏自动激活的会话；置顶分组折叠时跳过被折叠隐藏的置顶项，避免激活后被自动顶上来
+ *
+ * 折叠态判定只看用户开关；非置顶 / 有未读的置顶项始终可见，全是可折叠置顶时回退到 sorted[0] 兜底
+ */
+function pickFirstVisibleConversation(sorted: Conversation[]): Conversation | undefined {
+  if (sorted.length === 0) {
+    return undefined
+  }
+  const pinnedExpanded =
+    localStorage.getItem(StorageKeys.localStorage.conversationPinnedExpanded) === 'true'
+  if (pinnedExpanded) {
+    return sorted[0]
+  }
+  return sorted.find((c) => !c.top || (!c.silent && (c.unreadCount || 0) > 0)) ?? sorted[0]
+}
+
+/** 标签关闭前 flush 草稿队列；debounce 默认 trail-edge 触发，最后一次输入可能还压在队列里 */
+function onBeforeUnload() {
+  conversationStore.flushConversationDraftSave()
+}
+window.addEventListener('beforeunload', onBeforeUnload)
+
+/** 离开 IM 主壳：取消在飞的 pull + 主动断 WebSocket + flush 草稿 + 清空表情缓存 + 解绑 unload + 停语音 */
+onUnmounted(() => {
+  cancelPull()
+  webSocketStore.disconnect()
+  conversationStore.flushConversationDraftSave()
+  faceStore.clear()
+  // 模块级单例 audio 不会随视图卸载自动停，主动停掉避免切路由后语音继续响
+  voicePlayer.stop()
+  window.removeEventListener('beforeunload', onBeforeUnload)
+  // 停止当前 IM session 并清理各 store 内存
+  void stopRequests()
+})
+
+/**
+ * 当前会话切换：本地清零未读 + 上报后端已读 + 私聊补"对方已读到哪条"
+ *
+ * type+targetId 一起监听：私聊与群聊 id 同号时切换也能触发；其它会话已读状态由 WebSocket
+ * READ / RECEIPT 事件被动同步。私聊补一次拉对方已读位置，弥补离线 / 多端漏掉的 RECEIPT 推送
+ */
+watch(
+  () => [
+    conversationStore.activeConversation?.type,
+    conversationStore.activeConversation?.targetId
+  ],
+  async ([type, targetId]) => {
+    if (!targetId) {
+      return
+    }
+    // 本地清零未读 + 上报后端已读，让其它端 / 对方 UI 同步
+    await readActive()
+    // 私聊补一次"对方已读到哪条"，弥补离线 / 多端漏掉的 RECEIPT 推送
+    if (type === ImConversationType.PRIVATE) {
+      void syncPrivateReadStatus(targetId)
+    }
+  }
+)
+
+/**
+ * 浏览器标签 title 拼上未读数前缀；例：(63条未读)芋道源码
+ *
+ * 路由切换时 router.afterEach 会调 useTitle 重置 title；用 nextTick 排在它之后再覆盖
+ * 一并监听 route.fullPath，IM 子路由切换（消息 / 通讯录）也能重新加上前缀
+ */
+watch(
+  [() => conversationStore.getTotalUnreadCount, () => route.fullPath],
+  ([count]) => {
+    nextTick(() => {
+      const base = preferences.app.name
+      document.title = count > 0 ? `(${count > 99 ? '99+' : count}条未读)${base}` : base
+    })
+  },
+  { immediate: true }
+)
+</script>
+
+<template>
+  <!--
+    IM 外层容器：聊天模块的全屏沉浸式壳
+    - 左侧 ToolBar：头像 + 三 Tab（消息/好友/群聊）+ 底部设置
+    - 右侧 <router-view>：按路由渲染 MessagePage / FriendPage / GroupPage
+    - 挂载全局弹层：UserInfoCard / GroupInfoCard / ContextMenu
+  -->
+  <div
+    class="im-home flex w-full h-full overflow-hidden bg-[var(--ant-color-bg-layout)] text-[var(--ant-color-text)]"
+  >
+    <ToolBar />
+    <!--
+      keep-alive 缓存子页面：
+      - 切 Tab 不重建组件，MessagePanel 滚动位置、输入框草稿等 UI 状态不丢
+      - Vue 3 里 keep-alive 不能直接包 <router-view>（会有警告），必须走 v-slot 拿 Component
+    -->
+    <router-view v-if="childRouteReady" v-slot="{ Component }">
+      <keep-alive>
+        <component :is="Component" />
+      </keep-alive>
+    </router-view>
+    <div v-else class="flex-1 bg-[var(--ant-color-bg-container)]"></div>
+
+    <!-- 全局弹层：由 useImUiStore 统一调度 -->
+    <UserInfoCard />
+    <GroupInfoCard />
+    <ContextMenu />
+
+    <!-- 实时通话浮层；监听 rtcStore 全局状态，可在任意 IM 子页弹出 -->
+    <RtcCallContainer />
+  </div>
+</template>
+
+<style scoped>
+:global(:root) {
+  --im-border-color-lighter: #e8eaed;
+  --im-resize-line-color: #d8dde5;
+
+  /*
+   * IM 聊天端复用 web-antd 的 --ant-color-* 变量名。此处用 Vben design token 兜底定义，
+   * 保持 antd / ele 两端样式结构一致，并随主题（亮/暗）自动切换。
+   * 缺失时这些变量为空 → 背景透明、边框/填充失效（典型：表情面板透出输入框占位文字）。
+   */
+  --ant-color-bg-container: hsl(var(--card));
+  --ant-color-bg-elevated: hsl(var(--popover));
+  --ant-color-bg-layout: hsl(var(--background-deep));
+  --ant-color-border: hsl(var(--border));
+  --ant-color-border-secondary: hsl(var(--border));
+  --ant-color-text: hsl(var(--foreground));
+  --ant-color-text-secondary: hsl(var(--foreground) / 65%);
+  --ant-color-text-placeholder: hsl(var(--foreground) / 45%);
+  --ant-color-text-disabled: hsl(var(--foreground) / 30%);
+  /*
+   * fill 系列：浅色下用 Element Plus 风格的「冷调浅灰实色」而非半透明深色，
+   * 否则面板（会话列表 / 消息面板等）叠在灰底上会显脏发暗，和 Vue3+EP 的干净白差距明显。
+   * 取值依组件实际用法：secondary 多用于面板底（取最浅，对齐 EP --el-bg-color-page #f5f7fa），
+   * tertiary 多用于 hover / 图标块（比面板略深，保证 hover 可见）。深色在 .dark 里另行覆盖。
+   */
+  --ant-color-fill: #e2e6ec;
+  --ant-color-fill-secondary: #f4f6f9;
+  --ant-color-fill-tertiary: #eaedf2;
+  --ant-color-fill-dark: #d5dae2;
+  --ant-color-primary: hsl(var(--primary));
+  --ant-color-primary-hover: hsl(var(--primary) / 80%);
+  --ant-color-primary-bg: hsl(var(--primary) / 12%);
+  --ant-color-primary-bg-hover: hsl(var(--primary) / 18%);
+  --ant-color-info: hsl(var(--primary));
+  --ant-color-success: hsl(var(--success));
+  --ant-color-success-bg: hsl(var(--success) / 12%);
+  --ant-color-success-bg-hover: hsl(var(--success) / 18%);
+  --ant-color-warning: hsl(var(--warning));
+  --ant-color-warning-bg: hsl(var(--warning) / 12%);
+  --ant-color-warning-bg-hover: hsl(var(--warning) / 18%);
+  --ant-color-error: hsl(var(--destructive));
+}
+
+:global(.dark) {
+  --im-border-color-lighter: rgb(255 255 255 / 12%);
+  --im-resize-line-color: rgb(255 255 255 / 18%);
+
+  /* 深色下 fill 回到「基于前景色的半透明亮色」，叠在深底上得到自然的微亮表面 */
+  --ant-color-fill: hsl(var(--foreground) / 12%);
+  --ant-color-fill-secondary: hsl(var(--foreground) / 8%);
+  --ant-color-fill-tertiary: hsl(var(--foreground) / 4%);
+  --ant-color-fill-dark: hsl(var(--foreground) / 18%);
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/contact/friend-list.vue b/apps/web-ele/src/views/im/home/pages/contact/friend-list.vue
new file mode 100644
index 000000000..6fa0dbc98
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/contact/friend-list.vue
@@ -0,0 +1,73 @@
+<script lang="ts" setup>
+import type { FriendLite } from '../../types'
+
+import { ref, toRef } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { FriendItem } from '../../components/friend'
+import { useFriendBuckets } from '../../composables/useFriendBuckets'
+
+defineOptions({ name: 'ImContactFriendList' })
+
+const props = defineProps<{
+  activeId?: number
+  friends: FriendLite[]
+  keyword: string
+}>()
+
+const emit = defineEmits<{
+  chat: [friend: FriendLite]
+  delete: [friend: FriendLite]
+  select: [friend: FriendLite]
+}>()
+
+const expanded = ref(true)
+
+const { filtered, buckets } = useFriendBuckets(toRef(props, 'friends'), toRef(props, 'keyword'))
+</script>
+
+<template>
+  <!--
+    通讯录 - 好友分组
+    - 自治：折叠状态 + 关键字过滤 + 字母分桶 本组件内闭环
+    - 字母分桶 / 拼音搜索委托 useFriendBuckets，与选择类弹窗 FriendPickerPanel 共用一份规则
+    - 选中态由父级 activeId 透传；chat / delete 透传到父级走 store 改造
+  -->
+  <div>
+    <!-- 折叠分组头：字号对齐微信 PC（15px），hover 浅底色反馈 -->
+    <div
+      class="flex gap-2 items-center px-3.5 py-2.5 cursor-pointer select-none text-15px text-[var(--ant-color-text)] hover:bg-[var(--ant-color-fill-secondary)]"
+      @click="expanded = !expanded"
+    >
+      <Icon :icon="expanded ? 'ep:caret-bottom' : 'ep:caret-right'" :size="14" />
+      <span class="flex-1">好友</span>
+      <span class="text-sm text-[var(--ant-color-text-secondary)]">{{ filtered.length }}</span>
+    </div>
+    <div v-show="expanded">
+      <template v-for="bucket in buckets" :key="bucket.letter">
+        <!-- 字母分桶 header：浅底 + 小字号，作为好友列表内部分隔 -->
+        <div
+          class="pt-1 pb-0.5 px-3.5 text-12px text-[var(--ant-color-text-secondary)] bg-[var(--ant-color-fill-tertiary)]"
+        >
+          {{ bucket.letter }}
+        </div>
+        <FriendItem
+          v-for="friend in bucket.list"
+          :key="friend.id"
+          :friend="friend"
+          :active="activeId === friend.id"
+          @click="emit('select', friend)"
+          @chat="emit('chat', $event)"
+          @delete="emit('delete', $event)"
+        />
+      </template>
+      <div
+        v-if="filtered.length === 0"
+        class="py-3 text-12px text-center text-[var(--ant-color-text-disabled)]"
+      >
+        {{ keyword ? '没有匹配的好友' : '暂无好友' }}
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/pages/contact/friend-request-detail.vue b/apps/web-ele/src/views/im/home/pages/contact/friend-request-detail.vue
new file mode 100644
index 000000000..1b63f1c27
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/contact/friend-request-detail.vue
@@ -0,0 +1,229 @@
+<script lang="ts" setup>
+import type { FriendRequest, User } from '../../types'
+
+import { computed, ref } from 'vue'
+
+import { prompt } from '@vben/common-ui'
+import { DICT_TYPE } from '@vben/constants'
+import { getDictLabel } from '@vben/hooks'
+
+import { ElButton, ElInput, ElMessage } from 'element-plus'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { ImFriendRequestHandleResult } from '../../../utils/constants'
+import { UserAvatar } from '../../components/user'
+import { UserInfo } from '../../components/user'
+import { useFriendStore } from '../../store/friendStore'
+
+defineOptions({ name: 'ImContactFriendRequestDetail' })
+
+const props = defineProps<{
+  request: FriendRequest
+}>()
+
+const emit = defineEmits<{
+  chat: [peerUserId: number]
+}>()
+
+const friendStore = useFriendStore()
+
+/** 当前登录用户编号；用 computed 包一层，切账号后随 wsCache 重取，避免顶层求值在 keep-alive 实例里持有旧 id */
+const currentUserId = computed(() => getCurrentUserId())
+
+/** 是不是我发起的（fromUserId === currentUserId） */
+const iSentIt = computed(() => props.request.fromUserId === currentUserId.value)
+
+/** 是否「已拒绝」态：模板里多处用到，computed 一次省得到处写枚举比对 */
+const refused = computed(
+  () => props.request.handleResult === ImFriendRequestHandleResult.REFUSED
+)
+
+/** 是否「已通过」态：转走 UserInfo 好友详情入口 */
+const agreed = computed(
+  () => props.request.handleResult === ImFriendRequestHandleResult.AGREED
+)
+
+/** 对端的用户编号 / 昵称 / 头像 */
+const peerUserId = computed(() =>
+  iSentIt.value ? props.request.toUserId : props.request.fromUserId
+)
+const peerNickname = computed(() =>
+  iSentIt.value
+    ? props.request.toNickname || String(props.request.toUserId)
+    : props.request.fromNickname || String(props.request.fromUserId)
+)
+const peerAvatar = computed(() =>
+  iSentIt.value ? props.request.toAvatar : props.request.fromAvatar
+)
+
+/** 透给 UserInfo 的最小用户信息；UserInfo 内部会按 id 调 getSimpleUser 补齐性别 / 部门 */
+const peerUser = computed<User>(() => ({
+  id: peerUserId.value,
+  nickname: peerNickname.value,
+  avatar: peerAvatar.value
+}))
+
+// 各自的 loading 用于按钮 spinner 显示；processing 是跨按钮互斥锁，避免同意 / 拒绝并发提交同一申请
+const agreeing = ref(false)
+const refusing = ref(false)
+const processing = ref(false)
+
+/** 同意申请：互斥锁 + 状态二次校验，避免并发 / 服务端已处理后再次提交 */
+async function handleAgree() {
+  if (processing.value) {
+    return
+  }
+  if (props.request.handleResult !== ImFriendRequestHandleResult.UNHANDLED) {
+    return
+  }
+  processing.value = true
+  agreeing.value = true
+  try {
+    await friendStore.agreeFriendRequest(props.request.id)
+    ElMessage.success('已同意好友申请')
+  } finally {
+    agreeing.value = false
+    processing.value = false
+  }
+}
+
+/** 拒绝申请：弹 prompt 收集可选拒绝理由（点取消则中止），随后调 store 落库 + 提示 */
+async function handleRefuse() {
+  if (processing.value) {
+    return
+  }
+  if (props.request.handleResult !== ImFriendRequestHandleResult.UNHANDLED) {
+    return
+  }
+  // 1. 弹 prompt 收集拒绝理由（最多 255 字）；用户点「取消」会 reject，中止后续流程
+  let handleContent: string | undefined
+  try {
+    const result = await prompt<string>({
+      beforeClose(scope) {
+        if (!scope.isConfirm) {
+          return
+        }
+        if ((scope.value || '').length > 255) {
+          ElMessage.error('最多 255 个字符')
+          return false
+        }
+      },
+      cancelText: '取消',
+      component: ElInput,
+      componentProps: {
+        clearable: true,
+        maxlength: 255,
+        placeholder: '不填则不告知对方原因',
+        rows: 3
+      },
+      content: '',
+      defaultValue: '',
+      confirmText: '拒绝',
+      modelPropName: 'value',
+      title: '拒绝好友申请'
+    })
+    handleContent = result || undefined
+  } catch {
+    return
+  }
+  // 2. prompt 期间状态可能被跨端改成 AGREED / REFUSED，再校验一次避免重复提交
+  if (processing.value) {
+    return
+  }
+  if (props.request.handleResult !== ImFriendRequestHandleResult.UNHANDLED) {
+    return
+  }
+  processing.value = true
+  refusing.value = true
+  try {
+    await friendStore.refuseFriendRequest(props.request.id, handleContent)
+    ElMessage.success('已拒绝好友申请')
+  } finally {
+    refusing.value = false
+    processing.value = false
+  }
+}
+</script>
+
+<template>
+  <!--
+    新的朋友详情面板
+    - 已通过 → 直接走 UserInfo 好友详情，跟通讯录里点开好友的体验完全一致
+    - 未处理 / 已拒绝 → 申请态面板：头像 + 申请/拒绝对话气泡 + 来源 + 操作按钮
+  -->
+  <div v-if="agreed" class="flex justify-center pt-12 px-6">
+    <div class="w-full max-w-[320px]">
+      <UserInfo
+        :user="peerUser"
+        :display-name="friendStore.getFriend(peerUserId)?.displayName || ''"
+        relation="friend"
+        @chat="emit('chat', peerUserId)"
+      />
+    </div>
+  </div>
+
+  <div v-else class="flex flex-col items-center px-6 pt-12">
+    <UserAvatar
+      :id="peerUserId"
+      :url="peerAvatar"
+      :name="peerNickname"
+      :size="64"
+      :clickable="false"
+    />
+    <div class="mt-3 text-base font-semibold text-[var(--ant-color-text)]">
+      {{ peerNickname }}
+    </div>
+
+    <!-- 申请理由块：仿微信灰底气泡，按申请方身份前缀；长文本 break-words 折行 -->
+    <div
+      v-if="request.applyContent"
+      class="w-full max-w-[420px] mt-6 px-3.5 py-3 rounded-md bg-[var(--ant-color-fill-secondary)] text-13px text-[var(--ant-color-text)] break-words"
+    >
+      <span class="text-[var(--ant-color-text-secondary)]">
+        {{ iSentIt ? '我' : peerNickname }}:
+      </span>
+      <span class="ml-1">{{ request.applyContent }}</span>
+    </div>
+    <!-- 来源行：label 左、value 右，对齐微信「来源」行 -->
+    <div
+      v-if="request.addSource"
+      class="w-full max-w-[420px] mt-3 flex items-center text-13px text-[var(--ant-color-text-secondary)]"
+    >
+      <span class="w-16 flex-shrink-0 whitespace-nowrap">来源</span>
+      <span class="text-[var(--ant-color-text)]">
+        {{ getDictLabel(DICT_TYPE.IM_FRIEND_ADD_SOURCE, request.addSource) }}
+      </span>
+    </div>
+    <!-- 拒绝理由：label 左、value 右；长文本 break-words 自动折行 -->
+    <div
+      v-if="refused && request.handleContent"
+      class="w-full max-w-[420px] mt-3 flex items-start text-13px text-[var(--ant-color-text-secondary)]"
+    >
+      <span class="w-16 flex-shrink-0 whitespace-nowrap">拒绝理由</span>
+      <span class="flex-1 min-w-0 break-words text-[var(--ant-color-text)]">
+        {{ request.handleContent }}
+      </span>
+    </div>
+
+    <!-- 操作按钮 -->
+    <div class="w-full max-w-[420px] mt-8 flex justify-center">
+      <!-- 我发起 + 等待中：禁用「等待对方验证」 -->
+      <ElButton
+        v-if="iSentIt && request.handleResult === ImFriendRequestHandleResult.UNHANDLED"
+        disabled
+      >
+        等待对方验证
+      </ElButton>
+      <!-- 别人加我 + 等待中：同意 / 拒绝 -->
+      <template v-if="!iSentIt && request.handleResult === ImFriendRequestHandleResult.UNHANDLED">
+        <ElButton @click="handleRefuse" :loading="refusing" :disabled="processing">拒绝</ElButton>
+        <ElButton type="primary" @click="handleAgree" :loading="agreeing" :disabled="processing">
+          同意
+        </ElButton>
+      </template>
+      <!-- 已拒绝：占位禁用按钮 -->
+      <ElButton v-if="refused" disabled>已拒绝</ElButton>
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/pages/contact/friend-request-list.vue b/apps/web-ele/src/views/im/home/pages/contact/friend-request-list.vue
new file mode 100644
index 000000000..2b60adf60
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/contact/friend-request-list.vue
@@ -0,0 +1,138 @@
+<script lang="ts" setup>
+import type { FriendRequest } from '../../types'
+
+import { computed, ref } from 'vue'
+
+import { DICT_TYPE } from '@vben/constants'
+import { getDictLabel } from '@vben/hooks'
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElBadge } from 'element-plus'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { UserAvatar } from '../../components/user'
+import { useFriendStore } from '../../store/friendStore'
+
+defineOptions({ name: 'ImContactFriendRequestList' })
+
+const props = defineProps<{
+  activeId?: number
+  requests: FriendRequest[]
+}>()
+
+const emit = defineEmits<{
+  select: [request: FriendRequest]
+}>()
+
+const friendStore = useFriendStore()
+const expanded = ref(true)
+/** 当前登录用户编号；用 computed 包一层，切账号后随 wsCache 重取，避免顶层求值在 keep-alive 实例里持有旧 id */
+const currentUserId = computed(() => getCurrentUserId())
+
+/** 列表项展示对端：fromUserId == 我 → 对端 = toUser；否则对端 = fromUser */
+function getPeer(request: FriendRequest) {
+  const sentByMe = request.fromUserId === currentUserId.value
+  return {
+    id: sentByMe ? request.toUserId : request.fromUserId,
+    nickname: sentByMe
+      ? request.toNickname || String(request.toUserId)
+      : request.fromNickname || String(request.fromUserId),
+    avatar: sentByMe ? request.toAvatar : request.fromAvatar
+  }
+}
+
+/** 列表项预先附 peer 字段，模板里直接 {{ peer.xxx }} 一次成型，省 3 次 helper 调用 */
+const enrichedRequests = computed(() =>
+  props.requests.map((request) => ({ request, peer: getPeer(request) }))
+)
+
+const loadingMore = ref(false) // 点击「加载更多」拉下一页；store 内部按 maxId 游标分页 + pending 去重
+async function handleLoadMore() {
+  if (loadingMore.value) {
+    return
+  }
+  loadingMore.value = true
+  try {
+    await friendStore.loadMoreFriendRequestList()
+  } finally {
+    loadingMore.value = false
+  }
+}
+</script>
+
+<template>
+  <!--
+    通讯录 - 新的朋友分组
+    - 自治：折叠状态由组件内 ref 管理，默认展开
+    - 列表项展示：头像 + 昵称 + 申请理由 + 状态标签（等待验证 / 已添加 / 已拒绝）
+    - 选中态由父级 activeId 透传；点击触发 select 事件
+  -->
+  <div>
+    <!-- 折叠分组头 -->
+    <div
+      class="flex gap-2 items-center px-3.5 py-2.5 text-15px text-[var(--ant-color-text)] cursor-pointer select-none hover:bg-[var(--ant-color-fill-secondary)]"
+      @click="expanded = !expanded"
+    >
+      <Icon :icon="expanded ? 'ep:caret-bottom' : 'ep:caret-right'" :size="14" />
+      <span class="flex-1">新的朋友</span>
+      <!-- 红点：未处理且别人加我的（统一走 store getter，避免本地 computed 跟 store 双口径） -->
+      <ElBadge
+        v-if="friendStore.getUnhandledRequestCount > 0"
+        :count="friendStore.getUnhandledRequestCount"
+        :max="99"
+        class="mr-2"
+      />
+      <span class="text-sm text-[var(--ant-color-text-secondary)]">{{ requests.length }}</span>
+    </div>
+    <div v-show="expanded">
+      <div
+        v-for="{ request, peer } in enrichedRequests"
+        :key="request.id"
+        class="flex gap-3 items-start px-3.5 py-2.5 cursor-pointer transition-colors hover:bg-[var(--ant-color-fill-secondary)]"
+        :class="{
+          'bg-[var(--ant-color-fill)]': activeId === request.id
+        }"
+        @click="emit('select', request)"
+      >
+        <UserAvatar
+          :id="peer.id"
+          :url="peer.avatar"
+          :name="peer.nickname"
+          :size="36"
+          :clickable="false"
+        />
+        <div class="flex-1 min-w-0 overflow-hidden">
+          <div class="flex justify-between gap-2 items-center">
+            <span class="flex-1 text-sm font-medium truncate text-[var(--ant-color-text)]">
+              {{ peer.nickname }}
+            </span>
+            <span class="flex-shrink-0 text-12px text-[var(--ant-color-text-secondary)]">
+              {{ getDictLabel(DICT_TYPE.IM_FRIEND_REQUEST_HANDLE_RESULT, request.handleResult) }}
+            </span>
+          </div>
+          <div
+            v-if="request.applyContent"
+            class="mt-0.5 text-xs truncate text-[var(--ant-color-text-secondary)]"
+          >
+            {{ request.applyContent }}
+          </div>
+        </div>
+      </div>
+      <div
+        v-if="requests.length === 0"
+        class="py-3 text-12px text-center text-[var(--ant-color-text-disabled)]"
+      >
+        暂无新的朋友
+      </div>
+      <!-- 加载更多：按本地最旧 requestId 游标分页拉下一批；hasMore=false 不展示 -->
+      <div
+        v-else-if="friendStore.hasMoreFriendRequests"
+        class="py-2 text-12px text-center cursor-pointer text-[var(--ant-color-text-secondary)] hover:bg-[var(--ant-color-fill-secondary)]"
+        @click="handleLoadMore"
+      >
+        {{ loadingMore ? '加载中…' : '加载更多' }}
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/pages/contact/group-detail.vue b/apps/web-ele/src/views/im/home/pages/contact/group-detail.vue
new file mode 100644
index 000000000..e93bb356e
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/contact/group-detail.vue
@@ -0,0 +1,26 @@
+<script lang="ts" setup>
+import type { GroupLite } from '../../types'
+
+import { GroupInfo } from '../../components/group'
+
+defineOptions({ name: 'ImContactGroupDetail' })
+
+defineProps<{
+  group: GroupLite
+}>()
+
+const emit = defineEmits<{
+  chat: [group: GroupLite]
+}>()
+</script>
+
+<template>
+  <!--
+    通讯录 - 群聊详情
+    - 内容走共享 <GroupInfo>，与 GroupInfoCard 浮层用同一份组件
+    - 通讯录里都是已加群（GroupInfo 内部按 groupStore 推导）；chat 抛上去由父级承接
+  -->
+  <div class="pt-12 px-6">
+    <GroupInfo :group="group" @chat="emit('chat', $event)" />
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/pages/contact/group-list.vue b/apps/web-ele/src/views/im/home/pages/contact/group-list.vue
new file mode 100644
index 000000000..8b094f791
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/contact/group-list.vue
@@ -0,0 +1,65 @@
+<script lang="ts" setup>
+import type { GroupLite } from '../../types'
+
+import { computed, ref } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { GroupItem } from '../../components/group'
+
+defineOptions({ name: 'ImContactGroupList' })
+
+const props = defineProps<{
+  activeId?: number
+  groups: GroupLite[]
+  keyword: string
+}>()
+
+const emit = defineEmits<{ select: [group: GroupLite] }>()
+
+const expanded = ref(true)
+
+const filtered = computed(() => {
+  const keywordLower = props.keyword.trim().toLowerCase()
+  if (!keywordLower) {
+    return props.groups
+  }
+  return props.groups.filter((group) =>
+    (group.showGroupName || group.name || '').toLowerCase().includes(keywordLower)
+  )
+})
+</script>
+
+<template>
+  <!--
+    通讯录 - 群聊分组
+    - 自治：折叠状态 + 关键字过滤本组件内闭环
+    - 选中态由父级 activeId 透传，避免子组件持有 selection 知识
+  -->
+  <div>
+    <!-- 折叠分组头：字号对齐微信 PC（15px），hover 浅底色反馈 -->
+    <div
+      class="flex gap-2 items-center px-3.5 py-2.5 text-15px text-[var(--ant-color-text)] cursor-pointer select-none hover:bg-[var(--ant-color-fill-secondary)]"
+      @click="expanded = !expanded"
+    >
+      <Icon :icon="expanded ? 'ep:caret-bottom' : 'ep:caret-right'" :size="14" />
+      <span class="flex-1">群聊</span>
+      <span class="text-sm text-[var(--ant-color-text-secondary)]">{{ filtered.length }}</span>
+    </div>
+    <div v-show="expanded">
+      <GroupItem
+        v-for="group in filtered"
+        :key="group.id"
+        :group="group"
+        :active="activeId === group.id"
+        @click="emit('select', group)"
+      />
+      <div
+        v-if="filtered.length === 0"
+        class="py-3 text-12px text-center text-[var(--ant-color-text-disabled)]"
+      >
+        {{ keyword ? '没有匹配的群聊' : '暂无群聊' }}
+      </div>
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/pages/contact/index.vue b/apps/web-ele/src/views/im/home/pages/contact/index.vue
new file mode 100644
index 000000000..e6b79b8de
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/contact/index.vue
@@ -0,0 +1,309 @@
+<script lang="ts" setup>
+import type { FriendLite, FriendRequest, Group, GroupLite, User } from '../../types'
+
+import { computed, onMounted, ref, watch } from 'vue'
+import { useRouter } from 'vue-router'
+
+import { confirm } from '@vben/common-ui'
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElInput, ElMessage } from 'element-plus'
+
+import { ImConversationType } from '../../../utils/constants'
+import { StorageKeys } from '../../../utils/db'
+import { getFriendDisplayName, getGroupDisplayName, isGroupQuit } from '../../../utils/user'
+import { ResizableAside } from '../../components'
+import { UserInfo } from '../../components/user'
+import { useConversationStore } from '../../store/conversationStore'
+import { useFriendStore } from '../../store/friendStore'
+import { useGroupStore } from '../../store/groupStore'
+import FriendList from './friend-list.vue'
+import FriendRequestDetail from './friend-request-detail.vue'
+import FriendRequestList from './friend-request-list.vue'
+import GroupDetail from './group-detail.vue'
+import GroupList from './group-list.vue'
+
+defineOptions({ name: 'ImContactPage' })
+
+const router = useRouter()
+const conversationStore = useConversationStore()
+const friendStore = useFriendStore()
+const groupStore = useGroupStore()
+
+/** 用 type 判别选中是好友 / 群聊 / 好友申请 */
+type Selection =
+  | { friend: FriendLite; type: 'friend'; }
+  | { group: GroupLite; type: 'group'; }
+  | { request: FriendRequest; type: 'request'; }
+
+const selection = ref<null | Selection>(null)
+const keyword = ref('')
+
+/** 选中申请详情：详情用 store 里的最新副本（同意 / 拒绝后状态会变） */
+const currentRequest = computed<FriendRequest>(() => {
+  const req = selection.value?.type === 'request' ? selection.value.request : null
+  if (!req) {
+    return {} as FriendRequest
+  }
+  return friendStore.getFriendRequest(req.id) || req
+})
+
+/** 我相关的申请列表（用 friendStore 里的实时副本，便于通知到达后自动刷新） */
+const friendRequests = computed<FriendRequest[]>(() => friendStore.friendRequests)
+
+/** 好友列表的展示快照：附带后端算好的拼音，给 FriendList 做字母分桶 / 拼音搜索 */
+const friends = computed<FriendLite[]>(() => friendStore.getActiveFriendLiteList)
+
+const groups = computed<GroupLite[]>(() =>
+  // 通讯录只展示当前仍在群的；已退群历史群只留在 store 里供消息展示群名 / 头像，不进通讯录
+  groupStore.groups
+    .filter((group: Group) => !isGroupQuit(group))
+    .map((group: Group) => ({
+      id: group.id,
+      name: group.name,
+      showGroupName: getGroupDisplayName(group), // 优先用群备注 groupRemark，没设置时回落到原群名；避免点"进入群聊"时把已同步的备注会话名刷回原名
+      showImage: group.avatar,
+      showImageThumb: group.avatar,
+      memberCount: group.memberCount
+    }))
+)
+
+/**
+ * store 列表变化时同步 selection 持的对象副本：对端推送 / 跨端动作改 store 后，右侧详情能跟上：
+ * - 命中则替换为最新引用，资料 / 备注 / 申请状态变更立刻反映
+ * - 找不到（删除 / 拒绝 / 已通过等让记录消失）则置 null 收起详情
+ */
+watch(
+  friends,
+  (list) => {
+    const selected = selection.value
+    if (selected?.type !== 'friend') {
+      return
+    }
+    const fresh = list.find((friend) => friend.id === selected.friend.id)
+    if (!fresh) {
+      selection.value = null
+    } else if (fresh !== selected.friend) {
+      selection.value = { type: 'friend', friend: fresh }
+    }
+  },
+  { deep: true }
+)
+watch(
+  groups,
+  (list) => {
+    const selected = selection.value
+    if (selected?.type !== 'group') {
+      return
+    }
+    const fresh = list.find((group) => group.id === selected.group.id)
+    if (!fresh) {
+      selection.value = null
+    } else if (fresh !== selected.group) {
+      selection.value = { type: 'group', group: fresh }
+    }
+  },
+  { deep: true }
+)
+watch(
+  friendRequests,
+  (list) => {
+    const selected = selection.value
+    if (selected?.type !== 'request') {
+      return
+    }
+    const fresh = list.find((request) => request.id === selected.request.id)
+    if (!fresh) {
+      selection.value = null
+    } else if (fresh !== selected.request) {
+      selection.value = { type: 'request', request: fresh }
+    }
+  },
+  { deep: true }
+)
+
+const friendUser = computed<null | User>(() => {
+  if (selection.value?.type !== 'friend') {
+    return null
+  }
+  const friend = selection.value.friend
+  return {
+    id: friend.id,
+    nickname: friend.nickname,
+    avatar: friend.avatar
+  }
+})
+
+onMounted(async () => {
+  await Promise.all([
+    friendStore.fetchFriendList(),
+    friendStore.fetchFriendRequestList(),
+    groupStore.fetchGroupList()
+  ])
+})
+
+/** 选中好友 → 切到好友详情 */
+function handleSelectFriend(friend: FriendLite) {
+  selection.value = { type: 'friend', friend }
+}
+
+/** 选中群聊 → 切到群详情 */
+function handleSelectGroup(group: GroupLite) {
+  selection.value = { type: 'group', group }
+}
+
+/** 选中好友申请 → 切到「新的朋友」详情 */
+function handleSelectRequest(request: FriendRequest) {
+  selection.value = { type: 'request', request }
+}
+
+/** 申请详情里点「发消息」：直接进与对端的私聊会话 */
+function handleChatPeer(peerUserId: number) {
+  const friend = friendStore.getFriend(peerUserId)
+  const conversationName = friend ? getFriendDisplayName(friend) : String(peerUserId)
+  conversationStore.openConversation(
+    peerUserId,
+    ImConversationType.PRIVATE,
+    conversationName,
+    friend?.avatar || '',
+    { silent: !!friend?.silent }
+  )
+  router.push({ name: 'ImHomeConversation' })
+}
+
+/** 进入与该好友的私聊会话 */
+function handleChatFriend(friend: FriendLite) {
+  // 从 friendStore 同步备注 + 免打扰，避免新建会话用过期数据
+  const entry = friendStore.getFriend(friend.id)
+  const conversationName = entry ? getFriendDisplayName(entry) : friend.nickname
+  conversationStore.openConversation(
+    friend.id,
+    ImConversationType.PRIVATE,
+    conversationName,
+    friend.avatar || '',
+    { silent: !!entry?.silent }
+  )
+  router.push({ name: 'ImHomeConversation' })
+}
+
+/** 进入该群的群聊会话 */
+function handleChatGroup(group: GroupLite) {
+  const entry = groupStore.getGroup(group.id)
+  conversationStore.openConversation(
+    group.id,
+    ImConversationType.GROUP,
+    group.showGroupName || group.name || '',
+    group.showImage || group.showImageThumb || '',
+    { silent: !!entry?.silent }
+  )
+  router.push({ name: 'ImHomeConversation' })
+}
+
+/** 删除好友：二次确认 → store 落库 → 清空当前选中 */
+async function handleDeleteFriend(friend: FriendLite) {
+  try {
+    await confirm(`确定删除好友「${friend.nickname}」吗？`, '删除联系人')
+    // friendStore.deleteFriend 内部已经级联清理对应私聊会话
+    await friendStore.deleteFriend(friend.id)
+    if (selection.value?.type === 'friend' && selection.value.friend.id === friend.id) {
+      selection.value = null
+    }
+    ElMessage.success('已删除好友')
+  } catch {}
+}
+
+/** 备注已保存：UserInfo 内部已经走完 friendStore 落库 + 提示，本侧只负责同步 selection 持的旧 FriendLite 副本 */
+function onRemarkSaved(displayName: string) {
+  if (selection.value?.type === 'friend') {
+    selection.value.friend.displayName = displayName
+  }
+}
+</script>
+
+<template>
+  <!--
+    通讯录 Tab 整页（参考微信 PC 通讯录）
+    - 左：搜索 + GroupList / FriendList 两个折叠分组（好友按字母分桶）
+    - 右：选中项的详情，好友走共享 <UserInfo>（relation=friend），群聊走 GroupDetail
+    - 本页仅做：选中分发 + 数据源转换 + 跨组件事件落 store
+  -->
+  <div class="flex flex-1 h-full min-w-0 bg-[var(--ant-color-bg-container)]">
+    <ResizableAside :default-width="260" :storage-key="StorageKeys.localStorage.asideWidth">
+      <!-- 顶部：仅搜索框；h-14 与消息 Tab 顶部对齐，避免切换时搜索框上下抖动 -->
+      <div
+        class="flex flex-shrink-0 items-center h-14 px-4 border-b border-b-solid border-[var(--im-border-color-lighter)]"
+      >
+        <ElInput v-model="keyword" placeholder="搜索" clearable class="flex-1">
+          <template #prefix>
+            <Icon icon="ant-design:search-outlined" />
+          </template>
+        </ElInput>
+      </div>
+
+      <!-- 列表主体：拆 FriendRequestList / GroupList / FriendList 三个子组件，各自管理折叠 + 过滤；本页只透传选中态 -->
+      <!-- overflow-y-auto：联系人多时本列表可滚动（父 ResizableAside 不提供滚动），对齐 Vue3 的 el-scrollbar -->
+      <div class="flex-1 overflow-y-auto">
+        <FriendRequestList
+          :requests="friendRequests"
+          :active-id="selection?.type === 'request' ? selection.request.id : undefined"
+          @select="handleSelectRequest"
+        />
+        <GroupList
+          :groups="groups"
+          :keyword="keyword"
+          :active-id="selection?.type === 'group' ? selection.group.id : undefined"
+          @select="handleSelectGroup"
+        />
+        <FriendList
+          :friends="friends"
+          :keyword="keyword"
+          :active-id="selection?.type === 'friend' ? selection.friend.id : undefined"
+          @select="handleSelectFriend"
+          @chat="handleChatFriend"
+          @delete="handleDeleteFriend"
+        />
+      </div>
+    </ResizableAside>
+
+    <!-- 右侧详情区 -->
+    <div class="flex-1 min-w-0">
+      <!-- 空态：占位图标 + 提示文案 -->
+      <div
+        v-if="!selection"
+        class="flex flex-col items-center justify-center h-full gap-3 text-[var(--ant-color-text-secondary)]"
+      >
+        <Icon
+          icon="ant-design:contacts-outlined"
+          :size="64"
+          class="text-[var(--ant-color-text-placeholder)]"
+        />
+        <span class="text-sm">在左侧选择好友或群聊查看详情</span>
+      </div>
+      <!-- 好友详情 -->
+      <div v-else-if="selection.type === 'friend'" class="flex justify-center pt-12 px-6">
+        <div class="w-full max-w-[320px]">
+          <UserInfo
+            :user="friendUser"
+            :display-name="selection.friend.displayName || ''"
+            relation="friend"
+            @chat="handleChatFriend(selection.friend)"
+            @deleted="selection = null"
+            @saved="onRemarkSaved"
+          />
+        </div>
+      </div>
+      <!-- 群详情 -->
+      <GroupDetail
+        v-else-if="selection.type === 'group'"
+        :group="selection.group"
+        @chat="handleChatGroup"
+      />
+      <!-- 新的朋友 - 申请详情 -->
+      <FriendRequestDetail
+        v-else-if="selection.type === 'request'"
+        :request="currentRequest"
+        @chat="handleChatPeer"
+      />
+    </div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/conversation-group-side.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/conversation-group-side.vue
new file mode 100644
index 000000000..5dd7b5b1b
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/conversation-group-side.vue
@@ -0,0 +1,837 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from '../../../../components/group'
+import type { Conversation, GroupLite } from '../../../../types'
+
+import { computed, ref, watch } from 'vue'
+
+import { confirm } from '@vben/common-ui'
+import { CommonStatusEnum } from '@vben/constants'
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElButton, ElDrawer, ElInput, ElMessage, ElPopover, ElSwitch } from 'element-plus'
+
+import {
+  dissolveGroup,
+  muteAll,
+  updateGroup
+} from '#/api/im/group'
+import { quitGroup, updateGroupMember } from '#/api/im/group/member'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+import { ImConversationType, ImGroupMemberRole } from '#/views/im/utils/constants'
+import { toGroupCardTarget } from '#/views/im/utils/message'
+import { isGroupQuit } from '#/views/im/utils/user'
+
+import { GroupAdminSetDialog } from '../../../../components/group'
+import { GroupMemberAddDialog } from '../../../../components/group'
+import { GroupMemberGrid } from '../../../../components/group'
+import { GroupMemberRemoveDialog } from '../../../../components/group'
+import { GroupOwnerTransferDialog } from '../../../../components/group'
+import { GroupRequestListDialog } from '../../../../components/group'
+import { RecommendCardDialog } from '../../../../components/user'
+import { useConversationStore } from '../../../../store/conversationStore'
+import { useGroupStore } from '../../../../store/groupStore'
+
+defineOptions({ name: 'ImConversationGroupSide' })
+
+// 大群默认只展示前 N 个成员（4×4 宫格 − 2 个瓦片预留给"添加 / 移出"按钮）
+
+const props = withDefaults(
+  defineProps<{
+    conversation?: Conversation | null // 当前会话：用于读 / 切免打扰、置顶状态
+    group?: GroupLite & { groupRemark?: string; notice?: string; remarkNickName?: string; } // 当前群信息（可空：无激活群会话时）
+    members?: GroupMemberLite[]
+    modelValue?: boolean // 抽屉是否打开（v-model）
+  }>(),
+  {
+    conversation: null,
+    group: undefined,
+    modelValue: false,
+    members: () => []
+  }
+)
+
+const emit = defineEmits<{
+  openHistory: [] // 点击 "查找聊天内容" 行 → 父组件打开 MessageHistory 弹窗
+  reload: [friendIds?: number[]] // 邀请 / 移除 / 修改群资料后，父组件重新拉群数据；邀请新成员场景透出 friendIds 让上层可选精准刷新
+  'update:modelValue': [value: boolean]
+}>()
+
+const MEMBER_PREVIEW_COUNT = 14
+const conversationStore = useConversationStore()
+const groupStore = useGroupStore()
+
+const visible = computed({
+  get: () => props.modelValue,
+  set: (v) => emit('update:modelValue', v)
+})
+
+// ==================== 角色 / 成员展示 ====================
+
+const searchText = ref('')
+const showAllMembers = ref(false)
+
+const inviteDialogRef = ref<InstanceType<typeof GroupMemberAddDialog>>() // 邀请好友入群弹窗 ref：handleOpenInvite 调 open({ groupId }) 打开
+/** 打开邀请好友入群弹窗 */
+function handleOpenInvite() {
+  if (!props.group?.id) {
+    return
+  }
+  inviteDialogRef.value?.open({ groupId: props.group.id })
+}
+
+const myId = computed(() => getCurrentUserId())
+/** 历史退群群：禁所有群操作入口（邀请 / 移出 / 改资料 / 禁言 / 审批 / 退出等），只保留展示；props.group 是 GroupLite 无 joinStatus，回 store 取全量 */
+const isQuitGroup = computed(() => {
+  const id = props.group?.id
+  return id != null && isGroupQuit(groupStore.getGroup(id))
+})
+const isOwner = computed(
+  () => !isQuitGroup.value && props.group != null && props.group.ownerId === myId.value
+)
+/** 当前用户在群里的角色（来自 props.members 的 me 行）；用于判定是否可移出他人 */
+const myRole = computed(() => props.members.find((m) => m.userId === myId.value)?.role)
+/** 群主或管理员：在抽屉里有 "移出群成员" 入口；历史退群群一律视为无权限 */
+const isOwnerOrAdmin = computed(
+  () =>
+    !isQuitGroup.value &&
+    (myRole.value === ImGroupMemberRole.OWNER || myRole.value === ImGroupMemberRole.ADMIN)
+)
+
+/** 排除已退群成员 + 关键字过滤；按角色排序：群主→管理员→普通成员（同角色按 userId 稳定） */
+const visibleMembers = computed(() => {
+  return props.members
+    .filter(
+      (member) =>
+        member.status !== CommonStatusEnum.DISABLE &&
+        (member.showName || '').includes(searchText.value)
+    )
+    .toSorted((a, b) => {
+      const roleA = a.role ?? ImGroupMemberRole.NORMAL
+      const roleB = b.role ?? ImGroupMemberRole.NORMAL
+      return roleA === roleB ? a.userId - b.userId : roleA - roleB
+    })
+})
+
+/** 折叠规则：搜索 / 已展开 时不折叠，其余只取前 N 个 */
+const moreMembersHidden = computed(
+  () =>
+    !searchText.value && !showAllMembers.value && visibleMembers.value.length > MEMBER_PREVIEW_COUNT
+)
+const displayMembers = computed(() =>
+  moreMembersHidden.value
+    ? visibleMembers.value.slice(0, MEMBER_PREVIEW_COUNT)
+    : visibleMembers.value
+)
+
+// 抽屉关闭时清掉成员区临时态（搜索关键字、查看更多展开）
+watch(visible, (v) => {
+  if (!v) {
+    searchText.value = ''
+    showAllMembers.value = false
+  }
+})
+
+// ==================== 群信息编辑 ====================
+
+const namePopoverVisible = ref(false)
+const noticePopoverVisible = ref(false)
+const remarkPopoverVisible = ref(false)
+const groupRemarkPopoverVisible = ref(false)
+const editName = ref('')
+const editNotice = ref('')
+const editRemark = ref('')
+const editGroupRemark = ref('')
+
+// popover 弹出时把当前值灌进编辑态，避免上次未保存的脏值
+watch(namePopoverVisible, (v) => {
+  if (v) editName.value = props.group?.name || ''
+})
+watch(noticePopoverVisible, (v) => {
+  if (v) editNotice.value = props.group?.notice || ''
+})
+watch(remarkPopoverVisible, (v) => {
+  if (v) editRemark.value = props.group?.remarkNickName || ''
+})
+watch(groupRemarkPopoverVisible, (v) => {
+  if (v) editGroupRemark.value = props.group?.groupRemark || ''
+})
+
+// 抽屉关闭时清掉所有 popover，避免下次打开仍弹着
+watch(visible, (v) => {
+  if (!v) {
+    namePopoverVisible.value = false
+    noticePopoverVisible.value = false
+    remarkPopoverVisible.value = false
+    groupRemarkPopoverVisible.value = false
+  }
+})
+
+/** 群主：保存群名（走 /im/group/update）；trim 后空字符串拒提交，与 saveGroupRemark 行为对齐 */
+async function saveName() {
+  if (!props.group) {
+    return
+  }
+  const trimmed = editName.value.trim()
+  if (!trimmed) {
+    ElMessage.warning('群名称不能为空')
+    return
+  }
+  await updateGroup({ id: props.group.id, name: trimmed })
+  namePopoverVisible.value = false
+  ElMessage.success('保存成功')
+  emit('reload')
+}
+
+/** 群主：保存群公告 */
+async function saveNotice() {
+  if (!props.group) {
+    return
+  }
+  await updateGroup({ id: props.group.id, notice: editNotice.value })
+  noticePopoverVisible.value = false
+  ElMessage.success('保存成功')
+  emit('reload')
+}
+
+/** 群主：切换「进群审批」开关；开启后所有「申请」「邀请」路径都需群主 / 管理员同意 */
+async function handleJoinApprovalChange(value: boolean | number | string) {
+  if (!props.group) {
+    return
+  }
+  await updateGroup({ id: props.group.id, joinApproval: !!value })
+  ElMessage.success('保存成功')
+  emit('reload')
+}
+
+/** 任何成员：保存群备注（仅自己可见，会替换会话列表 / 顶部群名展示） */
+async function saveGroupRemark() {
+  if (!props.group) {
+    return
+  }
+  await updateGroupMember({
+    groupId: props.group.id,
+    groupRemark: editGroupRemark.value.trim()
+  })
+  groupRemarkPopoverVisible.value = false
+  ElMessage.success('保存成功')
+  emit('reload')
+}
+
+/** 任何成员：保存自己在群里的昵称（走 /im/group-member/update） */
+async function saveRemark() {
+  if (!props.group) {
+    return
+  }
+  await updateGroupMember({
+    groupId: props.group.id,
+    displayUserName: editRemark.value
+  })
+  remarkPopoverVisible.value = false
+  ElMessage.success('保存成功')
+  emit('reload')
+}
+
+// ==================== 开关切换 ====================
+
+/**
+ * 消息免打扰：本地 conversationStore 立即切；后端 /silent 异步同步，失败回滚本地
+ *
+ * 与 ConversationItem 右键菜单的"消息免打扰"语义一致；区别仅在 UI 入口
+ */
+function onMutedChange(value: boolean | number | string) {
+  if (!props.conversation) {
+    return
+  }
+  const next = !!value
+  const { type, targetId } = props.conversation
+  conversationStore.setConversationSilent(type, targetId, next)
+  groupStore.setGroupSilent(targetId, next).catch((error) => {
+    console.error('[IM ConversationGroupSide] setGroupSilent 失败', { targetId }, error)
+    conversationStore.setConversationSilent(type, targetId, !next)
+  })
+}
+
+/** 置顶聊天：纯本地 conversationStore 排序态（无后端字段） */
+function onTopChange(value: boolean | number | string) {
+  if (!props.conversation) {
+    return
+  }
+  conversationStore.setConversationTop(props.conversation.type, props.conversation.targetId, !!value)
+}
+
+// ==================== 全群禁言 ====================
+
+/** 当前群是否全群禁言 */
+const currentMutedAll = computed(() => {
+  if (!props.group) {
+    return false
+  }
+  return groupStore.getGroup(props.group.id)?.mutedAll ?? false
+})
+
+/** 全群禁言开关切换 */
+async function onMuteAllChange(value: boolean | number | string) {
+  if (!props.group) {
+    return
+  }
+  const newValue = !!value
+  await muteAll({ id: props.group.id, mutedAll: newValue })
+  ElMessage.success(newValue ? '已开启全群禁言' : '已关闭全群禁言')
+  emit('reload')
+}
+
+// ==================== 进群审批 ====================
+
+const requestListDialogRef = ref<InstanceType<typeof GroupRequestListDialog>>() // 进群申请列表弹窗 ref：handleOpenRequestList 调 open({ groupId }) 触发
+
+/** 打开当前群的进群申请列表 */
+function handleOpenRequestList() {
+  if (!props.group?.id) {
+    return
+  }
+  requestListDialogRef.value?.open({ groupId: props.group.id })
+}
+
+// ==================== 分享群名片 ====================
+
+const recommendCardDialogRef = ref<InstanceType<typeof RecommendCardDialog>>() // 分享群名片弹窗 ref：handleShareGroupCard 调用 open({ target }) 打开
+
+/** 分享群名片：把当前群作为名片消息推荐给其他会话 */
+function handleShareGroupCard() {
+  const target = toGroupCardTarget(props.group)
+  if (!target) {
+    return
+  }
+  recommendCardDialogRef.value?.open({ target })
+}
+
+// ==================== 退出群聊 ====================
+
+/** 退出群聊（普通成员入口；群主退出走"解散群"是另一条路径，这里不处理） */
+async function handleQuit() {
+  if (!props.group) {
+    return
+  }
+  // 二次确认
+  try {
+    await confirm('退出群聊后将不再接收群里的消息，确认退出吗？', '确认退出')
+  } catch {
+    return
+  }
+  const groupId = props.group.id
+  await quitGroup(groupId)
+  // 本地立即响应：先把 self.member 置 DISABLE（让 GroupInfo 等 isMember 收敛），再清会话 + 群 store
+  if (myId.value) {
+    groupStore.updateGroupMemberStatus(groupId, myId.value, CommonStatusEnum.DISABLE)
+  }
+  conversationStore.removeConversation(ImConversationType.GROUP, groupId)
+  groupStore.removeGroup(groupId)
+  ElMessage.success('已退出群聊')
+  visible.value = false
+}
+
+/** 解散群聊（仅群主入口） */
+async function handleDissolve() {
+  if (!props.group) {
+    return
+  }
+  try {
+    await confirm('解散后所有成员将被移出，且无法恢复，确认解散吗？', '确认解散')
+  } catch {
+    return
+  }
+  const groupId = props.group.id
+  await dissolveGroup(groupId)
+  conversationStore.removeConversation(ImConversationType.GROUP, groupId)
+  groupStore.removeGroup(groupId)
+  ElMessage.success('群聊已解散')
+  visible.value = false
+}
+
+// ==================== 群主操作 ====================
+// 移除群成员（群主 / 管理员可见）+ 设置群管理员（仅群主）+ 群主管理权转让（仅群主）
+
+const removeDialogRef = ref<InstanceType<typeof GroupMemberRemoveDialog>>() // 移除群成员弹窗 ref
+const adminSetDialogRef = ref<InstanceType<typeof GroupAdminSetDialog>>() // 设置群管理员弹窗 ref
+const ownerTransferDialogRef = ref<InstanceType<typeof GroupOwnerTransferDialog>>() // 转让群主弹窗 ref
+
+// ---------- 移除群成员 ----------
+
+/** 打开移除群成员弹窗：始终隐藏群主；管理员视角额外隐藏其它管理员（管理员不能移出管理员） */
+function handleOpenRemove() {
+  if (!props.group?.id) {
+    return
+  }
+  const hideIds: number[] = []
+  if (props.group.ownerId) {
+    hideIds.push(props.group.ownerId)
+  }
+  if (myRole.value === ImGroupMemberRole.ADMIN) {
+    props.members
+      .filter((m) => m.role === ImGroupMemberRole.ADMIN)
+      .forEach((m) => hideIds.push(m.userId))
+  }
+  removeDialogRef.value?.open({
+    groupId: props.group.id,
+    members: props.members,
+    hideIds
+  })
+}
+
+// ---------- 设置群管理员 ----------
+
+/** 打开设置群管理员弹窗：当前管理员默认勾选；群主从候选里隐藏 */
+function handleOpenAdminSet() {
+  if (!props.group?.id) {
+    return
+  }
+  // 过滤已退群成员，避免 maxSize 名额被隐藏成员占用导致无法新增管理员
+  const currentAdminIds = props.members
+    .filter(
+      (member) =>
+        member.role === ImGroupMemberRole.ADMIN && member.status !== CommonStatusEnum.DISABLE
+    )
+    .map((member) => member.userId)
+  const hideIds = props.group.ownerId ? [props.group.ownerId] : []
+  adminSetDialogRef.value?.open({
+    groupId: props.group.id,
+    members: props.members,
+    currentAdminIds,
+    hideIds
+  })
+}
+
+// ---------- 群主管理权转让 ----------
+
+/** 打开转让群主弹窗：当前用户从候选里隐藏（不能转给自己） */
+function handleOpenTransferOwner() {
+  if (!props.group?.id) {
+    return
+  }
+  ownerTransferDialogRef.value?.open({
+    groupId: props.group.id,
+    members: props.members,
+    hideIds: [myId.value]
+  })
+}
+</script>
+
+<template>
+  <!-- 聊天面板右侧群信息抽屉：成员宫格 + 群信息 + 开关 + 退出群聊，整体对齐微信 PC -->
+  <ElDrawer
+    v-model="visible"
+    body-class="!p-0"
+    :closable="false"
+    modal-class="im-conversation-group-side__modal"
+    placement="right"
+    width="380px"
+  >
+    <div v-if="group" class="flex flex-col h-full bg-[var(--ant-color-bg-container)]">
+      <!-- 上部：可滚动内容区 -->
+      <div class="flex-1 overflow-y-auto bg-[var(--im-conversation-side-bg)]">
+        <!-- ==================== 群成员区 ==================== -->
+        <div class="px-4 pt-4 pb-[10px] bg-[var(--ant-color-bg-container)]">
+          <ElInput v-model="searchText" placeholder="搜索群成员" clearable>
+            <template #prefix>
+              <Icon
+                icon="ant-design:search-outlined"
+                class="text-[var(--ant-color-text-placeholder)]"
+              />
+            </template>
+          </ElInput>
+
+          <div class="flex flex-wrap gap-x-1 gap-y-[14px] mt-[14px]">
+            <GroupMemberGrid
+              v-for="member in displayMembers"
+              :key="member.userId"
+              :member="member"
+              :size="50"
+              clickable
+              :group-name="group.name"
+            />
+
+            <!-- 添加（任何成员都能邀请；历史退群群隐藏） -->
+            <div
+              v-if="!isQuitGroup"
+              class="im-conversation-group-side__tile-wrap flex flex-col items-center w-[66px] cursor-pointer"
+              content="邀请好友入群"
+              @click="handleOpenInvite"
+            >
+              <div class="im-conversation-group-side__icon-tile flex items-center justify-center w-[50px] h-[50px] text-20px text-[var(--ant-color-text)] bg-[var(--ant-color-fill-tertiary)] border border-dashed border-[var(--ant-color-border)] rounded-md transition-colors duration-200">
+                <Icon icon="ant-design:plus-outlined" />
+              </div>
+              <div class="mt-1.5 text-12px leading-[1.5] text-[var(--ant-color-text)] text-center">添加</div>
+            </div>
+
+            <!-- 移出（群主或管理员；管理员只能移出普通成员，由后端校验） -->
+            <div
+              v-if="isOwnerOrAdmin"
+              class="im-conversation-group-side__tile-wrap flex flex-col items-center w-[66px] cursor-pointer"
+              content="移出群成员"
+              @click="handleOpenRemove"
+            >
+              <div class="im-conversation-group-side__icon-tile flex items-center justify-center w-[50px] h-[50px] text-20px text-[var(--ant-color-text)] bg-[var(--ant-color-fill-tertiary)] border border-dashed border-[var(--ant-color-border)] rounded-md transition-colors duration-200">
+                <Icon icon="ant-design:minus-outlined" />
+              </div>
+              <div class="mt-1.5 text-12px leading-[1.5] text-[var(--ant-color-text)] text-center">移出</div>
+            </div>
+          </div>
+
+          <!-- 大群折叠：默认只展示前 N 个，点 "查看更多" 全展开（搜索时不折叠） -->
+          <div
+            v-if="moreMembersHidden"
+            class="flex items-center justify-center gap-1 mt-[10px] pt-1.5 pb-0.5 text-12px text-[var(--ant-color-text-secondary)] cursor-pointer transition-colors duration-150 hover:text-[var(--ant-color-primary)]"
+            @click="showAllMembers = true"
+          >
+            查看更多
+            <Icon icon="ant-design:down-outlined" :size="10" />
+          </div>
+        </div>
+
+        <div class="flex-shrink-0 h-[10px]"></div>
+
+        <!-- ==================== 群信息 ==================== -->
+        <!-- label 在上、value 在下，纵向堆叠（对齐微信 PC 设计）；只有 "群公告" 因为内容长加 > chevron -->
+        <div class="bg-[var(--ant-color-bg-container)]">
+          <!-- 群聊名称（群主可改） -->
+          <ElPopover
+            v-if="isOwner"
+            v-model="namePopoverVisible"
+            trigger="click"
+            placement="left-start"
+            :width="280"
+          >
+            <template #reference>
+              <div
+                class="im-conversation-group-side__row flex flex-col items-stretch gap-1.5 px-4 py-[14px] text-14px min-h-6 cursor-pointer transition-colors duration-150 hover:bg-[var(--ant-color-fill-tertiary)]"
+              >
+                <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">群聊名称</span>
+                <span class="text-13px text-[var(--ant-color-text)] break-all leading-[1.6] truncate">{{ group.name }}</span>
+              </div>
+            </template>
+            <div class="flex flex-col gap-2">
+              <ElInput v-model="editName" :maxlength="20" placeholder="请输入群聊名称" />
+              <div class="flex justify-end gap-2">
+                <ElButton size="small" @click="namePopoverVisible = false">取消</ElButton>
+                <ElButton size="small" type="primary" @click="saveName">保存</ElButton>
+              </div>
+            </div>
+          </ElPopover>
+          <div
+            v-else
+            class="im-conversation-group-side__row flex flex-col items-stretch gap-1.5 px-4 py-[14px] text-14px min-h-6 transition-colors duration-150"
+          >
+            <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">群聊名称</span>
+            <span class="text-13px text-[var(--ant-color-text)] break-all leading-[1.6] truncate">{{ group.name }}</span>
+          </div>
+
+          <!-- 群公告（群主可改）：内容可能很长，加 > chevron 表示可展开编辑 -->
+          <ElPopover
+            v-if="isOwner"
+            v-model="noticePopoverVisible"
+            trigger="click"
+            placement="left-start"
+            :width="320"
+          >
+            <template #reference>
+              <div
+                class="im-conversation-group-side__row flex flex-col items-stretch gap-1.5 px-4 py-[14px] text-14px min-h-6 cursor-pointer transition-colors duration-150 hover:bg-[var(--ant-color-fill-tertiary)]"
+              >
+                <div class="flex items-center justify-between gap-2">
+                  <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">群公告</span>
+                  <Icon
+                    icon="ant-design:right-outlined"
+                    :size="11"
+                    class="text-[var(--ant-color-text-placeholder)]"
+                  />
+                </div>
+                <span
+                  v-if="group.notice"
+                  class="text-13px text-[var(--ant-color-text)] break-all leading-[1.6] line-clamp-2"
+                >
+                  {{ group.notice }}
+                </span>
+                <span v-else class="text-13px text-[var(--ant-color-text-placeholder)] leading-[1.6]">未设置</span>
+              </div>
+            </template>
+            <div class="flex flex-col gap-2">
+              <ElInput
+                v-model="editNotice"
+                type="textarea"
+                :rows="4"
+                :maxlength="1024"
+                show-count
+                placeholder="请输入群公告"
+              />
+              <div class="flex justify-end gap-2">
+                <ElButton size="small" @click="noticePopoverVisible = false">取消</ElButton>
+                <ElButton size="small" type="primary" @click="saveNotice">保存</ElButton>
+              </div>
+            </div>
+          </ElPopover>
+          <div
+            v-else
+            class="im-conversation-group-side__row flex flex-col items-stretch gap-1.5 px-4 py-[14px] text-14px min-h-6 transition-colors duration-150"
+          >
+            <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">群公告</span>
+            <span
+              v-if="group.notice"
+              class="text-13px text-[var(--ant-color-text)] break-all leading-[1.6] line-clamp-2"
+            >
+              {{ group.notice }}
+            </span>
+            <span v-else class="text-13px text-[var(--ant-color-text-placeholder)] leading-[1.6]">未设置</span>
+          </div>
+
+          <!-- 备注（仅自己可见；保存后会替换会话列表 / 顶部群名展示）；历史退群群隐藏：改备注走 updateGroupMember，已退群会被后端拒 -->
+          <ElPopover
+            v-if="!isQuitGroup"
+            v-model="groupRemarkPopoverVisible"
+            trigger="click"
+            placement="left-start"
+            :width="280"
+          >
+            <template #reference>
+              <div
+                class="im-conversation-group-side__row flex flex-col items-stretch gap-1.5 px-4 py-[14px] text-14px min-h-6 cursor-pointer transition-colors duration-150 hover:bg-[var(--ant-color-fill-tertiary)]"
+              >
+                <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">备注</span>
+                <span
+                  v-if="group.groupRemark"
+                  class="text-13px text-[var(--ant-color-text)] break-all leading-[1.6] line-clamp-2"
+                >
+                  {{ group.groupRemark }}
+                </span>
+                <span v-else class="text-13px text-[var(--ant-color-text-placeholder)] leading-[1.6]">
+                  群聊的备注仅自己可见
+                </span>
+              </div>
+            </template>
+            <div class="flex flex-col gap-2">
+              <ElInput
+                v-model="editGroupRemark"
+                type="textarea"
+                :rows="3"
+                :maxlength="64"
+                show-count
+                placeholder="仅自己可见"
+              />
+              <div class="flex justify-end gap-2">
+                <ElButton size="small" @click="groupRemarkPopoverVisible = false">取消</ElButton>
+                <ElButton size="small" type="primary" @click="saveGroupRemark">保存</ElButton>
+              </div>
+            </div>
+          </ElPopover>
+
+          <!-- 我在本群的昵称（任何成员都能改自己的）；历史退群群隐藏：走 updateGroupMember，已退群会被后端拒 -->
+          <ElPopover
+            v-if="!isQuitGroup"
+            v-model="remarkPopoverVisible"
+            trigger="click"
+            placement="left-start"
+            :width="280"
+          >
+            <template #reference>
+              <div
+                class="im-conversation-group-side__row flex flex-col items-stretch gap-1.5 px-4 py-[14px] text-14px min-h-6 cursor-pointer transition-colors duration-150 hover:bg-[var(--ant-color-fill-tertiary)]"
+              >
+                <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">我在本群的昵称</span>
+                <span
+                  v-if="group.remarkNickName"
+                  class="text-13px text-[var(--ant-color-text)] break-all leading-[1.6] truncate"
+                >
+                  {{ group.remarkNickName }}
+                </span>
+                <span v-else class="text-13px text-[var(--ant-color-text-placeholder)] leading-[1.6]">点击设置</span>
+              </div>
+            </template>
+            <div class="flex flex-col gap-2">
+              <ElInput v-model="editRemark" :maxlength="20" placeholder="请输入本群昵称" />
+              <div class="flex justify-end gap-2">
+                <ElButton size="small" @click="remarkPopoverVisible = false">取消</ElButton>
+                <ElButton size="small" type="primary" @click="saveRemark">保存</ElButton>
+              </div>
+            </div>
+          </ElPopover>
+        </div>
+
+        <div class="flex-shrink-0 h-[10px]"></div>
+
+        <!-- ==================== 查找聊天内容 ==================== -->
+        <!-- 点击 → 父组件打开 MessageHistory 弹窗 -->
+
+        <div class="flex-shrink-0 h-[10px]"></div>
+
+        <div class="bg-[var(--ant-color-bg-container)]">
+          <div
+            class="im-conversation-group-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 cursor-pointer transition-colors duration-150 hover:bg-[var(--ant-color-fill-tertiary)]"
+            @click="emit('openHistory')"
+          >
+            <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">查找聊天内容</span>
+            <Icon
+              icon="ant-design:right-outlined"
+              :size="11"
+              class="text-[var(--ant-color-text-placeholder)]"
+            />
+          </div>
+          <!-- 分享群名片：弹 RecommendCardDialog，把当前群作为名片消息推荐给其他会话 -->
+          <div
+            v-if="group"
+            class="im-conversation-group-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 cursor-pointer transition-colors duration-150 hover:bg-[var(--ant-color-fill-tertiary)]"
+            @click="handleShareGroupCard"
+          >
+            <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">分享群名片</span>
+            <Icon
+              icon="ant-design:right-outlined"
+              :size="11"
+              class="text-[var(--ant-color-text-placeholder)]"
+            />
+          </div>
+        </div>
+
+        <div class="flex-shrink-0 h-[10px]"></div>
+
+        <!-- ==================== 开关项 ==================== -->
+        <div class="bg-[var(--ant-color-bg-container)]">
+          <div class="im-conversation-group-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 transition-colors duration-150">
+            <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">消息免打扰</span>
+            <ElSwitch :checked="!!conversation?.silent" @change="onMutedChange" />
+          </div>
+          <div class="im-conversation-group-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 transition-colors duration-150">
+            <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">置顶聊天</span>
+            <ElSwitch :checked="!!conversation?.top" @change="onTopChange" />
+          </div>
+          <!-- 全群禁言：仅群主或管理员可操作 -->
+          <div v-if="isOwnerOrAdmin" class="im-conversation-group-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 transition-colors duration-150">
+            <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">全群禁言</span>
+            <ElSwitch :checked="!!currentMutedAll" @change="onMuteAllChange" />
+          </div>
+        </div>
+
+        <!-- ==================== 进群审批 ==================== -->
+        <!-- 单独一段：群主开关 + 紧跟「- 进群申请」子项；与微信群管理布局对齐 -->
+        <template v-if="isOwner || (isOwnerOrAdmin && !!group.joinApproval)">
+          <div class="flex-shrink-0 h-[10px]"></div>
+          <div class="bg-[var(--ant-color-bg-container)]">
+            <!-- 进群审批：仅群主可操作；开启后普通成员的「申请」「邀请」路径都需群主 / 管理员同意；群主 / 管理员邀请直进 -->
+            <div v-if="isOwner" class="im-conversation-group-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 transition-colors duration-150">
+              <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">进群需要群主 / 群管理确认</span>
+              <ElSwitch :checked="!!group.joinApproval" @change="handleJoinApprovalChange" />
+            </div>
+            <!-- 进群申请子项：仅当开启审批 + 当前用户是 owner / admin 时出现；点击进列表 dialog -->
+            <div
+              v-if="isOwnerOrAdmin && !!group.joinApproval"
+              class="im-conversation-group-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 cursor-pointer transition-colors duration-150 hover:bg-[var(--ant-color-fill-tertiary)]"
+              @click="handleOpenRequestList"
+            >
+              <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">- 进群申请</span>
+              <Icon
+                icon="ant-design:right-outlined"
+                :size="11"
+                class="text-[var(--ant-color-text-placeholder)]"
+              />
+            </div>
+          </div>
+        </template>
+
+        <!-- ==================== 群主操作 ==================== -->
+        <!-- 仅群主可见，含管理员设置 + 群主管理权转让 -->
+        <template v-if="isOwner">
+          <div class="flex-shrink-0 h-[10px]"></div>
+          <div class="bg-[var(--ant-color-bg-container)]">
+            <div
+              class="im-conversation-group-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 cursor-pointer transition-colors duration-150 hover:bg-[var(--ant-color-fill-tertiary)]"
+              @click="handleOpenAdminSet"
+            >
+              <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">群管理员</span>
+              <Icon
+                icon="ant-design:right-outlined"
+                :size="11"
+                class="text-[var(--ant-color-text-placeholder)]"
+              />
+            </div>
+            <div
+              class="im-conversation-group-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 cursor-pointer transition-colors duration-150 hover:bg-[var(--ant-color-fill-tertiary)]"
+              @click="handleOpenTransferOwner"
+            >
+              <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">群主管理权转让</span>
+              <Icon
+                icon="ant-design:right-outlined"
+                :size="11"
+                class="text-[var(--ant-color-text-placeholder)]"
+              />
+            </div>
+          </div>
+        </template>
+      </div>
+
+      <!-- ==================== 底部：退出 / 解散群聊（历史退群群隐藏，已退群无需再退） ==================== -->
+      <div
+        v-if="!isQuitGroup"
+        class="flex-shrink-0 px-4 pt-[14px] pb-[18px] bg-[var(--ant-color-bg-container)] border-t border-t-solid border-[var(--im-border-color-lighter)]"
+      >
+        <!-- 群主：解散群聊 -->
+        <ElButton
+          v-if="isOwner"
+          class="w-full !h-9 text-14px"
+          type="danger"
+          @click="handleDissolve"
+        >
+          解散群聊
+        </ElButton>
+        <!-- 非群主：退出群聊 -->
+        <ElButton
+          v-else
+          class="w-full !h-9 text-14px"
+          type="danger"
+          @click="handleQuit"
+        >
+          退出群聊
+        </ElButton>
+      </div>
+    </div>
+
+    <!-- ==================== 子对话框 ==================== -->
+    <!-- 邀请新成员 / 选成员移除 -->
+    <GroupMemberAddDialog ref="inviteDialogRef" @reload="(ids) => $emit('reload', ids)" />
+    <GroupMemberRemoveDialog ref="removeDialogRef" @reload="$emit('reload')" />
+
+    <!-- 群主操作：管理员设置（一个弹窗合并增 / 删，提交时 diff）+ 群主管理权转让 -->
+    <GroupAdminSetDialog ref="adminSetDialogRef" @reload="$emit('reload')" />
+    <GroupOwnerTransferDialog ref="ownerTransferDialogRef" @reload="$emit('reload')" />
+
+    <!-- 进群申请列表（仅当开启审批 + 当前用户是 owner / admin 时入口可见） -->
+    <GroupRequestListDialog ref="requestListDialogRef" />
+
+    <!-- 分享群名片：把当前群作为名片消息推荐给其他会话 -->
+    <RecommendCardDialog ref="recommendCardDialogRef" />
+  </ElDrawer>
+</template>
+
+<style scoped>
+/* 「添加 / 移出」瓦片：hover 时联动内部 icon-tile 走主色，跨子元素的 hover 联动无法用单元素工具类表达 */
+.im-conversation-group-side__tile-wrap:hover .im-conversation-group-side__icon-tile {
+  color: var(--ant-color-primary);
+  border-color: var(--ant-color-primary);
+  background-color: var(--ant-color-primary-bg);
+}
+
+.im-conversation-group-side__modal {
+  --im-conversation-side-bg: #f5f7fa;
+}
+
+/* :deep 穿透 Icon 内部 svg； el-icon 全局 color 在暗色模式下被主题盖过，锁 fill 到当前色 */
+.im-conversation-group-side__icon-tile :deep(svg) {
+  fill: currentColor !important;
+}
+
+/* 相邻信息行加分隔线； 相邻兄弟选择器无法用工具类表达 */
+.im-conversation-group-side__row + .im-conversation-group-side__row {
+  border-top: 1px solid var(--im-border-color-lighter);
+}
+
+/* 整体放进 :global()，避免 Vue scoped 把 `:global(.dark) .xxx` 塌缩成裸 `.dark` 而把变量刷到 <html> */
+:global(.dark .im-conversation-group-side__modal) {
+  --im-conversation-side-bg: rgb(255 255 255 / 5%);
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/conversation-item.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/conversation-item.vue
new file mode 100644
index 000000000..ab905aff5
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/conversation-item.vue
@@ -0,0 +1,314 @@
+<script lang="ts" setup>
+import type { Conversation } from '../../../../types'
+
+import { computed } from 'vue'
+
+import { confirm } from '@vben/common-ui'
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElTag } from 'element-plus'
+
+import { buildRecallTip } from '#/views/im/utils/conversation'
+import { formatConversationTime } from '#/views/im/utils/time'
+import { getSenderDisplayName } from '#/views/im/utils/user'
+
+import { ImContentType, ImConversationType, isNormalMessage } from '../../../../../utils/constants'
+import { GroupAvatar } from '../../../../components/group'
+import { UserAvatar } from '../../../../components/user'
+import { useConversationStore } from '../../../../store/conversationStore'
+import { useFriendStore } from '../../../../store/friendStore'
+import { useGroupRequestStore } from '../../../../store/groupRequestStore'
+import { useGroupStore } from '../../../../store/groupStore'
+import { useImUiStore } from '../../../../store/uiStore'
+
+defineOptions({ name: 'ImConversationItem' })
+
+// 周中文名（dayjs 的 day() 返回 0-6，0=周日）；项目没全局装 dayjs/locale/zh-cn，本地映射避免引副作用
+const props = defineProps<{
+  conversation: Conversation
+}>()
+
+const conversationStore = useConversationStore()
+const friendStore = useFriendStore()
+const groupStore = useGroupStore()
+const groupRequestStore = useGroupRequestStore()
+const uiStore = useImUiStore()
+
+const isActive = computed(
+  () =>
+    conversationStore.activeConversation?.targetId === props.conversation.targetId &&
+    conversationStore.activeConversation?.type === props.conversation.type
+)
+
+/**
+ * 当前会话的草稿快照：存在时列表显示 [草稿] 前缀 + 文本，盖掉 sender 前缀和 @我 红字
+ * 当前打开的会话不展示草稿；输入内容已经在编辑器里可见，列表再显示 [草稿] 反而冗余
+ */
+const draft = computed(() => {
+  if (isActive.value) {
+    return undefined
+  }
+  return conversationStore.getConversationDraft(props.conversation)
+})
+
+const isGroup = computed(() => props.conversation.type === ImConversationType.GROUP)
+
+/** 最后一条消息发送者的展示名：实时算 + 快照 fallback（getSenderDisplayName 算不出时兜底） */
+const lastSenderDisplayName = computed(() => {
+  const senderId = props.conversation.lastSenderId
+  if (!senderId) {
+    return ''
+  }
+  return getSenderDisplayName(
+    senderId,
+    props.conversation.type,
+    props.conversation.targetId,
+    props.conversation.lastSenderDisplayName
+  )
+})
+
+/** 群聊 + 有最后发送者 + 最后一条是普通消息时，显示发送者前缀（FRIEND_* / GROUP_* / RECALL / 草稿态不带前缀） */
+const showSendName = computed(() => {
+  if (draft.value) {
+    return false
+  }
+  if (!isGroup.value) {
+    return false
+  }
+  if (!props.conversation.lastSenderId) {
+    return false
+  }
+  const lastType = props.conversation.lastMessageType
+  return lastType != null && isNormalMessage(lastType)
+})
+
+/** 列表展示文案：草稿优先（对齐微信 PC：有草稿时盖掉最后一条预览）→ 撤回实时算 → lastContent 兜底 */
+const lastContentDisplay = computed(() => {
+  if (draft.value) {
+    return draft.value.plain
+  }
+  if (
+    props.conversation.lastMessageType === ImContentType.RECALL &&
+    props.conversation.lastSenderId != null
+  ) {
+    return buildRecallTip(
+      props.conversation.lastSenderId,
+      !!props.conversation.lastSelfSend,
+      props.conversation.type,
+      props.conversation.targetId,
+      props.conversation.lastSenderDisplayName
+    )
+  }
+  return props.conversation.lastContent
+})
+
+/** 会话列表 "[草稿]" / "@ 我" / "@ 全体成员" 红字提示；草稿优先（对齐微信 PC） */
+const atText = computed(() => {
+  if (draft.value) {
+    return '[草稿]'
+  }
+  if (props.conversation.atMe) {
+    return '[有人@我]'
+  }
+  if (props.conversation.atAll) {
+    return '[@全体成员]'
+  }
+  return ''
+})
+
+/** 群聊未处理加群申请红字前缀；store 已经按「我管理的群」过滤过，count > 0 即可显示 */
+const requestText = computed(() => {
+  if (!isGroup.value) {
+    return ''
+  }
+  const count = groupRequestStore.getUnhandledGroupRequestCountMap.get(props.conversation.targetId) ?? 0
+  return count > 0 ? `[${count}条进群申请]` : ''
+})
+
+/** 点击切会话 */
+function handleClick() {
+  conversationStore.setActiveConversation(props.conversation)
+}
+
+/** 切换置顶 */
+function handleTop() {
+  conversationStore.setConversationTop(
+    props.conversation.type,
+    props.conversation.targetId,
+    !props.conversation.top
+  )
+}
+
+/** 切换免打扰：乐观 UI（先本地切换，菜单立即关；后端失败回滚 conversation 状态） */
+function handleMuted() {
+  const next = !props.conversation.silent
+  const { type, targetId } = props.conversation
+  conversationStore.setConversationSilent(type, targetId, next)
+  const sync =
+    type === ImConversationType.PRIVATE
+      ? friendStore.setFriendSilent(targetId, next)
+      : groupStore.setGroupSilent(targetId, next)
+  sync.catch((error) => {
+    console.error('[IM] 切换免打扰失败', error)
+    conversationStore.setConversationSilent(type, targetId, !next)
+  })
+}
+
+/** 删除会话：二次确认后软删 */
+async function handleDelete() {
+  try {
+    await confirm(`确定删除与「${props.conversation.name}」的会话吗？`, '删除会话')
+    conversationStore.removeConversation(props.conversation.type, props.conversation.targetId)
+  } catch {}
+}
+
+/** 右键菜单：置顶 / 免打扰 / 删除 */
+function handleContextMenu(e: MouseEvent) {
+  uiStore.openContextMenu(
+    { x: e.clientX, y: e.clientY },
+    [
+      { key: 'TOP', name: props.conversation.top ? '取消置顶' : '置顶' },
+      { key: 'MUTED', name: props.conversation.silent ? '允许消息通知' : '消息免打扰' },
+      { key: 'DELETE', name: '删除', divided: true, danger: true }
+    ],
+    (item) => {
+      switch (item.key) {
+      case 'DELETE': {
+        void handleDelete()
+
+      break;
+      }
+      case 'MUTED': {
+        handleMuted()
+
+      break;
+      }
+      case 'TOP': {
+        handleTop()
+
+      break;
+      }
+      // No default
+      }
+    }
+  )
+}
+
+</script>
+
+<template>
+  <div
+    class="relative flex items-center gap-2.5 px-4 py-3 cursor-pointer transition-colors hover:bg-[var(--ant-color-fill)]"
+    :class="{ '!bg-[#d9ecff] dark:!bg-[var(--ant-color-primary-bg-hover)]': isActive }"
+    :data-conversation-key="`${conversation.type}-${conversation.targetId}`"
+    @click="handleClick"
+    @contextmenu.prevent="handleContextMenu"
+  >
+    <!-- 头像 + 未读提示；普通会话显示红色数字徽标，免打扰会话仅显示纯小红点（对齐微信，不暴露具体条数） -->
+    <div class="relative">
+      <GroupAvatar
+        v-if="isGroup"
+        :group-id="conversation.targetId"
+        :url="conversation.avatar"
+        :name="conversation.name"
+        :size="40"
+      />
+      <UserAvatar
+        v-else
+        :url="conversation.avatar"
+        :name="conversation.name"
+        :size="40"
+        :clickable="false"
+      />
+      <!-- 数字徽标：非免打扰且有未读时显示具体条数 -->
+      <span
+        v-show="!conversation.silent && conversation.unreadCount > 0"
+        class="absolute -top-1.5 -right-1.5 min-w-[18px] h-[18px] px-1.5 text-11px leading-[18px] text-white text-center bg-[#f56c6c] border border-solid border-white dark:border-[var(--ant-color-bg-container)] rounded-full box-border whitespace-nowrap"
+      >
+        {{ conversation.unreadCount > 99 ? '99+' : conversation.unreadCount }}
+      </span>
+      <!-- 小红点：免打扰且有未读时仅提示存在新消息；切回非免打扰后用上面的数字徽标暴露累计未读 -->
+      <span
+        v-show="conversation.silent && conversation.unreadCount > 0"
+        class="absolute -top-1 -right-1 w-2.5 h-2.5 bg-[#f56c6c] border border-solid border-white dark:border-[var(--ant-color-bg-container)] rounded-full box-border"
+      ></span>
+    </div>
+
+    <div class="flex-1 min-w-0">
+      <div class="flex items-center justify-between">
+        <span class="flex flex-1 items-center gap-1 min-w-0">
+          <span class="overflow-hidden text-sm truncate text-[var(--ant-color-text)]">
+            {{ conversation.name }}
+          </span>
+          <ElTag
+            v-if="isGroup"
+            type="primary"
+            size="small"
+            class="conversation-item__tag flex-shrink-0 !h-[18px] !px-1 !leading-4"
+          >
+            群
+          </ElTag>
+        </span>
+        <span class="flex-shrink-0 ml-1 text-12px text-[var(--ant-color-text-secondary)]">
+          {{ formatConversationTime(conversation.lastSendTime) }}
+        </span>
+      </div>
+      <div class="flex items-center mt-1 leading-5">
+        <!-- 进群申请红字前缀：群主 / 管理员看到自己管理的群下还有未处理申请时显示 -->
+        <span
+          v-if="requestText"
+          class="conversation-item__prefix flex-shrink overflow-hidden text-12px text-[#c70b0b] truncate whitespace-nowrap"
+        >
+          {{ requestText }}
+        </span>
+        <!-- @红字提示：atMe 优先于 atAll -->
+        <span
+          v-if="atText"
+          class="conversation-item__prefix flex-shrink overflow-hidden text-12px text-[#c70b0b] truncate whitespace-nowrap"
+        >
+          {{ atText }}
+        </span>
+        <!-- 群聊最后一条发送者前缀：按 lastSenderId + 当前会话上下文实时算名字 -->
+        <span
+          v-if="showSendName"
+          class="conversation-item__sender flex-shrink overflow-hidden text-12px text-[var(--ant-color-text-secondary)] truncate whitespace-nowrap"
+        >
+          {{ lastSenderDisplayName }}:&nbsp;
+        </span>
+        <span
+          class="flex-1 min-w-0 overflow-hidden text-12px truncate text-[var(--ant-color-text-secondary)]"
+        >
+          {{ lastContentDisplay }}
+        </span>
+        <!-- 免打扰图标 -->
+        <Icon
+          v-if="conversation.silent"
+          icon="mdi:bell-off-outline"
+          :size="14"
+          class="conversation-item__silent flex-shrink-0 ml-1 text-[var(--ant-color-text-disabled)]"
+          content="消息免打扰"
+        />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* 消掉 el-tag 切会话时 active 底色变化的渐变（看起来像闪烁）； :deep 穿透 el-tag 自身样式 */
+.conversation-item__tag {
+  transition: none !important;
+}
+
+/* el-icon 的全局 color:var(--color) 在暗色模式下会渲染成白色，这里用 :deep + !important 锁定 */
+.conversation-item__silent :deep(svg) {
+  fill: currentColor !important;
+}
+
+.conversation-item__prefix {
+  max-width: 45%;
+}
+
+.conversation-item__sender {
+  max-width: 50%;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/conversation-private-side.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/conversation-private-side.vue
new file mode 100644
index 000000000..5c731442c
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/conversation-private-side.vue
@@ -0,0 +1,279 @@
+<script lang="ts" setup>
+import type { Conversation, Friend } from '../../../../types'
+
+import { computed, ref, watch } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElButton, ElDrawer, ElInput, ElMessage, ElPopover, ElSwitch } from 'element-plus'
+
+import { useConversationStore } from '#/views/im/home/store/conversationStore'
+import { useFriendStore } from '#/views/im/home/store/friendStore'
+import { useGroupStore } from '#/views/im/home/store/groupStore'
+import { ImConversationType } from '#/views/im/utils/constants'
+import { getFriendDisplayName, getGroupDisplayName } from '#/views/im/utils/user'
+
+import { GroupCreateDialog } from '../../../../components/group'
+import { UserAvatar } from '../../../../components/user'
+
+defineOptions({ name: 'ImConversationPrivateSide' })
+
+const props = withDefaults(
+  defineProps<{
+    conversation?: Conversation | null // 当前会话（取置顶 / 免打扰态）
+    friend?: Friend // 对方好友信息（取头像 / 昵称）
+    modelValue?: boolean // 抽屉开关（v-model）
+  }>(),
+  {
+    conversation: null,
+    friend: undefined,
+    modelValue: false
+  }
+)
+
+const emit = defineEmits<{
+  openHistory: [] // 点击 "查找聊天内容" 行 → 父组件打开 MessageHistory 弹窗
+  'update:modelValue': [value: boolean]
+}>()
+
+const visible = computed({
+  get: () => props.modelValue,
+  set: (value) => emit('update:modelValue', value)
+})
+
+const conversationStore = useConversationStore()
+const friendStore = useFriendStore()
+const groupStore = useGroupStore()
+
+/** tile 标签 / 后续聊天界面用的展示名：备注优先 */
+const displayName = computed(() => (props.friend ? getFriendDisplayName(props.friend) : ''))
+
+const createGroupDialogRef = ref<InstanceType<typeof GroupCreateDialog>>() // 发起群聊弹窗 ref：handleOpenCreateGroup 调 open({ lockedIds }) 锁定对方
+
+/** 打开发起群聊弹窗：把对方默认勾上且不可取消，对应微信"基于私聊发起群聊" */
+function handleOpenCreateGroup() {
+  const lockedIds = props.friend ? [props.friend.friendUserId] : []
+  createGroupDialogRef.value?.open({ lockedIds })
+}
+
+const displayNamePopoverVisible = ref(false)
+const editDisplayName = ref('')
+
+// popover 弹出时把当前备注灌进编辑态，避免上次未保存的脏值
+watch(displayNamePopoverVisible, (open) => {
+  if (open) {
+    editDisplayName.value = props.friend?.displayName || ''
+  }
+})
+
+// 抽屉关闭时把还没收掉的 popover 一并清掉，避免下次打开闪一下
+watch(visible, (open) => {
+  if (!open) {
+    displayNamePopoverVisible.value = false
+  }
+})
+
+/** 备注 popover 点击保存 */
+async function handleSaveDisplayName() {
+  if (!props.friend) {
+    return
+  }
+  await friendStore.setFriendDisplayName(props.friend.friendUserId, editDisplayName.value)
+  displayNamePopoverVisible.value = false
+  ElMessage.success('保存成功')
+}
+
+/**
+ * 切免打扰：乐观双写 conversationStore + friendStore；后端失败回滚 conversation 状态，保持与 ConversationItem.handleMuted 一致
+ */
+function handleMutedChange(value: boolean | number | string) {
+  if (!props.conversation) {
+    return
+  }
+  const next = !!value
+  const { type, targetId } = props.conversation
+  conversationStore.setConversationSilent(type, targetId, next)
+  if (type !== ImConversationType.PRIVATE) {
+    return
+  }
+  friendStore.setFriendSilent(targetId, next).catch((error) => {
+    console.error('[IM ConversationPrivateSide] 切换免打扰失败', { targetId }, error)
+    conversationStore.setConversationSilent(type, targetId, !next)
+  })
+}
+
+/** 切置顶：纯本地 conversationStore 排序态（无后端字段） */
+function handleTopChange(value: boolean | number | string) {
+  if (!props.conversation) {
+    return
+  }
+  conversationStore.setConversationTop(props.conversation.type, props.conversation.targetId, !!value)
+}
+
+/** 群创建成功：跳到新群会话 + 关掉本侧抽屉，让用户专注新群 */
+function handleGroupCreated(groupId: number) {
+  const group = groupStore.getGroup(groupId)
+  if (!group) {
+    return
+  }
+  conversationStore.openConversation(
+    groupId,
+    ImConversationType.GROUP,
+    getGroupDisplayName(group),
+    group.avatar || '',
+    { silent: !!group.silent }
+  )
+  visible.value = false
+}
+</script>
+
+<template>
+  <!--
+    私聊侧边抽屉
+    - 整体结构对齐 ConversationGroupSide：宫格 + 信息行 + 开关
+    - 顶部好友宫格 + "+" tile：点 + 调起 GroupCreateDialog 并锁定对方，对齐微信"基于私聊发起群聊"
+    - "清空聊天记录"按钮在 WeChat 里有，但目前后端没建消息清空能力，先不加避免做半吊子
+  -->
+  <ElDrawer
+    v-model="visible"
+    body-class="!p-0"
+    :closable="false"
+    modal-class="im-conversation-private-side__modal"
+    placement="right"
+    width="340px"
+  >
+    <!-- friend 缺失场景：陌生人会话刚打开 / 好友数据还没补拉到；空白会让用户以为抽屉坏了，给个加载占位 -->
+    <div
+      v-if="!friend"
+      class="flex flex-col items-center justify-center h-full text-13px text-[var(--ant-color-text-placeholder)] bg-[var(--ant-color-bg-container)]"
+    >
+      加载中...
+    </div>
+    <div v-else class="flex flex-col h-full bg-[var(--ant-color-bg-container)]">
+      <div class="flex-1 overflow-y-auto bg-[var(--ant-color-fill-secondary)]">
+        <!-- 好友宫格：原 tile + "+" tile，对齐 GroupSide 视觉，让两种抽屉看起来是一家的 -->
+        <div class="flex flex-wrap gap-1 px-4 pt-4 pb-[14px] bg-[var(--ant-color-bg-container)]">
+          <div class="flex flex-col items-center w-[66px]">
+            <UserAvatar
+              :id="friend.friendUserId"
+              :url="friend.avatar"
+              :name="friend.nickname"
+              :size="50"
+            />
+            <div class="w-full mt-1.5 overflow-hidden text-12px leading-[1.5] text-[var(--ant-color-text)] text-center truncate">
+              {{ displayName }}
+            </div>
+          </div>
+
+          <!-- + tile：点击调起 GroupCreateDialog，把对方 id 作为 lockedIds 传入 -->
+          <div
+            class="im-conversation-private-side__tile-wrap-clickable flex flex-col items-center w-[66px] cursor-pointer"
+            content="发起群聊"
+            @click="handleOpenCreateGroup"
+          >
+            <div class="im-conversation-private-side__icon-tile flex items-center justify-center w-[50px] h-[50px] text-20px text-[var(--ant-color-text)] bg-[var(--ant-color-fill-tertiary)] border border-dashed border-[var(--ant-color-border)] rounded-md transition-colors duration-200">
+              <Icon icon="ant-design:plus-outlined" />
+            </div>
+            <div class="w-full mt-1.5 overflow-hidden text-12px leading-[1.5] text-[var(--ant-color-text)] text-center truncate">添加</div>
+          </div>
+        </div>
+
+        <div class="flex-shrink-0 h-[10px]"></div>
+
+        <!-- 备注（仅自己可见）：点击弹 popover 编辑，保存后立即刷新本抽屉 + 会话列表展示名 -->
+        <div class="bg-[var(--ant-color-bg-container)]">
+          <ElPopover
+            v-model="displayNamePopoverVisible"
+            trigger="click"
+            placement="left-start"
+            :width="280"
+          >
+            <template #reference>
+              <div
+                class="im-conversation-private-side__row flex flex-col items-stretch gap-1.5 px-4 py-[14px] text-14px min-h-6 cursor-pointer transition-colors duration-150 hover:bg-[var(--ant-color-fill-tertiary)]"
+              >
+                <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">备注</span>
+                <span
+                  v-if="friend.displayName"
+                  class="text-13px leading-[1.6] text-[var(--ant-color-text)] break-all line-clamp-2"
+                >
+                  {{ friend.displayName }}
+                </span>
+                <span v-else class="text-13px leading-[1.6] text-[var(--ant-color-text-placeholder)]">
+                  好友备注仅自己可见
+                </span>
+              </div>
+            </template>
+            <div class="flex flex-col gap-2">
+              <ElInput
+                v-model="editDisplayName"
+                :maxlength="16"
+                show-count
+                placeholder="请输入备注名"
+              />
+              <div class="flex justify-end gap-2">
+                <ElButton size="small" @click="displayNamePopoverVisible = false">取消</ElButton>
+                <ElButton size="small" type="primary" @click="handleSaveDisplayName">
+                  保存
+                </ElButton>
+              </div>
+            </div>
+          </ElPopover>
+        </div>
+
+        <div class="flex-shrink-0 h-[10px]"></div>
+
+        <!-- 查找聊天内容 -->
+        <div class="bg-[var(--ant-color-bg-container)]">
+          <div
+            class="im-conversation-private-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 cursor-pointer transition-colors duration-150 hover:bg-[var(--ant-color-fill-tertiary)]"
+            @click="emit('openHistory')"
+          >
+            <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">查找聊天内容</span>
+            <Icon
+              icon="ant-design:right-outlined"
+              :size="11"
+              class="text-[var(--ant-color-text-placeholder)]"
+            />
+          </div>
+        </div>
+
+        <div class="flex-shrink-0 h-[10px]"></div>
+
+        <!-- 开关项 -->
+        <div class="bg-[var(--ant-color-bg-container)]">
+          <div class="im-conversation-private-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 transition-colors duration-150">
+            <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">消息免打扰</span>
+            <ElSwitch :checked="!!conversation?.silent" @change="handleMutedChange" />
+          </div>
+          <div class="im-conversation-private-side__row flex items-center justify-between gap-3 px-4 py-[13px] text-14px min-h-6 transition-colors duration-150">
+            <span class="flex-shrink-0 text-14px text-[var(--ant-color-text)]">置顶聊天</span>
+            <ElSwitch :checked="!!conversation?.top" @change="handleTopChange" />
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <!-- 子对话框：发起群聊（锁定对方为已选） -->
+    <GroupCreateDialog ref="createGroupDialogRef" @created="handleGroupCreated" />
+  </ElDrawer>
+</template>
+
+<style scoped>
+/* 「+」 tile： hover 时联动内部 icon-tile 走主色； 跨子元素的 hover 联动无法用单元素工具类表达 */
+.im-conversation-private-side__tile-wrap-clickable:hover .im-conversation-private-side__icon-tile {
+  color: var(--ant-color-primary);
+  border-color: var(--ant-color-primary);
+  background-color: var(--ant-color-primary-bg);
+}
+
+/* :deep 穿透 Icon 内部 svg； el-icon 全局 color 在暗色模式下被主题盖过，锁 fill 到当前色 */
+.im-conversation-private-side__icon-tile :deep(svg) {
+  fill: currentColor !important;
+}
+
+/* 相邻信息行加分隔线； 相邻兄弟选择器无法用工具类表达 */
+.im-conversation-private-side__row + .im-conversation-private-side__row {
+  border-top: 1px solid var(--ant-color-border-secondary);
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/index.ts b/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/index.ts
new file mode 100644
index 000000000..97c89acc1
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/conversation/index.ts
@@ -0,0 +1,3 @@
+export { default as ConversationGroupSide } from './conversation-group-side.vue';
+export { default as ConversationItem } from './conversation-item.vue';
+export { default as ConversationPrivateSide } from './conversation-private-side.vue';
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/index.ts b/apps/web-ele/src/views/im/home/pages/conversation/components/index.ts
new file mode 100644
index 000000000..9d4f6d45d
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/index.ts
@@ -0,0 +1,3 @@
+export * from './conversation';
+export * from './input';
+export * from './message';
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/input/face-picker.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/input/face-picker.vue
new file mode 100644
index 000000000..0890f7d49
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/input/face-picker.vue
@@ -0,0 +1,353 @@
+<script lang="ts" setup>
+import type { ImFacePackApi } from '#/api/im/face/pack'
+import type { ImFaceUserItemApi } from '#/api/im/face/useritem'
+
+import { computed, onUnmounted, ref, useTemplateRef, watch } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElMessage, ElTooltip } from 'element-plus'
+
+import { uploadFile } from '#/api/infra/file'
+import { useFaceStore } from '#/views/im/home/store/faceStore'
+import { IM_EMOJI_LIST } from '#/views/im/utils/emoji'
+import { probeImageSize } from '#/views/im/utils/image'
+
+defineOptions({ name: 'ImFacePicker' })
+
+const props = withDefaults(
+  defineProps<{
+    /** full：emoji + 个人表情 + 系统包（聊天主输入用）；emoji：仅 emoji（留言 / 评论场景） */
+    mode?: FacePickerMode
+    visible: boolean
+  }>(),
+  { mode: 'full' }
+)
+
+const emit = defineEmits<{
+  /** 选中 Unicode emoji（如 😀），调用方应插入到输入框走 TEXT 通道 */
+  selectEmoji: [emoji: string]
+  /** 选中表情贴图，调用方应走 FACE 消息发送 */
+  selectFace: [face: { height: number; name?: string; url: string; width: number; }]
+  'update:visible': [value: boolean]
+}>()
+
+/** 面板模式 */
+type FacePickerMode = 'emoji' | 'full'
+
+const rootRef = useTemplateRef<HTMLDivElement>('rootRef')
+const uploadInputRef = useTemplateRef<HTMLInputElement>('uploadInputRef')
+
+const faceStore = useFaceStore()
+
+// tab 标识常量；pack:N 类用 packTabKey() 拼出，避免散落字符串字面量
+const FACE_TAB = {
+  EMOJI: 'emoji',
+  MINE: 'mine'
+} as const
+const packTabKey = (packId: number) => `pack:${packId}`
+
+const activeTab = ref<string>(FACE_TAB.EMOJI) // 当前激活的 tab
+
+/** 是否完整模式（含个人 / 系统包 tab） */
+const isFullMode = computed(() => props.mode === 'full')
+
+const uploading = ref(false) // 上传中标记，避免连续点击触发并发上传
+
+/** 选 emoji 字符：插到输入框；选完不关面板，方便用户连发多个 */
+function handleSelectEmoji(emoji: string) {
+  emit('selectEmoji', emoji)
+}
+
+/** 选个人表情：直接发；点完关面板，对齐微信 */
+function handleSelectFaceUserItem(item: ImFaceUserItemApi.FaceUserItem) {
+  emit('selectFace', { url: item.url, width: item.width, height: item.height, name: item.name })
+  emit('update:visible', false)
+}
+
+/** 选系统表情包内表情：直接发；点完关面板 */
+function handleSelectPackItem(item: ImFacePackApi.FacePackUserItem) {
+  emit('selectFace', { url: item.url, width: item.width, height: item.height, name: item.name })
+  emit('update:visible', false)
+}
+
+/** 长按 / 右键删除个人表情 */
+async function handleDeleteUserItem(item: ImFaceUserItemApi.FaceUserItem) {
+  if (!confirm('确认删除该表情？')) {
+    return
+  }
+  await faceStore.removeFaceUserItem(item.id)
+}
+
+/** 点 + 触发文件选择 */
+function onUploadClick() {
+  uploadInputRef.value?.click()
+}
+
+/** 文件选完即上传，成功后写入 faceStore 个人表情列表 */
+async function onUploadPicked(e: Event) {
+  const input = e.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (!file) {
+    return
+  }
+  uploading.value = true
+  let size: { height: number; width: number; }
+  try {
+    size = await probeImageSize(file)
+  } catch (error) {
+    console.warn('[IM] 解析个人表情失败', error)
+    ElMessage.error('图片解析失败')
+    uploading.value = false
+    return
+  }
+
+  try {
+    const url = await uploadFile({ file })
+    if (!url) {
+      ElMessage.error('上传失败')
+      return
+    }
+    const payload = { url, width: size.width, height: size.height }
+    await faceStore.addFaceUserItem(payload)
+  } finally {
+    uploading.value = false
+  }
+}
+
+/** 面板展开时拉数据 + 挂全局 click；mode='emoji' 时不拉系统包 / 个人表情 */
+watch(
+  () => props.visible,
+  (visible) => {
+    if (visible) {
+      document.addEventListener('click', handleDocumentClick)
+      if (isFullMode.value) {
+        // 系统包通常已被 home onMounted 预拉过；ensureXxx 内部 promise 缓存避免重复请求
+        void faceStore.ensureFacePackList()
+        void faceStore.ensureFaceUserItemList()
+      }
+    } else {
+      document.removeEventListener('click', handleDocumentClick)
+    }
+  },
+  { immediate: true }
+)
+
+/** 点击面板外部关闭 */
+function handleDocumentClick(e: MouseEvent) {
+  if (!props.visible || !rootRef.value) {
+    return
+  }
+  if (!rootRef.value.contains(e.target as Node)) {
+    emit('update:visible', false)
+  }
+}
+
+onUnmounted(() => {
+  document.removeEventListener('click', handleDocumentClick)
+})
+</script>
+
+<template>
+  <!--
+    表情面板（多 tab）：emoji / 个人表情 / N 个系统表情包
+    - 对齐微信 PC：底部 tab 栏切换面板内容；emoji 保持 Unicode（仍由 TEXT 通道发送）
+    - 个人表情 / 系统表情走 FACE 内容类型，通过 selectFace 事件由调用方走 sendRaw 发送
+    - mode='emoji' 时只显示 emoji tab + 隐藏底部 tab 栏，给留言 / 评论这类只发文本的场景用
+    - 定位由调用方决定（通常浮在表情按钮上方）
+  -->
+  <div
+    v-if="visible"
+    ref="rootRef"
+    class="im-popover-arrow absolute z-100 flex flex-col w-[380px] rounded-md bg-[var(--ant-color-bg-container)] shadow-[0_4px_16px_rgba(0,0,0,0.12)]"
+    @click.stop
+  >
+    <!-- 主内容区：高度固定 + 各 tab 用 v-show 切换，避免每次切 tab 重建 scrollbar 造成滚动位置丢失 -->
+    <div class="relative h-[300px] overflow-hidden">
+      <!-- emoji 网格 -->
+      <div v-show="activeTab === FACE_TAB.EMOJI" style="height: 300px; overflow-y: auto">
+        <div class="grid grid-cols-10 gap-0.5 p-2">
+          <button
+            v-for="emoji in IM_EMOJI_LIST"
+            :key="emoji"
+            class="p-1 text-xl leading-none bg-transparent border-none rounded cursor-pointer transition-colors hover:bg-[var(--ant-color-fill)]"
+            type="button"
+            @click="handleSelectEmoji(emoji)"
+          >
+            {{ emoji }}
+          </button>
+        </div>
+      </div>
+
+      <!-- 个人表情：5 列方格，无名字标签；末尾「+」上传 -->
+      <div v-if="isFullMode" v-show="activeTab === FACE_TAB.MINE" style="height: 300px; overflow-y: auto">
+        <div class="grid grid-cols-5 gap-2 p-3">
+          <!-- 上传入口固定放第一格；dashed border 与表情格子区分视觉语义，对齐 el-upload 观感 -->
+          <button
+            class="aspect-square flex items-center justify-center rounded-md cursor-pointer transition-colors border border-dashed border-[var(--ant-color-border)] bg-transparent text-[var(--ant-color-text-placeholder)] hover:border-[var(--ant-color-primary)] hover:text-[var(--ant-color-primary)] disabled:cursor-not-allowed disabled:text-[var(--ant-color-text-disabled)]"
+            type="button"
+            :disabled="uploading"
+            :content="uploading ? '上传中…' : '上传图片到个人表情'"
+            @click="onUploadClick"
+          >
+            <Icon
+              :icon="uploading ? 'eos-icons:bubble-loading' : 'ant-design:plus-outlined'"
+              :size="22"
+            />
+          </button>
+          <div
+            v-for="item in faceStore.faceUserItems"
+            :key="item.id"
+            class="im-face-grid-cell group relative aspect-square flex items-center justify-center rounded-md bg-[var(--ant-color-fill-tertiary)] cursor-pointer transition-colors hover:bg-[var(--ant-color-fill)]"
+            :content="item.name || '点击发送 / 右键删除'"
+            @click="handleSelectFaceUserItem(item)"
+            @contextmenu.prevent="handleDeleteUserItem(item)"
+          >
+            <img
+              :src="item.url"
+              :alt="item.name || '表情'"
+              class="max-w-full max-h-full object-contain"
+              draggable="false"
+            />
+          </div>
+          <div
+            v-if="faceStore.faceUserItems.length === 0"
+            class="col-span-5 flex items-center justify-center py-12 text-sm text-[var(--ant-color-text-placeholder)]"
+          >
+            还没有个人表情，点 + 上传 / 在聊天里长按消息添加
+          </div>
+        </div>
+      </div>
+
+      <!-- 系统表情包：5 列方格 + 下方表情名（无 name 时不显示标签，保持高度一致） -->
+      <template v-if="isFullMode">
+        <div
+          v-for="pack in faceStore.facePacks"
+          v-show="activeTab === packTabKey(pack.id)"
+          :key="pack.id"
+          style="height: 300px; overflow-y: auto"
+        >
+          <div class="grid grid-cols-5 gap-2 p-3">
+            <div
+              v-for="item in pack.items"
+              :key="item.id"
+              class="im-face-grid-cell flex flex-col items-center gap-1 cursor-pointer rounded-md p-1 transition-colors hover:bg-[var(--ant-color-fill)]"
+              :content="item.name || ''"
+              @click="handleSelectPackItem(item)"
+            >
+              <div
+                class="aspect-square w-full flex items-center justify-center bg-[var(--ant-color-fill-tertiary)] rounded"
+              >
+                <img
+                  :src="item.url"
+                  :alt="item.name || '表情'"
+                  class="max-w-full max-h-full object-contain"
+                  draggable="false"
+                />
+              </div>
+              <div
+                class="h-4 text-xs text-[var(--ant-color-text-secondary)] truncate w-full text-center leading-4"
+              >
+                {{ item.name || '' }}
+              </div>
+            </div>
+            <div
+              v-if="pack.items.length === 0"
+              class="col-span-5 flex items-center justify-center py-12 text-sm text-[var(--ant-color-text-placeholder)]"
+            >
+              该表情包暂无表情
+            </div>
+          </div>
+        </div>
+      </template>
+    </div>
+
+    <!-- 底部 tab 栏：[ emoji / 个人 / 系统包 1..N ]；mode='emoji' 时隐藏 -->
+    <div
+      v-if="isFullMode"
+      class="flex flex-shrink-0 items-center gap-1 px-2 py-1.5 border-t border-t-solid border-[var(--ant-color-border-secondary)]"
+    >
+      <ElTooltip content="Emoji 表情" placement="top" :show-after="300">
+        <button
+          class="inline-flex items-center justify-center w-[30px] h-[30px] border-none rounded bg-transparent cursor-pointer transition-colors hover:bg-[var(--ant-color-fill)]"
+          :class="
+            activeTab === FACE_TAB.EMOJI
+              ? 'bg-[var(--ant-color-fill)] text-[var(--ant-color-primary)]'
+              : 'text-[var(--ant-color-text)]'
+          "
+          type="button"
+          @click="activeTab = FACE_TAB.EMOJI"
+        >
+          <Icon icon="ant-design:smile-outlined" :size="18" />
+        </button>
+      </ElTooltip>
+      <ElTooltip content="个人表情" placement="top" :show-after="300">
+        <button
+          class="inline-flex items-center justify-center w-[30px] h-[30px] border-none rounded bg-transparent cursor-pointer transition-colors hover:bg-[var(--ant-color-fill)]"
+          :class="
+            activeTab === FACE_TAB.MINE
+              ? 'bg-[var(--ant-color-fill)] text-[var(--ant-color-primary)]'
+              : 'text-[var(--ant-color-text)]'
+          "
+          type="button"
+          @click="activeTab = FACE_TAB.MINE"
+        >
+          <Icon icon="ant-design:heart-outlined" :size="18" />
+        </button>
+      </ElTooltip>
+      <ElTooltip
+        v-for="pack in faceStore.facePacks"
+        :key="pack.id"
+        :content="pack.name"
+        placement="top"
+        :show-after="300"
+      >
+        <button
+          class="inline-flex items-center justify-center w-[30px] h-[30px] border-none rounded bg-transparent cursor-pointer transition-colors hover:bg-[var(--ant-color-fill)]"
+          :class="
+            activeTab === packTabKey(pack.id)
+              ? 'bg-[var(--ant-color-fill)] text-[var(--ant-color-primary)]'
+              : 'text-[var(--ant-color-text)]'
+          "
+          type="button"
+          @click="activeTab = packTabKey(pack.id)"
+        >
+          <img
+            v-if="pack.icon"
+            :src="pack.icon"
+            :alt="pack.name"
+            class="w-[18px] h-[18px] object-contain"
+            draggable="false"
+          />
+          <Icon v-else icon="ant-design:appstore-outlined" :size="18" />
+        </button>
+      </ElTooltip>
+    </div>
+
+    <!-- 隐藏的文件选择器（点 + 时触发） -->
+    <input
+      v-if="isFullMode"
+      ref="uploadInputRef"
+      type="file"
+      accept="image/*"
+      hidden
+      @change="onUploadPicked"
+    />
+  </div>
+</template>
+
+<style scoped>
+/* 底部小三角：指向触发图标，仿微信 PC 气泡指针；left 偏移对应表情按钮（工具栏 1st icon） */
+.im-popover-arrow::after {
+  content: '';
+  position: absolute;
+  top: calc(100% - 1px);
+  left: 10px;
+  border-style: solid;
+  border-width: 6px 6px 0 6px;
+  border-color: var(--ant-color-bg-container) transparent transparent transparent;
+  filter: drop-shadow(0 2px 2px rgba(0, 0, 0, 0.08));
+}
+
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/input/index.ts b/apps/web-ele/src/views/im/home/pages/conversation/components/input/index.ts
new file mode 100644
index 000000000..f48ba3700
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/input/index.ts
@@ -0,0 +1,5 @@
+export { default as FacePicker } from './face-picker.vue';
+export { default as MentionPicker } from './mention-picker.vue';
+export { default as MessageInput } from './message-input.vue';
+export { default as MessageMultiSelectBar } from './message-multi-select-bar.vue';
+export { default as VoiceRecorder } from './voice-recorder.vue';
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/input/mention-picker.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/input/mention-picker.vue
new file mode 100644
index 000000000..760f96991
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/input/mention-picker.vue
@@ -0,0 +1,207 @@
+<script lang="ts" setup>
+import { computed, ref, useTemplateRef, watch } from 'vue'
+
+import { CommonStatusEnum } from '@vben/constants'
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+import { IM_AT_ALL_NICKNAME, IM_AT_ALL_USER_ID } from '#/views/im/utils/constants'
+
+import { GroupMember, type GroupMemberLite } from '../../../../components/group'
+
+defineOptions({ name: 'ImMentionPicker' })
+
+const props = withDefaults(
+  defineProps<{
+    canAtAll?: boolean // 当前用户是否能 @ 全员（群主 / 管理员），父组件按角色算好传入
+    members: GroupMemberLite[] // 当前群的成员列表
+    // 浮层位置：x 横坐标 + top / bottom 二选一（bottom 锚定时 picker 下沿贴 @ 上方）
+    position?: { bottom?: number; top?: number; x: number; }
+    searchText?: string // @ 后输入的过滤文本
+    visible: boolean // 是否显示
+  }>(),
+  {
+    searchText: '',
+    position: () => ({ x: 0, bottom: 0 })
+  }
+)
+
+const emit = defineEmits<{
+  select: [member: GroupMemberLite]
+  'update:visible': [value: boolean]
+}>()
+
+const scrollRef = useTemplateRef<HTMLDivElement>('scrollRef')
+const activeIdx = ref(0)
+
+/** 当前登录用户 id（成员列表过滤掉自己） */
+const selfUserId = computed(() => getCurrentUserId())
+
+/**
+ * 虚拟"所有人"项：群主 / 管理员（canAtAll=true）+ 关键字命中"所有人"前缀时存在
+ *
+ * MessageInput 走 token data-id 收集 atUserIds，不依赖文案字符串；
+ * 这里的 userId / 文案都从 im/utils/constants 取，避免散落
+ */
+const allItem = computed<GroupMemberLite | null>(() => {
+  if (!props.canAtAll) {
+    return null
+  }
+  if (!IM_AT_ALL_NICKNAME.startsWith(props.searchText)) {
+    return null
+  }
+  // @所有人 是个伪成员，nickname 给 IM_AT_ALL_NICKNAME 让头像 :name 行为对齐普通成员
+  return {
+    userId: IM_AT_ALL_USER_ID,
+    showName: IM_AT_ALL_NICKNAME,
+    nickname: IM_AT_ALL_NICKNAME
+  }
+})
+
+/** 真成员：过滤自己 / 退群 / 不匹配关键字；不截断数量，浮层 max-height + el-scrollbar 撑滚动 */
+const memberItems = computed<GroupMemberLite[]>(() =>
+  props.members.filter(
+    (member) =>
+      member.userId !== selfUserId.value &&
+      member.status !== CommonStatusEnum.DISABLE &&
+      !!member.showName &&
+      member.showName.startsWith(props.searchText)
+  )
+)
+
+/** 键盘导航与 pickActive 走的扁平列表，allItem 在前、memberItems 在后 */
+const showMembers = computed<GroupMemberLite[]>(() => {
+  return allItem.value ? [allItem.value, ...memberItems.value] : memberItems.value
+})
+
+/** 候选列表变化（用户输入关键词在过滤）→ 重置高亮到首项 + 滚回顶 */
+watch(showMembers, (list) => {
+  activeIdx.value = list.length > 0 ? 0 : -1
+  scrollToTop()
+})
+
+/** 浮层重新打开 → 重置高亮 + 滚回顶（避免上次的中间状态残留） */
+watch(
+  () => props.visible,
+  (v) => {
+    if (v) {
+      activeIdx.value = showMembers.value.length > 0 ? 0 : -1
+      scrollToTop()
+    }
+  }
+)
+
+/** el-scrollbar 没暴露 scrollTo，直接拿内部 wrap 调 scrollTop */
+function scrollToTop() {
+  const scrollWrap = scrollRef.value
+  if (scrollWrap) {
+    scrollWrap.scrollTop = 0
+  }
+}
+
+/** 键盘上下导航时把高亮项滚到可视区：超出底边下推、超出顶边上拉，否则不动 */
+function scrollToActive() {
+  const scrollWrap = scrollRef.value
+  if (!scrollWrap) {
+    return
+  }
+  const itemHeight = 40
+  const activeOffsetTop = activeIdx.value * itemHeight
+  if (activeOffsetTop + itemHeight > scrollWrap.scrollTop + scrollWrap.clientHeight) {
+    scrollWrap.scrollTop = activeOffsetTop + itemHeight - scrollWrap.clientHeight
+  } else if (activeOffsetTop < scrollWrap.scrollTop) {
+    scrollWrap.scrollTop = activeOffsetTop
+  }
+}
+
+/** 选中一项：emit 给 MessageInput 落 token，同时关掉浮层 */
+function handleSelect(member: GroupMemberLite) {
+  emit('select', member)
+  emit('update:visible', false)
+}
+
+// 暴露给父组件的键盘导航方法
+defineExpose({
+  moveUp() {
+    if (activeIdx.value > 0) {
+      activeIdx.value--
+      scrollToActive()
+    }
+  },
+  moveDown() {
+    if (activeIdx.value < showMembers.value.length - 1) {
+      activeIdx.value++
+      scrollToActive()
+    }
+  },
+  pickActive() {
+    const member = showMembers.value[activeIdx.value]
+    if (activeIdx.value >= 0 && member) {
+      handleSelect(member)
+    }
+  },
+  hasCandidates: () => showMembers.value.length > 0
+})
+</script>
+
+<template>
+  <!--
+    @ 成员选择浮层（对齐微信 PC：所有人在顶 + 群成员分组 + 底部三角指针）
+    - 父组件通过 v-model:visible 控制显隐，searchText 过滤
+    - 父组件通过 ref 调 moveUp / moveDown / pickActive 实现键盘上下 + Enter 选中
+    - @select 发射被选中的成员
+  -->
+  <div
+    v-show="visible && showMembers.length > 0"
+    class="message-input__mention-picker !fixed z-100 w-50 rounded-md bg-[var(--ant-color-bg-container)] shadow-[0_4px_16px_rgba(0,0,0,0.12)]"
+    :style="{
+      left: `${position.x }px`,
+      top: position.top != null ? `${position.top }px` : 'auto',
+      bottom: position.bottom != null ? `${position.bottom }px` : 'auto'
+    }"
+  >
+    <div ref="scrollRef" style="max-height: 300px; overflow-y: auto">
+      <!-- 所有人：虚拟项，仅群主可选；蓝色方块 + 群体图标，跟下面的成员头像区分 -->
+      <div
+        v-if="allItem"
+        class="flex items-center gap-2.5 px-[5px] h-10 cursor-pointer transition-colors hover:bg-[var(--ant-color-fill)]"
+        :class="{ 'bg-[#e1eaf7] dark:bg-[var(--ant-color-primary-bg)]': activeIdx === 0 }"
+        @click.stop="handleSelect(allItem)"
+      >
+        <div
+          class="flex items-center justify-center w-[30px] h-[30px] rounded text-white bg-[var(--ant-color-primary)] flex-shrink-0"
+        >
+          <Icon icon="ep:user-filled" :size="18" />
+        </div>
+        <span class="overflow-hidden text-sm truncate text-[var(--ant-color-text)]">
+          {{ allItem.showName }}
+        </span>
+      </div>
+
+      <!-- 群成员 section header：只有"所有人 + 真成员"两边都在时才出现，避免单一来源时显得多余 -->
+      <div
+        v-if="allItem && memberItems.length > 0"
+        class="px-2 pt-2 pb-1 text-12px text-[var(--ant-color-text-secondary)]"
+      >
+        群成员
+      </div>
+
+      <!-- 真成员行 -->
+      <GroupMember
+        v-for="(member, idx) in memberItems"
+        :key="member.userId"
+        :member="member"
+        :height="40"
+        :active="activeIdx === (allItem ? idx + 1 : idx)"
+        :clickable="false"
+        @click.stop="handleSelect(member)"
+      />
+    </div>
+
+    <!-- 三角指针：picker 在 @ 下方（position.top 锚定）→ 箭头朝上贴顶；picker 在 @ 上方（position.bottom 锚定）→ 箭头朝下贴底 -->
+    <div
+      class="absolute left-4 w-3 h-3 rotate-45 bg-[var(--ant-color-bg-container)]"
+      :class="position.top != null ? '-top-1.5' : '-bottom-1.5'"
+    ></div>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/input/message-input.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/input/message-input.vue
new file mode 100644
index 000000000..746555b20
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/input/message-input.vue
@@ -0,0 +1,1217 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from '../../../../components/group'
+
+import type { Conversation } from '#/views/im/home/types'
+
+import { computed, onBeforeUnmount, onMounted, ref, useTemplateRef, watch } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+import { isOpenableUrl } from '@vben/utils'
+
+import { ElButton, ElDropdown, ElDropdownItem, ElDropdownMenu, ElMessage, ElTooltip } from 'element-plus'
+
+import { uploadFile } from '#/api/infra/file'
+import {
+  ensureMediaSizeWithinLimit,
+  useMediaUploader
+} from '#/views/im/home/composables/useMediaUploader'
+import { useMessageSender } from '#/views/im/home/composables/useMessageSender'
+import { useMuteOverlay } from '#/views/im/home/composables/useMuteOverlay'
+import { useConversationStore } from '#/views/im/home/store/conversationStore'
+import { useFriendStore } from '#/views/im/home/store/friendStore'
+import { useGroupStore } from '#/views/im/home/store/groupStore'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+import { DANGEROUS_FILE_EXTENSIONS, MESSAGE_GROUP_READ_ENABLED } from '#/views/im/utils/config'
+import { ImContentType, ImConversationType, ImGroupMemberRole } from '#/views/im/utils/constants'
+import { getConversationKey } from '#/views/im/utils/conversation'
+import {
+  type FaceMessage,
+  type QuoteMessage,
+  serializeMessage,
+  withQuotePayload
+} from '#/views/im/utils/message'
+import { getMemberDisplayName } from '#/views/im/utils/user'
+
+import { ReplyPreview } from '../message'
+import FacePicker from './face-picker.vue'
+import MentionPicker from './mention-picker.vue'
+import VoiceRecorder from './voice-recorder.vue'
+
+defineOptions({ name: 'ImMessageInput' })
+
+const conversationStore = useConversationStore()
+const groupStore = useGroupStore()
+const friendStore = useFriendStore()
+const { send, sendRaw } = useMessageSender()
+const {
+  uploadAndSendMedia,
+  insertMediaPlaceholder,
+  markMediaFailed,
+  commitMediaPlaceholder,
+  createUploadProgressHandler,
+  verifyMediaUploadStillAllowed,
+  requireMediaHandler
+} = useMediaUploader()
+const muteOverlay = useMuteOverlay() // 禁言 / 封禁覆盖层
+
+const editorRef = useTemplateRef<HTMLDivElement>('editorRef')
+const imageInputRef = useTemplateRef<HTMLInputElement>('imageInputRef')
+const fileInputRef = useTemplateRef<HTMLInputElement>('fileInputRef')
+const videoInputRef = useTemplateRef<HTMLInputElement>('videoInputRef')
+const mentionRef = useTemplateRef<InstanceType<typeof MentionPicker>>('mentionRef')
+
+// ==================== 文本 / 发送 ====================
+const canSend = ref(false) // editor 是否有可发送内容；contenteditable 没 v-model，靠 input 事件主动同步
+
+/** 维护 canSend + data-empty（撑起 placeholder）；不写草稿，restoreDraftToEditor 复用避免回流 */
+function applyEditorUiState(editor: HTMLDivElement) {
+  const raw = editor.textContent || ''
+  // canSend 按 trim 后判断（空格 / 换行不算可发送内容）；禁言态直接禁用
+  canSend.value = !!raw.trim() && !!conversationStore.activeConversation && !muteOverlay.value
+  // data-empty 按原始内容判断：用户敲一个空格也要让 placeholder 隐藏，避免视觉叠加
+  // 用属性"存在 / 缺失"而非 'true'/'false' 字符串：CSS [data-empty]::before 命中即可，
+  // 比 [data-empty='true'] 直观；浏览器删空后留 <br> → :empty 不命中，所以必须 JS 维护
+  if (raw) {
+    delete editor.dataset.empty
+  } else {
+    editor.dataset.empty = ''
+  }
+}
+
+/** 用户编辑入口的统一收尾：UI 状态同步 + 草稿写回 store（列表立即出 [草稿] 前缀） */
+function syncEditorState() {
+  const editor = editorRef.value
+  if (!editor) {
+    return
+  }
+  applyEditorUiState(editor)
+  syncDraftToStore(editor)
+}
+
+/** 禁言状态变化时同步发送按钮 */
+watch(muteOverlay, () => {
+  const editor = editorRef.value
+  if (editor) {
+    applyEditorUiState(editor)
+  }
+})
+
+/** 把 editor 当前内容写到会话草稿；plain 由 collectFromEditor 拿，与发送时同源避免列表与实发不一致 */
+function syncDraftToStore(editor: HTMLDivElement) {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  // collectFromEditor 已 trim，plain 为空时 store 内部按 clearConversationDraft 处理
+  // reply 透传当前快照：setConversationDraft 是整对象替换，不读旧 reply 会让用户每敲一个键就把引用条擦掉
+  const { text } = collectFromEditor(editor)
+  const existing = conversationStore.getConversationDraft(conversation)
+  conversationStore.setConversationDraft(conversation, {
+    html: editor.innerHTML,
+    plain: text,
+    reply: existing?.reply
+  })
+}
+
+/** 切会话时把 store 里的草稿还原到 editor；只更 UI 不回写草稿，避免 store→editor→store 回流 */
+function restoreDraftToEditor() {
+  const editor = editorRef.value
+  if (!editor) {
+    return
+  }
+  const conversation = conversationStore.activeConversation
+  const draft = conversation ? conversationStore.getConversationDraft(conversation) : undefined
+  editor.innerHTML = draft?.html || ''
+  applyEditorUiState(editor)
+  // 把光标移到末尾，让用户接着输入；空内容直接 focus 即可
+  if (draft?.html) {
+    placeCaretAtEnd(editor)
+  }
+}
+
+/** 把光标放到 contenteditable 元素的末尾——切回有草稿的会话时光标自然落在尾部，对齐微信 */
+function placeCaretAtEnd(el: HTMLElement) {
+  const range = document.createRange()
+  range.selectNodeContents(el)
+  range.collapse(false)
+  const sel = window.getSelection()
+  if (!sel) {
+    return
+  }
+  sel.removeAllRanges()
+  sel.addRange(range)
+}
+
+/**
+ * 走 DOM 把 editor 内容拼回 text + atUserIds
+ *
+ * 节点分支：
+ * 1. text 节点：直接拼 textContent；过程中滤掉 ZWSP（token 首位锚点用，不进发送内容）
+ * 2. br：拼 \n（Shift+Enter 走 execCommand('insertLineBreak') 产物）
+ * 3. span[data-id]：拼 token 显示文本 + 把 dataset.id 收到 atUserIds（不递归 span 内部）
+ * 4. div：浏览器在 contenteditable 里默认换行容器，前置 \n 后递归子节点
+ * 5. 其他元素：透传，递归子节点
+ *
+ * atUserIds 走 Set 去重：用户 @ 张三两次时 atUserIds 只出现一次；trim 末尾空白
+ */
+function collectFromEditor(root: HTMLElement): { atUserIds: number[]; text: string; } {
+  const userIds: number[] = []
+  let text = ''
+
+  function walk(node: Node) {
+    if (node.nodeType === Node.TEXT_NODE) {
+      text += (node.textContent || '').replaceAll('​', '')
+      return
+    }
+    if (node.nodeType !== Node.ELEMENT_NODE) {
+      return
+    }
+    const el = node as HTMLElement
+    const tag = el.tagName.toLowerCase()
+    if (tag === 'br') {
+      text += '\n'
+      return
+    }
+    if (tag === 'span' && el.dataset.id) {
+      text += el.textContent || ''
+      const id = Number(el.dataset.id)
+      if (!Number.isNaN(id)) {
+        userIds.push(id)
+      }
+      return
+    }
+    if (tag === 'div') {
+      if (text && !text.endsWith('\n')) {
+        text += '\n'
+      }
+      el.childNodes.forEach((child) => walk(child))
+      return
+    }
+    el.childNodes.forEach((child) => walk(child))
+  }
+
+  // 直接从 root.childNodes 开始，避免把 root 本身也当元素处理（虽然目前没有特殊样式，但以防未来改动）
+  root.childNodes.forEach((child) => walk(child))
+  return {
+    text: text.trim(),
+    atUserIds: [...new Set(userIds)]
+  }
+}
+
+/**
+ * 发送：从 DOM 收 text + atUserIds → 清空编辑器 → 走 useMessageSender.send
+ *
+ * 1. 防御：canSend 是 false（trim 后空 / 没激活会话）或 editor 没 mount → 直接 return
+ * 2. 收集：DOM walk 拿到要发送的文本 + atUserIds
+ * 3. 二次防御：collectFromEditor 走 trim，可能比 syncEditorState 更严格（例如全 ZWSP），仍空就 return
+ * 4. 清空 + 同步状态：先清 innerHTML 再 syncEditorState 让 placeholder / canSend 一起回归
+ *    （顺序很重要：先清后 sync，否则 sync 看到旧内容会误判）
+   * 5. 上送：atUserIds 非空才传，避免发空数组；quote 由 clearConversationDraft 前抓取，确保引用条立即消失
+ */
+async function handleSend(options?: { receipt?: boolean }) {
+  const editor = editorRef.value
+  if (!canSend.value || !editor || muteOverlay.value) {
+    return
+  }
+  const { text, atUserIds } = collectFromEditor(editor)
+  if (!text) {
+    return
+  }
+  // 1. 抓 quote 后清空 editor + 当前会话草稿（包含 reply）；syncEditorState 后 / reply 都为空
+  //    store 内部会自动清理，但显式 clearConversationDraft 能立即同步、不依赖 debounce 时序，列表上的 [草稿] 立即消失
+  const replyQuote = replyTarget.value
+  editor.innerHTML = ''
+  if (conversationStore.activeConversation) {
+    conversationStore.clearConversationDraft(conversationStore.activeConversation)
+  }
+  syncEditorState()
+  // 2. 发送
+  await send(text, {
+    atUserIds: atUserIds.length > 0 ? atUserIds : undefined,
+    receipt: options?.receipt,
+    quote: replyQuote
+  })
+}
+
+/** 发送按钮下拉菜单操作 */
+function handleSendMenuClick({ key }: { key: number | string }) {
+  if (key === 'receipt') {
+    handleSend({ receipt: true })
+  }
+}
+
+// ==================== 选区 / 插入 ====================
+/**
+ * 上次落在 editor 内的 selection（焦点被表情面板等夺走时用来回到原插入点）
+ *
+ * 监听 document.selectionchange 比 editor.@blur 更可靠：blur 时 selection 已经移走
+ */
+let savedRange: null | Range = null
+
+/**
+ * 走 native execCommand，保留浏览器原生 undo 栈
+ *
+ * execCommand 在 lib.dom 里被标 @deprecated（IDE 显示删除线），但 'insertText' /
+ * 'insertLineBreak' 没有等价的 W3C 标准替代——Range/Selection 自己拼 DOM 会让 Ctrl+Z 失效。
+ * 集中到这里调用，调用点不必散落 ts-expect-error；不引入 eslint disable（项目当前
+ * @typescript-eslint v7 没有 no-deprecated 规则，加了也无效，反而让 lint 报"规则不存在"）
+ */
+function nativeExec(command: 'insertLineBreak' | 'insertText', value?: string) {
+  document.execCommand(command, false, value)
+}
+
+/**
+ * document selectionchange 监听：把落在 editor 内的 selection 缓存到 savedRange，
+ * insertText 在焦点被偷走后用它把光标恢复到原插入点
+ */
+function onSelectionChange() {
+  const editor = editorRef.value
+  const sel = window.getSelection()
+  if (!editor || !sel || sel.rangeCount === 0) {
+    return
+  }
+  const range = sel.getRangeAt(0)
+  if (editor.contains(range.startContainer)) {
+    savedRange = range.cloneRange()
+  }
+}
+
+/**
+ * 点击 editor / picker 外部时关掉浮层，避免输入 @keyword 后用户点别处浮层不消失
+ *
+ * 用 mousedown 而非 click：click 在某些浏览器里 picker 元素消失后回不到原 target，会被吞掉
+ */
+function onDocMousedown(e: MouseEvent) {
+  if (!mentionVisible.value) {
+    return
+  }
+  const target = e.target as Node | null
+  if (!target) {
+    return
+  }
+  if (editorRef.value?.contains(target)) {
+    return
+  }
+  // picker 是 fixed 定位的兄弟节点，不在 editor 子树里；用类名定位
+  const pickerEl = document.querySelector('.message-input__mention-picker')
+  if (pickerEl?.contains(target)) {
+    return
+  }
+  closeMention()
+}
+
+onMounted(() => {
+  document.addEventListener('selectionchange', onSelectionChange)
+  document.addEventListener('mousedown', onDocMousedown)
+  restoreDraftToEditor()
+})
+
+onBeforeUnmount(() => {
+  document.removeEventListener('selectionchange', onSelectionChange)
+  document.removeEventListener('mousedown', onDocMousedown)
+})
+
+/**
+ * 切会话时还原对方的草稿到 editor
+ *
+ * 同步关 @ / 表情 / 语音浮层并清 savedRange：
+ * - mentionRange / savedRange 旧引用还指向上一会话的 DOM 节点，不清下次插 token 会落错位置
+ * - 语音录制弹窗保留时，录完触发的 onVoiceSend 会读当前 activeConversation，把语音发到新会话
+ */
+watch(
+  () =>
+    conversationStore.activeConversation
+      ? getConversationKey(conversationStore.activeConversation)
+      : null,
+  () => {
+    closeMention()
+    emojiVisible.value = false
+    voiceVisible.value = false
+    savedRange = null
+    restoreDraftToEditor()
+  }
+)
+
+/**
+ * 把字符串插入光标处（emoji 面板等场景调用）
+ *
+ * 1. editor 没挂直接返回
+ * 2. 焦点回到 editor + 把 savedRange 恢复成当前 selection（emoji 面板偷焦点后还能回原位）
+ * 3. nativeExec 插文本，保留浏览器原生 undo 栈
+ * 4. 同步 canSend / placeholder
+ */
+function insertText(str: string) {
+  const editor = editorRef.value
+  if (!editor) {
+    return
+  }
+  editor.focus()
+  if (savedRange) {
+    const sel = window.getSelection()
+    if (sel) {
+      sel.removeAllRanges()
+      sel.addRange(savedRange)
+    }
+  }
+  // 1. nativeExec 插文本，保留浏览器原生 undo 栈
+  nativeExec('insertText', str)
+  // 2. 同步 canSend / placeholder
+  syncEditorState()
+}
+
+/**
+ * 粘贴处理
+ *
+ * 1. 优先扫 clipboardData.items 找文件类型条目（截图、拖入的图片 / 文件等）
+ *    - image/* → 走 IMAGE 上传发送
+ *    - 其它 file → 走 FILE 上传发送
+ *    - 一次粘贴只处理第一个文件，避免一次粘贴发出多条消息
+ * 2. 没文件再走 text：剥掉外部样式 / 脚本，避免外站 inline style 污染 editor
+ *    （contenteditable 默认粘贴会带 HTML，所以模板上 @paste.prevent 拦截）
+ */
+function onPaste(e: ClipboardEvent) {
+  // 1. 优先扫 clipboardData.items 找文件类型条目（截图、拖入的图片 / 文件等）
+  const items = e.clipboardData?.items
+  if (items?.length) {
+    for (const item of items) {
+      if (!item) {
+        continue
+      }
+      if (item.kind !== 'file') {
+        continue
+      }
+      const file = item.getAsFile()
+      if (!file) {
+        continue
+      }
+      if (item.type.startsWith('image/')) {
+        void uploadAndSendImage(file)
+      } else {
+        void uploadAndSendFile(file)
+      }
+      return
+    }
+  }
+  // 2. 没文件再走 text：剥掉外部样式 / 脚本，避免外站 inline style 污染 editor
+  const text = e.clipboardData?.getData('text/plain') || ''
+  if (text) {
+    nativeExec('insertText', text)
+    // @paste.prevent 阻断了浏览器默认 input 事件，需手动同步草稿 / canSend，与 insertText() 路径一致
+    syncEditorState()
+  }
+}
+
+/** 编辑器内容变化的统一入口：先同步 canSend / placeholder，再判 @ 浮层是否要展开 */
+function onInput() {
+  syncEditorState()
+  detectAtMention()
+}
+
+// ==================== 引用 / 回复 ====================
+
+/** 当前会话的「正在回复」对象，从会话草稿派生 */
+const replyTarget = computed<QuoteMessage | undefined>(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return undefined
+  }
+  return conversationStore.getConversationDraft(conversation)?.reply
+})
+
+/** 清掉当前 reply 但保留正文草稿：点 × 关闭 / 发送即将进行时调 */
+function clearConversationReplyDraft() {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  conversationStore.clearConversationReplyDraft(conversation)
+}
+
+/** 取走当前 reply 快照（抓一次清一次），媒体上传链路在动手前统一调它拿 quote */
+function consumeReply(): QuoteMessage | undefined {
+  const quote = replyTarget.value
+  if (quote) {
+    clearConversationReplyDraft()
+  }
+  return quote
+}
+
+// ==================== 表情 ====================
+const emojiVisible = ref(false)
+/** 切换表情面板；打开时互斥关掉语音面板 */
+function toggleEmoji() {
+  emojiVisible.value = !emojiVisible.value
+  if (emojiVisible.value) {
+    voiceVisible.value = false
+  }
+}
+
+/** 选中表情贴图：拼 FaceMessage payload 直接走 sendRaw 发送（quote 复用当前 reply 快照） */
+async function onSelectFace(face: { height: number; name?: string; url: string; width: number; }) {
+  if (muteOverlay.value) {
+    return
+  }
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  const replyQuote = consumeReply()
+  const payload = withQuotePayload<FaceMessage>(
+    { url: face.url, width: face.width, height: face.height, name: face.name },
+    replyQuote
+  )
+  await sendRaw(ImContentType.FACE, serializeMessage(payload), { conversation })
+}
+
+// ==================== @ 成员选择（群聊） ====================
+const isGroup = computed(
+  () => conversationStore.activeConversation?.type === ImConversationType.GROUP
+)
+
+/** 从 groupStore 读当前激活群的成员（切会话时由 MessagePanel 预拉） */
+const groupMembers = computed<GroupMemberLite[]>(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || conversation.type !== ImConversationType.GROUP) {
+    return []
+  }
+  const group = groupStore.getGroup(conversation.targetId)
+  return (group?.members || []).map((member) => {
+    const friend = friendStore.getFriend(member.userId)
+    return {
+      userId: member.userId,
+      showName: getMemberDisplayName(member, friend),
+      nickname: member.nickname,
+      avatar: member.avatar,
+      status: member.status
+    }
+  })
+})
+
+/** 当前用户是否能 @ 全员；群主 + 管理员都允许（对齐微信 PC：admin 也能 @ 所有人） */
+const canAtAll = computed<boolean>(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || conversation.type !== ImConversationType.GROUP) {
+    return false
+  }
+  const group = groupStore.getGroup(conversation.targetId)
+  if (!group) {
+    return false
+  }
+  const myId = getCurrentUserId()
+  if (!myId) {
+    return false
+  }
+  if (group.ownerUserId === myId) {
+    return true
+  }
+  return group.members?.find((member) => member.userId === myId)?.role === ImGroupMemberRole.ADMIN
+})
+
+const mentionVisible = ref(false)
+const mentionSearchText = ref('')
+/** 浮层定位：x 是左边距；top / bottom 二选一—— bottom 锚定（picker 下沿贴 @）是默认，
+ *  上方放不下时退化为 top 锚定（picker 上沿贴 @ 下方） */
+const mentionPosition = ref<{ bottom?: number; top?: number; x: number; }>({ x: 0, bottom: 0 })
+
+/** MentionPicker 的容器宽度（与组件里的 w-50 对齐），用于视口右沿回弹；
+ *  高度不再用常量算位置——bottom 锚定后 picker 内容多寡都不影响下沿位置，自然贴 @ */
+const MENTION_WIDTH = 200
+const MENTION_MIN_FIT_ABOVE = 120 // 上方剩余空间至少这么多才放上方，否则翻到下方（避免 picker 被视口顶 / 顶部 chat header 切掉）
+
+/** 当前 @ 关键词在 editor 里的范围；onMentionSelect 用它定位删除 + 插入 token */
+let mentionRange: null | Range = null
+
+/** 关闭浮层 + 清掉 range，避免上次残留的 range 被下一次 onMentionSelect 误用 */
+function closeMention() {
+  mentionVisible.value = false
+  mentionRange = null
+}
+
+/** 在光标当前文本节点里向前找 @keyword，命中则展开浮层 */
+function detectAtMention() {
+  if (!isGroup.value) {
+    closeMention()
+    return
+  }
+  const sel = window.getSelection()
+  if (!sel || sel.rangeCount === 0) {
+    closeMention()
+    return
+  }
+  const range = sel.getRangeAt(0)
+  if (!range.collapsed || range.startContainer.nodeType !== Node.TEXT_NODE) {
+    closeMention()
+    return
+  }
+  const node = range.startContainer
+  const offset = range.startOffset
+  const before = (node.textContent || '').slice(0, offset)
+  // 直接找最近的 @：不限制前置字符，对齐微信"中文紧贴 @ 也能联想"（你好@张三、，@张三 都触发）；
+  // 代价是 email-like "test@example.com" 也会触发，但聊天输入里粘 email 的概率低，
+  // 且用户按 Esc 即可关浮层；兜底由 [^\s@] 保证一旦输入空格 / 第二个 @ 就停下
+  const match = before.match(/@([^\s@]*)$/)
+  if (!match) {
+    closeMention()
+    return
+  }
+  const keyword = match[1] ?? ''
+  const atOffset = offset - keyword.length - 1
+  mentionRange = document.createRange()
+  mentionRange.setStart(node, atOffset)
+  mentionRange.setEnd(node, offset)
+  mentionSearchText.value = keyword
+  // 锚定在 @ 符号本身，而非当前 caret——否则用户每多敲一个字浮层就跟着右移（"飘"）
+  positionMention(node, atOffset)
+  mentionVisible.value = true
+}
+
+/**
+ * 浮层位置：默认 bottom 锚定（picker 下沿贴 @ 上方 8px），上方不够才翻成 top 锚定
+ *
+ * 1. 计算 @ 字符屏幕坐标 rect
+ * 2. 横向：picker 左边对齐 @，越过视口右沿则左推；至少留 8px 留白
+ * 3. 纵向：上方剩余 ≥ MENTION_MIN_FIT_ABOVE 走 bottom 锚定（不依赖 picker 实际高度，
+ *    无论 1 项还是 N 项 picker 下沿都贴 @）；不够则翻到 @ 下方走 top 锚定
+ */
+function positionMention(node: Node, atOffset: number) {
+  // 1. 计算 @ 字符屏幕坐标 rect
+  const anchor = document.createRange()
+  anchor.setStart(node, atOffset)
+  anchor.collapse(true)
+  const rect = anchor.getBoundingClientRect()
+  // 2. 横向：picker 左边对齐 @，越过视口右沿则左推；至少留 8px 留白
+  const left = Math.max(8, Math.min(rect.left, window.innerWidth - MENTION_WIDTH - 8))
+  // 3. 纵向：上方剩余 ≥ MENTION_MIN_FIT_ABOVE 走 bottom 锚定
+  mentionPosition.value = rect.top >= MENTION_MIN_FIT_ABOVE ? { x: left, bottom: window.innerHeight - rect.top + 8 } : { x: left, top: rect.bottom + 8 };
+}
+
+/** editor 内部滚动时同步浮层位置（多行 + 触发滚动条场景） */
+function onEditorScroll() {
+  if (!mentionVisible.value || !mentionRange) {
+    return
+  }
+  positionMention(mentionRange.startContainer, mentionRange.startOffset)
+}
+
+function onMentionSelect(member: GroupMemberLite) {
+  const editor = editorRef.value
+  if (!editor || !mentionRange) {
+    return
+  }
+  // 删 @keyword，插入 contenteditable=false 的 token：
+  // 删除时整段消除 + 不会被光标拆穿；data-id 是后续 collectFromEditor 收 atUserIds 的钩子
+  // token 文本固定走真实昵称：群里所有成员看到的字面量一致，避免我侧的好友备注 / 群昵称污染发送文本
+  mentionRange.deleteContents()
+  const span = document.createElement('span')
+  span.className = 'mention-token'
+  span.dataset.id = String(member.userId)
+  span.contentEditable = 'false'
+  span.textContent = `@${member.nickname || member.showName}`
+  mentionRange.insertNode(span)
+  // token 在 editor 首位时，contenteditable=false 边缘会让光标无法挪到 token 前
+  // 补一个零宽空格当锚点；DOM walk 时会被滤掉，不进入发送内容
+  const prev = span.previousSibling
+  if (!prev || (prev.nodeType === Node.TEXT_NODE && !prev.textContent)) {
+    span.parentNode?.insertBefore(document.createTextNode('\u200B'), span)
+  }
+  // 在 token 后补一个 NBSP，让光标可以继续输入；NBSP 比普通空格更稳，避免被浏览器折叠
+  const space = document.createTextNode('\u00A0')
+  span.parentNode?.insertBefore(space, span.nextSibling)
+  // 光标移到 NBSP 之后
+  const sel = window.getSelection()
+  if (sel) {
+    const newRange = document.createRange()
+    newRange.setStartAfter(space)
+    newRange.collapse(true)
+    sel.removeAllRanges()
+    sel.addRange(newRange)
+  }
+  closeMention()
+  editor.focus()
+  syncEditorState()
+}
+
+/**
+ * 键盘事件分发
+ *
+ * 1. mention 浮层打开时
+ *    1.1 ↑/↓ 移动高亮
+ *    1.2 Enter 有候选 → 选中；无候选 fall through 到下面的发送分支，避免按 Enter 没反应
+ *    1.3 Esc 关浮层
+ * 2. Shift+Enter 换行：强制走 br（浏览器默认会插 div，DOM walk 拼接更复杂）
+ * 3. 普通 Enter 发送（IME composition 期间不触发，避免选词被误发）
+ */
+function onKeydown(e: KeyboardEvent) {
+  // 1. mention 浮层打开时
+  if (mentionVisible.value) {
+    if (e.key === 'ArrowUp') {
+      e.preventDefault()
+      mentionRef.value?.moveUp()
+      return
+    }
+    if (e.key === 'ArrowDown') {
+      e.preventDefault()
+      mentionRef.value?.moveDown()
+      return
+    }
+    if (e.key === 'Enter' && !e.isComposing && mentionRef.value?.hasCandidates()) {
+        e.preventDefault()
+        mentionRef.value?.pickActive()
+        return
+      }
+    if (e.key === 'Escape') {
+      closeMention()
+      return
+    }
+  }
+  // 2. Shift+Enter 换行：强制走 br（浏览器默认会插 div，DOM walk 拼接更复杂）
+  if (e.key === 'Enter' && e.shiftKey && !e.isComposing) {
+    e.preventDefault()
+    nativeExec('insertLineBreak')
+    syncEditorState()
+    return
+  }
+  // 3. 普通 Enter 发送（IME composition 期间不触发，避免选词被误发）
+  if (e.key === 'Enter' && !e.shiftKey && !e.ctrlKey && !e.isComposing) {
+    e.preventDefault()
+    handleSend()
+  }
+}
+
+// ==================== 图片 / 文件 / 语音 上传 ====================
+
+/** 上传前的统一拦截：禁言态 / 无激活会话直接放弃；返回当前 conversation 与抓走的 quote */
+function prepareMediaUpload(): undefined | { conversation: Conversation; quote?: QuoteMessage } {
+  if (muteOverlay.value) {
+    return undefined
+  }
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return undefined
+  }
+  return { conversation, quote: consumeReply() }
+}
+
+/** 上传并发送 IMAGE 消息（占位 + 进度 + 真实 url ack 由 useMediaUploader 处理） */
+async function uploadAndSendImage(file: File) {
+  const context = prepareMediaUpload()
+  if (!context) {
+    return
+  }
+  await uploadAndSendMedia({
+    file,
+    type: ImContentType.IMAGE,
+    quote: context.quote,
+    conversation: context.conversation
+  })
+}
+
+/** 上传并发送 FILE 消息；payload 由 mediaTypeHandlers[FILE] 自动拼 url + name + size */
+async function uploadAndSendFile(file: File) {
+  // 文件名取最后一个 "." 之后的部分；无后缀 / 空字符串都按"未知"放行
+  const extension = file.name.split('.').pop()?.toLowerCase() ?? ''
+  if (extension && DANGEROUS_FILE_EXTENSIONS.includes(extension)) {
+    ElMessage.warning(`不允许发送 .${extension} 类型文件`)
+    return
+  }
+  const context = prepareMediaUpload()
+  if (!context) {
+    return
+  }
+  await uploadAndSendMedia({
+    file,
+    type: ImContentType.FILE,
+    quote: context.quote,
+    conversation: context.conversation
+  })
+}
+
+/** 图片选完即上传 + 发送 IMAGE 消息（不放入 editor，由 useMediaUploader 接管占位 / 进度 / ack） */
+async function onImagePicked(e: Event) {
+  const input = e.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (file) {
+    await uploadAndSendImage(file)
+  }
+}
+
+/** 文件选完即上传 + 发送 FILE 消息（携带原始 name / size 元数据） */
+async function onFilePicked(e: Event) {
+  const input = e.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (file) {
+    await uploadAndSendFile(file)
+  }
+}
+
+// ==================== 语音 ====================
+const voiceVisible = ref(false)
+/** 打开语音录制面板；互斥关掉表情面板 */
+function openVoice() {
+  voiceVisible.value = true
+  emojiVisible.value = false
+}
+/** 发送录音消息 */
+async function onVoiceSend(payload: {
+  blob: Blob
+  duration: number
+  extension: string
+  mimeType: string
+}) {
+  const context = prepareMediaUpload()
+  if (!context) {
+    return
+  }
+  const file = new File([payload.blob], `voice-${Date.now()}.${payload.extension}`, {
+    type: payload.mimeType || payload.blob.type
+  })
+  await uploadAndSendMedia({
+    file,
+    type: ImContentType.VOICE,
+    quote: context.quote,
+    conversation: context.conversation,
+    context: { voiceDuration: payload.duration }
+  })
+}
+
+// ==================== 视频 ====================
+type VideoProbe = {
+  cover?: Blob
+  duration?: number
+  height?: number
+  width?: number
+}
+
+const VIDEO_COVER_MAX_DIM = 720 // 封面最长边 cap：聊天列表里的视频封面没必要原视频分辨率，4K 原尺寸 jpeg 1-3MB 太浪费
+
+/**
+ * 加载视频本地预览，一次性拿到 metadata（duration / 宽高）+ 首帧封面 blob
+ *
+ * 一个 video 元素串两件事是为了避免重复 decode：metadata 解完后直接 seek 首帧再截图。
+ * 截图失败不抛异常，只让 cover 缺失，保证主流程仍能上传视频本体。
+ *
+ * finally 里显式断引用是因为：仅 revokeObjectURL 不足以让 video decoder 立即释放，
+ * 部分浏览器版本上 4K 视频解码 buffer 可滞留数十 MB 几秒到十几秒，连发几条会累计放大。
+ */
+async function probeVideoFile(file: File): Promise<VideoProbe> {
+  // 1. 准备离屏 video
+  // 1.1 muted + preload=metadata：只下载文件头，不预加载整条流
+  const objectUrl = URL.createObjectURL(file)
+  const video = document.createElement('video')
+  video.preload = 'metadata'
+  video.muted = true
+  video.src = objectUrl
+  try {
+    // 1.2 等 metadata 加载：解出 duration / 宽高才有 seek + 截图的依据
+    await new Promise<void>((resolve, reject) => {
+      video.addEventListener('loadedmetadata', () => resolve(), { once: true })
+      video.addEventListener('error', () => reject(new Error('video metadata load error')), {
+        once: true
+      })
+    })
+    // 1.3 抽元信息：duration 偶有 NaN（极少数损坏文件），软处理为 undefined
+    const meta = {
+      duration: Number.isFinite(video.duration) ? Math.round(video.duration) : undefined,
+      width: video.videoWidth || undefined,
+      height: video.videoHeight || undefined
+    }
+
+    // 2. 截首帧封面（独立 try：失败仅降级 cover 为空，不影响 meta）
+    let cover: Blob | undefined
+    try {
+      // 2.1 算 seek 时间：0.1s 避开常见的纯黑首帧；时长 < 0.2s 的极短视频退化为 0
+      const seekTo = video.duration > 0.2 ? 0.1 : 0
+      // 2.2 seek + 3s 超时：currentTime 设为当前值（譬如已经是 0 的极短视频）
+      //     部分浏览器不触发 onseeked，promise 会一直 pending 卡死整条链路
+      await new Promise<void>((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error('video seek timeout')), 3000)
+        video.addEventListener('seeked', () => {
+          clearTimeout(timer)
+          resolve()
+        }, { once: true })
+        video.addEventListener(
+          'error',
+          () => {
+            clearTimeout(timer)
+            reject(new Error('video seek error'))
+          },
+          { once: true }
+        )
+        video.currentTime = seekTo
+      })
+      // 2.3 离屏 canvas 等比缩放：长边 cap 720（VIDEO_COVER_MAX_DIM）
+      const canvas = document.createElement('canvas')
+      const ratio = Math.min(1, VIDEO_COVER_MAX_DIM / Math.max(video.videoWidth, video.videoHeight))
+      canvas.width = Math.round(video.videoWidth * ratio)
+      canvas.height = Math.round(video.videoHeight * ratio)
+      const context = canvas.getContext('2d')
+      if (context && canvas.width && canvas.height) {
+        // 2.4 当前帧绘到 canvas → toBlob 拿 jpeg；0.8 质量是聊天封面常用甜点
+        context.drawImage(video, 0, 0, canvas.width, canvas.height)
+        cover =
+          (await new Promise<Blob | null>((resolve) =>
+            canvas.toBlob((b) => resolve(b), 'image/jpeg', 0.8)
+          )) ?? undefined
+        // 2.5 提前释放 canvas backing store（4K 原尺寸 33MB），别等 GC
+        canvas.width = 0
+        canvas.height = 0
+      }
+    } catch (error) {
+      console.warn('[IM] 视频封面截取失败', error)
+    }
+    return { ...meta, cover }
+  } finally {
+    // 3. 显式释放 video 资源
+    // 3.1 revoke 本地 objectUrl
+    URL.revokeObjectURL(objectUrl)
+    // 3.2 触发 unload，让 decoder buffer 立即释放
+    video.removeAttribute('src')
+    video.load()
+  }
+}
+
+/**
+ * 上传并发送 VIDEO 消息
+ *
+ * 1. 立即占位：blob URL 既当 video src 也当 poster，浏览器会拿首帧绘制 cover；status=SENDING + 进度条
+ * 2. probe 与视频上传同步起跑；封面上传等 probe 出 cover 后与视频上传竞速
+ *    （probe 解码 + 封面上传通常被视频上传时长完全遮蔽，体感节省几百 ms 起步）
+ * 3. 视频本体上传必须成功，拿不到 url 就把占位置 FAILED；封面是锦上添花，失败仅日志
+ * 4. 视频链路耗时长，上传期间用户切会话则放弃发送（避免落到错误会话里）；切走再切回来不算变化（key 仍相等）
+ */
+async function uploadAndSendVideo(file: File) {
+  if (!ensureMediaSizeWithinLimit(file, ImContentType.VIDEO, ElMessage.warning)) {
+    return
+  }
+  const context = prepareMediaUpload()
+  if (!context) {
+    return
+  }
+  const { conversation } = context
+  const replyQuote = context.quote
+  const startKey = getConversationKey(conversation)
+
+  // 1. 立即占位：url 走 blob 让 <video src> 拉首字节渲染；coverUrl 不设 blob
+  //    （<video poster> 期待图片资源，传 video blob 在部分浏览器会退化成黑底，不是稳定行为）
+  //    cover 等 probe 异步出真实 URL 后由 commit 阶段一起 patch；_localFile 留 file 供失败重试
+  //    payload 拼装走 mediaTypeHandlers[VIDEO].build 与 commit 阶段共享同一份逻辑
+  const videoHandler = requireMediaHandler(ImContentType.VIDEO)
+  const buildPlaceholderContent = (blobUrl: string): string =>
+    serializeMessage(withQuotePayload(videoHandler.build(file, blobUrl, {}), replyQuote))
+  const { clientMessageId } = insertMediaPlaceholder({
+    file,
+    type: ImContentType.VIDEO,
+    conversation,
+    buildContent: buildPlaceholderContent
+  })
+
+  // 2. 三路并行起跑（probe 与两条上传无依赖，封面上传等 probe 出 cover 后立即接力）
+  // 2.1 视频本体上传：async IIFE 包一层让 await 显式可见（lint 不再误判 floating promise），
+  //     失败兜底为 url=undefined，由 step 3 拿不到 url 时收尾
+  const videoUploadPromise: Promise<string | undefined> = (async () => {
+    try {
+      return await uploadFile(
+        { file },
+        createUploadProgressHandler(conversation, clientMessageId)
+      )
+    } catch (error) {
+      console.warn('[IM] 视频本体上传失败', error)
+      return undefined
+    }
+  })()
+  // 2.2 probe 拿元信息 + 封面 blob：解码失败降级为空 probe，不阻断视频上传
+  const probePromise = probeVideoFile(file).catch((error): VideoProbe => {
+    console.warn('[IM] 视频元信息加载失败，降级为仅 url + size', error)
+    return {}
+  })
+  // 2.3 封面上传：等 probe.cover 出来后接力起跑，与视频上传竞速；失败降级 coverUrl 为空
+  const coverUploadPromise = probePromise.then(async (probe) => {
+    if (!probe.cover) {
+      return { probe, coverUrl: undefined as string | undefined }
+    }
+    try {
+      const coverUrl = await uploadFile({
+        file: new File([probe.cover], `cover-${Date.now()}.jpg`, { type: 'image/jpeg' })
+      })
+      return { probe, coverUrl }
+    } catch (error) {
+      console.warn('[IM] 视频封面上传失败', error)
+      return { probe, coverUrl: undefined as string | undefined }
+    }
+  })
+
+  // 3. 收口校验
+  // 3.1 等两条上传链路汇合
+  const [videoRes, { probe, coverUrl }] = await Promise.all([
+    videoUploadPromise,
+    coverUploadPromise
+  ])
+  // 3.2 视频本体没 url：占位置 FAILED，让用户决定重试 / 删除（_localFile 在内存里）
+  const url = videoRes
+  if (!url) {
+    markMediaFailed(conversation.type, conversation.targetId, clientMessageId)
+    return
+  }
+  if (!isOpenableUrl(url)) {
+    console.warn('[IM] 视频上传返回了不支持打开的 URL', { url })
+    ElMessage.warning('上传返回的视频地址不支持打开')
+    markMediaFailed(conversation.type, conversation.targetId, clientMessageId)
+    return
+  }
+  const safeCoverUrl = coverUrl && isOpenableUrl(coverUrl) ? coverUrl : undefined
+  if (coverUrl && !safeCoverUrl) {
+    console.warn('[IM] 视频封面上传返回了不支持打开的 URL', { coverUrl })
+  }
+  // 3.3 上传后会话校验 + muteOverlay 复查（与 useMediaUploader.uploadAndSendMedia 同一道）
+  if (
+    !verifyMediaUploadStillAllowed(conversation, startKey, ImContentType.VIDEO, clientMessageId)
+  ) {
+    return
+  }
+
+  // 4. 拼真实 VideoMessage payload，patch 进占位 + 走 sendRaw 复用占位发送
+  const realContent = serializeMessage(
+    withQuotePayload(
+      videoHandler.build(file, url, {
+        videoProbe: { duration: probe.duration, width: probe.width, height: probe.height },
+        videoCoverUrl: safeCoverUrl
+      }),
+      replyQuote
+    )
+  )
+  await commitMediaPlaceholder({
+    type: ImContentType.VIDEO,
+    conversation,
+    clientMessageId,
+    realContent
+  })
+}
+
+/** 视频选完即上传 + 发送 VIDEO 消息（不放入 editor，独立链路：probe + 双上传，最终走 commitMediaPlaceholder 收尾） */
+async function onVideoPicked(e: Event) {
+  const input = e.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (file) {
+    await uploadAndSendVideo(file)
+  }
+}
+</script>
+
+<template>
+  <!--
+    外层底色与消息流（bg-color-page）保持一致，让"消息 → 输入"无色差过渡；
+    padding 给内层白卡片呼吸空间，卡片自带边框就够区分输入区，不再需要一条 border-t
+  -->
+  <div class="relative bg-[var(--ant-color-bg-layout)] px-3 pt-2 pb-3">
+    <!-- 禁言 / 封禁覆盖层：优先级 封禁 > 全群禁言 > 成员禁言 -->
+    <div
+      v-if="muteOverlay"
+      class="message-input__mute-overlay absolute top-2 right-3 bottom-3 left-3 z-20 flex items-center justify-center gap-2 rounded-lg border border-solid text-sm"
+      :class="
+        muteOverlay.icon === 'ant-design:stop-outlined'
+          ? 'message-input__mute-overlay--error'
+          : 'message-input__mute-overlay--warning'
+      "
+    >
+      <Icon :icon="muteOverlay.icon" :size="18" />
+      <span>{{ muteOverlay.text }}</span>
+    </div>
+    <!-- 内层白色圆角卡片 = editor + 工具栏；border + rounded 模拟微信「输入框」边界 -->
+    <div
+      class="relative flex flex-col bg-[var(--ant-color-bg-container)] rounded-lg border border-solid border-[var(--im-border-color-lighter)]"
+    >
+      <!--
+        输入区在上：contenteditable div（取代 textarea，对齐微信 PC：输入区在上，操作在下）
+        - 让 @ 浮层能拿到真实光标 rect（textarea 拿不到）
+        - 让 @ 成员以 <span data-id> token 节点存在，删 token 即删 id，避免 stale atUserIds
+        - placeholder 通过 data-empty + ::before 模拟（contenteditable 没有原生 placeholder）
+      -->
+      <div
+        ref="editorRef"
+        class="message-input__editor relative min-h-[120px] max-h-[200px] overflow-y-auto py-3.5 px-4 text-sm leading-normal outline-none whitespace-pre-wrap break-words"
+        contenteditable="true"
+        data-placeholder="按 Enter 发送，Shift+Enter 换行"
+        data-empty=""
+        role="textbox"
+        @keydown="onKeydown"
+        @input="onInput"
+        @scroll.passive="onEditorScroll"
+        @paste.prevent="onPaste"
+      ></div>
+
+      <!-- 引用预览条 -->
+      <ReplyPreview
+        v-if="replyTarget"
+        :quote="replyTarget"
+        closable
+        class="mx-3 mb-1.5"
+        @close="clearConversationReplyDraft"
+      />
+
+      <!--
+        底部工具栏：左侧操作图标 + 右侧发送按钮（对齐微信 PC：操作图标统一放底部）
+        - relative 给 FacePicker 提供 absolute 锚点，picker 用 bottom-full 向上弹出
+        - 图标统一 30×30 点击区（18px icon + p-1.5），gap-1 让间距贴合微信观感
+        - border-t 在编辑区与工具栏之间画一条与 card 边框同色的细线
+      -->
+      <div
+        class="relative flex items-center justify-between gap-2 px-3 py-2 border-t border-t-solid border-[var(--im-border-color-lighter)]"
+      >
+        <div class="flex items-center gap-1">
+          <!--
+            所有 icon 统一走 Iconify 线性图标：
+            - 视觉风格更接近微信 PC（线性、圆角，比 Element Plus 内置的更轻量）
+            - 笑脸 / 图片 / 文件夹 / 麦克风 同源，避免和 Element Plus 内置图标视觉割裂
+            - 外层 span 复用 .message-input__tool 的 padding / hover 样式，scoped CSS 的 :deep(svg) 仍能命中
+          -->
+          <ElTooltip content="表情" placement="top">
+            <span
+              class="message-input__tool inline-flex items-center justify-center box-content p-1.5 cursor-pointer rounded transition-colors hover:bg-[var(--ant-color-fill)]"
+              @click.stop="toggleEmoji"
+            >
+              <Icon icon="ant-design:smile-outlined" :size="18" />
+            </span>
+          </ElTooltip>
+          <ElTooltip content="发送图片" placement="top">
+            <span
+              class="message-input__tool inline-flex items-center justify-center box-content p-1.5 cursor-pointer rounded transition-colors hover:bg-[var(--ant-color-fill)]"
+              @click="imageInputRef?.click()"
+            >
+              <Icon icon="ant-design:picture-outlined" :size="18" />
+            </span>
+          </ElTooltip>
+          <ElTooltip content="发送文件" placement="top">
+            <span
+              class="message-input__tool inline-flex items-center justify-center box-content p-1.5 cursor-pointer rounded transition-colors hover:bg-[var(--ant-color-fill)]"
+              @click="fileInputRef?.click()"
+            >
+              <Icon icon="ant-design:folder-outlined" :size="18" />
+            </span>
+          </ElTooltip>
+          <ElTooltip content="语音消息" placement="top">
+            <span
+              class="message-input__tool inline-flex items-center justify-center box-content p-1.5 cursor-pointer rounded transition-colors hover:bg-[var(--ant-color-fill)]"
+              @click.stop="openVoice"
+            >
+              <Icon icon="ant-design:audio-outlined" :size="18" />
+            </span>
+          </ElTooltip>
+          <ElTooltip content="发送视频" placement="top">
+            <span
+              class="message-input__tool inline-flex items-center justify-center box-content p-1.5 cursor-pointer rounded transition-colors hover:bg-[var(--ant-color-fill)]"
+              @click="videoInputRef?.click()"
+            >
+              <Icon icon="ant-design:video-camera-outlined" :size="18" />
+            </span>
+          </ElTooltip>
+        </div>
+
+        <!-- 群聊 + 群已读开启：发送按钮 + ▼ 下拉菜单（点主按钮普通发送 / 点 ▼ 选「发送回执消息」） -->
+        <ElDropdown
+          v-if="isGroup && MESSAGE_GROUP_READ_ENABLED"
+          split-button
+          type="primary"
+          :disabled="!canSend"
+          @click="handleSend()"
+          @command="handleSendMenuClick"
+        >
+          发 送
+          <template #dropdown>
+            <ElDropdownMenu>
+              <ElDropdownItem command="receipt">发送回执消息</ElDropdownItem>
+            </ElDropdownMenu>
+          </template>
+        </ElDropdown>
+        <!-- 私聊或群已读关闭：普通发送按钮（无群回执入口） -->
+        <ElButton v-else type="primary" :disabled="!canSend" @click="handleSend()">
+          发 送
+        </ElButton>
+
+        <!-- 表情面板：bottom-full 让 picker 下沿贴工具栏顶部，向上弹出（对齐工具栏左侧首图标） -->
+        <FacePicker
+          v-model:visible="emojiVisible"
+          class="bottom-full left-3 mb-2"
+          @select-emoji="insertText"
+          @select-face="onSelectFace"
+        />
+
+        <!-- 语音录制面板：与表情面板同处工具栏，bottom-full 向上弹出，避免离触发的麦克风图标过远 -->
+        <VoiceRecorder v-model="voiceVisible" class="bottom-full left-3 mb-2" @send="onVoiceSend" />
+      </div>
+    </div>
+
+    <!-- @ 选择浮层：群聊才启用 -->
+    <MentionPicker
+      ref="mentionRef"
+      v-model:visible="mentionVisible"
+      :position="mentionPosition"
+      :members="groupMembers"
+      :search-text="mentionSearchText"
+      :can-at-all="canAtAll"
+      @select="onMentionSelect"
+    />
+
+    <!-- 隐藏的文件选择器 -->
+    <input ref="imageInputRef" type="file" accept="image/*" hidden @change="onImagePicked" />
+    <input ref="fileInputRef" type="file" hidden @change="onFilePicked" />
+    <input ref="videoInputRef" type="file" accept="video/*" hidden @change="onVideoPicked" />
+  </div>
+</template>
+
+<style scoped>
+/* el-icon 全局规则 .el-icon{color:var(--color,inherit); font-size:inherit; width:1em; height:1em} 优先级更高，
+   用字面选择器 + !important 锁死；颜色取 Element Plus 主题变量，暗色自动切到浅灰 */
+.message-input__tool,
+.message-input__tool:deep(svg) {
+  font-size: 18px !important;
+  color: var(--ant-color-text) !important;
+  fill: currentColor !important;
+}
+.message-input__tool:hover,
+.message-input__tool:hover:deep(svg) {
+  color: var(--ant-color-primary) !important;
+}
+
+.message-input__mute-overlay--warning {
+  color: #d48806;
+  background: #fff7e6;
+  border-color: #ffd591;
+}
+
+.message-input__mute-overlay--error {
+  color: #cf1322;
+  background: #fff1f0;
+  border-color: #ffa39e;
+}
+
+/* 注意：必须把 .dark 与目标类整体放进 :global()，否则 Vue scoped 编译会把
+   `:global(.dark) .xxx` 错误塌缩成裸 `.dark`，导致这些颜色被直接刷到 <html> 上
+   （暗色下整页发红/发暗黄）。BEM 类名唯一，整体 global 不会误伤其它元素。 */
+:global(.dark .message-input__mute-overlay--warning) {
+  color: #ffd666;
+  background: rgb(77 56 21 / 88%);
+  border-color: #ad6800;
+}
+
+:global(.dark .message-input__mute-overlay--error) {
+  color: #ff7875;
+  background: rgb(91 33 33 / 88%);
+  border-color: #a8071a;
+}
+
+/* 用 data-empty 而非 :empty：浏览器在删空后会留下 <br>，:empty 不命中；data-empty 由 syncEditorState 维护 */
+.message-input__editor[data-empty]::before {
+  content: attr(data-placeholder);
+  color: var(--ant-color-text-placeholder);
+  pointer-events: none;
+  position: absolute;
+}
+
+/* @ token 走主色高亮；contenteditable=false 让 backspace 整段删而不是逐字符 */
+.message-input__editor :deep(.mention-token) {
+  color: var(--ant-color-primary);
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/input/message-multi-select-bar.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/input/message-multi-select-bar.vue
new file mode 100644
index 000000000..74edcaced
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/input/message-multi-select-bar.vue
@@ -0,0 +1,153 @@
+<script lang="ts" setup>
+import type { Message } from '#/views/im/home/types'
+
+import { computed, inject } from 'vue'
+
+import { confirm } from '@vben/common-ui'
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { useMessageMultiSelect } from '#/views/im/home/composables/useMessageMultiSelect'
+import { useConversationStore } from '#/views/im/home/store/conversationStore'
+import { useMessageStore } from '#/views/im/home/store/messageStore'
+import { ImForwardMode, isNormalMessage } from '#/views/im/utils/constants'
+import { getClientConversationId } from '#/views/im/utils/db'
+
+import { IM_FORWARD_DIALOG_KEY } from '../message/forward/keys'
+
+defineOptions({ name: 'ImMessageMultiSelectBar' })
+
+const conversationStore = useConversationStore()
+const messageStore = useMessageStore()
+const openForwardDialog = inject(IM_FORWARD_DIALOG_KEY)
+const multiSelect = useMessageMultiSelect()
+
+/** 选中条数 */
+const selectedCount = computed(() => multiSelect.state.selectedClientMessageIds.length)
+
+/** 当前会话内已选消息 */
+function getSelectedMessages(): Message[] {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return []
+  }
+  const ids = multiSelect.selectedIdSet.value
+  return messageStore
+    .getMessages(getClientConversationId(conversation.type, conversation.targetId))
+    .filter((message) => ids.has(message.clientMessageId) && isNormalMessage(message.type))
+}
+
+/** 逐条转发：开 ForwardDialog 单条模式 */
+function handleForwardOneByOne() {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  const messages = getSelectedMessages()
+  if (messages.length === 0) {
+    return
+  }
+  openForwardDialog?.({
+    mode: ImForwardMode.SINGLE,
+    messages,
+    sourceConversation: conversation
+  })
+}
+
+/** 合并转发：开 ForwardDialog 合并模式 */
+function handleForwardMerged() {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  const messages = getSelectedMessages()
+  if (messages.length === 0) {
+    return
+  }
+  openForwardDialog?.({
+    mode: ImForwardMode.MERGE,
+    messages,
+    sourceConversation: conversation
+  })
+}
+
+/** 删除：弹确认框 → 本地批量移除（不同步后端，对齐微信「删除」语义） */
+async function handleDelete() {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  const messages = getSelectedMessages()
+  if (messages.length === 0) {
+    return
+  }
+  try {
+    await confirm(`确认删除选中的 ${messages.length} 条消息？`, {
+      cancelText: '取消',
+      confirmText: '确定',
+      icon: 'warning',
+      title: '删除确认'
+    })
+  } catch {
+    return
+  }
+  for (const m of messages) {
+    messageStore.removeMessage(conversation.type, conversation.targetId, {
+      id: m.id,
+      clientMessageId: m.clientMessageId
+    })
+  }
+  multiSelect.exit()
+}
+
+/** 取消多选 */
+function handleCancel() {
+  multiSelect.exit()
+}
+</script>
+
+<template>
+  <div
+    v-if="multiSelect.state.active"
+    class="flex items-center justify-center gap-12 px-5 w-full h-full border-t border-t-solid bg-[var(--ant-color-bg-container)] border-[var(--im-border-color-lighter)]"
+  >
+    <span
+      class="absolute left-5 top-1/2 -translate-y-1/2 text-12px text-[var(--ant-color-text-secondary)]"
+    >
+      已选 {{ selectedCount }} 条
+    </span>
+
+    <button
+      class="inline-flex flex-col items-center gap-1 px-3 py-1 text-12px rounded-md border-0 bg-transparent cursor-pointer transition-colors text-[var(--ant-color-text)] hover:text-[var(--ant-color-primary)] hover:bg-[var(--ant-color-fill)] disabled:text-[var(--ant-color-text-disabled)] disabled:cursor-not-allowed disabled:bg-transparent"
+      :disabled="selectedCount === 0"
+      @click="handleForwardOneByOne"
+    >
+      <Icon icon="ant-design:share-alt-outlined" :size="22" />
+      <span>逐条转发</span>
+    </button>
+
+    <button
+      class="inline-flex flex-col items-center gap-1 px-3 py-1 text-12px rounded-md border-0 bg-transparent cursor-pointer transition-colors text-[var(--ant-color-text)] hover:text-[var(--ant-color-primary)] hover:bg-[var(--ant-color-fill)] disabled:text-[var(--ant-color-text-disabled)] disabled:cursor-not-allowed disabled:bg-transparent"
+      :disabled="selectedCount === 0"
+      @click="handleForwardMerged"
+    >
+      <Icon icon="tabler:arrow-merge" :size="22" />
+      <span>合并转发</span>
+    </button>
+
+    <button
+      class="inline-flex flex-col items-center gap-1 px-3 py-1 text-12px rounded-md border-0 bg-transparent cursor-pointer transition-colors text-[var(--ant-color-text)] hover:bg-[var(--ant-color-fill)] hover:text-[var(--ant-color-error)] disabled:text-[var(--ant-color-text-disabled)] disabled:cursor-not-allowed disabled:bg-transparent"
+      :disabled="selectedCount === 0"
+      @click="handleDelete"
+    >
+      <Icon icon="ant-design:delete-outlined" :size="22" />
+      <span>删除</span>
+    </button>
+
+    <button
+      class="absolute right-5 top-1/2 -translate-y-1/2 inline-flex items-center justify-center w-7 h-7 rounded-full border-0 bg-transparent cursor-pointer transition-colors text-[var(--ant-color-text-secondary)] hover:text-[var(--ant-color-text)] hover:bg-[var(--ant-color-fill)]"
+      @click="handleCancel"
+    >
+      <Icon icon="ant-design:close-outlined" :size="20" />
+    </button>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/input/voice-recorder.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/input/voice-recorder.vue
new file mode 100644
index 000000000..f2709cdeb
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/input/voice-recorder.vue
@@ -0,0 +1,340 @@
+<script lang="ts" setup>
+import {
+  computed,
+  onBeforeUnmount,
+  onMounted,
+  onUnmounted,
+  ref,
+  useTemplateRef,
+  watch
+} from 'vue'
+
+import { ElButton, ElMessage } from 'element-plus'
+
+import { formatSeconds } from '#/views/im/utils/time'
+
+defineOptions({ name: 'ImVoiceRecorder' })
+
+const props = withDefaults(
+  defineProps<{
+    maxDuration?: number // 最长录制秒数
+    modelValue: boolean // 是否显示
+  }>(),
+  {
+    maxDuration: 60
+  }
+)
+
+const emit = defineEmits<{
+  send: [payload: { blob: Blob; duration: number; extension: string; mimeType: string }] // 录制完成数据
+  'update:modelValue': [value: boolean]
+}>()
+
+const VOICE_MIME_TYPE_OPTIONS = [
+  { extension: 'webm', mimeType: 'audio/webm;codecs=opus' },
+  { extension: 'webm', mimeType: 'audio/webm' },
+  { extension: 'm4a', mimeType: 'audio/mp4' },
+  { extension: 'ogg', mimeType: 'audio/ogg;codecs=opus' },
+  { extension: 'ogg', mimeType: 'audio/ogg' }
+]
+
+const visible = computed({
+  get: () => props.modelValue,
+  set: (v) => emit('update:modelValue', v)
+})
+
+const rootRef = useTemplateRef<HTMLDivElement>('rootRef')
+
+/** 录制状态 */
+type Status = 'idle' | 'preview' | 'recording'
+const status = ref<Status>('idle')
+const duration = ref(0)
+const previewUrl = ref('')
+
+let mediaRecorder: MediaRecorder | null = null
+let audioChunks: Blob[] = []
+let mediaStream: MediaStream | null = null
+let timer: null | ReturnType<typeof setInterval> = null
+let recordedBlob: Blob | null = null
+let discarding = false
+let recordingMimeType = ''
+let recordingExtension = ''
+let recordedMimeType = ''
+let recordedExtension = ''
+
+/** 计时器文案 */
+const timerText = computed(() => formatSeconds(duration.value))
+
+/** 监听面板显示状态 */
+watch(visible, (v) => {
+  if (v) {
+    document.addEventListener('click', handleDocumentClick)
+  } else {
+    document.removeEventListener('click', handleDocumentClick)
+    resetAll()
+  }
+})
+
+/** 处理外部点击 */
+function handleDocumentClick(e: MouseEvent) {
+  if (!props.modelValue || !rootRef.value) {
+    return
+  }
+  if (rootRef.value.contains(e.target as Node)) {
+    return
+  }
+  if (status.value !== 'idle') {
+    return
+  }
+  visible.value = false
+}
+
+/** 获取支持的录音格式 */
+function getSupportedVoiceMimeType() {
+  if (typeof MediaRecorder === 'undefined' || !MediaRecorder.isTypeSupported) {
+    return undefined
+  }
+  return VOICE_MIME_TYPE_OPTIONS.find((item) => MediaRecorder.isTypeSupported(item.mimeType))
+}
+
+/** 获取录音文件后缀 */
+function getVoiceExtension(mimeType: string) {
+  const normalizedMimeType = mimeType.split(';')[0]
+  if (normalizedMimeType === 'audio/mp4') {
+    return 'm4a'
+  }
+  if (normalizedMimeType === 'audio/ogg') {
+    return 'ogg'
+  }
+  return 'webm'
+}
+
+/** 创建录音器 */
+function createVoiceRecorder(stream: MediaStream) {
+  const supportedMimeType = getSupportedVoiceMimeType()
+  const recorder = supportedMimeType
+    ? new MediaRecorder(stream, { mimeType: supportedMimeType.mimeType })
+    : new MediaRecorder(stream)
+  recordingMimeType = recorder.mimeType || supportedMimeType?.mimeType || ''
+  recordingExtension = supportedMimeType?.extension || (recordingMimeType ? getVoiceExtension(recordingMimeType) : '')
+  return recorder
+}
+
+/** 开始录制 */
+async function startRecord() {
+  if (typeof MediaRecorder === 'undefined' || !navigator.mediaDevices?.getUserMedia) {
+    ElMessage.error('当前浏览器不支持录音（需要 HTTPS 或 localhost）')
+    return
+  }
+  try {
+    mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true })
+  } catch {
+    ElMessage.error('无法获取麦克风权限')
+    return
+  }
+  audioChunks = []
+  discarding = false
+  try {
+    mediaRecorder = createVoiceRecorder(mediaStream)
+  } catch {
+    cleanupStream()
+    ElMessage.error('当前浏览器不支持录音格式')
+    return
+  }
+  mediaRecorder.addEventListener('dataavailable', (event: BlobEvent) => {
+    if (event.data.size > 0) {
+      audioChunks.push(event.data)
+    }
+  })
+  mediaRecorder.addEventListener('stop', () => {
+    if (discarding) {
+      return
+    }
+    recordedMimeType = recordingMimeType || mediaRecorder?.mimeType || audioChunks[0]?.type || 'audio/webm'
+    recordedExtension = recordingExtension || getVoiceExtension(recordedMimeType)
+    recordedBlob = new Blob(audioChunks, { type: recordedMimeType })
+    previewUrl.value = URL.createObjectURL(recordedBlob)
+    status.value = 'preview'
+  })
+  mediaRecorder.start()
+  status.value = 'recording'
+  duration.value = 0
+  timer = setInterval(() => {
+    duration.value++
+    if (duration.value >= props.maxDuration) {
+      stopRecord()
+    }
+  }, 1000)
+}
+
+/** 停止录制 */
+function stopRecord() {
+  if (duration.value < 1) {
+    ElMessage.warning('录音时间太短')
+    resetAll()
+    return
+  }
+  if (mediaRecorder && mediaRecorder.state !== 'inactive') {
+    mediaRecorder.stop()
+  }
+  cleanupStream()
+  if (timer) {
+    clearInterval(timer)
+    timer = null
+  }
+}
+
+/** 重新录制 */
+function restart() {
+  clearPreview()
+  duration.value = 0
+  status.value = 'idle'
+}
+
+/** 发送录音 */
+function handleSend() {
+  if (!recordedBlob) {
+    return
+  }
+  emit('send', {
+    blob: recordedBlob,
+    duration: duration.value,
+    extension: recordedExtension,
+    mimeType: recordedMimeType || recordedBlob.type
+  })
+  visible.value = false
+}
+
+/** 取消录制 */
+function handleCancel() {
+  visible.value = false
+}
+
+/** 重置录制资源 */
+function resetAll() {
+  discarding = true
+  if (mediaRecorder && mediaRecorder.state !== 'inactive') {
+    mediaRecorder.stop()
+  }
+  cleanupStream()
+  if (timer) {
+    clearInterval(timer)
+    timer = null
+  }
+  audioChunks = []
+  duration.value = 0
+  status.value = 'idle'
+  recordingMimeType = ''
+  recordingExtension = ''
+  recordedMimeType = ''
+  recordedExtension = ''
+  clearPreview()
+}
+
+/** 释放预览音频 */
+function clearPreview() {
+  recordedBlob = null
+  if (previewUrl.value) {
+    URL.revokeObjectURL(previewUrl.value)
+    previewUrl.value = ''
+  }
+}
+
+/** 关闭麦克风采集 */
+function cleanupStream() {
+  mediaStream?.getTracks().forEach((t) => t.stop())
+  mediaStream = null
+}
+
+onMounted(() => {
+  if (props.modelValue) {
+    document.addEventListener('click', handleDocumentClick)
+  }
+})
+
+onBeforeUnmount(resetAll)
+
+onUnmounted(() => {
+  document.removeEventListener('click', handleDocumentClick)
+})
+</script>
+
+<template>
+  <!-- 语音录制面板 -->
+  <div
+    v-if="visible"
+    ref="rootRef"
+    class="im-popover-arrow absolute z-100 w-80 p-4 rounded-md bg-[var(--ant-color-bg-container)] shadow-[0_4px_16px_rgba(0,0,0,0.12)]"
+    @click.stop
+  >
+    <div class="flex flex-col items-center gap-3">
+      <!-- 录制时长 -->
+      <div class="text-[28px] font-medium tabular-nums text-[var(--ant-color-text)]">
+        {{ timerText }}
+      </div>
+
+      <!-- 状态文案 -->
+      <div class="text-13px text-[var(--ant-color-text-secondary)]">
+        <span v-if="status === 'idle'">点击下方按钮开始录制</span>
+        <span v-else-if="status === 'recording'">录制中，最长 {{ maxDuration }} 秒</span>
+        <span v-else>录制完成，可试听后发送</span>
+      </div>
+
+      <!-- 录制状态 -->
+      <div
+        v-if="status !== 'preview'"
+        class="w-12 h-12 rounded-full bg-[var(--ant-color-border)]"
+        :class="{ 'im-voice-recorder__pulse bg-[#f56c6c]': status === 'recording' }"
+      ></div>
+      <audio v-else :src="previewUrl" controls class="w-full"></audio>
+    </div>
+
+    <!-- 操作按钮 -->
+    <div class="flex justify-end gap-2 mt-3">
+      <template v-if="status === 'idle'">
+        <ElButton size="small" @click="handleCancel">取消</ElButton>
+        <ElButton size="small" type="primary" @click="startRecord">开始录制</ElButton>
+      </template>
+      <template v-else-if="status === 'recording'">
+        <ElButton size="small" @click="handleCancel">取消</ElButton>
+        <ElButton size="small" type="primary" @click="stopRecord">停止录制</ElButton>
+      </template>
+      <template v-else>
+        <ElButton size="small" @click="handleCancel">取消</ElButton>
+        <ElButton size="small" @click="restart">重新录制</ElButton>
+        <ElButton size="small" type="primary" @click="handleSend">发送</ElButton>
+      </template>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* 底部小三角 */
+.im-popover-arrow::after {
+  content: '';
+  position: absolute;
+  top: calc(100% - 1px);
+  left: 110px;
+  border-style: solid;
+  border-width: 6px 6px 0 6px;
+  border-color: var(--ant-color-bg-container) transparent transparent transparent;
+  filter: drop-shadow(0 2px 2px rgba(0, 0, 0, 0.08));
+}
+
+/* 录音中的脉冲动画 */
+.im-voice-recorder__pulse {
+  animation: im-voice-pulse 1s infinite;
+}
+
+@keyframes im-voice-pulse {
+  0% {
+    box-shadow: 0 0 0 0 rgba(245, 108, 108, 0.6);
+  }
+  70% {
+    box-shadow: 0 0 0 20px rgba(245, 108, 108, 0);
+  }
+  100% {
+    box-shadow: 0 0 0 0 rgba(245, 108, 108, 0);
+  }
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/index.ts b/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/index.ts
new file mode 100644
index 000000000..5e83f77c4
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/index.ts
@@ -0,0 +1,2 @@
+export { default as MessageForwardDialog } from './message-forward-dialog.vue';
+export { default as MessageMergeDetailDialog } from './message-merge-detail-dialog.vue';
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/keys.ts b/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/keys.ts
new file mode 100644
index 000000000..f76c1919c
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/keys.ts
@@ -0,0 +1,24 @@
+import type { InjectionKey } from 'vue'
+
+import type { Conversation, Message } from '#/views/im/home/types'
+import type { ImForwardModeValue } from '#/views/im/utils/constants'
+
+/** 打开转发弹窗 */
+export type OpenForwardDialog = (opts: {
+  messages: Message[]
+  mode: ImForwardModeValue
+  sourceConversation: Conversation
+}) => void
+
+/** 打开合并消息详情弹窗 */
+export type OpenMergeDetailDialog = (content: string) => void
+
+/** 重拨 RTC 通话；点私聊 RTC_CALL_END 气泡触发 */
+export type RtcRedial = (mediaType: number) => void
+
+/** MessagePanel 通过 provide 暴露给子树 */
+export const IM_FORWARD_DIALOG_KEY: InjectionKey<OpenForwardDialog> = Symbol('IM_FORWARD_DIALOG')
+export const IM_MERGE_DETAIL_DIALOG_KEY: InjectionKey<OpenMergeDetailDialog> = Symbol(
+  'IM_MERGE_DETAIL_DIALOG'
+)
+export const IM_RTC_REDIAL_KEY: InjectionKey<RtcRedial> = Symbol('IM_RTC_REDIAL')
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/message-forward-dialog.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/message-forward-dialog.vue
new file mode 100644
index 000000000..0488418e0
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/message-forward-dialog.vue
@@ -0,0 +1,446 @@
+<script lang="ts" setup>
+import type { Conversation, FriendLite, Message } from '#/views/im/home/types'
+
+import { computed, reactive, ref } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElButton, ElDialog, ElInput, ElMessage } from 'element-plus'
+
+import { createGroup } from '#/api/im/group'
+import { ConversationPickerPanel } from '#/views/im/home/components/picker'
+import { FriendPickerPanel } from '#/views/im/home/components/picker'
+import { useMessageMultiSelect } from '#/views/im/home/composables/useMessageMultiSelect'
+import { useMessageSender } from '#/views/im/home/composables/useMessageSender'
+import { useConversationStore } from '#/views/im/home/store/conversationStore'
+import { useFriendStore } from '#/views/im/home/store/friendStore'
+import { useGroupStore } from '#/views/im/home/store/groupStore'
+import { MESSAGE_MERGE_PREVIEW_LINES } from '#/views/im/utils/config'
+import {
+  ImContentType,
+  ImConversationType,
+  ImForwardMode,
+  type ImForwardModeValue
+} from '#/views/im/utils/constants'
+import { getConversationKey, summarizeMessageContent } from '#/views/im/utils/conversation'
+import { buildDefaultGroupName } from '#/views/im/utils/group'
+import {
+  buildMergeMessagePayload,
+  removeQuotePayload,
+  serializeMessage
+} from '#/views/im/utils/message'
+import { getGroupDisplayName, isGroupQuit } from '#/views/im/utils/user'
+
+import { FacePicker } from '../../input'
+
+defineOptions({ name: 'ImMessageForwardDialog' })
+
+const conversationStore = useConversationStore()
+const friendStore = useFriendStore()
+const groupStore = useGroupStore()
+const { sendRaw, send } = useMessageSender()
+const multiSelect = useMessageMultiSelect()
+
+const state = reactive({
+  mode: ImForwardMode.SINGLE as ImForwardModeValue,
+  messages: [] as Message[],
+  sourceConversation: null as Conversation | null
+})
+const visible = ref(false)
+const view = ref<'contact' | 'conversation'>('conversation') // 当前视图：默认会话选择，「创建聊天」入口切到好友选择
+const selectedKeys = ref<string[]>([])
+const selectedFriendIds = ref<number[]>([])
+const leaveMessage = ref('')
+const sending = ref(false)
+const emojiVisible = ref(false) // emoji picker 显隐：右侧笑脸按钮切换
+
+defineExpose({
+  /** 打开转发弹窗：reset → 灌参 → visible=true */
+  open(opts: { messages: Message[]; mode: ImForwardModeValue; sourceConversation: Conversation }) {
+    state.mode = opts.mode
+    state.messages = opts.messages
+    state.sourceConversation = opts.sourceConversation
+    view.value = 'conversation'
+    selectedKeys.value = []
+    selectedFriendIds.value = []
+    leaveMessage.value = ''
+    emojiVisible.value = false
+    sending.value = false
+    visible.value = true
+  }
+})
+
+/** 弹窗标题：会话视图按 mode 区分「逐条 / 合并转发」；好友视图固定为「选择好友」 */
+const headerTitle = computed(() => {
+  if (view.value === 'contact') {
+    return '选择好友'
+  }
+  return state.mode === ImForwardMode.MERGE ? '合并转发' : '逐条转发'
+})
+
+/** 确认按钮文案：单选「发送」、多选「分别发送(n)」 */
+const confirmButtonText = computed(() =>
+  selectedKeys.value.length > 1 ? `分别发送（${selectedKeys.value.length}）` : '发送'
+)
+
+/** 候选会话：从 store 拿排序后的列表（转发回原会话也允许，与微信一致）；公众号 / 频道单向消息不接受转发，从候选里剔除 */
+const candidateConversations = computed<Conversation[]>(() =>
+  conversationStore.getSortedConversationList.filter(
+    (conversation) =>
+      conversation.type !== ImConversationType.CHANNEL &&
+      // 历史退群群不可被转发选中（选了后端也会拒）
+      !(
+        conversation.type === ImConversationType.GROUP &&
+        isGroupQuit(groupStore.getGroup(conversation.targetId))
+      )
+  )
+)
+
+/** 好友视图候选列表：直接复用 friendStore Lite 视图 */
+const friends = computed<FriendLite[]>(() => friendStore.getActiveFriendLiteList)
+
+/** 切到好友视图：清掉之前在会话视图输入的留言，避免在不可见输入框里把留言静默发到新群 */
+function handleSwitchToContact() {
+  view.value = 'contact'
+  leaveMessage.value = ''
+  emojiVisible.value = false
+}
+
+/** 选中 emoji：拼到留言末尾；FacePicker 自身负责关闭面板 */
+function handleEmojiSelect(emoji: string) {
+  leaveMessage.value = `${leaveMessage.value}${emoji}`
+}
+
+/** 合并 payload + 序列化 content；merge 模式下一次构造，预览 / 发送共用 */
+const mergeBundle = computed(() => {
+  if (
+    state.mode !== ImForwardMode.MERGE ||
+    !state.sourceConversation ||
+    state.messages.length === 0
+  ) {
+    return null
+  }
+  const payload = buildMergeMessagePayload(state.messages, state.sourceConversation)
+  return { payload, content: serializeMessage(payload) }
+})
+
+/** 合并模式预览：从 messages 前 N 条派生「{昵称}：{摘要}」 */
+const mergePreview = computed(() => {
+  const payload = mergeBundle.value?.payload
+  if (!payload) {
+    return null
+  }
+  const lines = payload.messages
+    .slice(0, MESSAGE_MERGE_PREVIEW_LINES)
+    .map((item) => `${item.senderNickname}：${summarizeMessageContent(item)}`)
+  return { title: payload.title, lines }
+})
+
+/** 逐条模式预览：取前 N 条摘要 */
+const singlePreviewLines = computed(() =>
+  state.messages.slice(0, MESSAGE_MERGE_PREVIEW_LINES).map((m) => summarizeMessageContent(m))
+)
+
+/** 待发送的逐条消息：剥离 quote 一次，发送多目标时复用 */
+const cleanedSinglePayloads = computed(() =>
+  state.messages.map((m) => ({ type: m.type, content: removeQuotePayload(m.content) }))
+)
+
+/**
+ * 给单个目标发送转发消息：merge 一次 sendRaw、single 按时间序逐条 sendRaw
+ *
+ * 任一原消息失败即停止后续，返回 false 让上层跳过留言
+ */
+async function forwardToTarget(target: Conversation): Promise<boolean> {
+  if (state.mode === ImForwardMode.MERGE) {
+    const content = mergeBundle.value?.content
+    if (!content) {
+      return false
+    }
+    return sendRaw(ImContentType.MERGE, content, { conversation: target })
+  }
+  for (const payload of cleanedSinglePayloads.value) {
+    const ok = await sendRaw(payload.type, payload.content, { conversation: target })
+    if (!ok) {
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * 确认发送：单条模式逐条循环；合并模式发一条 MergeMessage
+ *
+ * 文案聚合：全部成功「已转发」、全部失败「转发失败：A、B」、部分失败「已转发，但 X、Y 失败」；
+ * 留言只在该目标的转发消息全部成功后才追加，避免错序
+ */
+async function handleSend() {
+  if (selectedKeys.value.length === 0) {
+    return
+  }
+  if (state.messages.length === 0) {
+    ElMessage.warning('没有可转发的消息')
+    return
+  }
+  // 反查已选 conversation 对象（按 selectedKeys 数组顺序，即点击顺序）
+  const candidates = candidateConversations.value
+  const byKey = new Map(candidates.map((c) => [getConversationKey(c), c]))
+  const targets = selectedKeys.value
+    .map((key) => byKey.get(key))
+    .filter((c): c is Conversation => c != null)
+  if (targets.length === 0) {
+    return
+  }
+  const leaveText = leaveMessage.value.trim()
+  sending.value = true
+  try {
+    const tasks = targets.map(async (target) => {
+      const forwardOk = await forwardToTarget(target)
+      if (!forwardOk) {
+        return { target, ok: false }
+      }
+      const ok = leaveText ? await send(leaveText, { conversation: target }) : true
+      return { target, ok }
+    })
+    const results = await Promise.all(tasks)
+    const failedNames = results.filter((r) => !r.ok).map((r) => r.target.name || '未命名会话')
+    // 命中的目标统一推到最近转发列表（部分失败也推：用户的"意图"已表达）
+    conversationStore.pushRecentForwardConversationKeyList(targets.map((c) => getConversationKey(c)))
+    if (failedNames.length === 0) {
+      ElMessage.success('已转发')
+    } else if (failedNames.length === targets.length) {
+      ElMessage.error(`转发失败：${failedNames.join('、')}`)
+    } else {
+      ElMessage.warning(`已转发，但 ${failedNames.join('、')} 失败`)
+    }
+    if (multiSelect.state.active) {
+      multiSelect.exit()
+    }
+    visible.value = false
+  } finally {
+    sending.value = false
+  }
+}
+
+/**
+ * 好友视图发送：先建群（同时邀请所选好友）→ 给新群复用 forwardToTarget 转发 → 发留言 → 关弹窗
+ *
+ * 跟会话视图的差别：先要 createGroup 拿到 groupId，之后构造 GROUP 临时 conversation 喂给已有的 forwardToTarget
+ * （sendRaw 内部会自动 insertMessage 把新群登记进 store，最近转发列表也能正常推）
+ */
+async function handleCreateGroupAndSend() {
+  if (selectedFriendIds.value.length === 0) {
+    return
+  }
+  if (state.messages.length === 0) {
+    ElMessage.warning('没有可转发的消息')
+    return
+  }
+  const byId = new Map(friends.value.map((f) => [f.id, f]))
+  const members = selectedFriendIds.value
+    .map((id) => byId.get(id))
+    .filter((f): f is FriendLite => f != null)
+  if (members.length === 0) {
+    return
+  }
+  sending.value = true
+  try {
+    const memberUserIds = members.map((m) => m.id)
+    const name = buildDefaultGroupName(members)
+    const group = await createGroup({ name, memberUserIds, joinApproval: false })
+    if (!group?.id) {
+      throw new Error('创建群失败：未返回群编号')
+    }
+    // upsert 进 groupStore，省一次 fetchGroupList
+    groupStore.upsertGroup({
+      id: group.id,
+      name: group.name,
+      avatar: group.avatar,
+      notice: group.notice,
+      ownerUserId: group.ownerUserId
+    })
+    // 给新群构造一个临时 conversation 对象给 forwardToTarget 用；sendRaw 内部会自动 insertMessage 登记
+    const newConversation: Conversation = {
+      type: ImConversationType.GROUP,
+      targetId: group.id,
+      name: getGroupDisplayName(group) || name,
+      avatar: group.avatar || '',
+      unreadCount: 0,
+      lastContent: '',
+      lastSendTime: 0
+    }
+    const forwardOk = await forwardToTarget(newConversation)
+    if (forwardOk) {
+      const leaveText = leaveMessage.value.trim()
+      if (leaveText) {
+        await send(leaveText, { conversation: newConversation })
+      }
+      conversationStore.pushRecentForwardConversationKeyList([getConversationKey(newConversation)])
+      ElMessage.success('已创建群聊并转发')
+    } else {
+      ElMessage.warning('群已创建，但消息转发失败，请稍后在群里重试')
+    }
+    // 统一退多选 + 关弹窗：成功 / 失败都要退源会话的多选态，避免遗留
+    if (multiSelect.state.active) {
+      multiSelect.exit()
+    }
+    visible.value = false
+  } finally {
+    sending.value = false
+  }
+}
+</script>
+
+<template>
+  <!--
+    转发消息（逐条 / 合并）：选目标会话 + 留言后批量发送
+    - dialog 壳本组件持有；选择 UI 委托 ConversationPickerPanel / FriendPickerPanel
+    - view='conversation'：选已有会话发送（默认视图）
+    - view='contact'：从「创建聊天」入口进入，选好友建群再转发，业务壳层切视图
+    - footer slot 塞预览卡（合并 / 逐条不同视觉）+ 留言 + 提交按钮
+    - 对外接口沿用：ref + open({ mode, messages, sourceConversation })
+  -->
+  <ElDialog
+    v-model="visible"
+    width="720px"
+    :close-on-click-modal="false"
+    
+    class="im-picker-dialog im-forward-dialog"
+  >
+    <template #header>
+      <div class="flex gap-2 items-center">
+        <Icon
+          v-if="view === 'contact'"
+          icon="ant-design:arrow-left-outlined"
+          :size="16"
+          class="cursor-pointer im-forward-dialog__back"
+          @click="view = 'conversation'"
+        />
+        <span class="text-base text-[var(--ant-color-text)]">
+          {{ headerTitle }}
+        </span>
+      </div>
+    </template>
+
+    <div class="h-[480px]">
+      <!-- 会话视图：选已有会话转发 -->
+      <ConversationPickerPanel
+        v-if="view === 'conversation'"
+        v-model:selected-keys="selectedKeys"
+        :conversations="candidateConversations"
+        :recent-forward-conversation-keys="conversationStore.recentForwardConversationKeys"
+        :show-create-chat="true"
+        @create-chat="handleSwitchToContact"
+        @remove-recent="conversationStore.removeRecentForwardConversationKey"
+      >
+        <template #footer>
+          <div class="flex flex-col gap-3 px-4 py-3">
+            <!-- 合并模式预览：「[聊天记录] 标题 + 摘要列表」预览卡 -->
+            <div
+              v-if="state.mode === ImForwardMode.MERGE && mergePreview"
+              class="flex flex-col w-full overflow-hidden rounded-md bg-[var(--ant-color-bg-container)] border border-solid border-[var(--ant-color-border-secondary)]"
+            >
+              <div
+                class="px-3 py-2 text-sm font-medium truncate text-[var(--ant-color-text)]"
+              >
+                {{ mergePreview.title }}
+              </div>
+              <div class="flex flex-col px-3 pb-2 gap-0.5">
+                <div
+                  v-for="(line, idx) in mergePreview.lines"
+                  :key="idx"
+                  class="text-12px text-[var(--ant-color-text-secondary)] truncate"
+                >
+                  {{ line }}
+                </div>
+              </div>
+              <div
+                class="px-3 py-1 text-12px border-t border-t-solid text-[var(--ant-color-text-placeholder)] border-[var(--ant-color-border-secondary)] bg-[var(--ant-color-fill-tertiary)]"
+              >
+                聊天记录
+              </div>
+            </div>
+
+            <!-- 逐条模式预览：消息数 + 首条摘要 -->
+            <div
+              v-else-if="state.mode === ImForwardMode.SINGLE && singlePreviewLines.length > 0"
+              class="flex flex-col w-full overflow-hidden rounded-md bg-[var(--ant-color-bg-container)] border border-solid border-[var(--ant-color-border-secondary)]"
+            >
+              <div class="flex flex-col px-3 py-2 gap-0.5">
+                <div
+                  v-for="(line, idx) in singlePreviewLines"
+                  :key="idx"
+                  class="text-13px text-[var(--ant-color-text)] truncate"
+                >
+                  {{ line }}
+                </div>
+              </div>
+              <div
+                class="px-3 py-1 text-12px border-t border-t-solid text-[var(--ant-color-text-placeholder)] border-[var(--ant-color-border-secondary)] bg-[var(--ant-color-fill-tertiary)]"
+              >
+                共 {{ state.messages.length }} 条消息
+              </div>
+            </div>
+
+            <!-- 留言（单行）：右侧表情按钮触发 FacePicker；选中 emoji 拼到末尾 -->
+            <div class="relative">
+              <ElInput v-model="leaveMessage" :maxlength="100" placeholder="给朋友留言">
+                <template #suffix>
+                  <Icon
+                    icon="ant-design:smile-outlined"
+                    :size="18"
+                    class="cursor-pointer text-[var(--ant-color-text-secondary)] hover:text-[var(--ant-color-primary)]"
+                    @click.stop="emojiVisible = !emojiVisible"
+                  />
+                </template>
+              </ElInput>
+              <FacePicker
+                v-model:visible="emojiVisible"
+                mode="emoji"
+                class="bottom-full right-0 mb-2"
+                @select-emoji="handleEmojiSelect"
+              />
+            </div>
+
+            <div class="flex gap-2 justify-end">
+              <ElButton @click="visible = false">取消</ElButton>
+              <ElButton
+                type="primary"
+                :loading="sending"
+                :disabled="selectedKeys.length === 0"
+                @click="handleSend"
+              >
+                {{ confirmButtonText }}
+              </ElButton>
+            </div>
+          </div>
+        </template>
+      </ConversationPickerPanel>
+
+      <!-- 好友视图：选好友建群后转发 -->
+      <FriendPickerPanel v-else v-model:selected-ids="selectedFriendIds" :friends="friends" />
+    </div>
+
+    <!-- 好友视图的 dialog footer：建群并转发 -->
+    <template v-if="view === 'contact'" #footer>
+      <ElButton @click="visible = false">取消</ElButton>
+      <ElButton
+        type="primary"
+        :loading="sending"
+        :disabled="selectedFriendIds.length === 0"
+        @click="handleCreateGroupAndSend"
+      >
+        创建群聊并发送
+      </ElButton>
+    </template>
+  </ElDialog>
+</template>
+
+<style scoped lang="scss">
+/* 复用选择类弹窗的公共 mixin； 内部是 :deep 穿透 el-dialog 内部 header / body 的样式，无法替换为工具类 */
+@use '#/views/im/home/components/picker/picker-dialog' as picker;
+
+.im-picker-dialog {
+  @include picker.styles;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/message-merge-detail-dialog.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/message-merge-detail-dialog.vue
new file mode 100644
index 000000000..9659cf2e1
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/forward/message-merge-detail-dialog.vue
@@ -0,0 +1,129 @@
+<script lang="ts" setup>
+import { computed, ref } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElDialog } from 'element-plus'
+
+import { UserAvatar } from '#/views/im/home/components/user'
+import { useVoicePlayer } from '#/views/im/home/composables/useVoicePlayer'
+import { type MergeMessage, parseMessage } from '#/views/im/utils/message'
+import { formatMergeItemTime } from '#/views/im/utils/time'
+
+import { MessageBubble } from '..'
+
+defineOptions({ name: 'ImMessageMergeDetailDialog' })
+
+const voicePlayer = useVoicePlayer()
+const visible = ref(false)
+
+const stack = ref<MergeMessage[]>([]) // 嵌套层级栈，存 parsed payload 避免切层重 parse
+
+defineExpose({
+  /** 打开详情弹窗，传入顶层合并消息 content */
+  open(content: string) {
+    const payload = parseMessage<MergeMessage>(content)
+    stack.value = payload ? [payload] : []
+    visible.value = true
+  }
+})
+
+/** 当前层 payload */
+const currentPayload = computed<MergeMessage | null>(
+  () => stack.value[stack.value.length - 1] ?? null
+)
+
+/** 嵌套合并气泡点击：解析 content 后压栈进入下一层 */
+function handleNestedOpen(content: string) {
+  const payload = parseMessage<MergeMessage>(content)
+  if (payload) {
+    stack.value.push(payload)
+  }
+}
+
+/** 顶部返回箭头点击：弹出栈顶回到上一层 */
+function handleBack() {
+  if (stack.value.length > 1) {
+    stack.value.pop()
+  }
+}
+
+/** 弹窗关闭：清栈 + 停语音，下次打开从顶层重新开始 */
+function handleClose() {
+  stack.value = []
+  voicePlayer.stop()
+}
+
+</script>
+
+<template>
+  <ElDialog
+    v-model="visible"
+    width="560px"
+    
+    :close-on-click-modal="false"
+    class="im-merge-detail-dialog"
+    :closable="true"
+    @close="handleClose"
+  >
+    <template #header>
+      <div class="flex items-center gap-2">
+        <Icon
+          v-if="stack.length > 1"
+          icon="ant-design:left-outlined"
+          class="cursor-pointer text-[var(--ant-color-text-secondary)] hover:text-[var(--ant-color-text)]"
+          @click="handleBack"
+        />
+        <span class="text-base font-medium truncate">{{ currentPayload?.title || '聊天记录' }}</span>
+      </div>
+    </template>
+
+    <div v-if="currentPayload" class="flex flex-col h-[480px]">
+      <div
+        class="px-4 py-2 text-12px text-[var(--ant-color-text-secondary)] border-b border-b-solid border-[var(--ant-color-border-secondary)]"
+      >
+        以下是 {{ currentPayload.messages.length }} 条消息
+      </div>
+      <!-- overflow-y-auto：合并消息多时在定高弹窗内可滚动，对齐 Vue3 的 el-scrollbar -->
+      <div class="flex-1 overflow-y-auto">
+        <div
+          v-for="(item, idx) in currentPayload.messages"
+          :key="idx"
+          class="flex gap-3 items-start px-4 py-3 border-b border-b-solid border-[var(--ant-color-border-secondary)]"
+        >
+          <UserAvatar
+            :url="item.senderAvatar"
+            :name="item.senderNickname"
+            :size="36"
+            :clickable="false"
+          />
+          <div class="flex-1 min-w-0">
+            <div class="flex gap-2 items-baseline">
+              <span class="text-13px font-medium text-[var(--ant-color-text)] truncate">
+                {{ item.senderNickname }}
+              </span>
+              <span class="text-12px text-[var(--ant-color-text-secondary)] flex-shrink-0">
+                {{ formatMergeItemTime(item.sendTime) }}
+              </span>
+            </div>
+            <!-- 复用主聊天气泡渲染；MERGE 嵌套点击 push 当前层 -->
+            <div class="mt-1.5">
+              <MessageBubble
+                :type="item.type"
+                :content="item.content"
+                @open-merge="handleNestedOpen($event)"
+              />
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  </ElDialog>
+</template>
+
+<style scoped>
+/* :deep 穿透 el-dialog 内部 body，去掉默认内边距，让滚动区贴边 */
+.im-merge-detail-dialog :deep(.el-dialog__body) {
+  padding: 0;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/group-pinned-message.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/group-pinned-message.vue
new file mode 100644
index 000000000..6534146fd
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/group-pinned-message.vue
@@ -0,0 +1,207 @@
+<script lang="ts" setup>
+import type { Message } from '../../../../types'
+
+import { computed, ref, watch } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElButton, ElMessage } from 'element-plus'
+
+import { unpinGroupMessage as apiUnpinGroupMessage } from '#/api/im/group'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+import { ImConversationType, ImGroupMemberRole } from '#/views/im/utils/constants'
+import { resolveConversationLastContent } from '#/views/im/utils/conversation'
+import { getSenderDisplayName, isGroupQuit } from '#/views/im/utils/user'
+
+import { useGroupStore } from '../../../../store/groupStore'
+
+defineOptions({ name: 'ImGroupPinnedMessage' })
+
+const props = defineProps<{
+  /** 当前群编号（自行从 groupStore 拿完整 Group，跟随响应式） */
+  groupId: number
+}>()
+
+const emit = defineEmits<{
+  /** 点击置顶消息 → 父级 MessagePanel 滚动定位到原消息位置 */
+  locate: [messageId: number]
+}>()
+
+const groupStore = useGroupStore()
+
+/** 当前群（含 pinnedMessages） */
+const group = computed(() => groupStore.getGroup(props.groupId))
+
+const expanded = ref(false)
+const removingId = ref<null | number>(null)
+
+// 切群时重置展开 / 移除中状态：本地 ref 不跟随 groupId，否则上一群"展开"或"移除中"会带到新群
+watch(
+  () => props.groupId,
+  () => {
+    expanded.value = false
+    removingId.value = null
+  }
+)
+
+/** 当前群置顶消息列表（直接走 group.value，跟随响应式） */
+const pinnedMessages = computed<Message[]>(() => group.value?.pinnedMessages ?? [])
+
+/** 顶部胶囊展示的最新一条（即列表最后一条，pin 顺序追加） */
+const latest = computed<Message | null>(
+  () => pinnedMessages.value[pinnedMessages.value.length - 1] ?? null
+)
+
+/** 当前用户是否群主 / 管理员（决定是否显示「移除」入口） */
+const canManage = computed(() => {
+  // 历史退群群：本地缓存残留时也不给「移除」入口
+  if (isGroupQuit(group.value)) {
+    return false
+  }
+  const myId = getCurrentUserId()
+  const role = group.value?.members?.find((m) => m.userId === myId)?.role
+  return role === ImGroupMemberRole.OWNER || role === ImGroupMemberRole.ADMIN
+})
+
+/** 顶部胶囊点击：单条直接跳转原消息位置；多条切换展开 / 折叠 */
+function handleTopClick() {
+  if (!latest.value) {
+    return
+  }
+  if (pinnedMessages.value.length === 1) {
+    handleLocate(latest.value)
+    return
+  }
+  expanded.value = !expanded.value
+}
+
+/** 点击置顶消息行 → 触发跳转 + 收起弹出层 */
+function handleLocate(message: Message) {
+  if (!message.id) {
+    return
+  }
+  emit('locate', message.id)
+  expanded.value = false
+}
+
+/** 置顶消息发送人显示名 */
+function getSenderName(message: Message): string {
+  return group.value
+    ? getSenderDisplayName(message.senderId, ImConversationType.GROUP, group.value.id)
+    : ''
+}
+
+/** 置顶消息预览文本：复用会话最后一条摘要逻辑（[图片] / [文件] / 文本等） */
+function getPreview(message: Message): string {
+  return group.value
+    ? resolveConversationLastContent(message, ImConversationType.GROUP, group.value.id)
+    : ''
+}
+
+/** 移除置顶：调后端 API，loading 期间禁止重复点；后端广播 GROUP_MESSAGE_UNPIN 由 dispatcher 自动同步本地 */
+async function handleRemove(pinnedMessage: Message) {
+  if (!group.value || !pinnedMessage.id || removingId.value !== null) {
+    return
+  }
+  removingId.value = pinnedMessage.id
+  try {
+    await apiUnpinGroupMessage({ id: group.value.id, messageId: pinnedMessage.id })
+    ElMessage.success('已取消置顶')
+  } finally {
+    removingId.value = null
+  }
+}
+</script>
+
+<template>
+  <!-- 群聊置顶消息：仅群聊 + 有置顶时显示，悬挂在群聊头部下方左上角；不占整行（对齐微信 PC） -->
+  <div
+    v-if="latest"
+    class="im-group-pinned-message relative flex flex-shrink-0 flex-col items-start px-4 pt-1.5 pb-2 bg-[var(--ant-color-fill-secondary)]"
+  >
+    <!-- 顶部胶囊：单条点击跳转；多条折叠点击展开；多条展开点击折叠 -->
+    <div
+      class="flex items-center gap-1.5 w-[360px] px-3 py-1.5 rounded-[10px] text-13px text-[var(--ant-color-text)] bg-[var(--ant-color-bg-container)] shadow-[0_1px_2px_rgba(0,0,0,0.04)] cursor-pointer hover:bg-[var(--ant-color-fill-tertiary)]"
+      @click="handleTopClick"
+    >
+      <Icon
+        icon="ant-design:pushpin-outlined"
+        :size="14"
+        class="flex-shrink-0 text-[var(--ant-color-warning)]"
+      />
+      <span class="flex-shrink-0 text-[var(--ant-color-text-secondary)]">{{ getSenderName(latest) }}：</span>
+      <span class="flex-1 min-w-0 truncate">{{ getPreview(latest) }}</span>
+      <!-- 单条：移除按钮；多条折叠：共 N 条；多条展开：收起箭头 -->
+      <ElButton
+        v-if="pinnedMessages.length === 1 && canManage"
+        link
+        size="small"
+        :loading="removingId === latest.id"
+        class="flex-shrink-0 !h-auto !p-0 text-13px"
+        @click.stop="handleRemove(latest)"
+      >
+        移除
+      </ElButton>
+      <template v-else-if="pinnedMessages.length > 1">
+        <span class="flex-shrink-0 text-[var(--ant-color-text-secondary)] text-12px">
+          共 {{ pinnedMessages.length }} 条
+        </span>
+        <Icon
+          :icon="expanded ? 'ant-design:up-outlined' : 'ant-design:down-outlined'"
+          :size="11"
+          class="flex-shrink-0 text-[var(--ant-color-text-placeholder)]"
+        />
+      </template>
+    </div>
+
+    <!-- 多条展开：浅色面板包裹完整列表，每条独立胶囊；点击跳转到对应消息位置 -->
+    <div
+      v-if="pinnedMessages.length > 1 && expanded"
+      class="im-group-pinned-message__list absolute top-full left-1.5 z-10 flex flex-col gap-2.5 w-[380px] p-3 rounded-xl bg-[var(--ant-color-bg-container)] shadow-[0_6px_16px_rgba(0,0,0,0.12)]"
+      style="margin-top: -1px"
+    >
+      <div
+        v-for="msg in pinnedMessages"
+        :key="msg.id"
+        class="flex items-center gap-1.5 w-full px-3 py-1.5 rounded-[10px] text-13px text-[var(--ant-color-text)] bg-[var(--ant-color-fill-secondary)] cursor-pointer hover:bg-[var(--ant-color-bg-container)]"
+        @click="handleLocate(msg)"
+      >
+        <Icon
+          icon="ant-design:pushpin-outlined"
+          :size="14"
+          class="flex-shrink-0 text-[var(--ant-color-warning)]"
+        />
+        <span class="flex-shrink-0 text-[var(--ant-color-text-secondary)]">
+          {{ getSenderName(msg) }}：
+        </span>
+        <span class="flex-1 min-w-0 truncate">{{ getPreview(msg) }}</span>
+        <ElButton
+          v-if="canManage"
+          link
+          size="small"
+          :loading="removingId === msg.id"
+          class="flex-shrink-0 !h-auto !p-0 text-13px"
+          @click.stop="handleRemove(msg)"
+        >
+          移除
+        </ElButton>
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* 弹出层朝上的三角箭头；走 ::before + 4 边 border 配色画，颜色跟弹出层 background 一致 */
+.im-group-pinned-message__list::before {
+  content: '';
+  position: absolute;
+  top: -8px;
+  left: 184px;
+  width: 0;
+  height: 0;
+  border-left: 8px solid transparent;
+  border-right: 8px solid transparent;
+  border-bottom: 8px solid var(--ant-color-bg-container);
+  filter: drop-shadow(0 -2px 1px rgba(0, 0, 0, 0.04));
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/group-request-pending.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/group-request-pending.vue
new file mode 100644
index 000000000..4c401d7ee
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/group-request-pending.vue
@@ -0,0 +1,88 @@
+<script lang="ts" setup>
+import { computed, ref } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+import { ImGroupMemberRole } from '#/views/im/utils/constants'
+
+import { GroupRequestListDialog } from '../../../../components/group'
+import { useGroupRequestStore } from '../../../../store/groupRequestStore'
+import { useGroupStore } from '../../../../store/groupStore'
+
+defineOptions({ name: 'ImGroupRequestPending' })
+
+const props = defineProps<{
+  groupId: number
+}>()
+
+const groupStore = useGroupStore()
+const groupRequestStore = useGroupRequestStore()
+
+const requestListDialogRef = ref<InstanceType<typeof GroupRequestListDialog>>() // 申请列表弹窗 ref：handleOpen 调 open({ groupId }) 触发
+
+/** 打开当前群的进群申请列表 */
+function handleOpen() {
+  requestListDialogRef.value?.open({ groupId: props.groupId })
+}
+
+/** 当前群（含 ownerUserId / members） */
+const group = computed(() => groupStore.getGroup(props.groupId))
+
+/** 当前用户在群里的角色；优先用 group.members，懒加载未到时回退到 ownerUserId 直判 */
+const myRole = computed(() => {
+  const myId = getCurrentUserId()
+  if (group.value?.ownerUserId === myId) {
+    return ImGroupMemberRole.OWNER
+  }
+  return group.value?.members?.find((m) => m.userId === myId)?.role
+})
+
+/** 仅群主 / 管理员可见 */
+const canManage = computed(
+  () => myRole.value === ImGroupMemberRole.OWNER || myRole.value === ImGroupMemberRole.ADMIN
+)
+
+/** 当前群未处理申请数；从 store 派生 */
+const pendingCount = computed(() => groupRequestStore.getUnhandledGroupRequestCount(props.groupId))
+</script>
+
+<template>
+  <!--
+    群顶部「待处理加群申请」横幅
+    - 仅当登录用户是该群 owner / admin 且该群下未处理申请数 > 0 时显示
+    - count 从 groupRequestStore 派生（全局存）；本端处理 / WS 通知到达后 store 自动更新
+    - 点击横幅打开 GroupRequestListDialog（含历史已处理记录），不再就地展开
+  -->
+  <div
+    v-if="canManage && pendingCount > 0"
+    class="flex flex-shrink-0 flex-col items-start px-4 pt-1.5 pb-2 bg-[var(--ant-color-fill-secondary)]"
+  >
+    <div
+      class="inline-flex items-center gap-1.5 px-3 py-1.5 rounded-[10px] text-13px text-[var(--ant-color-text)] bg-[var(--ant-color-bg-container)] cursor-pointer shadow-[0_1px_2px_rgba(0,0,0,0.04)] transition-colors hover:bg-[var(--ant-color-fill-tertiary)]"
+      @click="handleOpen"
+    >
+      <Icon
+        icon="ant-design:user-add-outlined"
+        :size="14"
+        class="im-group-request-pending__icon flex-shrink-0 text-[var(--ant-color-success)]"
+      />
+      <span class="flex-1 min-w-0 truncate"> 新进群申请（{{ pendingCount }}） </span>
+      <Icon
+        icon="ant-design:right-outlined"
+        :size="11"
+        class="flex-shrink-0 text-[var(--ant-color-text-placeholder)]"
+      />
+    </div>
+
+    <!-- 申请列表 dialog：复用同一组件，避免群管理面板与会话顶部各写一份 -->
+    <GroupRequestListDialog ref="requestListDialogRef" />
+  </div>
+</template>
+
+<style scoped>
+/* :deep 穿透 Icon 子组件 DOM；强制 svg 走 currentColor 应对暗色模式 el-icon 全局色覆盖 */
+.im-group-request-pending__icon :deep(svg) {
+  fill: currentColor !important;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/index.ts b/apps/web-ele/src/views/im/home/pages/conversation/components/message/index.ts
new file mode 100644
index 000000000..025a74cc3
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/index.ts
@@ -0,0 +1,10 @@
+export { default as GroupPinnedMessage } from './group-pinned-message.vue';
+export { default as GroupRequestPending } from './group-request-pending.vue';
+export { default as MaterialBubble } from './material-bubble.vue';
+export { default as MessageBubble } from './message-bubble.vue';
+export { default as MessageHistory } from './message-history.vue';
+export { default as MessageItem } from './message-item.vue';
+export { default as MessagePanel } from './message-panel.vue';
+export { default as MessageReadStatus } from './message-read-status.vue';
+export { default as ReplyPreview } from './reply-preview.vue';
+export { default as TipSegments } from './tip-segments.vue';
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/material-bubble.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/material-bubble.vue
new file mode 100644
index 000000000..93c0b16e4
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/material-bubble.vue
@@ -0,0 +1,170 @@
+<script lang="ts" setup>
+import { computed, ref } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+import { openSafeUrl } from '@vben/utils'
+
+import { ElDialog } from 'element-plus'
+
+import { getChannelMaterial } from '#/api/im/channel/material'
+import { useChannelStore } from '#/views/im/home/store/channelStore'
+import { useConversationStore } from '#/views/im/home/store/conversationStore'
+import { ImConversationType } from '#/views/im/utils/constants'
+import { type MaterialMessage, parseMessage } from '#/views/im/utils/message'
+
+const props = defineProps<{
+  content: string
+}>()
+
+const conversationStore = useConversationStore()
+const channelStore = useChannelStore()
+
+/** 当前是否在公众号 / 频道会话里：决定走大卡片还是紧凑转发卡片 */
+const isChannelView = computed(
+  () => conversationStore.activeConversation?.type === ImConversationType.CHANNEL
+)
+
+/** 反序列化 content JSON 为 payload 对象 */
+const payload = computed<MaterialMessage>(
+  () => parseMessage<MaterialMessage>(props.content) ?? {}
+)
+
+/** 来源频道；紧凑卡底部渲染头像 + 名称 */
+const sourceChannel = computed(() =>
+  payload.value.channelId ? channelStore.getChannel(payload.value.channelId) : undefined
+)
+
+const detailVisible = ref(false)
+const detailLoading = ref(false)
+const detailHtml = ref('')
+
+// 点击行为：url 非空跳外链；为空则按 payload.materialId 拉富文本正文，全屏 dialog 渲染
+const onClick = async () => {
+  if (payload.value.url) {
+    openSafeUrl(payload.value.url)
+    return
+  }
+  if (!payload.value.materialId) {
+    return
+  }
+  detailVisible.value = true
+  detailLoading.value = true
+  detailHtml.value = ''
+  try {
+    const material = await getChannelMaterial(payload.value.materialId)
+    detailHtml.value = material?.content ?? ''
+  } catch (error) {
+    console.error('[Material] 拉取正文失败', error)
+  } finally {
+    detailLoading.value = false
+  }
+}
+</script>
+
+<template>
+  <!-- 公众号会话内大卡片：对齐微信公众号单图文卡（封面 9:5 + 下方白底加粗标题条） -->
+  <div
+    v-if="isChannelView"
+    class="material-card cursor-pointer w-full overflow-hidden rounded-lg bg-[var(--ant-color-bg-container)] border border-solid border-[var(--im-border-color-lighter)]"
+    @click="onClick"
+  >
+    <img v-if="payload.coverUrl" class="block w-full h-[200px] object-cover" :src="payload.coverUrl" />
+    <div class="px-3.5 py-3 text-15px font-600 leading-[1.4] text-[var(--ant-color-text)] line-clamp-2">
+      {{ payload.title || '(无标题)' }}
+    </div>
+  </div>
+
+  <!-- 私聊 / 群聊里被转发的素材紧凑卡片：标题 + 摘要在左、小封面在右、底部频道头像 + 名称（对齐微信公众号转发卡） -->
+  <div
+    v-else
+    class="material-card cursor-pointer flex flex-col w-[260px] px-3.5 pt-3 pb-2.5 rounded-lg bg-[var(--ant-color-bg-container)] border border-solid border-[var(--im-border-color-lighter)]"
+    @click="onClick"
+  >
+    <div class="flex gap-2.5 items-start">
+      <div class="flex flex-1 flex-col gap-1.5 min-w-0">
+        <div class="text-15px font-600 leading-[1.4] text-[var(--ant-color-text)] line-clamp-2 break-all">
+          {{ payload.title || '(无标题)' }}
+        </div>
+        <div
+          v-if="payload.summary"
+          class="text-12px leading-[1.5] text-[var(--ant-color-text-secondary)] line-clamp-2 break-all"
+        >
+          {{ payload.summary }}
+        </div>
+      </div>
+      <img
+        v-if="payload.coverUrl"
+        class="flex-shrink-0 w-[60px] h-[60px] object-cover rounded bg-[var(--ant-color-fill-secondary)]"
+        :src="payload.coverUrl"
+      />
+    </div>
+    <div class="flex items-center gap-1.5 mt-2.5 pt-2 border-t border-t-solid border-[var(--im-border-color-lighter)] text-12px text-[var(--ant-color-text-secondary)]">
+      <img
+        v-if="sourceChannel?.avatar"
+        class="w-4 h-4 rounded-full object-cover flex-shrink-0"
+        :src="sourceChannel.avatar"
+      />
+      <Icon v-else icon="ep:promotion" :size="14" />
+      <span class="truncate">{{ sourceChannel?.name || '频道消息' }}</span>
+    </div>
+  </div>
+
+  <!-- 富文本详情：全屏弹窗按需挂载，关闭后释放富文本 DOM -->
+  <ElDialog
+    v-model="detailVisible"
+    :content="payload.title || '详情'"
+    
+    width="100vw"
+    class="im-material-detail-modal"
+    destroy-on-close
+  >
+    <div v-loading="detailLoading" class="w-full">
+      <div class="material-detail-body max-w-[720px] mx-auto px-5 pt-6 pb-20 min-h-[60vh]">
+        <div class="text-[22px] font-600 leading-[1.4] text-[var(--ant-color-text)] mb-5">
+          {{ payload.title || '' }}
+        </div>
+        <div
+          v-if="detailHtml"
+          class="article-content text-15px leading-[1.75] text-[var(--ant-color-text)]"
+          v-dompurify-html="detailHtml"
+        ></div>
+        <div
+          v-else-if="!detailLoading"
+          class="text-center text-[var(--ant-color-text-secondary)] mt-20"
+        >
+          暂无正文
+        </div>
+      </div>
+    </div>
+  </ElDialog>
+</template>
+
+<style scoped lang="scss">
+/* hover 阴影 + transition：合写一处，写法更紧凑 */
+.material-card {
+  transition: box-shadow 0.15s ease;
+
+  &:hover {
+    box-shadow: 0 2px 12px rgba(0, 0, 0, 0.08);
+  }
+}
+
+/* :deep 穿透 v-dompurify-html 渲染的内嵌 DOM；统一控制富文本里的 img / p / hN 排版 */
+.article-content {
+  :deep(img) {
+    max-width: 100%;
+    height: auto;
+  }
+
+  :deep(p) {
+    margin: 12px 0;
+  }
+
+  :deep(h1),
+  :deep(h2),
+  :deep(h3) {
+    margin: 20px 0 12px;
+    font-weight: 600;
+  }
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-bubble.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-bubble.vue
new file mode 100644
index 000000000..8b05daa74
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-bubble.vue
@@ -0,0 +1,414 @@
+<script lang="ts" setup>
+import { computed, onBeforeUnmount } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+import { formatFileSize, openSafeUrl } from '@vben/utils'
+
+import { ElImage } from 'element-plus'
+
+import { CardBubble } from '#/views/im/home/components/card'
+import { useVoicePlayer } from '#/views/im/home/composables/useVoicePlayer'
+import { MESSAGE_MERGE_PREVIEW_LINES } from '#/views/im/utils/config'
+import { ImContentType } from '#/views/im/utils/constants'
+import { summarizeMessageContent } from '#/views/im/utils/conversation'
+import {
+  type AudioMessage,
+  type CardMessage,
+  type FaceMessage,
+  type FileMessage,
+  getFileIconInfo,
+  type ImageMessage,
+  type MentionCandidate,
+  type MergeMessage,
+  parseMessage,
+  parseTextSegments,
+  type TextMessage,
+  type VideoMessage
+} from '#/views/im/utils/message'
+import { formatSeconds } from '#/views/im/utils/time'
+
+import MaterialBubble from './material-bubble.vue'
+import TipSegments from './tip-segments.vue'
+
+defineOptions({ name: 'ImMessageBubble' })
+
+const props = defineProps<{
+  /** 消息 content（JSON 字符串） */
+  content: string
+  /** TEXT 气泡的 @ mention 候选名字；不传则文本里的 @xxx 退化为普通文本 */
+  mentions?: MentionCandidate[]
+  /** 是否自己发送，影响气泡配色（绿底 vs 灰底） */
+  selfSend?: boolean
+  /** 内容类型，对齐 ImContentType */
+  type: number
+  /** 媒体上传进度（0-100）；非 null 即视为上传中，渲染遮罩 / 进度条 */
+  uploadProgress?: null | number
+}>()
+
+const emit = defineEmits<{
+  /** 名片点击：调用方决定弹卡片 / 跳群等行为 */
+  clickCard: [card: CardMessage, e: MouseEvent]
+  /** 合并消息气泡点击：调用方决定开 dialog 或栈内 push */
+  openMerge: [content: string]
+}>()
+
+/** 各 type 判定 */
+const isText = computed(() => props.type === ImContentType.TEXT)
+const isImage = computed(() => props.type === ImContentType.IMAGE)
+const isFile = computed(() => props.type === ImContentType.FILE)
+const isVoice = computed(() => props.type === ImContentType.VOICE)
+const isVideo = computed(() => props.type === ImContentType.VIDEO)
+const isFace = computed(() => props.type === ImContentType.FACE)
+const isCard = computed(() => props.type === ImContentType.CARD)
+const isMerge = computed(() => props.type === ImContentType.MERGE)
+const isMaterial = computed(() => props.type === ImContentType.MATERIAL)
+
+/** 媒体上传中：uploadProgress 非 null 即视为上传中 */
+const isUploading = computed(() => props.uploadProgress != null)
+const uploadProgress = computed(() => props.uploadProgress ?? 0)
+const uploadProgressText = computed(() => `${uploadProgress.value}%`)
+
+/**
+ * 单一 parse 入口：content 一变只 parse 一次，按 type 分发到下面 7 个 payload
+ *
+ * 各类型 payload 共用同一棵 JSON 树，避免 7 个 computed 各自重 parse 同一份 content
+ */
+const parsedContent = computed<unknown>(() => parseMessage(props.content))
+
+const textPayload = computed(() =>
+  isText.value ? (parsedContent.value as null | TextMessage) : null
+)
+
+/** 文本气泡 segment 数组：mention 高亮 + URL 自动识别 + 普通文本三段拼接 */
+const textSegments = computed(() => {
+  const content = textPayload.value?.content
+  if (!content) {
+    return []
+  }
+  return parseTextSegments(content, props.mentions || [])
+})
+const imagePayload = computed(() =>
+  isImage.value ? (parsedContent.value as ImageMessage | null) : null
+)
+const filePayload = computed(() =>
+  isFile.value ? (parsedContent.value as FileMessage | null) : null
+)
+const voicePayload = computed(() =>
+  isVoice.value ? (parsedContent.value as AudioMessage | null) : null
+)
+const videoPayload = computed(() =>
+  isVideo.value ? (parsedContent.value as null | VideoMessage) : null
+)
+const cardPayload = computed(() =>
+  isCard.value ? (parsedContent.value as CardMessage | null) : null
+)
+const mergePayload = computed(() =>
+  isMerge.value ? (parsedContent.value as MergeMessage | null) : null
+)
+
+/** 合并消息内嵌前 N 条派生「{昵称}：{摘要}」 */
+const mergePreviewLines = computed(() => {
+  if (!mergePayload.value) {
+    return []
+  }
+  return mergePayload.value.messages
+    .slice(0, MESSAGE_MERGE_PREVIEW_LINES)
+    .map((item) => `${item.senderNickname}：${summarizeMessageContent(item)}`)
+})
+
+const FACE_DIMENSION_MAX = 2048 // 表情 payload：非法宽高派生成 undefined，让 <img> 走 CSS max-w / max-h 兜底
+const facePayload = computed(() => {
+  if (!isFace.value) {
+    return null
+  }
+  const raw = parsedContent.value as FaceMessage | null
+  if (!raw) {
+    return null
+  }
+  const sanitize = (v: number | undefined) =>
+    v && v > 0 && v <= FACE_DIMENSION_MAX ? v : undefined
+  return { ...raw, width: sanitize(raw.width), height: sanitize(raw.height) }
+})
+
+/** 文件图标 + 配色：按扩展名分发 */
+const fileIconInfo = computed(() => getFileIconInfo(filePayload.value?.name))
+
+/** 文本 / 文件 / 语音气泡的整体 class（含 selfSend 配色 + ::before 三角的 side class） */
+function bubbleClass(variant: 'file' | 'text' | 'voice'): string[] {
+  const isSelf = props.selfSend
+  const side = isSelf ? 'message-bubble--self' : 'message-bubble--other'
+  switch (variant) {
+    case 'file': {
+      return [
+        side,
+        'message-bubble--file',
+        isSelf
+          ? 'bg-[#95ec69] border-[var(--ant-color-border-secondary)]'
+          : 'bg-[var(--ant-color-bg-container)] border-[var(--ant-color-border-secondary)] hover:border-[#409eff]'
+      ]
+    }
+    case 'text': {
+      return [
+        side,
+        'message-bubble--text',
+        isSelf
+          ? 'text-black bg-[#95ec69]'
+          : 'text-[var(--ant-color-text)]'
+      ]
+    }
+    case 'voice': {
+      return [side, 'message-bubble--voice', isSelf ? 'bg-[#95ec69]' : '']
+    }
+  }
+}
+
+/** 文件点击 → 新窗口下载；上传中跳过 */
+function handleFileClick() {
+  if (isUploading.value || !filePayload.value?.url) {
+    return
+  }
+  openSafeUrl(filePayload.value.url)
+}
+
+const voicePlayer = useVoicePlayer() // 语音点击：托管给 useVoicePlayer 全局互斥播放，新点的语音会停掉旧的
+/**
+ * 实例级唯一播放 key：每个 MessageBubble 实例独立一份
+ *
+ * 不用 url 当 key 是为了避免「主面板 / 历史抽屉 / 合并详情同一条语音」共享身份：那样三处气泡会
+ * 同时显示播放态，且任何一处卸载都会 stop 掉别处仍可见的播放
+ */
+const voiceKey = Symbol('im-message-bubble-voice')
+const voicePlaying = computed(() => voicePlayer.isPlaying(voiceKey))
+function handleVoiceClick() {
+  const url = voicePayload.value?.url
+  if (!url) {
+    return
+  }
+  voicePlayer.play(voiceKey, url)
+}
+
+/** 气泡卸载兜底：传 key 让 stop 自己判别「是不是我」，不会误伤别人的播放 */
+onBeforeUnmount(() => {
+  voicePlayer.stop(voiceKey)
+})
+</script>
+
+<template>
+  <!-- 文本：按 segment 渲染，mention 高亮可点击、URL 自动识别成可点击链接 -->
+  <div
+    v-if="isText && textPayload"
+    class="relative px-3.5 py-2.5 text-sm leading-normal break-words whitespace-pre-wrap rounded-lg"
+    :class="bubbleClass('text')"
+  >
+    <TipSegments :segments="textSegments" />
+  </div>
+
+  <!-- 图片：el-image 内置预览；上传中半透明遮罩 -->
+  <div v-else-if="isImage && imagePayload" class="relative inline-block">
+    <ElImage
+      class="max-w-[220px] rounded cursor-zoom-in"
+      :src="imagePayload.thumbnailUrl || imagePayload.url"
+      :preview="isUploading ? false : { src: imagePayload.url }"
+    />
+    <div
+      v-if="isUploading"
+      class="absolute inset-0 flex items-center justify-center text-sm text-white bg-black bg-opacity-45 rounded pointer-events-none"
+    >
+      {{ uploadProgressText }}
+    </div>
+  </div>
+
+  <!-- 文件：文件名 + 大小靠左、彩色大图标贴右；上传中插一条进度条 -->
+  <div
+    v-else-if="isFile && filePayload"
+    class="relative flex gap-3 items-center min-w-[260px] max-w-[340px] px-3.5 py-3 border border-solid rounded transition-colors"
+    :class="[bubbleClass('file'), isUploading ? 'cursor-default' : 'cursor-pointer']"
+    @click="handleFileClick"
+  >
+    <div class="flex-1 min-w-0">
+      <div class="overflow-hidden text-sm font-medium truncate text-[var(--ant-color-text)]">
+        {{ filePayload.name }}
+      </div>
+      <div class="mt-1 text-12px text-[var(--ant-color-text-secondary)]">
+        {{ formatFileSize(filePayload.size) }}
+      </div>
+      <div v-if="isUploading" class="flex gap-2 items-center mt-1.5">
+        <div class="overflow-hidden flex-1 h-1 rounded bg-[var(--ant-color-fill-dark)]">
+          <div
+            class="h-full bg-[var(--ant-color-primary)] transition-[width] duration-150"
+            :style="{ width: `${uploadProgress }%` }"
+          ></div>
+        </div>
+        <span class="text-11px text-[var(--ant-color-text-secondary)] tabular-nums">
+          {{ uploadProgressText }}
+        </span>
+      </div>
+    </div>
+    <Icon :icon="fileIconInfo.icon" :color="fileIconInfo.color" :size="40" class="flex-shrink-0" />
+  </div>
+
+  <!-- 语音 -->
+  <div
+    v-else-if="isVoice && voicePayload"
+    class="relative flex gap-2 items-center min-w-[120px] px-3.5 py-2.5 rounded-lg cursor-pointer"
+    :class="bubbleClass('voice')"
+    @click="handleVoiceClick"
+  >
+    <Icon
+      icon="ant-design:audio-outlined"
+      :size="18"
+      class="message-bubble__voice-icon"
+      :class="{ 'im-voice-playing': voicePlaying }"
+    />
+    <span class="text-13px text-[var(--ant-color-text)]">
+      {{ formatSeconds(voicePayload.duration) }}
+    </span>
+  </div>
+
+  <!-- 视频：原生 controls 内嵌播放，poster 走后端封面；上传中半透明遮罩 -->
+  <div v-else-if="isVideo && videoPayload?.url" class="relative inline-block">
+    <video
+      class="max-w-[280px] max-h-[320px] rounded bg-black"
+      :src="videoPayload.url"
+      :poster="videoPayload.coverUrl"
+      :controls="!isUploading"
+      preload="metadata"
+    ></video>
+    <div
+      v-if="isUploading"
+      class="absolute inset-0 flex items-center justify-center text-sm text-white bg-black bg-opacity-45 rounded pointer-events-none"
+    >
+      {{ uploadProgressText }}
+    </div>
+  </div>
+  <!-- 视频但 payload 解析失败 / 没 url：降级展示 -->
+  <div
+    v-else-if="isVideo"
+    class="px-3.5 py-2.5 text-sm italic rounded-lg text-[var(--ant-color-text-secondary)] bg-[var(--ant-color-fill-secondary)]"
+  >
+    [视频消息]
+  </div>
+
+  <!-- 表情贴图：裸 <img> 不套气泡 -->
+  <div v-else-if="isFace && facePayload" class="inline-block">
+    <img
+      :src="facePayload.url"
+      :alt="facePayload.name || '表情'"
+      :content="facePayload.name || ''"
+      :width="facePayload.width"
+      :height="facePayload.height"
+      class="block max-w-[160px] max-h-[160px] object-contain"
+      draggable="false"
+    />
+  </div>
+
+  <!-- 名片 -->
+  <CardBubble
+    v-else-if="isCard && cardPayload"
+    :card="cardPayload"
+    clickable
+    @click="(e: MouseEvent) => emit('clickCard', cardPayload!, e)"
+  />
+
+  <!-- 合并转发气泡：title + 摘要预览 + 底部「聊天记录」标签 -->
+  <div
+    v-else-if="isMerge && mergePayload"
+    class="flex flex-col w-[260px] rounded-md overflow-hidden cursor-pointer bg-[var(--ant-color-bg-container)] border border-solid border-[var(--ant-color-border)] hover:border-[#409eff]"
+    @click="emit('openMerge', content)"
+  >
+    <div class="px-3 py-2 text-sm font-medium text-[var(--ant-color-text)] truncate">
+      {{ mergePayload.title }}
+    </div>
+    <div class="flex flex-col gap-0.5 px-3 pb-2">
+      <div
+        v-for="(line, idx) in mergePreviewLines"
+        :key="idx"
+        class="text-12px text-[var(--ant-color-text-secondary)] truncate"
+      >
+        {{ line }}
+      </div>
+    </div>
+    <div
+      class="px-3 py-1 text-12px border-t border-t-solid text-[var(--ant-color-text-placeholder)] border-[var(--ant-color-border-secondary)] bg-[var(--ant-color-fill-tertiary)]"
+    >
+      聊天记录
+    </div>
+  </div>
+  <!-- 合并消息解析失败兜底 -->
+  <div
+    v-else-if="isMerge"
+    class="px-3.5 py-2.5 text-sm italic rounded-lg text-[var(--ant-color-text-secondary)] bg-[var(--ant-color-fill-secondary)]"
+  >
+    [聊天记录]
+  </div>
+
+  <!-- 频道素材：图文卡片，点击拉富文本 / 跳外链 -->
+  <MaterialBubble v-else-if="isMaterial" :content="props.content" />
+
+  <!-- 未知类型降级 -->
+  <div
+    v-else
+    class="px-3.5 py-2.5 text-sm italic rounded-lg text-[var(--ant-color-text-secondary)] bg-[var(--ant-color-fill-secondary)]"
+  >
+    [不支持的内容类型]
+  </div>
+</template>
+
+<style scoped>
+/* 气泡尾巴小三角指向对应头像（对方在左、自己在右）；走 ::before + 4 边 border 配色画：透明 3 边 + 实色 1 边，
+   颜色与气泡背景对应，留 1px 视觉吃进去，省一张图片 */
+.message-bubble--other::before,
+.message-bubble--self::before {
+  content: '';
+  position: absolute;
+  top: 12px;
+  width: 0;
+  height: 0;
+  border-style: solid;
+}
+.message-bubble--other {
+  --im-message-bubble-other-bg: #f5f5f5;
+}
+.message-bubble--other.message-bubble--text,
+.message-bubble--other.message-bubble--voice {
+  background-color: var(--im-message-bubble-other-bg);
+}
+.message-bubble--other::before {
+  left: -5px;
+  border-width: 5px 6px 5px 0;
+  border-color: transparent var(--im-message-bubble-other-bg) transparent transparent;
+}
+.message-bubble--self::before {
+  right: -5px;
+  border-width: 5px 0 5px 6px;
+  border-color: transparent transparent transparent #95ec69;
+}
+
+/* 整体放进 :global()，避免 Vue scoped 把 `:global(.dark) .xxx` 塌缩成裸 `.dark` 而把变量刷到 <html> */
+:global(.dark .message-bubble--other) {
+  --im-message-bubble-other-bg: rgb(255 255 255 / 12%);
+}
+
+/* :deep 穿透 scoped 子组件 DOM；el-icon 在暗色模式下全局 color 被 .el-icon{color:var(--color)} 干扰，把 voice 图标 fill 锁死 */
+.message-bubble__voice-icon :deep(svg) {
+  fill: #606266 !important;
+}
+.message-bubble__voice-icon.im-voice-playing :deep(svg) {
+  fill: #409eff !important;
+}
+
+/* @keyframes 需要 SCSS 声明；播放中的脉冲动画 */
+.im-voice-playing {
+  animation: im-voice-icon-pulse 0.8s infinite;
+}
+
+@keyframes im-voice-icon-pulse {
+  0%,
+  100% {
+    transform: scale(1);
+  }
+  50% {
+    transform: scale(1.15);
+  }
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-history.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-history.vue
new file mode 100644
index 000000000..ae4f58a60
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-history.vue
@@ -0,0 +1,806 @@
+<script lang="ts" setup>
+import type { Message } from '#/views/im/home/types'
+
+import { computed, inject, ref, watch } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+import { useUserStore } from '@vben/stores'
+
+import dayjs from 'dayjs'
+import { ElButton, ElCalendar, ElDialog, ElInput, ElPopover, ElTag } from 'element-plus'
+
+import { getGroupMessageList as apiGetGroupMessageList } from '#/api/im/message/group'
+import { getPrivateMessageList as apiGetPrivateMessageList } from '#/api/im/message/private'
+import { useMessagePuller } from '#/views/im/home/composables/useMessagePuller'
+import { useVoicePlayer } from '#/views/im/home/composables/useVoicePlayer'
+import {
+  ImContentType,
+  ImConversationType,
+  isFriendChatTip,
+  isGroupNotification
+} from '#/views/im/utils/constants'
+import {
+  buildFacePreviewText,
+  buildRecallTip,
+  buildRecallTipSegments,
+  getConversationKey
+} from '#/views/im/utils/conversation'
+import { getClientConversationId } from '#/views/im/utils/db'
+import {
+  resolveFriendNotificationSegments,
+  resolveFriendNotificationText,
+  resolveGroupNotificationSegments
+} from '#/views/im/utils/message'
+import {
+  type CardMessage,
+  type FaceMessage,
+  type FileMessage,
+  getCardLabelInfo,
+  type MergeMessage,
+  parseMessage,
+  type TextMessage
+} from '#/views/im/utils/message'
+import { formatHistoryTime } from '#/views/im/utils/time'
+import {
+  getMemberDisplayName,
+  getSenderDisplayName,
+  getSenderRealNickname
+} from '#/views/im/utils/user'
+
+import { GroupMember, type GroupMemberLite } from '../../../../components/group'
+import { UserAvatar } from '../../../../components/user'
+import { useConversationStore } from '../../../../store/conversationStore'
+import { useFriendStore } from '../../../../store/friendStore'
+import { useGroupStore } from '../../../../store/groupStore'
+import { useMessageStore } from '../../../../store/messageStore'
+import { IM_MERGE_DETAIL_DIALOG_KEY } from './forward/keys'
+import MessageBubble from './message-bubble.vue'
+import TipSegments from './tip-segments.vue'
+
+defineOptions({ name: 'ImMessageHistory' })
+
+const emit = defineEmits<{
+  // 历史消息行上的"定位"按钮：通知父组件 MessagePanel 滚到对应消息位置 + 关掉自己
+  locate: [messageId: number]
+}>()
+
+const userStore = useUserStore()
+const conversationStore = useConversationStore()
+const messageStore = useMessageStore()
+const groupStore = useGroupStore()
+const friendStore = useFriendStore()
+const openMergeDetail = inject(IM_MERGE_DETAIL_DIALOG_KEY)
+const voicePlayer = useVoicePlayer()
+const { convertPrivateMessage, convertGroupMessage } = useMessagePuller()
+
+const visible = ref(false)
+
+defineExpose({
+  /** 打开历史消息抽屉 */
+  open() {
+    visible.value = true
+  }
+})
+
+const conversation = computed(() => conversationStore.activeConversation)
+const isGroup = computed(() => conversation.value?.type === ImConversationType.GROUP)
+const allMessages = computed<Message[]>(() =>
+  conversation.value
+    ? messageStore.getMessages(
+        getClientConversationId(conversation.value.type, conversation.value.targetId)
+      )
+    : []
+)
+
+/** 单条消息的发送人显示名：渲染时按 conversation 上下文走 WeChat 优先级实时算 */
+function senderDisplayNameOf(message: Message): string {
+  return getSenderDisplayName(
+    message.senderId,
+    conversation.value?.type ?? 0,
+    conversation.value?.targetId ?? 0
+  )
+}
+
+/** 群广播事件 segments 的成员名解析器；按当前会话 targetId 走 getSenderDisplayName */
+function resolveGroupMemberName(message: Message): (userId: number) => string {
+  return (id: number) => getSenderDisplayName(id, ImConversationType.GROUP, message.targetId ?? 0)
+}
+
+/** 单条消息的发送人真实昵称：给 UserAvatar 色卡 / alt 用，永远是 nickname 不掺备注 */
+function senderRealNicknameOf(message: Message): string {
+  return getSenderRealNickname(
+    message.senderId,
+    conversation.value?.type ?? 0,
+    conversation.value?.targetId ?? 0
+  )
+}
+
+/** 单条撤回消息的 tip 文案：buildRecallTip 内部按 conversation 上下文实时算 sender 名 */
+function recallTipOf(message: Message): string {
+  return buildRecallTip(
+    message.senderId,
+    message.selfSend,
+    conversation.value?.type ?? 0,
+    conversation.value?.targetId ?? 0
+  )
+}
+
+/** 单条撤回消息的 tip segments：sender 名段挂可点击 mention */
+function recallTipSegmentsOf(message: Message) {
+  return buildRecallTipSegments(
+    message.senderId,
+    message.selfSend,
+    conversation.value?.type ?? 0,
+    conversation.value?.targetId ?? 0
+  )
+}
+
+// ==================== 标题 ====================
+
+/**
+ * 弹窗标题：参考微信 PC
+ * - 私聊：与"X"的聊天记录
+ * - 群聊："X 群"的聊天记录(N)
+ */
+const title = computed(() => {
+  if (!conversation.value) {
+    return '聊天记录'
+  }
+  const name = conversation.value.name
+  if (isGroup.value) {
+    return `"${name}"的聊天记录(${allMessages.value.length})`
+  }
+  return `与"${name}"的聊天记录`
+})
+
+// ==================== 搜索 + 筛选 chip ====================
+
+/** 当前激活的筛选条件 —— 单 chip 模式（同时只 1 个），点击 tab 落新值，× 清空 */
+type ActiveFilter =
+  | { day: string; kind: 'date'; } // YYYY-MM-DD
+  | { kind: 'file' }
+  | { kind: 'image' }
+  | { kind: 'member'; nickname: string; userId: number; }
+  | { kind: 'voice' }
+
+const keyword = ref('')
+const activeFilter = ref<ActiveFilter | null>(null)
+
+/** chip 文案：日期 / 群成员 多带值，其他直接 tab 名 */
+const filterChipLabel = computed(() => {
+  if (!activeFilter.value) {
+    return ''
+  }
+  switch (activeFilter.value.kind) {
+    case 'date': {
+      return `日期：${activeFilter.value.day}`
+    }
+    case 'file': {
+      return '文件'
+    }
+    case 'image': {
+      return '图片'
+    }
+    case 'member': {
+      return `@${activeFilter.value.nickname}`
+    }
+    case 'voice': {
+      return '语音'
+    }
+    default: {
+      return ''
+    }
+  }
+})
+
+/** 点 tab 落筛选；同 kind 重复点击 → 当 toggle 关掉（避免迷惑） */
+function setFilter(filter: ActiveFilter) {
+  if (
+    activeFilter.value?.kind === filter.kind &&
+    filter.kind !== 'date' &&
+    filter.kind !== 'member'
+  ) {
+    activeFilter.value = null
+    return
+  }
+  activeFilter.value = filter
+}
+
+/** chip × 关闭 / 重置 */
+function clearFilter() {
+  activeFilter.value = null
+}
+
+// ==================== 日期 popover ====================
+
+const datePopoverVisible = ref(false)
+const datePickerValue = ref(new Date())
+
+/** 日期 popover 确定：把 Date → YYYY-MM-DD 落到 activeFilter，关 popover */
+function onDateConfirm() {
+  if (!datePickerValue.value) {
+    datePopoverVisible.value = false
+    return
+  }
+  const day = dayjs(datePickerValue.value).format('YYYY-MM-DD')
+  activeFilter.value = { kind: 'date', day }
+  datePopoverVisible.value = false
+}
+
+// ==================== 群成员 popover ====================
+
+const memberPopoverVisible = ref(false)
+const memberSearchKeyword = ref('')
+
+/** 群成员 picker 列表：从 groupStore 拉 + 适配 GroupMemberLite + 关键字过滤 */
+const filteredMembersForPicker = computed<GroupMemberLite[]>(() => {
+  if (!isGroup.value || !conversation.value) {
+    return []
+  }
+  const group = groupStore.getGroup(conversation.value.targetId)
+  const all = (group?.members || []).map((member) => {
+    const friend = friendStore.getFriend(member.userId)
+    return {
+      userId: member.userId,
+      showName: getMemberDisplayName(member, friend),
+      nickname: member.nickname,
+      avatar: member.avatar,
+      status: member.status
+    }
+  })
+  const trimmedKeyword = memberSearchKeyword.value.trim()
+  if (!trimmedKeyword) {
+    return all
+  }
+  return all.filter((member) => member.showName.includes(trimmedKeyword))
+})
+
+/** 群成员 picker 选择：落 activeFilter + 关 popover + 清搜索词 */
+function onMemberSelect(member: GroupMemberLite) {
+  activeFilter.value = {
+    kind: 'member',
+    userId: member.userId,
+    nickname: member.showName
+  }
+  memberPopoverVisible.value = false
+  memberSearchKeyword.value = ''
+}
+
+// ==================== 列表过滤 ====================
+
+/** activeFilter 命中：默认无筛选时全部命中 */
+function matchesActiveFilter(message: Message): boolean {
+  if (!activeFilter.value) {
+    return true
+  }
+  switch (activeFilter.value.kind) {
+    case 'date': {
+      return dayjs(message.sendTime).format('YYYY-MM-DD') === activeFilter.value.day
+    }
+    case 'file': {
+      return message.type === ImContentType.FILE
+    }
+    case 'image': {
+      return message.type === ImContentType.IMAGE
+    }
+    case 'member': {
+      return message.senderId === activeFilter.value.userId
+    }
+    case 'voice': {
+      return message.type === ImContentType.VOICE
+    }
+    default: {
+      return true
+    }
+  }
+}
+
+/**
+ * 当前列表：先 activeFilter 过滤、再 keyword 模糊命中、最后 reverse（最新在前）
+ *
+ * 关键字命中走 textSnippetOf —— 文本拿原文、媒体拿"[图片]"等占位词、文件拿文件名
+ */
+const currentList = computed<Message[]>(() => {
+  const trimmedKeyword = keyword.value.trim()
+  let list = allMessages.value.filter((message) => matchesActiveFilter(message))
+  if (trimmedKeyword) {
+    list = list.filter((message) => textSnippetOf(message).includes(trimmedKeyword))
+  }
+  return list.toReversed()
+})
+
+// ==================== 加载更早消息 ====================
+
+const HISTORY_PAGE_SIZE = 50
+const loadingMore = ref(false)
+const hasMore = ref(true)
+
+/**
+ * 加载更早消息：拿当前最早一条 id 作 maxId（不含），调 list 接口拉一页 + convert + prepend
+ *
+ * - 未对接 list 接口的 type / keyword / sender 过滤参数：后端只支持 maxId + limit 游标分页，
+ *   tab 筛选在前端做（数据来回到本地后过滤）
+ * - 本地占位跳过：后端没法按 messageId 查
+ * - 返回数量 < limit 视为到顶
+ */
+async function loadEarlier() {
+  // 重入 / 到顶 / 无会话 早退：避免重复请求或在 conversation 切换间隙触发
+  if (loadingMore.value || !hasMore.value || !conversation.value) {
+    return
+  }
+  // 仅 PRIVATE / GROUP 走分页接口；CHANNEL 单向广播、没有 list 接口，落到 else 会误调私聊接口（receiverId 传 channelId）
+  const requestedType = conversation.value.type
+  if (requestedType !== ImConversationType.PRIVATE && requestedType !== ImConversationType.GROUP) {
+    return
+  }
+  // 快照当前会话主键：await 期间用户切走 / 关闭面板时丢弃响应，避免旧会话历史被 prepend 到新会话造成串号
+  const requestedKey = getConversationKey(conversation.value)
+  const requestedTargetId = conversation.value.targetId
+  const requestedIsGroup = requestedType === ImConversationType.GROUP
+
+  loadingMore.value = true
+  try {
+    // 算 maxId（不含，作为后端游标）：取当前会话本地缓存里最早一条服务端 id；
+    // 本地乐观占位消息没有服务端 id，要剔除
+    // 全是占位 / 列表为空时 reduce 不更新初值（POSITIVE_INFINITY），转成 undefined → 后端从最新拉
+    let earliestId = Number.POSITIVE_INFINITY
+    for (const message of allMessages.value) {
+      if (message.id && message.id > 0) {
+        earliestId = Math.min(earliestId, message.id)
+      }
+    }
+    const maxId = Number.isFinite(earliestId) ? earliestId : undefined
+
+    // 调后端 list 接口：私聊 / 群聊接口签名不同，分支调度；返回结果用 useMessagePuller
+    // 暴露的 convert 函数转成本地 Message（与 puller 同一份字段映射，避免分歧）
+    let earlier: Message[] = []
+    let pageLength = 0
+    if (requestedIsGroup) {
+      const list = await apiGetGroupMessageList({
+        groupId: requestedTargetId,
+        maxId,
+        limit: HISTORY_PAGE_SIZE
+      })
+      earlier = (list || []).map((message) => convertGroupMessage(message))
+      pageLength = list?.length ?? 0
+    } else {
+      const list = await apiGetPrivateMessageList({
+        receiverId: requestedTargetId,
+        maxId,
+        limit: HISTORY_PAGE_SIZE
+      })
+      earlier = (list || []).map((message) => convertPrivateMessage(message))
+      pageLength = list?.length ?? 0
+    }
+
+    // await 期间 active 可能被外部置 null / 换主键：直接丢弃响应；不更新 hasMore（旧会话到顶不代表新会话到顶）也不 prepend
+    if (!conversation.value || getConversationKey(conversation.value) !== requestedKey) {
+      return
+    }
+
+    // 返回数量 < limit 视为到顶 —— 关闭"加载更早"按钮，避免后续点击空跑接口
+    if (pageLength < HISTORY_PAGE_SIZE) {
+      hasMore.value = false
+    }
+    // 合并到 messageStore：prependMessageList 内部去重 + 升序合并 + 落 IndexedDB；
+    // 主聊天面板的 messages 是同一份引用，老消息也会一起出现在主面板里（符合预期）
+    messageStore.prependMessageList(requestedType, requestedTargetId, earlier)
+  } finally {
+    loadingMore.value = false
+  }
+}
+
+// ==================== 弹窗打开 reset ====================
+
+/** 弹窗打开时把上次的 chip / 搜索 / 加载状态都清干净，避免上次的状态残留迷惑 */
+function onDialogOpen() {
+  activeFilter.value = null
+  keyword.value = ''
+  hasMore.value = true
+  datePopoverVisible.value = false
+  memberPopoverVisible.value = false
+  memberSearchKeyword.value = ''
+  datePickerValue.value = new Date()
+  // 本地无消息时立即拉一次（maxId=undefined 从最新开始），避免新设备 / 缓存清后弹窗只显示"暂无消息"
+  if (allMessages.value.length === 0 && hasMore.value && conversation.value) {
+    void loadEarlier()
+  }
+}
+
+/** 抽屉关闭时复位 + 停语音 */
+watch(visible, (value) => {
+  if (!value) {
+    activeFilter.value = null
+    keyword.value = ''
+    voicePlayer.stop()
+  }
+})
+
+/**
+ * 抽屉开着时外部切了 active conversation：dialog 的 title / 列表 / isGroup 全部跟着新 conversation 走，
+ * 这里把分页态一并重置；否则旧会话残留的 loadingMore=true / hasMore=false 会让新会话"加载更早"按钮失效
+ */
+watch(conversation, () => {
+  loadingMore.value = false
+  hasMore.value = true
+})
+
+// ==================== helper ====================
+
+/** 取头像 url：自己用 userStore，群里查 groupStore 成员，私聊用 conversation.avatar */
+function getAvatar(message: Message): string {
+  if (message.selfSend) {
+    return userStore.userInfo?.avatar || ''
+  }
+  if (!conversation.value) {
+    return ''
+  }
+  if (isGroup.value) {
+    const group = groupStore.getGroup(conversation.value.targetId)
+    return group?.members?.find((member) => member.userId === message.senderId)?.avatar || ''
+  }
+  return conversation.value.avatar || ''
+}
+
+/** 关键字命中文本：文本类返回原文、文件返回文件名（利于按文件名搜）、其他返回占位词 */
+function textSnippetOf(message: Message): string {
+  if (isFriendChatTip(message.type)) {
+    return resolveFriendNotificationText(message)
+  }
+  switch (message.type) {
+    case ImContentType.CARD: {
+      const card = parseMessage<CardMessage>(message.content)
+      return `[${getCardLabelInfo(card).label}] ${card?.name ?? ''}`
+    }
+    case ImContentType.FACE: {
+      return buildFacePreviewText(parseMessage<FaceMessage>(message.content))
+    }
+    case ImContentType.FILE: {
+      return parseMessage<FileMessage>(message.content)?.name ?? '[文件]'
+    }
+    case ImContentType.IMAGE: {
+      return '[图片]'
+    }
+    case ImContentType.MERGE: {
+      const merge = parseMessage<MergeMessage>(message.content)
+      return merge?.title ?? '[聊天记录]'
+    }
+    case ImContentType.RECALL: {
+      return recallTipOf(message)
+    }
+    case ImContentType.TEXT: {
+      return parseMessage<TextMessage>(message.content)?.content ?? ''
+    }
+    case ImContentType.VIDEO: {
+      return '[视频]'
+    }
+    case ImContentType.VOICE: {
+      return '[语音]'
+    }
+    default: {
+      return ''
+    }
+  }
+}
+
+/**
+ * 定位到聊天位置：emit 给 MessagePanel 走 scrollIntoView + 短暂高亮，再关掉自己
+ * messageId === 0（本地占位消息）跳过——还没拿到真实 id，DOM 上没法 querySelector
+ */
+function locateMessage(messageId: number) {
+  if (!messageId) {
+    return
+  }
+  emit('locate', messageId)
+  visible.value = false
+}
+</script>
+
+<template>
+  <!--
+    历史消息弹窗（对齐微信 PC）
+    - 居中 dialog，title "与「X」聊天记录" / "「X 群」聊天记录(N)"
+    - 默认无筛选，全量倒序展示；点击 tab 落筛选 → 搜索框左侧出 chip × 可清
+    - 文件 / 图片 / 链接：直接落筛选；日期 / 群成员：弹 popover 二次选择再落
+    - "加载更早消息"：列表底部按钮，点击调 /im/message/{private,group}/list 拿一页 + prepend
+  -->
+  <ElDialog
+    v-model="visible"
+    :title="title"
+    width="640px"
+    class="im-message-history__dialog"
+    @opened="onDialogOpen"
+  >
+    <div class="flex flex-col gap-3 h-[520px]">
+      <!-- 搜索区：activeFilter 存在时左侧出 chip × 可清，否则纯搜索框 -->
+      <div
+        class="im-message-history__searchbar flex items-center gap-2 px-3 py-1.5 rounded-md bg-[var(--ant-color-fill-secondary)]"
+      >
+        <ElTag
+          v-if="activeFilter"
+          closable
+          size="small"
+          class="im-message-history__chip flex-shrink-0"
+          @close="clearFilter"
+        >
+          {{ filterChipLabel }}
+        </ElTag>
+        <Icon
+          v-else
+          icon="ant-design:search-outlined"
+          class="text-[var(--ant-color-text-secondary)]"
+        />
+        <input
+          v-model="keyword"
+          type="text"
+          placeholder="搜索"
+          class="im-message-history__search-input flex-1 min-w-0 bg-transparent border-none outline-none text-sm text-[var(--ant-color-text)]"
+        />
+      </div>
+
+      <!-- Tab 行：文件 / 图片 / 语音 / 日期(popover) / 群成员(popover, 仅群聊)；底部一条分割线把 tab 区跟消息列表分开，对齐微信观感 -->
+      <div
+        class="flex gap-5 px-2 pb-2 text-sm flex-shrink-0 text-[#1989fa] border-b border-b-solid border-[var(--ant-color-border-secondary)]"
+      >
+        <span
+          class="im-message-history__tab cursor-pointer"
+          :class="{ 'im-message-history__tab--active': activeFilter?.kind === 'file' }"
+          @click="setFilter({ kind: 'file' })"
+        >
+          文件
+        </span>
+        <span
+          class="im-message-history__tab cursor-pointer"
+          :class="{ 'im-message-history__tab--active': activeFilter?.kind === 'image' }"
+          @click="setFilter({ kind: 'image' })"
+        >
+          图片
+        </span>
+        <span
+          class="im-message-history__tab cursor-pointer"
+          :class="{ 'im-message-history__tab--active': activeFilter?.kind === 'voice' }"
+          @click="setFilter({ kind: 'voice' })"
+        >
+          语音
+        </span>
+        <!-- 日期：el-popover 包 el-calendar，确认后才落筛选 -->
+        <ElPopover
+          v-model="datePopoverVisible"
+          trigger="click"
+          placement="bottom"
+          :width="320"
+        >
+          <template #reference>
+            <span
+              class="im-message-history__tab cursor-pointer"
+              :class="{ 'im-message-history__tab--active': activeFilter?.kind === 'date' }"
+            >
+              日期
+            </span>
+          </template>
+          <div class="im-message-history__date-panel">
+            <div class="px-2 pt-1 pb-2 text-13px font-medium text-[var(--ant-color-text)]">
+              选择发送日期
+            </div>
+            <ElCalendar
+              v-model="datePickerValue"
+              :fullscreen="false"
+              class="im-message-history__calendar"
+            />
+            <div class="flex gap-2 justify-end px-2 pt-2">
+              <ElButton size="small" @click="datePopoverVisible = false">取消</ElButton>
+              <ElButton size="small" type="primary" @click="onDateConfirm">确定</ElButton>
+            </div>
+          </div>
+        </ElPopover>
+        <!-- 群成员：仅群聊；popover 内自带搜索 + GroupMember 列表 -->
+        <ElPopover
+          v-if="isGroup"
+          v-model="memberPopoverVisible"
+          trigger="click"
+          placement="bottom"
+          :width="320"
+        >
+          <template #reference>
+            <span
+              class="im-message-history__tab cursor-pointer"
+              :class="{ 'im-message-history__tab--active': activeFilter?.kind === 'member' }"
+            >
+              群成员
+            </span>
+          </template>
+          <div>
+            <ElInput v-model="memberSearchKeyword" placeholder="搜索群成员" size="small">
+              <template #prefix>
+                <Icon icon="ant-design:search-outlined" />
+              </template>
+            </ElInput>
+            <div class="max-h-[360px] overflow-y-auto mt-2">
+              <GroupMember
+                v-for="member in filteredMembersForPicker"
+                :key="member.userId"
+                :member="member"
+                :height="44"
+                :clickable="false"
+                class="cursor-pointer hover:bg-[var(--ant-color-fill)]"
+                @click="onMemberSelect(member)"
+              />
+              <div
+                v-if="filteredMembersForPicker.length === 0"
+                class="py-6 text-12px text-center text-[var(--ant-color-text-disabled)]"
+              >
+                没有匹配的成员
+              </div>
+            </div>
+          </div>
+        </ElPopover>
+      </div>
+
+      <!-- 消息列表 -->
+      <div class="flex-1 overflow-y-auto">
+        <template v-for="message in currentList" :key="message.id || message.clientMessageId">
+          <!-- 好友会话事件（FRIEND_ADD / FRIEND_DELETE）：居中灰色，不挂头像 / sender，
+               跟主聊天面板里 MessageItem 的渲染语义对齐 -->
+          <div
+            v-if="isFriendChatTip(message.type)"
+            class="px-4 py-3 text-12px text-center italic text-[var(--ant-color-text-secondary)] border-b border-b-solid border-[var(--ant-color-border-secondary)]"
+          >
+            <TipSegments :segments="resolveFriendNotificationSegments(message)" />
+          </div>
+
+          <!-- 群广播事件：跟好友事件同灰色样式，mention 段挂点击弹 UserInfoCard -->
+          <div
+            v-else-if="isGroupNotification(message.type)"
+            class="px-4 py-3 text-12px text-center italic text-[var(--ant-color-text-secondary)] border-b border-b-solid border-[var(--ant-color-border-secondary)]"
+          >
+            <TipSegments
+              :segments="resolveGroupNotificationSegments(message, resolveGroupMemberName(message))"
+            />
+          </div>
+
+          <!-- 普通消息行 -->
+          <div
+            v-else
+            class="im-message-history__row flex gap-3 items-start px-1 py-3 border-b border-b-solid border-[var(--ant-color-border-secondary)]"
+          >
+            <UserAvatar
+              :url="getAvatar(message)"
+              :name="senderRealNicknameOf(message)"
+              :size="36"
+              :clickable="false"
+            />
+            <div class="flex-1 min-w-0">
+              <div
+                class="flex justify-between items-start text-12px text-[var(--ant-color-text-secondary)]"
+              >
+                <span class="font-medium text-[var(--ant-color-text)]">
+                  {{ senderDisplayNameOf(message) }}
+                </span>
+                <span class="im-message-history__meta relative flex-shrink-0">
+                  <span class="block text-right">{{ formatHistoryTime(message.sendTime) }}</span>
+                  <!-- 定位到聊天位置：absolute 浮在时间下方，行 hover 才显示，
+                       不参与右侧栏 flex 排版（避免隐藏时占位让"我"和内容之间留空）；
+                       仅有真实 id 的消息才支持（本地占位消息不行） -->
+                  <span
+                    v-if="message.id && message.id > 0"
+                    class="im-message-history__locate"
+                    @click="locateMessage(message.id!)"
+                  >
+                    定位到聊天位置
+                  </span>
+                </span>
+              </div>
+
+              <div class="mt-1.5">
+                <!-- 撤回：单独走灰色 tip，sender 名段可点击 -->
+                <div
+                  v-if="message.type === ImContentType.RECALL"
+                  class="text-sm italic text-[var(--ant-color-text-secondary)]"
+                >
+                  <TipSegments :segments="recallTipSegmentsOf(message)" />
+                </div>
+                <!-- 其它类型走 MessageBubble 复用主聊天气泡 -->
+                <MessageBubble
+                  v-else
+                  :type="message.type"
+                  :content="message.content"
+                  @open-merge="openMergeDetail?.($event)"
+                />
+              </div>
+            </div>
+          </div>
+        </template>
+
+        <div
+          v-if="currentList.length === 0"
+          class="py-10 text-center text-13px text-[var(--ant-color-text-disabled)]"
+        >
+          {{ keyword || activeFilter ? '没有匹配的消息' : '暂无消息' }}
+        </div>
+
+        <!-- 加载更早消息：列表底部 trigger（reverse 后最早的在最下，按钮放底部更自然）；
+             filter 命中 0 条时仍保留 —— 加载更早可能带回匹配内容 -->
+        <div
+          v-if="hasMore && allMessages.length > 0"
+          class="py-3 text-center border-t border-t-solid border-[var(--ant-color-border-secondary)]"
+        >
+          <ElButton :loading="loadingMore" link @click="loadEarlier">
+            加载更早消息
+          </ElButton>
+        </div>
+        <!-- "没有更早" 只在已有匹配项时露出，避免和上面"没有匹配的消息"空态文案重叠 -->
+        <div
+          v-else-if="!hasMore && currentList.length > 0"
+          class="py-3 text-12px text-center text-[var(--ant-color-text-disabled)]"
+        >
+          没有更早的消息了
+        </div>
+      </div>
+    </div>
+  </ElDialog>
+</template>
+
+<style scoped>
+/* :deep 穿透 el-tag 子组件 DOM；搜索区 chip 禁掉 hover 颜色过渡 / × 图标动效，避免在搜索区里有抖动感 */
+.im-message-history__chip,
+.im-message-history__chip :deep(.el-tag__close) {
+  transition: none !important;
+  animation: none !important;
+}
+
+/* 「定位到聊天位置」按钮：父行 hover 才显示，走 .parent:hover .child 跨元素状态联动 */
+.im-message-history__locate {
+  position: absolute;
+  top: 100%;
+  right: 0;
+  margin-top: 4px;
+  display: none;
+  white-space: nowrap;
+  color: #1989fa;
+  cursor: pointer;
+  transition: color 0.15s;
+}
+.im-message-history__row:hover .im-message-history__locate {
+  display: block;
+}
+.im-message-history__locate:hover {
+  color: #146fc7;
+}
+
+/* ::after 伪元素画激活下划线；tab 默认蓝色行内文字，激活态加下划线 */
+.im-message-history__tab {
+  position: relative;
+  padding: 4px 2px;
+  color: #1989fa;
+  transition: color 0.15s;
+}
+.im-message-history__tab:hover {
+  color: #2f81d4;
+}
+.im-message-history__tab--active::after {
+  content: '';
+  position: absolute;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  height: 2px;
+  background: #1989fa;
+  border-radius: 1px;
+}
+
+/* 压缩日历间距，适配 320px popover */
+.im-message-history__calendar :deep(.el-calendar__header) {
+  padding: 4px 8px;
+}
+.im-message-history__calendar :deep(.el-calendar-table) {
+  font-size: 12px;
+}
+.im-message-history__calendar :deep(.el-calendar-table td) {
+  padding: 1px 0;
+}
+.im-message-history__calendar :deep(.el-calendar-day) {
+  height: 28px;
+  margin: 0 2px;
+  padding: 2px 4px 0;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-item.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-item.vue
new file mode 100644
index 000000000..e59f45695
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-item.vue
@@ -0,0 +1,1055 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from '../../../../components/group'
+import type { Message } from '../../../../types'
+
+import { computed, inject } from 'vue'
+
+import { confirm } from '@vben/common-ui'
+import { IconifyIcon as Icon } from '@vben/icons'
+import { useUserStore } from '@vben/stores'
+
+import { useClipboard } from '@vueuse/core'
+import { ElMessage, ElTag } from 'element-plus'
+
+import { pinGroupMessage as apiPinGroupMessage, cancelMuteMember } from '#/api/im/group'
+import { removeGroupMember } from '#/api/im/group/member'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+import {
+  MESSAGE_GROUP_READ_ENABLED,
+  MESSAGE_PRIVATE_READ_ENABLED,
+  MESSAGE_RECALL_WINDOW_MS,
+  MESSAGE_TIME_TIP_GAP_MS
+} from '#/views/im/utils/config'
+import {
+  ImContentType,
+  ImConversationType,
+  ImForwardMode,
+  ImFriendAddSource,
+  ImGroupMemberRole,
+  ImMessageReceiptStatus,
+  ImMessageStatus,
+  isFriendChatTip,
+  isGroupNotification,
+  isMediaMessageType,
+  isNormalMessage,
+  isRtcCallTip
+} from '#/views/im/utils/constants'
+import { buildRecallTipSegments } from '#/views/im/utils/conversation'
+import {
+  buildQuoteFromMessage,
+  type CardMessage,
+  extractAddableFace,
+  getQuoteFromMessage,
+  type MentionCandidate,
+  parseMessage,
+  type TextMessage
+} from '#/views/im/utils/message'
+import {
+  parseRtcCallPayload,
+  resolveFriendNotificationSegments,
+  resolveGroupNotificationSegments,
+  resolveRtcCallPrivateBubbleText,
+  resolveRtcCallTipSegments
+} from '#/views/im/utils/message'
+import { formatTimeTip } from '#/views/im/utils/time'
+import {
+  getMemberDisplayName,
+  getMentionCandidates,
+  getSenderDisplayName,
+  getSenderRealNickname,
+  isGroupQuit
+} from '#/views/im/utils/user'
+
+import { UserAvatar } from '../../../../components/user'
+import { mediaTypeHandlers, useMediaUploader } from '../../../../composables/useMediaUploader'
+import { useMessageMultiSelect } from '../../../../composables/useMessageMultiSelect'
+import { useMessageSender } from '../../../../composables/useMessageSender'
+import { useMuteOverlay } from '../../../../composables/useMuteOverlay'
+import { useConversationStore } from '../../../../store/conversationStore'
+import { useFaceStore } from '../../../../store/faceStore'
+import { useFriendStore } from '../../../../store/friendStore'
+import { useGroupStore } from '../../../../store/groupStore'
+import { useMessageStore } from '../../../../store/messageStore'
+import { useImUiStore } from '../../../../store/uiStore'
+import {
+  IM_FORWARD_DIALOG_KEY,
+  IM_MERGE_DETAIL_DIALOG_KEY,
+  IM_RTC_REDIAL_KEY
+} from './forward/keys'
+import MessageBubble from './message-bubble.vue'
+import MessageReadStatus from './message-read-status.vue'
+import ReplyPreview from './reply-preview.vue'
+import TipSegments from './tip-segments.vue'
+
+defineOptions({ name: 'ImMessageItem' })
+
+const props = defineProps<{
+  message: Message
+  /** 列表中的上一条消息，用于判断是否要在当前消息上方渲染时间分隔条；不传按列表第一条处理 */
+  prevMessage?: Message
+}>()
+
+const emit = defineEmits<{
+  /** 引用块点击 → MessagePanel 滚定位 + 高亮 */
+  locate: [messageId: number]
+  /** 禁言：需要父组件打开时长选择弹窗 */
+  mute: [groupId: number, userId: number, displayName: string]
+  /** 数据变更后刷新群信息 */
+  reload: []
+}>()
+
+// ==================== Stores / Hooks ====================
+
+const userStore = useUserStore()
+const conversationStore = useConversationStore()
+const messageStore = useMessageStore()
+const groupStore = useGroupStore()
+const friendStore = useFriendStore()
+const faceStore = useFaceStore()
+const uiStore = useImUiStore()
+const { recall, sendRaw } = useMessageSender()
+const { uploadAndSendMedia } = useMediaUploader()
+const muteOverlay = useMuteOverlay()
+// legacy:true 兼容 HTTP 环境，没有 navigator.clipboard 时降级到 execCommand
+const { copy: copyToClipboard } = useClipboard({ legacy: true })
+
+// ==================== 内容类型判断 ====================
+
+/** 是否在当前消息上方渲染时间分隔条：列表第一条 / 距上一条超过阈值；缺 sendTime 不渲染；频道素材每条都显示 */
+const shouldShowTimeTip = computed(() => {
+  if (!props.message.sendTime) {
+    return false
+  }
+  if (isMaterial.value) {
+    return true
+  }
+  if (!props.prevMessage?.sendTime) {
+    return true
+  }
+  return props.message.sendTime - props.prevMessage.sendTime > MESSAGE_TIME_TIP_GAP_MS
+})
+
+/** 仅 MessageItem 自身仍要用到的 type 判定（其它分支已下沉到 MessageBubble） */
+const isVoice = computed(() => props.message.type === ImContentType.VOICE)
+const isMerge = computed(() => props.message.type === ImContentType.MERGE)
+/**
+ * 频道素材在「频道会话」内仿微信公众号样式（居中 + 无头像）；
+ * 私聊 / 群聊里被转发过来的素材按 selfSend 走标准气泡布局（自己右、对方左、带头像）
+ */
+const isMaterial = computed(
+  () =>
+    props.message.type === ImContentType.MATERIAL &&
+    conversationStore.activeConversation?.type === ImConversationType.CHANNEL
+)
+
+/** 当前是否在公众号 / 频道会话内：限制右键菜单只展示转发 / 删除 */
+const isChannelConversation = computed(
+  () => conversationStore.activeConversation?.type === ImConversationType.CHANNEL
+)
+
+// ==================== 事件消息（撤回 / 好友 / 群广播） ====================
+// 这三类不走普通气泡，渲染成居中灰色 tip；判断 + 文案配对放一起，新增第四类事件只需在本块改完
+
+/** 是否已撤回：pull / WS 两路都会调 recallMessage 把原消息更新为 type=RECALL，渲染只需识别 type */
+const isRecall = computed(() => props.message.type === ImContentType.RECALL)
+
+/** 撤回提示 segments：依赖 activeConversation 实时算 sender 名 */
+const recallTipSegments = computed(() => {
+  const conversation = conversationStore.activeConversation
+  return buildRecallTipSegments(
+    props.message.senderId,
+    props.message.selfSend,
+    conversation?.type ?? 0,
+    conversation?.targetId ?? 0
+  )
+})
+
+/** 是否会话内好友事件气泡（FRIEND_ADD / FRIEND_DELETE） */
+const isFriendChatTipMessage = computed(() => isFriendChatTip(props.message.type))
+
+/** 好友事件 segments */
+const friendChatTipSegments = computed(() => resolveFriendNotificationSegments(props.message))
+
+/** 是否群广播事件（GROUP_CREATE..GROUP_BANNED 段位，排除 GROUP_MEMBER_SETTING_UPDATE 个人信号） */
+const isGroupNotificationMessage = computed(() => isGroupNotification(props.message.type))
+
+/** 群广播事件 segments */
+const groupNotificationSegments = computed(() =>
+  resolveGroupNotificationSegments(props.message, (id: number) =>
+    getSenderDisplayName(id, ImConversationType.GROUP, props.message.targetId ?? 0)
+  )
+)
+
+/** 私聊 RTC_CALL_END 走「准气泡」（左右分布 + 电话图标 + 文案）；非私聊场景为 null */
+const rtcCallEndPrivatePayload = computed(() => {
+  if (props.message.type !== ImContentType.RTC_CALL_END) {
+    return null
+  }
+  const payload = parseRtcCallPayload(props.message.content)
+  return payload?.conversationType === ImConversationType.PRIVATE ? payload : null
+})
+
+/** 是否私聊通话气泡 */
+const isRtcCallPrivateBubbleMessage = computed(() => rtcCallEndPrivatePayload.value !== null)
+
+/** 私聊通话气泡文案（按 operatorUserId 是否当前用户区分；对齐微信两端不同视角） */
+const rtcCallPrivateBubbleText = computed(() =>
+  resolveRtcCallPrivateBubbleText(rtcCallEndPrivatePayload.value)
+)
+
+/** 是否会话内群通话事件居中 tip */
+const isRtcCallTipMessage = computed(() => {
+  if (!isRtcCallTip(props.message.type)) {
+    return false
+  }
+  const payload = parseRtcCallPayload(props.message.content)
+  if (payload?.conversationType !== ImConversationType.GROUP) {
+    return false
+  }
+  return !isRtcCallPrivateBubbleMessage.value
+})
+
+/** 通话事件 segments；仅群聊 tip 用 */
+const rtcCallTipSegments = computed(() => resolveRtcCallTipSegments(props.message))
+
+// ==================== 消息内容解析 / payload ====================
+
+/** 引用对象：气泡内嵌入展示；非引用消息返回 null，模板 v-if 不渲染 */
+const quote = computed(() => getQuoteFromMessage(props.message.content))
+
+const openForwardDialog = inject(IM_FORWARD_DIALOG_KEY) // MessagePanel 注入的弹窗触发函数
+const openMergeDetail = inject(IM_MERGE_DETAIL_DIALOG_KEY)
+const redialRtcCall = inject(IM_RTC_REDIAL_KEY)
+
+/** 私聊 RTC_CALL_END 气泡点击：用同款 mediaType 重拨 */
+function handleRtcCallBubbleClick() {
+  const mediaType = rtcCallEndPrivatePayload.value?.mediaType
+  if (mediaType == null) {
+    return
+  }
+  redialRtcCall?.(mediaType)
+}
+
+const multiSelect = useMessageMultiSelect() // 多选模式：模块级单例 composable
+
+/** 合并消息气泡点击：打开详情弹窗（嵌套合并由弹窗内部 push 栈） */
+function handleMergeOpen(content: string) {
+  openMergeDetail?.(content)
+}
+
+/** 文本气泡 @ mention 候选名字：仅群消息有效，按 atUserIds 反查群成员真实昵称；非 TEXT 不走 store 读，让 getMentionCandidates 直接返回稳定空数组 */
+const textMentions = computed<MentionCandidate[]>(() => {
+  if (props.message.type !== ImContentType.TEXT) {
+    return getMentionCandidates(undefined, null)
+  }
+  return getMentionCandidates(props.message.atUserIds, conversationStore.activeConversation)
+})
+
+/** 名片点击：用户名片弹 UserInfoCard，群名片弹 GroupInfoCard；其它 targetType（含改包脏数据）忽略 */
+function handleCardClick(card: CardMessage, e: MouseEvent) {
+  if (!card?.targetId) {
+    return
+  }
+  if (card.targetType === ImConversationType.PRIVATE) {
+    uiStore.openUserInfoCardAtEvent(
+      { id: card.targetId, nickname: card.name, avatar: card.avatar },
+      e,
+      ImFriendAddSource.CARD
+    )
+    return
+  }
+  if (card.targetType === ImConversationType.GROUP) {
+    uiStore.openGroupInfoCardAtEvent(
+      {
+        id: card.targetId,
+        name: card.name,
+        showImage: card.avatar,
+        memberCount: card.memberCount
+      },
+      e
+    )
+  }
+}
+
+/** 媒体上传中：MessageBubble 自渲染遮罩 / 进度条；外层只用作 showSendingLoading 判定 */
+const isUploading = computed(() => props.message.uploadProgress != null)
+
+/**
+ * 是否在气泡尾部显示「发送中」loading 转圈
+ *
+ * 图片 / 视频 / 文件气泡内嵌已有进度反馈（遮罩 / 进度条），外层 loading 不再叠加；
+ * 语音气泡只有麦克风 + 时长，无内嵌进度，必须保留外层 loading 让用户感知正在发送
+ */
+const showSendingLoading = computed(
+  () => props.message.status === ImMessageStatus.SENDING && (!isUploading.value || isVoice.value)
+)
+
+// ==================== 发送人 / 已读 / @ ====================
+
+/** 群聊 + 对方消息 时，在气泡上方显示发送者昵称 */
+const showSenderName = computed(() => {
+  if (props.message.selfSend) {
+    return false
+  }
+  return conversationStore.activeConversation?.type === ImConversationType.GROUP
+})
+
+/** 发送者头像；私聊的 conversation.avatar 就是对方头像（openConversation 入参约定） */
+const senderAvatar = computed(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || props.message.selfSend) {
+    return ''
+  }
+  if (conversation.type === ImConversationType.GROUP) {
+    const group = groupStore.getGroup(conversation.targetId)
+    return group?.members?.find((member) => member.userId === props.message.senderId)?.avatar || ''
+  }
+  return conversation.avatar || ''
+})
+
+/** 头像色卡 fallback 文本：永远是真实昵称，不掺备注 */
+const senderRealNickname = computed(() => {
+  const conversation = conversationStore.activeConversation
+  return getSenderRealNickname(
+    props.message.senderId,
+    conversation?.type ?? 0,
+    conversation?.targetId ?? 0
+  )
+})
+
+/** 气泡上方发送人显示名（仅群聊对方消息显示）：好友备注 > 群备注 > 真实昵称 */
+const senderDisplayName = computed(() => {
+  const conversation = conversationStore.activeConversation
+  return getSenderDisplayName(
+    props.message.senderId,
+    conversation?.type ?? 0,
+    conversation?.targetId ?? 0
+  )
+})
+
+/** 私聊「已读 / 未读」态（仅对自己发送的私聊消息展示；私聊已读全局关闭时不再展示） */
+const privateReadLabel = computed(() => {
+  if (!MESSAGE_PRIVATE_READ_ENABLED) {
+    return ''
+  }
+  if (!props.message.selfSend) {
+    return ''
+  }
+  if (conversationStore.activeConversation?.type !== ImConversationType.PRIVATE) {
+    return ''
+  }
+  if (props.message.receiptStatus === ImMessageReceiptStatus.DONE) {
+    return '已读'
+  }
+  if (props.message.receiptStatus === ImMessageReceiptStatus.PENDING) {
+    return '未读'
+  }
+  return ''
+})
+
+/** 是否需要显示群回执 popover：自己发的群消息且后端开启了回执（NO_RECEIPT 表示发送时未要求回执，不渲染；群已读全局关闭时统一不展示） */
+const showGroupReadStatus = computed(() => {
+  if (!MESSAGE_GROUP_READ_ENABLED) {
+    return false
+  }
+  if (!props.message.selfSend) {
+    return false
+  }
+  if (conversationStore.activeConversation?.type !== ImConversationType.GROUP) {
+    return false
+  }
+  const status = props.message.receiptStatus
+  if (status === undefined || status === null) {
+    return false
+  }
+  return status !== ImMessageReceiptStatus.NO_RECEIPT
+})
+
+/** 当前群成员（供 MessageReadStatus 计算未读名单；未加载完时兜底空数组不渲染） */
+const groupMembersForReadStatus = computed<GroupMemberLite[]>(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || conversation.type !== ImConversationType.GROUP) {
+    return []
+  }
+  const group = groupStore.getGroup(conversation.targetId)
+  return (group?.members || []).map((member) => {
+    const friend = friendStore.getFriend(member.userId)
+    return {
+      userId: member.userId,
+      showName: getMemberDisplayName(member, friend),
+      nickname: member.nickname,
+      avatar: member.avatar,
+      status: member.status
+    }
+  })
+})
+
+/** 是否 @我（群消息展示小徽标） */
+const isAtMe = computed(() => {
+  const myId = getCurrentUserId()
+  if (!myId) {
+    return false
+  }
+  return (props.message.atUserIds || []).includes(myId)
+})
+
+// ==================== 右键菜单 / 操作 ====================
+
+// 右键菜单 key 常量；push 端和分发端从同一处取，typo 编译期就能抓
+const MENU_KEYS = {
+  COPY: 'COPY',
+  REPLY: 'REPLY',
+  FORWARD: 'FORWARD',
+  MULTI_SELECT: 'MULTI_SELECT',
+  PIN: 'PIN',
+  ADD_TO_FACE: 'ADD_TO_FACE',
+  MUTE: 'MUTE',
+  UNMUTE: 'UNMUTE',
+  KICK: 'KICK',
+  RECALL: 'RECALL',
+  DELETE: 'DELETE'
+} as const
+type MenuKey = (typeof MENU_KEYS)[keyof typeof MENU_KEYS]
+
+/**
+ * 右键菜单项：
+ * - 引用：已落库 + 未撤回的消息可引用，引用块写入会话草稿
+ * - 撤回 / 删除：互斥；自己发送 + 已落库 + 未撤回 + 2 分钟内显示「撤回」（推服务器），其它显示「删除」（仅本地清）
+ *
+ * 好友事件气泡态不弹菜单
+ */
+async function handleContextMenu(e: MouseEvent) {
+  if (isFriendChatTipMessage.value) {
+    return
+  }
+  // 多选模式下不弹菜单：右键点击就当切换勾选，与单击行为一致
+  if (isInMultiSelect.value) {
+    if (canForward.value) {
+      multiSelect.toggle(props.message)
+    }
+    return
+  }
+
+  type MenuItem = {
+    danger?: boolean
+    disabled?: boolean
+    divided?: boolean
+    icon?: string
+    key: MenuKey
+    name: string
+  }
+  // 频道（公众号）会话单向消息：只保留转发 + 本地删除；不支持复制 / 引用 / 多选 / 撤回 / 群管理操作
+  if (isChannelConversation.value) {
+    const channelItems: MenuItem[] = []
+    if (canForward.value) {
+      channelItems.push({
+        key: MENU_KEYS.FORWARD,
+        name: '转发',
+        icon: 'ant-design:share-alt-outlined'
+      })
+    }
+    channelItems.push({
+      key: MENU_KEYS.DELETE,
+      name: '删除',
+      icon: 'ant-design:delete-outlined',
+      divided: true,
+      danger: true
+    })
+    uiStore.openContextMenu({ x: e.clientX, y: e.clientY }, channelItems, async (item) => {
+      if (item.key === MENU_KEYS.FORWARD) {
+        handleForward()
+      } else if (item.key === MENU_KEYS.DELETE) {
+        handleDelete()
+      }
+    })
+    return
+  }
+
+  const items: MenuItem[] = []
+  // 「复制」：仅文本消息支持；放在第一项，对齐微信桌面右键习惯
+  if (props.message.type === ImContentType.TEXT) {
+    items.push({
+      key: MENU_KEYS.COPY,
+      name: '复制',
+      icon: 'ant-design:copy-outlined'
+    })
+  }
+  // 「引用」：已落库 + 未撤回 + 非合并转发；MERGE 内嵌快照在引用预览里无法降级展示
+  if (!!props.message.id && !isRecall.value && !isMerge.value) {
+    items.push({
+      key: MENU_KEYS.REPLY,
+      name: '引用',
+      icon: 'bxs:quote-alt-left'
+    })
+  }
+  // 「转发」「多选」：已落库 + 普通消息 + 未撤回；触发 ForwardDialog / 进入多选模式
+  if (canForward.value) {
+    items.push({
+      key: MENU_KEYS.FORWARD,
+      name: '转发',
+      icon: 'ant-design:share-alt-outlined'
+    }, {
+      key: MENU_KEYS.MULTI_SELECT,
+      name: '多选',
+      icon: 'ant-design:check-square-outlined'
+    })
+  }
+  // 「置顶」：仅群聊 + 普通消息 + 已落库 + 未撤回 + 群主或管理员；已置顶不再展示，由置顶面板的「移除」入口承接
+  // 不本地预判上限，让后端校验，超限时通过 error toast 反馈
+  if (canPin.value) {
+    items.push({
+      key: MENU_KEYS.PIN,
+      name: '置顶',
+      icon: 'ant-design:pushpin-outlined'
+    })
+  }
+  // 「添加到表情」：FACE / IMAGE 消息 + 已落库 + 未撤回；写入个人表情包，对照微信「添加到表情」
+  if (canAddToFace.value) {
+    items.push({
+      key: MENU_KEYS.ADD_TO_FACE,
+      name: '添加到表情',
+      icon: 'ant-design:smile-outlined'
+    })
+  }
+  // 「禁言 / 解禁 / 移除」：群聊 + 非自己消息 + 我是群主或管理员
+  if (currentGroup.value && !props.message.selfSend && canManageSender.value) {
+    const senderMember = currentGroup.value.members?.find(
+      (m) => m.userId === props.message.senderId
+    )
+    const isMuted = senderMember?.muteEndTime && new Date(senderMember.muteEndTime) > new Date()
+    if (isMuted) {
+      items.push({
+        key: MENU_KEYS.UNMUTE,
+        name: '解除禁言',
+        icon: 'ant-design:audio-outlined',
+        divided: true
+      })
+    } else {
+      items.push({
+        key: MENU_KEYS.MUTE,
+        name: '禁言',
+        icon: 'ant-design:audio-muted-outlined',
+        divided: true
+      })
+    }
+    items.push({
+      key: MENU_KEYS.KICK,
+      name: '移除',
+      icon: 'ant-design:user-delete-outlined',
+      danger: true
+    })
+  }
+  // 「撤回 / 删除」二选一：
+  // - 自己发送 + 已落库 + 未撤回 + 在撤回窗口内 → 撤回（推服务器把消息态置 RECALL）
+  // - 其它（对方消息 / 已撤回 / 超出撤回窗口）→ 删除（仅本地清，不动后端）
+  // divided 把这一项和上面的「引用」隔开，danger 显红对齐微信
+  const canRecall =
+    props.message.selfSend &&
+    !!props.message.id &&
+    !isRecall.value &&
+    Date.now() - props.message.sendTime <= MESSAGE_RECALL_WINDOW_MS
+  if (canRecall) {
+    items.push({
+      key: MENU_KEYS.RECALL,
+      name: '撤回',
+      icon: 'ant-design:undo-outlined',
+      divided: true,
+      danger: true
+    })
+  } else {
+    items.push({
+      key: MENU_KEYS.DELETE,
+      name: '删除',
+      icon: 'ant-design:delete-outlined',
+      divided: true,
+      danger: true
+    })
+  }
+
+  // 把菜单渲染交给全局 uiStore（单例，避免每条消息都挂一份菜单 DOM）
+  const menuHandlers: Record<MenuKey, () => Promise<void> | void> = {
+    [MENU_KEYS.COPY]: handleCopy,
+    [MENU_KEYS.REPLY]: handleReply,
+    [MENU_KEYS.FORWARD]: handleForward,
+    [MENU_KEYS.MULTI_SELECT]: handleEnterMultiSelect,
+    [MENU_KEYS.PIN]: handlePin,
+    [MENU_KEYS.ADD_TO_FACE]: handleAddToFace,
+    [MENU_KEYS.MUTE]: handleMute,
+    [MENU_KEYS.UNMUTE]: handleUnmute,
+    [MENU_KEYS.KICK]: handleKick,
+    [MENU_KEYS.RECALL]: handleRecall,
+    [MENU_KEYS.DELETE]: handleDelete
+  }
+  uiStore.openContextMenu({ x: e.clientX, y: e.clientY }, items, async (item) => {
+    await menuHandlers[item.key as MenuKey]?.()
+  })
+}
+
+/** 是否可「添加到表情」：FACE / IMAGE 消息 + 已落库 + 未撤回（GIF / 静图都允许） */
+const canAddToFace = computed(() => {
+  if (isRecall.value || !props.message.id) {
+    return false
+  }
+  return extractAddableFace(props.message) !== null
+})
+
+/** 添加到个人表情：从 message 抽 url + 尺寸 + name 写入个人表情库 */
+async function handleAddToFace() {
+  const payload = extractAddableFace(props.message)
+  if (!payload) {
+    return
+  }
+  const data = await faceStore.addFaceUserItem(payload)
+  if (data) {
+    ElMessage.success('已添加到表情')
+  }
+}
+
+/** 当前激活会话对应的群（私聊场景为 undefined） */
+const currentGroup = computed(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || conversation.type !== ImConversationType.GROUP) {
+    return undefined
+  }
+  return groupStore.getGroup(conversation.targetId)
+})
+
+/** 当前用户在该群里的角色；私聊或非群成员 → undefined */
+const myGroupRole = computed(() => {
+  const myId = getCurrentUserId()
+  return currentGroup.value?.members?.find((m) => m.userId === myId)?.role
+})
+
+/** 是否可管理该消息发送人：我的角色高于目标角色（群主 > 管理员 > 普通成员）；目标角色未知时不展示 */
+const canManageSender = computed(() => {
+  // 历史退群群：本地可能残留成员缓存，显式排除，避免右键仍出「禁言 / 移除」
+  if (!currentGroup.value || isGroupQuit(currentGroup.value) || !myGroupRole.value) {
+    return false
+  }
+  const senderMember = currentGroup.value.members?.find((m) => m.userId === props.message.senderId)
+  // 成员缓存不完整时不展示管理操作，等成员数据补齐后再判断
+  if (!senderMember?.role) {
+    return false
+  }
+  // 角色数值：1=群主 2=管理员 3=普通成员；数值越小权限越高
+  return myGroupRole.value < senderMember.role
+})
+
+/** 是否允许转发 / 多选：普通消息 + 已落库 + 未撤回；本地占位 / 撤回 / 事件消息一律不可 */
+const canForward = computed(
+  () => isNormalMessage(props.message.type) && !!props.message.id && !isRecall.value
+)
+
+/** 多选模式是否激活；切换会话由 index.vue 主动 exitMultiSelect */
+const isInMultiSelect = computed(() => multiSelect.state.active)
+
+/** 当前消息是否已勾选 */
+const isMessageChecked = computed(() => {
+  if (!isInMultiSelect.value) {
+    return false
+  }
+  return multiSelect.selectedIdSet.value.has(props.message.clientMessageId)
+})
+
+/** 多选模式下点击气泡：可转发的消息切换勾选；事件 / 撤回 / 占位等不响应（直接吃掉点击避免触发图片预览等） */
+function handleMultiSelectClick(e: MouseEvent) {
+  if (!isInMultiSelect.value) {
+    return
+  }
+  e.preventDefault()
+  e.stopPropagation()
+  if (!canForward.value) {
+    return
+  }
+  multiSelect.toggle(props.message)
+}
+
+/** 是否允许置顶（已置顶消息不再展示菜单项，由置顶面板的「移除」入口承接）：群聊 + 普通消息 + 已落库 + 未撤回 + 群主或管理员 + 未置顶 */
+const canPin = computed(
+  () =>
+    !!currentGroup.value &&
+    !isGroupQuit(currentGroup.value) &&
+    isNormalMessage(props.message.type) &&
+    !!props.message.id &&
+    !isRecall.value &&
+    (myGroupRole.value === ImGroupMemberRole.OWNER ||
+      myGroupRole.value === ImGroupMemberRole.ADMIN) &&
+    !currentGroup.value.pinnedMessages?.some((m) => m.id === props.message.id)
+)
+
+/** 置顶消息：二次确认 → 调后端 pin-message；后端广播 GROUP_MESSAGE_PIN，本端 dispatcher 拉最新 pinnedMessages */
+async function handlePin() {
+  const group = currentGroup.value
+  if (!group || !props.message.id) {
+    return
+  }
+  try {
+    await confirm('将在当前群成员的聊天中置顶', '置顶消息')
+    await apiPinGroupMessage({ id: group.id, messageId: props.message.id })
+    ElMessage.success('已置顶')
+  } catch {}
+}
+
+/** 复制文本消息：解出 content 字段写入剪贴板，提示「内容已复制到剪贴板」 */
+async function handleCopy() {
+  const text = parseMessage<TextMessage>(props.message.content)?.content
+  if (!text) {
+    return
+  }
+  await copyToClipboard(text)
+  ElMessage.success('内容已复制到剪贴板')
+}
+
+/** 进入引用模式：把当前消息构造成 QuoteMessage 写入会话草稿 */
+function handleReply() {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  conversationStore.setConversationReplyDraft(conversation, buildQuoteFromMessage(props.message))
+}
+
+/** 转发当前消息：打开 ForwardDialog（单条模式；mode=single 即原样转） */
+function handleForward() {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  openForwardDialog?.({
+    mode: ImForwardMode.SINGLE,
+    messages: [props.message],
+    sourceConversation: conversation
+  })
+}
+
+/** 进入多选模式，初始勾选当前消息 */
+function handleEnterMultiSelect() {
+  multiSelect.enter(props.message)
+}
+
+/**
+ * 撤回消息：弹确认框 → 调 useMessageSender.recall → 后端通过 WS RECALL 事件推回，
+ * websocketStore 把对应 message 的 type 改成 RECALL，UI 自动切到"XX 撤回了一条消息"
+ *
+ * 不做乐观撤回：失败 / 超时 / 后端拒绝时本端状态可能与服务端漂移，统一让 WS 回推最稳
+ */
+async function handleRecall() {
+  try {
+    await confirm('确定要撤回这条消息吗？', '撤回消息')
+    await recall(props.message)
+  } catch {}
+}
+
+/**
+ * 失败消息点击重试
+ *
+ * - 媒体消息（image / file / voice / video）：_localFile 在内存就重走 uploadAndSendMedia（重新上传 + 占位 + 进度）
+ * - 文本消息：复用原 clientMessageId + status 回滚到 SENDING，走 existingClientMessageId 路径让服务端按 cmid 幂等
+ *
+ * 媒体类型若 _localFile 已丢（理论上 IDB 恢复阶段就被 drop，进不到这里；保险起见仍走文本兜底）则按文本路径重发，
+ * 后端拒绝失效 blob URL 时再次 FAILED，用户可右键删除
+ *
+ * 不还原原 receipt：群回执是发送时的扩展选项、不会持久化到 message，强行猜测可能与原意不符；
+ * 默认按"无回执"重发，绝大多数场景符合预期，要回执就重新发一次更直观
+ */
+async function handleResend() {
+  if (props.message.status !== ImMessageStatus.FAILED) {
+    return
+  }
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  // 禁言 / 封禁时拦截：避免重试绕过 MessageInput 的 muteOverlay 又走一次 sendRaw 让后端拒
+  if (muteOverlay.value) {
+    return
+  }
+  const message = props.message
+  const file = message._localFile
+
+  // 媒体类型 + _localFile 在 → 重走 uploadAndSendMedia；type 分发 + 旧元数据复用统一在 mediaTypeHandlers 表里
+  if (isMediaMessageType(message.type) && file) {
+    const handler = mediaTypeHandlers[message.type]
+    if (handler) {
+      const oldQuote = getQuoteFromMessage(message.content) ?? undefined
+      const context = handler.extractResendContext(message.content)
+      await uploadAndSendMedia({
+        file,
+        type: message.type,
+        quote: oldQuote,
+        conversation,
+        context,
+        existingClientMessageId: message.clientMessageId
+      })
+      return
+    }
+  }
+
+  // 文本类型 / 媒体类型但 _localFile 已丢：把 FAILED 占位回滚到 SENDING，复用 clientMessageId 让服务端按 cmid 幂等去重
+  messageStore.patchMessage(conversation.type, conversation.targetId, message.clientMessageId, {
+    status: ImMessageStatus.SENDING
+  })
+  await sendRaw(message.type, message.content, {
+    atUserIds: message.atUserIds,
+    existingClientMessageId: message.clientMessageId
+  })
+}
+
+/**
+ * 删除消息：本地软删，仅从 messageStore 移除，不调后端
+ * 区别于"撤回"：服务端没动，多端登录时其它客户端 / 群里其他人依然能看到这条
+ */
+/** 禁言：emit 给父组件打开时长选择弹窗（避免 MessageItem 过重） */
+function handleMute() {
+  const group = currentGroup.value
+  if (!group) {
+    return
+  }
+  const name = senderDisplayName.value || '该成员'
+  emit('mute', group.id, props.message.senderId, name)
+}
+
+/** 解除禁言 */
+async function handleUnmute() {
+  const group = currentGroup.value
+  if (!group) {
+    return
+  }
+  try {
+    await confirm('确定解除该成员的禁言吗？', '解除禁言')
+    await cancelMuteMember({ id: group.id, userId: props.message.senderId })
+    ElMessage.success('已解除禁言')
+    emit('reload')
+  } catch {}
+}
+
+/** 移除群成员 */
+async function handleKick() {
+  const group = currentGroup.value
+  if (!group) {
+    return
+  }
+  const name = senderDisplayName.value || '该成员'
+  try {
+    await confirm(`确定将「${name}」移出群聊吗？`, '移除成员')
+    await removeGroupMember({ groupId: group.id, memberUserIds: [props.message.senderId] })
+    ElMessage.success('已移除')
+    emit('reload')
+  } catch {}
+}
+
+function handleDelete() {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  messageStore.removeMessage(conversation.type, conversation.targetId, {
+    id: props.message.id,
+    clientMessageId: props.message.clientMessageId
+  })
+}
+</script>
+
+<template>
+  <!-- 时间分隔条：列表第一条 / 距上一条超过阈值时居中显示灰色时间 -->
+  <div
+    v-if="shouldShowTimeTip"
+    class="flex items-center justify-center px-4 py-2 text-12px text-[var(--ant-color-text-disabled)]"
+  >
+    {{ formatTimeTip(message.sendTime) }}
+  </div>
+
+  <!-- 好友会话事件（FRIEND_ADD / FRIEND_DELETE）：跟群广播事件同灰色样式，文案固定 -->
+  <div
+    v-if="isFriendChatTipMessage"
+    class="flex items-center justify-center px-4 py-2 text-12px text-[var(--ant-color-text-secondary)]"
+  >
+    <TipSegments :segments="friendChatTipSegments" />
+  </div>
+
+  <!-- 群广播事件：跟好友事件同灰色样式，mention 段挂点击弹 UserInfoCard -->
+  <div
+    v-else-if="isGroupNotificationMessage"
+    class="flex items-center justify-center px-4 py-2 text-12px text-[var(--ant-color-text-secondary)]"
+  >
+    <TipSegments :segments="groupNotificationSegments" />
+  </div>
+
+  <!-- 群通话事件（RTC_CALL_START / RTC_CALL_END）：居中灰色 tip 两段式 -->
+  <div
+    v-else-if="isRtcCallTipMessage"
+    class="flex items-center justify-center px-4 py-2 text-12px text-[var(--ant-color-text-secondary)]"
+  >
+    <TipSegments :segments="rtcCallTipSegments" />
+  </div>
+
+  <!-- 私聊通话结束（RTC_CALL_END）：仿微信「准气泡」；按 selfSend 左右分布；电话图标 + 文案 -->
+  <div v-else-if="isRtcCallPrivateBubbleMessage" class="flex gap-2 items-start px-4 py-2">
+    <div
+      class="flex flex-1 min-w-0 gap-2 items-start"
+      :class="{ 'flex-row-reverse': message.selfSend }"
+    >
+      <UserAvatar
+        :id="message.selfSend ? getCurrentUserId() : message.senderId"
+        :name="senderRealNickname"
+        :url="message.selfSend ? userStore.userInfo?.avatar : senderAvatar"
+        :size="36"
+      />
+      <div
+        class="flex gap-2 items-center px-3.5 py-2 text-sm rounded-lg cursor-pointer"
+        :class="
+          message.selfSend
+            ? 'text-black bg-[#95ec69]'
+            : 'text-[var(--ant-color-text)] bg-[var(--ant-color-fill-secondary)]'
+        "
+        @click="handleRtcCallBubbleClick"
+      >
+        <Icon icon="ant-design:phone-outlined" :size="16" class="rotate-[135deg] flex-shrink-0" />
+        <span class="whitespace-nowrap">{{ rtcCallPrivateBubbleText }}</span>
+      </div>
+    </div>
+  </div>
+
+  <!-- 撤回消息：整行灰色 tip，sender 名段可点击 -->
+  <div
+    v-else-if="isRecall"
+    class="flex items-center justify-center px-4 py-2 text-12px text-[var(--ant-color-text-secondary)]"
+  >
+    <TipSegments :segments="recallTipSegments" />
+  </div>
+
+  <!-- 普通消息气泡 -->
+  <div
+    v-else
+    class="flex gap-2 items-start px-4 py-2"
+    :class="{ 'cursor-pointer': isInMultiSelect }"
+    @contextmenu.prevent="handleContextMenu"
+    @click.capture="handleMultiSelectClick"
+  >
+    <!-- 多选指示：永远在整行最左侧（自己 / 对方消息一致），不参与 selfSend reverse -->
+    <span
+      v-if="isInMultiSelect"
+      class="flex flex-shrink-0 items-center justify-center mt-3 w-5 h-5 rounded-full transition-colors"
+      :class="
+        isMessageChecked
+          ? 'bg-[#07c160]'
+          : 'border border-solid border-[var(--ant-color-border)] bg-[var(--ant-color-bg-container)]'
+      "
+    >
+      <Icon v-if="isMessageChecked" icon="ant-design:check-outlined" :size="12" color="#fff" />
+    </span>
+
+    <!-- 消息行：头像 + 气泡内部按 selfSend reverse；频道素材仿公众号样式居中且不显示头像 -->
+    <div
+      class="flex flex-1 min-w-0 gap-2 items-start"
+      :class="{ 'flex-row-reverse': message.selfSend, 'justify-center': isMaterial }"
+    >
+      <!-- 头像：点击弹 UserInfoCard 由 UserAvatar 内部承接；频道素材消息不显示头像 -->
+      <UserAvatar
+        v-if="!isMaterial"
+        :id="message.selfSend ? getCurrentUserId() : message.senderId"
+        :name="senderRealNickname"
+        :url="message.selfSend ? userStore.userInfo?.avatar : senderAvatar"
+        :size="36"
+      />
+
+      <div
+        class="flex flex-col gap-0.5"
+        :class="[
+          message.selfSend ? 'items-end' : '',
+          // 公众号会话内素材：固定 360 宽（对齐微信公众号卡片）；其它（含私聊 / 群聊转发的素材）：70% 上限，气泡自己撑宽度
+          isMaterial ? 'w-[360px]' : 'max-w-[70%]'
+        ]"
+      >
+        <!-- 群聊对方消息：气泡上方显示发送者昵称 -->
+        <div
+          v-if="showSenderName"
+          class="mb-0.5 text-12px text-[var(--ant-color-text-secondary)] leading-tight"
+        >
+          {{ senderDisplayName }}
+        </div>
+        <div class="flex gap-1.5 items-center" :class="{ 'flex-row-reverse': message.selfSend }">
+          <!-- 消息内容：按 type 走 9 类气泡，统一由 MessageBubble 渲染 -->
+          <MessageBubble
+            :type="message.type"
+            :content="message.content"
+            :self-send="message.selfSend"
+            :upload-progress="message.uploadProgress"
+            :mentions="textMentions"
+            @click-card="handleCardClick"
+            @open-merge="handleMergeOpen"
+          />
+
+          <!-- 状态区：自己消息展示发送状态 + 已读/群回执；对方消息 + @自己时展示 @徽标 -->
+          <div class="flex gap-1.5 items-center text-base">
+            <template v-if="message.selfSend">
+              <Icon
+                v-if="showSendingLoading"
+                icon="ant-design:loading-outlined"
+                class="im-loading-spin"
+              />
+              <Icon
+                v-else-if="message.status === ImMessageStatus.FAILED"
+                icon="ant-design:warning-filled"
+                color="#f56c6c"
+                class="cursor-pointer"
+                content="发送失败，点击重试"
+                @click="handleResend"
+              />
+              <!-- 已读态（私聊） -->
+              <span
+                v-else-if="privateReadLabel"
+                class="text-12px whitespace-nowrap"
+                :class="
+                  message.receiptStatus === ImMessageReceiptStatus.DONE
+                    ? 'text-[#409eff]'
+                    : 'text-[var(--ant-color-text-secondary)]'
+                "
+              >
+                {{ privateReadLabel }}
+              </span>
+              <!-- 群回执：点击弹 popover 展示已读 / 未读成员列表 -->
+              <MessageReadStatus
+                v-else-if="showGroupReadStatus"
+                :message="message"
+                :group-id="conversationStore.activeConversation?.targetId || 0"
+                :group-members="groupMembersForReadStatus"
+                class="text-12px whitespace-nowrap text-[var(--ant-color-text-secondary)]"
+              />
+            </template>
+            <!-- 群 @ 我提示 -->
+            <ElTag
+              v-if="!message.selfSend && isAtMe"
+              type="danger"
+              size="small"
+              class="ml-1"
+            >
+              @我
+            </ElTag>
+          </div>
+        </div>
+        <!-- 引用块：气泡下方，selfSend 时竖线在右侧 -->
+        <ReplyPreview
+          v-if="quote"
+          :quote="quote"
+          clickable
+          :mirrored="message.selfSend"
+          class="max-w-[280px]"
+          @locate="emit('locate', $event)"
+        />
+      </div>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* @keyframes 需要 SCSS 声明；SENDING 状态的转圈动画 */
+.im-loading-spin {
+  animation: im-loading-spin 1s linear infinite;
+}
+@keyframes im-loading-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-panel.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-panel.vue
new file mode 100644
index 000000000..b52ff540f
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-panel.vue
@@ -0,0 +1,813 @@
+<script lang="ts" setup>
+import type { GroupMemberLite } from '../../../../components/group'
+import type { GroupLite } from '../../../../types'
+
+import { computed, nextTick, provide, ref, watch } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElMessage, ElPopover, ElTooltip } from 'element-plus'
+
+import { createCall } from '#/api/im/rtc'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+import { ImConversationType, ImRtcCallMediaType, ImRtcCallStatus } from '#/views/im/utils/constants'
+import { getClientConversationId } from '#/views/im/utils/db'
+import { resolveCallEndReasonText } from '#/views/im/utils/message'
+import { getGroupDisplayName, getMemberDisplayName, isGroupQuit } from '#/views/im/utils/user'
+
+import { GroupMuteMemberDialog } from '../../../../components/group'
+import {
+  RtcCallMemberPickerDialog,
+  RtcGroupCallBanner
+} from '../../../../components/rtc'
+import { useMessageMultiSelect } from '../../../../composables/useMessageMultiSelect'
+import { useVoicePlayer } from '../../../../composables/useVoicePlayer'
+import { useConversationStore } from '../../../../store/conversationStore'
+import { useFriendStore } from '../../../../store/friendStore'
+import { useGroupStore } from '../../../../store/groupStore'
+import { useMessageStore } from '../../../../store/messageStore'
+import { useRtcStore } from '../../../../store/rtcStore'
+import { useImUiStore } from '../../../../store/uiStore'
+import { ConversationGroupSide } from '../conversation'
+import { ConversationPrivateSide } from '../conversation'
+import { MessageInput } from '../input'
+import { MessageMultiSelectBar } from '../input'
+import { MessageForwardDialog } from './forward'
+import { MessageMergeDetailDialog } from './forward'
+import {
+  IM_FORWARD_DIALOG_KEY,
+  IM_MERGE_DETAIL_DIALOG_KEY,
+  IM_RTC_REDIAL_KEY
+} from './forward/keys'
+import GroupPinnedMessage from './group-pinned-message.vue'
+import GroupRequestPending from './group-request-pending.vue'
+import MessageHistory from './message-history.vue'
+import MessageItem from './message-item.vue'
+
+defineOptions({ name: 'ImMessagePanel' })
+
+const conversationStore = useConversationStore()
+const messageStore = useMessageStore()
+const friendStore = useFriendStore()
+const uiStore = useImUiStore()
+const groupStore = useGroupStore()
+const rtcStore = useRtcStore()
+const listRef = ref<HTMLElement>()
+
+// ==================== 转发 / 合并消息详情：本地 dialog 浮层 ====================
+// MessageItem / MessageMultiSelectBar / MessageHistory 通过 inject 触发；不挂全局 store
+
+const forwardDialogRef = ref<InstanceType<typeof MessageForwardDialog>>()
+const mergeDetailDialogRef = ref<InstanceType<typeof MessageMergeDetailDialog>>()
+
+provide(IM_FORWARD_DIALOG_KEY, (opts) => forwardDialogRef.value?.open(opts))
+provide(IM_MERGE_DETAIL_DIALOG_KEY, (content) => mergeDetailDialogRef.value?.open(content))
+provide(IM_RTC_REDIAL_KEY, (mediaType: number) => {
+  if (isPrivate.value) {
+    void startPrivateCall(mediaType)
+  }
+}) // 私聊 RTC_CALL_END 气泡点击重拨；MessageItem 注入后调用
+
+// ==================== 多选模式 ====================
+// 模块级单例 state（composable）；本组件仅做切会话退出 + template 显隐判定
+
+const multiSelect = useMessageMultiSelect()
+const voicePlayer = useVoicePlayer()
+
+/** 切会话退出多选 + 停语音；避免上一会话的勾选 / 播放态泄漏到新会话（type+targetId 一起监听，私聊与群聊 id 同号时也能触发） */
+watch(
+  () => [
+    conversationStore.activeConversation?.type,
+    conversationStore.activeConversation?.targetId
+  ],
+  () => {
+    multiSelect.exit()
+    voicePlayer.stop()
+  }
+)
+
+const messages = computed(() => {
+  const conversation = conversationStore.activeConversation
+  return conversation
+    ? messageStore.getMessages(getClientConversationId(conversation.type, conversation.targetId))
+    : []
+})
+const isGroup = computed(
+  () => conversationStore.activeConversation?.type === ImConversationType.GROUP
+)
+const isPrivate = computed(
+  () => conversationStore.activeConversation?.type === ImConversationType.PRIVATE
+)
+const isChannel = computed(
+  () => conversationStore.activeConversation?.type === ImConversationType.CHANNEL
+)
+
+/** 当前激活会话是否历史退群群：禁群通话、隐藏群申请横幅等操作入口；聊天历史、群名头像照常展示 */
+const isQuitGroup = computed(() => {
+  const conversation = conversationStore.activeConversation
+  return (
+    conversation?.type === ImConversationType.GROUP &&
+    isGroupQuit(groupStore.getGroup(conversation.targetId))
+  )
+})
+
+/** 私聊会话且对端不是有效好友（本端 friend 记录缺失或 DISABLE）；单边删除语义下「被对方删除」不触发本端横幅 */
+const showNotFriendBanner = computed(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || conversation.type !== ImConversationType.PRIVATE) {
+    return false
+  }
+  return !friendStore.isActiveFriend(conversation.targetId)
+})
+
+/** 点击「对方还不是你的朋友」胶囊：打开 UserInfoCard，引导用户重新添加 */
+function handleNotFriendClick(event: MouseEvent) {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  const rect = (event.currentTarget as HTMLElement).getBoundingClientRect()
+  uiStore.openUserInfoCard(
+    {
+      id: conversation.targetId,
+      nickname: conversation.name,
+      avatar: conversation.avatar
+    },
+    { x: rect.left, y: rect.bottom + 4 }
+  )
+}
+
+/**
+ * 群聊 header 显示的人数：优先 groupStore.memberCount（无需等成员列表），无值再回退 members.length
+ *
+ * 之所以不直接用 groupMembers.value.length：成员列表是按需懒加载的，刚切到群时未加载完，
+ * 而 groupInfo.memberCount 跟群信息一起来，能更早显示人数避免"先空再蹦"
+ */
+const headerMemberCount = computed(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || conversation.type !== ImConversationType.GROUP) {
+    return 0
+  }
+  const group = groupStore.getGroup(conversation.targetId)
+  return group?.memberCount ?? group?.members?.length ?? 0
+})
+
+/** 顶部副标题：仅当群备注 ≠ 原群名时显示原群名（对齐微信 PC 双行 header） */
+const headerSubtitle = computed(() => {
+  const remark = groupInfo.value?.groupRemark
+  const name = groupInfo.value?.name
+  return remark && name && remark !== name ? name : ''
+})
+
+const BOTTOM_THRESHOLD = 80 // "是否停留在底部"的阈值：距离底部 < 80px 视为底部
+const showJumpToBottom = ref(false) // 当前是否已不在底部（显示"回到底部"按钮）
+const newMessageCount = ref(0) // 不在底部期间累计的新消息数
+
+/**
+ * 当前激活的群详情：优先 groupStore（带详细字段），未加载完时用 activeConversation 兜底
+ *
+ * groupStore 是按需懒加载的，初次进群时 ensureGroupData 触发后才会有完整数据；
+ * 兜底字段（name / avatar）保证 header 不会"闪空"，notice / ownerId / memberCount
+ * 必须等 store 就位才有值（这些字段在 conversation 里没有）
+ */
+const groupInfo = computed<
+  | (GroupLite & {
+      groupRemark?: string
+      notice?: string
+      ownerId?: number
+      remarkNickName?: string
+    })
+  | undefined
+>(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || conversation.type !== ImConversationType.GROUP) {
+    return undefined
+  }
+  const group = groupStore.getGroup(conversation.targetId)
+  const selfMember = group?.members?.find((member) => member.userId === getCurrentUserId())
+  const showGroupName = group ? getGroupDisplayName(group) : conversation.name
+  return {
+    id: conversation.targetId,
+    name: group?.name || conversation.name,
+    showGroupName,
+    showImage: group?.avatar || conversation.avatar,
+    notice: group?.notice,
+    remarkNickName: selfMember?.displayUserName,
+    groupRemark: group?.groupRemark,
+    ownerId: group?.ownerUserId,
+    memberCount: group?.memberCount,
+    joinApproval: group?.joinApproval
+  }
+})
+
+/** 群成员列表：直接取 groupStore 缓存，map 成 GroupMemberLite 给下游消费（@-mention / 邀请等） */
+const groupMembers = computed<GroupMemberLite[]>(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || conversation.type !== ImConversationType.GROUP) {
+    return []
+  }
+  const group = groupStore.getGroup(conversation.targetId)
+  return (group?.members || []).map((member) => {
+    // 显示名走「好友备注 > 群备注 > 真实昵称」三级；头像走 nickname 保稳定
+    const friend = friendStore.getFriend(member.userId)
+    return {
+      userId: member.userId,
+      showName: getMemberDisplayName(member, friend),
+      nickname: member.nickname,
+      avatar: member.avatar,
+      status: member.status,
+      role: member.role
+    }
+  })
+})
+
+/** 切换到群会话时同步群信息 + 成员 */
+async function ensureGroupData(groupId: number) {
+  // 远程拉群信息（群名 / 公告 / 群主等元数据）
+  await groupStore.fetchGroupInfo(groupId).catch((error) => {
+    console.warn('[IM MessagePanel] fetchGroupInfo 失败', { groupId }, error)
+  })
+  if (isGroupQuit(groupStore.getGroup(groupId))) {
+    return
+  }
+
+  // 先从 IDB 同步加载群成员，让首帧立即出成员名 / 头像
+  await groupStore.loadGroupMemberList(groupId).catch((error) => {
+    console.warn('[IM MessagePanel] loadGroupMemberList 失败', { groupId }, error)
+    return null
+  })
+  const group = groupStore.getGroup(groupId)
+  if (!group?.membersLoaded || group.membersExpired) {
+    groupStore.fetchGroupMemberList(groupId, true).catch((error) => {
+      console.warn('[IM MessagePanel] fetchGroupMemberList 失败', { groupId }, error)
+    })
+  }
+}
+
+/** 群信息抽屉里点"刷新"：强拉一次最新群元数据 + 群成员 */
+function reloadGroupData() {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || conversation.type !== ImConversationType.GROUP) {
+    return
+  }
+  groupStore.fetchGroupInfo(conversation.targetId)
+  groupStore.fetchGroupMemberList(conversation.targetId, true)
+}
+
+const historyDialogRef = ref<InstanceType<typeof MessageHistory>>() // 历史消息抽屉 ref：「聊天历史」icon / 抽屉「查找聊天内容」入口都调 open() 触发
+const sideVisible = ref(false) // 信息抽屉开关：群聊 / 私聊共用一个 ref
+const muteMemberDialogRef = ref<InstanceType<typeof GroupMuteMemberDialog>>()
+const callMemberPickerRef = ref<InstanceType<typeof RtcCallMemberPickerDialog>>()
+const pendingMediaType = ref<null | number>(null) // 群通话发起：成员选择弹窗打开期间临时持有的 mediaType
+
+/** 消息右键菜单「禁言」→ 打开时长选择弹窗 */
+function handleMuteMember(groupId: number, userId: number, displayName: string) {
+  muteMemberDialogRef.value?.open(groupId, userId, displayName)
+}
+
+/** 信息抽屉的 toggle：跟 header 上 3 点图标按钮共用 */
+function toggleSide() {
+  sideVisible.value = !sideVisible.value
+}
+
+const callPopoverVisible = ref(false) // 私聊通话入口：popover 触发；点 语音 / 视频 直接发起
+const callInviting = ref(false) // 通话发起中
+async function startPrivateCall(mediaType: number) {
+  callPopoverVisible.value = false
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  await doInvite({
+    conversationType: ImConversationType.PRIVATE,
+    mediaType,
+    inviteeIds: [conversation.targetId]
+  })
+}
+
+/** 群通话入口：默认语音直接弹选人；与微信群通话一致，进通话后用户按需开摄像头 */
+function handleGroupCall() {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return
+  }
+  pendingMediaType.value = ImRtcCallMediaType.VOICE
+  callMemberPickerRef.value?.open({ groupId: conversation.targetId, mode: 'invite' })
+}
+
+/** 选人弹窗确认；带选中 ID 发起群通话 */
+async function onCallMemberPicked(selectedIds: number[]) {
+  const conversation = conversationStore.activeConversation
+  const mediaType = pendingMediaType.value
+  pendingMediaType.value = null
+  if (!conversation || mediaType == null || selectedIds.length === 0) {
+    return
+  }
+  await doInvite({
+    conversationType: ImConversationType.GROUP,
+    mediaType,
+    groupId: conversation.targetId,
+    inviteeIds: selectedIds
+  })
+}
+
+/** 实际调 create 接口；统一处理成功 / ENDED（如忙线立即结束） */
+async function doInvite(reqVO: {
+  conversationType: number
+  groupId?: number
+  inviteeIds: number[]
+  mediaType: number
+}) {
+  if (callInviting.value) {
+    return
+  }
+  if (rtcStore.isActive) {
+    ElMessage.warning('当前已有通话')
+    return
+  }
+  callInviting.value = true
+  try {
+    const data = await createCall(reqVO)
+    // 后端已 INSERT + 立即 end（如忙线）：toast 提示，不进 INVITING 阶段；chat tip 由 RTC_CALL_END 推送写入消息流
+    if (data.status === ImRtcCallStatus.ENDED) {
+      ElMessage.warning(resolveCallEndReasonText(data.endReason))
+      return
+    }
+    // 正常进入 INVITING 阶段：走 store 逻辑发起通话，后续状态更新 / 消息流更新由 RTC 模块监听推送处理
+    rtcStore.startInviting(data)
+  } finally {
+    callInviting.value = false
+  }
+}
+
+/** 当前私聊对应的好友（抽屉头部展示用） */
+const privateFriend = computed(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || conversation.type !== ImConversationType.PRIVATE) {
+    return undefined
+  }
+  return friendStore.getFriend(conversation.targetId)
+})
+
+/** 计算距离底部的像素 */
+function distanceFromBottom(): number {
+  const el = listRef.value
+  if (!el) {
+    return 0
+  }
+  return el.scrollHeight - el.scrollTop - el.clientHeight
+}
+
+/**
+ * 消息列表滚动事件：刷新"是否在底部"状态
+ * - 在底部：隐藏"回到底部"浮窗 + 清掉"未读新消息"计数
+ * - 不在底部：显示"回到底部"浮窗，新消息会累计到 newMessageCount
+ */
+function handleScroll() {
+  const dist = distanceFromBottom()
+  const atBottom = dist <= BOTTOM_THRESHOLD
+  showJumpToBottom.value = !atBottom
+  if (atBottom) {
+    newMessageCount.value = 0
+  }
+}
+
+/**
+ * 滚到底部：切会话 / 收到新消息（且当前在底部）/ 用户主动点「回到底部」 都走这里
+ *
+ * smooth=true 走平滑动画，适合用户主动点击；初始 / 自动滚动用 auto，避免用户感知到动画拖拽
+ */
+async function scrollToBottom(smooth = false) {
+  // 1. 滚到当前 scrollHeight 的底部（图片 / 视频还在加载时只是大致到底）
+  // 1.1 等 v-for 把新消息真正渲染进 DOM 后再算 scrollHeight，否则差最后一条的位置
+  await nextTick()
+  if (!listRef.value) {
+    return
+  }
+  // 1.2 触发滚动；smooth 仅 user 主动点「回到底部」用，初始 / 自动滚走 auto 避免动画拖拽感
+  listRef.value.scrollTo({
+    top: listRef.value.scrollHeight,
+    behavior: smooth ? 'smooth' : 'auto'
+  })
+  newMessageCount.value = 0
+  showJumpToBottom.value = false
+  // 1.3 记下「期望停下的 scrollTop」；图片 / 视频加载完底部会上移，scrollTop 没动就说明用户没手动滚走
+  //     不能用 distanceFromBottom 判断：底部上移会让 distance 变大，被误判为「用户滚走了」直接放弃补滚
+  const expectedScrollTop = listRef.value.scrollHeight - listRef.value.clientHeight
+
+  // 2. 等媒体加载完后补滚到真实底部
+  // 2.1 等容器内未加载完的图片 / 视频元数据；加载完后 scrollHeight 会增长到真实底部
+  await waitMediaSettled()
+  if (!listRef.value) {
+    return
+  }
+  // 2.2 仅在用户没手动滚走时（scrollTop 仍贴近 expectedScrollTop）才补滚，避免等待期间用户上翻被打断
+  if (Math.abs(listRef.value.scrollTop - expectedScrollTop) > BOTTOM_THRESHOLD) {
+    return
+  }
+  // 2.3 补滚到新底部
+  listRef.value.scrollTo({ top: listRef.value.scrollHeight, behavior: 'auto' })
+}
+
+/**
+ * 等待容器内未加载完的图片 / 视频；最多等 2s 防止超大资源把整个滚动跟进卡住
+ *
+ * 仅关心元数据（loadedmetadata / img.complete），不等真正解码，因为尺寸够算 scrollHeight 就行
+ */
+function waitMediaSettled(): Promise<void> {
+  // 1. 收集容器内未加载完的图片 / 视频
+  if (!listRef.value) {
+    return Promise.resolve()
+  }
+  // 1.1 一次扫 img + video，按 element 类型分别看「complete / readyState」过滤 pending
+  const pendingMedia = [...listRef.value.querySelectorAll<HTMLImageElement | HTMLVideoElement>('img, video')].filter((el) => (el instanceof HTMLImageElement ? !el.complete : el.readyState < 1))
+  // 1.2 没有 pending 直接返回，省掉 Promise.race / setTimeout 闭包构造
+  if (pendingMedia.length === 0) {
+    return Promise.resolve()
+  }
+
+  // 2. 等所有 pending 资源 load / error，最长 2s 兜底
+  // 2.1 每个 element 都监听对应 loadedEvent + error，任一触发即 resolve（不让单条失败卡 race）
+  const loadAll = Promise.all(
+    pendingMedia.map(
+      (el) =>
+        new Promise<void>((resolve) => {
+          const loadedEvent = el instanceof HTMLImageElement ? 'load' : 'loadedmetadata'
+          el.addEventListener(loadedEvent, () => resolve(), { once: true })
+          el.addEventListener('error', () => resolve(), { once: true })
+        })
+    )
+  ).then(() => undefined)
+  // 2.2 2s 超时兜底，防止超大资源 / 网络挂起把整个滚动跟进永久卡住
+  const timeout = new Promise<void>((resolve) => setTimeout(resolve, 2000))
+  return Promise.race([loadAll, timeout])
+}
+
+/**
+ * 定位到聊天位置：MessageHistory 行上"定位"按钮 / 气泡内引用块点击触发
+ *
+ * 1. 先关掉历史弹窗（避免 scroll 时遮挡 + dialog 关闭后让聊天面板拿回焦点）
+ * 2. nextTick 等弹窗 leave 动画 / 列表渲染稳定后再查 DOM
+ * 3. 按 data-message-id 找 wrapper，scrollIntoView({ block: center }) 让消息落到视口中部
+ * 4. 加 --highlight class 短暂高亮，提示用户"就是这条"
+ * 5. 找不到 wrapper(原消息已分页出去)时弹 warning 提示,与微信"消息已不在窗口"观感一致
+ */
+async function handleLocate(messageId: number) {
+  if (!messageId) {
+    return
+  }
+  await nextTick()
+  if (!listRef.value) {
+    return
+  }
+  const target = listRef.value.querySelector<HTMLElement>(`[data-message-id="${messageId}"]`)
+  if (!target) {
+    ElMessage.warning('原消息不在视野')
+    return
+  }
+  target.scrollIntoView({ behavior: 'smooth', block: 'center' })
+  target.classList.add('message-panel__message-anchor--highlight')
+  setTimeout(() => {
+    target.classList.remove('message-panel__message-anchor--highlight')
+  }, 1600)
+}
+
+/**
+ * 消息数量变化时的滚动跟进策略
+ * - 当前在底部 → 自动滚到新底部（用户在"实时跟读"，体验上跟微信一致）
+ * - 不在底部 → 累计 newMessageCount，让 sticky 浮窗显示"X 条新消息"，让用户主动点
+ */
+watch(
+  () => messages.value.length,
+  (newLen, oldLen) => {
+    // 仅处理新增（delta > 0）；删除 / 撤回让 length 减少时不动滚动状态
+    const delta = (newLen || 0) - (oldLen || 0)
+    if (delta <= 0) {
+      return
+    }
+    // 用 BOTTOM_THRESHOLD（80px）做容差：用户稍微往上翻几行就视作"不在底部"，
+    // 否则一直 auto-scroll 会把人正在读的内容顶走，体验糟糕
+    const dist = distanceFromBottom()
+    if (dist <= BOTTOM_THRESHOLD) {
+      scrollToBottom()
+    } else {
+      newMessageCount.value += delta
+      showJumpToBottom.value = true
+    }
+  }
+)
+
+/**
+ * 切换会话：清空"在不在底部"相关状态、强制滚到底部、群会话预拉资料
+ *
+ * type+targetId 一起监听：私聊与群聊 id 同号时切换也能触发；immediate:true 让首次进入页面就能初始化
+ */
+watch(
+  () => [
+    conversationStore.activeConversation?.type,
+    conversationStore.activeConversation?.targetId
+  ],
+  ([type, targetId]) => {
+    // 切会话时上一会话的「未读累计 + 浮窗显示」必须清掉，否则会带到新会话里看起来很突兀
+    newMessageCount.value = 0
+    showJumpToBottom.value = false
+    // 抽屉里展示的群信息 / 好友信息属于上一会话，切会话时统一关掉
+    sideVisible.value = false
+    scrollToBottom()
+    // 仅群聊预拉详情 / 成员（私聊对端在首屏 fetchFriendList 时就拉了）
+    if (targetId && type === ImConversationType.GROUP) {
+      ensureGroupData(targetId)
+    }
+  },
+  { immediate: true }
+)
+</script>
+
+<template>
+  <div class="flex flex-1 flex-col min-w-0 bg-[var(--ant-color-fill-secondary)]">
+    <template v-if="conversationStore.activeConversation">
+      <!-- 顶部 header：第一行群名 + 右侧图标，第二行嵌入置顶气泡（仅群聊 + 有置顶） -->
+      <div
+        class="flex flex-shrink-0 flex-col bg-[var(--ant-color-fill-secondary)] border-b border-b-solid border-[var(--im-border-color-lighter)]"
+      >
+        <div class="flex items-center justify-between h-14 px-5">
+          <span class="flex flex-col min-w-0">
+            <span class="flex items-baseline gap-1.5 min-w-0">
+              <span
+                class="overflow-hidden text-base font-medium truncate text-[var(--ant-color-text)]"
+              >
+                {{ conversationStore.activeConversation?.name || '' }}
+              </span>
+              <span
+                v-if="isGroup && headerMemberCount > 0"
+                class="flex-shrink-0 text-sm text-[var(--ant-color-text-secondary)]"
+              >
+                ({{ headerMemberCount }})
+              </span>
+            </span>
+            <!-- 副标题：备注 ≠ 群名时展示原群名，提示用户当前看到的主名是自己设的备注 -->
+            <span
+              v-if="headerSubtitle"
+              class="overflow-hidden text-xs truncate text-[var(--ant-color-text-secondary)]"
+            >
+              {{ headerSubtitle }}
+            </span>
+          </span>
+          <div class="flex gap-2 items-center">
+            <!-- 聊天历史 -->
+            <ElTooltip content="聊天历史" placement="bottom">
+              <button
+                class="message-panel__header-icon"
+                type="button"
+                @click="historyDialogRef?.open()"
+              >
+                <Icon icon="ep:chat-dot-round" />
+              </button>
+            </ElTooltip>
+            <!-- 通话入口：私聊弹「语音 / 视频」popover；群聊直接进选人弹窗 -->
+            <ElPopover
+              v-if="isPrivate"
+              v-model="callPopoverVisible"
+              placement="bottom-end"
+              :width="140"
+              trigger="click"
+              popper-class="message-panel__call-popover"
+            >
+              <template #reference>
+                <button class="message-panel__header-icon" type="button">
+                  <Icon icon="ant-design:phone-outlined" />
+                </button>
+              </template>
+              <div class="flex flex-col gap-0.5">
+                <div
+                  class="flex items-center gap-2.5 px-3 py-2 rounded cursor-pointer text-sm text-[var(--ant-color-text)] hover:bg-[var(--ant-color-fill-secondary)]"
+                  @click="startPrivateCall(ImRtcCallMediaType.VOICE)"
+                >
+                  <Icon icon="ant-design:phone-outlined" :size="16" />
+                  <span>语音通话</span>
+                </div>
+                <div
+                  class="flex items-center gap-2.5 px-3 py-2 rounded cursor-pointer text-sm text-[var(--ant-color-text)] hover:bg-[var(--ant-color-fill-secondary)]"
+                  @click="startPrivateCall(ImRtcCallMediaType.VIDEO)"
+                >
+                  <Icon icon="ant-design:video-camera-outlined" :size="16" />
+                  <span>视频通话</span>
+                </div>
+              </div>
+            </ElPopover>
+            <ElTooltip v-else-if="!isQuitGroup" content="通话" placement="bottom">
+              <button
+                class="message-panel__header-icon"
+                type="button"
+                @click="handleGroupCall"
+              >
+                <Icon icon="ant-design:phone-outlined" />
+              </button>
+            </ElTooltip>
+            <!-- 信息抽屉入口：群聊有，私聊仅在对方是好友时显示（非好友会话抽屉内容为空，没意义） -->
+            <ElTooltip
+              v-if="isGroup || (isPrivate && !showNotFriendBanner)"
+              :content="isGroup ? '群聊信息' : '聊天信息'"
+              placement="bottom"
+            >
+              <button
+                class="message-panel__header-icon"
+                type="button"
+                @click="toggleSide"
+              >
+                <Icon icon="ant-design:ellipsis-outlined" />
+              </button>
+            </ElTooltip>
+          </div>
+        </div>
+
+        <!-- 群通话胶囊条：仅群聊 + 该群有活跃通话时显示；点击展开看成员 + 加入按钮 -->
+        <RtcGroupCallBanner
+          v-if="isGroup && !isQuitGroup && conversationStore.activeConversation"
+          :group-id="conversationStore.activeConversation.targetId"
+        />
+
+        <!-- 群置顶消息：第二行嵌入 header；仅群聊 + 有置顶时显示 -->
+        <GroupPinnedMessage
+          v-if="isGroup && conversationStore.activeConversation"
+          :group-id="conversationStore.activeConversation.targetId"
+          @locate="handleLocate"
+        />
+        <!-- 群顶部「待处理加群申请」横幅：仅群聊 + owner / admin + count > 0 时显示 -->
+        <GroupRequestPending
+          v-if="isGroup && !isQuitGroup && conversationStore.activeConversation"
+          :group-id="conversationStore.activeConversation.targetId"
+        />
+        <!-- 私聊：对方不再是有效好友（我删了对方 / 从未加过；单边设计下「被对方删除」本端 friendStore 不更新故不会触发）；胶囊嵌在 header 内（跟群置顶同级），点击弹 UserInfoCard -->
+        <div
+          v-if="showNotFriendBanner"
+          class="flex flex-shrink-0 items-start px-4 pb-2 bg-[var(--ant-color-fill-secondary)]"
+        >
+          <div
+            class="inline-flex items-center gap-2 px-2.5 py-1 rounded-full text-13px cursor-pointer text-[var(--ant-color-text)] bg-[var(--ant-color-warning-bg)] transition-colors hover:bg-[var(--ant-color-warning-bg-hover)]"
+            @click="handleNotFriendClick"
+          >
+            <span
+              class="inline-flex items-center justify-center w-4 h-4 rounded-full text-white bg-[var(--ant-color-warning)] flex-shrink-0"
+            >
+              <Icon icon="ant-design:user-outlined" :size="11" />
+            </span>
+            <span>对方还不是你的朋友</span>
+            <Icon icon="ep:arrow-right" :size="12" class="text-[var(--ant-color-text-secondary)]" />
+          </div>
+        </div>
+      </div>
+
+      <!-- 中间：消息列表 -->
+      <div
+        ref="listRef"
+        class="relative flex-1 py-2 overflow-y-auto bg-[var(--ant-color-bg-layout)]"
+        @scroll="handleScroll"
+      >
+        <div
+          v-if="messages.length === 0"
+          class="flex items-center justify-center h-full text-sm text-[var(--ant-color-text-secondary)]"
+        >
+          暂无消息
+        </div>
+        <!-- data-message-id 给 MessageHistory "定位到聊天位置" 用：父级通过 querySelector
+             找到这层 wrapper，scrollIntoView + 加高亮 class；本地占位消息跳过 -->
+        <div
+          v-for="(msg, index) in messages"
+          :key="msg.id || msg.clientMessageId"
+          :data-message-id="msg.id || ''"
+          class="message-panel__message-anchor"
+        >
+          <MessageItem
+            :message="msg"
+            :prev-message="messages[index - 1]"
+            @locate="handleLocate"
+            @mute="handleMuteMember"
+            @reload="reloadGroupData"
+          />
+        </div>
+
+        <!-- 回到底部浮动按钮（滚动不在底部时显示） -->
+        <transition name="message-panel__jump-fade">
+          <div
+            v-if="showJumpToBottom"
+            class="message-panel__jump-bottom sticky bottom-3 left-1/2 inline-flex gap-1.5 items-center w-fit mx-auto px-3.5 py-1.5 text-xs text-[#409eff] bg-[var(--ant-color-bg-elevated)] rounded-2xl shadow-[0_2px_8px_rgba(0,0,0,0.12)] cursor-pointer hover:text-white hover:bg-[#409eff]"
+            @click="scrollToBottom(true)"
+          >
+            <Icon icon="ant-design:down-outlined" :size="14" />
+            <span v-if="newMessageCount > 0" class="font-medium">
+              {{ newMessageCount > 99 ? '99+' : newMessageCount }} 条新消息
+            </span>
+            <span v-else>回到底部</span>
+          </div>
+        </transition>
+      </div>
+
+      <!-- 底部：输入框（频道单向消息无需输入框）；多选模式底栏作为浮层盖在上面，保持下方输入框尺寸不变 -->
+      <div v-if="!isChannel" class="relative">
+        <MessageInput />
+        <MessageMultiSelectBar v-if="multiSelect.state.active" class="absolute inset-0 z-10" />
+      </div>
+
+      <!-- 右侧信息抽屉：群聊 / 私聊各自一份 -->
+      <ConversationGroupSide
+        v-if="isGroup"
+        v-model="sideVisible"
+        :group="groupInfo"
+        :conversation="conversationStore.activeConversation"
+        :members="groupMembers"
+        @reload="reloadGroupData"
+        @open-history="historyDialogRef?.open()"
+      />
+      <ConversationPrivateSide
+        v-else
+        v-model="sideVisible"
+        :conversation="conversationStore.activeConversation"
+        :friend="privateFriend"
+        @open-history="historyDialogRef?.open()"
+      />
+
+      <!-- 历史消息抽屉 -->
+      <MessageHistory ref="historyDialogRef" @locate="handleLocate" />
+
+      <!-- 转发弹窗 / 合并消息详情：在 MessagePanel 子树内挂载，子组件通过 inject 触发 -->
+      <MessageForwardDialog ref="forwardDialogRef" />
+      <MessageMergeDetailDialog ref="mergeDetailDialogRef" />
+
+      <!-- 禁言时长选择弹窗 -->
+      <GroupMuteMemberDialog ref="muteMemberDialogRef" @success="reloadGroupData" />
+
+      <!-- 群通话成员选择弹窗 -->
+      <RtcCallMemberPickerDialog ref="callMemberPickerRef" @success="onCallMemberPicked" />
+    </template>
+    <div
+      v-else
+      class="flex items-center justify-center h-full text-sm text-[var(--ant-color-text-secondary)]"
+    >
+      <span>选择一个会话开始聊天</span>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+/* :deep 穿透 el-icon 子组件 svg；el-icon 全局规则 .el-icon{color:var(--color,inherit)} 优先级更高，
+   用 :deep + !important 锁色；颜色取 Element Plus 主题变量，暗色模式自动切到更亮的灰 */
+.message-panel__header-icon,
+.message-panel__header-icon :deep(svg) {
+  width: 20px;
+  height: 20px;
+  color: var(--ant-color-text) !important;
+  fill: currentColor !important;
+  transition: color 0.15s;
+}
+
+.message-panel__header-icon {
+  box-sizing: content-box;
+  border: 0;
+  background: transparent;
+  cursor: pointer;
+  padding: 4px;
+}
+.message-panel__header-icon:hover,
+.message-panel__header-icon:hover :deep(svg) {
+  color: var(--ant-color-primary) !important;
+}
+
+/* sticky + translate 居中：fit-content 宽度不会撑满，transform 水平 -50% 偏移；同时 transition opacity 和 transform 两个属性 */
+.message-panel__jump-bottom {
+  transform: translateX(-50%);
+  transition:
+    opacity 0.2s,
+    transform 0.2s;
+}
+
+/* JS 切换 highlight class + background-color transition 联动；MessageHistory「定位」跳过来时短暂高亮 1.6s */
+.message-panel__message-anchor {
+  transition: background-color 0.6s ease;
+}
+.message-panel__message-anchor--highlight {
+  background-color: var(--ant-color-warning-bg);
+}
+
+/* Vue <transition> 钩子类名固定，必须 SCSS 声明；回到底部按钮淡入淡出 */
+.message-panel__jump-fade-enter-active,
+.message-panel__jump-fade-leave-active {
+  transition:
+    opacity 0.2s,
+    transform 0.2s;
+}
+
+.message-panel__jump-fade-enter-from,
+.message-panel__jump-fade-leave-to {
+  opacity: 0;
+  transform: translate(-50%, 20px);
+}
+</style>
+
+<style>
+/* el-popover 全局样式：紧贴菜单的小 padding；非 scoped 才能命中 popper-class */
+.message-panel__call-popover.el-popover.el-popper {
+  min-width: auto;
+  padding: 6px;
+}
+</style>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-read-status.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-read-status.vue
new file mode 100644
index 000000000..8de3690ac
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/message-read-status.vue
@@ -0,0 +1,169 @@
+<script lang="ts" setup>
+import type { Message } from '../../../../types'
+
+import { computed, ref } from 'vue'
+
+import { CommonStatusEnum } from '@vben/constants'
+
+import { ElPopover, ElTabPane, ElTabs } from 'element-plus'
+
+import { getGroupReadUsers as apiGetGroupReadUsers } from '#/api/im/message/group'
+
+import { ImConversationType, ImMessageReceiptStatus } from '../../../../../utils/constants'
+import { PagedScroller } from '../../../../components'
+import { GroupMember, type GroupMemberLite } from '../../../../components/group'
+import { useMessageStore } from '../../../../store/messageStore'
+
+defineOptions({ name: 'ImMessageReadStatus' })
+
+const props = defineProps<{
+  // 当前群编号；供 loadReadUsers 作为 /im/message/group/get-read-users 的入参
+  groupId: number
+  // 当前群所有成员（外部 MessagePanel.groupMembers 传入；没有就传空数组，未读列表会变空但不报错）
+  groupMembers: GroupMemberLite[]
+  message: Message
+}>()
+
+const messageStore = useMessageStore()
+
+// popover 开关：show 时拉已读名单，关闭后保留 readUserIds 缓存（重开同一条消息不再请求）
+const popVisible = ref(false)
+const activeTab = ref<'read' | 'unread'>('read')
+// 服务端返回的"已读这条消息的 userId 列表"，未读靠 visibleMembers 减去这份得到
+const readUserIds = ref<number[]>([])
+
+/**
+ * 标签文案：
+ * - receiptStatus === DONE：服务端确认全员已读 → 直接显示"全部已读"，readCount 不再使用
+ * - readCount > 0：显示"N 人已读"
+ * - 其他（readCount = 0 或 undefined，且未到 DONE）：显示"未读"
+ */
+const label = computed(() => {
+  if (props.message.receiptStatus === ImMessageReceiptStatus.DONE) {
+    return '全部已读'
+  }
+  const readCount = props.message.readCount || 0
+  return readCount > 0 ? `${readCount} 人已读` : '未读'
+})
+
+/**
+ * 这条消息"应该被谁看到"的可见成员集合（已读 / 未读两个 tab 共用基底）
+ *
+ * 三层过滤：
+ * 1. 定向群消息：receiverUserIds 非空时，只算名单内的成员。少了这层，未在投递范围里的人
+ *    会被错算成"未读"（getGroupReadUsers 后端已按可见性过滤，前端必须配套）
+ * 2. 发送者本人：自己发的消息算不算"自己已读"语义模糊，索性两个 tab 都不展示
+ * 3. 已退群（status === DISABLE）：他读没读已经不关心，UI 不展示
+ */
+const visibleMembers = computed<GroupMemberLite[]>(() => {
+  const receiverUserIds = props.message.receiverUserIds
+  const isDirected = !!receiverUserIds && receiverUserIds.length > 0
+  return props.groupMembers.filter(
+    (member) =>
+      member.status !== CommonStatusEnum.DISABLE &&
+      member.userId !== props.message.senderId &&
+      (!isDirected || receiverUserIds.includes(member.userId))
+  )
+})
+
+/** 已读 = 可见成员 ∩ readUserIds */
+const readMembers = computed(() =>
+  visibleMembers.value.filter((member) => readUserIds.value.includes(member.userId))
+)
+
+/** 未读 = 可见成员 − readUserIds */
+const unreadMembers = computed(() =>
+  visibleMembers.value.filter((member) => !readUserIds.value.includes(member.userId))
+)
+
+/**
+ * 拉取已读用户 id 列表
+ *
+ * 触发：el-popover @show（按需懒加载，避免每条群消息都预拉）
+ * 跳过：本地占位消息（id = 0，还没拿到服务端 id），后端没法按 messageId 查
+ * 失败：仅控制台告警，readUserIds 保持空数组 → label 走 readCount 兜底，不阻塞 UI
+ *
+ * 拉到名单后顺手把 readCount / receiptStatus 回写到 messageStore，让 popover 外面的
+ * label 也跟着走最新数：离线 / 漏收 RECEIPT 事件时本地 readCount 会偏旧，弹层里看到"已读 5"
+ * 但外面仍是"未读"或旧人数；这里以服务端返回为准矫正回去
+ */
+async function loadReadUsers() {
+  if (!props.message.id) {
+    return
+  }
+  try {
+    const userIds = await apiGetGroupReadUsers({
+      groupId: props.groupId,
+      messageId: props.message.id
+    })
+    readUserIds.value = userIds || []
+    const readCount = readUserIds.value.length
+    // 全可见成员都已读 → 更新为 DONE，让外面 label 直接命中「全部已读」分支；
+    // 否则只更新 readCount，receiptStatus 维持不变（PENDING）
+    const allRead = readCount > 0 && readCount >= visibleMembers.value.length
+    messageStore.applyMessageReadReceipt({
+      conversationType: ImConversationType.GROUP,
+      targetId: props.groupId,
+      groupMessageId: props.message.id,
+      readCount,
+      receiptStatus: allRead ? ImMessageReceiptStatus.DONE : undefined
+    })
+  } catch (error) {
+    console.error('[IM] 拉取群已读列表失败:', error)
+  }
+}
+</script>
+
+<template>
+  <!--
+    群消息已读状态
+    - 标签形态：展示「N 已读」或「全部已读」；点击弹出 popover 用 tab 列出已读 / 未读成员
+    - 渲染条件：仅在群聊、自己发送、receiptStatus !== NO_RECEIPT 时挂出（由 MessageItem 把关）
+    - 已读名单按需拉：popover 触发 show 才打 /im/message/group/get-read-users，避免每条群消息都预拉
+    - 未读名单 = 当前群成员 − 自己 − 已退群 − 已读集合（前端聚合，后端只回已读 userId）
+  -->
+  <ElPopover
+    v-model="popVisible"
+    placement="left"
+    trigger="click"
+    :width="320"
+    @show="loadReadUsers"
+  >
+    <template #reference>
+      <span
+        class="text-12px whitespace-nowrap cursor-pointer text-[var(--ant-color-text-secondary)] hover:text-[#409eff]"
+      >
+        {{ label }}
+      </span>
+    </template>
+
+    <ElTabs v-model="activeTab">
+      <ElTabPane :tab="`已读(${readMembers.length})`" key="read">
+        <PagedScroller :items="readMembers" :page-size="20" item-key="userId" class="h-75">
+          <template #default="{ item }">
+            <GroupMember :member="item as GroupMemberLite" :height="40" :clickable="false" />
+          </template>
+        </PagedScroller>
+        <div
+          v-if="readMembers.length === 0"
+          class="py-5 text-12px text-center text-[var(--ant-color-text-disabled)]"
+        >
+          {{ groupMembers.length === 0 ? '群成员未加载' : '暂无已读' }}
+        </div>
+      </ElTabPane>
+      <ElTabPane :tab="`未读(${unreadMembers.length})`" key="unread">
+        <PagedScroller :items="unreadMembers" :page-size="20" item-key="userId" class="h-75">
+          <template #default="{ item }">
+            <GroupMember :member="item as GroupMemberLite" :height="40" :clickable="false" />
+          </template>
+        </PagedScroller>
+        <div
+          v-if="unreadMembers.length === 0"
+          class="py-5 text-12px text-center text-[var(--ant-color-text-disabled)]"
+        >
+          {{ groupMembers.length === 0 ? '群成员未加载' : '全部已读' }}
+        </div>
+      </ElTabPane>
+    </ElTabs>
+  </ElPopover>
+</template>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/reply-preview.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/reply-preview.vue
new file mode 100644
index 000000000..1cda681cb
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/reply-preview.vue
@@ -0,0 +1,234 @@
+<script lang="ts" setup>
+import { computed } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+import { formatFileSize } from '@vben/utils'
+
+import { CardLineLabel } from '#/views/im/home/components/card'
+import { ImContentType } from '#/views/im/utils/constants'
+import { getClientConversationId } from '#/views/im/utils/db'
+import {
+  type AudioMessage,
+  type CardMessage,
+  type FaceMessage,
+  type FileMessage,
+  getFileIconInfo,
+  type ImageMessage,
+  type MaterialMessage,
+  parseMessage,
+  type QuoteMessage,
+  type TextMessage,
+  type VideoMessage
+} from '#/views/im/utils/message'
+import { formatSeconds } from '#/views/im/utils/time'
+import { getSenderDisplayName } from '#/views/im/utils/user'
+
+import { useConversationStore } from '../../../../store/conversationStore'
+import { useMessageStore } from '../../../../store/messageStore'
+
+defineOptions({ name: 'ImReplyPreview' })
+
+const props = withDefaults(
+  defineProps<{
+    /** 气泡内为 true 支持点击跳转,输入条为 false */
+    clickable?: boolean
+    /** 输入条为 true 显示 × 关闭按钮 */
+    closable?: boolean
+    /** 自己发送的气泡为 true，把竖线镜像到右侧，与气泡同侧 */
+    mirrored?: boolean
+    quote: QuoteMessage
+  }>(),
+  {
+    clickable: false,
+    closable: false,
+    mirrored: false
+  }
+)
+
+const emit = defineEmits<{
+  close: []
+  locate: [messageId: number]
+}>()
+
+const MAX_TEXT_PREVIEW_LEN = 60 // 文本摘要在引用块里展示的最大字符数
+
+const conversationStore = useConversationStore()
+const messageStore = useMessageStore()
+
+/** 在当前会话消息列表里查找原消息,仅用于实时判断是否已撤回;摘要 / 缩略图都从 quote.content 直接派生 */
+const liveMessage = computed(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation || !props.quote.messageId) {
+    return undefined
+  }
+  return messageStore
+    .getMessages(getClientConversationId(conversation.type, conversation.targetId))
+    .find((message) => message.id === props.quote.messageId)
+})
+
+/** 命中本地缓存且 type === RECALL 才判定为已撤回;不在缓存的当快照仍有效 */
+const isRecalled = computed(() => liveMessage.value?.type === ImContentType.RECALL)
+
+/** 渲染时实时算,与气泡上方显示名走同一套规则,避免备注变更后引用块陈旧 */
+const senderName = computed(() => {
+  const conversation = conversationStore.activeConversation
+  if (!conversation) {
+    return ''
+  }
+  return getSenderDisplayName(props.quote.senderId, conversation.type, conversation.targetId)
+})
+
+/** quote.content 解析一次缓存，让多个 computed 复用，长会话每条引用气泡少一次 JSON.parse */
+type AnyQuotePayload = Partial<
+  AudioMessage &
+    CardMessage &
+    FaceMessage &
+    FileMessage &
+    ImageMessage &
+    MaterialMessage &
+    TextMessage &
+    VideoMessage
+>
+const parsedPayload = computed(() => parseMessage<AnyQuotePayload>(props.quote.content))
+
+const isText = computed(() => props.quote.type === ImContentType.TEXT)
+const isFile = computed(() => props.quote.type === ImContentType.FILE)
+const isVoice = computed(() => props.quote.type === ImContentType.VOICE)
+const isCard = computed(() => props.quote.type === ImContentType.CARD)
+const isFace = computed(() => props.quote.type === ImContentType.FACE)
+const isMaterial = computed(() => props.quote.type === ImContentType.MATERIAL)
+
+/** 文本超过 MAX_TEXT_PREVIEW_LEN 截断，长内容不撑爆引用块 */
+const textPreview = computed(() => {
+  const text = parsedPayload.value?.content ?? ''
+  return text.length <= MAX_TEXT_PREVIEW_LEN ? text : `${text.slice(0, Math.max(0, MAX_TEXT_PREVIEW_LEN))}…`
+})
+
+/** 文件 icon：按扩展名挑色，跟主气泡渲染同源 */
+const fileIcon = computed(() => getFileIconInfo(parsedPayload.value?.name))
+
+/** 缩略图 URL：图片 / 视频 / 表情贴图 / 频道素材封面从 quote.content 直接取，不依赖本地缓存 */
+const thumbnailUrl = computed<string | undefined>(() => {
+  if (isRecalled.value) {
+    return undefined
+  }
+  const { type } = props.quote
+  if (type === ImContentType.IMAGE) {
+    return parsedPayload.value?.thumbnailUrl || parsedPayload.value?.url
+  }
+  if (type === ImContentType.VIDEO || type === ImContentType.MATERIAL) {
+    return parsedPayload.value?.coverUrl
+  }
+  if (type === ImContentType.FACE) {
+    return parsedPayload.value?.url
+  }
+  return undefined
+})
+
+/** 仅 clickable 且未撤回时触发跳转 */
+function onClick() {
+  if (!props.clickable || isRecalled.value) {
+    return
+  }
+  emit('locate', props.quote.messageId)
+}
+</script>
+
+<template>
+  <!--
+    引用预览块（对齐微信 PC）：2px 竖线作为「引用」视觉标识 + 紧凑内容预览
+    - clickable=true（气泡内）：点击触发 locate emit；撤回态禁用跳转
+    - closable=true（输入条）：尾部 × 关闭按钮
+    - mirrored=true（自己发送的气泡）：竖线镜像到右侧，与气泡同侧
+    - 内容预览（与主气泡同源，不缩写成「[文件]/[语音]」）：
+      - 文本：截断后纯文字
+      - 图片 / 视频：缩略图（IMAGE 用 thumbnailUrl/url，VIDEO 用 coverUrl）
+      - 文件：file icon + 文件名 + 大小
+      - 语音：audio icon + 时长
+      - 撤回（命中本地缓存且 type === RECALL）：「原消息已撤回」斜体灰字
+  -->
+  <div
+    class="flex w-fit gap-1.5 items-center min-w-0 py-0.5 text-12px text-[var(--ant-color-text-secondary)] rounded transition-colors"
+    :class="[
+      mirrored
+        ? 'pl-1 pr-2 border-r-2 border-r-solid border-r-[var(--ant-color-border)]'
+        : 'pl-2 pr-1 border-l-2 border-l-solid border-l-[var(--ant-color-border)]',
+      {
+        'cursor-pointer hover:text-[var(--ant-color-text)]': clickable && !isRecalled,
+        'hover:bg-[var(--ant-color-fill-secondary)]': (clickable && !isRecalled) || closable
+      }
+    ]"
+    @click="onClick"
+  >
+    <span class="flex-shrink-0">{{ senderName }}:</span>
+
+    <!-- 撤回降级 -->
+    <span v-if="isRecalled" class="italic">原消息已撤回</span>
+
+    <!-- 文本 -->
+    <span v-else-if="isText" class="min-w-0 line-clamp-2 break-words">{{ textPreview }}</span>
+
+    <!-- 文件：icon + 文件名 + 大小 -->
+    <template v-else-if="isFile">
+      <Icon :icon="fileIcon.icon" :color="fileIcon.color" :size="14" class="flex-shrink-0" />
+      <span v-if="parsedPayload?.name" class="min-w-0 line-clamp-2 break-words">
+        {{ parsedPayload.name }}
+      </span>
+      <span
+        v-if="parsedPayload?.size"
+        class="flex-shrink-0 text-[var(--ant-color-text-placeholder)]"
+      >
+        {{ formatFileSize(parsedPayload.size) }}
+      </span>
+    </template>
+
+    <!-- 语音：audio icon + 时长 -->
+    <template v-else-if="isVoice">
+      <Icon icon="ant-design:audio-outlined" :size="14" class="flex-shrink-0" />
+      <span v-if="parsedPayload?.duration" class="flex-shrink-0">
+        {{ formatSeconds(parsedPayload.duration) }}
+      </span>
+    </template>
+
+    <!-- 名片 -->
+    <CardLineLabel
+      v-else-if="isCard"
+      :card="parsedPayload"
+      class="min-w-0 line-clamp-2 break-words"
+    />
+
+    <!-- 表情贴图：缩略图 + name（无 name 仅显示 [表情]） -->
+    <template v-else-if="isFace">
+      <span class="flex-shrink-0">[表情]</span>
+      <span v-if="parsedPayload?.name" class="min-w-0 line-clamp-2 break-words">
+        {{ parsedPayload.name }}
+      </span>
+    </template>
+
+    <!-- 频道素材：[频道] + 标题 + 封面缩略图 -->
+    <template v-else-if="isMaterial">
+      <span class="flex-shrink-0">[频道]</span>
+      <span v-if="parsedPayload?.title" class="min-w-0 line-clamp-2 break-words">
+        {{ parsedPayload.title }}
+      </span>
+    </template>
+
+    <!-- 图片 / 视频 / 表情贴图 / 频道素材缩略图 -->
+    <img
+      v-if="thumbnailUrl"
+      :src="thumbnailUrl"
+      class="flex-shrink-0 object-cover w-6 h-6 rounded"
+      alt=""
+    />
+
+    <!-- 关闭按钮 -->
+    <button
+      v-if="closable"
+      type="button"
+      class="flex-shrink-0 inline-flex items-center justify-center w-4 h-4 cursor-pointer rounded-full bg-transparent border-none text-[var(--ant-color-text-secondary)] hover:bg-[var(--ant-color-fill)] hover:text-[var(--ant-color-text)]"
+      @click.stop="emit('close')"
+    >
+      <Icon icon="ant-design:close-outlined" :size="10" />
+    </button>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/components/message/tip-segments.vue b/apps/web-ele/src/views/im/home/pages/conversation/components/message/tip-segments.vue
new file mode 100644
index 000000000..19b7be2b1
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/components/message/tip-segments.vue
@@ -0,0 +1,54 @@
+<!--
+  消息文本片段渲染：tip 文案 + TEXT 气泡共用
+  - mention 段挂点击 → openMentionUserInfoCardAtEvent
+  - link 段渲染 <a target="_blank">，浏览器默认行为打开新标签
+  - text 段原样输出
+-->
+<script lang="ts" setup>
+import type { TipSegment } from '#/views/im/utils/message'
+
+import { IM_AT_ALL_USER_ID } from '#/views/im/utils/constants'
+import { openMentionUserInfoCardAtEvent } from '#/views/im/utils/user'
+
+defineOptions({ name: 'ImTipSegments' })
+
+defineProps<{
+  segments: TipSegment[]
+}>()
+
+/** @全体成员是广播 mention，仅高亮配色，不挂可点击交互 */
+function isClickableMention(segment: { userId: number }): boolean {
+  return segment.userId !== IM_AT_ALL_USER_ID
+}
+
+/** mention 段点击：fallbackName 取 segment 文本，避免 friend / member 都查不到时弹空 */
+function handleMentionClick(
+  segment: { text: string; type: 'mention'; userId: number; },
+  event: MouseEvent
+) {
+  if (!isClickableMention(segment)) {
+    return
+  }
+  openMentionUserInfoCardAtEvent(segment.userId, event, segment.text)
+}
+</script>
+
+<template>
+  <template v-for="(segment, _index) in segments" :key="_index">
+    <span
+      v-if="segment.type === 'mention'"
+      class="text-[#576b95]"
+      :class="{ 'cursor-pointer hover:underline': isClickableMention(segment) }"
+      @click.stop="handleMentionClick(segment, $event)"
+      >{{ segment.text }}</span>
+    <a
+      v-else-if="segment.type === 'link'"
+      :href="segment.href"
+      target="_blank"
+      rel="noopener noreferrer"
+      class="text-[#576b95] hover:underline break-all"
+      @click.stop
+      >{{ segment.text }}</a>
+    <span v-else>{{ segment.text }}</span>
+  </template>
+</template>
diff --git a/apps/web-ele/src/views/im/home/pages/conversation/index.vue b/apps/web-ele/src/views/im/home/pages/conversation/index.vue
new file mode 100644
index 000000000..7bd9d538c
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/pages/conversation/index.vue
@@ -0,0 +1,281 @@
+<script lang="ts" setup>
+import type { Conversation } from '../../types'
+
+import { computed, nextTick, ref, watch } from 'vue'
+
+import { IconifyIcon as Icon } from '@vben/icons'
+
+import { ElButton, ElDropdown, ElDropdownItem, ElDropdownMenu, ElInput } from 'element-plus'
+
+import { ImConversationType } from '../../../utils/constants'
+import { filterConversationsByKeyword, getConversationKey } from '../../../utils/conversation'
+import { StorageKeys } from '../../../utils/db'
+import { getGroupDisplayName } from '../../../utils/user'
+import { ResizableAside } from '../../components'
+import { FriendAddDialog } from '../../components/friend'
+import { GroupCreateDialog } from '../../components/group'
+import { useConversationStore } from '../../store/conversationStore'
+import { useGroupStore } from '../../store/groupStore'
+import { useImUiStore } from '../../store/uiStore'
+import { ConversationItem, MessagePanel } from './components'
+
+defineOptions({ name: 'ImMessagePage' })
+
+const conversationStore = useConversationStore()
+const groupStore = useGroupStore()
+const uiStore = useImUiStore()
+
+// ==================== 会话列表 ====================
+
+const keyword = ref('')
+
+const sortedConversations = computed(() => conversationStore.getSortedConversationList)
+
+/** 顶部搜索框过滤会话：只按 name 模糊匹配，避免命中 lastContent 等次要字段干扰 */
+const filteredConversations = computed(() =>
+  filterConversationsByKeyword(sortedConversations.value, keyword.value)
+)
+
+// ==================== 置顶相关 ====================
+
+const PINNED_FOLD_THRESHOLD = 3 // 置顶超过该数量时显示折叠入口；以下数量直接铺开（避免单条置顶就出折叠头视觉太重）
+
+// 置顶折叠展开态：localStorage 持久化，刷新后保留用户上次的选择，对齐微信
+const pinnedExpanded = ref(
+  localStorage.getItem(StorageKeys.localStorage.conversationPinnedExpanded) === 'true'
+)
+
+/** toggle + 写盘 */
+function togglePinnedExpanded() {
+  pinnedExpanded.value = !pinnedExpanded.value
+  localStorage.setItem(
+    StorageKeys.localStorage.conversationPinnedExpanded,
+    String(pinnedExpanded.value)
+  )
+}
+
+/** 置顶会话：单独切片，给折叠头计数 + 折叠区渲染用 */
+const pinnedConversations = computed(() => filteredConversations.value.filter((c) => c.top))
+
+/** 非置顶会话：折叠态下始终铺开在折叠头之下 */
+const normalConversations = computed(() => filteredConversations.value.filter((c) => !c.top))
+
+/**
+ * 置顶分两堆：visible（折叠头之上 = 未读 + 当前激活）/ foldable（折叠头之下）；一次 partition 完成
+ *
+ * 当前激活会话也"钉"在 visible：避免点开未读置顶 → 立刻被读 → 列表一闪重排回折叠的体验
+ */
+const pinnedGroups = computed(() => {
+  const visible: Conversation[] = []
+  const foldable: Conversation[] = []
+  for (const conversation of pinnedConversations.value) {
+    if (isActiveConversation(conversation) || hasUnreadBadge(conversation)) {
+      visible.push(conversation)
+    } else {
+      foldable.push(conversation)
+    }
+  }
+  return { visible, foldable }
+})
+
+/** 折叠时只渲 visible（未读 / 激活穿透）；展开时渲全部 —— 展开后不分组，避免点击折叠区跨组上跳 */
+const renderedPinnedConversations = computed(() =>
+  pinnedExpanded.value ? pinnedConversations.value : pinnedGroups.value.visible
+)
+
+/** 置顶折叠时是否上浮到折叠头之上：仅以数字徽标为准；免打扰即便有未读也只展示小红点，不参与上浮 */
+function hasUnreadBadge(conversation: Conversation): boolean {
+  return !conversation.silent && (conversation.unreadCount || 0) > 0
+}
+
+/** 是否为当前激活会话 */
+function isActiveConversation(conversation: Conversation): boolean {
+  const active = conversationStore.activeConversation
+  return !!active && getConversationKey(active) === getConversationKey(conversation)
+}
+
+/**
+ * 是否进入"分组模式"（独立浅底 + 可能有折叠头）：搜索时不分组（用户在找人，别再让折叠挡住）；
+ * 置顶数 < 阈值也不分组，避免单条置顶就出折叠头视觉太重
+ */
+const showPinnedSection = computed(
+  () => !keyword.value.trim() && pinnedConversations.value.length >= PINNED_FOLD_THRESHOLD
+)
+
+// ==================== 添加朋友 ====================
+
+const friendAddDialogRef = ref<InstanceType<typeof FriendAddDialog>>() // 添加朋友弹窗 ref：右上角 +-下拉「添加朋友」入口调 open() 触发
+
+// ==================== 建群相关 ====================
+
+const createGroupDialogRef = ref<InstanceType<typeof GroupCreateDialog>>() // 发起群聊弹窗 ref：handleOpenCreateGroup 调 open() 打开
+
+/** 打开发起群聊弹窗：无锁定项的全局入口 */
+function handleOpenCreateGroup() {
+  createGroupDialogRef.value?.open()
+}
+
+/** 处理建群成功 */
+function handleGroupCreated(groupId: number) {
+  // GroupCreateDialog 已经 upsertGroup 把新群写进 store，这里只 get + 打开会话
+  const group = groupStore.getGroup(groupId)
+  if (!group) {
+    return
+  }
+  conversationStore.openConversation(
+    groupId,
+    ImConversationType.GROUP,
+    getGroupDisplayName(group),
+    group.avatar || '',
+    { silent: !!group.silent }
+  )
+}
+
+// ==================== 滚动到下一个未读 ====================
+// 工具栏「消息」Tab 二次点击 → uiStore.nextUnreadJumpNonce 递增 → 本页 watch 滚动到下一条未读
+// 含免打扰会话（小红点也算未读）；通过维护 lastJumpedConversationKey 让连续点击顺序穿过整个未读列表
+
+/** 上次命中的未读会话 key；为空时从未读列表头开始 */
+let lastJumpedConversationKey: null | string = null
+
+/** 滚动到下一个未读会话（含免打扰）；目标被搜索框过滤或藏在置顶折叠区时先解除拦截再滚 */
+async function jumpToNextUnread() {
+  // 含免打扰的全量未读会话；空则直接返回
+  const unreadList = sortedConversations.value.filter((c) => (c.unreadCount || 0) > 0)
+  if (unreadList.length === 0) {
+    return
+  }
+  // 从上次命中那条往后推一位；首次或上次目标已读完不在列表里时，refIndex=-1，从头开始
+  const refIndex = lastJumpedConversationKey
+    ? unreadList.findIndex((c) => getConversationKey(c) === lastJumpedConversationKey)
+    : -1
+  const target = unreadList[(refIndex + 1) % unreadList.length]
+  if (!target) {
+    return
+  }
+  const key = getConversationKey(target)
+  lastJumpedConversationKey = key
+
+  // 目标被搜索关键字过滤掉：清空 keyword 让它重新进入可见列表
+  if (keyword.value && !filteredConversations.value.some((c) => getConversationKey(c) === key)) {
+    keyword.value = ''
+  }
+  // 目标藏在置顶折叠区：临时展开；不写 localStorage，刷新后还原折叠态
+  const inFoldable = pinnedGroups.value.foldable.some((c) => getConversationKey(c) === key)
+  if (inFoldable && !pinnedExpanded.value) {
+    pinnedExpanded.value = true
+  }
+
+  // 等 keyword / pinnedExpanded 变化反应到 DOM 后再去取目标元素
+  await nextTick()
+  const el = document.querySelector(`[data-conversation-key="${key}"]`) as HTMLElement | null
+  if (!el) {
+    return
+  }
+  // block: 'start' 把目标会话顶到列表可视区第一行；对齐微信"切到下一个未读=列表的第一条"
+  el.scrollIntoView({ behavior: 'smooth', block: 'start' })
+}
+
+watch(() => uiStore.nextUnreadJumpNonce, jumpToNextUnread)
+</script>
+
+<template>
+  <!-- 消息 Tab：左侧会话列表 + 右侧聊天面板 -->
+  <div class="flex flex-1 min-w-0 h-full">
+    <!-- 左侧会话列表（可拖拽宽度） -->
+    <ResizableAside :default-width="260" :storage-key="StorageKeys.localStorage.asideWidth">
+      <!-- 顶部：搜索框 + "+" 号下拉（对齐微信 PC：发起群聊 / 添加朋友）；h-14 与右侧 MessagePanel 头部对齐 -->
+      <div
+        class="flex flex-shrink-0 gap-2 items-center h-14 px-4 border-b border-b-solid border-[var(--im-border-color-lighter)]"
+      >
+        <ElInput v-model="keyword" placeholder="搜索" clearable class="flex-1">
+          <template #prefix>
+            <Icon icon="ant-design:search-outlined" />
+          </template>
+        </ElInput>
+        <ElDropdown trigger="click" placement="bottom">
+          <ElButton size="small" circle>
+            <Icon icon="ant-design:plus-outlined" />
+          </ElButton>
+          <template #dropdown>
+            <ElDropdownMenu>
+              <ElDropdownItem @click="handleOpenCreateGroup">
+                <span class="inline-flex items-center gap-2">
+                  <Icon icon="ant-design:message-outlined" :size="16" />
+                  <span>发起群聊</span>
+                </span>
+              </ElDropdownItem>
+              <ElDropdownItem @click="friendAddDialogRef?.open()">
+                <span class="inline-flex items-center gap-2">
+                  <Icon icon="ant-design:user-add-outlined" :size="16" />
+                  <span>添加朋友</span>
+                </span>
+              </ElDropdownItem>
+            </ElDropdownMenu>
+          </template>
+        </ElDropdown>
+      </div>
+
+      <!-- 会话列表主体 -->
+      <div class="flex-1 overflow-y-auto">
+        <!-- 置顶会话：数量 < 阈值或搜索中直接铺开；否则进入分组模式（独立浅底 + 可选折叠头） -->
+        <template v-if="!showPinnedSection">
+          <ConversationItem
+            v-for="conversation in pinnedConversations"
+            :key="getConversationKey(conversation)"
+            :conversation="conversation"
+          />
+        </template>
+        <div v-else class="bg-[var(--ant-color-fill-secondary)]">
+          <ConversationItem
+            v-for="conversation in renderedPinnedConversations"
+            :key="getConversationKey(conversation)"
+            :conversation="conversation"
+          />
+
+          <!-- 折叠头：放在置顶区底部对齐 WeChat mac；展开 / 折叠态共用，仅在还有"可折叠"内容、或当前已展开时出现 -->
+          <div
+            v-if="pinnedGroups.foldable.length > 0 || pinnedExpanded"
+            class="flex items-center justify-between px-4 py-2.5 cursor-pointer transition-colors text-13px text-[var(--ant-color-text)] border-y border-y-solid border-[var(--im-border-color-lighter)] hover:bg-[var(--ant-color-fill)]"
+            @click="togglePinnedExpanded"
+          >
+            <span class="flex items-center gap-1.5">
+              <Icon icon="ant-design:menu-outlined" :size="14" />
+              {{
+                pinnedExpanded
+                  ? '折叠置顶聊天'
+                  : `${pinnedGroups.foldable.length} 个置顶聊天`
+              }}
+            </span>
+            <Icon
+              :icon="pinnedExpanded ? 'ant-design:up-outlined' : 'ant-design:down-outlined'"
+              :size="11"
+              class="text-[var(--ant-color-text-placeholder)]"
+            />
+          </div>
+        </div>
+
+        <!-- 普通会话 -->
+        <ConversationItem
+          v-for="conversation in normalConversations"
+          :key="getConversationKey(conversation)"
+          :conversation="conversation"
+        />
+
+        <div
+          v-if="filteredConversations.length === 0"
+          class="flex items-center justify-center py-10 text-sm text-[var(--ant-color-text-secondary)]"
+        >
+          {{ keyword ? '没有满足条件的会话' : '暂无会话' }}
+        </div>
+      </div>
+    </ResizableAside>
+
+    <!-- 右侧聊天面板 -->
+    <MessagePanel />
+
+    <!-- 添加朋友 / 发起群聊弹窗 -->
+    <FriendAddDialog ref="friendAddDialogRef" />
+    <GroupCreateDialog ref="createGroupDialogRef" @created="handleGroupCreated" />
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/home/store/channelStore.ts b/apps/web-ele/src/views/im/home/store/channelStore.ts
new file mode 100644
index 000000000..3f059ca0c
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/store/channelStore.ts
@@ -0,0 +1,108 @@
+import type { ImManagerChannelApi } from '#/api/im/manager/channel'
+
+import { acceptHMRUpdate, defineStore } from 'pinia'
+
+import { getSimpleChannelList } from '#/api/im/manager/channel'
+
+import { ImConversationType } from '../../utils/constants'
+import { getDb } from '../../utils/db'
+import { useConversationStore } from './conversationStore'
+
+/**
+ * IM 频道 Store
+ *
+ * 负责：缓存当前用户能看到的频道精简列表（含 id / code / name / avatar），
+ * 供会话列表 / 卡片渲染时反查频道名称 + 头像，避免显示「频道 1」这种占位
+ */
+export const useChannelStore = defineStore('imChannelStore', {
+  state: () => ({
+    channels: [] as ImManagerChannelApi.Channel[],
+    loaded: false
+  }),
+
+  getters: {
+    getChannel(state): (id: number) => ImManagerChannelApi.Channel | undefined {
+      return (id: number) => state.channels.find((c) => c.id === id)
+    }
+  },
+
+  actions: {
+    // ==================== 本地缓存 ====================
+
+    /** 从 IndexedDB 恢复频道列表 */
+    async loadChannelList(): Promise<boolean> {
+      try {
+        const cached = await getDb().getAll<ImManagerChannelApi.Channel>('channels')
+        if (!cached || cached.length === 0) {
+          return false
+        }
+        this.channels = cached
+        return true
+      } catch (error) {
+        console.warn('[IM channelStore] 本地频道缓存读取失败', error)
+        return false
+      }
+    },
+
+    /** 保存频道列表 */
+    saveChannelList(): void {
+      void getDb()
+        .transaction(['channels'], 'readwrite', async (tx) => {
+          const db = getDb()
+          await db.clearStore('channels', tx)
+          for (const channel of this.channels) {
+            await db.put('channels', channel, tx)
+          }
+        })
+        .catch((error) => console.warn('[IM channelStore] 本地频道缓存写入失败', error))
+    },
+
+    // ==================== 远端拉取 ====================
+
+    /** 拉取启用的频道精简列表；成功后回填会话列表已有的频道 name / avatar，覆盖 IDB 旧占位 */
+    async fetchChannelList(force = false) {
+      if (this.loaded && !force) {
+        return
+      }
+      try {
+        this.channels = (await getSimpleChannelList()) || []
+        this.loaded = true
+        this.syncChannelConversationMetadata()
+        this.saveChannelList()
+      } catch (error) {
+        console.warn('[IM channelStore] fetchChannelList 失败', error)
+      }
+    },
+
+    /** 用最新的频道信息覆盖已有 CHANNEL 会话的 name / avatar */
+    syncChannelConversationMetadata() {
+      const conversationStore = useConversationStore()
+      const indexed = new Map(this.channels.map((c) => [c.id, c]))
+      conversationStore.conversations.forEach((conversation) => {
+        if (conversation.type !== ImConversationType.CHANNEL) {
+          return
+        }
+        const channel = indexed.get(conversation.targetId)
+        if (!channel) {
+          return
+        }
+        conversationStore.updateConversation(ImConversationType.CHANNEL, conversation.targetId, {
+          name: channel.name,
+          avatar: channel.avatar
+        })
+      })
+    },
+
+    /** 清空频道内存 */
+    clear() {
+      this.channels = []
+      this.loaded = false
+    }
+  }
+})
+
+if (import.meta.hot) {
+  import.meta.hot.accept(acceptHMRUpdate(useChannelStore, import.meta.hot))
+}
+
+export const useChannelStoreWithOut = () => useChannelStore()
diff --git a/apps/web-ele/src/views/im/home/store/conversationStore.ts b/apps/web-ele/src/views/im/home/store/conversationStore.ts
new file mode 100644
index 000000000..e108338b0
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/store/conversationStore.ts
@@ -0,0 +1,885 @@
+import type {
+  Conversation,
+  ConversationDO,
+  ConversationRead,
+  ConversationReadDO,
+  MessageDO
+} from '../types'
+
+import type { ImConversationReadApi } from '#/api/im/conversation/read'
+
+import { acceptHMRUpdate, defineStore } from 'pinia'
+
+import { pullMyConversationReadList as apiPullMyConversationReadList } from '#/api/im/conversation/read'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { CONVERSATION_RECENT_FORWARD_MAX } from '../../utils/config'
+import {
+  ImConversationType,
+  ImMessageReceiptStatus,
+  ImMessageStatus,
+  isNormalMessage
+} from '../../utils/constants'
+import { type DbTransaction, getClientConversationId, getDb, StorageKeys } from '../../utils/db'
+import { runIncrementalPull } from '../../utils/pull'
+import { useMessageStore } from './messageStore'
+
+const PERSIST_DRAFT_DEBOUNCE_MS = 500
+const pendingDraftConversations = new Set<Conversation>()
+
+type LegacyConversationDO = ConversationDO & { readMessageId?: number }
+
+/** 创建草稿保存防抖函数 */
+function createDraftDebounce(fn: () => void, wait: number) {
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  const run = () => {
+    if (timer) {
+      clearTimeout(timer)
+      timer = undefined
+    }
+    fn()
+  }
+  const debounced = () => {
+    if (timer) {
+      clearTimeout(timer)
+    }
+    timer = setTimeout(run, wait)
+  }
+  debounced.cancel = () => {
+    if (timer) {
+      clearTimeout(timer)
+      timer = undefined
+    }
+  }
+  debounced.flush = run
+  return debounced
+}
+
+/** 会话转 IndexedDB 记录 */
+function toConversationDO(conversation: Conversation): ConversationDO {
+  const draft = conversation.draft
+  return {
+    targetId: conversation.targetId,
+    type: conversation.type,
+    name: conversation.name,
+    avatar: conversation.avatar,
+    unreadCount: conversation.unreadCount,
+    lastContent: conversation.lastContent,
+    lastSendTime: conversation.lastSendTime,
+    lastSenderId: conversation.lastSenderId,
+    lastMessageType: conversation.lastMessageType,
+    lastMessageId: conversation.lastMessageId,
+    lastClientMessageId: conversation.lastClientMessageId,
+    lastMessageStatus: conversation.lastMessageStatus,
+    lastReceiptStatus: conversation.lastReceiptStatus,
+    lastSelfSend: conversation.lastSelfSend,
+    lastSenderDisplayName: conversation.lastSenderDisplayName,
+    deleted: conversation.deleted,
+    top: conversation.top,
+    silent: conversation.silent,
+    atMe: conversation.atMe,
+    atAll: conversation.atAll,
+    draft: draft ? { ...draft, reply: draft.reply ? { ...draft.reply } : undefined } : undefined,
+    clientConversationId: getClientConversationId(conversation.type, conversation.targetId)
+  }
+}
+
+/** IndexedDB 记录转会话 */
+function fromConversationDO(conversation: LegacyConversationDO): Conversation {
+  const {
+    clientConversationId: _clientConversationId,
+    readMessageId: _readMessageId,
+    ...rest
+  } = conversation
+  return rest
+}
+
+/** 会话读位置转 IndexedDB 记录 */
+function toConversationReadDO(record: ConversationRead): ConversationReadDO {
+  return {
+    conversationType: record.conversationType,
+    targetId: record.targetId,
+    messageId: record.messageId,
+    updateTime: record.updateTime,
+    clientConversationId: getClientConversationId(record.conversationType, record.targetId)
+  }
+}
+
+/** IndexedDB 记录转会话读位置 */
+function fromConversationReadDO(record: ConversationReadDO): ConversationRead {
+  const { clientConversationId: _clientConversationId, ...rest } = record
+  return rest
+}
+
+/** 是否为有效会话读位置 */
+function isValidConversationReadRecord(record: ImConversationReadApi.ConversationReadRespVO): boolean {
+  return !!record.conversationType && !!record.targetId && !!record.messageId
+}
+
+/** 获取对方普通消息最大编号 */
+function getMaxIncomingNormalMessageId(
+  messages: Array<Pick<MessageDO, 'id' | 'selfSend' | 'status' | 'type'>>
+): number {
+  let maxMessageId = 0
+  for (const message of messages) {
+    if (
+      message.id &&
+      !message.selfSend &&
+      isNormalMessage(message.type) &&
+      message.status !== ImMessageStatus.RECALL &&
+      message.id > maxMessageId
+    ) {
+      maxMessageId = message.id
+    }
+  }
+  return maxMessageId
+}
+
+export const useConversationStore = defineStore('imConversationStore', {
+  state: () => ({
+    conversations: [] as Conversation[], // 全量会话列表（私聊 + 群聊 + 频道）
+    conversationReads: {} as Record<string, ConversationRead>, // 会话读位置
+    activeConversation: null as Conversation | null, // 当前激活的会话
+    loading: false, // 是否正在批量加载
+    recentForwardConversationKeys: [] as string[] // 最近转发会话 key 列表
+  }),
+
+  getters: {
+    /** 排序后的会话列表 */
+    getSortedConversationList(state): Conversation[] {
+      return state.conversations
+        .filter((conversation) => !conversation.deleted)
+        .toSorted((a, b) => {
+          const aTop = a.top ? 1 : 0
+          const bTop = b.top ? 1 : 0
+          if (aTop !== bTop) {
+            return bTop - aTop
+          }
+          return (b.lastSendTime || 0) - (a.lastSendTime || 0)
+        })
+    },
+
+    /** 未读总数 */
+    getTotalUnreadCount(state): number {
+      return state.conversations
+        .filter((conversation) => !conversation.deleted && !conversation.silent)
+        .reduce((sum, conversation) => sum + (conversation.unreadCount || 0), 0)
+    },
+
+    /** 查找会话 */
+    getConversation:
+      (state) =>
+      (type: number, targetId: number): Conversation | undefined =>
+        state.conversations.find(
+          (conversation) => conversation.type === type && conversation.targetId === targetId
+        ),
+
+    /** 查找会话读位置 */
+    getConversationRead:
+      (state) =>
+      (type: number, targetId: number): ConversationRead | undefined =>
+        state.conversationReads[getClientConversationId(type, targetId)]
+  },
+
+  actions: {
+    /** 加载会话 */
+    async loadConversationList() {
+      // 1. 清理旧账号内存
+      const userId = getCurrentUserId()
+      if (!userId) {
+        this.clear()
+        return
+      }
+      const previousActiveKey = this.activeConversation
+        ? getClientConversationId(this.activeConversation.type, this.activeConversation.targetId)
+        : null
+      this.clear()
+      // 2. 从 IndexedDB 读取会话和轻量设置
+      const db = getDb()
+      const [conversations, conversationReads, recent] = await Promise.all([
+        db.getAll<ConversationDO>('conversations'),
+        db.getAll<ConversationReadDO>('conversationReads'),
+        db.getSetting<string[]>(StorageKeys.settings.recentForwardConversationKeys)
+      ])
+      const nextConversationReads: Record<string, ConversationRead> = {}
+      for (const record of conversationReads) {
+        const item = fromConversationReadDO(record)
+        nextConversationReads[getClientConversationId(item.conversationType, item.targetId)] = item
+      }
+      const migratedReads: ConversationRead[] = []
+      for (const conversation of conversations as LegacyConversationDO[]) {
+        if (!conversation.readMessageId) {
+          continue
+        }
+        const key = getClientConversationId(conversation.type, conversation.targetId)
+        if (nextConversationReads[key]) {
+          continue
+        }
+        const record = {
+          conversationType: conversation.type,
+          targetId: conversation.targetId,
+          messageId: conversation.readMessageId
+        }
+        nextConversationReads[key] = record
+        migratedReads.push(record)
+      }
+      const nextConversations = (conversations as LegacyConversationDO[]).map((conversation) =>
+        fromConversationDO(conversation)
+      )
+      this.conversationReads = nextConversationReads
+      await this.applyLocalConversationReads(nextConversations)
+      this.conversations = nextConversations
+      if (migratedReads.length > 0) {
+        void this.saveConversationReadRecord(migratedReads).catch((error) =>
+          console.warn('[IM conversationStore] 会话读位置迁移失败', error)
+        )
+      }
+      if (Array.isArray(recent)) {
+        this.recentForwardConversationKeys = recent.slice(0, CONVERSATION_RECENT_FORWARD_MAX)
+      }
+      // 3. 恢复当前激活会话
+      if (previousActiveKey) {
+        this.activeConversation =
+          this.conversations.find(
+            (conversation) =>
+              !conversation.deleted &&
+              getClientConversationId(conversation.type, conversation.targetId) ===
+                previousActiveKey
+          ) ?? null
+      }
+    },
+
+    /** 清空会话内存 */
+    clear() {
+      saveDraftConversationListDebounced.cancel()
+      pendingDraftConversations.clear()
+      this.conversations = []
+      this.conversationReads = {}
+      this.activeConversation = null
+      this.recentForwardConversationKeys = []
+    },
+
+    /** 持久化会话读位置 */
+    async saveConversationReadRecord(
+      target: ConversationRead | ConversationRead[] | null | undefined,
+      tx?: DbTransaction
+    ): Promise<void> {
+      let targets: ConversationRead[] = []
+      if (Array.isArray(target)) {
+        targets = target
+      } else if (target) {
+        targets = [target]
+      }
+      const records = targets.map((record) => toConversationReadDO(record))
+      if (records.length === 0) {
+        return
+      }
+      const db = getDb()
+      if (tx) {
+        for (const record of records) {
+          await db.put('conversationReads', record, tx)
+        }
+        return
+      }
+      await db.transaction(['conversationReads'], 'readwrite', async (tx) => {
+        for (const record of records) {
+          await db.put('conversationReads', record, tx)
+        }
+      })
+    },
+
+    /** 应用本地会话读位置 */
+    async applyLocalConversationReads(conversations?: Conversation[]) {
+      const targetConversations = conversations || this.conversations
+      const changedConversations: Conversation[] = []
+      for (const conversation of targetConversations) {
+        const record = this.getConversationRead(conversation.type, conversation.targetId)
+        if (!record) {
+          continue
+        }
+        if (this.applyReadToConversation(conversation, record.messageId)) {
+          changedConversations.push(conversation)
+          continue
+        }
+        if (conversation.unreadCount === 0 && !conversation.atMe && !conversation.atAll) {
+          continue
+        }
+        const messages = await getDb().getAllByIndex<MessageDO>(
+          'messages',
+          'clientConversationId',
+          getClientConversationId(conversation.type, conversation.targetId)
+        )
+        const maxIncomingMessageId = getMaxIncomingNormalMessageId(messages)
+        if (maxIncomingMessageId > 0 && maxIncomingMessageId <= record.messageId) {
+          conversation.unreadCount = 0
+          conversation.atMe = false
+          conversation.atAll = false
+          changedConversations.push(conversation)
+        }
+      }
+      if (changedConversations.length > 0) {
+        await this.saveConversationRecord(changedConversations)
+      }
+    },
+
+    /** 判断消息是否已被会话读位置覆盖 */
+    isMessageCoveredByReadPosition(
+      conversation: Pick<Conversation, 'targetId' | 'type'>,
+      message?: null | { id?: number }
+    ): boolean {
+      if (!message?.id) {
+        return false
+      }
+      const record = this.getConversationRead(conversation.type, conversation.targetId)
+      return !!record && message.id <= record.messageId
+    },
+
+    /** 应用读位置到会话 */
+    applyReadToConversation(conversation: Conversation, messageId: number): boolean {
+      if (!conversation.lastMessageId || conversation.lastMessageId > messageId) {
+        return false
+      }
+      if (conversation.unreadCount === 0 && !conversation.atMe && !conversation.atAll) {
+        return false
+      }
+      conversation.unreadCount = 0
+      conversation.atMe = false
+      conversation.atAll = false
+      return true
+    },
+
+    /** 应用会话读位置 */
+    async applyConversationReadList(
+      records: ImConversationReadApi.ConversationReadRespVO[],
+      isActive?: () => boolean
+    ): Promise<void> {
+      if (records.length === 0) {
+        return
+      }
+      const changedReads = new Map<string, ConversationRead>()
+      const changedConversations = new Map<string, Conversation>()
+      const changedMessages = new Map<string, MessageDO>()
+      const db = getDb()
+      const messageStore = useMessageStore()
+
+      // 1. 按读位置更新会话未读和频道已读态
+      for (const record of records) {
+        if (isActive && !isActive()) {
+          return
+        }
+        if (!isValidConversationReadRecord(record)) {
+          continue
+        }
+        const clientConversationId = getClientConversationId(
+          record.conversationType,
+          record.targetId
+        )
+        let storedMessages: MessageDO[] | undefined
+        const getStoredMessages = async () => {
+          if (!storedMessages) {
+            storedMessages = await db.getAllByIndex<MessageDO>(
+              'messages',
+              'clientConversationId',
+              clientConversationId
+            )
+          }
+          return storedMessages
+        }
+        const current = this.conversationReads[clientConversationId]
+        const messageId = Math.max(record.messageId, current?.messageId || 0)
+        if (!current || messageId > current.messageId) {
+          const next = {
+            conversationType: record.conversationType,
+            targetId: record.targetId,
+            messageId,
+            updateTime: record.updateTime
+          }
+          this.conversationReads[clientConversationId] = next
+          changedReads.set(clientConversationId, next)
+        }
+
+        const conversation = this.getConversation(record.conversationType, record.targetId)
+        if (conversation && this.applyReadToConversation(conversation, messageId)) {
+          changedConversations.set(clientConversationId, conversation)
+        } else if (conversation) {
+          const maxIncomingMessageId = getMaxIncomingNormalMessageId(await getStoredMessages())
+          if (maxIncomingMessageId > 0 && maxIncomingMessageId <= messageId) {
+            conversation.unreadCount = 0
+            conversation.atMe = false
+            conversation.atAll = false
+            changedConversations.set(clientConversationId, conversation)
+          }
+        }
+        if (record.conversationType !== ImConversationType.CHANNEL) {
+          continue
+        }
+        const memoryMessages = messageStore.getMessages(clientConversationId)
+        for (const message of memoryMessages) {
+          if (
+            message.id &&
+            message.id <= messageId &&
+            message.receiptStatus !== ImMessageReceiptStatus.DONE
+          ) {
+            message.receiptStatus = ImMessageReceiptStatus.DONE
+          }
+        }
+        for (const message of await getStoredMessages()) {
+          if (
+            message.id &&
+            message.id <= messageId &&
+            message.receiptStatus !== ImMessageReceiptStatus.DONE
+          ) {
+            message.receiptStatus = ImMessageReceiptStatus.DONE
+            changedMessages.set(message.messageKey, message)
+          }
+        }
+      }
+
+      // 2. 持久化本轮变更
+      if (
+        changedReads.size === 0 &&
+        changedConversations.size === 0 &&
+        changedMessages.size === 0
+      ) {
+        return
+      }
+      if (isActive && !isActive()) {
+        return
+      }
+      const stores: Array<'conversationReads' | 'conversations' | 'messages'> = []
+      if (changedReads.size > 0) {
+        stores.push('conversationReads')
+      }
+      if (changedConversations.size > 0) {
+        stores.push('conversations')
+      }
+      if (changedMessages.size > 0) {
+        stores.push('messages')
+      }
+      await db.transaction(stores, 'readwrite', async (tx) => {
+        if (changedReads.size > 0) {
+          await this.saveConversationReadRecord([...changedReads.values()], tx)
+        }
+        if (changedConversations.size > 0) {
+          await this.saveConversationRecord([...changedConversations.values()], tx)
+        }
+        for (const message of changedMessages.values()) {
+          await db.put('messages', message, tx)
+        }
+      })
+    },
+
+    /** 增量拉取会话读位置 */
+    async pullConversationReads(isActive?: () => boolean): Promise<void> {
+      await runIncrementalPull(
+        StorageKeys.settings.conversationReadPullCursor,
+        apiPullMyConversationReadList,
+        async (records) => {
+          if (isActive && !isActive()) {
+            return false
+          }
+          await this.applyConversationReadList(records, isActive)
+          if (isActive && !isActive()) {
+            return false
+          }
+          return true
+        },
+        isActive
+      )
+    },
+
+    /** 执行会话记录持久化 */
+    async saveConversationRecord(
+      target: Conversation | Conversation[] | null | undefined,
+      tx?: DbTransaction
+    ): Promise<void> {
+      const db = getDb()
+      const conversations = (Array.isArray(target) ? target : (target ? [target] : [])).map(
+        (conversation) => toConversationDO(conversation)
+      )
+      if (conversations.length === 0) {
+        return
+      }
+      if (tx) {
+        for (const conversation of conversations) {
+          await db.put('conversations', conversation, tx)
+        }
+        return
+      }
+      await db.transaction(['conversations'], 'readwrite', async (tx) => {
+        for (const conversation of conversations) {
+          await db.put('conversations', conversation, tx)
+        }
+      })
+    },
+
+    /** 持久化单个会话 */
+    saveConversation(conversation: Conversation | null | undefined, tx?: DbTransaction): void {
+      if (!conversation) {
+        return
+      }
+      void this.saveConversationRecord(conversation, tx).catch((error) =>
+        console.warn('[IM conversationStore] 会话写入失败', error)
+      )
+    },
+
+    /** 持久化会话列表 */
+    saveConversationList(conversations?: Conversation[] | null, tx?: DbTransaction): void {
+      if (this.loading && !tx) {
+        return
+      }
+      void this.saveConversationRecord(conversations || this.conversations, tx).catch((error) =>
+        console.warn('[IM conversationStore] 会话写入失败', error)
+      )
+    },
+
+    /** 确保会话存在 */
+    ensureConversation(info: {
+      avatar: string
+      name: string
+      silent?: boolean
+      targetId: number
+      type: number
+    }): Conversation {
+      // 1. 创建不存在的会话
+      let conversation = this.getConversation(info.type, info.targetId)
+      if (!conversation) {
+        conversation = this.createEmptyConversation(
+          info.type,
+          info.targetId,
+          info.name,
+          info.avatar,
+          info.silent
+        )
+        this.conversations.unshift(conversation)
+      } else if (conversation.deleted) {
+        // 2. 恢复软删除会话
+        conversation.deleted = false
+        conversation.name = info.name || conversation.name
+        conversation.avatar = info.avatar || conversation.avatar
+        if (info.silent !== undefined) {
+          conversation.silent = info.silent
+        }
+      } else {
+        // 3. 同步会话展示元数据
+        if (info.name) {
+          conversation.name = info.name
+        }
+        if (info.avatar) {
+          conversation.avatar = info.avatar
+        }
+        if (info.silent !== undefined) {
+          conversation.silent = info.silent
+        }
+      }
+      return conversation
+    },
+
+    /** 打开或创建会话 */
+    openConversation(
+      targetId: number,
+      type: number,
+      name: string,
+      avatar: string,
+      options?: { silent?: boolean }
+    ): Conversation {
+      // 1. 确保会话在列表中
+      const conversation = this.ensureConversation({
+        type,
+        targetId,
+        name,
+        avatar,
+        silent: options?.silent
+      })
+      // 2. 激活会话并保存
+      this.setActiveConversation(conversation)
+      this.saveConversation(conversation)
+      return conversation
+    },
+
+    /** 设置当前会话 */
+    setActiveConversation(conversation: Conversation | null) {
+      this.activeConversation = conversation
+      if (!conversation) {
+        return
+      }
+      // 1. 清理会话级未读状态
+      conversation.unreadCount = 0
+      conversation.atMe = false
+      conversation.atAll = false
+      // 2. 懒加载消息并保存会话摘要
+      void useMessageStore().ensureConversationMessageListLoaded(conversation)
+      this.saveConversation(conversation)
+    },
+
+    /** 创建空会话 */
+    createEmptyConversation(
+      type: number,
+      targetId: number,
+      name: string,
+      avatar: string,
+      silent = false
+    ): Conversation {
+      return {
+        targetId,
+        type,
+        name,
+        avatar,
+        lastContent: '',
+        lastSendTime: 0,
+        unreadCount: 0,
+        deleted: false,
+        top: false,
+        silent,
+        atMe: false,
+        atAll: false
+      }
+    },
+
+    /** 设置置顶 */
+    setConversationTop(type: number, targetId: number, top: boolean) {
+      const conversation = this.getConversation(type, targetId)
+      if (!conversation) {
+        return
+      }
+      conversation.top = top
+      this.saveConversation(conversation)
+    },
+
+    /** 设置免打扰 */
+    setConversationSilent(type: number, targetId: number, silent: boolean) {
+      const conversation = this.getConversation(type, targetId)
+      if (!conversation) {
+        return
+      }
+      conversation.silent = silent
+      this.saveConversation(conversation)
+    },
+
+    /** 删除会话 */
+    removeConversation(type: number, targetId: number) {
+      // 1. 标记会话删除
+      const conversation = this.getConversation(type, targetId)
+      if (!conversation) {
+        return
+      }
+      if (this.activeConversation === conversation) {
+        this.activeConversation = null
+      }
+      conversation.deleted = true
+      // 2. 删除会话关联的消息和草稿
+      useMessageStore().deleteConversationMessageList(type, targetId)
+      this.clearConversationDraft(conversation)
+      this.saveConversation(conversation)
+    },
+
+    /** 删除私聊会话 */
+    removePrivateConversation(friendId: number) {
+      this.removeConversation(ImConversationType.PRIVATE, friendId)
+    },
+
+    /** 删除群聊会话 */
+    removeGroupConversation(groupId: number) {
+      this.removeConversation(ImConversationType.GROUP, groupId)
+    },
+
+    /** 标记会话已读 */
+    markConversationRead(type: number, targetId: number, messageId?: number) {
+      const conversation = this.getConversation(type, targetId)
+      if (!conversation) {
+        return
+      }
+      const key = getClientConversationId(type, targetId)
+      const current = this.conversationReads[key]
+      const readMessageIdAdvanced = !!messageId && messageId > (current?.messageId || 0)
+      if (
+        conversation.unreadCount === 0 &&
+        !conversation.atMe &&
+        !conversation.atAll &&
+        !readMessageIdAdvanced
+      ) {
+        return
+      }
+      conversation.unreadCount = 0
+      conversation.atMe = false
+      conversation.atAll = false
+      if (readMessageIdAdvanced) {
+        const record = {
+          conversationType: type,
+          targetId,
+          messageId,
+          updateTime: Date.now()
+        }
+        this.conversationReads[key] = record
+        void getDb()
+          .transaction(['conversations', 'conversationReads'], 'readwrite', async (tx) => {
+            await this.saveConversationRecord(conversation, tx)
+            await this.saveConversationReadRecord(record, tx)
+          })
+          .catch((error) => console.warn('[IM conversationStore] 会话已读写入失败', error))
+        return
+      }
+      this.saveConversation(conversation)
+    },
+
+    // ==================== 最近转发 ====================
+
+    /** 推送最近转发会话 */
+    pushRecentForwardConversationKeyList(keys: string[]) {
+      if (!keys || keys.length === 0) {
+        return
+      }
+      const merged = [...keys, ...this.recentForwardConversationKeys]
+      this.recentForwardConversationKeys = [...new Set(merged)].slice(
+        0,
+        CONVERSATION_RECENT_FORWARD_MAX
+      )
+      this.saveRecentForwardConversationKeyList()
+    },
+
+    /** 移除最近转发会话 */
+    removeRecentForwardConversationKey(key: string) {
+      const index = this.recentForwardConversationKeys.indexOf(key)
+      if (index === -1) {
+        return
+      }
+      this.recentForwardConversationKeys.splice(index, 1)
+      this.saveRecentForwardConversationKeyList()
+    },
+
+    /** 保存最近转发会话 */
+    saveRecentForwardConversationKeyList() {
+      void getDb()
+        .setSetting(
+          StorageKeys.settings.recentForwardConversationKeys,
+          this.recentForwardConversationKeys.slice(0, CONVERSATION_RECENT_FORWARD_MAX)
+        )
+        .catch((error) => console.warn('[IM conversationStore] 最近转发列表写入失败', error))
+    },
+
+    // ==================== 会话维护 ====================
+
+    /** 重排会话 */
+    sortConversationList() {
+      this.conversations.sort((a, b) => (b.lastSendTime || 0) - (a.lastSendTime || 0))
+      this.saveConversationList(this.conversations)
+    },
+
+    /** 同步会话展示元数据 */
+    updateConversation(
+      type: number,
+      targetId: number,
+      info: { avatar?: string; name?: string; silent?: boolean }
+    ) {
+      const conversation = this.getConversation(type, targetId)
+      if (!conversation) {
+        return
+      }
+      let changed = false
+      if (info.name && conversation.name !== info.name) {
+        conversation.name = info.name
+        changed = true
+      }
+      if (info.avatar !== undefined && conversation.avatar !== info.avatar) {
+        conversation.avatar = info.avatar || ''
+        changed = true
+      }
+      if (info.silent !== undefined && conversation.silent !== info.silent) {
+        conversation.silent = info.silent
+        changed = true
+      }
+      if (changed) {
+        this.saveConversation(conversation)
+      }
+    },
+
+    // ==================== 草稿 ====================
+
+    /** 获取草稿 */
+    getConversationDraft(conversation: { targetId: number; type: number; }): Conversation['draft'] | undefined {
+      return this.getConversation(conversation.type, conversation.targetId)?.draft
+    },
+
+    /** 设置草稿 */
+    setConversationDraft(
+      conversation: { targetId: number; type: number; },
+      snapshot: NonNullable<Conversation['draft']>
+    ): void {
+      if (!snapshot.plain.trim() && !snapshot.reply) {
+        this.clearConversationDraft(conversation)
+        return
+      }
+      const target = this.getConversation(conversation.type, conversation.targetId)
+      if (!target) {
+        return
+      }
+      target.draft = snapshot
+      this.scheduleConversationDraftSave(target)
+    },
+
+    /** 清除草稿 */
+    clearConversationDraft(conversation: { targetId: number; type: number; }): void {
+      const target = this.getConversation(conversation.type, conversation.targetId)
+      if (!target?.draft) {
+        return
+      }
+      target.draft = undefined
+      this.scheduleConversationDraftSave(target)
+    },
+
+    /** 设置回复草稿 */
+    setConversationReplyDraft(
+      conversation: { targetId: number; type: number; },
+      quote: NonNullable<Conversation['draft']>['reply']
+    ) {
+      if (!quote) {
+        return
+      }
+      const existing = this.getConversationDraft(conversation)
+      this.setConversationDraft(conversation, {
+        html: existing?.html ?? '',
+        plain: existing?.plain ?? '',
+        reply: quote
+      })
+    },
+
+    /** 清除回复草稿 */
+    clearConversationReplyDraft(conversation: { targetId: number; type: number; }): void {
+      const existing = this.getConversationDraft(conversation)
+      if (!existing?.reply) {
+        return
+      }
+      this.setConversationDraft(conversation, { ...existing, reply: undefined })
+    },
+
+    /** 调度草稿保存 */
+    scheduleConversationDraftSave(conversation: Conversation): void {
+      pendingDraftConversations.add(conversation)
+      saveDraftConversationListDebounced()
+    },
+
+    /** 立即保存草稿 */
+    flushConversationDraftSave(): void {
+      saveDraftConversationListDebounced.flush()
+    }
+  }
+})
+
+export const useConversationStoreWithOut = () => useConversationStore()
+
+/** 合并草稿写入 */
+const saveDraftConversationListDebounced = createDraftDebounce(() => {
+  const conversations = [...pendingDraftConversations]
+  pendingDraftConversations.clear()
+  if (conversations.length === 0) {
+    return
+  }
+  void useConversationStoreWithOut()
+    .saveConversationRecord(conversations)
+    .catch((error) => console.warn('[IM conversationStore] 草稿写入失败', error))
+}, PERSIST_DRAFT_DEBOUNCE_MS)
+
+if (import.meta.hot) {
+  import.meta.hot.accept(acceptHMRUpdate(useConversationStore, import.meta.hot))
+}
diff --git a/apps/web-ele/src/views/im/home/store/faceStore.ts b/apps/web-ele/src/views/im/home/store/faceStore.ts
new file mode 100644
index 000000000..40112a2ef
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/store/faceStore.ts
@@ -0,0 +1,151 @@
+import type { ImFacePackApi } from '#/api/im/face/pack'
+import type { ImFaceUserItemApi } from '#/api/im/face/useritem'
+
+import { ref } from 'vue'
+
+import { acceptHMRUpdate, defineStore } from 'pinia'
+
+import { getFacePackList as apiGetFacePackList } from '#/api/im/face/pack'
+import { createFaceUserItem as apiCreateFaceUserItem, deleteFaceUserItem as apiDeleteFaceUserItem, getFaceUserItemList as apiGetFaceUserItemList } from '#/api/im/face/useritem'
+
+/**
+ * IM 表情面板数据 store（系统表情包 + 个人表情）
+ *
+ * 不持久化：数据小、低频；每次进 IM 第一次打开表情面板时按需拉，关 tab 即丢弃
+ * - 系统包：IM 主页 onMounted 后台预拉（不阻塞首屏），消除面板首次展开的白屏
+ * - 个人表情：切到「收藏」tab / 长按消息「添加到表情」时按需拉
+ */
+export const useFaceStore = defineStore('imFace', () => {
+
+  /** 系统表情包列表（含每个包的 items）；运营管理后台维护 */
+  const facePacks = ref<ImFacePackApi.FacePackUser[]>([])
+  /** 个人表情包列表（用户长按「添加到表情」/ 上传产生） */
+  const faceUserItems = ref<ImFaceUserItemApi.FaceUserItem[]>([])
+
+  /** clear() 时递增；旧账号请求返回后不写入新账号内存 */
+  let storeEpoch = 0
+
+  /**
+   * 系统表情包拉取 promise；ensureFacePackList 内 cache：
+   * - null = 还没拉过，下次调用真发请求
+   * - resolve 后保留对象 = 后续调用 await 立即返回，不再发请求
+   * - reject 后置回 null，让调用方下次重试
+   */
+  let facePacksPromise: null | Promise<void> = null
+  /** 按需拉取系统表情包（已拉过则直接复用 cached promise） */
+  async function ensureFacePackList(): Promise<void> {
+    if (!facePacksPromise) {
+      const requestEpoch = storeEpoch
+      facePacksPromise = apiGetFacePackList()
+        .then((data) => {
+          if (requestEpoch !== storeEpoch) {
+            return
+          }
+          facePacks.value = data || []
+        })
+        .catch((error) => {
+          console.warn('[IM] 拉取表情包失败', error)
+          if (requestEpoch === storeEpoch) {
+            facePacksPromise = null
+          }
+          throw error
+        })
+    }
+    return facePacksPromise
+  }
+
+  /** 个人表情拉取 promise；语义同上 */
+  let faceUserItemsPromise: null | Promise<void> = null
+  /** 按需拉取个人表情（已拉过则直接复用 cached promise） */
+  async function ensureFaceUserItemList(): Promise<void> {
+    if (!faceUserItemsPromise) {
+      const requestEpoch = storeEpoch
+      faceUserItemsPromise = apiGetFaceUserItemList()
+        .then((data) => {
+          if (requestEpoch !== storeEpoch) {
+            return
+          }
+          faceUserItems.value = data || []
+        })
+        .catch((error) => {
+          console.warn('[IM] 拉取个人表情失败', error)
+          if (requestEpoch === storeEpoch) {
+            faceUserItemsPromise = null
+          }
+          throw error
+        })
+    }
+    return faceUserItemsPromise
+  }
+
+  /**
+   * 添加个人表情；服务端对同 URL 抛 FACE_USER_ITEM_DUPLICATED 错误
+   *
+   * 来源：1. 用户在表情面板「+」上传图片  2. 长按消息「添加到表情」
+   */
+  async function addFaceUserItem(reqVO: ImFaceUserItemApi.FaceUserItemSaveReqVO): Promise<boolean> {
+    const requestEpoch = storeEpoch
+    const id = await apiCreateFaceUserItem(reqVO)
+    if (!id) {
+      return false
+    }
+    // 已切账号时跳过旧请求结果
+    if (requestEpoch !== storeEpoch) {
+      return false
+    }
+    // id 不在缓存里才插入；服务端唯一约束兜底了 race，本地理论上不会拿到重复 id
+    if (!faceUserItems.value.some((item) => item.id === id)) {
+      faceUserItems.value.unshift({
+        id,
+        url: reqVO.url,
+        name: reqVO.name,
+        width: reqVO.width,
+        height: reqVO.height
+      })
+    }
+    return true
+  }
+
+  /** 删除个人表情；本地立即移除 */
+  async function removeFaceUserItem(id: number): Promise<boolean> {
+    const requestEpoch = storeEpoch
+    try {
+      await apiDeleteFaceUserItem(id)
+      // 已切账号时跳过旧请求结果
+      if (requestEpoch !== storeEpoch) {
+        return false
+      }
+      faceUserItems.value = faceUserItems.value.filter((item) => item.id !== id)
+      return true
+    } catch (error) {
+      console.warn('[IM] 删除个人表情失败', { id }, error)
+      return false
+    }
+  }
+
+  /** 清空表情缓存 */
+  function clear(): void {
+    facePacks.value = []
+    faceUserItems.value = []
+    facePacksPromise = null
+    faceUserItemsPromise = null
+    storeEpoch++
+  }
+
+  return {
+    facePacks,
+    faceUserItems,
+    ensureFacePackList,
+    ensureFaceUserItemList,
+    addFaceUserItem,
+    removeFaceUserItem,
+    clear
+  }
+})
+
+/** 在 setup 外（路由守卫等）取 store 实例的工具方法 */
+export const useFaceStoreWithOut = () => useFaceStore()
+
+if (import.meta.hot) {
+  import.meta.hot.accept(acceptHMRUpdate(useFaceStore, import.meta.hot))
+}
diff --git a/apps/web-ele/src/views/im/home/store/friendStore.ts b/apps/web-ele/src/views/im/home/store/friendStore.ts
new file mode 100644
index 000000000..bf959b836
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/store/friendStore.ts
@@ -0,0 +1,849 @@
+import type { Friend, FriendLite, FriendRequest } from '../types'
+
+import type { ImFriendApi } from '#/api/im/friend'
+import type { ImFriendRequestApi } from '#/api/im/friend/request'
+
+import { CommonStatusEnum } from '@vben/constants'
+
+import { acceptHMRUpdate, defineStore } from 'pinia'
+
+import { blockFriend as apiBlockFriend, deleteFriend as apiDeleteFriend, getFriend as apiGetFriend, getMyFriendList as apiGetMyFriendList, pullMyFriendList as apiPullMyFriendList, unblockFriend as apiUnblockFriend, updateFriend as apiUpdateFriend } from '#/api/im/friend'
+import { agreeFriendRequest as apiAgreeFriendRequest, applyFriendRequest as apiApplyFriendRequest, getMyFriendRequest as apiGetMyFriendRequest, getMyFriendRequestList as apiGetMyFriendRequestList, pullMyFriendRequestList as apiPullMyFriendRequestList, refuseFriendRequest as apiRefuseFriendRequest } from '#/api/im/friend/request'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { FRIEND_REQUEST_PAGE_SIZE } from '../../utils/config'
+import { ImConversationType, ImFriendRequestHandleResult } from '../../utils/constants'
+import { getDb, StorageKeys } from '../../utils/db'
+import { runIncrementalPull } from '../../utils/pull'
+import { getFriendDisplayName } from '../../utils/user'
+import { useConversationStore } from './conversationStore'
+
+type PendingRequest = { epoch: number; promise: Promise<void>; userId: number; }
+
+/** 当前正在进行的好友列表拉取；多 dispatcher 同时触发时复用同一 Promise，避免雪崩重拉 */
+let pendingFetchFriends: null | PendingRequest = null
+/** 当前正在进行的好友申请列表拉取；多端连续多条申请到达时复用同一 Promise，避免雪崩重拉 */
+let pendingFetchRequests: null | PendingRequest = null
+/** 当前正在进行的「加载更多申请」请求 */
+let pendingLoadMoreRequests: null | PendingRequest = null
+/** 当前正在进行的好友详情请求 */
+const pendingFetchFriendInfos = new Map<string, Promise<void>>()
+
+/** clear() 时递增；旧账号那次还没返回的请求 resolve 后比对一致才写 store，防跨账号数据泄漏 */
+let storeEpoch = 0
+
+/** 构建好友详情请求去重 key */
+function getPendingFriendInfoKey(userId: number, friendUserId: number): string {
+  return `${userId}:${friendUserId}`
+}
+
+/** 好友通知 payload（对齐后端 BaseFriendNotification + 子类裁减后的字段） */
+export interface FriendNotificationPayload {
+  operatorUserId: number
+  friendUserId: number
+  // FRIEND_REQUEST_* 系列：申请记录的核心字段（避免 payload 携带完整 DO）
+  requestId?: number
+  applyContent?: string
+  handleContent?: string
+  addSource?: number
+  // FRIEND_REQUEST_RECEIVED：申请方聚合字段，供前端直推 push 进列表，无需回拉
+  fromNickname?: string
+  fromAvatar?: string
+  // FRIEND_UPDATE：单边属性变更
+  displayName?: string
+  silent?: boolean
+  pinned?: boolean
+  // FRIEND_DELETE：是否级联清理本端相关数据（如私聊会话）
+  clear?: boolean
+}
+
+/**
+ * IM 好友 Store
+ *
+ * 负责：
+ * - 拉取 / 缓存当前登录用户的好友列表 + 申请列表
+ * - 申请-审批流程（apply / agree / refuse）+ 备注 / 免打扰 / 联系人置顶 / 拉黑
+ * - 接收 WebSocket 1201-1210 段位通知，按事件分发到 friendStore 内部各 dispatcher
+ */
+export const useFriendStore = defineStore('imFriendStore', {
+  state: () => ({
+    friends: [] as Friend[],
+    // 仅 fetchFriendList 成功后置位；loadFriendData（IDB）不置位，否则后台 SWR 刷新会被缓存命中跳过
+    loaded: false,
+    /** 我相关的好友申请列表（含我发起的 + 别人加我的；后端按 id 倒序游标分页） */
+    friendRequests: [] as FriendRequest[],
+    /** 是否还有更早的申请记录可加载；返回不满 page size 即置 false */
+    hasMoreFriendRequests: true
+  }),
+
+  getters: {
+    /**
+     * friendUserId → Friend 的 O(1) 索引；从 friends 数组派生，Pinia 在 friends 变化时自动重算
+     *
+     * 消息渲染需要按 senderId 反查发送人头像 / 备注，每条消息渲染都会 getFriend；
+     * 直接 find 时 N 条消息 × M 好友 = O(N×M)；建索引后单次读 O(1)，重建只在写好友（fetchFriendList / upsertFriend 等）时发生
+     */
+    getFriendMap: (state): Map<number, Friend> => {
+      const map = new Map<number, Friend>()
+      for (const friend of state.friends) {
+        map.set(friend.friendUserId, friend)
+      }
+      return map
+    },
+    /** 按 friendUserId 找好友（含已软删的 DISABLE 记录，调用方自行判定） */
+    getFriend(): (friendUserId: number) => Friend | undefined {
+      return (friendUserId: number) => this.getFriendMap.get(friendUserId)
+    },
+    /** 当前生效的好友列表（过滤掉 DISABLE 软删记录） */
+    getActiveFriendList: (state): Friend[] => {
+      return state.friends.filter((friend) => friend.status !== CommonStatusEnum.DISABLE)
+    },
+    /** 当前生效好友的 Lite 视图（PickerPanel / 选人弹窗共用，自带拼音字段供分桶 / 搜索） */
+    getActiveFriendLiteList(): FriendLite[] {
+      return this.getActiveFriendList.map((friend: Friend) => ({
+        id: friend.friendUserId,
+        nickname: friend.nickname,
+        nicknamePinyin: friend.nicknamePinyin,
+        avatar: friend.avatar,
+        displayName: friend.displayName,
+        displayNamePinyin: friend.displayNamePinyin
+      }))
+    },
+    /** 判断对方是否是当前用户的有效好友（存在 + 非 DISABLE） */
+    isActiveFriend() {
+      return (friendUserId: number): boolean => {
+        const entry = this.getFriend(friendUserId)
+        return !!entry && entry.status !== CommonStatusEnum.DISABLE
+      }
+    },
+    /** 我的黑名单（blocked=true 且 ENABLE） */
+    getBlockedFriendList: (state): Friend[] => {
+      return state.friends.filter(
+        (friend) => friend.status !== CommonStatusEnum.DISABLE && friend.blocked === true
+      )
+    },
+    /** 未处理申请数（接收方=我）—— 实时派生，「新的朋友」红点用 */
+    getUnhandledRequestCount: (state): number => {
+      const currentUserId = getCurrentUserId()
+      return state.friendRequests.filter(
+        (request) =>
+          request.handleResult === ImFriendRequestHandleResult.UNHANDLED &&
+          request.toUserId === currentUserId
+      ).length
+    }
+  },
+
+  actions: {
+    // ==================== 本地缓存 ====================
+
+    /** 从 IndexedDB 恢复好友和好友申请 */
+    async loadFriendData(): Promise<boolean> {
+      try {
+        const [friends, friendRequests] = await Promise.all([
+          getDb().getAll<Friend>('friends'),
+          getDb().getAll<FriendRequest>('friendRequests')
+        ])
+        if (friends.length > 0) {
+          this.friends = friends
+        }
+        if (friendRequests.length > 0) {
+          this.friendRequests = friendRequests.toSorted(
+            (requestA, requestB) => requestB.id - requestA.id
+          )
+          this.hasMoreFriendRequests = friendRequests.length >= FRIEND_REQUEST_PAGE_SIZE
+        }
+        return friends.length > 0
+      } catch (error) {
+        console.warn('[IM friendStore] 本地好友缓存读取失败', error)
+        return false
+      }
+    },
+
+    /** 保存好友列表 */
+    saveFriendList(): void {
+      void getDb()
+        .transaction(['friends'], 'readwrite', async (tx) => {
+          const db = getDb()
+          await db.clearStore('friends', tx)
+          for (const friend of this.friends) {
+            if (friend.id) {
+              await db.put('friends', friend, tx)
+            }
+          }
+        })
+        .catch((error) => console.warn('[IM friendStore] 本地好友缓存写入失败', error))
+    },
+
+    /** 保存单个好友 */
+    async saveFriendRecord(friend: Friend | undefined): Promise<void> {
+      if (!friend?.id) {
+        return
+      }
+      await getDb().put('friends', friend)
+    },
+
+    /** 保存单个好友 */
+    saveFriend(friend: Friend | undefined): void {
+      void this.saveFriendRecord(friend).catch((error) =>
+        console.warn('[IM friendStore] 本地好友写入失败', error)
+      )
+    },
+
+    /** 保存好友申请列表 */
+    saveFriendRequestList(): void {
+      void getDb()
+        .transaction(['friendRequests'], 'readwrite', async (tx) => {
+          const db = getDb()
+          await db.clearStore('friendRequests', tx)
+          for (const request of this.friendRequests) {
+            await db.put('friendRequests', request, tx)
+          }
+        })
+        .catch((error) => console.warn('[IM friendStore] 本地好友申请缓存写入失败', error))
+    },
+
+    /** 保存单条好友申请 */
+    async saveFriendRequestRecord(request: FriendRequest | undefined): Promise<void> {
+      if (!request) {
+        return
+      }
+      await getDb().put('friendRequests', request)
+    },
+
+    /** 保存单条好友申请 */
+    saveFriendRequest(request: FriendRequest | undefined): void {
+      void this.saveFriendRequestRecord(request).catch((error) =>
+        console.warn('[IM friendStore] 本地好友申请写入失败', error)
+      )
+    },
+
+    // ==================== 远端拉取 ====================
+
+    /** 从后端拉取并覆盖本地列表（含 DISABLE 历史好友给已删对话兜底）；只同步 ENABLE 的会话信息，DISABLE 的不动 —— cascade 清会话由 WS dispatcher 按 payload.clear 处理，避免 fetchFriendList 覆盖用户「不清空聊天记录」的选择 */
+    async fetchFriendList(force = false) {
+      if (this.loaded && !force) {
+        return
+      }
+      // 快照 epoch；clear() 之后到 .then 之间触发的 epoch++ 表示账号已切，旧结果不能写入新 store
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      if (
+        pendingFetchFriends?.epoch === requestEpoch &&
+        pendingFetchFriends.userId === requestUserId
+      ) {
+        return pendingFetchFriends.promise
+      }
+      const promise = apiGetMyFriendList()
+        .then((list) => {
+          if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+            return
+          }
+          this.friends = (list || []).map((friend) => convertFriend(friend))
+          this.loaded = true
+          const conversationStore = useConversationStore()
+          for (const friend of this.friends) {
+            if (friend.status === CommonStatusEnum.DISABLE) {
+              continue
+            }
+            conversationStore.updateConversation(ImConversationType.PRIVATE, friend.friendUserId, {
+              name: getFriendDisplayName(friend),
+              avatar: friend.avatar,
+              silent: friend.silent
+            })
+          }
+          this.saveFriendList()
+        })
+        .finally(() => {
+          if (
+            pendingFetchFriends?.epoch === requestEpoch &&
+            pendingFetchFriends.userId === requestUserId
+          ) {
+            pendingFetchFriends = null
+          }
+        })
+      pendingFetchFriends = { epoch: requestEpoch, userId: requestUserId, promise }
+      return promise
+    },
+
+    /**
+     * 增量拉取好友变更并合并：进入 IM 首屏主数据恢复（空游标 = 首次全量增量拉）+ 重连 / 离线补偿
+     *
+     * 含已删除好友，按 status 走 upsert
+     */
+    async pullFriends() {
+      // 快照 epoch；账号在拉取途中切换（clear() → epoch++）时丢弃旧账号那几页结果，防跨账号数据泄漏
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      const isActive = () => requestEpoch === storeEpoch && getCurrentUserId() === requestUserId
+      await runIncrementalPull(
+        StorageKeys.settings.friendPullCursor,
+        apiPullMyFriendList,
+        async (records) => {
+          if (!isActive()) {
+            return false
+          }
+          await Promise.all(records.map((vo) => this.upsertFriendForPull(convertFriend(vo))))
+          return true
+        },
+        isActive
+      )
+      // 置 loaded，供通讯录页 fetchFriendList(force=false) 复用缓存而非重复全量拉
+      if (isActive()) {
+        this.loaded = true
+      }
+    },
+
+    /** 按 friendUserId 获取详情并合并到本地（保证 nickname / avatar 最新） */
+    async fetchFriendInfo(friendUserId: number) {
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      if (!requestUserId) {
+        return
+      }
+      const key = getPendingFriendInfoKey(requestUserId, friendUserId)
+      const inflight = pendingFetchFriendInfos.get(key)
+      if (inflight) {
+        return inflight
+      }
+      const promise = (async () => {
+        try {
+          const data = await apiGetFriend(friendUserId)
+          if (!data) {
+            return
+          }
+          // clear() 已切账号：旧请求的好友详情不能再 upsert 进新账号的 friends
+          if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+            return
+          }
+          this.upsertFriend(convertFriend(data))
+        } catch (error) {
+          console.warn('[IM friendStore] fetchFriendInfo 失败', error)
+        }
+      })().finally(() => {
+        if (pendingFetchFriendInfos.get(key) === promise) {
+          pendingFetchFriendInfos.delete(key)
+        }
+      })
+      pendingFetchFriendInfos.set(key, promise)
+      return promise
+    },
+
+    // ==================== 申请-审批 ====================
+
+    /** 发起好友申请：成功后等待对方同意（不直接落地为好友） */
+    async applyFriendRequest(reqVO: ImFriendRequestApi.FriendRequestApplyReqVO): Promise<null | number> {
+      return await apiApplyFriendRequest(reqVO)
+    },
+
+    /** 同意一条好友申请；后端会双向落库 + 推 FRIEND_ADD，本端等通知到达再 upsertFriend */
+    async agreeFriendRequest(requestId: number) {
+      await apiAgreeFriendRequest(requestId)
+      await this.applyHandleResult(requestId, ImFriendRequestHandleResult.AGREED)
+    },
+
+    /** 拒绝一条好友申请 */
+    async refuseFriendRequest(requestId: number, handleContent?: string) {
+      await apiRefuseFriendRequest(requestId, handleContent)
+      await this.applyHandleResult(requestId, ImFriendRequestHandleResult.REFUSED, handleContent)
+    },
+
+    /** 把 handleResult 应用到本地申请记录；找不到就按 id 单查兜底 upsert，避免破坏 id 倒序 */
+    async applyHandleResult(
+      requestId: number,
+      result: number,
+      handleContent?: string
+    ): Promise<void> {
+      const request = this.getFriendRequest(requestId)
+      if (request) {
+        request.handleResult = result
+        if (handleContent !== undefined) {
+          request.handleContent = handleContent
+        }
+        request.handleTime = Date.now()
+        this.saveFriendRequest(request)
+        return
+      }
+      await this.fetchFriendRequest(requestId)
+    },
+
+    /** 拉取「我相关」的好友申请列表首页（页面打开 / 收到 FRIEND_REQUEST_RECEIVED 时刷新）；pending 期间复用同一 Promise */
+    async fetchFriendRequestList() {
+      if (pendingFetchRequests) {
+        const currentUserId = getCurrentUserId()
+        if (
+          pendingFetchRequests.epoch === storeEpoch &&
+          pendingFetchRequests.userId === currentUserId
+        ) {
+          return pendingFetchRequests.promise
+        }
+      }
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      const promise = apiGetMyFriendRequestList(FRIEND_REQUEST_PAGE_SIZE)
+        .then((list) => {
+          if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+            return
+          }
+          const items = (list || []).map((request) => convertFriendRequest(request))
+          this.friendRequests = items
+          // 不足一页即没有更多；满页可能还有，等 loadMore 拉到 0 条再确定
+          this.hasMoreFriendRequests = items.length >= FRIEND_REQUEST_PAGE_SIZE
+          this.saveFriendRequestList()
+        })
+        .finally(() => {
+          if (
+            pendingFetchRequests?.epoch === requestEpoch &&
+            pendingFetchRequests.userId === requestUserId
+          ) {
+            pendingFetchRequests = null
+          }
+        })
+      pendingFetchRequests = { epoch: requestEpoch, userId: requestUserId, promise }
+      return promise
+    },
+
+    /** 加载更多申请（按本地最旧 requestId 游标分页）；无更多 / pending 中直接返回 */
+    async loadMoreFriendRequestList() {
+      const requestUserId = getCurrentUserId()
+      const hasSameFetchPending =
+        pendingFetchRequests?.epoch === storeEpoch && pendingFetchRequests.userId === requestUserId
+      if (!this.hasMoreFriendRequests || hasSameFetchPending) {
+        return
+      }
+      if (
+        pendingLoadMoreRequests?.epoch === storeEpoch &&
+        pendingLoadMoreRequests.userId === requestUserId
+      ) {
+        return pendingLoadMoreRequests.promise
+      }
+      const oldest = this.friendRequests[this.friendRequests.length - 1]
+      if (!oldest) {
+        return this.fetchFriendRequestList()
+      }
+      const requestEpoch = storeEpoch
+      const promise = apiGetMyFriendRequestList(FRIEND_REQUEST_PAGE_SIZE, oldest.id)
+        .then((list) => {
+          if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+            return
+          }
+          const items = (list || []).map((request) => convertFriendRequest(request))
+          this.friendRequests.push(...items)
+          this.hasMoreFriendRequests = items.length >= FRIEND_REQUEST_PAGE_SIZE
+          this.saveFriendRequestList()
+        })
+        .finally(() => {
+          if (
+            pendingLoadMoreRequests?.epoch === requestEpoch &&
+            pendingLoadMoreRequests.userId === requestUserId
+          ) {
+            pendingLoadMoreRequests = null
+          }
+        })
+      pendingLoadMoreRequests = { epoch: requestEpoch, userId: requestUserId, promise }
+      return promise
+    },
+
+    /** 按 id 查申请记录；列表是按 id 倒序的小列表，O(n) find 即可，不再维护 Map 索引 */
+    getFriendRequest(requestId: number): FriendRequest | undefined {
+      return this.friendRequests.find((request) => request.id === requestId)
+    },
+
+    /** 按 id 从后端单查并 upsert 到本地（dispatcher 兜底用，避免全量重拉）；后端带越权过滤 */
+    async fetchFriendRequest(requestId: number) {
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      const data = await apiGetMyFriendRequest(requestId)
+      if (!data) {
+        return
+      }
+      // clear() 已切账号：旧请求的申请记录不能再写进新账号的 friendRequests
+      if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+        return
+      }
+      this.upsertFriendRequest(convertFriendRequest(data))
+    },
+
+    /** 合并单条好友申请：已有则按 id 覆盖；新记录按 id 倒序插入（比本地最旧还老则跳过，留给 loadMore 带回） */
+    upsertFriendRequest(next: FriendRequest) {
+      void this.upsertFriendRequestForPull(next).catch((error) =>
+        console.warn('[IM friendStore] 本地好友申请写入失败', error)
+      )
+    },
+
+    /** 合并单条好友申请 */
+    async upsertFriendRequestForPull(next: FriendRequest): Promise<void> {
+      const existing = this.getFriendRequest(next.id)
+      if (existing) {
+        Object.assign(existing, next)
+        await this.saveFriendRequestRecord(existing)
+        return
+      }
+      // 比本地最旧 id 还老：不入列表，让 loadMore 自然带回，避免破坏 id 倒序 / 后续 loadMore 重复 push
+      const oldest = this.friendRequests[this.friendRequests.length - 1]
+      if (oldest && next.id < oldest.id) {
+        return
+      }
+      // 按 id 倒序找首个比自己小的位置插入；找不到则追加末尾
+      const insertIndex = this.friendRequests.findIndex((request) => request.id < next.id)
+      if (insertIndex === -1) {
+        this.friendRequests.push(next)
+      } else {
+        this.friendRequests.splice(insertIndex, 0, next)
+      }
+      await this.saveFriendRequestRecord(next)
+    },
+
+    /** 增量拉取好友申请变更并合并（重连 / 离线补偿）；按 update_time + id 游标，已处理的按 handleResult 覆盖 */
+    async pullFriendRequests() {
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      const isActive = () => requestEpoch === storeEpoch && getCurrentUserId() === requestUserId
+      await runIncrementalPull(
+        StorageKeys.settings.friendRequestPullCursor,
+        apiPullMyFriendRequestList,
+        async (records) => {
+          if (!isActive()) {
+            return false
+          }
+          await Promise.all(
+            records.map((vo) => this.upsertFriendRequestForPull(convertFriendRequest(vo)))
+          )
+          return true
+        },
+        isActive
+      )
+    },
+
+    // ==================== 好友关系操作 ====================
+
+    /** 删除好友（单向软删，本端置 DISABLE）；clear=true 时级联清理本地相关数据（如私聊会话），并透传后端给多端同步 */
+    async deleteFriend(friendUserId: number, clear: boolean = true) {
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      await apiDeleteFriend(friendUserId, clear)
+      if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+        return
+      }
+      this.removeFriend(friendUserId, clear)
+    },
+
+    /** 切换免打扰：同步会话的 silent 字段，避免会话列表 silent 图标等 1210 推到才更新 */
+    async setFriendSilent(friendUserId: number, silent: boolean) {
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      await apiUpdateFriend({ friendUserId, silent })
+      if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+        return
+      }
+      const friend = this.getFriend(friendUserId)
+      if (friend) {
+        friend.silent = silent
+        const conversationStore = useConversationStore()
+        conversationStore.updateConversation(ImConversationType.PRIVATE, friendUserId, { silent })
+        this.saveFriend(friend)
+      }
+    },
+
+    /** 切换联系人置顶 */
+    async setFriendPinned(friendUserId: number, pinned: boolean) {
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      await apiUpdateFriend({ friendUserId, pinned })
+      if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+        return
+      }
+      const friend = this.getFriend(friendUserId)
+      if (friend) {
+        friend.pinned = pinned
+        this.saveFriend(friend)
+      }
+    },
+
+    /** 拉黑好友：本端乐观更新 + 调接口；后端 FRIEND_BLOCK 推到时由 dispatcher 兜底同步多端 */
+    async blockFriend(friendUserId: number) {
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      await apiBlockFriend(friendUserId)
+      if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+        return
+      }
+      const friend = this.getFriend(friendUserId)
+      if (friend) {
+        friend.blocked = true
+        this.saveFriend(friend)
+      }
+    },
+
+    /** 移出黑名单：本端乐观更新 + 调接口；后端 FRIEND_UNBLOCK 推到时由 dispatcher 兜底同步多端 */
+    async unblockFriend(friendUserId: number) {
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      await apiUnblockFriend(friendUserId)
+      if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+        return
+      }
+      const friend = this.getFriend(friendUserId)
+      if (friend) {
+        friend.blocked = false
+        this.saveFriend(friend)
+      }
+    },
+
+    /** 修改好友展示备注（仅自己可见） */
+    async setFriendDisplayName(friendUserId: number, displayName: string) {
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      const value = displayName.trim()
+      // 后端 displayName 语义：null/undefined = 不改，"" = 清空，所以这里直接传 value（可能是空串）
+      await apiUpdateFriend({ friendUserId, displayName: value })
+      if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+        return
+      }
+      const friend = this.getFriend(friendUserId)
+      if (friend) {
+        friend.displayName = value
+        const conversationStore = useConversationStore()
+        conversationStore.updateConversation(ImConversationType.PRIVATE, friendUserId, {
+          name: getFriendDisplayName(friend)
+        })
+        this.saveFriend(friend)
+      }
+    },
+
+    /** 本地合并 / 新增某个好友（WebSocket 事件 & 手动刷新都用） */
+    upsertFriend(friend: Friend) {
+      void this.upsertFriendForPull(friend).catch((error) =>
+        console.warn('[IM friendStore] 本地好友写入失败', error)
+      )
+    },
+
+    /** 本地合并 / 新增某个好友 */
+    async upsertFriendForPull(friend: Friend): Promise<void> {
+      const index = this.friends.findIndex(
+        (existing) => existing.friendUserId === friend.friendUserId
+      )
+      if (index === -1) {
+        this.friends.push({
+          ...friend,
+          status: friend.status ?? CommonStatusEnum.ENABLE
+        })
+      } else {
+        this.friends[index] = {
+          ...this.friends[index],
+          ...friend,
+          status: friend.status ?? CommonStatusEnum.ENABLE
+        }
+      }
+      const conversationStore = useConversationStore()
+      const merged = this.getFriend(friend.friendUserId)
+      conversationStore.updateConversation(ImConversationType.PRIVATE, friend.friendUserId, {
+        name: merged ? getFriendDisplayName(merged) : friend.nickname,
+        avatar: friend.avatar,
+        silent: friend.silent
+      })
+      await this.saveFriendRecord(merged)
+    },
+
+    /** 本地标记删除（WebSocket FRIEND_DELETE 事件触发；clear=true 时级联清相关数据如私聊会话） */
+    removeFriend(friendUserId: number, clear: boolean = true) {
+      const friend = this.getFriend(friendUserId)
+      if (friend) {
+        // blocked 不动，跟后端 deleteFriend0「删好友期间保留拉黑状态」对齐
+        friend.status = CommonStatusEnum.DISABLE
+        friend.deleteTime = Date.now()
+      }
+      if (clear) {
+        const conversationStore = useConversationStore()
+        conversationStore.removePrivateConversation(friendUserId)
+      }
+      this.saveFriend(friend)
+    },
+
+    // ==================== WebSocket 事件 dispatcher（1201-1210 段） ====================
+
+    /** FRIEND_REQUEST_RECEIVED(1203)：收到新申请；payload 已带申请方昵称 / 头像，按 requestId 直推 push 进列表 */
+    applyFriendRequestReceivedNotification(payload: FriendNotificationPayload) {
+      if (!payload.requestId) {
+        return
+      }
+      const currentUserId = getCurrentUserId()
+      const existingIndex = this.friendRequests.findIndex((item) => item.id === payload.requestId)
+      if (existingIndex !== -1) {
+        const existing = this.friendRequests.splice(existingIndex, 1)[0]
+        if (!existing) {
+          return
+        }
+        const next = {
+          ...existing,
+          fromUserId: payload.operatorUserId,
+          toUserId: currentUserId,
+          handleResult: ImFriendRequestHandleResult.UNHANDLED,
+          applyContent: payload.applyContent,
+          addSource: payload.addSource,
+          createTime: Date.now(),
+          fromNickname: payload.fromNickname,
+          fromAvatar: payload.fromAvatar
+        }
+        this.friendRequests.unshift(next)
+        this.saveFriendRequest(next)
+        return
+      }
+      const next = {
+        id: payload.requestId,
+        fromUserId: payload.operatorUserId,
+        toUserId: currentUserId,
+        handleResult: ImFriendRequestHandleResult.UNHANDLED,
+        applyContent: payload.applyContent,
+        addSource: payload.addSource,
+        createTime: Date.now(),
+        fromNickname: payload.fromNickname,
+        fromAvatar: payload.fromAvatar
+      }
+      this.friendRequests.unshift(next)
+      this.saveFriendRequest(next)
+    },
+
+    /** FRIEND_REQUEST_APPROVED(1201)：我的申请被同意；按 requestId 更新状态（FRIEND_ADD 会另外推） */
+    applyFriendRequestApprovedNotification(payload: FriendNotificationPayload) {
+      if (!payload.requestId) {
+        return
+      }
+      void this.applyHandleResult(payload.requestId, ImFriendRequestHandleResult.AGREED)
+    },
+
+    /** FRIEND_REQUEST_REJECTED(1202)：我的申请被拒绝；按 requestId 更新状态 */
+    applyFriendRequestRejectedNotification(payload: FriendNotificationPayload) {
+      if (!payload.requestId) {
+        return
+      }
+      void this.applyHandleResult(
+        payload.requestId,
+        ImFriendRequestHandleResult.REFUSED,
+        payload.handleContent
+      )
+    },
+
+    /**
+     * FRIEND_ADD(1204)：新增好友；本端拉取好友详情并入库
+     * peerUserId 由 websocketStore 按帧 sender / receiver 算好传入：becomeFriends 单条入库后双方收到同一份 payload，
+     * 本端真正的「对端」是帧上的另一个用户，不是 payload.friendUserId（payload 里固定是 toUserId）。
+     */
+    applyFriendAddNotification(_payload: FriendNotificationPayload, peerUserId: number) {
+      if (this.isActiveFriend(peerUserId)) {
+        return
+      }
+      void this.fetchFriendInfo(peerUserId)
+    },
+
+    /**
+     * FRIEND_DELETE(1205)：好友被删除；本端清理 + 按 payload.clear 决定是否级联清会话（多端跟主操作端一致）
+     * peerUserId 由 websocketStore 按帧 sender / receiver 算好传入；与 FRIEND_ADD 保持一致的 peer 推断
+     */
+    applyFriendDeleteNotification(payload: FriendNotificationPayload, peerUserId: number) {
+      this.removeFriend(peerUserId, payload.clear !== false)
+    },
+
+    /** FRIEND_BLOCK(1207)：拉黑；多端同步 */
+    applyFriendBlockNotification(payload: FriendNotificationPayload) {
+      const friend = this.getFriend(payload.friendUserId)
+      if (friend) {
+        friend.blocked = true
+        this.saveFriend(friend)
+      }
+    },
+
+    /** FRIEND_UNBLOCK(1208)：移出黑名单；多端同步 */
+    applyFriendUnblockNotification(payload: FriendNotificationPayload) {
+      const friend = this.getFriend(payload.friendUserId)
+      if (friend) {
+        friend.blocked = false
+        this.saveFriend(friend)
+      }
+    },
+
+    /** FRIEND_INFO_UPDATED(1209)：好友资料变更（昵称 / 头像）；重拉详情 */
+    applyFriendInfoUpdatedNotification(payload: FriendNotificationPayload) {
+      void this.fetchFriendInfo(payload.friendUserId)
+    },
+
+    /** FRIEND_UPDATE(1210)：批量更新（备注 / 免打扰 / 联系人置顶）；多端同步 */
+    applyFriendUpdateNotification(payload: FriendNotificationPayload) {
+      const friend = this.getFriend(payload.friendUserId)
+      if (!friend) {
+        return
+      }
+      if (payload.displayName != null) {
+        friend.displayName = payload.displayName
+      }
+      if (payload.silent != null) {
+        friend.silent = payload.silent
+      }
+      if (payload.pinned != null) {
+        friend.pinned = payload.pinned
+      }
+      const conversationStore = useConversationStore()
+      conversationStore.updateConversation(ImConversationType.PRIVATE, payload.friendUserId, {
+        name: getFriendDisplayName(friend),
+        silent: friend.silent
+      })
+      this.saveFriend(friend)
+    },
+
+    /** 清空好友内存状态，并废弃未返回请求（pending Promise 置空 + storeEpoch++） */
+    clear() {
+      this.friends = []
+      this.friendRequests = []
+      this.loaded = false
+      this.hasMoreFriendRequests = true
+      pendingFetchFriends = null
+      pendingFetchRequests = null
+      pendingLoadMoreRequests = null
+      pendingFetchFriendInfos.clear()
+      storeEpoch++
+    }
+  }
+})
+
+function convertFriend(vo: ImFriendApi.FriendRespVO): Friend {
+  return {
+    id: vo.id,
+    friendUserId: vo.friendUserId,
+    nickname: vo.nickname || String(vo.friendUserId),
+    nicknamePinyin: vo.nicknamePinyin,
+    avatar: vo.avatar,
+    silent: !!vo.silent,
+    displayName: vo.displayName || '',
+    displayNamePinyin: vo.displayNamePinyin,
+    addSource: vo.addSource,
+    pinned: !!vo.pinned,
+    blocked: !!vo.blocked,
+    status: vo.status,
+    addTime: vo.addTime ? new Date(vo.addTime).getTime() : undefined,
+    deleteTime: vo.deleteTime ? new Date(vo.deleteTime).getTime() : undefined
+  }
+}
+
+function convertFriendRequest(vo: ImFriendRequestApi.FriendRequestRespVO): FriendRequest {
+  return {
+    id: vo.id,
+    fromUserId: vo.fromUserId,
+    toUserId: vo.toUserId,
+    handleResult: vo.handleResult,
+    applyContent: vo.applyContent,
+    handleContent: vo.handleContent,
+    addSource: vo.addSource,
+    handleTime: vo.handleTime ? new Date(vo.handleTime).getTime() : undefined,
+    createTime: vo.createTime ? new Date(vo.createTime).getTime() : 0,
+    fromNickname: vo.fromNickname,
+    fromAvatar: vo.fromAvatar,
+    toNickname: vo.toNickname,
+    toAvatar: vo.toAvatar
+  }
+}
+
+export const useFriendStoreWithOut = () => useFriendStore()
+
+// dev: 让 Pinia 的 actions / state 改动支持 HMR，避免每次改 store 都得硬刷
+if (import.meta.hot) {
+  import.meta.hot.accept(acceptHMRUpdate(useFriendStore, import.meta.hot))
+}
diff --git a/apps/web-ele/src/views/im/home/store/groupRequestStore.ts b/apps/web-ele/src/views/im/home/store/groupRequestStore.ts
new file mode 100644
index 000000000..24ea5dae3
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/store/groupRequestStore.ts
@@ -0,0 +1,242 @@
+import type { ImGroupRequestApi } from '#/api/im/group/request'
+
+import { acceptHMRUpdate, defineStore } from 'pinia'
+
+import { agreeGroupRequest as apiAgreeGroupRequest, getMyGroupRequest as apiGetMyGroupRequest, getUnhandledRequestList as apiGetUnhandledRequestList, pullMyGroupRequestList as apiPullMyGroupRequestList, refuseGroupRequest as apiRefuseGroupRequest } from '#/api/im/group/request'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+import { ImGroupRequestHandleResult } from '#/views/im/utils/constants'
+
+import { getDb, StorageKeys } from '../../utils/db'
+import { runIncrementalPull } from '../../utils/pull'
+
+type PendingRequest = { epoch: number; promise: Promise<void>; userId: number; }
+
+/** clear() 时递增；旧账号 in-flight 的 pullGroupRequests 结果 resolve 后比对一致才写 store，防跨账号红点污染（与 friendStore 同口径） */
+let storeEpoch = 0
+let pendingUnhandledFetch: null | PendingRequest = null
+
+/**
+ * IM 加群申请 Store
+ *
+ * 仅维护「我管理的所有群」下未处理的申请列表（unhandledList）；
+ * 横幅 / Drawer 都从这里派生 count 和分组列表，避免给 ImGroupApi.GroupRespVO 挂 pendingRequestCount 字段
+ *
+ * 数据生命周期：
+ * - 进 IM 后调一次 fetchUnhandledGroupRequestList 拉首页全量
+ * - WebSocket 1503 → 调 addGroupRequestById(requestId) 拉单条 + push 到 unhandledList 头部
+ * - WebSocket 1505 / 1506 → 按 requestId 从 unhandledList 移除
+ * - WebSocket 1517 GROUP_ADMIN_ADD（自己被加为 admin）→ 重新调 fetchUnhandledGroupRequestList
+ * - 本端 agree / refuse 处理后 → 本地按 requestId 移除
+ */
+export const useGroupRequestStore = defineStore('imGroupRequestStore', {
+  state: () => ({
+    /** 我管理的所有群下未处理申请列表（按 id 倒序） */
+    unhandledList: [] as ImGroupRequestApi.GroupRequestRespVO[],
+    /** fetchUnhandledGroupRequestList 是否成功执行过；避免横幅显示 0 然后跳数字的闪烁 */
+    loaded: false
+  }),
+
+  getters: {
+    /**
+     * 各群下未处理申请数的 Map；O(N) 扫一次缓存供 ConversationItem 等 N 处复用，避免 N×M 重复 filter
+     */
+    getUnhandledGroupRequestCountMap(state): Map<number, number> {
+      const map = new Map<number, number>()
+      for (const request of state.unhandledList) {
+        map.set(request.groupId, (map.get(request.groupId) ?? 0) + 1)
+      }
+      return map
+    },
+    /** 指定群下的未处理申请数 */
+    getUnhandledGroupRequestCount(): (groupId: number) => number {
+      return (groupId: number) => this.getUnhandledGroupRequestCountMap.get(groupId) ?? 0
+    },
+    /** 指定群下的未处理申请列表 */
+    getUnhandledGroupRequestListByGroupId:
+      (state) =>
+      (groupId: number): ImGroupRequestApi.GroupRequestRespVO[] =>
+        state.unhandledList.filter((r) => r.groupId === groupId)
+  },
+
+  actions: {
+    /** 从 IndexedDB 恢复加群申请 */
+    async loadGroupRequestList(): Promise<boolean> {
+      try {
+        const cached = await getDb().getAll<ImGroupRequestApi.GroupRequestRespVO>('groupRequests')
+        if (!cached || cached.length === 0) {
+          return false
+        }
+        this.unhandledList = cached
+          .filter((request) => request.handleResult === ImGroupRequestHandleResult.UNHANDLED)
+          .toSorted((requestA, requestB) => requestB.id - requestA.id)
+        return true
+      } catch (error) {
+        console.warn('[IM groupRequestStore] 本地加群申请缓存读取失败', error)
+        return false
+      }
+    },
+
+    /** 保存加群申请列表 */
+    saveGroupRequestList(): void {
+      void getDb()
+        .transaction(['groupRequests'], 'readwrite', async (tx) => {
+          const db = getDb()
+          await db.clearStore('groupRequests', tx)
+          for (const request of this.unhandledList) {
+            await db.put('groupRequests', request, tx)
+          }
+        })
+        .catch((error) => console.warn('[IM groupRequestStore] 本地加群申请缓存写入失败', error))
+    },
+
+    /** 保存单条加群申请 */
+    async saveGroupRequestRecord(request: ImGroupRequestApi.GroupRequestRespVO): Promise<void> {
+      await getDb().put('groupRequests', request)
+    },
+
+    /** 保存单条加群申请 */
+    saveGroupRequest(request: ImGroupRequestApi.GroupRequestRespVO): void {
+      void this.saveGroupRequestRecord(request).catch((error) =>
+        console.warn('[IM groupRequestStore] 本地加群申请写入失败', error)
+      )
+    },
+
+    /** 拉取我管理的所有群下未处理申请；进 IM 后 / 升级 admin 后 / WS 推送有冲突时调用 */
+    async fetchUnhandledGroupRequestList() {
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      if (
+        pendingUnhandledFetch?.epoch === requestEpoch &&
+        pendingUnhandledFetch.userId === requestUserId
+      ) {
+        return pendingUnhandledFetch.promise
+      }
+      const promise = (async () => {
+        const list = await apiGetUnhandledRequestList()
+        if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+          return
+        }
+        this.unhandledList = list || []
+        this.loaded = true
+        this.saveGroupRequestList()
+      })().finally(() => {
+        if (
+          pendingUnhandledFetch?.epoch === requestEpoch &&
+          pendingUnhandledFetch.userId === requestUserId
+        ) {
+          pendingUnhandledFetch = null
+        }
+      })
+      pendingUnhandledFetch = { epoch: requestEpoch, userId: requestUserId, promise }
+      return promise
+    },
+
+    /**
+     * WS 收到 1503：拉最新内容并置顶
+     *
+     * 同一对 group_id, user_id 复用记录时 requestId 不变但 applyContent / inviterUserId 会刷新，所以无条件 fetch + 排到头部
+     */
+    async addGroupRequestById(requestId: number) {
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      const request = await apiGetMyGroupRequest(requestId)
+      if (!request) {
+        return
+      }
+      if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+        return
+      }
+      this.upsertGroupRequest(request)
+    },
+
+    /**
+     * 本地合并 / 新增单条加群申请（WS 推送 & 增量拉取共用）
+     *
+     * 未处理的按 id 去重后置顶；已处理的从未处理列表移除，避免补偿时把已同意 / 拒绝的记录塞回红点
+     */
+    upsertGroupRequest(request: ImGroupRequestApi.GroupRequestRespVO) {
+      void this.upsertGroupRequestForPull(request).catch((error) =>
+        console.warn('[IM groupRequestStore] 本地加群申请写入失败', error)
+      )
+    },
+
+    /** 本地合并 / 新增单条加群申请 */
+    async upsertGroupRequestForPull(request: ImGroupRequestApi.GroupRequestRespVO): Promise<void> {
+      if (request.handleResult !== ImGroupRequestHandleResult.UNHANDLED) {
+        await this.removeGroupRequestByIdForPull(request.id)
+        return
+      }
+      this.unhandledList = [request, ...this.unhandledList.filter((r) => r.id !== request.id)]
+      await this.saveGroupRequestRecord(request)
+    },
+
+    /**
+     * 增量拉取加群申请变更并合并；含已处理的按 handleResult 走移除（已处理 → 从红点列表剔除）
+     *
+     * 只做重连 / 后续离线补偿，不负责首登：首登红点走 fetchUnhandledGroupRequestList（服务端直接过滤未处理，语义更精准、启动更轻）。
+     * 故首次重连时游标为空 = 一次性全量走一遍（已处理记录命中 removeGroupRequestById 为 no-op，红点不受影响），之后增量。
+     */
+    async pullGroupRequests() {
+      // 快照 epoch；账号在拉取途中切换（clear() → epoch++）时丢弃旧账号那几页结果，防跨账号红点污染
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      const isActive = () => requestEpoch === storeEpoch && getCurrentUserId() === requestUserId
+      await runIncrementalPull(
+        StorageKeys.settings.groupRequestPullCursor,
+        apiPullMyGroupRequestList,
+        async (records) => {
+          if (!isActive()) {
+            return false
+          }
+          await Promise.all(records.map((vo) => this.upsertGroupRequestForPull(vo)))
+          return true
+        },
+        isActive
+      )
+      if (isActive()) {
+        this.loaded = true
+      }
+    },
+
+    /** WS 收到 1505 / 1506 或本端处理完一条：按 requestId 从列表移除 */
+    removeGroupRequestById(requestId: number) {
+      this.unhandledList = this.unhandledList.filter((r) => r.id !== requestId)
+      void getDb()
+        .delete('groupRequests', requestId)
+        .catch((error) => console.warn('[IM groupRequestStore] 本地加群申请删除失败', error))
+    },
+
+    /** 删除单条加群申请 */
+    async removeGroupRequestByIdForPull(requestId: number): Promise<void> {
+      this.unhandledList = this.unhandledList.filter((r) => r.id !== requestId)
+      await getDb().delete('groupRequests', requestId)
+    },
+
+    /** 同意申请；本端处理后立即从列表移除，避免被反复点击 */
+    async agreeGroupRequest(requestId: number) {
+      await apiAgreeGroupRequest(requestId)
+      this.removeGroupRequestById(requestId)
+    },
+
+    /** 拒绝申请 */
+    async refuseGroupRequest(requestId: number, handleContent?: string) {
+      await apiRefuseGroupRequest(requestId, handleContent)
+      this.removeGroupRequestById(requestId)
+    },
+
+    /** 清空加群申请内存 */
+    clear() {
+      this.unhandledList = []
+      this.loaded = false
+      // 账号切换：递增 epoch 废弃旧账号 in-flight 的 pullGroupRequests 结果，避免写进新账号红点列表
+      storeEpoch++
+      pendingUnhandledFetch = null
+    }
+  }
+})
+
+export const useGroupRequestStoreWithOut = () => useGroupRequestStore()
+
+if (import.meta.hot) {
+  import.meta.hot.accept(acceptHMRUpdate(useGroupRequestStore, import.meta.hot))
+}
diff --git a/apps/web-ele/src/views/im/home/store/groupStore.ts b/apps/web-ele/src/views/im/home/store/groupStore.ts
new file mode 100644
index 000000000..adacf614f
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/store/groupStore.ts
@@ -0,0 +1,974 @@
+import type { Group, GroupDO, GroupMember, Message } from '../types'
+
+import type { ImGroupApi } from '#/api/im/group'
+import type { ImGroupMemberApi } from '#/api/im/group/member'
+
+import { CommonStatusEnum } from '@vben/constants'
+
+import { acceptHMRUpdate, defineStore } from 'pinia'
+
+import { getGroup as apiGetGroup, getMyGroupList as apiGetMyGroupList } from '#/api/im/group'
+import { getGroupMember as apiGetGroupMember, getGroupMemberList as apiGetGroupMemberList, updateGroupMember as apiUpdateGroupMember } from '#/api/im/group/member'
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import {
+  ImContentType,
+  ImConversationType,
+  ImGroupMemberRole,
+  ImMessageStatus
+} from '../../utils/constants'
+import { getDb } from '../../utils/db'
+import { type GroupNotificationPayload } from '../../utils/message'
+import { getGroupDisplayName } from '../../utils/user'
+import { useConversationStore } from './conversationStore'
+import { useGroupRequestStore } from './groupRequestStore'
+
+/** clear() 时递增；旧账号 in-flight 的成员请求返回后比对一致才写 store */
+let storeEpoch = 0
+
+/**
+ * fetchGroupMemberList 并发去重表：同 groupId 同时进的请求共用一个 Promise
+ *
+ * key 必须带 userId——账号切换时 A 的请求不能被 B 复用，否则 IIFE 内部的 saveGroupMemberList 会把 A 的成员数据写进 B 的 IDB 桶
+ */
+const pendingMemberFetches = new Map<string, Promise<GroupMember[]>>()
+const pendingMemberKey = (userId: number, groupId: number) => `${userId}:${groupId}`
+
+/**
+ * fetchGroupMember 单成员并发去重表：同 (groupId, memberUserId) 同时进的请求共用一个 Promise
+ *
+ * 跟整群表分开：单成员 fetch 跟整群 fetch 语义不同（单成员不回填 me 的 silent），不能互相代替
+ */
+const pendingSingleMemberFetches = new Map<string, Promise<GroupMember | null>>()
+
+const pendingSingleMemberKey = (userId: number, groupId: number, memberUserId: number) =>
+  `${userId}:${groupId}:${memberUserId}`
+
+/** 构建群 IndexedDB 记录 */
+function buildGroupDO(group: Group): GroupDO {
+  const {
+    members: _members,
+    membersLoaded: _membersLoaded,
+    membersExpired: _membersExpired,
+    ...record
+  } = group
+  return record
+}
+
+/** 判断当前用户是否在 payload.memberUserIds 里（GROUP_CREATE / INVITE / KICK 自判用） */
+function isSelfInPayloadMembers(payload: GroupNotificationPayload): boolean {
+  const selfUserId = getCurrentUserId()
+  return !!selfUserId && (payload.memberUserIds || []).includes(selfUserId)
+}
+
+/** 刷新我管理的群申请红点 */
+function refreshUnhandledGroupRequests(): void {
+  useGroupRequestStore()
+    .fetchUnhandledGroupRequestList()
+    .catch(() => undefined)
+}
+
+/**
+ * IM 群 Store
+ *
+ * 负责：
+ * - 拉取 / 缓存当前登录用户加入的群列表
+ * - 按 groupId 懒加载群成员（供 ConversationGroupSide / MentionPicker / MessageReadStatus 消费）
+ * - 成员"已读 / 未读"等聚合查询由 MessageReadStatus 另行组合
+ */
+export const useGroupStore = defineStore('imGroupStore', {
+  state: () => ({
+    groups: [] as Group[],
+    loaded: false, // 仅 fetchGroupList 成功后置位；loadGroupList（IDB）不置位，否则后台 SWR 刷新会被缓存命中跳过
+    groupMembersExpired: false // 进入 IM / 重连后置位；IDB 里的成员桶延迟加载到内存时，也要按过期处理
+  }),
+
+  getters: {
+    getGroup:
+      (state) =>
+      (id: number): Group | undefined => {
+        return state.groups.find((g) => g.id === id)
+      },
+    /** 群成员 userId → GroupMember 索引；调用方按 userId 反查昵称 / 头像等元信息 */
+    getGroupMemberMap:
+      (state) =>
+      (id: number): Map<number, GroupMember> => {
+        const group = state.groups.find((g) => g.id === id)
+        return new Map((group?.members || []).map((m) => [m.userId, m]))
+      }
+  },
+
+  actions: {
+    // ==================== 本地缓存 ====================
+
+    /** 从 IndexedDB 恢复群列表 */
+    async loadGroupList(): Promise<boolean> {
+      try {
+        const cached = await getDb().getAll<GroupDO>('groups')
+        if (!cached || cached.length === 0) {
+          return false
+        }
+        this.groups = cached
+        return true
+      } catch (error) {
+        console.warn('[IM groupStore] 本地群缓存读取失败', error)
+        return false
+      }
+    },
+
+    /** 保存群列表 */
+    saveGroupList(): void {
+      void getDb()
+        .transaction(['groups'], 'readwrite', async (tx) => {
+          const db = getDb()
+          await db.clearStore('groups', tx)
+          for (const group of this.groups) {
+            await db.put('groups', buildGroupDO(group), tx)
+          }
+        })
+        .catch((error) => console.warn('[IM groupStore] 本地群缓存写入失败', error))
+    },
+
+    /** 保存单个群 */
+    async saveGroupRecord(group: Group | undefined): Promise<void> {
+      if (!group) {
+        return
+      }
+      await getDb().put('groups', buildGroupDO(group))
+    },
+
+    /** 保存单个群 */
+    saveGroup(group: Group | undefined): void {
+      void this.saveGroupRecord(group).catch((error) =>
+        console.warn('[IM groupStore] 本地群写入失败', error)
+      )
+    },
+
+    /** 从 IndexedDB 恢复指定群成员 */
+    async loadGroupMemberList(groupId: number): Promise<GroupMember[] | null> {
+      // in-memory 已"完整"加载（fetchGroupMemberList 跑过或上次冷启动从 IDB 整桶恢复过）：直接复用；
+      // 单成员补齐（fetchGroupMember）写进的 partial members 不在此返回缓存——其 membersLoaded=false
+      const cachedGroup = this.getGroup(groupId)
+      if (cachedGroup?.members && cachedGroup.membersLoaded) {
+        return cachedGroup.members
+      }
+      try {
+        const cached = await getDb().getAllByIndex<GroupMember>(
+          'groupMembers',
+          'groupId',
+          groupId
+        )
+        if (!cached || cached.length === 0) {
+          return null
+        }
+        // 把 IDB 拿到的成员落到对应 group
+        const group = this.getGroup(groupId)
+        if (group) {
+          group.members = cached
+          group.memberCount = cached.length
+          group.membersLoaded = true
+          group.membersExpired = this.groupMembersExpired
+        } else {
+          // group 还没就位：仅 in-memory 占位（name='' 表示未知），不调 upsertGroup —— 避免把假名灌进 conversation.name + groups IDB 桶；
+          // 后续，等 fetchGroupList 浅合并时，被真名覆盖
+          this.groups.push({
+            id: groupId,
+            name: '',
+            members: cached,
+            memberCount: cached.length,
+            membersLoaded: true,
+            membersExpired: this.groupMembersExpired
+          })
+        }
+        return cached
+      } catch (error) {
+        console.warn('[IM groupStore] 本地群成员缓存读取失败', { groupId }, error)
+        return null
+      }
+    },
+
+    /** 保存指定群成员 */
+    saveGroupMemberList(groupId: number): void {
+      const members = this.getGroup(groupId)?.members
+      if (!members) {
+        return
+      }
+      void getDb()
+        .transaction(['groupMembers'], 'readwrite', async (tx) => {
+          const db = getDb()
+          await db.deleteByIndex('groupMembers', 'groupId', groupId, tx)
+          for (const member of members) {
+            if (member.id) {
+              await db.put('groupMembers', member, tx)
+            }
+          }
+        })
+        .catch((error) =>
+          console.warn(`[IM groupStore] 本地群成员缓存写入失败 (groupId=${groupId})`, error)
+        )
+    },
+
+    // ==================== 远端拉取 ====================
+
+    /** 拉取群列表；同步刷新对应群聊会话的展示名 / 头像 + 落 IDB */
+    async fetchGroupList(force = false) {
+      if (this.loaded && !force) {
+        return
+      }
+      const requestEpoch = storeEpoch
+      const requestUserId = getCurrentUserId()
+      // 拉取当前登录用户加入的所有群（不带成员；成员按需再走 fetchGroupMemberList）
+      const list = await apiGetMyGroupList()
+      if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+        return
+      }
+      const fresh = (list || []).map((group) => convertGroup(group))
+      // 合并而非全量替换：成员缓存只在成员列表接口维护，群个人设置以群列表接口为准
+      const groupMap = new Map(this.groups.map((group) => [group.id, group]))
+      this.groups = fresh.map((group) => {
+        const existing = groupMap.get(group.id)
+        if (!existing) {
+          return group
+        }
+        return {
+          ...group,
+          members: existing.members,
+          memberCount: existing.memberCount ?? group.memberCount,
+          membersLoaded: existing.membersLoaded,
+          membersExpired: existing.membersExpired
+        }
+      })
+      this.loaded = true
+      const conversationStore = useConversationStore()
+      for (const group of this.groups) {
+        conversationStore.updateConversation(ImConversationType.GROUP, group.id, {
+          name: getGroupDisplayName(group),
+          avatar: group.avatar,
+          silent: group.silent
+        })
+      }
+      this.saveGroupList()
+      this.preloadMembersForEmptyAvatarGroups()
+    },
+
+    /** 预加载空群头像的成员列表，供 GroupAvatar 异步合成群头像 */
+    preloadMembersForEmptyAvatarGroups() {
+      for (const group of this.groups) {
+        if (
+          group.avatar ||
+          group.joinStatus === CommonStatusEnum.DISABLE ||
+          (group.membersLoaded && !group.membersExpired && group.members?.length)
+        ) {
+          continue
+        }
+        const force = !!group.membersLoaded && !group.membersExpired && !group.members?.length
+        this.fetchGroupMemberList(group.id, force).catch((error) => {
+          console.warn('[IM groupStore] 预加载群头像成员失败', { groupId: group.id }, error)
+        })
+      }
+    },
+
+    /** 失效全部群成员缓存 */
+    markAllGroupMembersExpired() {
+      this.groupMembersExpired = true
+      for (const group of this.groups) {
+        if (group.membersLoaded) {
+          group.membersExpired = true
+        }
+      }
+    },
+
+    /** 失效指定群成员缓存 */
+    markGroupMembersExpired(groupId: number) {
+      const group = this.getGroup(groupId)
+      if (group?.membersLoaded) {
+        group.membersExpired = true
+      }
+    },
+
+    /** 单群刷新：用 /im/group/get 拉一份最新元数据再 upsert，常用于 GROUP_UPDATE 推送后或手动 reload */
+    async fetchGroupInfo(groupId: number) {
+      try {
+        const data = await apiGetGroup(groupId)
+        if (!data) {
+          return
+        }
+        this.upsertGroup(convertGroup(data))
+      } catch (error) {
+        console.warn('[IM groupStore] fetchGroupInfo 失败', error)
+      }
+    },
+
+    /** 按群拉取成员（in-memory 缓存 + 并发去重，force=true 强刷）+ 落 IDB */
+    fetchGroupMemberList(groupId: number, force = false): Promise<GroupMember[]> {
+      // in-memory "完整"加载过才命中——单成员补齐写入的 partial members 不在此返回（membersLoaded=false）
+      const cached = this.getGroup(groupId)
+      if (cached && cached.members && cached.membersLoaded && !cached.membersExpired && !force) {
+        return Promise.resolve(cached.members)
+      }
+      // 未登录：不发起请求也不登记 in-flight，避免污染单飞表
+      const requestUserId = getCurrentUserId()
+      if (!requestUserId) {
+        return Promise.resolve([])
+      }
+      const requestEpoch = storeEpoch
+      // 同 (userId, groupId) 已经有正在飞的请求：直接复用，避免重复打接口
+      const key = pendingMemberKey(requestUserId, groupId)
+      const inflight = pendingMemberFetches.get(key)
+      if (inflight) {
+        return inflight
+      }
+      const promise = (async () => {
+        // 拉接口 + 单 pass 转换：同时捕获 me 的原始 VO，给下面回填 user-per-group 字段（silent / groupRemark）用
+        const list = await apiGetGroupMemberList(groupId)
+        if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+          return []
+        }
+        let meRaw: ImGroupMemberApi.GroupMemberRespVO | undefined
+        const members = (list || []).map((member) => {
+          if (member.userId === requestUserId) {
+            meRaw = member
+          }
+          return convertGroupMember(member, groupId)
+        })
+        const silent = !!meRaw?.silent
+        const groupRemark = meRaw?.groupRemark || ''
+
+        // 必须 await 之后重新 getGroup，避免 fetchGroupList 已并发写入真实 group 的 race
+        const group = this.getGroup(groupId)
+        const isPlaceholder = !group
+        let groupFieldsChanged = false
+        if (group) {
+          group.members = members
+          group.memberCount = members.length
+          group.membersLoaded = true
+          group.membersExpired = false
+          // silent / groupRemark 任一变化才同步到 conversation 和 IDB；groupRemark 变化要顺带刷会话名
+          if (group.silent !== silent || group.groupRemark !== groupRemark) {
+            group.silent = silent
+            group.groupRemark = groupRemark
+            groupFieldsChanged = true
+            const conversationStore = useConversationStore()
+            conversationStore.updateConversation(ImConversationType.GROUP, groupId, {
+              name: getGroupDisplayName(group),
+              silent
+            })
+          }
+        } else {
+          // group 还没就位：仅 in-memory push 占位（name='' 表示未知），不调 upsertGroup——避免把假名灌进 conversation.name + groups IDB 桶；
+          // 后续，等 fetchGroupList 浅合并时，被真名覆盖
+          this.groups.push({
+            id: groupId,
+            name: '',
+            members,
+            memberCount: members.length,
+            silent,
+            groupRemark,
+            membersLoaded: true,
+            membersExpired: false
+          })
+        }
+
+        // groups 桶仅在 user-per-group 字段实际变化时写——避免一次批量进群引发多次整桶重写
+        this.saveGroupMemberList(groupId)
+        if (!isPlaceholder && groupFieldsChanged) {
+          this.saveGroup(group)
+        }
+        return members
+        // 无论成功 / 失败都要从单飞表清掉，否则后续同 group 请求永远拿到这个 stale Promise
+      })().finally(() => pendingMemberFetches.delete(key))
+
+      // 把 Promise 登记进单飞表，让此后短时间内的同 (userId, groupId) 请求复用
+      pendingMemberFetches.set(key, promise)
+      return promise
+    },
+
+    /**
+     * 按 (groupId, memberUserId) 单成员补齐——deriveLastSenderDisplayName 兜底场景用
+     *
+     * 跟 fetchGroupMemberList 区别：只拉这一个成员，不动 me 的 silent / groupRemark（不是 me 的话拿不到）；
+     * 命中时把成员 upsert 进 group.members 数组并落 IDB，让后续渲染能用 displayUserName
+     */
+    fetchGroupMember(groupId: number, memberUserId: number): Promise<GroupMember | null> {
+      // in-memory 命中直接返回，不打接口
+      const cached = this.getGroup(groupId)?.members?.find((m) => m.userId === memberUserId)
+      if (cached) {
+        return Promise.resolve(cached)
+      }
+      // 未登录：不发起请求也不登记 in-flight，避免污染单飞表
+      const requestUserId = getCurrentUserId()
+      if (!requestUserId) {
+        return Promise.resolve(null)
+      }
+      const requestEpoch = storeEpoch
+      // 同 (userId, groupId, memberUserId) 已经有正在飞的请求：直接复用
+      const key = pendingSingleMemberKey(requestUserId, groupId, memberUserId)
+      const inflight = pendingSingleMemberFetches.get(key)
+      if (inflight) {
+        return inflight
+      }
+      const promise = (async () => {
+        const data = await apiGetGroupMember(groupId, memberUserId)
+        if (!data) {
+          return null
+        }
+        if (requestEpoch !== storeEpoch || getCurrentUserId() !== requestUserId) {
+          return null
+        }
+        const member = convertGroupMember(data, groupId)
+        // 把这一条 upsert 进 group.members 仅供 in-memory 渲染兜底；group 还没就位则用 placeholder
+        // 注意：不写 IDB——成员桶语义是"全量"，存"1 人桶"会污染下次冷启动的 loadGroupMemberList
+        const group = this.getGroup(groupId)
+        if (group) {
+          const memberList = group.members ?? []
+          const index = memberList.findIndex((m) => m.userId === memberUserId)
+          if (index === -1) {
+            memberList.push(member)
+          } else {
+            memberList[index] = member
+          }
+          group.members = memberList
+        } else {
+          // memberCount 不设：后续 fetchGroupList 合并 `existing.memberCount ?? fresh.memberCount` 时，
+          // 占位值会顶替真实值（fresh 不带 memberCount），等 fetchGroupMemberList 跑过才能拿到真实数
+          this.groups.push({
+            id: groupId,
+            name: '',
+            members: [member]
+          })
+        }
+        return member
+      })().finally(() => pendingSingleMemberFetches.delete(key))
+      pendingSingleMemberFetches.set(key, promise)
+      return promise
+    },
+
+    /** 按 id 插入或合并群（命中则浅合并保留旧字段，未命中则追加），同步把展示名 / 头像 / 免打扰推到对应会话 */
+    upsertGroup(group: Group) {
+      void this.upsertGroupAndSave(group).catch((error) =>
+        console.warn('[IM groupStore] 本地群写入失败', error)
+      )
+    },
+
+    /** 按 id 插入或合并群 */
+    async upsertGroupAndSave(group: Group): Promise<void> {
+      const index = this.groups.findIndex((g) => g.id === group.id)
+      if (index === -1) {
+        this.groups.push(group)
+      } else {
+        this.groups[index] = { ...this.groups[index], ...group }
+      }
+      // 同步推到 conversation：群名 / 头像 / 免打扰是会话列表展示用的，必须紧随 group 变更
+      const merged = this.getGroup(group.id) ?? group
+      const conversationStore = useConversationStore()
+      conversationStore.updateConversation(ImConversationType.GROUP, group.id, {
+        name: getGroupDisplayName(merged),
+        avatar: merged.avatar,
+        silent: merged.silent
+      })
+      // 持久化到 IDB（fire-and-forget）
+      await this.saveGroupRecord(merged)
+    },
+
+    /** 本地移除群缓存和群会话；群解散（GROUP_DEL）、退群、被踢都复用 */
+    removeGroup(id: number) {
+      // 本地硬删（区别于好友删除的软删保留记录）；级联清群聊会话避免列表里留死群
+      this.groups = this.groups.filter((g) => g.id !== id)
+      const conversationStore = useConversationStore()
+      conversationStore.removeGroupConversation(id)
+      void getDb()
+        .transaction(['groups', 'groupMembers'], 'readwrite', async (tx) => {
+          const db = getDb()
+          await db.delete('groups', id, tx)
+          await db.deleteByIndex('groupMembers', 'groupId', id, tx)
+        })
+        .catch((error) => console.warn(`[IM groupStore] 群缓存删除失败 (groupId=${id})`, error))
+    },
+
+    /** 切换免打扰：推后端 + 落本地 + 同步会话列表的 silent，避免 silent 图标 / 总未读 / 提示音判断与设置漂移；和 friendStore.setFriendSilent 对齐 */
+    async setGroupSilent(id: number, silent: boolean) {
+      await apiUpdateGroupMember({ groupId: id, silent })
+      const group = this.getGroup(id)
+      if (!group) {
+        return
+      }
+      group.silent = silent
+      const conversationStore = useConversationStore()
+      conversationStore.updateConversation(ImConversationType.GROUP, id, { silent })
+      this.saveGroup(group)
+    },
+
+    /** 批量更新群成员角色；本地不命中则忽略，等 fetchGroupMemberList 兜底 */
+    updateGroupMemberRoleList(groupId: number, userIds: number[], role: number) {
+      const group = this.getGroup(groupId)
+      if (!group?.members?.length) {
+        return
+      }
+      // 命中目标且角色已变化才标记 changed，避免无变化时整数组重建触发响应式
+      const idSet = new Set(userIds)
+      let changed = false
+      const newMembers = group.members.map((member) => {
+        if (!idSet.has(member.userId) || member.role === role) {
+          return member
+        }
+        changed = true
+        return { ...member, role }
+      })
+      // 有变化才整组替换，让响应式只在真有更新时通知下游
+      if (changed) {
+        group.members = newMembers
+        this.saveGroupMemberList(groupId)
+      }
+    },
+
+    /** 群主转让：群表 ownerUserId 改为新值；旧群主 role → NORMAL；新群主 role → OWNER */
+    transferGroupOwner(groupId: number, oldOwnerId: number, newOwnerId: number) {
+      const group = this.getGroup(groupId)
+      if (!group) {
+        return
+      }
+      if (group.ownerUserId !== newOwnerId) {
+        group.ownerUserId = newOwnerId
+      }
+      this.updateGroupMemberRoleList(groupId, [oldOwnerId], ImGroupMemberRole.NORMAL)
+      this.updateGroupMemberRoleList(groupId, [newOwnerId], ImGroupMemberRole.OWNER)
+      this.saveGroup(group)
+    },
+
+    /** 本地剔除群成员（GROUP_MEMBER_QUIT / KICK 事件）；不命中则等 fetchGroupMemberList 兜底 */
+    removeLocalGroupMemberList(groupId: number, userIds: number[]) {
+      const group = this.getGroup(groupId)
+      if (!group?.members?.length || userIds.length === 0) {
+        return
+      }
+      const idSet = new Set(userIds)
+      const next = group.members.filter((member) => !idSet.has(member.userId))
+      if (next.length === group.members.length) {
+        return
+      }
+      group.members = next
+      group.memberCount = next.length
+      this.saveGroupMemberList(groupId)
+    },
+
+    /** 本地更新群成员的 status（自己退群 / 被踢的本地预置；让 isMember 立即收敛到 stranger，不依赖 removeGroup 的整群移除） */
+    updateGroupMemberStatus(groupId: number, userId: number, status: number) {
+      const group = this.getGroup(groupId)
+      const member = group?.members?.find((m) => m.userId === userId)
+      if (!member || member.status === status) {
+        return
+      }
+      member.status = status
+      this.saveGroupMemberList(groupId)
+    },
+
+    /** 本地更新群成员的 displayUserName（GROUP_MEMBER_NICKNAME_UPDATE 事件）；不命中则等 fetchGroupMemberList 兜底 */
+    updateGroupMemberDisplayUserName(groupId: number, userId: number, displayUserName: string) {
+      const group = this.getGroup(groupId)
+      const member = group?.members?.find((m) => m.userId === userId)
+      if (!member || member.displayUserName === displayUserName) {
+        return
+      }
+      member.displayUserName = displayUserName
+      this.saveGroupMemberList(groupId)
+    },
+
+    /** 局部更新群字段（name / notice / avatar 等）；未命中本地缓存时静默忽略，等 fetchGroupList 兜底；新值跟旧值都相同时跳过响应式 + IDB 写 */
+    updateGroupFields(groupId: number, fields: Partial<Group>) {
+      const group = this.getGroup(groupId)
+      if (!group) {
+        return
+      }
+      const changed = (Object.keys(fields) as (keyof Group)[]).some((k) => group[k] !== fields[k])
+      if (!changed) {
+        return
+      }
+      Object.assign(group, fields)
+      const conversationStore = useConversationStore()
+      conversationStore.updateConversation(ImConversationType.GROUP, groupId, {
+        name: getGroupDisplayName(group),
+        avatar: group.avatar,
+        silent: group.silent
+      })
+      this.saveGroup(group)
+    },
+
+    /**
+     * 接收 GROUP_* 群广播事件，按 type 分发到对应私有 action
+     *
+     * WebSocket 实时收走 messageStore.insertMessage 旁路调用
+     * store 里没缓存的群静默忽略，等 fetchGroupList 兜底
+     */
+    applyGroupNotification(groupId: number, type: number, content?: string) {
+      if (!groupId) {
+        return
+      }
+      let payload: GroupNotificationPayload
+      try {
+        payload = content ? JSON.parse(content) : {}
+      } catch (error) {
+        console.warn(
+          '[IM groupStore] applyGroupNotification 解析 content 失败',
+          { groupId, type, contentLength: content?.length ?? 0 },
+          error
+        )
+        return
+      }
+      switch (type) {
+        case ImContentType.GROUP_ADMIN_ADD: {
+          this.updateGroupMemberRoleList(
+            groupId,
+            payload.memberUserIds || [],
+            ImGroupMemberRole.ADMIN
+          )
+          this.markGroupMembersExpired(groupId)
+          // 自己被加为管理员，原本看不到的群下未处理申请现在变可见，重新拉一次 unhandledList
+          if (isSelfInPayloadMembers(payload)) {
+            refreshUnhandledGroupRequests()
+          }
+          break
+        }
+        case ImContentType.GROUP_ADMIN_REMOVE: {
+          this.updateGroupMemberRoleList(
+            groupId,
+            payload.memberUserIds || [],
+            ImGroupMemberRole.NORMAL
+          )
+          this.markGroupMembersExpired(groupId)
+          if (isSelfInPayloadMembers(payload)) {
+            refreshUnhandledGroupRequests()
+          }
+          break
+        }
+        case ImContentType.GROUP_BANNED: {
+          this.updateGroupFields(groupId, { banned: !!payload.banned })
+          break
+        }
+        case ImContentType.GROUP_CANCEL_MUTED: {
+          this.updateGroupFields(groupId, { mutedAll: false })
+          break
+        }
+        case ImContentType.GROUP_CREATE: {
+          this.applyGroupCreateNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_DISSOLVE: {
+          this.removeGroup(groupId)
+          break
+        }
+        case ImContentType.GROUP_INFO_UPDATE: {
+          this.applyGroupInfoUpdateNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_MEMBER_CANCEL_MUTED: {
+          this.applyGroupMemberCancelMutedNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_MEMBER_ENTER: {
+          this.applyGroupMemberEnterNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_MEMBER_INVITE: {
+          this.applyGroupMemberInviteNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_MEMBER_KICK: {
+          this.applyGroupMemberKickNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_MEMBER_MUTED: {
+          this.applyGroupMemberMutedNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_MEMBER_NICKNAME_UPDATE: {
+          this.applyGroupMemberNicknameUpdateNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_MEMBER_QUIT: {
+          this.applyGroupMemberQuitNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_MESSAGE_PIN: {
+          this.applyGroupMessagePinNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_MESSAGE_UNPIN: {
+          this.applyGroupMessageUnpinNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_MUTED: {
+          this.updateGroupFields(groupId, { mutedAll: true })
+          break
+        }
+        case ImContentType.GROUP_NAME_UPDATE: {
+          this.applyGroupNameUpdateNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_NOTICE_UPDATE: {
+          this.applyGroupNoticeUpdateNotification(groupId, payload)
+          break
+        }
+        case ImContentType.GROUP_OWNER_TRANSFER: {
+          this.applyGroupOwnerTransferNotification(groupId, payload)
+          break
+        }
+      }
+    },
+
+    /** 创建群广播：群未就位时拉群详情 */
+    async applyGroupCreateNotification(groupId: number, payload: GroupNotificationPayload) {
+      if (!isSelfInPayloadMembers(payload)) {
+        return
+      }
+      const selfUserId = getCurrentUserId()
+      const selfIsOperator = !!selfUserId && payload.operatorUserId === selfUserId
+      if (selfIsOperator && this.getGroup(groupId)) {
+        return
+      }
+      await this.fetchGroupInfo(groupId)
+    },
+
+    /** 群名变更：按 newName 局部更新本地群名 */
+    applyGroupNameUpdateNotification(groupId: number, payload: GroupNotificationPayload) {
+      if (payload.newName) {
+        this.updateGroupFields(groupId, { name: payload.newName })
+      }
+    },
+
+    /** 群公告变更：按 newNotice 局部更新（允许空串作为「清空公告」） */
+    applyGroupNoticeUpdateNotification(groupId: number, payload: GroupNotificationPayload) {
+      this.updateGroupFields(groupId, { notice: payload.newNotice ?? '' })
+    },
+
+    /** 群信息变更（NAME / NOTICE 之外字段，当前承载头像变更） */
+    applyGroupInfoUpdateNotification(groupId: number, payload: GroupNotificationPayload) {
+      const fields: Partial<Group> = {}
+      if (payload.newAvatar) {
+        fields.avatar = payload.newAvatar
+      }
+      if (Object.keys(fields).length > 0) {
+        this.updateGroupFields(groupId, fields)
+      }
+    },
+
+    /** 成员加入：被邀请者本端 group 未就位先 fetchGroupInfo 初次拉取；所有人都刷成员列表（新成员 nickname / avatar 不在 payload） */
+    async applyGroupMemberInviteNotification(groupId: number, payload: GroupNotificationPayload) {
+      // 自己刚被拉进来：必须 await fetchGroupInfo 让群入 state.groups，否则 fetchGroupMemberList 的 guard 会兜空
+      if (isSelfInPayloadMembers(payload) && !this.getGroup(groupId)) {
+        await this.fetchGroupInfo(groupId)
+      }
+      this.markGroupMembersExpired(groupId)
+      this.fetchGroupMemberList(groupId, true).catch(() => undefined)
+    },
+
+    /** 自由进群：进群者本端 group 未就位先 fetchGroupInfo 初次拉取；所有人都刷成员列表 */
+    async applyGroupMemberEnterNotification(groupId: number, payload: GroupNotificationPayload) {
+      const selfUserId = getCurrentUserId()
+      // 自己自由进群：必须 await fetchGroupInfo 让群入 state.groups，否则 fetchGroupMemberList 的 guard 会兜空
+      if (selfUserId && payload.entrantUserId === selfUserId && !this.getGroup(groupId)) {
+        await this.fetchGroupInfo(groupId)
+      }
+      this.markGroupMembersExpired(groupId)
+      this.fetchGroupMemberList(groupId, true).catch(() => undefined)
+    },
+
+    /** 成员退群：退群者本人先把 self.status 置 DISABLE 再 removeGroup（保留状态语义 + 维持 groups 列表干净）；其他成员从本地列表移除 quitter */
+    applyGroupMemberQuitNotification(groupId: number, payload: GroupNotificationPayload) {
+      const selfUserId = getCurrentUserId()
+      if (selfUserId && payload.operatorUserId === selfUserId) {
+        this.updateGroupMemberStatus(groupId, selfUserId, CommonStatusEnum.DISABLE)
+        this.removeGroup(groupId)
+      } else if (payload.operatorUserId) {
+        this.removeLocalGroupMemberList(groupId, [payload.operatorUserId])
+        this.markGroupMembersExpired(groupId)
+      }
+    },
+
+    /** 成员被移出：被踢者本人先把 self.status 置 DISABLE 再 removeGroup；其他成员从本地列表移除被踢者 */
+    applyGroupMemberKickNotification(groupId: number, payload: GroupNotificationPayload) {
+      const memberIds = payload.memberUserIds || []
+      const selfUserId = getCurrentUserId()
+      if (isSelfInPayloadMembers(payload)) {
+        if (selfUserId) {
+          this.updateGroupMemberStatus(groupId, selfUserId, CommonStatusEnum.DISABLE)
+        }
+        this.removeGroup(groupId)
+      } else if (memberIds.length > 0) {
+        this.removeLocalGroupMemberList(groupId, memberIds)
+        this.markGroupMembersExpired(groupId)
+      }
+    },
+
+    /** 成员昵称变更：按 operatorUserId 局部更新对应 member.displayUserName */
+    applyGroupMemberNicknameUpdateNotification(groupId: number, payload: GroupNotificationPayload) {
+      if (payload.operatorUserId) {
+        this.updateGroupMemberDisplayUserName(
+          groupId,
+          payload.operatorUserId,
+          payload.displayUserName ?? ''
+        )
+        this.markGroupMembersExpired(groupId)
+      }
+    },
+
+    /** 群主转让：旧群主 → NORMAL，新群主 → OWNER；新群主自己侧重新拉申请列表 */
+    applyGroupOwnerTransferNotification(groupId: number, payload: GroupNotificationPayload) {
+      if (payload.operatorUserId && payload.newOwnerUserId) {
+        this.transferGroupOwner(groupId, payload.operatorUserId, payload.newOwnerUserId)
+        this.markGroupMembersExpired(groupId)
+      }
+      // 自己接管群主：原本看不到的群下未处理申请现在变可见，重新拉一次 unhandledList
+      const selfUserId = getCurrentUserId()
+      if (selfUserId && payload.newOwnerUserId === selfUserId) {
+        refreshUnhandledGroupRequests()
+      } else if (selfUserId && payload.operatorUserId === selfUserId) {
+        refreshUnhandledGroupRequests()
+      }
+    },
+
+    /** 群消息置顶：从 payload 取消息展示数据加入置顶列表 */
+    applyGroupMessagePinNotification(groupId: number, payload: GroupNotificationPayload) {
+      const message = payload.message
+      if (!message) {
+        return
+      }
+      const group = this.getGroup(groupId)
+      if (!group) {
+        return
+      }
+      // 幂等：已存在同 messageId 不重复 push
+      const existing = group.pinnedMessages || []
+      if (existing.some((msg) => msg.id === message.id)) {
+        return
+      }
+      group.pinnedMessages = [
+        ...existing,
+        {
+          id: message.id,
+          clientMessageId: '',
+          senderId: message.senderId,
+          type: message.type,
+          content: message.content,
+          status: ImMessageStatus.NORMAL,
+          sendTime: new Date(message.sendTime).getTime(),
+          targetId: message.groupId || groupId,
+          selfSend: message.senderId === getCurrentUserId(),
+          atUserIds: message.atUserIds ? [...message.atUserIds] : [],
+          receiverUserIds: message.receiverUserIds ? [...message.receiverUserIds] : []
+        }
+      ]
+      this.saveGroup(group)
+    },
+
+    /** 群消息取消置顶：按 messageId 从本地置顶列表中移除 */
+    applyGroupMessageUnpinNotification(groupId: number, payload: GroupNotificationPayload) {
+      if (!payload.messageId) {
+        return
+      }
+      const group = this.getGroup(groupId)
+      if (!group?.pinnedMessages?.length) {
+        return
+      }
+      const newPinnedMessages = group.pinnedMessages.filter((m) => m.id !== payload.messageId)
+      if (newPinnedMessages.length === group.pinnedMessages.length) {
+        return
+      }
+      group.pinnedMessages = newPinnedMessages
+      this.saveGroup(group)
+    },
+
+    /** 单成员禁言：更新目标成员的 muteEndTime */
+    applyGroupMemberMutedNotification(groupId: number, payload: GroupNotificationPayload) {
+      const group = this.getGroup(groupId)
+      const member = group?.members?.find((m) => m.userId === payload.mutedUserId)
+      if (member && payload.muteEndTime) {
+        member.muteEndTime = payload.muteEndTime
+        this.saveGroupMemberList(groupId)
+        this.markGroupMembersExpired(groupId)
+      }
+    },
+
+    /** 单成员取消禁言：清空目标成员的 muteEndTime */
+    applyGroupMemberCancelMutedNotification(groupId: number, payload: GroupNotificationPayload) {
+      const group = this.getGroup(groupId)
+      const member = group?.members?.find((m) => m.userId === payload.mutedUserId)
+      if (member) {
+        member.muteEndTime = undefined
+        this.saveGroupMemberList(groupId)
+        this.markGroupMembersExpired(groupId)
+      }
+    },
+
+    /** 切账号时仅清 in-memory，IDB 按 userId 分桶天然隔离，回切秒开 */
+    clear() {
+      this.groups = []
+      this.loaded = false
+      this.groupMembersExpired = false
+      // 账号切换：递增 epoch 废弃旧账号 in-flight 的成员请求
+      storeEpoch++
+      // 单飞表跟 in-memory state 一起重置；旧账号 in-flight 的请求 finally 也会自己 delete key，提前清空只是更干脆
+      pendingMemberFetches.clear()
+      pendingSingleMemberFetches.clear()
+    }
+  }
+})
+
+function convertGroup(group: ImGroupApi.GroupRespVO): Group {
+  return {
+    id: group.id,
+    name: group.name,
+    avatar: group.avatar,
+    notice: group.notice,
+    ownerUserId: group.ownerUserId,
+    pinnedMessages: group.pinnedMessages?.map((message) => convertGroupMessageVO(message)),
+    mutedAll: group.mutedAll,
+    banned: group.banned,
+    joinApproval: group.joinApproval,
+    joinStatus: group.joinStatus,
+    groupRemark: group.groupRemark,
+    silent: group.silent
+  }
+}
+
+/** 后端 ImGroupMessageApi.GroupMessageRespVO -> 前端 Message：补 targetId / selfSend / sendTime 等派生字段 */
+function convertGroupMessageVO(
+  message: NonNullable<ImGroupApi.GroupRespVO['pinnedMessages']>[number]
+): Message {
+  const currentUserId = getCurrentUserId()
+  return {
+    id: message.id,
+    clientMessageId: message.clientMessageId || '',
+    type: message.type,
+    content: message.content,
+    status: message.status,
+    sendTime: new Date(message.sendTime).getTime(),
+    senderId: message.senderId,
+    targetId: message.groupId,
+    selfSend: !!currentUserId && message.senderId === currentUserId,
+    atUserIds: message.atUserIds || [],
+    receiverUserIds: message.receiverUserIds || [],
+    receiptStatus: message.receiptStatus,
+    readCount: message.readCount
+  }
+}
+
+function convertGroupMember(member: ImGroupMemberApi.GroupMemberRespVO, groupId: number): GroupMember {
+  return {
+    id: member.id,
+    userId: member.userId,
+    groupId,
+    nickname: member.nickname || String(member.userId),
+    avatar: member.avatar,
+    displayUserName: member.displayUserName,
+    status: member.status,
+    role: member.role,
+    muteEndTime: member.muteEndTime
+  }
+}
+
+export const useGroupStoreWithOut = () => useGroupStore()
+
+// dev: 让 Pinia 的 actions 改动支持 HMR，免去每次改 store 都要硬刷
+if (import.meta.hot) {
+  import.meta.hot.accept(acceptHMRUpdate(useGroupStore, import.meta.hot))
+}
diff --git a/apps/web-ele/src/views/im/home/store/messageStore.ts b/apps/web-ele/src/views/im/home/store/messageStore.ts
new file mode 100644
index 000000000..f372780f1
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/store/messageStore.ts
@@ -0,0 +1,926 @@
+import type { Conversation, Message, MessageDO } from '../types'
+
+import { acceptHMRUpdate, defineStore } from 'pinia'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import {
+  IM_AT_ALL_USER_ID,
+  ImContentType,
+  ImConversationType,
+  ImMessageReceiptStatus,
+  ImMessageStatus,
+  isGroupNotification,
+  isNormalMessage
+} from '../../utils/constants'
+import { resolveConversationLastContent } from '../../utils/conversation'
+import {
+  type DbTransaction,
+  getClientConversationId,
+  getClientMessageKey,
+  getDb,
+  getServerMessageKey,
+  parseClientConversationId,
+  setMessageMaxId,
+  StorageKeys
+} from '../../utils/db'
+import {
+  generateClientMessageId,
+  parseRecallMessageId,
+  revokeBlobUrlsInContent
+} from '../../utils/message'
+import { isGroupQuit, tryGetSenderDisplayName } from '../../utils/user'
+import { useConversationStore } from './conversationStore'
+import { useGroupStore } from './groupStore'
+
+const MESSAGE_CACHE_RECENT_CONVERSATION_LIMIT = 5
+const MESSAGE_CACHE_RETAIN_CONVERSATION_LIMIT = MESSAGE_CACHE_RECENT_CONVERSATION_LIMIT + 1
+const ackMergingPromises = new Map<string, Promise<void>>()
+
+interface MessageConversationInfo {
+  type: number
+  targetId: number
+  name: string
+  avatar: string
+  silent?: boolean
+}
+
+interface PersistMessageRecordOptions {
+  mergeClientRecord?: boolean
+}
+
+/** 拉取消息批量处理项 */
+export type PulledMessage =
+  | {
+      conversationInfo: MessageConversationInfo
+      kind: 'insert'
+      message: Message
+    }
+  | {
+      conversationType: number
+      kind: 'recall'
+      recallSignalContent: string
+      targetId: number
+    }
+
+/** 获取会话的消息缓存 key */
+function getMessageCacheKey(type: number, targetId: number): string {
+  return getClientConversationId(type, targetId)
+}
+
+/** 生成消息本地主键 */
+function getMessageKey(
+  message: Pick<Message, 'clientMessageId' | 'id'>,
+  conversationType: number
+): string {
+  return message.id
+    ? getServerMessageKey(conversationType, message.id)
+    : getClientMessageKey(message.clientMessageId)
+}
+
+/** 补齐客户端消息编号 */
+function ensureClientMessageId(message: Message): Message {
+  if (!message.clientMessageId) {
+    message.clientMessageId = generateClientMessageId()
+  }
+  if (!message.id) {
+    message.id = undefined
+  }
+  return message
+}
+
+/** 转换为 IndexedDB 消息记录 */
+function buildMessageDO(message: Message, conversationType: number): MessageDO {
+  return {
+    id: message.id,
+    clientMessageId: message.clientMessageId,
+    type: message.type,
+    content: message.content,
+    status: message.status,
+    sendTime: message.sendTime,
+    senderId: message.senderId,
+    atUserIds: message.atUserIds ? [...message.atUserIds] : undefined,
+    receiverUserIds: message.receiverUserIds ? [...message.receiverUserIds] : undefined,
+    receiptStatus: message.receiptStatus,
+    readCount: message.readCount,
+    materialId: message.materialId,
+    targetId: message.targetId,
+    selfSend: message.selfSend,
+    messageKey: getMessageKey(message, conversationType),
+    conversationType,
+    clientConversationId: getClientConversationId(conversationType, message.targetId)
+  }
+}
+
+/** IndexedDB 消息记录转前端消息 */
+function buildMessageFromDO(message: MessageDO): Message {
+  const {
+    messageKey: _messageKey,
+    conversationType: _conversationType,
+    clientConversationId: _clientConversationId,
+    ...rest
+  } = message
+  return rest
+}
+
+/** 算出末条消息的发送人快照 */
+function deriveLastSenderDisplayName(
+  conversation: Conversation,
+  senderId: number
+): string | undefined {
+  // 1. 优先使用当前内存中的好友 / 群成员信息
+  const liveSenderName = tryGetSenderDisplayName(senderId, conversation.type, conversation.targetId)
+  if (liveSenderName) {
+    return liveSenderName
+  }
+  // 2. 群成员缓存缺失时异步补齐
+  if (conversation.type === ImConversationType.GROUP) {
+    const groupStore = useGroupStore()
+    const group = groupStore.getGroup(conversation.targetId)
+    if (!group || isGroupQuit(group)) {
+      return conversation.lastSenderId === senderId ? conversation.lastSenderDisplayName : undefined
+    }
+    const fetchPromise =
+      group?.membersLoaded && !group.membersExpired
+        ? groupStore.fetchGroupMember(conversation.targetId, senderId)
+        : groupStore.fetchGroupMemberList(conversation.targetId)
+    fetchPromise.catch((error) =>
+      console.warn(
+        '[IM messageStore] 兜底拉群成员失败',
+        { groupId: conversation.targetId, senderId, fullFetch: !group?.membersLoaded },
+        error
+      )
+    )
+  }
+  return conversation.lastSenderId === senderId ? conversation.lastSenderDisplayName : undefined
+}
+
+/** 按消息更新会话摘要 */
+function applyConversationSummary(conversation: Conversation, message: Message): void {
+  const senderDisplayName = deriveLastSenderDisplayName(conversation, message.senderId)
+  conversation.lastContent = resolveConversationLastContent(
+    message,
+    conversation.type,
+    conversation.targetId,
+    senderDisplayName
+  )
+  conversation.lastSendTime = message.sendTime || Date.now()
+  conversation.lastSenderId = message.senderId
+  conversation.lastMessageType = message.type
+  conversation.lastMessageId = message.id
+  conversation.lastClientMessageId = message.clientMessageId
+  conversation.lastMessageStatus = message.status
+  conversation.lastReceiptStatus = message.receiptStatus
+  conversation.lastSelfSend = message.selfSend
+  conversation.lastSenderDisplayName = senderDisplayName
+}
+
+/** 按末条消息重算会话摘要 */
+function recomputeConversationLast(conversation: Conversation, messages: Message[]): void {
+  const last = messages[messages.length - 1]
+  if (last) {
+    applyConversationSummary(conversation, last)
+    return
+  }
+  conversation.lastContent = ''
+  conversation.lastSendTime = 0
+  conversation.lastSenderId = undefined
+  conversation.lastMessageType = undefined
+  conversation.lastMessageId = undefined
+  conversation.lastClientMessageId = undefined
+  conversation.lastMessageStatus = undefined
+  conversation.lastReceiptStatus = undefined
+  conversation.lastSelfSend = undefined
+  conversation.lastSenderDisplayName = undefined
+}
+
+/** 同步群 @ 状态 */
+function syncConversationAtFlags(conversation: Conversation, message: Message): void {
+  if (
+    message.selfSend ||
+    conversation.type !== ImConversationType.GROUP ||
+    !message.atUserIds ||
+    message.atUserIds.length === 0
+  ) {
+    return
+  }
+  const currentUserId = getCurrentUserId()
+  if (currentUserId && message.atUserIds.includes(currentUserId)) {
+    conversation.atMe = true
+  }
+  if (message.atUserIds.includes(IM_AT_ALL_USER_ID)) {
+    conversation.atAll = true
+  }
+}
+
+/** 应用服务端消息更新 */
+function applyServerMessageUpdate(message: Message, updates: Partial<Message>): void {
+  if (updates.content && updates.content !== message.content) {
+    revokeBlobUrlsInContent(message.content)
+  }
+  Object.assign(message, updates)
+  if (updates.id === 0) {
+    message.id = undefined
+  }
+  if (updates.status !== undefined && updates.status !== ImMessageStatus.SENDING) {
+    message.uploadProgress = undefined
+    if (updates.status !== ImMessageStatus.FAILED) {
+      message._localFile = undefined
+    }
+  }
+}
+
+/** 判断是否为同一条消息 */
+function isSameMessage(left: Message, right: Message): boolean {
+  if (left.id && right.id && left.id === right.id) {
+    return true
+  }
+  return !!left.clientMessageId && left.clientMessageId === right.clientMessageId
+}
+
+export const useMessageStore = defineStore('imMessageStore', {
+  state: () => ({
+    messagesByConversation: {} as Record<string, Message[]>,
+    loadedConversationKeys: [] as string[],
+    privateMessageMaxId: 0,
+    groupMessageMaxId: 0,
+    channelMessageMaxId: 0
+  }),
+
+  getters: {
+    /** 获取会话已加载消息 */
+    getMessages:
+      (state) =>
+      (clientConversationId: string): Message[] =>
+        state.messagesByConversation[clientConversationId] || []
+  },
+
+  actions: {
+    /** 清空消息内存 */
+    clear() {
+      Object.values(this.messagesByConversation).forEach((messages) => {
+        messages.forEach((message) => {
+          revokeBlobUrlsInContent(message.content)
+          message._localFile = undefined
+        })
+      })
+      this.messagesByConversation = {}
+      this.loadedConversationKeys = []
+      this.privateMessageMaxId = 0
+      this.groupMessageMaxId = 0
+      this.channelMessageMaxId = 0
+      ackMergingPromises.clear()
+    },
+
+    /** 从 settings 加载消息游标 */
+    async loadMessageCursorList() {
+      const db = getDb()
+      const [privateMaxId, groupMaxId, channelMaxId] = await Promise.all([
+        db.getSetting<number>(StorageKeys.settings.privateMessageMaxId),
+        db.getSetting<number>(StorageKeys.settings.groupMessageMaxId),
+        db.getSetting<number>(StorageKeys.settings.channelMessageMaxId)
+      ])
+      this.privateMessageMaxId = privateMaxId || 0
+      this.groupMessageMaxId = groupMaxId || 0
+      this.channelMessageMaxId = channelMaxId || 0
+    },
+
+    /** 更新内存游标 */
+    updateMessageCursor(conversationType: number, messageId?: number) {
+      if (!messageId) {
+        return
+      }
+      if (conversationType === ImConversationType.PRIVATE && messageId > this.privateMessageMaxId) {
+        this.privateMessageMaxId = messageId
+      } else if (
+        conversationType === ImConversationType.GROUP &&
+        messageId > this.groupMessageMaxId
+      ) {
+        this.groupMessageMaxId = messageId
+      } else if (
+        conversationType === ImConversationType.CHANNEL &&
+        messageId > this.channelMessageMaxId
+      ) {
+        this.channelMessageMaxId = messageId
+      }
+    },
+
+    /** 标记会话近期使用 */
+    touchConversationMessageCache(clientConversationId: string) {
+      this.loadedConversationKeys = [
+        clientConversationId,
+        ...this.loadedConversationKeys.filter((key) => key !== clientConversationId)
+      ]
+      // 保留当前活跃会话 + 最近打开过的会话
+      const retained = this.loadedConversationKeys.slice(0, MESSAGE_CACHE_RETAIN_CONVERSATION_LIMIT)
+      const removed = this.loadedConversationKeys.slice(MESSAGE_CACHE_RETAIN_CONVERSATION_LIMIT)
+      this.loadedConversationKeys = retained
+      removed.forEach((key) => {
+        Reflect.deleteProperty(this.messagesByConversation, key)
+      })
+    },
+
+    /** 加载当前会话最近消息 */
+    async loadMoreMessageList(
+      clientConversationId: string,
+      beforeSendTime?: number,
+      limit = 50
+    ): Promise<Message[]> {
+      // 1. 从 IndexedDB 倒序读取一页，返回前已按时间升序排列
+      const list = await getDb().getMessageListByConversation(clientConversationId, {
+        beforeSendTime,
+        limit
+      })
+      // 2. 合并到内存缓存，过滤已存在的消息
+      const parsed = parseClientConversationId(clientConversationId)
+      if (!parsed) {
+        return []
+      }
+      const messages = list.map((message) => buildMessageFromDO(message))
+      const existing = this.messagesByConversation[clientConversationId] || []
+      const existingKeys = new Set(existing.map((message) => getMessageKey(message, parsed.type)))
+      const fresh = messages.filter(
+        (message) => !existingKeys.has(getMessageKey(message, parsed.type))
+      )
+      this.messagesByConversation[clientConversationId] = [...fresh, ...existing].toSorted(
+        (messageA, messageB) => (messageA.sendTime || 0) - (messageB.sendTime || 0)
+      )
+      this.touchConversationMessageCache(clientConversationId)
+      return fresh
+    },
+
+    /** 确保会话消息已加载 */
+    async ensureConversationMessageListLoaded(conversation: Conversation) {
+      const key = getMessageCacheKey(conversation.type, conversation.targetId)
+      if (this.messagesByConversation[key]) {
+        this.touchConversationMessageCache(key)
+        return
+      }
+      await this.loadMoreMessageList(key)
+    },
+
+    /** 获取内存消息数组 */
+    getMessageList(conversationType: number, targetId: number): Message[] {
+      const key = getMessageCacheKey(conversationType, targetId)
+      if (!this.messagesByConversation[key]) {
+        this.messagesByConversation[key] = []
+      }
+      this.touchConversationMessageCache(key)
+      return this.messagesByConversation[key]
+    },
+
+    /** 持久化消息记录 */
+    async saveMessageRecord(
+      message: Message,
+      conversationType: number,
+      tx?: DbTransaction,
+      options?: PersistMessageRecordOptions
+    ) {
+      const db = getDb()
+      const next = buildMessageDO(message, conversationType)
+      // 服务端 key 替换 client key
+      if (options?.mergeClientRecord && message.id && message.clientMessageId) {
+        const existing = await db.getByIndex<MessageDO>(
+          'messages',
+          'clientMessageId',
+          message.clientMessageId,
+          tx
+        )
+        if (existing && existing.messageKey !== next.messageKey) {
+          await db.delete('messages', existing.messageKey, tx)
+        }
+      }
+      await db.put('messages', next, tx)
+    },
+
+    /** 保存消息游标 */
+    async saveMessageCursor(conversationType: number, messageId?: number, tx?: DbTransaction) {
+      await setMessageMaxId(conversationType, messageId, tx)
+      this.updateMessageCursor(conversationType, messageId)
+    },
+
+    /** 应用撤回到内存 */
+    applyRecallMessageInMemory(
+      conversationType: number,
+      targetId: number,
+      recallSignalContent: string
+    ) {
+      // 1. 定位被撤回的原消息
+      const messageId = parseRecallMessageId(recallSignalContent)
+      if (!messageId) {
+        return null
+      }
+      const conversationStore = useConversationStore()
+      const conversation = conversationStore.getConversation(conversationType, targetId)
+      if (!conversation) {
+        return null
+      }
+      const messages = this.getMessageList(conversationType, targetId)
+      const message = messages.find((item) => item.id === messageId)
+      if (!message) {
+        return null
+      }
+      // 2. 更新消息和会话摘要
+      message.type = ImContentType.RECALL
+      message.status = ImMessageStatus.RECALL
+      message.content = ''
+      if (messages[messages.length - 1]?.id === messageId) {
+        recomputeConversationLast(conversation, messages)
+      }
+      return { conversation, message }
+    },
+
+    /** 批量写入拉取消息 */
+    async applyPulledMessageList(
+      pulledMessages: PulledMessage[],
+      conversationType: number,
+      maxMessageId?: number
+    ) {
+      if (pulledMessages.length === 0) {
+        // 1. 空批次只推进游标
+        await this.saveMessageCursor(conversationType, maxMessageId)
+        return
+      }
+      const conversationStore = useConversationStore()
+      const persistedMessages = new Map<
+        string,
+        { conversationType: number; mergeClientRecord?: boolean; message: Message; }
+      >()
+      const changedConversations = new Map<string, Conversation>()
+
+      const addChanged = (
+        conversation: Conversation,
+        message: Message,
+        options?: PersistMessageRecordOptions
+      ) => {
+        const clientConversationId = getClientConversationId(
+          conversation.type,
+          conversation.targetId
+        )
+        changedConversations.set(clientConversationId, conversation)
+        persistedMessages.set(getMessageKey(message, conversation.type), {
+          message,
+          conversationType: conversation.type,
+          mergeClientRecord: options?.mergeClientRecord
+        })
+      }
+
+      // 1. 先更新内存，收集需要持久化的消息和会话
+      for (const pulledMessage of pulledMessages) {
+        if (pulledMessage.kind === 'recall') {
+          // 1.1 撤回信号更新原消息
+          const changed = this.applyRecallMessageInMemory(
+            pulledMessage.conversationType,
+            pulledMessage.targetId,
+            pulledMessage.recallSignalContent
+          )
+          if (changed) {
+            addChanged(changed.conversation, changed.message)
+          }
+          continue
+        }
+
+        const { conversationInfo } = pulledMessage
+        const hasServerClientMessageId = !!pulledMessage.message.clientMessageId
+        const message = ensureClientMessageId(pulledMessage.message)
+        // 1.2 确保会话和消息缓存存在
+        const conversation = conversationStore.ensureConversation(conversationInfo)
+        const messages = this.getMessageList(conversationInfo.type, conversationInfo.targetId)
+        const existingIndex = messages.findIndex((existing) => isSameMessage(existing, message))
+        if (existingIndex !== -1) {
+          const existing = messages[existingIndex]
+          if (!existing) {
+            continue
+          }
+          // 1.3 已存在消息合并服务端状态
+          applyServerMessageUpdate(existing, message)
+          if (existingIndex === messages.length - 1) {
+            recomputeConversationLast(conversation, messages)
+            syncConversationAtFlags(conversation, message)
+          }
+          addChanged(conversation, existing, {
+            mergeClientRecord: hasServerClientMessageId
+          })
+          continue
+        }
+
+        // 1.4 新消息更新会话摘要和未读状态
+        applyConversationSummary(conversation, message)
+        syncConversationAtFlags(conversation, message)
+        const isActive =
+          conversationStore.activeConversation?.type === conversationInfo.type &&
+          conversationStore.activeConversation?.targetId === conversationInfo.targetId
+        if (
+          !message.selfSend &&
+          !isActive &&
+          !conversationStore.isMessageCoveredByReadPosition(conversation, message) &&
+          isNormalMessage(message.type) &&
+          message.status !== ImMessageStatus.RECALL
+        ) {
+          conversation.unreadCount++
+        }
+
+        // 1.5 新消息按服务端 id 插入内存列表
+        let insertIndex = messages.length
+        if (message.id) {
+          for (const [index, existing] of messages.entries()) {
+            if (existing.id && message.id < existing.id) {
+              insertIndex = index
+              break
+            }
+          }
+        }
+        messages.splice(insertIndex, 0, message)
+        addChanged(conversation, message, {
+          mergeClientRecord: hasServerClientMessageId && !!message.id
+        })
+      }
+
+      // 2. 单事务写入消息、会话摘要和游标
+      await getDb().transaction(
+        ['messages', 'conversations', 'settings'],
+        'readwrite',
+        async (tx) => {
+          // 2.1 写入本批变更消息
+          for (const item of persistedMessages.values()) {
+            await this.saveMessageRecord(item.message, item.conversationType, tx, {
+              mergeClientRecord: item.mergeClientRecord
+            })
+          }
+          // 2.2 写入本批变更会话
+          await conversationStore.saveConversationRecord([...changedConversations.values()], tx)
+          // 2.3 写入本批游标
+          await setMessageMaxId(conversationType, maxMessageId, tx)
+        }
+      )
+      // 3. 持久化成功后推进内存游标
+      this.updateMessageCursor(conversationType, maxMessageId)
+      for (const item of persistedMessages.values()) {
+        this.updateMessageCursor(item.conversationType, item.message.id)
+      }
+    },
+
+    /** 插入消息 */
+    insertMessage(
+      conversationInfo: MessageConversationInfo,
+      messageInfo: Message,
+      options?: { saveMaxId?: boolean }
+    ): Promise<void> {
+      const conversationStore = useConversationStore()
+      const hasIncomingClientMessageId = !!messageInfo.clientMessageId
+      const message = ensureClientMessageId(messageInfo)
+      // 1. 先处理消息带来的群资料变更
+      if (conversationInfo.type === ImConversationType.GROUP && isGroupNotification(message.type)) {
+        useGroupStore().applyGroupNotification(
+          conversationInfo.targetId,
+          message.type,
+          message.content
+        )
+      }
+
+      // 2. 确保会话和消息缓存存在
+      const conversation = conversationStore.ensureConversation(conversationInfo)
+      const messages = this.getMessageList(conversationInfo.type, conversationInfo.targetId)
+      const existingIndex = messages.findIndex((item) => isSameMessage(item, message))
+      // 3. 已存在消息走覆盖更新
+      if (existingIndex !== -1) {
+        const existing = messages[existingIndex]
+        if (!existing) {
+          return Promise.resolve()
+        }
+        applyServerMessageUpdate(existing, message)
+        if (existingIndex === messages.length - 1) {
+          recomputeConversationLast(conversation, messages)
+          syncConversationAtFlags(conversation, message)
+        }
+        return getDb()
+          .transaction(['messages', 'conversations', 'settings'], 'readwrite', async (tx) => {
+            await this.saveMessageRecord(existing, conversationInfo.type, tx, {
+              mergeClientRecord: hasIncomingClientMessageId
+            })
+            await conversationStore.saveConversationRecord(conversation, tx)
+            if (options?.saveMaxId !== false) {
+              await setMessageMaxId(conversationInfo.type, message.id, tx)
+            }
+          })
+          .catch((error) => {
+            console.error('[IM messageStore] 消息写入失败', error)
+            throw error
+          })
+          .then(() => {
+            this.updateMessageCursor(conversationInfo.type, message.id)
+          })
+      }
+
+      // 4. 新消息更新会话摘要和未读状态
+      applyConversationSummary(conversation, message)
+      syncConversationAtFlags(conversation, message)
+
+      const isActive =
+        conversationStore.activeConversation?.type === conversationInfo.type &&
+        conversationStore.activeConversation?.targetId === conversationInfo.targetId
+      if (
+        !message.selfSend &&
+        !isActive &&
+        !conversationStore.isMessageCoveredByReadPosition(conversation, message) &&
+        isNormalMessage(message.type) &&
+        message.status !== ImMessageStatus.RECALL
+      ) {
+        conversation.unreadCount++
+      }
+
+      // 5. 新消息按 id 插入到内存数组
+      let insertIndex = messages.length
+      if (message.id) {
+        for (const [index, existing] of messages.entries()) {
+          if (existing.id && message.id < existing.id) {
+            insertIndex = index
+            break
+          }
+        }
+      }
+      messages.splice(insertIndex, 0, message)
+      // 6. 单事务写入消息、会话摘要和游标
+      return getDb()
+        .transaction(['messages', 'conversations', 'settings'], 'readwrite', async (tx) => {
+          await this.saveMessageRecord(message, conversationInfo.type, tx, {
+            mergeClientRecord: hasIncomingClientMessageId && !!message.id
+          })
+          await conversationStore.saveConversationRecord(conversation, tx)
+          if (options?.saveMaxId !== false) {
+            await setMessageMaxId(conversationInfo.type, message.id, tx)
+          }
+        })
+        .catch((error) => {
+          console.error('[IM messageStore] 消息写入失败', error)
+          throw error
+        })
+        .then(() => {
+          this.updateMessageCursor(conversationInfo.type, message.id)
+        })
+    },
+
+    /** ack 合并 */
+    ackMessage(
+      conversationType: number,
+      targetId: number,
+      clientMessageId: string,
+      updates: Partial<Message>
+    ) {
+      const mergeKey = `${conversationType}:${targetId}:${clientMessageId}`
+      const existingPromise = ackMergingPromises.get(mergeKey)
+      if (existingPromise) {
+        return existingPromise
+      }
+      const promise = this.doAckMessage(
+        conversationType,
+        targetId,
+        clientMessageId,
+        updates
+      ).finally(() => {
+        ackMergingPromises.delete(mergeKey)
+      })
+      ackMergingPromises.set(mergeKey, promise)
+      return promise
+    },
+
+    /** 执行 ack 合并 */
+    async doAckMessage(
+      conversationType: number,
+      targetId: number,
+      clientMessageId: string,
+      updates: Partial<Message>
+    ) {
+      // 1. 定位待合并消息
+      const conversationStore = useConversationStore()
+      const conversation = conversationStore.getConversation(conversationType, targetId)
+      if (!conversation) {
+        return
+      }
+      const messages = this.getMessageList(conversationType, targetId)
+      const message = messages.find((item) => item.clientMessageId === clientMessageId)
+      if (!message) {
+        return
+      }
+      message._ackMerging = true
+      try {
+        // 2. 合并服务端 ack 到内存
+        applyServerMessageUpdate(message, updates)
+        if (messages[messages.length - 1] === message) {
+          recomputeConversationLast(conversation, messages)
+        }
+        // 3. 单事务写入消息、会话摘要和游标
+        await getDb()
+          .transaction(['messages', 'conversations', 'settings'], 'readwrite', async (tx) => {
+            await this.saveMessageRecord(message, conversationType, tx, {
+              mergeClientRecord: true
+            })
+            await conversationStore.saveConversationRecord(conversation, tx)
+            await setMessageMaxId(conversationType, message.id, tx)
+          })
+          .catch((error) => {
+            console.error('[IM messageStore] ack 写入失败', error)
+            throw error
+          })
+        this.updateMessageCursor(conversationType, message.id)
+      } finally {
+        // 4. 清理合并标记
+        message._ackMerging = false
+      }
+    },
+
+    /** 局部更新消息 */
+    patchMessage(
+      conversationType: number,
+      targetId: number,
+      clientMessageId: string,
+      patch: Partial<Message>
+    ) {
+      const message = this.getMessageList(conversationType, targetId).find(
+        (item) => item.clientMessageId === clientMessageId
+      )
+      if (!message) {
+        return
+      }
+      let changed = false
+      for (const key in patch) {
+        if (
+          Object.prototype.hasOwnProperty.call(patch, key) &&
+          (patch as Record<string, unknown>)[key] !==
+            (message as unknown as Record<string, unknown>)[key]
+        ) {
+          changed = true
+          break
+        }
+      }
+      if (changed) {
+        applyServerMessageUpdate(message, patch)
+      }
+    },
+
+    /** 撤回消息 */
+    async recallMessage(
+      conversationType: number,
+      targetId: number,
+      recallSignalContent: string
+    ): Promise<void> {
+      const conversationStore = useConversationStore()
+      const changed = this.applyRecallMessageInMemory(
+        conversationType,
+        targetId,
+        recallSignalContent
+      )
+      if (!changed) {
+        return
+      }
+      await getDb()
+        .transaction(['messages', 'conversations'], 'readwrite', async (tx) => {
+          await this.saveMessageRecord(changed.message, conversationType, tx)
+          await conversationStore.saveConversationRecord(changed.conversation, tx)
+        })
+        .catch((error) => {
+          console.error('[IM messageStore] 撤回消息写入失败', error)
+          throw error
+        })
+    },
+
+    /** 应用已读回执 */
+    applyMessageReadReceipt(options: {
+      conversationType: number
+      groupMessageId?: number
+      privateReadMaxId?: number
+      readCount?: number
+      receiptStatus?: number
+      targetId: number
+    }) {
+      const messages = this.getMessageList(options.conversationType, options.targetId)
+      const changed: Message[] = []
+      // 1. 私聊回执批量更新自己发送的消息
+      if (options.conversationType === ImConversationType.PRIVATE && options.privateReadMaxId) {
+        const privateReadMaxId = options.privateReadMaxId
+        messages.forEach((message) => {
+          if (
+            message.selfSend &&
+            message.id &&
+            message.id <= privateReadMaxId &&
+            message.receiptStatus === ImMessageReceiptStatus.PENDING
+          ) {
+            message.receiptStatus = ImMessageReceiptStatus.DONE
+            changed.push(message)
+          }
+        })
+      } else if (options.conversationType === ImConversationType.GROUP && options.groupMessageId) {
+        // 2. 群聊回执更新单条消息
+        const message = messages.find((item) => item.id === options.groupMessageId)
+        if (message) {
+          if (options.readCount !== undefined) {
+            message.readCount = options.readCount
+          }
+          if (options.receiptStatus !== undefined) {
+            message.receiptStatus = options.receiptStatus
+          }
+          changed.push(message)
+        }
+      }
+      if (changed.length === 0) {
+        return
+      }
+      // 3. 单事务写入变更消息
+      void getDb()
+        .transaction(['messages'], 'readwrite', async (tx) => {
+          for (const message of changed) {
+            await this.saveMessageRecord(message, options.conversationType, tx)
+          }
+        })
+        .catch((error) => console.warn('[IM messageStore] 回执写入失败', error))
+    },
+
+    /** 前置历史消息 */
+    prependMessageList(conversationType: number, targetId: number, earlierMessages: Message[]) {
+      if (earlierMessages.length === 0) {
+        return
+      }
+      const messages = this.getMessageList(conversationType, targetId)
+      const existingIds = new Set(messages.map((message) => message.id).filter(Boolean))
+      const fresh = earlierMessages
+        .map((message) => ensureClientMessageId(message))
+        .filter((message) => message.id && !existingIds.has(message.id))
+        .toSorted((messageA, messageB) => (messageA.id || 0) - (messageB.id || 0))
+      if (fresh.length === 0) {
+        return
+      }
+      const key = getMessageCacheKey(conversationType, targetId)
+      this.messagesByConversation[key] = [...fresh, ...messages]
+      void getDb()
+        .transaction(['messages'], 'readwrite', async (tx) => {
+          for (const message of fresh) {
+            await this.saveMessageRecord(message, conversationType, tx)
+          }
+        })
+        .catch((error) => console.warn('[IM messageStore] 历史消息写入失败', error))
+    },
+
+    /** 删除单条消息 */
+    removeMessage(
+      conversationType: number,
+      targetId: number,
+      key: { clientMessageId?: string; id?: number; }
+    ) {
+      // 1. 定位会话和消息
+      const conversationStore = useConversationStore()
+      const conversation = conversationStore.getConversation(conversationType, targetId)
+      if (!conversation) {
+        return
+      }
+      const messages = this.getMessageList(conversationType, targetId)
+      const index = messages.findIndex((message) => {
+        if (key.id && message.id && message.id === key.id) {
+          return true
+        }
+        return !!key.clientMessageId && message.clientMessageId === key.clientMessageId
+      })
+      if (index === -1) {
+        return
+      }
+      // 2. 从内存移除消息
+      const [removed] = messages.splice(index, 1)
+      if (!removed) {
+        return
+      }
+      revokeBlobUrlsInContent(removed.content)
+      if (index === messages.length) {
+        recomputeConversationLast(conversation, messages)
+      }
+      // 3. 删除本地记录并保存会话摘要
+      getDb()
+        .delete('messages', getMessageKey(removed, conversationType))
+        .catch((error) => console.warn('[IM messageStore] 消息删除失败', error))
+      conversationStore.saveConversation(conversation)
+    },
+
+    /** 删除会话全部消息 */
+    deleteConversationMessageList(conversationType: number, targetId: number) {
+      // 1. 清理内存消息和媒体资源
+      const clientConversationId = getClientConversationId(conversationType, targetId)
+      const messages = this.messagesByConversation[clientConversationId] || []
+      messages.forEach((message) => {
+        revokeBlobUrlsInContent(message.content)
+        message._localFile = undefined
+      })
+      Reflect.deleteProperty(this.messagesByConversation, clientConversationId)
+      this.loadedConversationKeys = this.loadedConversationKeys.filter(
+        (key) => key !== clientConversationId
+      )
+      // 2. 删除 IndexedDB 消息
+      getDb()
+        .deleteByIndex('messages', 'clientConversationId', clientConversationId)
+        .catch((error) => console.warn('[IM messageStore] 会话消息删除失败', error))
+    }
+  }
+})
+
+export const useMessageStoreWithOut = () => useMessageStore()
+
+if (import.meta.hot) {
+  import.meta.hot.accept(acceptHMRUpdate(useMessageStore, import.meta.hot))
+}
diff --git a/apps/web-ele/src/views/im/home/store/rtcStore.ts b/apps/web-ele/src/views/im/home/store/rtcStore.ts
new file mode 100644
index 000000000..b90ab837c
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/store/rtcStore.ts
@@ -0,0 +1,404 @@
+import type { ImRtcApi } from '#/api/im/rtc'
+
+import { computed, ref } from 'vue'
+
+import { defineStore } from 'pinia'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import {
+  ImConversationType,
+  type ImRtcCallEndReasonValue,
+  ImRtcCallStage,
+  type ImRtcCallStageValue,
+  ImRtcCallStatus,
+  type ImRtcParticipantStatusValue
+} from '../../utils/constants'
+import { useFriendStore } from './friendStore'
+import { useGroupStore } from './groupStore'
+
+// RTC_CALL 通话信令载荷；按 status 区分子类型语义
+export interface ImRtcCallNotification {
+  status: ImRtcParticipantStatusValue
+  room: string
+  conversationType: number
+  mediaType: number
+  groupId?: number
+  // INVITE 专属：被叫接通需要的 LiveKit 连接参数 + 主叫展示信息
+  livekitUrl?: string
+  token?: string
+  inviterUserId?: number
+  inviterNickname?: string
+  inviterAvatar?: string
+  // INVITE 专属：本次被邀请人列表；包含收件人自身，前端来电小条按需过滤展示「邀请的其他人」
+  inviteeIds?: number[]
+  // REJECT 专属：操作者展示信息（其它子类型走 RTC_CALL_END）
+  operatorUserId?: number
+  operatorNickname?: string
+  operatorAvatar?: string
+}
+
+// RTC_PARTICIPANT_CONNECTED 通话参与者加入载荷（LiveKit webhook 转推）
+export interface ImRtcParticipantConnectedNotification {
+  room: string
+  userId: number
+  conversationType: number
+  groupId?: number
+  // 群聊场景非邀请成员首次填充胶囊条用
+  mediaType?: number
+  inviterUserId?: number
+}
+
+// RTC_PARTICIPANT_DISCONNECTED 通话参与者离开载荷（LiveKit webhook 转推）
+export interface ImRtcParticipantDisconnectedNotification {
+  room: string
+  userId: number
+  conversationType: number
+  groupId?: number
+}
+
+// RTC_CALL_END 通话结束载荷（入消息流；私聊渲染消息气泡，群聊渲染系统提示行）
+export interface ImRtcCallEndNotification {
+  room: string
+  conversationType: number
+  mediaType: number
+  endReason: ImRtcCallEndReasonValue
+  durationSeconds?: number
+  // 操作者聚合字段：HANGUP/CANCEL/REJECT 触发人；webhook 兜底为 null
+  operatorUserId?: number
+  operatorNickname?: string
+  operatorAvatar?: string
+}
+
+export const useRtcStore = defineStore('imRtc', () => {
+  /** 当前阶段 */
+  const stage = ref<ImRtcCallStageValue>(ImRtcCallStage.IDLE)
+  /** 当前通话；invite / accept / refreshToken 拿到的完整信息 */
+  const call = ref<ImRtcApi.RtcCallRespVO | null>(null)
+  /** 来电载荷；仅 INCOMING 阶段使用；status 固定 INVITING，其它字段 INVITE 专属 */
+  const incomingPayload = ref<ImRtcCallNotification | null>(null)
+  /** 进入 RUNNING 的时间戳；用于通话时长展示；reset 时清零 */
+  const startedAt = ref(0)
+
+  /** 是否处于通话相关阶段 */
+  const isActive = computed(() => stage.value !== ImRtcCallStage.IDLE)
+
+  /**
+   * 对端展示名；按阶段 + 会话类型分支：
+   * INCOMING 取来电载荷的 inviterNickname；群通话取群名；私聊查 friendStore 反查对端 userId
+   */
+  const peerNickname = computed<string>(() => {
+    if (stage.value === ImRtcCallStage.INCOMING) {
+      return incomingPayload.value?.inviterNickname || ''
+    }
+    const c = call.value
+    if (!c) return ''
+    if (c.conversationType === ImConversationType.GROUP) {
+      return useGroupStore().getGroup(c.groupId ?? 0)?.name || ''
+    }
+    const peerUserId = resolvePrivatePeerUserId(c)
+    return (peerUserId && useFriendStore().getFriend(peerUserId)?.nickname) || ''
+  })
+
+  /** 对端头像；策略同 peerNickname */
+  const peerAvatar = computed<string>(() => {
+    if (stage.value === ImRtcCallStage.INCOMING) {
+      return incomingPayload.value?.inviterAvatar || ''
+    }
+    const c = call.value
+    if (!c) return ''
+    if (c.conversationType === ImConversationType.GROUP) {
+      return useGroupStore().getGroup(c.groupId ?? 0)?.avatar || ''
+    }
+    const peerUserId = resolvePrivatePeerUserId(c)
+    return (peerUserId && useFriendStore().getFriend(peerUserId)?.avatar) || ''
+  })
+
+  /** 私聊场景对端 userId：自己是主叫则取首个 invitee，否则取 inviter */
+  function resolvePrivatePeerUserId(c: ImRtcApi.RtcCallRespVO): number | undefined {
+    const myId = getCurrentUserId()
+    return c.inviterId === myId ? c.inviteeIds?.[0] : c.inviterId
+  }
+
+  /** 群活跃通话索引；groupId -> 群通话摘要；用于群聊顶部胶囊条 */
+  const groupActiveCalls = ref<Map<number, ImRtcApi.RtcGroupCallRespVO>>(new Map())
+
+  /**
+   * 已退出 / 已拒绝的用户编号集合；群通话场景内 pending 占位渲染时排除；
+   * 来源：参与者离开通知 + 群通话单人拒绝的 operatorUserId；通话结束（reset）时清空
+   */
+  const leftUserIds = ref<Set<number>>(new Set())
+
+  /** 是否已记录某 userId 已退出 / 拒绝 */
+  function isUserLeft(userId: number): boolean {
+    return leftUserIds.value.has(userId)
+  }
+
+  /** 标记某个 userId 已退出 / 拒绝；用于 pending 占位渲染时排除 */
+  function markUserLeft(userId: number) {
+    if (!userId || leftUserIds.value.has(userId)) {
+      return
+    }
+    leftUserIds.value = new Set([...leftUserIds.value, userId])
+  }
+
+  /**
+   * 主叫发起通话；按会话类型 + status 决定 stage；
+   * 群通话：发起人直接进 RUNNING 多人卡片视图，房内可能只有自己，等其他人陆续加入；
+   * 私聊：按 status 走；RUNNING（已加入已有通话场景）→ RUNNING；CREATED → INVITING 等被叫接通
+   */
+  function startInviting(data: ImRtcApi.RtcCallRespVO) {
+    call.value = data
+    // 群通话场景写入本地胶囊条缓存
+    syncGroupActiveCall(data)
+    // 更新 stage 状态
+    if (data.conversationType === ImConversationType.GROUP) {
+      stage.value = ImRtcCallStage.RUNNING
+      startedAt.value = Date.now()
+      return
+    }
+    const running = data.status === ImRtcCallStatus.RUNNING
+    stage.value = running ? ImRtcCallStage.RUNNING : ImRtcCallStage.INVITING
+    if (running) {
+      startedAt.value = Date.now()
+    }
+  }
+
+  /** 被叫收到来电；切到 INCOMING；接收 RTC_CALL(INVITE) payload */
+  function showIncoming(payload: ImRtcCallNotification) {
+    if (isActive.value) {
+      return
+    }
+    incomingPayload.value = payload
+    stage.value = ImRtcCallStage.INCOMING
+    // 按 inviter 兜底首次填充胶囊条
+    syncGroupActiveCall({
+      conversationType: payload.conversationType,
+      room: payload.room,
+      groupId: payload.groupId,
+      mediaType: payload.mediaType,
+      inviterId: payload.inviterUserId ?? 0,
+      joinedUserIds: payload.inviterUserId ? [payload.inviterUserId] : [],
+      inviteeIds: payload.inviteeIds
+    })
+  }
+
+  /** 进入通话中阶段 */
+  function enterRunning(data: ImRtcApi.RtcCallRespVO) {
+    call.value = data
+    // 离开 INCOMING 阶段；清空来电载荷
+    incomingPayload.value = null
+    stage.value = ImRtcCallStage.RUNNING
+    startedAt.value = Date.now()
+    // 接通后用 RespVO 完整覆盖胶囊条
+    syncGroupActiveCall(data)
+  }
+
+  /**
+   * 群通话场景同步本地 groupActiveCalls 缓存；非群通话或缺 groupId 直接返回；
+   * 不依赖后端 webhook 推送的 RTC_PARTICIPANT_CONNECTED 首次填充，避免胶囊条出现延迟；
+   * 被叫场景通知载荷无 joinedUserIds，调用方按主叫人兜底，后续 getActiveCall / 参与者事件刷新成完整列表
+   */
+  function syncGroupActiveCall(input: {
+    conversationType: number
+    groupId?: number
+    inviteeIds?: number[]
+    inviterId: number
+    joinedUserIds?: number[]
+    mediaType: number
+    room: string
+  }) {
+    if (input.conversationType !== ImConversationType.GROUP || !input.groupId) {
+      return
+    }
+    // 写入或更新群活跃通话缓存
+    setGroupCall({
+      room: input.room,
+      groupId: input.groupId,
+      mediaType: input.mediaType,
+      inviterId: input.inviterId,
+      joinedUserIds: input.joinedUserIds ?? [],
+      inviteeIds: input.inviteeIds ?? []
+    })
+  }
+
+  /** 重置；通话结束统一调用 */
+  function reset() {
+    stage.value = ImRtcCallStage.IDLE
+    call.value = null
+    incomingPayload.value = null
+    startedAt.value = 0
+    leftUserIds.value = new Set()
+  }
+
+  /** 通话中追加被邀请人；让 participants 网格出现 pending 占位、胶囊条同步更新 */
+  function appendInvitees(userIds: number[]) {
+    if (!call.value || userIds.length === 0) {
+      return
+    }
+    const existing = call.value.inviteeIds ?? []
+    const merged = [...new Set([...existing, ...userIds])]
+    if (merged.length === existing.length) {
+      return
+    }
+    call.value = { ...call.value, inviteeIds: merged }
+    syncGroupActiveCall(call.value)
+  }
+
+  // ==================== 群通话胶囊条状态 ====================
+
+  /**
+   * 群通话开始 / 状态刷新：写入 / 更新 groupActiveCalls；展示用「胶囊条」；
+   * 房内成员同步交给 LiveKit 客户端事件（ParticipantConnected / Disconnected）；
+   * 胶囊条不实时刷新 joinedUserIds / inviteeIds，展开 / 加入时再走 getActiveCall 接口拉最新
+   */
+  function setGroupCall(payload: ImRtcApi.RtcGroupCallRespVO) {
+    if (!payload?.groupId) {
+      return
+    }
+    // 浅比较：room / mediaType / joinedUserIds / inviteeIds 都没变就跳过，避免下游 watcher 无意义重算
+    const existing = groupActiveCalls.value.get(payload.groupId)
+    if (existing && isSameGroupCall(existing, payload)) {
+      return
+    }
+    const newGroupActiveCalls = new Map(groupActiveCalls.value)
+    newGroupActiveCalls.set(payload.groupId, payload)
+    groupActiveCalls.value = newGroupActiveCalls
+  }
+
+  /** 两条群通话摘要内容相等（room / mediaType / inviterId / 两个 userId 数组逐项相等） */
+  function isSameGroupCall(a: ImRtcApi.RtcGroupCallRespVO, b: ImRtcApi.RtcGroupCallRespVO): boolean {
+    if (a.room !== b.room || a.mediaType !== b.mediaType || a.inviterId !== b.inviterId) {
+      return false
+    }
+    return isSameNumberList(a.joinedUserIds ?? [], b.joinedUserIds ?? []) &&
+      isSameNumberList(a.inviteeIds ?? [], b.inviteeIds ?? [])
+  }
+
+  /** 判断两个用户编号列表是否逐项相等 */
+  function isSameNumberList(a: number[], b: number[]): boolean {
+    if (a.length !== b.length) {
+      return false
+    }
+    return a.every((item, index) => item === b[index])
+  }
+
+  /** 群通话结束：从 groupActiveCalls 移除；胶囊条消失 */
+  function removeGroupCall(groupId: number) {
+    if (!groupId || !groupActiveCalls.value.has(groupId)) {
+      return
+    }
+    const newGroupActiveCalls = new Map(groupActiveCalls.value)
+    newGroupActiveCalls.delete(groupId)
+    groupActiveCalls.value = newGroupActiveCalls
+  }
+
+  /** 获取群当前活跃通话；用于胶囊条按 groupId 查询 */
+  function getGroupCall(groupId: number): ImRtcApi.RtcGroupCallRespVO | undefined {
+    return groupActiveCalls.value.get(groupId)
+  }
+
+  /** 通话参与者加入：把 userId 加进 joinedUserIds；群聊场景无活跃记录时首次填充胶囊条 */
+  function applyParticipantConnected(payload: ImRtcParticipantConnectedNotification) {
+    const isGroup = payload.conversationType === ImConversationType.GROUP
+    if (!isGroup || !payload.groupId) {
+      return
+    }
+    // 胶囊条懒填充：本端可能在通话开始后才打开该群会话，没收到过 setGroupCall；
+    // 此处用加入通知建一条最小记录，inviteeIds 留空，展开 popover / 加入时再走 getActiveCall 补
+    const existing = groupActiveCalls.value.get(payload.groupId)
+    if (!existing) {
+      setGroupCall({
+        room: payload.room,
+        groupId: payload.groupId,
+        mediaType: payload.mediaType ?? 0,
+        inviterId: payload.inviterUserId ?? 0,
+        joinedUserIds: [payload.userId],
+        inviteeIds: []
+      })
+      return
+    }
+    if (existing.room !== payload.room) {
+      return
+    }
+    const joined = existing.joinedUserIds ?? []
+    if (joined.includes(payload.userId)) {
+      return
+    }
+    setGroupCall({ ...existing, joinedUserIds: [...joined, payload.userId] })
+  }
+
+  /** 通话参与者离开：从 joinedUserIds 移除；同时标记 leftUserIds（pending 占位渲染排除） */
+  function applyParticipantDisconnected(payload: ImRtcParticipantDisconnectedNotification) {
+    markUserLeft(payload.userId)
+    const isGroup = payload.conversationType === ImConversationType.GROUP
+    if (!isGroup || !payload.groupId) {
+      return
+    }
+    dropFromGroupActiveCall(payload.groupId, payload.room, payload.userId)
+  }
+
+  /** 群通话单人拒绝邀请：标记 leftUserIds + 从胶囊条 inviteeIds 移除（私聊拒绝走 RTC_CALL_END，不入本通道） */
+  function applyParticipantRejected(
+    payload: Pick<ImRtcCallNotification, 'conversationType' | 'groupId' | 'operatorUserId' | 'room'>
+  ) {
+    if (!payload.operatorUserId) {
+      return
+    }
+    markUserLeft(payload.operatorUserId)
+    if (payload.conversationType === ImConversationType.GROUP && payload.groupId) {
+      dropFromGroupActiveCall(payload.groupId, payload.room, payload.operatorUserId)
+    }
+  }
+
+  /** 群通话单人振铃超时；对 banner 的处理与拒接一致（语义独立、实现共享） */
+  function applyParticipantNoAnswer(
+    payload: Pick<ImRtcCallNotification, 'conversationType' | 'groupId' | 'operatorUserId' | 'room'>
+  ) {
+    applyParticipantRejected(payload)
+  }
+
+  /** 从指定群活跃通话的 joined / pending 列表里同步移除某用户；用于 disconnect / reject 让胶囊条不再展示 */
+  function dropFromGroupActiveCall(groupId: number, room: string, userId: number) {
+    const existing = groupActiveCalls.value.get(groupId)
+    if (!existing || existing.room !== room) {
+      return
+    }
+    const joined = existing.joinedUserIds ?? []
+    const invitee = existing.inviteeIds ?? []
+    const nextJoined = joined.filter((id) => id !== userId)
+    const nextInvitee = invitee.filter((id) => id !== userId)
+    if (nextJoined.length === joined.length && nextInvitee.length === invitee.length) {
+      return
+    }
+    setGroupCall({
+      ...existing,
+      joinedUserIds: nextJoined,
+      inviteeIds: nextInvitee
+    })
+  }
+
+  return {
+    stage,
+    call,
+    incomingPayload,
+    peerNickname,
+    peerAvatar,
+    startedAt,
+    isActive,
+    startInviting,
+    showIncoming,
+    enterRunning,
+    reset,
+    appendInvitees,
+    markUserLeft,
+    isUserLeft,
+    setGroupCall,
+    removeGroupCall,
+    getGroupCall,
+    applyParticipantConnected,
+    applyParticipantDisconnected,
+    applyParticipantRejected,
+    applyParticipantNoAnswer
+  }
+})
diff --git a/apps/web-ele/src/views/im/home/store/uiStore.ts b/apps/web-ele/src/views/im/home/store/uiStore.ts
new file mode 100644
index 000000000..93d0b6ebd
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/store/uiStore.ts
@@ -0,0 +1,155 @@
+import type { GroupLite, User } from '../types'
+
+import { reactive, ref } from 'vue'
+
+import { acceptHMRUpdate, defineStore } from 'pinia'
+
+import { ImFriendAddSource } from '../../utils/constants'
+
+/**
+ * IM 全局 UI store
+ *
+ * 收纳标准：触发点 N 个、挂载点想保持 1 个的浮层状态。
+ * 任意位置都可能 open，但 DOM 上只想留一份实例 → 走 store 派发，
+ * 由 `index.vue` 挂一个订阅组件统一渲染。
+ */
+export const useImUiStore = defineStore('imUiStore', () => {
+  // ==================== 用户名片 UserInfoCard ====================
+  // 用户名片悬浮卡
+
+  const userInfoCard = reactive({
+    show: false,
+    user: null as null | User,
+    position: { x: 0, y: 0 },
+    // addSource / addSourceExtra 跟随触发点带入「加好友」来源（群成员入口 = GROUP + 群名；其余默认搜索）
+    addSource: ImFriendAddSource.SEARCH as number,
+    addSourceExtra: '' as string
+  })
+
+  /** 打开用户名片 */
+  function openUserInfoCard(
+    user: User,
+    position: { x: number; y: number },
+    addSource: number = ImFriendAddSource.SEARCH,
+    addSourceExtra: string = ''
+  ) {
+    const viewportWidth = document.documentElement.clientWidth
+    const viewportHeight = document.documentElement.clientHeight
+    userInfoCard.user = user
+    userInfoCard.position.x = Math.min(position.x, viewportWidth - 350)
+    userInfoCard.position.y = Math.min(position.y, viewportHeight - 220)
+    userInfoCard.addSource = addSource
+    userInfoCard.addSourceExtra = addSourceExtra
+    userInfoCard.show = true
+  }
+
+  /** 鼠标点击位置 + 20px 横向偏移打开名片：避免名片直接覆盖触发元素，对齐头像 / 名片消息等点击交互的统一观感 */
+  function openUserInfoCardAtEvent(
+    user: User,
+    e: MouseEvent,
+    addSource: number = ImFriendAddSource.SEARCH,
+    addSourceExtra: string = ''
+  ) {
+    openUserInfoCard(user, { x: e.clientX + 20, y: e.clientY }, addSource, addSourceExtra)
+  }
+
+  /** 关闭用户名片 */
+  function closeUserInfoCard() {
+    userInfoCard.show = false
+  }
+
+  // ==================== 群名片 GroupInfoCard ====================
+
+  const groupInfoCard = reactive({
+    show: false,
+    group: null as GroupLite | null,
+    position: { x: 0, y: 0 }
+  })
+
+  /** 鼠标点击位置 + 20px 横向偏移打开群名片，对齐 UserInfoCard 的统一观感 */
+  function openGroupInfoCardAtEvent(group: GroupLite, e: MouseEvent) {
+    const viewportWidth = document.documentElement.clientWidth
+    const viewportHeight = document.documentElement.clientHeight
+    groupInfoCard.group = group
+    groupInfoCard.position.x = Math.min(e.clientX + 20, viewportWidth - 350)
+    groupInfoCard.position.y = Math.min(e.clientY, viewportHeight - 220)
+    groupInfoCard.show = true
+  }
+
+  /** 关闭群名片 */
+  function closeGroupInfoCard() {
+    groupInfoCard.show = false
+  }
+
+  // ==================== 右键菜单 ContextMenu ====================
+  // 右键菜单虽然是一个组件挂在主壳上，但其触发时机分散在各列表
+  interface ContextMenuItem {
+    key: string
+    name: string
+    disabled?: boolean
+    divided?: boolean // 是否在该项上方显示分割线（用于把"删除"等危险操作与上面的常规项隔开）
+    danger?: boolean // 是否走危险操作样式（红色文字）
+    icon?: string // 可选 iconify 图标名（如 ant-design:delete-outlined）；不传则不渲染前置图标
+  }
+
+  const contextMenu = reactive({
+    show: false,
+    position: { x: 0, y: 0 },
+    items: [] as ContextMenuItem[],
+    /** 选中回调：每次 open 时由调用方传入 */
+    onSelect: null as ((item: ContextMenuItem) => void) | null
+  })
+
+  /** 打开右键菜单 */
+  function openContextMenu(
+    position: { x: number; y: number },
+    items: ContextMenuItem[],
+    onSelect: (item: ContextMenuItem) => void
+  ) {
+    contextMenu.position = position
+    contextMenu.items = items
+    contextMenu.onSelect = onSelect
+    contextMenu.show = true
+  }
+
+  /** 关闭右键菜单 */
+  function closeContextMenu() {
+    contextMenu.show = false
+    contextMenu.onSelect = null
+  }
+
+  // ==================== 消息 Tab 跳转下一未读 ====================
+  // 在 ImHomeConversation 页面再次点击工具栏「消息」时触发；
+  // 通过递增 nonce 让 conversation/index.vue 的 watch 感知后执行滚动 + 高亮
+
+  const nextUnreadJumpNonce = ref(0)
+
+  /** 请求滚动到下一个未读会话（含免打扰） */
+  function requestNextUnreadJump() {
+    nextUnreadJumpNonce.value++
+  }
+
+  return {
+    userInfoCard,
+    openUserInfoCard,
+    openUserInfoCardAtEvent,
+    closeUserInfoCard,
+
+    groupInfoCard,
+    openGroupInfoCardAtEvent,
+    closeGroupInfoCard,
+
+    contextMenu,
+    openContextMenu,
+    closeContextMenu,
+
+    nextUnreadJumpNonce,
+    requestNextUnreadJump
+  }
+})
+
+// dev: 让 Pinia 的 actions / state 改动支持 HMR，避免每次改 store 都得硬刷
+// 否则 Vite 把新模块推下来后，老 store 实例的 action 闭包仍指向旧函数体
+if (import.meta.hot) {
+  import.meta.hot.accept(acceptHMRUpdate(useImUiStore, import.meta.hot))
+}
diff --git a/apps/web-ele/src/views/im/home/store/websocketStore.ts b/apps/web-ele/src/views/im/home/store/websocketStore.ts
new file mode 100644
index 000000000..682311ef3
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/store/websocketStore.ts
@@ -0,0 +1,1173 @@
+import type {
+  Group,
+  ImGroupMessageNotification,
+  ImMessageReadNotification,
+  ImMessageReceiptNotification,
+  ImNoConversationNotification,
+  ImNotificationWebSocketDTO,
+  ImPrivateMessageNotification,
+  Message,
+  WebSocketFrame
+} from '../types'
+
+import type { ImChannelMessageApi } from '#/api/im/message/channel'
+
+import { acceptHMRUpdate, defineStore } from 'pinia'
+
+import { readChannelMessages as apiReadChannelMessages } from '#/api/im/message/channel'
+import { readGroupMessages as apiReadGroupMessages } from '#/api/im/message/group'
+import { readPrivateMessages as apiReadPrivateMessages } from '#/api/im/message/private'
+import { getCurrentUserId, getRefreshToken } from '#/views/im/utils/auth'
+
+import { buildChannelConversationStub } from '../../utils/channel'
+import {
+  MESSAGE_GROUP_READ_ENABLED,
+  MESSAGE_PRIVATE_READ_ENABLED,
+  WS_RECONNECT_BASE_MS,
+  WS_RECONNECT_JITTER_MS,
+  WS_RECONNECT_MAX_MS
+} from '../../utils/config'
+import {
+  ImContentType,
+  ImConversationType,
+  ImMessageReceiptStatus,
+  ImMessageStatus,
+  ImRtcCallMediaType,
+  ImRtcParticipantStatus,
+  ImWebSocketMessageType,
+  isFriendChatTip,
+  isFriendNotification,
+  isGroupRequestNotification,
+  isNormalMessage
+} from '../../utils/constants'
+import {
+  getPrivateMessagePeerId,
+  playAudioTip,
+  resolveCallEndReasonText
+} from '../../utils/message'
+import { getFriendDisplayName, getGroupDisplayName } from '../../utils/user'
+import { useConversationStore } from './conversationStore'
+import { type FriendNotificationPayload, useFriendStore } from './friendStore'
+import { useGroupRequestStore } from './groupRequestStore'
+import { useGroupStore } from './groupStore'
+import { useMessageStore } from './messageStore'
+import {
+  type ImRtcCallEndNotification,
+  type ImRtcCallNotification,
+  type ImRtcParticipantConnectedNotification,
+  type ImRtcParticipantDisconnectedNotification,
+  useRtcStore
+} from './rtcStore'
+
+/** FRIEND_DELETE 帧 payload 是否带 clear=true：clear 语义是清会话本身，跳过气泡渲染 */
+const isFriendDeleteWithClear = (frame: ImPrivateMessageNotification): boolean => {
+  if (frame.type !== ImContentType.FRIEND_DELETE) {
+    return false
+  }
+  try {
+    const payload = JSON.parse(frame.content || '{}') as { clear?: boolean }
+    return payload.clear === true
+  } catch {
+    return false
+  }
+}
+
+/** 从私聊消息帧解析好友通知 payload */
+const parseFriendNotificationPayload = (
+  frame: ImPrivateMessageNotification
+): FriendNotificationPayload => JSON.parse(frame.content || '{}') as FriendNotificationPayload
+
+/** 私聊消息帧是否可推断好友对端 */
+const isPrivateMessageNotification = (
+  frame: ImNoConversationNotification | ImPrivateMessageNotification
+): frame is ImPrivateMessageNotification => 'senderId' in frame && 'receiverId' in frame
+
+const RTC_LIVEKIT_PROTOCOLS = new Set(['http:', 'https:', 'ws:', 'wss:'])
+const RTC_MEDIA_TYPES = new Set<number>(Object.values(ImRtcCallMediaType))
+
+/** 忽略普通实时帧持久化失败 */
+function ignoreRealtimePersistError(promise: Promise<void>): void {
+  void promise.catch(() => undefined)
+}
+
+interface WebSocketListenerSet {
+  close: (event: CloseEvent) => void
+  error: (event: Event) => void
+  message: (event: MessageEvent) => void
+  open: (event: Event) => void
+}
+
+const websocketListenerMap = new WeakMap<WebSocket, WebSocketListenerSet>()
+
+/** 绑定 WebSocket 事件 */
+function bindWebSocketListeners(socket: WebSocket, listeners: WebSocketListenerSet): void {
+  websocketListenerMap.set(socket, listeners)
+  socket.addEventListener('open', listeners.open)
+  socket.addEventListener('message', listeners.message)
+  socket.addEventListener('close', listeners.close)
+  socket.addEventListener('error', listeners.error)
+}
+
+/** 解绑 WebSocket 事件 */
+function unbindWebSocketListeners(socket: WebSocket): void {
+  const listeners = websocketListenerMap.get(socket)
+  if (!listeners) {
+    return
+  }
+  socket.removeEventListener('open', listeners.open)
+  socket.removeEventListener('message', listeners.message)
+  socket.removeEventListener('close', listeners.close)
+  socket.removeEventListener('error', listeners.error)
+  websocketListenerMap.delete(socket)
+}
+
+/** 校验 LiveKit 连接地址 */
+function isValidLiveKitUrl(url?: string): boolean {
+  if (!url) {
+    return false
+  }
+  try {
+    return RTC_LIVEKIT_PROTOCOLS.has(new URL(url).protocol)
+  } catch {
+    return false
+  }
+}
+
+/** 校验来电信令载荷 */
+function isValidRtcInvitePayload(payload: ImRtcCallNotification): boolean {
+  if (!payload.room || !payload.token || !isValidLiveKitUrl(payload.livekitUrl)) {
+    return false
+  }
+  if (!RTC_MEDIA_TYPES.has(payload.mediaType) || !payload.inviterUserId) {
+    return false
+  }
+  if (payload.conversationType === ImConversationType.PRIVATE) {
+    return true
+  }
+  return payload.conversationType === ImConversationType.GROUP && !!payload.groupId
+}
+
+/**
+ * WebSocket 私聊 DTO -> 前端 Message；targetId 是会话主键（对端 userId）
+ * 不写发送人名字段：渲染层走 utils/user 实时算（备注 / 群昵称变更后历史消息自动刷新）
+ */
+const convertPrivateMessage = (
+  websocketMessage: ImPrivateMessageNotification,
+  currentUserId: number
+): Message => ({
+  id: websocketMessage.id,
+  clientMessageId: websocketMessage.clientMessageId,
+  type: websocketMessage.type,
+  content: websocketMessage.content,
+  status: websocketMessage.status,
+  receiptStatus: websocketMessage.receiptStatus,
+  sendTime: new Date(websocketMessage.sendTime).getTime(),
+  senderId: websocketMessage.senderId,
+  targetId: getPrivateMessagePeerId(websocketMessage, currentUserId),
+  selfSend: websocketMessage.senderId === currentUserId
+})
+
+/**
+ * WebSocket 群聊 DTO -> 前端 Message
+ * 带 atUserIds / receiverUserIds 给 @ 标记和定向接收用；
+ * receiptStatus / readCount 让多端同步收到自己发的群消息时回执 UI 立刻就有数据
+ */
+const convertGroupMessage = (
+  websocketMessage: ImGroupMessageNotification,
+  currentUserId: number
+): Message => ({
+  id: websocketMessage.id,
+  clientMessageId: websocketMessage.clientMessageId,
+  type: websocketMessage.type,
+  content: websocketMessage.content,
+  status: websocketMessage.status,
+  sendTime: new Date(websocketMessage.sendTime).getTime(),
+  senderId: websocketMessage.senderId,
+  targetId: websocketMessage.groupId,
+  selfSend: websocketMessage.senderId === currentUserId,
+  atUserIds: websocketMessage.atUserIds || [],
+  receiverUserIds: websocketMessage.receiverUserIds || [],
+  receiptStatus: websocketMessage.receiptStatus,
+  readCount: websocketMessage.readCount
+})
+
+/**
+ * IM WebSocket Store
+ *
+ * 职责（不只是连通信，也是后端 IM 事件的统一入口 → 联动 conversationStore / friendStore / groupStore）：
+ *
+ * 1. 链路管理：建连 / 断连 / 心跳保活 / 自动重连
+ * 2. 帧分发：dispatchFrame → dispatchPrivateFrame / dispatchGroupFrame，按会话和内容类型分流
+ * 3. 缓冲：初始化加载期（conversationStore.loading=true）暂存消息，等 pull 完成后由 useMessagePuller 调 flushBuffer 回放
+ * 4. 事件处理（按类型分发到对应 handle*，联动 conversation / friend / group store）：
+ *    - 普通消息（TEXT / IMAGE / FILE / VOICE / VIDEO）：入库 + 当前会话自动已读 / 提示音
+ *    - 已读 / 回执（READ / RECEIPT）：多端已读同步、对方读后回执
+ *    - 好友变更（FRIEND_*）：同步 friendStore + 级联刷新私聊会话；FRIEND_ADD / FRIEND_DELETE 额外插入会话气泡
+ *    - 群个人信号（GROUP_MEMBER_SETTING_UPDATE）：同步 groupStore + 级联刷新群聊会话
+ *    - 群成员昵称变更（GROUP_MEMBER_NICKNAME_UPDATE）：同步 groupStore，不插入消息列表
+ *    - 群广播事件（GROUP_*）：走 handleGroupMessage + applyGroupNotification 旁路（含 DISSOLVE / QUIT / KICK 自判清群）
+ */
+export const useImWebSocketStore = defineStore('imWebSocketStore', {
+  state: () => ({
+    socket: null as null | WebSocket,
+    isConnected: false,
+    reconnectTimer: null as null | ReturnType<typeof setTimeout>,
+    /** 连续重连失败次数；onopen 成功 / disconnect 主动断开后清零，用于指数退避 */
+    reconnectAttempts: 0,
+    heartbeatTimer: null as null | ReturnType<typeof setInterval>,
+    messageBuffer: [] as Array<
+      | { conversationType: typeof ImConversationType.CHANNEL; payload: ImChannelMessageApi.ChannelMessageRespVO }
+      | {
+          conversationType: typeof ImConversationType.GROUP
+          payload: ImGroupMessageNotification
+        }
+      | {
+          conversationType: typeof ImConversationType.PRIVATE
+          payload: ImPrivateMessageNotification
+        }
+    > // 初始化加载期内，先把普通消息丢进缓冲区，pull 完成后再一次性回放
+  }),
+
+  actions: {
+    /**
+     * 取出缓冲区消息并清空（由 useMessagePuller 在 pull 完成后调用，统一回放给 conversationStore）
+     * 配合 messageBuffer 实现：在 conversationStore.loading 期间收到的 WS 消息先暂存，避免和 pull 的 minId 游标打架
+     */
+    flushBuffer() {
+      const msgs = [...this.messageBuffer]
+      this.messageBuffer = []
+      return msgs
+    },
+
+    /** 直接丢弃缓冲帧不回放（cancelPull / 离开 IM 调用，防止下次进 IM 把旧 session 帧回放进新 store） */
+    discardBuffer() {
+      this.messageBuffer = []
+    },
+
+    /**
+     * 连接 WebSocket
+     * 复用 yudao 内置 /infra/ws 通道，后端通过 sendObject(type, content) 下发
+     *
+     * 调用契约：切账号 / token 刷新前必须先 `disconnect()` 再 `connect()`；
+     * 本方法不感知 token 变化，旧 socket 在 CONNECTING / OPEN 状态会直接复用旧 token，可能拿到错误身份
+     */
+    connect() {
+      // 鉴权用 refreshToken（生命周期更长；access token 过期后服务端会通过 frame 通知重登）
+      const refreshToken = getRefreshToken()
+      if (!refreshToken) {
+        console.warn('[IM WS] refreshToken 为空，跳过连接')
+        return
+      }
+      // 旧 socket 还在 CONNECTING / OPEN 直接复用，避免叠加多份 onmessage 监听导致重复消息 / 提示音 / 已读上报
+      const existingSocket = this.socket
+      if (
+        existingSocket &&
+        (existingSocket.readyState === WebSocket.OPEN ||
+          existingSocket.readyState === WebSocket.CONNECTING)
+      ) {
+        return
+      }
+      // 旧 socket 已 CLOSING / CLOSED：解绑回调 + 清引用再 new，避免老 handler 仍持有 store 引用阻碍 GC
+      if (existingSocket) {
+        unbindWebSocketListeners(existingSocket)
+        this.socket = null
+      }
+      const url = `${this.buildWsUrl()}/infra/ws?token=${refreshToken}`
+      const socket = new WebSocket(url)
+      this.socket = socket
+
+      bindWebSocketListeners(socket, {
+        // 连接建立：标记上线 + 启动心跳保活；重连退避计数归零
+        open: () => {
+          this.isConnected = true
+          this.reconnectAttempts = 0
+          console.log('[IM WS] connected')
+          this.startHeartbeat()
+        },
+
+        // 收到帧：'pong' 是心跳应答直接吞掉；其余按 WebSocketFrame 解析后交给 dispatchFrame 分流
+        message: (event) => {
+          if (event.data === 'pong') {
+            return
+          }
+          try {
+            const frame = JSON.parse(event.data) as WebSocketFrame
+            this.dispatchFrame(frame)
+          } catch (error) {
+            console.error('[IM WS] message parse error:', error)
+          }
+        },
+
+        // 服务端关闭 / 网络断：标记下线，按指数退避自动重连
+        close: () => {
+          this.isConnected = false
+          console.log('[IM WS] disconnected')
+          this.reconnect()
+        },
+
+        // 异常时不主动 reconnect，主动 close() 让 close 成为唯一重连入口
+        error: (error) => {
+          console.error('[IM WS] error:', error)
+          this.isConnected = false
+          this.socket?.close()
+        }
+      })
+    },
+
+    /** 拼接 WebSocket 基础地址 */
+    buildWsUrl(): string {
+      // VITE_BASE_URL 可能是 http:// 或 https:// 开头，替换成 ws:// 或 wss://；如果没配置，就用当前页面的协议 + host
+      const baseUrl = (import.meta as any).env?.VITE_BASE_URL as string | undefined
+      if (baseUrl && baseUrl.length > 0) {
+        return baseUrl.replace(/^http/, 'ws')
+      }
+      // 当前页面协议 + host（如 http://localhost:8080），替换成 ws://localhost:8080
+      const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'
+      const host = window.location.host
+      return `${protocol}//${host}`
+    },
+
+    /**
+     * 按 IM 通知帧分发
+     */
+    dispatchFrame(frame: WebSocketFrame) {
+      if (frame.type !== ImWebSocketMessageType.NOTIFICATION) {
+        console.debug('[IM WS] 未识别事件', frame)
+        return
+      }
+
+      const notification = this.safeParse(frame.content) as ImNotificationWebSocketDTO | null
+      if (!notification?.payload || !notification.contentType) {
+        return
+      }
+      const payload = {
+        ...notification.payload,
+        type: notification.contentType
+      }
+      switch (notification.conversationType) {
+        case ImConversationType.CHANNEL: {
+          this.dispatchChannelFrame(payload as ImChannelMessageApi.ChannelMessageRespVO)
+          break
+        }
+        case ImConversationType.GROUP: {
+          this.dispatchGroupFrame(payload as ImGroupMessageNotification)
+          break
+        }
+        case ImConversationType.NONE: {
+          this.dispatchNoConversationFrame(payload as ImNoConversationNotification)
+          break
+        }
+        case ImConversationType.PRIVATE: {
+          this.dispatchPrivateFrame(payload as ImPrivateMessageNotification)
+          break
+        }
+        default: {
+          console.debug('[IM WS] 未识别通知', notification)
+        }
+      }
+    },
+
+    /**
+     * 无会话通知分发
+     */
+    dispatchNoConversationFrame(websocketMessage: ImNoConversationNotification) {
+      if (isFriendNotification(websocketMessage.type)) {
+        this.handleFriendNotification(websocketMessage)
+        return
+      }
+      if (isGroupRequestNotification(websocketMessage.type)) {
+        this.handleGroupRequestNotification(websocketMessage)
+        return
+      }
+      switch (websocketMessage.type) {
+        case ImContentType.RTC_CALL:
+        case ImContentType.RTC_PARTICIPANT_CONNECTED:
+        case ImContentType.RTC_PARTICIPANT_DISCONNECTED: {
+          this.handleRtcSignaling(websocketMessage)
+          break
+        }
+        default: {
+          console.debug('[IM WS] 未识别无会话通知', websocketMessage)
+        }
+      }
+    },
+
+    /**
+     * 频道帧分发：按 payload.type 分到 READ（多端已读同步）或普通素材推送
+     */
+    dispatchChannelFrame(websocketMessage: ImChannelMessageApi.ChannelMessageRespVO) {
+      if (websocketMessage.type === ImContentType.READ) {
+        this.handleChannelRead(websocketMessage)
+        return
+      }
+      ignoreRealtimePersistError(this.handleChannelMessage(websocketMessage))
+    },
+
+    /** 频道 READ：自己其它终端在某频道里标为已读，本端同步清零该频道未读 */
+    handleChannelRead(websocketMessage: ImChannelMessageApi.ChannelMessageRespVO) {
+      void useConversationStore()
+        .applyConversationReadList([
+          {
+            id: websocketMessage.id,
+            conversationType: ImConversationType.CHANNEL,
+            targetId: websocketMessage.channelId,
+            messageId: websocketMessage.id
+          }
+        ])
+        .catch((error) => console.warn('[IM WS] 频道已读同步失败', error))
+    },
+
+    /**
+     * 频道消息实时入会话；频道消息单向 + 无状态机，直接 insertMessage 即可
+     * pull 与 WS 拿到同一条 id 时，messageStore.insertMessage 内部按 id 去重，不会重复
+     */
+    handleChannelMessage(websocketMessage: ImChannelMessageApi.ChannelMessageRespVO): Promise<void> {
+      const conversationStore = useConversationStore()
+      const messageStore = useMessageStore()
+      // 离线加载期间先缓冲，等 pull 完成后再统一回放，避免重复或顺序错乱
+      if (conversationStore.loading) {
+        this.messageBuffer.push({
+          conversationType: ImConversationType.CHANNEL,
+          payload: websocketMessage
+        })
+        return Promise.resolve()
+      }
+      const sendTimeMs =
+        typeof websocketMessage.sendTime === 'number'
+          ? websocketMessage.sendTime
+          : new Date(websocketMessage.sendTime).getTime()
+      const conversation = conversationStore.getConversation(
+        ImConversationType.CHANNEL,
+        websocketMessage.channelId
+      )
+      const isActive =
+        conversationStore.activeConversation?.type === ImConversationType.CHANNEL &&
+        conversationStore.activeConversation?.targetId === websocketMessage.channelId
+      // 频道单向订阅，receiptStatus 表达「我是否已读这条」：会话打开即已读 DONE，否则 PENDING（与 pull 口径一致）
+      const persistPromise = messageStore.insertMessage(
+        buildChannelConversationStub(websocketMessage.channelId),
+        {
+          id: websocketMessage.id,
+          clientMessageId: '',
+          type: websocketMessage.type,
+          content: websocketMessage.content,
+          status: ImMessageStatus.NORMAL,
+          receiptStatus: isActive ? ImMessageReceiptStatus.DONE : ImMessageReceiptStatus.PENDING,
+          sendTime: sendTimeMs,
+          senderId: 0,
+          targetId: websocketMessage.channelId,
+          selfSend: false,
+          materialId: websocketMessage.materialId
+        }
+      )
+      if (isActive) {
+        // 窗口打开 = 已读：本端清未读 + 上报服务端读位置，避免读位置滞后
+        conversationStore.markConversationRead(
+          ImConversationType.CHANNEL,
+          websocketMessage.channelId,
+          websocketMessage.id
+        )
+        apiReadChannelMessages(websocketMessage.channelId, websocketMessage.id).catch((error) => {
+          console.warn('[IM WS] 频道自动已读上报失败', error)
+        })
+      } else if (!conversation?.silent && isNormalMessage(websocketMessage.type)) {
+        // 非当前会话且未免打扰：响一下提示音
+        playAudioTip()
+      }
+      return persistPromise
+    },
+
+    /** content 既可能已是对象也可能是 JSON 字符串（后端用 Map 序列化下发） */
+    safeParse(raw: unknown): null | Record<string, any> {
+      if (!raw) {
+        return null
+      }
+      if (typeof raw === 'object') {
+        return raw as Record<string, any>
+      }
+      try {
+        return JSON.parse(raw as string)
+      } catch (error) {
+        console.error('[IM WS] content 解析失败', error)
+        return null
+      }
+    },
+
+    // ==================== 普通消息 ====================
+
+    /**
+     * 私聊统一帧分发：按 payload.type（ImContentType）分到已读 / 回执 / 好友通知 / 普通消息
+     *
+     * 消息通知、已读通知、回执通知由外层 contentType 统一分发
+     */
+    dispatchPrivateFrame(websocketMessage: ImPrivateMessageNotification) {
+      try {
+        switch (websocketMessage.type) {
+          case ImContentType.READ: {
+            this.handlePrivateRead(websocketMessage as ImMessageReadNotification)
+            break
+          }
+          case ImContentType.RECEIPT: {
+            this.handlePrivateReceipt(websocketMessage as ImMessageReceiptNotification)
+            break
+          }
+          case ImContentType.RTC_CALL_END: {
+            // 入库 + 关闭通话窗 + 渲染聊天 tip（私聊场景）
+            this.handleRtcCallEnd(websocketMessage)
+            ignoreRealtimePersistError(this.handlePrivateMessage(websocketMessage))
+            break
+          }
+          default: {
+            if (isFriendChatTip(websocketMessage.type)) {
+              this.handleFriendNotification(websocketMessage)
+              // FRIEND_DELETE 的 clear=true 语义是清会话本身，跳过气泡避免在已清会话里写入虚拟消息
+              if (!isFriendDeleteWithClear(websocketMessage)) {
+                ignoreRealtimePersistError(this.handlePrivateMessage(websocketMessage))
+              }
+            } else {
+              // TEXT / IMAGE / FILE / VOICE / VIDEO 等普通消息
+              ignoreRealtimePersistError(this.handlePrivateMessage(websocketMessage))
+            }
+          }
+        }
+      } catch (error) {
+        // 单条帧的处理异常不应阻断后续帧；打印完整 websocketMessage 便于排查
+        console.warn('[IM WS] dispatchPrivateFrame 处理失败', websocketMessage, error)
+      }
+    },
+
+    /**
+     * 群聊统一帧分发：按 payload.type（ImContentType）分到已读 / 回执 / 群个人信号 / 普通消息
+     *
+     * GROUP_MEMBER_SETTING_UPDATE / GROUP_MEMBER_NICKNAME_UPDATE 是成员资料同步信号；其它群广播事件走 handleGroupMessage 入库 + 触发 applyGroupNotification 旁路
+     */
+    dispatchGroupFrame(websocketMessage: ImGroupMessageNotification) {
+      try {
+        switch (websocketMessage.type) {
+          case ImContentType.GROUP_MEMBER_NICKNAME_UPDATE: {
+            this.handleGroupMemberNicknameUpdate(websocketMessage)
+            break
+          }
+          case ImContentType.GROUP_MEMBER_SETTING_UPDATE: {
+            this.handleGroupMemberSettingUpdate(websocketMessage)
+            break
+          }
+          case ImContentType.READ: {
+            this.handleGroupRead(websocketMessage as ImMessageReadNotification)
+            break
+          }
+          case ImContentType.RECEIPT: {
+            this.handleGroupReceipt(websocketMessage as ImMessageReceiptNotification)
+            break
+          }
+          case ImContentType.RTC_CALL_END: {
+            // 入库 + 移除胶囊条 + 关闭通话窗（如果当前在该群通话内）
+            this.handleRtcCallEnd(websocketMessage)
+            ignoreRealtimePersistError(this.handleGroupMessage(websocketMessage))
+            break
+          }
+          case ImContentType.RTC_CALL_START: {
+            // 入库 + 渲染聊天 tip；胶囊条状态走 1602/1603，本帧不动 rtcStore，避免与首次填充竞争
+            ignoreRealtimePersistError(this.handleGroupMessage(websocketMessage))
+            break
+          }
+          default: {
+            // TEXT / IMAGE / FILE / VOICE / VIDEO + GROUP_* 群广播事件
+            ignoreRealtimePersistError(this.handleGroupMessage(websocketMessage))
+          }
+        }
+      } catch (error) {
+        // 单条帧的处理异常不应阻断后续帧；打印完整 websocketMessage 便于排查
+        console.warn('[IM WS] dispatchGroupFrame 处理失败', websocketMessage, error)
+      }
+    },
+
+    /**
+     * 私聊普通消息（TEXT / IMAGE / FILE / VOICE / VIDEO）入库 + 自动已读
+     *
+     * 流程：
+     * 1. 离线加载期缓冲（避开与 pull 回填的竞态）
+     * 2. 计算 selfSend / peerId 维度，拉好友信息回填展示字段
+     * 3. 撤回 TIP 直接转走 recallMessage，不进消息列表
+     * 4. 构造前端 Message，插入到对应私聊会话
+     * 5. 当前会话激活时自动上报已读；否则非免打扰响提示音
+     */
+    handlePrivateMessage(websocketMessage: ImPrivateMessageNotification): Promise<void> {
+      const conversationStore = useConversationStore()
+      const friendStore = useFriendStore()
+      const currentUserId = getCurrentUserId()
+
+      // 0. 防御层：senderId / receiverId 均不含当前用户的私聊帧直接丢弃，避免后端路由 / 多端串号污染会话
+      //    （FRIEND_* 等系统通知也走这条通道，但 fromUserId=senderId、toUserId=receiverId 仍是当前用户视角）
+      if (
+        currentUserId &&
+        websocketMessage.senderId !== currentUserId &&
+        websocketMessage.receiverId !== currentUserId
+      ) {
+        console.warn('[IM WS] 丢弃不属于当前用户的私聊帧', websocketMessage)
+        return Promise.resolve()
+      }
+
+      // 1. 离线加载期间先缓冲，等 pull 完成后再统一回放，避免重复或顺序错乱
+      if (conversationStore.loading) {
+        this.messageBuffer.push({
+          conversationType: ImConversationType.PRIVATE,
+          payload: websocketMessage
+        })
+        return Promise.resolve()
+      }
+
+      // 2. selfSend / peerId：自己发的消息属于「发给 receiverId 的会话」，别人发的属于「发送者的会话」
+      const selfSend = websocketMessage.senderId === currentUserId
+      const peerId = getPrivateMessagePeerId(websocketMessage, currentUserId)
+      // 未知对端（陌生人加好友前先收到消息等场景）：异步补拉一次，下次再渲染就有 name/avatar
+      const friend = friendStore.getFriend(peerId)
+      if (!friend) {
+        friendStore.fetchFriendInfo(peerId).catch(() => undefined)
+      }
+      // 会话标题永远跟「对端」走（不管谁发的消息）；这里只算一次给 insertMessage 用
+      const peerDisplayName = friend ? getFriendDisplayName(friend) : ''
+
+      // 3. 后端撤回：下发一条 RECALL 消息，content 为 `{"messageId": xxx}`（对齐 ImContentTypeEnum.RECALL → RecallMessage）
+      // 这里拦截下来改走 recallMessage（把原消息更新为 RECALL 态），不让它作为新消息进列表
+      if (websocketMessage.type === ImContentType.RECALL) {
+        return useMessageStore().recallMessage(
+          ImConversationType.PRIVATE,
+          peerId,
+          websocketMessage.content
+        )
+      }
+
+      // 4. 后端 DTO → 前端 Message：发送人名渲染时实时算，不写入消息字段
+      const message = convertPrivateMessage(websocketMessage, currentUserId)
+      const persistPromise = useMessageStore().insertMessage(
+        {
+          type: ImConversationType.PRIVATE,
+          targetId: peerId,
+          name: peerDisplayName || String(peerId),
+          avatar: friend?.avatar || '',
+          silent: friend?.silent
+        },
+        message
+      )
+
+      // 5. 仅对方消息才走「自动已读 / 提示音」分支：自己发的不会触发
+      if (!selfSend) {
+        const conversation = conversationStore.getConversation(ImConversationType.PRIVATE, peerId)
+        const isActive =
+          conversationStore.activeConversation?.type === ImConversationType.PRIVATE &&
+          conversationStore.activeConversation?.targetId === peerId
+        if (isActive) {
+          // 聊天窗口打开 = 实际看到了：本端清未读；私聊已读开启时再上报后端，让对方 UI 立刻切到"已读"
+          // 已读位置直接用刚到的消息 id（这条就是当前会话最大 id）
+          conversationStore.markConversationRead(
+            ImConversationType.PRIVATE,
+            peerId,
+            websocketMessage.id
+          )
+          if (MESSAGE_PRIVATE_READ_ENABLED) {
+            apiReadPrivateMessages(peerId, websocketMessage.id).catch((error) => {
+              console.warn('[IM WS] 自动已读上报失败', error)
+            })
+          }
+        } else if (!conversation?.silent && isNormalMessage(websocketMessage.type)) {
+          // 非当前会话且未免打扰：响一下提示音（带节流，详见 playAudioTip）；FRIEND_* 等系统事件不响
+          playAudioTip()
+        }
+      }
+      return persistPromise
+    },
+
+    /** 私聊 READ 事件：自己的其它终端在对方会话里标为已读，本端同步清零未读；私聊已读关闭时兜底忽略 */
+    handlePrivateRead(websocketMessage: ImMessageReadNotification) {
+      if (!MESSAGE_PRIVATE_READ_ENABLED) {
+        return
+      }
+      if (!websocketMessage.id || !websocketMessage.receiverId) {
+        return
+      }
+      void useConversationStore()
+        .applyConversationReadList([
+          {
+            id: websocketMessage.id,
+            conversationType: ImConversationType.PRIVATE,
+            targetId: websocketMessage.receiverId,
+            messageId: websocketMessage.id
+          }
+        ])
+        .catch((error) => console.warn('[IM WS] 私聊已读同步失败', error))
+    },
+
+    /**
+     * 私聊 RECEIPT 事件：对方读了我的消息，把和对方会话里自己发的消息标为已读
+     * 后端将 maxReadId 编码在通知的 id 字段，
+     * 这里据此卡边界，避免把"回执在路上时刚发的消息"误标为已读；私聊已读关闭时兜底忽略
+     */
+    handlePrivateReceipt(websocketMessage: ImMessageReceiptNotification) {
+      if (!MESSAGE_PRIVATE_READ_ENABLED) {
+        return
+      }
+      if (!websocketMessage.id) {
+        return
+      }
+      if (!websocketMessage.senderId) {
+        return
+      }
+      useMessageStore().applyMessageReadReceipt({
+        conversationType: ImConversationType.PRIVATE,
+        targetId: websocketMessage.senderId,
+        privateReadMaxId: websocketMessage.id
+      })
+    },
+
+    /**
+     * 群聊普通消息入库 + 自动已读（结构与 handlePrivateMessage 对称）
+     *
+     * 流程：
+     * 1. 离线加载期缓冲
+     * 2. 未知群时拉群详情兜底
+     * 3. 撤回 TIP 直接转走
+     * 4. 构造 Message + at 字段，插入到对应群聊会话（发送人名渲染时实时算）
+     * 5. 当前会话激活时自动上报已读（带 lastMessageId）；否则非免打扰响提示音
+     */
+    handleGroupMessage(websocketMessage: ImGroupMessageNotification): Promise<void> {
+      const conversationStore = useConversationStore()
+      const groupStore = useGroupStore()
+      const currentUserId = getCurrentUserId()
+      const selfSend = websocketMessage.senderId === currentUserId
+
+      // 0. 防御层：定向群消息 receiverUserIds 非空且未包含当前用户时丢弃
+      //    自己发的（selfSend）始终通过；全员可见（receiverUserIds 为空 / 缺失）也通过
+      const receiverUserIds = websocketMessage.receiverUserIds
+      if (
+        currentUserId &&
+        !selfSend &&
+        Array.isArray(receiverUserIds) &&
+        receiverUserIds.length > 0 &&
+        !receiverUserIds.includes(currentUserId)
+      ) {
+        console.warn('[IM WS] 丢弃不属于当前用户的定向群消息', websocketMessage)
+        return Promise.resolve()
+      }
+
+      // 1. 离线加载期缓冲（与私聊对称）
+      if (conversationStore.loading) {
+        this.messageBuffer.push({
+          conversationType: ImConversationType.GROUP,
+          payload: websocketMessage
+        })
+        return Promise.resolve()
+      }
+
+      // 2. 未知群时自动拉群详情 + 成员（被拉入群但还没收到 GROUP_CREATE 时的兜底）
+      const group = groupStore.getGroup(websocketMessage.groupId)
+      if (!group) {
+        groupStore.fetchGroupInfo(websocketMessage.groupId).catch(() => undefined)
+      }
+
+      // 3. 后端撤回：下发一条 RECALL 消息，content 为 `{"messageId": xxx}`
+      // 这里拦截下来改走 recallMessage（把原消息更新为 RECALL 态）
+      if (websocketMessage.type === ImContentType.RECALL) {
+        return useMessageStore().recallMessage(
+          ImConversationType.GROUP,
+          websocketMessage.groupId,
+          websocketMessage.content
+        )
+      }
+
+      // 4. 后端 DTO → 前端 Message：发送人名渲染时实时算，不写入消息字段
+      const message = convertGroupMessage(websocketMessage, currentUserId)
+      const persistPromise = useMessageStore().insertMessage(
+        {
+          type: ImConversationType.GROUP,
+          targetId: websocketMessage.groupId,
+          name: group ? getGroupDisplayName(group) : String(websocketMessage.groupId),
+          avatar: group?.avatar || '',
+          silent: group?.silent
+        },
+        message
+      )
+
+      // 5. 仅对方消息才走「自动已读 / 提示音」（与私聊对称）
+      if (!selfSend) {
+        const conversation = conversationStore.getConversation(
+          ImConversationType.GROUP,
+          websocketMessage.groupId
+        )
+        const isActive =
+          conversationStore.activeConversation?.type === ImConversationType.GROUP &&
+          conversationStore.activeConversation?.targetId === websocketMessage.groupId
+        if (isActive) {
+          // 群已读上报需要带 messageId（群消息以"读到第几条"的游标为准，区别于私聊只标 receiverId）；群已读关闭时仅本地清零
+          conversationStore.markConversationRead(
+            ImConversationType.GROUP,
+            websocketMessage.groupId,
+            websocketMessage.id
+          )
+          if (MESSAGE_GROUP_READ_ENABLED) {
+            apiReadGroupMessages(websocketMessage.groupId, websocketMessage.id).catch(
+              (error) => {
+                console.warn('[IM WS] 自动已读上报失败', error)
+              }
+            )
+          }
+        } else if (!conversation?.silent && isNormalMessage(websocketMessage.type)) {
+          // GROUP_* 群广播事件等系统消息不响提示音
+          playAudioTip()
+        }
+      }
+      return persistPromise
+    },
+
+    // ==================== 群聊已读 / 回执 ====================
+
+    /** 群聊 READ：自己其它终端在某群里标为已读，本端同步清零该群未读 + @ 红字；群已读关闭时兜底忽略 */
+    handleGroupRead(websocketMessage: ImMessageReadNotification) {
+      if (!MESSAGE_GROUP_READ_ENABLED) {
+        return
+      }
+      const readMessageId = websocketMessage.readId || websocketMessage.id
+      if (!readMessageId || !websocketMessage.groupId) {
+        return
+      }
+      void useConversationStore()
+        .applyConversationReadList([
+          {
+            id: readMessageId,
+            conversationType: ImConversationType.GROUP,
+            targetId: websocketMessage.groupId,
+            messageId: readMessageId
+          }
+        ])
+        .catch((error) => console.warn('[IM WS] 群聊已读同步失败', error))
+    },
+
+    /** 群聊 RECEIPT：更新某条群消息的 readCount / receiptStatus；群已读关闭时兜底忽略 */
+    handleGroupReceipt(websocketMessage: ImMessageReceiptNotification) {
+      if (!MESSAGE_GROUP_READ_ENABLED) {
+        return
+      }
+      if (!websocketMessage.id || !websocketMessage.groupId) {
+        return
+      }
+      useMessageStore().applyMessageReadReceipt({
+        conversationType: ImConversationType.GROUP,
+        targetId: websocketMessage.groupId,
+        groupMessageId: websocketMessage.id,
+        readCount: websocketMessage.readCount,
+        receiptStatus: websocketMessage.receiptStatus
+      })
+    },
+
+    // ==================== 好友通知（1201-1210 段位） ====================
+
+    /**
+     * 算 FRIEND_ADD / FRIEND_DELETE 帧的「对端 userId」：
+     *    becomeFriends 单条入库后双方收到同一份 payload，payload.friendUserId 固定是 toUserId，本端真正的对端要从帧 sender / receiver 反推
+     */
+    computeFriendPeerId(frame: ImPrivateMessageNotification): number {
+      const currentUserId = getCurrentUserId()
+      return getPrivateMessagePeerId(frame, currentUserId)
+    },
+
+    /**
+     * 好友通知统一入口：按 type 分发到 friendStore 内部 dispatcher
+     */
+    handleFriendNotification(
+      websocketMessage: ImNoConversationNotification | ImPrivateMessageNotification
+    ) {
+      const payload = isPrivateMessageNotification(websocketMessage)
+        ? parseFriendNotificationPayload(websocketMessage)
+        : (websocketMessage as unknown as FriendNotificationPayload)
+      const friendStore = useFriendStore()
+      switch (websocketMessage.type) {
+        case ImContentType.FRIEND_ADD: {
+          friendStore.applyFriendAddNotification(
+            payload,
+            isPrivateMessageNotification(websocketMessage)
+              ? this.computeFriendPeerId(websocketMessage)
+              : payload.friendUserId
+          )
+          break
+        }
+        case ImContentType.FRIEND_BLOCK: {
+          friendStore.applyFriendBlockNotification(payload)
+          break
+        }
+        case ImContentType.FRIEND_DELETE: {
+          friendStore.applyFriendDeleteNotification(
+            payload,
+            isPrivateMessageNotification(websocketMessage)
+              ? this.computeFriendPeerId(websocketMessage)
+              : payload.friendUserId
+          )
+          break
+        }
+        case ImContentType.FRIEND_INFO_UPDATED: {
+          friendStore.applyFriendInfoUpdatedNotification(payload)
+          break
+        }
+        case ImContentType.FRIEND_REQUEST_APPROVED: {
+          friendStore.applyFriendRequestApprovedNotification(payload)
+          break
+        }
+        case ImContentType.FRIEND_REQUEST_RECEIVED: {
+          friendStore.applyFriendRequestReceivedNotification(payload)
+          break
+        }
+        case ImContentType.FRIEND_REQUEST_REJECTED: {
+          friendStore.applyFriendRequestRejectedNotification(payload)
+          break
+        }
+        case ImContentType.FRIEND_UNBLOCK: {
+          friendStore.applyFriendUnblockNotification(payload)
+          break
+        }
+        case ImContentType.FRIEND_UPDATE: {
+          friendStore.applyFriendUpdateNotification(payload)
+          break
+        }
+        default: {
+          console.debug('[IM WS] 未识别好友通知', websocketMessage)
+        }
+      }
+    },
+
+    // ==================== 加群申请通知（1503 / 1505 / 1506） ====================
+
+    /**
+     * 加群申请通知统一入口：分发到 groupRequestStore，驱动横幅 + Drawer 同步
+     */
+    handleGroupRequestNotification(websocketMessage: ImNoConversationNotification) {
+      const payload = websocketMessage as { requestId?: number }
+      if (!payload.requestId) {
+        return
+      }
+      const groupRequestStore = useGroupRequestStore()
+      switch (websocketMessage.type) {
+        case ImContentType.GROUP_REQUEST_APPROVED:
+        case ImContentType.GROUP_REQUEST_REJECTED: {
+          groupRequestStore.removeGroupRequestById(payload.requestId)
+          break
+        }
+        case ImContentType.GROUP_REQUEST_RECEIVED: {
+          groupRequestStore.addGroupRequestById(payload.requestId).catch(() => undefined)
+          break
+        }
+        default: {
+          break
+        }
+      }
+    },
+
+    // ==================== 群关系事件（承载于群聊通道，按 inner type 分流） ====================
+
+    /**
+     * GROUP_MEMBER_SETTING_UPDATE：多端同步成员个人设置变更（silent / groupRemark）
+     *
+     * payload 携带变更字段，按非 null 字段直接局部更新；省一次 fetchGroupMemberList 接口
+     */
+    handleGroupMemberSettingUpdate(websocketMessage: ImGroupMessageNotification) {
+      // content 解析失败由外层 dispatchGroupFrame 的 try-catch 兜底（含 websocketMessage 打印），不重复 catch
+      const payload: { groupRemark?: string; silent?: boolean; } = JSON.parse(
+        websocketMessage.content || '{}'
+      )
+      const groupStore = useGroupStore()
+      const group = groupStore.getGroup(websocketMessage.groupId)
+      if (!group) {
+        return
+      }
+      const fields: Partial<Group> = {}
+      if (payload.silent != null) {
+        fields.silent = payload.silent
+      }
+      if (payload.groupRemark != null) {
+        fields.groupRemark = payload.groupRemark
+      }
+      if (Object.keys(fields).length > 0) {
+        groupStore.updateGroupFields(websocketMessage.groupId, fields)
+      }
+    },
+
+    /** GROUP_MEMBER_NICKNAME_UPDATE：同步成员在群里的昵称 */
+    handleGroupMemberNicknameUpdate(websocketMessage: ImGroupMessageNotification) {
+      useGroupStore().applyGroupNotification(
+        websocketMessage.groupId,
+        websocketMessage.type,
+        websocketMessage.content
+      )
+    },
+
+    // ==================== 心跳 / 重连 ====================
+
+    /** 心跳包：纯文本 'ping'，对应服务端 'pong'（后端这层用纯字符串约定，避免 JSON 解析开销） */
+    sendHeartBeat() {
+      if (this.socket && this.isConnected) {
+        this.socket.send('ping')
+      }
+    },
+
+    /** 主动断开（切换用户 / 退出登录时用）：关 socket + 停心跳 + 取消待重连 */
+    disconnect() {
+      if (this.socket) {
+        // close() 异步触发 onclose / onerror，回调里会无条件 reconnect；
+        // 主动关闭路径必须先全部解绑，否则 onclose 会引发自动重连，CONNECTING 期间的 in-flight message 也可能被老 onmessage 投递到 stale 上下文
+        unbindWebSocketListeners(this.socket)
+        this.socket.close()
+        this.socket = null
+      }
+      // onclose 已被解绑，不会再帮我们设 isConnected=false，这里手动复位
+      this.isConnected = false
+      this.stopHeartbeat()
+      if (this.reconnectTimer) {
+        clearTimeout(this.reconnectTimer)
+        this.reconnectTimer = null
+      }
+      // 主动断开（切账号 / 退出）：清零退避计数，下次 connect 重新从最短间隔起算
+      this.reconnectAttempts = 0
+    },
+
+    /**
+     * 自动重连：指数退避 base * 2^attempt（封顶 max）+ 0~jitter ms 随机偏移
+     *
+     * onclose 是唯一入口；onerror 不再调本方法（浏览器规范两者必同时触发，避免计数 +2）
+     * 不设次数上限，频率封顶在 WS_RECONNECT_MAX_MS（约 30s）持续重试，直到链路恢复或主动 disconnect
+     */
+    reconnect() {
+      this.stopHeartbeat()
+      if (this.reconnectTimer) {
+        clearTimeout(this.reconnectTimer)
+        this.reconnectTimer = null
+      }
+      const backoff = Math.min(
+        WS_RECONNECT_BASE_MS * 2 ** this.reconnectAttempts,
+        WS_RECONNECT_MAX_MS
+      )
+      const delay = backoff + Math.floor(Math.random() * WS_RECONNECT_JITTER_MS)
+      this.reconnectAttempts++
+      console.log(`[IM WS] reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`)
+      this.reconnectTimer = setTimeout(() => {
+        this.connect()
+      }, delay)
+    },
+
+    /** 心跳 5 秒一次，保活 + 探活（链路断了 onclose 会触发，由 reconnect 兜底） */
+    startHeartbeat() {
+      if (this.heartbeatTimer) clearInterval(this.heartbeatTimer)
+      this.heartbeatTimer = setInterval(() => {
+        if (this.socket && this.isConnected) {
+          this.sendHeartBeat()
+        }
+      }, 5000)
+    },
+
+    /** 停心跳：disconnect / 重连前调，避免老 timer 在新 socket 上继续触发 sendHeartBeat */
+    stopHeartbeat() {
+      if (this.heartbeatTimer) {
+        clearInterval(this.heartbeatTimer)
+        this.heartbeatTimer = null
+      }
+    },
+
+    // ==================== 实时通话信令分发 ====================
+
+    /**
+     * 通话信令分发：1601 RTC_CALL（按 status 区分 INVITING / JOINED / REJECTED / NO_ANSWER / LEFT）+ 1602 / 1603 参与者加入 / 离开
+     * <p>
+     * 单一 dispatcher，按 type 分发到 rtcStore
+     */
+    handleRtcSignaling(websocketMessage: ImNoConversationNotification) {
+      const rtcStore = useRtcStore()
+      switch (websocketMessage.type) {
+        case ImContentType.RTC_CALL: {
+          const payload = websocketMessage as unknown as ImRtcCallNotification
+          switch (payload.status) {
+            case ImRtcParticipantStatus.INVITING: {
+              if (!isValidRtcInvitePayload(payload)) {
+                console.warn('[IM WS] RTC_CALL invite payload 不合法', payload)
+                return
+              }
+              // 当前已在通话中：忽略新来电；后端层面也会拒绝，这里是兜底
+              if (!rtcStore.isActive) {
+                rtcStore.showIncoming(payload)
+              }
+              break
+            }
+            case ImRtcParticipantStatus.JOINED:
+            case ImRtcParticipantStatus.LEFT: {
+              // ACCEPT / HUNGUP 暂不需要本端额外响应；rtcStore 状态由 1602/1603 + END 维护
+              break
+            }
+            case ImRtcParticipantStatus.NO_ANSWER: {
+              // 群通话单人振铃超时；信令独立保留语义，处理与 REJECTED 一致
+              rtcStore.applyParticipantNoAnswer(payload)
+              break
+            }
+            case ImRtcParticipantStatus.REJECTED: {
+              rtcStore.applyParticipantRejected(payload)
+              break
+            }
+            default: {
+              console.warn('[IM WS] 未识别的 RTC_CALL status', payload)
+            }
+          }
+          return
+        }
+        case ImContentType.RTC_PARTICIPANT_CONNECTED: {
+          const payload = websocketMessage as unknown as ImRtcParticipantConnectedNotification
+          if (payload?.room && payload.userId) {
+            rtcStore.applyParticipantConnected(payload)
+          }
+          return
+        }
+        case ImContentType.RTC_PARTICIPANT_DISCONNECTED: {
+          const payload = websocketMessage as unknown as ImRtcParticipantDisconnectedNotification
+          if (payload?.room && payload.userId) {
+            rtcStore.applyParticipantDisconnected(payload)
+          }
+        }
+      }
+    },
+
+    /**
+     * RTC_CALL_END 通话结束；私聊 + 群聊都走这一条；payload 携带 conversationType 区分
+     * <p>
+     * 私聊：关闭当前通话窗
+     * 群聊：移除胶囊条；如本端在该群通话内则关闭通话窗
+     */
+    handleRtcCallEnd(
+      websocketMessage: ImGroupMessageNotification | ImPrivateMessageNotification
+    ) {
+      const payload = this.safeParse(websocketMessage.content) as ImRtcCallEndNotification | null
+      if (!payload?.room) {
+        return
+      }
+      const rtcStore = useRtcStore()
+      const isGroup = payload.conversationType === ImConversationType.GROUP
+      // 群通话：移除胶囊条（按外层 groupId 取，不依赖 payload）
+      const groupId = (websocketMessage as ImGroupMessageNotification).groupId
+      if (isGroup && groupId) {
+        rtcStore.removeGroupCall(groupId)
+      }
+      // 通话窗 / 来电窗指向同一 room 时关闭：
+      //   RUNNING / INVITING 阶段对比 call.room；INCOMING 阶段对比 incomingPayload.room
+      const matchCall = rtcStore.call?.room === payload.room
+      const matchIncoming = rtcStore.incomingPayload?.room === payload.room
+      if (rtcStore.isActive && (matchCall || matchIncoming)) {
+        const reasonText = resolveCallEndReasonText(payload.endReason)
+        console.info('[Call] end:', reasonText)
+        rtcStore.reset()
+      }
+    }
+  }
+})
+
+export const useImWebSocketStoreWithOut = () => {
+  return useImWebSocketStore()
+}
+
+// dev: 让 Pinia 的 actions / state 改动支持 HMR，避免每次改 store 都得硬刷
+// 否则 Vite 把新模块推下来后，老 store 实例的 action 闭包仍指向旧函数体
+if (import.meta.hot) {
+  import.meta.hot.accept(acceptHMRUpdate(useImWebSocketStore, import.meta.hot))
+}
diff --git a/apps/web-ele/src/views/im/home/types/index.ts b/apps/web-ele/src/views/im/home/types/index.ts
new file mode 100644
index 000000000..f85af3a82
--- /dev/null
+++ b/apps/web-ele/src/views/im/home/types/index.ts
@@ -0,0 +1,306 @@
+// ==================== WebSocket 帧 / 事件 ====================
+
+// 后端 WebSocket 统一帧结构：{ type, content }
+export interface WebSocketFrame {
+  type: string // 帧类型，对齐 ImWebSocketMessageType
+  content: string // 帧内容（JSON 字符串）
+}
+
+// IM WebSocket 通知 DTO（对齐后端 ImNotificationWebSocketDTO）
+export interface ImNotificationWebSocketDTO {
+  conversationType: number // 会话类型
+  contentType: number // 内容类型
+  payload: Record<string, any> // 负载数据
+}
+
+// 无会话在线通知（对齐后端 conversationType = NONE 的独立 payload）
+export interface ImNoConversationNotification {
+  type: number // 内容类型
+  [key: string]: any
+}
+
+// 私聊消息 DTO（对齐后端 ImPrivateMessageNotification）
+export interface ImPrivateMessageNotification {
+  id: number // 消息编号
+  clientMessageId: string // 客户端消息编号
+  senderId: number // 发送人编号
+  receiverId: number // 接收人编号
+  type: number // 内容类型
+  content: string // 消息内容
+  status: number // 消息状态
+  receiptStatus?: number // 回执状态（不需要 / 待完成 / 已完成）
+  sendTime: string // 发送时间
+}
+
+// 群聊消息 DTO（对齐后端 ImGroupMessageNotification）
+export interface ImGroupMessageNotification {
+  id: number // 消息编号
+  clientMessageId: string // 客户端消息编号
+  senderId: number // 发送人编号
+  groupId: number // 群编号
+  type: number // 内容类型
+  content: string // 消息内容
+  status: number // 消息状态
+  sendTime: string // 发送时间
+  atUserIds?: number[] // 群 @ 目标用户列表
+  receiverUserIds?: number[] // 群定向接收用户列表
+  readCount?: number // 群回执已读人数（type = RECEIPT 时使用）
+  receiptStatus?: number // 群回执状态（type = RECEIPT 时使用）
+  readId?: number // 已读位置
+}
+
+// 消息已读同步通知（对齐后端 ImMessageReadNotification）
+export interface ImMessageReadNotification {
+  id: number // 已读位置
+  type: number // 内容类型
+  senderId?: number // 发送人编号
+  receiverId?: number // 私聊接收人编号
+  groupId?: number // 群编号
+  channelId?: number // 频道编号
+  readId?: number // 已读位置
+}
+
+// 消息回执通知（对齐后端 ImMessageReceiptNotification）
+export interface ImMessageReceiptNotification {
+  id: number // 消息编号
+  type: number // 内容类型
+  senderId?: number // 已读方用户编号
+  receiverId?: number // 私聊接收人编号
+  groupId?: number // 群编号
+  readCount?: number // 群回执已读人数
+  receiptStatus?: number // 群回执状态
+}
+
+// ==================== 本地会话 / 消息结构 ====================
+
+/** 引用消息 */
+export interface QuoteMessage {
+  messageId: number // 引用消息编号
+  senderId: number // 引用消息发送人编号
+  type: number // 引用内容类型
+  content: string // 引用消息内容
+}
+
+// 会话数据结构（前端自有结构，后端无对应实体）
+export interface Conversation {
+  // ========== 核心标识 ==========
+  targetId: number // 会话目标编号：私聊=对方 userId；群聊=groupId
+  type: number // 会话类型，对齐 ImConversationType
+
+  // ========== 展示字段 ==========
+  name: string // 展示名称（私聊=好友昵称；群聊=群名）
+  avatar: string // 头像
+  unreadCount: number // 未读数
+
+  // ========== 最后一条消息事实索引 ==========
+  lastContent: string // 会话列表展示的最后一条消息摘要
+  lastSendTime: number // 最后一条消息时间，用于排序
+  lastSenderId?: number // 发送人编号
+  lastMessageType?: number // 内容类型，对齐 ImContentType
+  lastMessageId?: number // 最后一条服务端消息编号
+  lastClientMessageId?: string // 最后一条客户端消息编号
+  lastMessageStatus?: number // 最后一条消息状态
+  lastReceiptStatus?: number // 最后一条群回执状态
+  lastSelfSend?: boolean // 是否自己发的
+  lastSenderDisplayName?: string // 发送人显示名快照——仅作 utils/user.getSenderDisplayName 实时算不出真名时的 fallback
+
+  // ========== UI 状态 ==========
+  deleted?: boolean // 是否已删除（软删标记，持久化时过滤）
+  top?: boolean // 是否置顶（排序时优先）
+  silent?: boolean // 是否免打扰（不展示未读徽标 + 不响提示音）
+  atMe?: boolean // 群聊：是否有人 @我
+  atAll?: boolean // 群聊：是否有人 @全体成员
+  draft?: {
+    html: string // 输入框 HTML
+    plain: string // 输入框纯文本
+    reply?: QuoteMessage // 引用消息
+  } // 输入框草稿
+}
+
+// 消息数据结构
+export interface Message {
+  // ========== 后端字段（对齐 ImPrivateMessageNotification / ImGroupMessageNotification） ==========
+  id?: number // 服务端消息编号，发送中为空
+  clientMessageId: string // 客户端消息编号，本地生成用于合并去重
+  type: number // 内容类型，对齐 ImContentType
+  content: string // 消息内容，JSON 字符串
+  status: number // 消息状态，对齐 ImMessageStatus
+  sendTime: number // 发送时间（前端转毫秒时间戳；后端为 LocalDateTime 字符串）
+  senderId: number // 发送人编号
+  atUserIds?: number[] // 群 @ 目标用户列表
+  receiverUserIds?: number[] // 群定向接收用户列表
+  receiptStatus?: number // 回执状态，对齐 ImMessageReceiptStatus（私聊 / 群 / 频道通用）
+  readCount?: number // 群回执已读人数（仅群消息）
+  materialId?: number // 关联频道素材编号（仅频道消息 type=MATERIAL）
+
+  // ========== 前端扩展字段 ==========
+  // 发送人显示名一律渲染时实时算：utils/user.getSenderDisplayName / getSenderRealNickname
+  // 不在 Message 上存任何名字快照，避免备注 / 群昵称变更后历史消息显示陈旧
+  targetId: number // 会话目标编号（私聊=对端 userId / 群聊=groupId），与 Conversation.targetId 一致
+  selfSend: boolean // 是否自己发送（前端按 senderId 计算）
+  uploadProgress?: number // 媒体消息上传进度（0-100）；status=SENDING 期间持续更新；ack 后置 undefined
+  // 媒体消息内存中保留的原始 File；下划线前缀表示不进 JSON / 不持久化（IDB 恢复后必为 undefined）
+  // 失败重试时按它重走上传；页面刷新后该字段丢失，恢复阶段直接 drop 整条消息
+  _localFile?: File
+  _ackMerging?: boolean // ack 合并中标记，不持久化
+}
+
+// ==================== IndexedDB 本地存储结构 ====================
+
+export interface ConversationDO extends Conversation {
+  clientConversationId: string // `${type}:${targetId}`
+}
+
+export interface ConversationRead {
+  conversationType: number // 会话类型，对齐 ImConversationType
+  targetId: number // 会话目标编号
+  messageId: number // 当前用户已读到的最大消息编号
+  updateTime?: number // 更新时间
+}
+
+export interface ConversationReadDO extends ConversationRead {
+  clientConversationId: string // `${conversationType}:${targetId}`
+}
+
+export interface MessageDO extends Omit<Message, '_ackMerging' | '_localFile' | 'uploadProgress'> {
+  messageKey: string // `${conversationType}:${id}` 或 `client:${clientMessageId}`
+  conversationType: number // 会话类型，对齐 ImConversationType
+  clientConversationId: string // ConversationDO.clientConversationId
+}
+
+export interface SettingDO<T = unknown> {
+  key: string
+  value: T
+  updateTime?: number
+}
+
+// ==================== 群 / 群成员 ====================
+
+// 群实体（前端内部结构）
+export interface Group {
+  // ========== 后端字段（对齐 ImGroupApi.GroupRespVO） ==========
+  id: number // 群编号
+  name: string // 群名称
+  avatar?: string // 群头像
+  notice?: string // 群公告
+  ownerUserId?: number // 群主用户编号
+  pinnedMessages?: Message[] // 群置顶消息列表
+  mutedAll?: boolean // 是否全群禁言
+  banned?: boolean // 是否被管理员封禁
+  joinApproval?: boolean // 进群是否需群主 / 管理员审批
+  joinStatus?: number // 当前登录用户在该群的成员状态（参见 CommonStatusEnum：0 在群 / 1 已退群）；历史退群群仍返回，供展示历史消息的群名 / 头像
+
+  // ========== 前端扩展字段（user-per-group 维度） ==========
+  silent?: boolean // 是否免打扰。从当前用户的 GroupMember 回填
+  groupRemark?: string // 群备注。从当前用户的 GroupMember 回填（当前用户对该群的自定义名）
+  members?: GroupMember[] // 群成员缓存（按需懒加载）
+  membersLoaded?: boolean // members 是否"完整加载"——只有整群 loadGroupMemberList / fetchGroupMemberList 命中时为 true；fetchGroupMember 单成员补齐不置位，避免 fetchGroupMemberList(force=false) 命中缓存时误判整群已加载
+  membersExpired?: boolean // 群成员缓存是否已过期；重连 / 重新进入 IM 后只标记不删除，下次进入群会话再刷新
+  memberCount?: number // 成员总数
+}
+
+export type GroupDO = Omit<Group, 'members' | 'membersExpired' | 'membersLoaded'>
+
+// 群成员实体（前端内部结构）
+export interface GroupMember {
+  // ========== 后端字段（对齐 ImGroupMemberApi.GroupMemberRespVO） ==========
+  id?: number // 群成员关系记录编号
+  groupId: number // 群编号
+  userId: number // 用户编号
+  avatar?: string // 头像
+  nickname: string // 用户昵称
+  displayUserName?: string // 该成员在群内自定义昵称（每个 member 一份；不与 nickname 合并，由消费方按需取舍）
+  status?: number // 在群 / 退群状态，对齐 CommonStatusEnum
+  role?: number // 成员角色，参见 ImGroupMemberRole 枚举：1=群主 2=管理员 3=普通成员
+  muteEndTime?: string // 禁言到期时间（ISO 字符串）
+
+  // ========== 前端扩展字段 ==========
+  isOwner?: boolean // 是否群主（前端从 Group.ownerUserId 计算）
+}
+
+// ==================== 好友 ====================
+
+// 好友实体（前端内部结构）
+export interface Friend {
+  // ========== 后端字段（对齐 ImFriendApi.FriendRespVO） ==========
+  id?: number // 好友关系记录编号（本地乐观新增时可能暂缺）
+  friendUserId: number // 好友用户编号（与 Conversation.targetId 对齐）
+  nickname: string // 好友昵称（对方真实昵称，永远不被备注覆盖；UI 显示走 displayName || nickname）
+  nicknamePinyin?: string // 昵称的拼音（后端用 Pinyin4j 算好回填，小写无空格）
+  avatar?: string // 好友头像
+  silent?: boolean // 是否免打扰（不展示未读徽标 + 不响提示音）
+  displayName?: string // 好友展示备注：仅自己可见的别名（单字段不歧义，不带 Friend 前缀）
+  displayNamePinyin?: string // 备注的拼音（后端用 Pinyin4j 算好回填，小写无空格）
+  status?: number // 好友状态，对齐 CommonStatusEnum（DISABLE = 已删除，软删保留记录）
+  addSource?: number // 添加来源；参见 ImFriendAddSourceEnum
+  pinned?: boolean // 是否置顶联系人
+  blocked?: boolean // 是否拉黑（仅自己可见，单边屏蔽对方私聊消息）
+  addTime?: number // 添加好友时间（毫秒时间戳；后端为 LocalDateTime 字符串，在 convertFriend 转换）
+  deleteTime?: number // 删除好友时间（毫秒时间戳；后端为 LocalDateTime 字符串，在 convertFriend 转换）
+}
+
+/**
+ * 好友申请记录（前端内部结构，对齐后端 ImFriendRequestApi.FriendRequestRespVO）
+ */
+export interface FriendRequest {
+  // ========== 后端字段（对齐 ImFriendRequestApi.FriendRequestRespVO） ==========
+  id: number // 申请编号
+  fromUserId: number // 发起方用户编号
+  toUserId: number // 接收方用户编号
+  handleResult: number // 处理结果：0=未处理；1=同意；2=拒绝
+  applyContent?: string // 申请理由（发起方填写）
+  handleContent?: string // 处理理由（接收方拒绝时可选填）
+  addSource?: number // 添加来源；参见 ImFriendAddSourceEnum
+  handleTime?: number // 处理时间（毫秒时间戳）
+  createTime: number // 申请创建时间（毫秒时间戳）
+
+  // ========== 聚合字段（自 AdminUser，仅展示用） ==========
+  fromNickname?: string // 发起方昵称
+  fromAvatar?: string // 发起方头像
+  toNickname?: string // 接收方昵称
+  toAvatar?: string // 接收方头像
+}
+
+// ==================== 用户名片 ====================
+
+// 用户精简信息（对齐后端 UserSimpleRespVO，名片 / 头像 hover 等场景共用）
+export interface User {
+  id: number
+  nickname?: string
+  avatar?: string
+  sex?: number
+  deptId?: number
+  deptName?: string
+}
+
+// ==================== 列表行展示用 Lite 类型 ====================
+
+/**
+ * 好友列表行：从 Friend 派生的展示快照
+ * - id 用 friendUserId（与列表 click / 选中比对一致），不是 Friend.id（关系记录主键）
+ * - 软删（status === DISABLE）由上游 friendStore.getActiveFriendList / getActiveFriendLiteList 统一过滤掉
+ */
+export interface FriendLite {
+  id: number
+  nickname: string
+  nicknamePinyin?: string // 昵称拼音（用于字母分桶 / 拼音搜索）
+  avatar?: string
+  displayName?: string
+  displayNamePinyin?: string // 备注拼音（优先于 nicknamePinyin 参与分桶）
+}
+
+/**
+ * 群列表行：从 Group 派生的展示快照
+ * - showGroupName / showImage：调用方决定带不带备注（如个人备注群名）；展示按 show* > 原值兜底
+ * - showImageThumb：高频列表用缩略图，避免拉原图阻塞滚动
+ */
+export interface GroupLite {
+  id: number
+  name?: string
+  showGroupName?: string
+  showImage?: string
+  showImageThumb?: string
+  memberCount?: number
+  ownerId?: number
+  joinApproval?: boolean // 进群是否需群主 / 管理员审批
+}
diff --git a/apps/web-ele/src/views/im/manager/channel/list/components/index.ts b/apps/web-ele/src/views/im/manager/channel/list/components/index.ts
new file mode 100644
index 000000000..da6d6607f
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/list/components/index.ts
@@ -0,0 +1 @@
+export { default as ChannelSelect } from './select.vue';
diff --git a/apps/web-ele/src/views/im/manager/channel/list/components/select.vue b/apps/web-ele/src/views/im/manager/channel/list/components/select.vue
new file mode 100644
index 000000000..1e49416ca
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/list/components/select.vue
@@ -0,0 +1,66 @@
+<script lang="ts" setup>
+import type { ImManagerChannelApi } from '#/api/im/manager/channel';
+
+import { computed, onMounted, ref } from 'vue';
+
+import { ElSelect } from 'element-plus'
+
+import { getSimpleChannelList } from '#/api/im/manager/channel';
+
+defineOptions({ name: 'ImManagerChannelSelect' });
+
+const props = withDefaults(
+  defineProps<{
+    clearable?: boolean
+    disabled?: boolean
+    modelValue?: number
+    placeholder?: string
+  }>(),
+  {
+    clearable: true,
+    disabled: false,
+    modelValue: undefined,
+    placeholder: '请选择频道',
+  },
+);
+
+const emit = defineEmits<{
+  'update:modelValue': [value: number | undefined];
+}>();
+
+const loading = ref(false);
+const channelList = ref<ImManagerChannelApi.Channel[]>([]);
+
+const value = computed({
+  get: () => props.modelValue,
+  set: (val) => emit('update:modelValue', val),
+});
+
+const options = computed(() =>
+  channelList.value.map((item) => ({ label: item.name, value: item.id })),
+);
+
+/** 加载频道列表 */
+async function loadChannelList() {
+  loading.value = true;
+  try {
+    channelList.value = await getSimpleChannelList();
+  } finally {
+    loading.value = false;
+  }
+}
+
+onMounted(loadChannelList);
+</script>
+
+<template>
+  <ElSelect
+    v-model="value"
+    :clearable="clearable"
+    :disabled="disabled"
+    :loading="loading"
+    :options="options"
+    :placeholder="placeholder"
+    class="w-full"
+  />
+</template>
diff --git a/apps/web-ele/src/views/im/manager/channel/list/data.ts b/apps/web-ele/src/views/im/manager/channel/list/data.ts
new file mode 100644
index 000000000..039ccaff1
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/list/data.ts
@@ -0,0 +1,156 @@
+import type { VbenFormSchema } from '#/adapter/form'
+import type { VxeTableGridOptions } from '#/adapter/vxe-table'
+
+import { CommonStatusEnum, DICT_TYPE } from '@vben/constants'
+import { getDictOptions } from '@vben/hooks'
+
+import { z } from '#/adapter/form'
+
+/** 新增/修改的表单 */
+export function useFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'id',
+      component: 'Input',
+      dependencies: {
+        triggerFields: [''],
+        show: () => false
+      }
+    },
+    {
+      fieldName: 'code',
+      label: '频道编码',
+      component: 'Input',
+      componentProps: {
+        placeholder: '如 system_notice'
+      },
+      rules: z
+        .string({ message: '频道编码不能为空' })
+        .regex(/^[a-z][a-z0-9_]*$/, '只能由小写字母 / 数字 / 下划线组成，且以字母开头')
+    },
+    {
+      fieldName: 'name',
+      label: '频道名称',
+      component: 'Input',
+      componentProps: {
+        placeholder: '如 系统公告'
+      },
+      rules: 'required'
+    },
+    {
+      fieldName: 'avatar',
+      label: '频道头像',
+      component: 'ImageUpload',
+      componentProps: {
+        maxNumber: 1
+      },
+      rules: 'required'
+    },
+    {
+      fieldName: 'sort',
+      label: '排序',
+      component: 'InputNumber',
+      componentProps: {
+        min: 0
+      },
+      rules: z.number().default(0)
+    },
+    {
+      fieldName: 'status',
+      label: '状态',
+      component: 'RadioGroup',
+      componentProps: {
+        options: getDictOptions(DICT_TYPE.COMMON_STATUS, 'number'),
+        isButton: true,
+      },
+      rules: z.number().default(CommonStatusEnum.ENABLE)
+    }
+  ]
+}
+
+/** 列表的搜索表单 */
+export function useGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'code',
+      label: '编码',
+      component: 'Input',
+      componentProps: {
+        clearable: true,
+        placeholder: '频道业务码'
+      }
+    },
+    {
+      fieldName: 'name',
+      label: '名称',
+      component: 'Input',
+      componentProps: {
+        clearable: true,
+        placeholder: '频道名称'
+      }
+    },
+    {
+      fieldName: 'status',
+      label: '状态',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.COMMON_STATUS, 'number'),
+        placeholder: '请选择状态'
+      }
+    }
+  ]
+}
+
+/** 列表的字段 */
+export function useGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    {
+      field: 'id',
+      title: '编号',
+      width: 80
+    },
+    {
+      field: 'avatar',
+      title: '头像',
+      width: 80,
+      slots: { default: 'avatar' }
+    },
+    {
+      field: 'code',
+      title: '编码',
+      minWidth: 160
+    },
+    {
+      field: 'name',
+      title: '名称',
+      minWidth: 140
+    },
+    {
+      field: 'sort',
+      title: '排序',
+      width: 80
+    },
+    {
+      field: 'status',
+      title: '状态',
+      width: 100,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.COMMON_STATUS }
+      }
+    },
+    {
+      field: 'createTime',
+      title: '创建时间',
+      minWidth: 180,
+      formatter: 'formatDateTime'
+    },
+    {
+      title: '操作',
+      width: 160,
+      fixed: 'right',
+      slots: { default: 'actions' }
+    }
+  ]
+}
diff --git a/apps/web-ele/src/views/im/manager/channel/list/index.vue b/apps/web-ele/src/views/im/manager/channel/list/index.vue
new file mode 100644
index 000000000..d1877c197
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/list/index.vue
@@ -0,0 +1,129 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table'
+import type { ImManagerChannelApi } from '#/api/im/manager/channel'
+
+import { Page, useVbenModal } from '@vben/common-ui'
+
+import { ElImage, ElLoading, ElMessage } from 'element-plus'
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table'
+import { deleteManagerChannel, getManagerChannelPage } from '#/api/im/manager/channel'
+import { $t } from '#/locales'
+
+import { useGridColumns, useGridFormSchema } from './data'
+import Form from './modules/form.vue'
+
+defineOptions({ name: 'ImManagerChannel' })
+
+const [FormModal, formModalApi] = useVbenModal({
+  connectedComponent: Form,
+  destroyOnClose: true
+})
+
+/** 刷新表格 */
+function handleRefresh() {
+  gridApi.query()
+}
+
+/** 创建频道 */
+function handleCreate() {
+  formModalApi.setData(null).open()
+}
+
+/** 编辑频道 */
+function handleEdit(row: ImManagerChannelApi.Channel) {
+  formModalApi.setData(row).open()
+}
+
+/** 删除频道 */
+async function handleDelete(row: ImManagerChannelApi.Channel) {
+  const loadingInstance = ElLoading.service({
+    text: $t('ui.actionMessage.deleting', [row.name]),
+  });
+  try {
+    await deleteManagerChannel(row.id)
+    ElMessage.success($t('ui.actionMessage.deleteSuccess', [row.name]))
+    handleRefresh()
+  } finally {
+    loadingInstance.close()
+  }
+}
+
+const [Grid, gridApi] = useVbenVxeGrid({
+  formOptions: {
+    schema: useGridFormSchema()
+  },
+  gridOptions: {
+    columns: useGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerChannelPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues
+          })
+        }
+      }
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true
+    }
+  } as VxeTableGridOptions<ImManagerChannelApi.Channel>
+})
+</script>
+
+<template>
+  <Page auto-content-height>
+    <FormModal @success="handleRefresh" />
+    <Grid table-title="频道列表">
+      <template #toolbar-tools>
+        <TableAction
+          :actions="[
+            {
+              label: $t('ui.actionTitle.create', ['频道']),
+              type: 'primary',
+              icon: ACTION_ICON.ADD,
+              auth: ['im:manager:channel:create'],
+              onClick: handleCreate
+            }
+          ]"
+        />
+      </template>
+      <template #avatar="{ row }">
+        <ElImage v-if="row.avatar" :src="row.avatar" :width="32" :height="32" />
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: $t('common.edit'),
+              link: true,
+              icon: ACTION_ICON.EDIT,
+              auth: ['im:manager:channel:update'],
+              onClick: handleEdit.bind(null, row)
+            },
+            {
+              label: $t('common.delete'),
+              link: true,
+              type: 'danger',
+              icon: ACTION_ICON.DELETE,
+              auth: ['im:manager:channel:delete'],
+              popConfirm: {
+                title: $t('ui.actionMessage.deleteConfirm', [row.name]),
+                confirm: handleDelete.bind(null, row)
+              }
+            }
+          ]"
+        />
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/channel/list/modules/form.vue b/apps/web-ele/src/views/im/manager/channel/list/modules/form.vue
new file mode 100644
index 000000000..ed046a24b
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/list/modules/form.vue
@@ -0,0 +1,82 @@
+<script lang="ts" setup>
+import type { ImManagerChannelApi } from '#/api/im/manager/channel'
+
+import { computed, ref } from 'vue'
+
+import { useVbenModal } from '@vben/common-ui'
+
+import { ElMessage } from 'element-plus'
+
+import { useVbenForm } from '#/adapter/form'
+import {
+  createManagerChannel,
+  getManagerChannel,
+  updateManagerChannel
+} from '#/api/im/manager/channel'
+import { $t } from '#/locales'
+
+import { useFormSchema } from '../data'
+
+const emit = defineEmits(['success'])
+const formData = ref<ImManagerChannelApi.Channel>()
+const getTitle = computed(() => {
+  return formData.value?.id
+    ? $t('ui.actionTitle.edit', ['频道'])
+    : $t('ui.actionTitle.create', ['频道'])
+})
+
+const [Form, formApi] = useVbenForm({
+  commonConfig: {
+    componentProps: {
+      class: 'w-full'
+    },
+    formItemClass: 'col-span-2',
+    labelWidth: 100
+  },
+  layout: 'horizontal',
+  schema: useFormSchema(),
+  showDefaultActions: false
+})
+
+const [Modal, modalApi] = useVbenModal({
+  async onConfirm() {
+    const { valid } = await formApi.validate()
+    if (!valid) {
+      return
+    }
+    modalApi.lock()
+    const data = (await formApi.getValues()) as ImManagerChannelApi.Channel
+    try {
+      await (formData.value?.id ? updateManagerChannel(data) : createManagerChannel(data))
+      await modalApi.close()
+      emit('success')
+      ElMessage.success($t('ui.actionMessage.operationSuccess'))
+    } finally {
+      modalApi.unlock()
+    }
+  },
+  async onOpenChange(isOpen: boolean) {
+    if (!isOpen) {
+      formData.value = undefined
+      return
+    }
+    const data = modalApi.getData<ImManagerChannelApi.Channel>()
+    if (!data || !data.id) {
+      return
+    }
+    modalApi.lock()
+    try {
+      formData.value = await getManagerChannel(data.id)
+      await formApi.setValues(formData.value)
+    } finally {
+      modalApi.unlock()
+    }
+  }
+})
+</script>
+
+<template>
+  <Modal :title="getTitle" class="w-1/3">
+    <Form class="mx-4" />
+  </Modal>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/channel/material/components/index.ts b/apps/web-ele/src/views/im/manager/channel/material/components/index.ts
new file mode 100644
index 000000000..a0d10a84c
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/material/components/index.ts
@@ -0,0 +1 @@
+export { default as MaterialSelect } from './select.vue';
diff --git a/apps/web-ele/src/views/im/manager/channel/material/components/select.vue b/apps/web-ele/src/views/im/manager/channel/material/components/select.vue
new file mode 100644
index 000000000..e94663886
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/material/components/select.vue
@@ -0,0 +1,71 @@
+<script lang="ts" setup>
+import type { ImManagerChannelMaterialApi } from '#/api/im/manager/channel/material';
+
+import { computed, ref, watch } from 'vue';
+
+import { ElSelect } from 'element-plus'
+
+import { getSimpleManagerChannelMaterialList } from '#/api/im/manager/channel/material';
+
+defineOptions({ name: 'ImManagerMaterialSelect' });
+
+const props = withDefaults(
+  defineProps<{
+    channelId?: number
+    clearable?: boolean
+    modelValue?: number
+    placeholder?: string
+  }>(),
+  {
+    clearable: true,
+    channelId: undefined,
+    modelValue: undefined,
+    placeholder: '请选择素材',
+  },
+);
+
+const emit = defineEmits<{
+  'update:modelValue': [value: number | undefined];
+}>();
+
+const loading = ref(false);
+const materialList = ref<ImManagerChannelMaterialApi.Material[]>([]);
+
+const value = computed({
+  get: () => props.modelValue,
+  set: (val) => emit('update:modelValue', val),
+});
+
+const options = computed(() =>
+  materialList.value.map((item) => ({ label: item.title, value: item.id })),
+);
+
+/** 按频道加载素材 */
+async function loadMaterialList(channelId?: number) {
+  emit('update:modelValue', undefined);
+  materialList.value = [];
+  if (!channelId) {
+    return;
+  }
+  loading.value = true;
+  try {
+    materialList.value = await getSimpleManagerChannelMaterialList(channelId);
+  } finally {
+    loading.value = false;
+  }
+}
+
+watch(() => props.channelId, loadMaterialList, { immediate: true });
+</script>
+
+<template>
+  <ElSelect
+    v-model="value"
+    :clearable="clearable"
+    :disabled="!channelId"
+    :loading="loading"
+    :options="options"
+    :placeholder="placeholder"
+    class="w-full"
+  />
+</template>
diff --git a/apps/web-ele/src/views/im/manager/channel/material/data.ts b/apps/web-ele/src/views/im/manager/channel/material/data.ts
new file mode 100644
index 000000000..61ff28b75
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/material/data.ts
@@ -0,0 +1,234 @@
+import type { VbenFormSchema } from '#/adapter/form';
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+
+import { markRaw } from 'vue';
+
+import { DICT_TYPE } from '@vben/constants';
+import { getDictOptions } from '@vben/hooks';
+
+import { z } from '#/adapter/form';
+import { getRangePickerDefaultProps } from '#/utils';
+import { ChannelSelect } from '#/views/im/manager/channel/list/components';
+
+/** 新增/修改的表单 */
+export function useFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'id',
+      component: 'Input',
+      dependencies: {
+        triggerFields: [''],
+        show: () => false,
+      },
+    },
+    {
+      fieldName: 'channelId',
+      label: '所属频道',
+      component: markRaw(ChannelSelect),
+      rules: 'selectRequired',
+    },
+    {
+      fieldName: 'type',
+      label: '内容类型',
+      component: 'RadioGroup',
+      componentProps: {
+        options: getDictOptions(DICT_TYPE.IM_CHANNEL_MATERIAL_TYPE, 'number'),
+        isButton: true,
+      },
+      rules: z.number().default(1),
+    },
+    {
+      fieldName: 'title',
+      label: '标题',
+      component: 'Input',
+      componentProps: {
+        maxlength: 128,
+        placeholder: '请输入标题',
+      },
+      rules: 'required',
+    },
+    {
+      fieldName: 'coverUrl',
+      label: '封面图',
+      component: 'ImageUpload',
+      componentProps: {
+        maxNumber: 1,
+      },
+    },
+    {
+      fieldName: 'summary',
+      label: '摘要',
+      component: 'Textarea',
+      componentProps: {
+        maxlength: 255,
+        placeholder: '请输入摘要',
+        rows: 2,
+      },
+    },
+    {
+      fieldName: 'content',
+      label: '正文',
+      component: 'RichTextarea',
+      dependencies: {
+        triggerFields: ['type'],
+        show: (values) => values.type === 1,
+      },
+    },
+    {
+      fieldName: 'url',
+      label: '跳转链接',
+      component: 'Input',
+      componentProps: {
+        placeholder: 'https://example.com/...',
+      },
+      dependencies: {
+        triggerFields: ['type'],
+        show: (values) => values.type !== 1,
+      },
+    },
+  ];
+}
+
+/** 列表的搜索表单 */
+export function useGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'channelId',
+      label: '频道',
+      component: markRaw(ChannelSelect),
+      componentProps: {
+        placeholder: '全部',
+      },
+    },
+    {
+      fieldName: 'title',
+      label: '标题',
+      component: 'Input',
+      componentProps: {
+        clearable: true,
+        placeholder: '标题关键字',
+      },
+    },
+  ];
+}
+
+/** 列表的字段 */
+export function useGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    {
+      field: 'id',
+      title: '编号',
+      width: 80,
+    },
+    {
+      field: 'coverUrl',
+      title: '封面',
+      width: 80,
+      slots: { default: 'cover' },
+    },
+    {
+      field: 'channelName',
+      title: '频道',
+      minWidth: 120,
+    },
+    {
+      field: 'type',
+      title: '内容类型',
+      width: 110,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_CHANNEL_MATERIAL_TYPE },
+      },
+    },
+    {
+      field: 'title',
+      title: '标题',
+      minWidth: 180,
+    },
+    {
+      field: 'summary',
+      title: '摘要',
+      minWidth: 180,
+    },
+    {
+      field: 'createTime',
+      title: '创建时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      title: '操作',
+      width: 160,
+      fixed: 'right',
+      slots: { default: 'actions' },
+    },
+  ];
+}
+
+/** 频道消息搜索表单 */
+export function useMessageGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'channelId',
+      label: '频道',
+      component: markRaw(ChannelSelect),
+      componentProps: {
+        placeholder: '全部',
+      },
+    },
+    {
+      fieldName: 'sendTime',
+      label: '发送时间',
+      component: 'RangePicker',
+      componentProps: {
+        ...getRangePickerDefaultProps(),
+        clearable: true,
+      },
+    },
+  ];
+}
+
+/** 频道消息字段 */
+export function useMessageGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    {
+      field: 'id',
+      title: '编号',
+      width: 80,
+    },
+    {
+      field: 'materialCoverUrl',
+      title: '封面',
+      width: 80,
+      slots: { default: 'cover' },
+    },
+    {
+      field: 'channelName',
+      title: '频道',
+      minWidth: 120,
+    },
+    {
+      field: 'materialTitle',
+      title: '素材标题',
+      minWidth: 180,
+    },
+    {
+      field: 'receiverUserIds',
+      title: '接收人',
+      width: 120,
+      slots: { default: 'receivers' },
+    },
+    {
+      field: 'sendTime',
+      title: '发送时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      title: '操作',
+      width: 100,
+      fixed: 'right',
+      slots: { default: 'actions' },
+    },
+  ];
+}
diff --git a/apps/web-ele/src/views/im/manager/channel/material/index.vue b/apps/web-ele/src/views/im/manager/channel/material/index.vue
new file mode 100644
index 000000000..a1fa2a750
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/material/index.vue
@@ -0,0 +1,137 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerChannelMaterialApi } from '#/api/im/manager/channel/material';
+
+import { Page, useVbenModal } from '@vben/common-ui';
+
+import { ElImage, ElLoading, ElMessage } from 'element-plus'
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
+import {
+  deleteManagerChannelMaterial,
+  getManagerChannelMaterialPage,
+} from '#/api/im/manager/channel/material';
+import { $t } from '#/locales';
+
+import { useGridColumns, useGridFormSchema } from './data';
+import Form from './modules/form.vue';
+
+defineOptions({ name: 'ImManagerChannelMaterial' });
+
+const [FormModal, formModalApi] = useVbenModal({
+  connectedComponent: Form,
+  destroyOnClose: true,
+});
+
+/** 刷新表格 */
+function handleRefresh() {
+  gridApi.query();
+}
+
+/** 创建素材 */
+function handleCreate() {
+  formModalApi.setData(null).open();
+}
+
+/** 编辑素材 */
+function handleEdit(row: ImManagerChannelMaterialApi.Material) {
+  formModalApi.setData(row).open();
+}
+
+/** 删除素材 */
+async function handleDelete(row: ImManagerChannelMaterialApi.Material) {
+  const loadingInstance = ElLoading.service({
+    text: $t('ui.actionMessage.deleting', [row.title]),
+  });
+  try {
+    await deleteManagerChannelMaterial(row.id);
+    ElMessage.success($t('ui.actionMessage.deleteSuccess', [row.title]));
+    handleRefresh();
+  } finally {
+    loadingInstance.close();
+  }
+}
+
+const [Grid, gridApi] = useVbenVxeGrid({
+  formOptions: {
+    schema: useGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerChannelMaterialPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerChannelMaterialApi.Material>,
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <FormModal @success="handleRefresh" />
+    <Grid table-title="素材列表">
+      <template #toolbar-tools>
+        <TableAction
+          :actions="[
+            {
+              label: $t('ui.actionTitle.create', ['素材']),
+              type: 'primary',
+              icon: ACTION_ICON.ADD,
+              auth: ['im:manager:channel-material:create'],
+              onClick: handleCreate,
+            },
+          ]"
+        />
+      </template>
+      <template #cover="{ row }">
+        <ElImage
+          v-if="row.coverUrl"
+          :height="40"
+          :src="row.coverUrl"
+          :width="40"
+        />
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: $t('common.edit'),
+              link: true,
+              icon: ACTION_ICON.EDIT,
+              auth: ['im:manager:channel-material:update'],
+              onClick: handleEdit.bind(null, row),
+            },
+            {
+              label: $t('common.delete'),
+              link: true,
+              type: 'danger',
+              icon: ACTION_ICON.DELETE,
+              auth: ['im:manager:channel-material:delete'],
+              popConfirm: {
+                title: $t('ui.actionMessage.deleteConfirm', [row.title]),
+                confirm: handleDelete.bind(null, row),
+              },
+            },
+          ]"
+        />
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/channel/material/modules/form.vue b/apps/web-ele/src/views/im/manager/channel/material/modules/form.vue
new file mode 100644
index 000000000..65f3e02bb
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/material/modules/form.vue
@@ -0,0 +1,87 @@
+<script lang="ts" setup>
+import type { ImManagerChannelMaterialApi } from '#/api/im/manager/channel/material';
+
+import { computed, ref } from 'vue';
+
+import { useVbenModal } from '@vben/common-ui';
+
+import { ElMessage } from 'element-plus'
+
+import { useVbenForm } from '#/adapter/form';
+import {
+  createManagerChannelMaterial,
+  getManagerChannelMaterial,
+  updateManagerChannelMaterial,
+} from '#/api/im/manager/channel/material';
+import { $t } from '#/locales';
+
+import { useFormSchema } from '../data';
+
+const emit = defineEmits(['success']);
+const formData = ref<ImManagerChannelMaterialApi.Material>();
+const getTitle = computed(() => {
+  return formData.value?.id
+    ? $t('ui.actionTitle.edit', ['素材'])
+    : $t('ui.actionTitle.create', ['素材']);
+});
+
+const [Form, formApi] = useVbenForm({
+  commonConfig: {
+    componentProps: {
+      class: 'w-full',
+    },
+    formItemClass: 'col-span-2',
+    labelWidth: 100,
+  },
+  layout: 'horizontal',
+  schema: useFormSchema(),
+  showDefaultActions: false,
+});
+
+const [Modal, modalApi] = useVbenModal({
+  async onConfirm() {
+    const { valid } = await formApi.validate();
+    if (!valid) {
+      return;
+    }
+    modalApi.lock();
+    const data =
+      (await formApi.getValues()) as ImManagerChannelMaterialApi.Material;
+    try {
+      await (formData.value?.id
+        ? updateManagerChannelMaterial(data)
+        : createManagerChannelMaterial(data));
+      await modalApi.close();
+      emit('success');
+      ElMessage.success($t('ui.actionMessage.operationSuccess'));
+    } finally {
+      modalApi.unlock();
+    }
+  },
+  async onOpenChange(isOpen: boolean) {
+    if (!isOpen) {
+      formData.value = undefined;
+      await formApi.resetForm();
+      return;
+    }
+    const data = modalApi.getData<ImManagerChannelMaterialApi.Material>();
+    await formApi.setValues({ type: 1 });
+    if (!data || !data.id) {
+      return;
+    }
+    modalApi.lock();
+    try {
+      formData.value = await getManagerChannelMaterial(data.id);
+      await formApi.setValues(formData.value);
+    } finally {
+      modalApi.unlock();
+    }
+  },
+});
+</script>
+
+<template>
+  <Modal :title="getTitle" class="w-1/2">
+    <Form class="mx-4" />
+  </Modal>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/channel/message/index.vue b/apps/web-ele/src/views/im/manager/channel/message/index.vue
new file mode 100644
index 000000000..39a5c915b
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/message/index.vue
@@ -0,0 +1,131 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerChannelMessageApi } from '#/api/im/manager/channel/message';
+
+import { Page, useVbenModal } from '@vben/common-ui';
+
+import { ElImage, ElLoading, ElMessage, ElTag } from 'element-plus'
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
+import {
+  deleteManagerChannelMessage,
+  getManagerChannelMessagePage,
+} from '#/api/im/manager/channel/message';
+import { $t } from '#/locales';
+
+import { useMessageGridColumns, useMessageGridFormSchema } from '../material/data';
+import SendForm from './modules/send-form.vue';
+
+defineOptions({ name: 'ImManagerChannelMessage' });
+
+const [SendModal, sendModalApi] = useVbenModal({
+  connectedComponent: SendForm,
+  destroyOnClose: true,
+});
+
+/** 刷新表格 */
+function handleRefresh() {
+  gridApi.query();
+}
+
+/** 打开发送弹窗 */
+function handleSend() {
+  sendModalApi.open();
+}
+
+/** 删除频道消息 */
+async function handleDelete(row: ImManagerChannelMessageApi.ChannelMessage) {
+  const loadingInstance = ElLoading.service({
+    text: $t('ui.actionMessage.deleting', [row.id]),
+  });
+  try {
+    await deleteManagerChannelMessage(row.id);
+    ElMessage.success($t('ui.actionMessage.deleteSuccess', [row.id]));
+    handleRefresh();
+  } finally {
+    loadingInstance.close();
+  }
+}
+
+const [Grid, gridApi] = useVbenVxeGrid({
+  formOptions: {
+    schema: useMessageGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useMessageGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerChannelMessagePage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerChannelMessageApi.ChannelMessage>,
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <SendModal @success="handleRefresh" />
+    <Grid table-title="频道消息列表">
+      <template #toolbar-tools>
+        <TableAction
+          :actions="[
+            {
+              label: '立即推送',
+              type: 'primary',
+              icon: ACTION_ICON.ADD,
+              auth: ['im:manager:channel-message:send'],
+              onClick: handleSend,
+            },
+          ]"
+        />
+      </template>
+      <template #cover="{ row }">
+        <ElImage
+          v-if="row.materialCoverUrl"
+          :height="40"
+          :src="row.materialCoverUrl"
+          :width="40"
+        />
+      </template>
+      <template #receivers="{ row }">
+        <ElTag v-if="!row.receiverUserIds || row.receiverUserIds.length === 0" type="warning">
+          全员
+        </ElTag>
+        <span v-else>{{ row.receiverUserIds.length }} 人</span>
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: $t('common.delete'),
+              link: true,
+              type: 'danger',
+              icon: ACTION_ICON.DELETE,
+              auth: ['im:manager:channel-message:delete'],
+              popConfirm: {
+                title: $t('ui.actionMessage.deleteConfirm', [row.id]),
+                confirm: handleDelete.bind(null, row),
+              },
+            },
+          ]"
+        />
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/channel/message/modules/send-form.vue b/apps/web-ele/src/views/im/manager/channel/message/modules/send-form.vue
new file mode 100644
index 000000000..cd3636d0f
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/channel/message/modules/send-form.vue
@@ -0,0 +1,100 @@
+<script lang="ts" setup>
+import { ref } from 'vue';
+
+import { useVbenModal } from '@vben/common-ui';
+
+import { ElForm, ElFormItem, ElMessage, ElRadio, ElRadioGroup } from 'element-plus'
+
+import { sendManagerChannelMessage } from '#/api/im/manager/channel/message';
+import { ChannelSelect } from '#/views/im/manager/channel/list/components';
+import { MaterialSelect } from '#/views/im/manager/channel/material/components';
+import { UserSelect } from '#/views/system/user/components';
+
+const emit = defineEmits(['success']);
+
+const formData = ref({
+  channelId: undefined as number | undefined,
+  materialId: undefined as number | undefined,
+  receiverUserType: 'all' as 'all' | 'users',
+  receiverUserIds: [] as number[],
+});
+
+/** 重置表单 */
+function resetForm() {
+  formData.value = {
+    channelId: undefined,
+    materialId: undefined,
+    receiverUserType: 'all',
+    receiverUserIds: [],
+  };
+}
+
+const [Modal, modalApi] = useVbenModal({
+  async onConfirm() {
+    if (!formData.value.channelId || !formData.value.materialId) {
+      ElMessage.warning('请选择频道和素材');
+      return;
+    }
+    if (
+      formData.value.receiverUserType === 'users' &&
+      formData.value.receiverUserIds.length === 0
+    ) {
+      ElMessage.warning('请至少选择一个接收用户');
+      return;
+    }
+    modalApi.lock();
+    try {
+      await sendManagerChannelMessage({
+        materialId: formData.value.materialId,
+        receiverUserIds:
+          formData.value.receiverUserType === 'users'
+            ? formData.value.receiverUserIds
+            : undefined,
+      });
+      await modalApi.close();
+      emit('success');
+      ElMessage.success('推送成功');
+    } finally {
+      modalApi.unlock();
+    }
+  },
+  onOpenChange(isOpen: boolean) {
+    if (isOpen) {
+      resetForm();
+    }
+  },
+});
+</script>
+
+<template>
+  <Modal title="立即推送频道消息" class="w-2/5">
+    <ElForm label-width="110px">
+      <ElFormItem label="所属频道" required>
+        <ChannelSelect
+          v-model="formData.channelId"
+          placeholder="请选择频道（用于加载素材）"
+        />
+      </ElFormItem>
+      <ElFormItem label="素材" required>
+        <MaterialSelect
+          v-model="formData.materialId"
+          :channel-id="formData.channelId"
+          placeholder="请选择素材"
+        />
+      </ElFormItem>
+      <ElFormItem label="受众">
+        <ElRadioGroup v-model="formData.receiverUserType">
+          <ElRadio value="all">全员</ElRadio>
+          <ElRadio value="users">指定用户</ElRadio>
+        </ElRadioGroup>
+      </ElFormItem>
+      <ElFormItem v-if="formData.receiverUserType === 'users'" label="接收用户" required>
+        <UserSelect
+          v-model="formData.receiverUserIds"
+          multiple
+          placeholder="请选择接收用户"
+        />
+      </ElFormItem>
+    </ElForm>
+  </Modal>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/face/pack/data.ts b/apps/web-ele/src/views/im/manager/face/pack/data.ts
new file mode 100644
index 000000000..9ea351de9
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/face/pack/data.ts
@@ -0,0 +1,373 @@
+import type { VbenFormSchema } from '#/adapter/form';
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+
+import { CommonStatusEnum, DICT_TYPE } from '@vben/constants';
+import { getDictOptions } from '@vben/hooks';
+
+import { z } from '#/adapter/form';
+import { getRangePickerDefaultProps } from '#/utils';
+
+/** 表情包表单 */
+export function usePackFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'id',
+      component: 'Input',
+      dependencies: {
+        triggerFields: [''],
+        show: () => false,
+      },
+    },
+    {
+      fieldName: 'icon',
+      label: '封面',
+      component: 'ImageUpload',
+      componentProps: {
+        maxNumber: 1,
+      },
+    },
+    {
+      fieldName: 'name',
+      label: '名称',
+      component: 'Input',
+      componentProps: {
+        maxlength: 64,
+        placeholder: '请输入表情包名称',
+      },
+      rules: 'required',
+    },
+    {
+      fieldName: 'sort',
+      label: '排序',
+      component: 'InputNumber',
+      componentProps: {
+        min: 0,
+        max: 9999,
+      },
+      rules: z.number().default(0),
+    },
+    {
+      fieldName: 'status',
+      label: '状态',
+      component: 'RadioGroup',
+      componentProps: {
+        options: getDictOptions(DICT_TYPE.COMMON_STATUS, 'number'),
+        isButton: true,
+      },
+      rules: z.number().default(CommonStatusEnum.ENABLE),
+    },
+  ];
+}
+
+/** 表情包搜索表单 */
+export function usePackGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'name',
+      label: '表情包',
+      component: 'Input',
+      componentProps: {
+        clearable: true,
+        placeholder: '请输入表情包名称',
+      },
+    },
+    {
+      fieldName: 'status',
+      label: '状态',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.COMMON_STATUS, 'number'),
+        placeholder: '请选择状态',
+      },
+    },
+    {
+      fieldName: 'createTime',
+      label: '创建时间',
+      component: 'RangePicker',
+      componentProps: {
+        ...getRangePickerDefaultProps(),
+        clearable: true,
+      },
+    },
+  ];
+}
+
+/** 表情包字段 */
+export function usePackGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    { type: 'checkbox', width: 40 },
+    {
+      field: 'id',
+      title: '编号',
+      width: 100,
+    },
+    {
+      field: 'icon',
+      title: '封面',
+      width: 80,
+      slots: { default: 'icon' },
+    },
+    {
+      field: 'name',
+      title: '名称',
+      minWidth: 140,
+    },
+    {
+      field: 'sort',
+      title: '排序',
+      width: 80,
+    },
+    {
+      field: 'status',
+      title: '状态',
+      width: 100,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.COMMON_STATUS },
+      },
+    },
+    {
+      field: 'createTime',
+      title: '创建时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      title: '操作',
+      width: 240,
+      fixed: 'right',
+      slots: { default: 'actions' },
+    },
+  ];
+}
+
+/** 表情表单 */
+export function useItemFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'id',
+      component: 'Input',
+      dependencies: {
+        triggerFields: [''],
+        show: () => false,
+      },
+    },
+    {
+      fieldName: 'packId',
+      component: 'Input',
+      dependencies: {
+        triggerFields: [''],
+        show: () => false,
+      },
+    },
+    {
+      fieldName: 'url',
+      label: '表情图',
+      component: 'ImageUpload',
+      componentProps: {
+        maxNumber: 1,
+      },
+      rules: 'required',
+    },
+    {
+      fieldName: 'name',
+      label: '表情名',
+      component: 'Input',
+      componentProps: {
+        maxlength: 64,
+        placeholder: '请输入表情名',
+      },
+    },
+    {
+      fieldName: 'width',
+      label: '宽度',
+      component: 'InputNumber',
+      componentProps: {
+        min: 1,
+        max: 2048,
+      },
+      rules: 'required',
+    },
+    {
+      fieldName: 'height',
+      label: '高度',
+      component: 'InputNumber',
+      componentProps: {
+        min: 1,
+        max: 2048,
+      },
+      rules: 'required',
+    },
+    {
+      fieldName: 'sort',
+      label: '排序',
+      component: 'InputNumber',
+      componentProps: {
+        min: 0,
+        max: 9999,
+      },
+      rules: z.number().default(0),
+    },
+    {
+      fieldName: 'status',
+      label: '状态',
+      component: 'RadioGroup',
+      componentProps: {
+        options: getDictOptions(DICT_TYPE.COMMON_STATUS, 'number'),
+        isButton: true,
+      },
+      rules: z.number().default(CommonStatusEnum.ENABLE),
+    },
+  ];
+}
+
+/** 表情搜索表单 */
+export function useItemGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'name',
+      label: '表情名',
+      component: 'Input',
+      componentProps: {
+        clearable: true,
+        placeholder: '请输入表情名',
+      },
+    },
+    {
+      fieldName: 'status',
+      label: '状态',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.COMMON_STATUS, 'number'),
+        placeholder: '请选择状态',
+      },
+    },
+  ];
+}
+
+/** 表情字段 */
+export function useItemGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    { type: 'checkbox', width: 40 },
+    {
+      field: 'id',
+      title: '编号',
+      width: 80,
+    },
+    {
+      field: 'url',
+      title: '表情图',
+      width: 80,
+      slots: { default: 'image' },
+    },
+    {
+      field: 'name',
+      title: '表情名',
+      minWidth: 140,
+    },
+    {
+      title: '尺寸',
+      width: 120,
+      slots: { default: 'size' },
+    },
+    {
+      field: 'sort',
+      title: '排序',
+      width: 80,
+    },
+    {
+      field: 'status',
+      title: '状态',
+      width: 100,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.COMMON_STATUS },
+      },
+    },
+    {
+      title: '操作',
+      width: 160,
+      fixed: 'right',
+      slots: { default: 'actions' },
+    },
+  ];
+}
+
+/** 用户表情搜索表单 */
+export function useUserItemGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'userId',
+      label: '用户编号',
+      component: 'InputNumber',
+      componentProps: {
+        clearable: true,
+        placeholder: '请输入用户编号',
+      },
+    },
+    {
+      fieldName: 'name',
+      label: '表情名',
+      component: 'Input',
+      componentProps: {
+        clearable: true,
+        placeholder: '请输入表情名',
+      },
+    },
+    {
+      fieldName: 'createTime',
+      label: '添加时间',
+      component: 'RangePicker',
+      componentProps: {
+        ...getRangePickerDefaultProps(),
+        clearable: true,
+      },
+    },
+  ];
+}
+
+/** 用户表情字段 */
+export function useUserItemGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    {
+      field: 'id',
+      title: '编号',
+      width: 100,
+    },
+    {
+      field: 'url',
+      title: '表情图',
+      width: 80,
+      slots: { default: 'image' },
+    },
+    {
+      field: 'name',
+      title: '表情名',
+      minWidth: 140,
+    },
+    {
+      title: '所属用户',
+      minWidth: 180,
+      slots: { default: 'user' },
+    },
+    {
+      title: '尺寸',
+      width: 120,
+      slots: { default: 'size' },
+    },
+    {
+      field: 'createTime',
+      title: '添加时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      title: '操作',
+      width: 100,
+      fixed: 'right',
+      slots: { default: 'actions' },
+    },
+  ];
+}
diff --git a/apps/web-ele/src/views/im/manager/face/pack/index.vue b/apps/web-ele/src/views/im/manager/face/pack/index.vue
new file mode 100644
index 000000000..a18b8bf8e
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/face/pack/index.vue
@@ -0,0 +1,195 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerFacePackApi } from '#/api/im/manager/face/pack';
+
+import { ref } from 'vue';
+
+import { Page, useVbenModal } from '@vben/common-ui';
+import { isEmpty } from '@vben/utils';
+
+import { ElImage, ElLoading, ElMessage } from 'element-plus'
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
+import {
+  deleteManagerFacePack,
+  deleteManagerFacePackList,
+  getManagerFacePackPage,
+} from '#/api/im/manager/face/pack';
+import { $t } from '#/locales';
+
+import {
+  usePackGridColumns,
+  usePackGridFormSchema,
+} from './data';
+import Form from './modules/form.vue';
+import ItemDrawer from './modules/item-drawer.vue';
+
+defineOptions({ name: 'ImManagerFacePack' });
+
+const itemDrawerRef = ref<InstanceType<typeof ItemDrawer>>();
+const checkedIds = ref<number[]>([]);
+
+const [FormModal, formModalApi] = useVbenModal({
+  connectedComponent: Form,
+  destroyOnClose: true,
+});
+
+/** 刷新表格 */
+function handleRefresh() {
+  gridApi.query();
+}
+
+/** 创建表情包 */
+function handleCreate() {
+  formModalApi.setData(null).open();
+}
+
+/** 编辑表情包 */
+function handleEdit(row: ImManagerFacePackApi.FacePack) {
+  formModalApi.setData(row).open();
+}
+
+/** 打开表情管理 */
+function handleItems(row: ImManagerFacePackApi.FacePack) {
+  itemDrawerRef.value?.open(row);
+}
+
+/** 删除表情包 */
+async function handleDelete(row: ImManagerFacePackApi.FacePack) {
+  const loadingInstance = ElLoading.service({
+    text: $t('ui.actionMessage.deleting', [row.name]),
+  });
+  try {
+    await deleteManagerFacePack(row.id);
+    ElMessage.success($t('ui.actionMessage.deleteSuccess', [row.name]));
+    handleRefresh();
+  } finally {
+    loadingInstance.close();
+  }
+}
+
+/** 批量删除表情包 */
+async function handleDeleteBatch() {
+  const loadingInstance = ElLoading.service({
+    text: $t('ui.actionMessage.deletingBatch'),
+  });
+  try {
+    await deleteManagerFacePackList(checkedIds.value);
+    checkedIds.value = [];
+    ElMessage.success($t('ui.actionMessage.deleteSuccess'));
+    handleRefresh();
+  } finally {
+    loadingInstance.close();
+  }
+}
+
+/** 表格选中变化 */
+function handleRowCheckboxChange({
+  records,
+}: {
+  records: ImManagerFacePackApi.FacePack[];
+}) {
+  checkedIds.value = records.map((item) => item.id);
+}
+
+const [Grid, gridApi] = useVbenVxeGrid({
+  formOptions: {
+    schema: usePackGridFormSchema(),
+  },
+  gridOptions: {
+    columns: usePackGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerFacePackPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerFacePackApi.FacePack>,
+  gridEvents: {
+    checkboxAll: handleRowCheckboxChange,
+    checkboxChange: handleRowCheckboxChange,
+  },
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <FormModal @success="handleRefresh" />
+    <ItemDrawer ref="itemDrawerRef" />
+    <Grid table-title="表情包列表">
+      <template #toolbar-tools>
+        <TableAction
+          :actions="[
+            {
+              label: $t('ui.actionTitle.create', ['表情包']),
+              type: 'primary',
+              icon: ACTION_ICON.ADD,
+              auth: ['im:manager:face-pack:create'],
+              onClick: handleCreate,
+            },
+            {
+              label: $t('ui.actionTitle.deleteBatch'),
+              type: 'danger',
+              icon: ACTION_ICON.DELETE,
+              auth: ['im:manager:face-pack:delete'],
+              disabled: isEmpty(checkedIds),
+              popConfirm: {
+                title: $t('ui.actionMessage.deleteBatchConfirm'),
+                confirm: handleDeleteBatch,
+              },
+            },
+          ]"
+        />
+      </template>
+      <template #icon="{ row }">
+        <ElImage v-if="row.icon" :height="32" :src="row.icon" :width="32" />
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: '管理表情',
+              link: true,
+              icon: ACTION_ICON.VIEW,
+              auth: ['im:manager:face-pack-item:query'],
+              onClick: handleItems.bind(null, row),
+            },
+            {
+              label: $t('common.edit'),
+              link: true,
+              icon: ACTION_ICON.EDIT,
+              auth: ['im:manager:face-pack:update'],
+              onClick: handleEdit.bind(null, row),
+            },
+            {
+              label: $t('common.delete'),
+              link: true,
+              type: 'danger',
+              icon: ACTION_ICON.DELETE,
+              auth: ['im:manager:face-pack:delete'],
+              popConfirm: {
+                title: $t('ui.actionMessage.deleteConfirm', [row.name]),
+                confirm: handleDelete.bind(null, row),
+              },
+            },
+          ]"
+        />
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/face/pack/modules/form.vue b/apps/web-ele/src/views/im/manager/face/pack/modules/form.vue
new file mode 100644
index 000000000..f3357540a
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/face/pack/modules/form.vue
@@ -0,0 +1,83 @@
+<script lang="ts" setup>
+import type { ImManagerFacePackApi } from '#/api/im/manager/face/pack';
+
+import { computed, ref } from 'vue';
+
+import { useVbenModal } from '@vben/common-ui';
+
+import { ElMessage } from 'element-plus'
+
+import { useVbenForm } from '#/adapter/form';
+import {
+  createManagerFacePack,
+  getManagerFacePack,
+  updateManagerFacePack,
+} from '#/api/im/manager/face/pack';
+import { $t } from '#/locales';
+
+import { usePackFormSchema } from '../data';
+
+const emit = defineEmits(['success']);
+const formData = ref<ImManagerFacePackApi.FacePack>();
+const getTitle = computed(() => {
+  return formData.value?.id ? '修改表情包' : '新增表情包';
+});
+
+const [Form, formApi] = useVbenForm({
+  commonConfig: {
+    componentProps: {
+      class: 'w-full',
+    },
+    formItemClass: 'col-span-2',
+    labelWidth: 80,
+  },
+  layout: 'horizontal',
+  schema: usePackFormSchema(),
+  showDefaultActions: false,
+});
+
+const [Modal, modalApi] = useVbenModal({
+  async onConfirm() {
+    const { valid } = await formApi.validate();
+    if (!valid) {
+      return;
+    }
+    modalApi.lock();
+    const data = (await formApi.getValues()) as ImManagerFacePackApi.FacePack;
+    try {
+      await (formData.value?.id
+        ? updateManagerFacePack(data)
+        : createManagerFacePack(data));
+      await modalApi.close();
+      emit('success');
+      ElMessage.success($t('ui.actionMessage.operationSuccess'));
+    } finally {
+      modalApi.unlock();
+    }
+  },
+  async onOpenChange(isOpen: boolean) {
+    if (!isOpen) {
+      formData.value = undefined;
+      await formApi.resetForm();
+      return;
+    }
+    const data = modalApi.getData<ImManagerFacePackApi.FacePack>();
+    if (!data || !data.id) {
+      return;
+    }
+    modalApi.lock();
+    try {
+      formData.value = await getManagerFacePack(data.id);
+      await formApi.setValues(formData.value);
+    } finally {
+      modalApi.unlock();
+    }
+  },
+});
+</script>
+
+<template>
+  <Modal :title="getTitle" class="w-1/3">
+    <Form class="mx-4" />
+  </Modal>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/face/pack/modules/item-drawer.vue b/apps/web-ele/src/views/im/manager/face/pack/modules/item-drawer.vue
new file mode 100644
index 000000000..cea487b98
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/face/pack/modules/item-drawer.vue
@@ -0,0 +1,214 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerFacePackItemApi } from '#/api/im/manager/face/item';
+import type { ImManagerFacePackApi } from '#/api/im/manager/face/pack';
+
+import { computed, nextTick, ref } from 'vue';
+
+import { useVbenModal } from '@vben/common-ui';
+import { isEmpty } from '@vben/utils';
+
+import { ElDrawer, ElImage, ElLoading, ElMessage } from 'element-plus'
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
+import {
+  deleteManagerFacePackItem,
+  deleteManagerFacePackItemList,
+  getManagerFacePackItemPage,
+} from '#/api/im/manager/face/item';
+import { $t } from '#/locales';
+
+import { useItemGridColumns, useItemGridFormSchema } from '../data';
+import ItemForm from './item-form.vue';
+
+const visible = ref(false);
+const currentPack = ref<ImManagerFacePackApi.FacePack>();
+const checkedIds = ref<number[]>([]);
+const title = computed(() =>
+  currentPack.value ? `「${currentPack.value.name}」表情管理` : '表情管理',
+);
+
+const [ItemFormModal, itemFormModalApi] = useVbenModal({
+  connectedComponent: ItemForm,
+  destroyOnClose: true,
+});
+
+/** 打开抽屉 */
+function open(pack: ImManagerFacePackApi.FacePack) {
+  currentPack.value = pack;
+  visible.value = true;
+  checkedIds.value = [];
+}
+
+defineExpose({ open });
+
+/** 抽屉打开后查询表情列表 */
+async function handleOpenChange(open: boolean) {
+  if (!open) {
+    return;
+  }
+  await nextTick();
+  gridApi.query();
+}
+
+/** 刷新表格 */
+function handleRefresh() {
+  gridApi.query();
+}
+
+/** 创建表情 */
+function handleCreate() {
+  itemFormModalApi.setData({ packId: currentPack.value?.id }).open();
+}
+
+/** 编辑表情 */
+function handleEdit(row: ImManagerFacePackItemApi.FacePackItem) {
+  itemFormModalApi
+    .setData({ id: row.id, packId: currentPack.value?.id })
+    .open();
+}
+
+/** 删除表情 */
+async function handleDelete(row: ImManagerFacePackItemApi.FacePackItem) {
+  const loadingInstance = ElLoading.service({
+    text: $t('ui.actionMessage.deleting', [row.name || row.id]),
+  });
+  try {
+    await deleteManagerFacePackItem(row.id);
+    ElMessage.success($t('ui.actionMessage.deleteSuccess', [row.name || row.id]));
+    handleRefresh();
+  } finally {
+    loadingInstance.close();
+  }
+}
+
+/** 批量删除表情 */
+async function handleDeleteBatch() {
+  const loadingInstance = ElLoading.service({
+    text: $t('ui.actionMessage.deletingBatch'),
+  });
+  try {
+    await deleteManagerFacePackItemList(checkedIds.value);
+    checkedIds.value = [];
+    ElMessage.success($t('ui.actionMessage.deleteSuccess'));
+    handleRefresh();
+  } finally {
+    loadingInstance.close();
+  }
+}
+
+/** 表格选中变化 */
+function handleRowCheckboxChange({
+  records,
+}: {
+  records: ImManagerFacePackItemApi.FacePackItem[];
+}) {
+  checkedIds.value = records.map((item) => item.id);
+}
+
+const [Grid, gridApi] = useVbenVxeGrid({
+  formOptions: {
+    schema: useItemGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useItemGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerFacePackItemPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            packId: currentPack.value?.id,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerFacePackItemApi.FacePackItem>,
+  gridEvents: {
+    checkboxAll: handleRowCheckboxChange,
+    checkboxChange: handleRowCheckboxChange,
+  },
+});
+</script>
+
+<template>
+  <ElDrawer
+    v-model="visible"
+    :content="title"
+    destroy-on-close
+    width="65%"
+    @after-open-change="handleOpenChange"
+  >
+    <ItemFormModal @success="handleRefresh" />
+    <Grid table-title="表情列表">
+      <template #toolbar-tools>
+        <TableAction
+          :actions="[
+            {
+              label: $t('ui.actionTitle.create', ['表情']),
+              type: 'primary',
+              icon: ACTION_ICON.ADD,
+              auth: ['im:manager:face-pack-item:create'],
+              onClick: handleCreate,
+            },
+            {
+              label: $t('ui.actionTitle.deleteBatch'),
+              type: 'danger',
+              icon: ACTION_ICON.DELETE,
+              auth: ['im:manager:face-pack-item:delete'],
+              disabled: isEmpty(checkedIds),
+              popConfirm: {
+                title: $t('ui.actionMessage.deleteBatchConfirm'),
+                confirm: handleDeleteBatch,
+              },
+            },
+          ]"
+        />
+      </template>
+      <template #image="{ row }">
+        <ElImage v-if="row.url" :height="40" :src="row.url" :width="40" />
+      </template>
+      <template #size="{ row }">
+        <span v-if="row.width || row.height">
+          {{ row.width || '?' }} × {{ row.height || '?' }}
+        </span>
+        <span v-else>-</span>
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: $t('common.edit'),
+              link: true,
+              icon: ACTION_ICON.EDIT,
+              auth: ['im:manager:face-pack-item:update'],
+              onClick: handleEdit.bind(null, row),
+            },
+            {
+              label: $t('common.delete'),
+              link: true,
+              type: 'danger',
+              icon: ACTION_ICON.DELETE,
+              auth: ['im:manager:face-pack-item:delete'],
+              popConfirm: {
+                title: $t('ui.actionMessage.deleteConfirm', [row.name || row.id]),
+                confirm: handleDelete.bind(null, row),
+              },
+            },
+          ]"
+        />
+      </template>
+    </Grid>
+  </ElDrawer>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/face/pack/modules/item-form.vue b/apps/web-ele/src/views/im/manager/face/pack/modules/item-form.vue
new file mode 100644
index 000000000..484b1ba48
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/face/pack/modules/item-form.vue
@@ -0,0 +1,119 @@
+<script lang="ts" setup>
+import type { ImManagerFacePackItemApi } from '#/api/im/manager/face/item';
+
+import { computed, ref, watch } from 'vue';
+
+import { useVbenModal } from '@vben/common-ui';
+
+import { ElMessage } from 'element-plus'
+
+import { useVbenForm } from '#/adapter/form';
+import {
+  createManagerFacePackItem,
+  getManagerFacePackItem,
+  updateManagerFacePackItem,
+} from '#/api/im/manager/face/item';
+import { $t } from '#/locales';
+import { probeImageSize } from '#/views/im/manager/utils/format';
+
+import { useItemFormSchema } from '../data';
+
+const emit = defineEmits(['success']);
+const formData = ref<ImManagerFacePackItemApi.FacePackItem>();
+const packId = ref(0);
+const lastUrl = ref('');
+const getTitle = computed(() => {
+  return formData.value?.id ? '修改表情' : '新增表情';
+});
+
+const [Form, formApi] = useVbenForm({
+  commonConfig: {
+    componentProps: {
+      class: 'w-full',
+    },
+    formItemClass: 'col-span-2',
+    labelWidth: 80,
+  },
+  layout: 'horizontal',
+  schema: useItemFormSchema(),
+  showDefaultActions: false,
+});
+
+/** 回填图片尺寸 */
+async function applyImageSize(url?: string) {
+  if (!url) {
+    lastUrl.value = '';
+    await formApi.setFieldValue('width', undefined);
+    await formApi.setFieldValue('height', undefined);
+    return;
+  }
+  if (url === lastUrl.value) {
+    return;
+  }
+  lastUrl.value = url;
+  try {
+    const size = await probeImageSize(url);
+    await formApi.setFieldValue('width', size.width);
+    await formApi.setFieldValue('height', size.height);
+  } catch {
+    ElMessage.warning('图片尺寸探测失败，请手动填写宽高');
+  }
+}
+
+watch(
+  () => formApi.form.values?.url,
+  (url) => {
+    void applyImageSize(url as string | undefined);
+  },
+);
+
+const [Modal, modalApi] = useVbenModal({
+  async onConfirm() {
+    const { valid } = await formApi.validate();
+    if (!valid) {
+      return;
+    }
+    modalApi.lock();
+    const data = (await formApi.getValues()) as ImManagerFacePackItemApi.FacePackItem;
+    try {
+      data.packId = data.packId || packId.value;
+      await (formData.value?.id
+        ? updateManagerFacePackItem(data)
+        : createManagerFacePackItem(data));
+      await modalApi.close();
+      emit('success');
+      ElMessage.success($t('ui.actionMessage.operationSuccess'));
+    } finally {
+      modalApi.unlock();
+    }
+  },
+  async onOpenChange(isOpen: boolean) {
+    if (!isOpen) {
+      formData.value = undefined;
+      lastUrl.value = '';
+      await formApi.resetForm();
+      return;
+    }
+    const data = modalApi.getData<{ id?: number; packId: number }>();
+    packId.value = data?.packId || 0;
+    await formApi.setValues({ packId: packId.value, sort: 0 });
+    if (!data?.id) {
+      return;
+    }
+    modalApi.lock();
+    try {
+      formData.value = await getManagerFacePackItem(data.id);
+      lastUrl.value = formData.value.url;
+      await formApi.setValues(formData.value);
+    } finally {
+      modalApi.unlock();
+    }
+  },
+});
+</script>
+
+<template>
+  <Modal :title="getTitle" class="w-1/3">
+    <Form class="mx-4" />
+  </Modal>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/face/userItem/index.vue b/apps/web-ele/src/views/im/manager/face/userItem/index.vue
new file mode 100644
index 000000000..86b27aca9
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/face/userItem/index.vue
@@ -0,0 +1,105 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerFaceUserItemApi } from '#/api/im/manager/face/useritem';
+
+import { Page } from '@vben/common-ui';
+
+import { ElImage, ElLoading, ElMessage } from 'element-plus'
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
+import {
+  deleteManagerFaceUserItem,
+  getManagerFaceUserItemPage,
+} from '#/api/im/manager/face/useritem';
+import { $t } from '#/locales';
+import { formatUserLabel } from '#/views/im/manager/utils/format';
+
+import { useUserItemGridColumns, useUserItemGridFormSchema } from '../pack/data';
+
+defineOptions({ name: 'ImManagerFaceUserItem' });
+
+/** 刷新表格 */
+function handleRefresh() {
+  gridApi.query();
+}
+
+/** 删除用户表情 */
+async function handleDelete(row: ImManagerFaceUserItemApi.FaceUserItem) {
+  const loadingInstance = ElLoading.service({
+    text: $t('ui.actionMessage.deleting', [row.name || row.id]),
+  });
+  try {
+    await deleteManagerFaceUserItem(row.id);
+    ElMessage.success($t('ui.actionMessage.deleteSuccess', [row.name || row.id]));
+    handleRefresh();
+  } finally {
+    loadingInstance.close();
+  }
+}
+
+const [Grid, gridApi] = useVbenVxeGrid({
+  formOptions: {
+    schema: useUserItemGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useUserItemGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerFaceUserItemPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerFaceUserItemApi.FaceUserItem>,
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <Grid table-title="用户表情列表">
+      <template #image="{ row }">
+        <ElImage v-if="row.url" :height="40" :src="row.url" :width="40" />
+      </template>
+      <template #user="{ row }">
+        {{ formatUserLabel(row.userNickname, row.userId) }}
+      </template>
+      <template #size="{ row }">
+        <span v-if="row.width || row.height">
+          {{ row.width || '?' }} × {{ row.height || '?' }}
+        </span>
+        <span v-else>-</span>
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: $t('common.delete'),
+              link: true,
+              type: 'danger',
+              icon: ACTION_ICON.DELETE,
+              auth: ['im:manager:face-user-item:delete'],
+              popConfirm: {
+                title: $t('ui.actionMessage.deleteConfirm', [row.name || row.id]),
+                confirm: handleDelete.bind(null, row),
+              },
+            },
+          ]"
+        />
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/friend/data.ts b/apps/web-ele/src/views/im/manager/friend/data.ts
new file mode 100644
index 000000000..42518c055
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/friend/data.ts
@@ -0,0 +1,264 @@
+import type { VbenFormSchema } from '#/adapter/form';
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+
+import { markRaw } from 'vue';
+
+import { DICT_TYPE } from '@vben/constants';
+import { getDictOptions } from '@vben/hooks';
+
+import { getRangePickerDefaultProps } from '#/utils';
+import { UserSelect } from '#/views/system/user/components';
+
+/** 好友关系搜索表单 */
+export function useFriendGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'userId',
+      label: '用户',
+      component: markRaw(UserSelect),
+    },
+    {
+      fieldName: 'friendUserId',
+      label: '好友',
+      component: markRaw(UserSelect),
+      componentProps: {
+        placeholder: '请选择好友',
+      },
+    },
+    {
+      fieldName: 'status',
+      label: '好友状态',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_FRIEND_STATUS, 'number'),
+        placeholder: '请选择好友状态',
+      },
+    },
+    {
+      fieldName: 'silent',
+      label: '免打扰',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.INFRA_BOOLEAN_STRING, 'boolean'),
+        placeholder: '请选择免打扰状态',
+      },
+    },
+    {
+      fieldName: 'addTime',
+      label: '添加时间',
+      component: 'RangePicker',
+      componentProps: {
+        ...getRangePickerDefaultProps(),
+        clearable: true,
+      },
+    },
+  ];
+}
+
+/** 好友关系列表字段 */
+export function useFriendGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    {
+      field: 'id',
+      title: '编号',
+      width: 100,
+    },
+    {
+      title: '用户',
+      minWidth: 180,
+      slots: { default: 'user' },
+    },
+    {
+      title: '好友',
+      minWidth: 180,
+      slots: { default: 'friend' },
+    },
+    {
+      field: 'displayName',
+      title: '备注',
+      minWidth: 120,
+    },
+    {
+      field: 'addSource',
+      title: '添加来源',
+      width: 120,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_FRIEND_ADD_SOURCE },
+      },
+    },
+    {
+      field: 'silent',
+      title: '免打扰',
+      width: 90,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.INFRA_BOOLEAN_STRING },
+      },
+    },
+    {
+      field: 'pinned',
+      title: '置顶',
+      width: 80,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.INFRA_BOOLEAN_STRING },
+      },
+    },
+    {
+      field: 'blocked',
+      title: '拉黑',
+      width: 80,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.INFRA_BOOLEAN_STRING },
+      },
+    },
+    {
+      field: 'status',
+      title: '状态',
+      width: 100,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_FRIEND_STATUS },
+      },
+    },
+    {
+      field: 'addTime',
+      title: '添加时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      field: 'deleteTime',
+      title: '删除时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      title: '操作',
+      width: 120,
+      fixed: 'right',
+      slots: { default: 'actions' },
+    },
+  ];
+}
+
+/** 好友申请搜索表单 */
+export function useFriendRequestGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'fromUserId',
+      label: '发起方',
+      component: markRaw(UserSelect),
+      componentProps: {
+        placeholder: '请选择发起方',
+      },
+    },
+    {
+      fieldName: 'toUserId',
+      label: '接收方',
+      component: markRaw(UserSelect),
+      componentProps: {
+        placeholder: '请选择接收方',
+      },
+    },
+    {
+      fieldName: 'handleResult',
+      label: '处理结果',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_FRIEND_REQUEST_HANDLE_RESULT, 'number'),
+        placeholder: '请选择处理结果',
+      },
+    },
+    {
+      fieldName: 'addSource',
+      label: '添加来源',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_FRIEND_ADD_SOURCE, 'number'),
+        placeholder: '请选择添加来源',
+      },
+    },
+    {
+      fieldName: 'createTime',
+      label: '创建时间',
+      component: 'RangePicker',
+      componentProps: {
+        ...getRangePickerDefaultProps(),
+        clearable: true,
+      },
+    },
+  ];
+}
+
+/** 好友申请列表字段 */
+export function useFriendRequestGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    {
+      field: 'id',
+      title: '编号',
+      width: 100,
+    },
+    {
+      title: '发起方',
+      minWidth: 180,
+      slots: { default: 'fromUser' },
+    },
+    {
+      title: '接收方',
+      minWidth: 180,
+      slots: { default: 'toUser' },
+    },
+    {
+      field: 'applyContent',
+      title: '申请理由',
+      minWidth: 160,
+    },
+    {
+      field: 'displayName',
+      title: '备注',
+      minWidth: 120,
+    },
+    {
+      field: 'addSource',
+      title: '添加来源',
+      width: 120,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_FRIEND_ADD_SOURCE },
+      },
+    },
+    {
+      field: 'handleResult',
+      title: '处理结果',
+      width: 110,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_FRIEND_REQUEST_HANDLE_RESULT },
+      },
+    },
+    {
+      field: 'handleContent',
+      title: '处理理由',
+      minWidth: 140,
+    },
+    {
+      field: 'handleTime',
+      title: '处理时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      field: 'createTime',
+      title: '创建时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+  ];
+}
diff --git a/apps/web-ele/src/views/im/manager/friend/index.vue b/apps/web-ele/src/views/im/manager/friend/index.vue
new file mode 100644
index 000000000..7f9b33186
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/friend/index.vue
@@ -0,0 +1,84 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerFriendApi } from '#/api/im/manager/friend';
+
+import { useRouter } from 'vue-router';
+
+import { Page } from '@vben/common-ui';
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
+import { getManagerFriendPage } from '#/api/im/manager/friend';
+import { formatUserLabel } from '#/views/im/manager/utils/format';
+
+import { useFriendGridColumns, useFriendGridFormSchema } from './data';
+
+defineOptions({ name: 'ImManagerFriend' });
+
+const router = useRouter();
+
+/** 查看私聊消息 */
+function handleConversation(row: ImManagerFriendApi.Friend) {
+  router.push({
+    name: 'ImPrivateMessage',
+    query: {
+      senderId: row.userId,
+      receiverId: row.friendUserId,
+    },
+  });
+}
+
+const [Grid] = useVbenVxeGrid({
+  formOptions: {
+    schema: useFriendGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useFriendGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerFriendPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerFriendApi.Friend>,
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <Grid table-title="好友关系列表">
+      <template #user="{ row }">
+        {{ formatUserLabel(row.userNickname, row.userId) }}
+      </template>
+      <template #friend="{ row }">
+        {{ formatUserLabel(row.friendNickname, row.friendUserId) }}
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: '查看对话',
+              link: true,
+              icon: ACTION_ICON.VIEW,
+              onClick: handleConversation.bind(null, row),
+            },
+          ]"
+        />
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/friend/request/index.vue b/apps/web-ele/src/views/im/manager/friend/request/index.vue
new file mode 100644
index 000000000..57c0a0700
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/friend/request/index.vue
@@ -0,0 +1,60 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerFriendRequestApi } from '#/api/im/manager/friend/request';
+
+import { Page } from '@vben/common-ui';
+
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+import { getManagerFriendRequestPage } from '#/api/im/manager/friend/request';
+import { formatUserLabel } from '#/views/im/manager/utils/format';
+
+import {
+  useFriendRequestGridColumns,
+  useFriendRequestGridFormSchema,
+} from '../data';
+
+defineOptions({ name: 'ImManagerFriendRequest' });
+
+const [Grid] = useVbenVxeGrid({
+  formOptions: {
+    schema: useFriendRequestGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useFriendRequestGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerFriendRequestPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerFriendRequestApi.FriendRequest>,
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <Grid table-title="好友申请列表">
+      <template #fromUser="{ row }">
+        {{ formatUserLabel(row.fromNickname, row.fromUserId) }}
+      </template>
+      <template #toUser="{ row }">
+        {{ formatUserLabel(row.toNickname, row.toUserId) }}
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/group/components/index.ts b/apps/web-ele/src/views/im/manager/group/components/index.ts
new file mode 100644
index 000000000..4bbf84f44
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/group/components/index.ts
@@ -0,0 +1,2 @@
+export { default as GroupSelectDialog } from './select-dialog.vue';
+export { default as GroupSelect } from './select.vue';
diff --git a/apps/web-ele/src/views/im/manager/group/components/select-dialog.vue b/apps/web-ele/src/views/im/manager/group/components/select-dialog.vue
new file mode 100644
index 000000000..e61a0ddd4
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/group/components/select-dialog.vue
@@ -0,0 +1,271 @@
+<script lang="ts" setup>
+import type { VbenFormSchema } from '#/adapter/form';
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerGroupApi } from '#/api/im/manager/group';
+
+import { nextTick, ref } from 'vue';
+
+import { DICT_TYPE } from '@vben/constants';
+import { getDictOptions } from '@vben/hooks';
+
+import { ElButton, ElDialog, ElMessage } from 'element-plus'
+
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+import {
+  getManagerGroup,
+  getManagerGroupPage,
+} from '#/api/im/manager/group';
+
+const emit = defineEmits<{
+  selected: [rows: ImManagerGroupApi.Group[]];
+}>();
+
+const open = ref(false); // 弹窗是否打开
+const multiple = ref(false); // 是否多选
+const selectedRows = ref<ImManagerGroupApi.Group[]>([]); // 已选群列表
+const preSelectedIds = ref<number[]>([]); // 预选群编号列表
+
+/** 群选择弹窗的搜索表单 */
+function useGroupSelectGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'name',
+      label: '群名称',
+      component: 'Input',
+      componentProps: {
+        clearable: true,
+        placeholder: '请输入群名称',
+      },
+    },
+    {
+      fieldName: 'status',
+      label: '群状态',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_GROUP_STATUS, 'number'),
+        placeholder: '请选择群状态',
+      },
+    },
+  ];
+}
+
+/** 群选择弹窗的字段 */
+function useGroupSelectGridColumns(
+  isMultiple = false,
+): VxeTableGridOptions<ImManagerGroupApi.Group>['columns'] {
+  return [
+    {
+      type: isMultiple ? 'checkbox' : 'radio',
+      width: 50,
+    },
+    {
+      field: 'id',
+      title: '编号',
+      width: 100,
+    },
+    {
+      field: 'name',
+      title: '群名称',
+      minWidth: 160,
+    },
+    {
+      field: 'ownerNickname',
+      title: '群主',
+      minWidth: 160,
+    },
+    {
+      field: 'memberCount',
+      title: '成员数',
+      width: 90,
+    },
+    {
+      field: 'status',
+      title: '群状态',
+      width: 100,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_GROUP_STATUS },
+      },
+    },
+  ];
+}
+
+/** 获取多选记录，包含 VXE reserve 跨页记录 */
+function getMultipleSelectedRows() {
+  const selectedMap = new Map<number, ImManagerGroupApi.Group>();
+  const records = [
+    ...(gridApi.grid.getCheckboxReserveRecords?.() ?? []),
+    ...(gridApi.grid.getCheckboxRecords?.() ?? []),
+  ] as ImManagerGroupApi.Group[];
+  records.forEach((row) => {
+    selectedMap.set(row.id, row);
+  });
+  return [...selectedMap.values()];
+}
+
+/** 处理多选勾选变化 */
+function handleCheckboxSelectChange() {
+  selectedRows.value = getMultipleSelectedRows();
+}
+
+/** 处理单选切换 */
+function handleRadioChange(row: ImManagerGroupApi.Group) {
+  selectedRows.value = [row];
+}
+
+/** 多选模式下切换行勾选 */
+async function toggleMultipleRow(row: ImManagerGroupApi.Group) {
+  const selected = gridApi.grid.isCheckedByCheckboxRow(row);
+  await gridApi.grid.setCheckboxRow(row, !selected);
+  selectedRows.value = getMultipleSelectedRows();
+}
+
+/** 处理行双击：单选直接确认，多选切换勾选 */
+async function handleCellDblclick({ row }: { row: ImManagerGroupApi.Group }) {
+  if (multiple.value) {
+    await toggleMultipleRow(row);
+    return;
+  }
+  selectedRows.value = [row];
+  await gridApi.grid.setRadioRow(row);
+  handleConfirm();
+}
+
+/** 回显预选群 */
+async function applyPreSelection() {
+  if (preSelectedIds.value.length === 0) {
+    return;
+  }
+  const rows = gridApi.grid.getData() as ImManagerGroupApi.Group[];
+  for (const row of rows) {
+    if (!preSelectedIds.value.includes(row.id)) {
+      continue;
+    }
+    if (multiple.value) {
+      await gridApi.grid.setCheckboxRow(row, true);
+    } else {
+      await gridApi.grid.setRadioRow(row);
+      selectedRows.value = [row];
+      return;
+    }
+  }
+  if (multiple.value) {
+    selectedRows.value = getMultipleSelectedRows();
+    return;
+  }
+  const targetId = preSelectedIds.value[0];
+  if (targetId) {
+    selectedRows.value = [await getManagerGroup(targetId)];
+  }
+}
+
+const [Grid, gridApi] = useVbenVxeGrid({
+  formOptions: {
+    schema: useGroupSelectGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useGroupSelectGridColumns(false),
+    height: 520,
+    keepSource: true,
+    checkboxConfig: {
+      highlight: true,
+      range: true,
+      reserve: true,
+    },
+    radioConfig: {
+      highlight: true,
+      trigger: 'row',
+    },
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerGroupPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerGroupApi.Group>,
+  gridEvents: {
+    cellDblclick: handleCellDblclick,
+    checkboxAll: handleCheckboxSelectChange,
+    checkboxChange: handleCheckboxSelectChange,
+    radioChange: ({ row }: { row: ImManagerGroupApi.Group }) => {
+      handleRadioChange(row);
+    },
+  },
+});
+
+/** 重置查询和选择状态 */
+async function resetQueryState() {
+  selectedRows.value = [];
+  await gridApi.grid.clearCheckboxRow();
+  await gridApi.grid.clearCheckboxReserve();
+  await gridApi.grid.clearRadioRow();
+  await gridApi.formApi.resetForm();
+}
+
+/** 打开群选择弹窗 */
+async function openModal(
+  selectedIds?: number[],
+  options?: { multiple?: boolean },
+) {
+  open.value = true;
+  multiple.value = options?.multiple ?? false;
+  preSelectedIds.value = selectedIds || [];
+  await nextTick();
+  gridApi.setGridOptions({
+    columns: useGroupSelectGridColumns(multiple.value),
+  });
+  await resetQueryState();
+  await gridApi.query();
+  await nextTick();
+  await applyPreSelection();
+}
+
+/** 关闭群选择弹窗 */
+function closeModal() {
+  open.value = false;
+}
+
+/** 确认选择群 */
+function handleConfirm() {
+  const rows = multiple.value ? getMultipleSelectedRows() : selectedRows.value;
+  if (rows.length === 0) {
+    ElMessage.warning(multiple.value ? '请至少选择一条数据' : '请选择一条数据');
+    return;
+  }
+  emit('selected', multiple.value ? rows : [rows[0]!]);
+  open.value = false;
+}
+
+defineExpose({ open: openModal });
+</script>
+
+<template>
+  <ElDialog
+    v-model="open"
+    title="群选择"
+    width="70%"
+    :destroy-on-close="true"
+    @ok="handleConfirm"
+    @cancel="closeModal"
+  >
+    <Grid table-title="群列表" />
+    <template #footer>
+      <ElButton @click="closeModal">取消</ElButton>
+      <ElButton type="primary" @click="handleConfirm">确定</ElButton>
+    </template>
+  </ElDialog>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/group/components/select.vue b/apps/web-ele/src/views/im/manager/group/components/select.vue
new file mode 100644
index 000000000..22ff65a20
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/group/components/select.vue
@@ -0,0 +1,129 @@
+<script lang="ts" setup>
+import type { ImManagerGroupApi } from '#/api/im/manager/group';
+
+import { computed, ref, useAttrs, watch } from 'vue';
+
+import { IconifyIcon } from '@vben/icons';
+
+import { ElInput, ElTooltip } from 'element-plus'
+
+import { getManagerGroup } from '#/api/im/manager/group';
+
+import GroupSelectDialog from './select-dialog.vue';
+
+defineOptions({ name: 'ImManagerGroupSelect', inheritAttrs: false });
+
+const props = withDefaults(
+  defineProps<{
+    clearable?: boolean;
+    disabled?: boolean;
+    modelValue?: number;
+    placeholder?: string;
+  }>(),
+  {
+    clearable: true,
+    disabled: false,
+    modelValue: undefined,
+    placeholder: '请选择群',
+  },
+);
+
+const emit = defineEmits<{
+  change: [item: ImManagerGroupApi.Group | undefined];
+  'update:modelValue': [value: number | undefined];
+}>();
+
+const attrs = useAttrs();
+const dialogRef = ref<InstanceType<typeof GroupSelectDialog>>(); // 群选择弹窗
+const hovering = ref(false); // 鼠标是否悬停
+const selectedItem = ref<ImManagerGroupApi.Group>(); // 已选群
+
+/** 输入框显示文本 */
+const displayLabel = computed(() => selectedItem.value?.name ?? '');
+
+/** 是否显示清除图标 */
+const showClear = computed(() => {
+  return props.clearable && !props.disabled && hovering.value && props.modelValue != null;
+});
+
+/** 根据编号查询群信息（用于编辑回显） */
+async function resolveItemById(id: number | undefined) {
+  if (id == null) {
+    selectedItem.value = undefined;
+    return;
+  }
+  if (selectedItem.value?.id === id) {
+    return;
+  }
+  selectedItem.value = await getManagerGroup(id);
+}
+
+watch(() => props.modelValue, resolveItemById, { immediate: true });
+
+/** 清空已选群 */
+function clearSelected() {
+  selectedItem.value = undefined;
+  emit('update:modelValue', undefined);
+  emit('change', undefined);
+}
+
+/** 打开群选择弹窗 */
+function handleClick(event: MouseEvent) {
+  if (props.disabled) {
+    return;
+  }
+  const target = event.target as HTMLElement;
+  if (showClear.value && target.closest('.el-input__suffix')) {
+    event.stopPropagation();
+    clearSelected();
+    return;
+  }
+  dialogRef.value?.open(props.modelValue == null ? [] : [props.modelValue]);
+}
+
+/** 弹窗选中回调 */
+function handleSelected(rows: ImManagerGroupApi.Group[]) {
+  const item = rows[0];
+  if (!item) {
+    return;
+  }
+  selectedItem.value = item;
+  emit('update:modelValue', item.id);
+  emit('change', item);
+}
+</script>
+
+<template>
+  <div
+    v-bind="attrs"
+    class="w-full"
+    :class="disabled ? 'cursor-not-allowed' : 'cursor-pointer'"
+    @click="handleClick"
+    @mouseenter="hovering = true"
+    @mouseleave="hovering = false"
+  >
+    <ElTooltip :disabled="!selectedItem" placement="top" :show-after="500">
+      <template #content>
+        <div v-if="selectedItem" class="leading-6">
+          <div>群名称：{{ selectedItem.name || '-' }}</div>
+          <div>群主：{{ selectedItem.ownerNickname || '-' }}</div>
+          <div>成员数：{{ selectedItem.memberCount ?? '-' }}</div>
+        </div>
+      </template>
+      <ElInput
+        :disabled="disabled"
+        :placeholder="placeholder"
+        :model-value="displayLabel"
+        readonly
+      >
+        <template #suffix>
+          <IconifyIcon
+            class="size-4"
+            :icon="showClear ? 'lucide:circle-x' : 'lucide:search'"
+          />
+        </template>
+      </ElInput>
+    </ElTooltip>
+  </div>
+  <GroupSelectDialog ref="dialogRef" @selected="handleSelected" />
+</template>
diff --git a/apps/web-ele/src/views/im/manager/group/data.ts b/apps/web-ele/src/views/im/manager/group/data.ts
new file mode 100644
index 000000000..1c3508bc4
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/group/data.ts
@@ -0,0 +1,255 @@
+import type { VbenFormSchema } from '#/adapter/form';
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+
+import { markRaw } from 'vue';
+
+import { DICT_TYPE } from '@vben/constants';
+import { getDictOptions } from '@vben/hooks';
+
+import { getRangePickerDefaultProps } from '#/utils';
+import { GroupSelect } from '#/views/im/manager/group/components';
+import { UserSelect } from '#/views/system/user/components';
+
+/** 群搜索表单 */
+export function useGroupGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'name',
+      label: '群名称',
+      component: 'Input',
+      componentProps: {
+        clearable: true,
+        placeholder: '请输入群名称',
+      },
+    },
+    {
+      fieldName: 'ownerUserId',
+      label: '群主',
+      component: markRaw(UserSelect),
+      componentProps: {
+        placeholder: '请选择群主',
+      },
+    },
+    {
+      fieldName: 'status',
+      label: '群状态',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_GROUP_STATUS, 'number'),
+        placeholder: '请选择群状态',
+      },
+    },
+    {
+      fieldName: 'banned',
+      label: '是否封禁',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.INFRA_BOOLEAN_STRING, 'boolean'),
+        placeholder: '请选择封禁状态',
+      },
+    },
+    {
+      fieldName: 'createTime',
+      label: '创建时间',
+      component: 'RangePicker',
+      componentProps: {
+        ...getRangePickerDefaultProps(),
+        clearable: true,
+      },
+    },
+  ];
+}
+
+/** 群列表字段 */
+export function useGroupGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    {
+      field: 'id',
+      title: '编号',
+      width: 100,
+    },
+    {
+      field: 'avatar',
+      title: '头像',
+      width: 80,
+      slots: { default: 'avatar' },
+    },
+    {
+      field: 'name',
+      title: '群名称',
+      minWidth: 160,
+    },
+    {
+      title: '群主',
+      minWidth: 180,
+      slots: { default: 'owner' },
+    },
+    {
+      field: 'memberCount',
+      title: '成员数',
+      width: 90,
+    },
+    {
+      field: 'status',
+      title: '群状态',
+      width: 100,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_GROUP_STATUS },
+      },
+    },
+    {
+      field: 'banned',
+      title: '封禁状态',
+      width: 120,
+      slots: { default: 'banned' },
+    },
+    {
+      field: 'mutedAll',
+      title: '全群禁言',
+      width: 100,
+      slots: { default: 'mutedAll' },
+    },
+    {
+      field: 'createTime',
+      title: '创建时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      title: '操作',
+      width: 320,
+      fixed: 'right',
+      slots: { default: 'actions' },
+    },
+  ];
+}
+
+/** 加群申请搜索表单 */
+export function useGroupRequestGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'groupId',
+      label: '群',
+      component: markRaw(GroupSelect),
+    },
+    {
+      fieldName: 'userId',
+      label: '申请人',
+      component: markRaw(UserSelect),
+      componentProps: {
+        placeholder: '请选择申请人',
+      },
+    },
+    {
+      fieldName: 'inviterUserId',
+      label: '邀请人',
+      component: markRaw(UserSelect),
+      componentProps: {
+        placeholder: '请选择邀请人',
+      },
+    },
+    {
+      fieldName: 'handleResult',
+      label: '处理结果',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_GROUP_REQUEST_HANDLE_RESULT, 'number'),
+        placeholder: '请选择处理结果',
+      },
+    },
+    {
+      fieldName: 'addSource',
+      label: '加入来源',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_GROUP_ADD_SOURCE, 'number'),
+        placeholder: '请选择加入来源',
+      },
+    },
+    {
+      fieldName: 'createTime',
+      label: '创建时间',
+      component: 'RangePicker',
+      componentProps: {
+        ...getRangePickerDefaultProps(),
+        clearable: true,
+      },
+    },
+  ];
+}
+
+/** 加群申请列表字段 */
+export function useGroupRequestGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    {
+      field: 'id',
+      title: '编号',
+      width: 100,
+    },
+    {
+      title: '群',
+      minWidth: 180,
+      slots: { default: 'group' },
+    },
+    {
+      title: '申请人 / 被邀请人',
+      minWidth: 200,
+      slots: { default: 'user' },
+    },
+    {
+      title: '邀请人',
+      minWidth: 180,
+      slots: { default: 'inviter' },
+    },
+    {
+      field: 'applyContent',
+      title: '申请理由',
+      minWidth: 160,
+    },
+    {
+      field: 'addSource',
+      title: '加入来源',
+      width: 120,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_GROUP_ADD_SOURCE },
+      },
+    },
+    {
+      field: 'handleResult',
+      title: '处理结果',
+      width: 110,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_GROUP_REQUEST_HANDLE_RESULT },
+      },
+    },
+    {
+      title: '处理人',
+      minWidth: 180,
+      slots: { default: 'handler' },
+    },
+    {
+      field: 'handleContent',
+      title: '处理理由',
+      minWidth: 140,
+    },
+    {
+      field: 'handleTime',
+      title: '处理时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      field: 'createTime',
+      title: '创建时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+  ];
+}
diff --git a/apps/web-ele/src/views/im/manager/group/index.vue b/apps/web-ele/src/views/im/manager/group/index.vue
new file mode 100644
index 000000000..417768ca3
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/group/index.vue
@@ -0,0 +1,169 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerGroupApi } from '#/api/im/manager/group';
+
+import { ref } from 'vue';
+import { useRouter } from 'vue-router';
+
+import { confirm, Page, useVbenModal } from '@vben/common-ui';
+import { CommonStatusEnum, DICT_TYPE } from '@vben/constants';
+
+import { ElAvatar, ElMessage, ElTag, ElTooltip } from 'element-plus'
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
+import {
+  dissolveManagerGroup,
+  getManagerGroupPage,
+  unbanManagerGroup,
+} from '#/api/im/manager/group';
+import { DictTag } from '#/components/dict-tag';
+import { formatUserLabel } from '#/views/im/manager/utils/format';
+
+import { useGroupGridColumns, useGroupGridFormSchema } from './data';
+import BanForm from './modules/ban-form.vue';
+import Detail from './modules/detail.vue';
+
+defineOptions({ name: 'ImManagerGroup' });
+
+const router = useRouter();
+const detailRef = ref<InstanceType<typeof Detail>>();
+
+const [BanModal, banModalApi] = useVbenModal({
+  connectedComponent: BanForm,
+  destroyOnClose: true,
+});
+
+/** 刷新表格 */
+function handleRefresh() {
+  gridApi.query();
+}
+
+/** 打开详情 */
+function handleDetail(row: ImManagerGroupApi.Group) {
+  detailRef.value?.open(row);
+}
+
+/** 查看群聊消息 */
+function handleConversation(row: ImManagerGroupApi.Group) {
+  router.push({
+    name: 'ImGroupMessage',
+    query: { groupId: row.id },
+  });
+}
+
+/** 打开封禁弹窗 */
+function handleBan(row: ImManagerGroupApi.Group) {
+  banModalApi.setData(row).open();
+}
+
+/** 解封群 */
+async function handleUnban(row: ImManagerGroupApi.Group) {
+  await confirm(`确认解封群「${row.name}」吗？`);
+  await unbanManagerGroup(row.id);
+  ElMessage.success('解封成功');
+  handleRefresh();
+}
+
+/** 解散群 */
+async function handleDissolve(row: ImManagerGroupApi.Group) {
+  await confirm(`确认解散群「${row.name}」吗？`);
+  await dissolveManagerGroup(row.id);
+  ElMessage.success('解散成功');
+  handleRefresh();
+}
+
+const [Grid, gridApi] = useVbenVxeGrid({
+  formOptions: {
+    schema: useGroupGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useGroupGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerGroupPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerGroupApi.Group>,
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <BanModal @success="handleRefresh" />
+    <Detail ref="detailRef" />
+    <Grid table-title="群列表">
+      <template #avatar="{ row }">
+        <ElAvatar :src="row.avatar" :size="40">
+          {{ row.name?.charAt(0) || '?' }}
+        </ElAvatar>
+      </template>
+      <template #owner="{ row }">
+        {{ formatUserLabel(row.ownerNickname, row.ownerUserId) }}
+      </template>
+      <template #banned="{ row }">
+        <ElTooltip v-if="row.banned" :content="row.bannedReason">
+          <span class="inline-flex">
+            <DictTag :type="DICT_TYPE.INFRA_BOOLEAN_STRING" :value="row.banned" />
+          </span>
+        </ElTooltip>
+        <DictTag v-else :type="DICT_TYPE.INFRA_BOOLEAN_STRING" :value="row.banned" />
+      </template>
+      <template #mutedAll="{ row }">
+        <ElTag v-if="row.mutedAll" type="danger">已禁言</ElTag>
+        <ElTag v-else>未禁言</ElTag>
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: '详情',
+              link: true,
+              icon: ACTION_ICON.VIEW,
+              auth: ['im:manager:group:query'],
+              onClick: handleDetail.bind(null, row),
+            },
+            {
+              label: '查看对话',
+              link: true,
+              icon: ACTION_ICON.VIEW,
+              onClick: handleConversation.bind(null, row),
+            },
+            {
+              label: row.banned ? '解封' : '封禁',
+              link: true,
+              type: row.banned ? 'primary' : 'danger',
+              icon: ACTION_ICON.CLOSE,
+              auth: ['im:manager:group:ban'],
+              onClick: row.banned ? handleUnban.bind(null, row) : handleBan.bind(null, row),
+            },
+            {
+              label: '解散',
+              link: true,
+              type: 'danger',
+              icon: ACTION_ICON.DELETE,
+              auth: ['im:manager:group:dissolve'],
+              ifShow: row.status === CommonStatusEnum.ENABLE,
+              onClick: handleDissolve.bind(null, row),
+            },
+          ]"
+        />
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/group/modules/ban-form.vue b/apps/web-ele/src/views/im/manager/group/modules/ban-form.vue
new file mode 100644
index 000000000..bd8b1a2ec
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/group/modules/ban-form.vue
@@ -0,0 +1,66 @@
+<script lang="ts" setup>
+import type { ImManagerGroupApi } from '#/api/im/manager/group';
+
+import { reactive } from 'vue';
+
+import { useVbenModal } from '@vben/common-ui';
+
+import { ElForm, ElFormItem, ElInput, ElMessage } from 'element-plus'
+
+import { banManagerGroup } from '#/api/im/manager/group';
+
+const emit = defineEmits(['success']);
+
+const formData = reactive({
+  id: 0,
+  groupName: '',
+  reason: '',
+});
+
+const [Modal, modalApi] = useVbenModal({
+  async onConfirm() {
+    if (!formData.reason.trim()) {
+      ElMessage.warning('请输入封禁原因');
+      return;
+    }
+    modalApi.lock();
+    try {
+      await banManagerGroup({ id: formData.id, reason: formData.reason });
+      await modalApi.close();
+      emit('success');
+      ElMessage.success('封禁成功');
+    } finally {
+      modalApi.unlock();
+    }
+  },
+  onOpenChange(isOpen: boolean) {
+    if (!isOpen) {
+      return;
+    }
+    const data = modalApi.getData<ImManagerGroupApi.Group>();
+    formData.id = data.id;
+    formData.groupName = data.name;
+    formData.reason = '';
+  },
+});
+</script>
+
+<template>
+  <Modal title="封禁群" class="w-1/3">
+    <ElForm label-width="80px">
+      <ElFormItem label="群名称">
+        {{ formData.groupName }}
+      </ElFormItem>
+      <ElFormItem label="封禁原因" required>
+        <ElInput
+type="textarea"
+          v-model="formData.reason"
+          :maxlength="200"
+          :rows="3"
+          placeholder="请输入封禁原因"
+          show-count
+        />
+      </ElFormItem>
+    </ElForm>
+  </Modal>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/group/modules/detail.vue b/apps/web-ele/src/views/im/manager/group/modules/detail.vue
new file mode 100644
index 000000000..e3480400e
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/group/modules/detail.vue
@@ -0,0 +1,136 @@
+<script lang="ts" setup>
+import type { ImManagerGroupApi } from '#/api/im/manager/group';
+
+import { computed, ref } from 'vue';
+
+import { CommonStatusEnum, DICT_TYPE } from '@vben/constants';
+
+import { ElAvatar, ElCheckbox, ElDescriptions, ElDescriptionsItem, ElDrawer, ElTable, ElTableColumn, ElTag } from 'element-plus'
+
+import { getManagerGroupMemberList } from '#/api/im/manager/group';
+import { DictTag } from '#/components/dict-tag';
+import {
+  formatDateTimeText,
+  formatUserLabel,
+} from '#/views/im/manager/utils/format';
+
+const visible = ref(false);
+const detail = ref<ImManagerGroupApi.Group>({} as ImManagerGroupApi.Group);
+const loading = ref(false);
+const activeOnly = ref(true);
+const memberList = ref<ImManagerGroupApi.GroupMember[]>([]);
+
+const filteredMembers = computed(() =>
+  activeOnly.value
+    ? memberList.value.filter((item) => item.status === CommonStatusEnum.ENABLE)
+    : memberList.value,
+);
+
+/** 打开详情 */
+async function open(row: ImManagerGroupApi.Group) {
+  detail.value = row;
+  visible.value = true;
+  activeOnly.value = true;
+  loading.value = true;
+  try {
+    memberList.value = await getManagerGroupMemberList(row.id);
+  } finally {
+    loading.value = false;
+  }
+}
+
+defineExpose({ open });
+</script>
+
+<template>
+  <ElDrawer v-model="visible" destroy-on-close title="群详情" width="900">
+    <ElDescriptions bordered :column="2">
+      <ElDescriptionsItem label="群编号">{{ detail.id }}</ElDescriptionsItem>
+      <ElDescriptionsItem label="群名称">{{ detail.name }}</ElDescriptionsItem>
+      <ElDescriptionsItem label="头像">
+        <ElAvatar :src="detail.avatar" :size="36">
+          {{ detail.name?.charAt(0) || '?' }}
+        </ElAvatar>
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="群主">
+        {{ formatUserLabel(detail.ownerNickname, detail.ownerUserId) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="成员数">{{ detail.memberCount || 0 }}</ElDescriptionsItem>
+      <ElDescriptionsItem label="群状态">
+        <DictTag :type="DICT_TYPE.IM_GROUP_STATUS" :value="detail.status" />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="封禁状态">
+        <DictTag :type="DICT_TYPE.INFRA_BOOLEAN_STRING" :value="detail.banned" />
+        <span v-if="detail.banned" class="ml-2 text-gray-400">
+          {{ detail.bannedReason }}
+        </span>
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="全群禁言">
+        <ElTag v-if="detail.mutedAll" type="danger">已禁言</ElTag>
+        <ElTag v-else>未禁言</ElTag>
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="群公告" :span="2">
+        {{ detail.notice || '-' }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="创建时间" :span="2">
+        {{ formatDateTimeText(detail.createTime) }}
+      </ElDescriptionsItem>
+    </ElDescriptions>
+
+    <div class="mb-4 mt-5 flex items-center justify-between">
+      <span class="font-bold">群成员</span>
+      <ElCheckbox v-model="activeOnly">仅展示当前群内的成员</ElCheckbox>
+    </div>
+    <ElTable
+      v-loading="loading"
+      :data="filteredMembers"
+      bordered
+      row-key="userId"
+      size="small"
+    >
+      <ElTableColumn label="头像" width="80">
+        <template #default="{ row }">
+          <ElAvatar :src="row.avatar" :size="40">
+            {{ row.nickname?.charAt(0) || '?' }}
+          </ElAvatar>
+        </template>
+      </ElTableColumn>
+      <ElTableColumn label="用户编号" prop="userId" width="100" />
+      <ElTableColumn label="角色" width="100">
+        <template #default="{ row }">
+          <DictTag :type="DICT_TYPE.IM_GROUP_MEMBER_ROLE" :value="row.role" />
+        </template>
+      </ElTableColumn>
+      <ElTableColumn label="昵称" prop="nickname" />
+      <ElTableColumn label="组内显示名" prop="displayUserName" />
+      <ElTableColumn label="群备注" prop="groupRemark" />
+      <ElTableColumn label="免打扰" width="90">
+        <template #default="{ row }">
+          <DictTag :type="DICT_TYPE.INFRA_BOOLEAN_STRING" :value="row.silent" />
+        </template>
+      </ElTableColumn>
+      <ElTableColumn label="状态" width="100">
+        <template #default="{ row }">
+          <DictTag :type="DICT_TYPE.COMMON_STATUS" :value="row.status" />
+        </template>
+      </ElTableColumn>
+      <ElTableColumn label="入群时间" width="180">
+        <template #default="{ row }">{{ formatDateTimeText(row.joinTime) }}</template>
+      </ElTableColumn>
+      <ElTableColumn label="退群时间" width="180">
+        <template #default="{ row }">{{ formatDateTimeText(row.quitTime) }}</template>
+      </ElTableColumn>
+      <ElTableColumn label="禁言状态" width="180">
+        <template #default="{ row }">
+          <template v-if="row.muteEndTime && new Date(row.muteEndTime) > new Date()">
+            <ElTag type="danger">禁言中</ElTag>
+            <div class="mt-1 text-xs text-gray-400">
+              {{ formatDateTimeText(row.muteEndTime) }}
+            </div>
+          </template>
+          <span v-else>-</span>
+        </template>
+      </ElTableColumn>
+    </ElTable>
+  </ElDrawer>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/group/request/index.vue b/apps/web-ele/src/views/im/manager/group/request/index.vue
new file mode 100644
index 000000000..0bf1ef4d8
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/group/request/index.vue
@@ -0,0 +1,75 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerGroupRequestApi } from '#/api/im/manager/group/request';
+
+import { Page } from '@vben/common-ui';
+
+import { useVbenVxeGrid } from '#/adapter/vxe-table';
+import { getManagerGroupRequestPage } from '#/api/im/manager/group/request';
+import {
+  formatGroupLabel,
+  formatUserLabel,
+} from '#/views/im/manager/utils/format';
+
+import {
+  useGroupRequestGridColumns,
+  useGroupRequestGridFormSchema,
+} from '../data';
+
+defineOptions({ name: 'ImManagerGroupRequest' });
+
+const [Grid] = useVbenVxeGrid({
+  formOptions: {
+    schema: useGroupRequestGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useGroupRequestGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerGroupRequestPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerGroupRequestApi.GroupRequest>,
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <Grid table-title="加群申请列表">
+      <template #group="{ row }">
+        {{ formatGroupLabel(row.groupName, row.groupId) }}
+      </template>
+      <template #user="{ row }">
+        {{ formatUserLabel(row.userNickname, row.userId) }}
+      </template>
+      <template #inviter="{ row }">
+        <template v-if="row.inviterUserId">
+          {{ formatUserLabel(row.inviterNickname, row.inviterUserId) }}
+        </template>
+        <span v-else>主动申请</span>
+      </template>
+      <template #handler="{ row }">
+        <template v-if="row.handleUserId">
+          {{ formatUserLabel(row.handleNickname, row.handleUserId) }}
+        </template>
+        <span v-else>-</span>
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/message/content-preview.vue b/apps/web-ele/src/views/im/manager/message/content-preview.vue
new file mode 100644
index 000000000..9bb960113
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/message/content-preview.vue
@@ -0,0 +1,254 @@
+<script lang="ts" setup>
+import { computed } from 'vue';
+
+import { getDictObj } from '@vben/hooks';
+import { IconifyIcon } from '@vben/icons';
+import { formatFileSize, openSafeUrl } from '@vben/utils';
+
+import { ElImage } from 'element-plus'
+
+import { CardLineLabel } from '#/views/im/home/components/card';
+import { MESSAGE_MERGE_PREVIEW_LINES } from '#/views/im/utils/config';
+import {
+  ImContentType,
+  ImRtcCallEndReason,
+  ImRtcCallMediaType,
+  isFriendChatTip,
+  isGroupNotification,
+  isRtcCallTip,
+} from '#/views/im/utils/constants';
+import {
+  buildFacePreviewText,
+  summarizeMessageContent,
+} from '#/views/im/utils/conversation';
+import {
+  getFileIconInfo,
+  parseMessage,
+  parseRtcCallPayload,
+  resolveFriendNotificationText,
+  resolveGroupNotificationText,
+} from '#/views/im/utils/message';
+import { formatSeconds } from '#/views/im/utils/time';
+
+defineOptions({ name: 'ImManagerMessageContentPreview' });
+
+const props = defineProps<{
+  content?: string;
+  senderNickname?: string;
+  type?: number;
+}>();
+
+const payload = computed<null | Record<string, any>>(() =>
+  parseMessage<Record<string, any>>(props.content ?? ''),
+);
+
+const textContent = computed(() => payload.value?.content || '');
+
+const fileIconInfo = computed(() => getFileIconInfo(payload.value?.name));
+
+const cardPayload = computed(() => {
+  if (props.type !== ImContentType.CARD || !payload.value) {
+    return undefined;
+  }
+  return {
+    ...payload.value,
+    name: payload.value.name || payload.value.nickname || payload.value.userId || '',
+  };
+});
+
+const mergePreviewLines = computed(() => {
+  const messages = payload.value?.messages;
+  if (!Array.isArray(messages)) {
+    return [];
+  }
+  return messages
+    .slice(0, MESSAGE_MERGE_PREVIEW_LINES)
+    .map((item) => `${item.senderNickname}：${summarizeMessageContent(item)}`);
+});
+
+const fallbackText = computed(() => {
+  const raw = props.content || '';
+  if (!raw) {
+    return '';
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed === 'object' && parsed.content) {
+      return String(parsed.content);
+    }
+  } catch {}
+  return raw;
+});
+
+const friendTipText = computed(() =>
+  resolveFriendNotificationText({ type: props.type }),
+);
+
+const groupTipText = computed(() =>
+  resolveGroupNotificationText(
+    { type: props.type, content: props.content },
+    (id) => `用户(${id})`,
+    props.senderNickname,
+  ),
+);
+
+const rtcCallTipText = computed(() => {
+  const rtcPayload = parseRtcCallPayload(props.content);
+  if (!rtcPayload) {
+    return '';
+  }
+  const mediaLabel =
+    rtcPayload.mediaType === ImRtcCallMediaType.VIDEO ? '视频' : '语音';
+  if (props.type === ImContentType.RTC_CALL_START) {
+    const inviter =
+      rtcPayload.inviterNickname?.trim() ||
+      `用户(${rtcPayload.inviterUserId ?? ''})`;
+    return `${inviter} 发起了${mediaLabel}通话`;
+  }
+  const segments = [`${mediaLabel}通话已结束`];
+  if (
+    rtcPayload.endReason &&
+    rtcPayload.endReason !== ImRtcCallEndReason.HANGUP
+  ) {
+    const reason = getDictObj(
+      'im_rtc_call_end_reason',
+      String(rtcPayload.endReason),
+    )?.label;
+    if (reason) {
+      segments.push(reason);
+    }
+  }
+  const duration = rtcPayload.durationSeconds ?? 0;
+  if (duration > 0) {
+    segments.push(`时长 ${formatSeconds(duration)}`);
+  }
+  return segments.join('，');
+});
+
+/** 打开视频 */
+function openVideo() {
+  openSafeUrl(payload.value?.url);
+}
+</script>
+
+<template>
+  <span v-if="type === ImContentType.TEXT" class="whitespace-pre-wrap break-all">
+    {{ textContent }}
+  </span>
+
+  <ElImage
+    v-else-if="type === ImContentType.IMAGE && payload"
+    :height="60"
+    :src="payload.thumbnailUrl || payload.url"
+    :width="60"
+  />
+
+  <span
+    v-else-if="type === ImContentType.FILE && payload"
+    class="inline-flex items-center gap-1.5"
+  >
+    <IconifyIcon
+      :color="fileIconInfo.color"
+      :icon="fileIconInfo.icon"
+      class="size-4"
+    />
+    <span class="max-w-52 truncate">{{ payload.name }}</span>
+    <span v-if="payload.size > 0" class="text-xs text-gray-400">
+      {{ formatFileSize(payload.size) }}
+    </span>
+  </span>
+
+  <span
+    v-else-if="type === ImContentType.VOICE && payload"
+    class="inline-flex items-center gap-1.5"
+  >
+    <IconifyIcon class="size-4" icon="ant-design:audio-outlined" />
+    <span>{{ formatSeconds(payload.duration || 0) }}</span>
+  </span>
+
+  <span
+    v-else-if="type === ImContentType.VIDEO && payload"
+    class="inline-flex items-center gap-1.5"
+  >
+    <button
+      v-if="payload.coverUrl"
+      class="relative size-[60px] overflow-hidden rounded border-0 p-0"
+      type="button"
+      @click="openVideo"
+    >
+      <img :src="payload.coverUrl" class="size-full object-cover" />
+      <IconifyIcon
+        class="absolute inset-0 m-auto size-6 text-white drop-shadow"
+        icon="ant-design:play-circle-filled"
+      />
+    </button>
+    <span v-else class="inline-flex items-center gap-1.5">
+      <IconifyIcon class="size-4" icon="ant-design:video-camera-filled" />
+      <span>[视频]</span>
+    </span>
+    <span v-if="payload.duration" class="text-xs text-gray-400">
+      {{ formatSeconds(payload.duration) }}
+    </span>
+    <span v-if="payload.size > 0" class="text-xs text-gray-400">
+      {{ formatFileSize(payload.size) }}
+    </span>
+  </span>
+
+  <CardLineLabel
+    v-else-if="type === ImContentType.CARD && cardPayload"
+    :card="cardPayload"
+    :icon-size="16"
+  />
+
+  <span
+    v-else-if="type === ImContentType.FACE && payload"
+    class="inline-flex items-center gap-1.5"
+  >
+    <img
+      v-if="payload.url"
+      :alt="payload.name || '表情'"
+      :src="payload.url"
+      class="size-[30px] rounded object-contain"
+      draggable="false"
+    />
+    <span>{{ buildFacePreviewText(payload) }}</span>
+  </span>
+
+  <span
+    v-else-if="type === ImContentType.MERGE && payload"
+    class="inline-flex flex-col gap-0.5 align-middle"
+  >
+    <span>[聊天记录] {{ payload.title }}</span>
+    <span
+      v-for="(line, index) in mergePreviewLines"
+      :key="index"
+      class="truncate text-xs text-gray-400"
+    >
+      {{ line }}
+    </span>
+  </span>
+
+  <span v-else-if="type === ImContentType.RECALL" class="text-xs text-gray-400">
+    [消息已撤回]
+  </span>
+  <span v-else-if="type === ImContentType.READ" class="text-xs text-gray-400">
+    [已读回执]
+  </span>
+  <span v-else-if="type === ImContentType.RECEIPT" class="text-xs text-gray-400">
+    [回执]
+  </span>
+  <span v-else-if="isGroupNotification(type ?? -1)" class="text-xs text-gray-400">
+    {{ groupTipText }}
+  </span>
+  <span v-else-if="isFriendChatTip(type ?? -1)" class="text-xs text-gray-400">
+    {{ friendTipText }}
+  </span>
+  <span
+    v-else-if="isRtcCallTip(type ?? -1)"
+    class="inline-flex items-center gap-1.5 text-xs text-gray-400"
+  >
+    <IconifyIcon class="size-4 rotate-[135deg]" icon="ant-design:phone-outlined" />
+    <span>{{ rtcCallTipText }}</span>
+  </span>
+  <span v-else class="whitespace-pre-wrap break-all">{{ fallbackText }}</span>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/message/data.ts b/apps/web-ele/src/views/im/manager/message/data.ts
new file mode 100644
index 000000000..e9a9fc1b0
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/message/data.ts
@@ -0,0 +1,254 @@
+import type { VbenFormSchema } from '#/adapter/form';
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+
+import { markRaw } from 'vue';
+
+import { DICT_TYPE } from '@vben/constants';
+import { getDictOptions } from '@vben/hooks';
+
+import { getRangePickerDefaultProps } from '#/utils';
+import { GroupSelect } from '#/views/im/manager/group/components';
+import { UserSelect } from '#/views/system/user/components';
+
+/** 私聊消息搜索表单 */
+export function usePrivateGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'senderId',
+      label: '发送人',
+      component: markRaw(UserSelect),
+      componentProps: {
+        placeholder: '请选择发送人',
+      },
+    },
+    {
+      fieldName: 'receiverId',
+      label: '接收人',
+      component: markRaw(UserSelect),
+      componentProps: {
+        placeholder: '请选择接收人',
+      },
+    },
+    {
+      fieldName: 'type',
+      label: '内容类型',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_CONTENT_TYPE, 'number'),
+        placeholder: '请选择内容类型',
+      },
+    },
+    {
+      fieldName: 'content',
+      label: '消息内容',
+      component: 'Input',
+      componentProps: {
+        clearable: true,
+        placeholder: '请输入消息内容',
+      },
+    },
+    {
+      fieldName: 'sendTime',
+      label: '发送时间',
+      component: 'RangePicker',
+      componentProps: {
+        ...getRangePickerDefaultProps(),
+        clearable: true,
+      },
+    },
+  ];
+}
+
+/** 私聊消息字段 */
+export function usePrivateGridColumns(showReadColumns: boolean): VxeTableGridOptions['columns'] {
+  return [
+    {
+      field: 'id',
+      title: '编号',
+      width: 100,
+    },
+    {
+      title: '发送人',
+      minWidth: 160,
+      slots: { default: 'sender' },
+    },
+    {
+      title: '接收人',
+      minWidth: 160,
+      slots: { default: 'receiver' },
+    },
+    {
+      field: 'type',
+      title: '类型',
+      width: 100,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_CONTENT_TYPE },
+      },
+    },
+    {
+      title: '内容预览',
+      minWidth: 260,
+      align: 'left',
+      slots: { default: 'content' },
+    },
+    ...(showReadColumns
+      ? [
+          {
+            field: 'status',
+            title: '状态',
+            width: 100,
+            cellRender: {
+              name: 'CellDict',
+              props: { type: DICT_TYPE.IM_MESSAGE_STATUS },
+            },
+          },
+          {
+            field: 'receiptStatus',
+            title: '回执',
+            width: 110,
+            cellRender: {
+              name: 'CellDict',
+              // 回执状态（私聊 / 群聊共用 im_message_receipt_status），与源端「回执」列对齐
+              props: { type: DICT_TYPE.IM_MESSAGE_RECEIPT_STATUS },
+            },
+          },
+        ]
+      : []),
+    {
+      field: 'sendTime',
+      title: '发送时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      title: '操作',
+      width: 100,
+      fixed: 'right',
+      slots: { default: 'actions' },
+    },
+  ];
+}
+
+/** 群聊消息搜索表单 */
+export function useGroupGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'groupId',
+      label: '群',
+      component: markRaw(GroupSelect),
+    },
+    {
+      fieldName: 'senderId',
+      label: '发送人',
+      component: markRaw(UserSelect),
+      componentProps: {
+        placeholder: '请选择发送人',
+      },
+    },
+    {
+      fieldName: 'type',
+      label: '内容类型',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_CONTENT_TYPE, 'number'),
+        placeholder: '请选择内容类型',
+      },
+    },
+    {
+      fieldName: 'content',
+      label: '消息内容',
+      component: 'Input',
+      componentProps: {
+        clearable: true,
+        placeholder: '请输入消息内容',
+      },
+    },
+    {
+      fieldName: 'sendTime',
+      label: '发送时间',
+      component: 'RangePicker',
+      componentProps: {
+        ...getRangePickerDefaultProps(),
+        clearable: true,
+      },
+    },
+  ];
+}
+
+/** 群聊消息字段 */
+export function useGroupGridColumns(showReadColumns: boolean): VxeTableGridOptions['columns'] {
+  return [
+    {
+      field: 'id',
+      title: '编号',
+      width: 100,
+    },
+    {
+      title: '群',
+      minWidth: 160,
+      slots: { default: 'group' },
+    },
+    {
+      title: '发送人',
+      minWidth: 160,
+      slots: { default: 'sender' },
+    },
+    {
+      field: 'type',
+      title: '类型',
+      width: 100,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_CONTENT_TYPE },
+      },
+    },
+    {
+      title: '@用户',
+      minWidth: 180,
+      slots: { default: 'atUsers' },
+    },
+    {
+      title: '内容预览',
+      minWidth: 260,
+      align: 'left',
+      slots: { default: 'content' },
+    },
+    ...(showReadColumns
+      ? [
+          {
+            field: 'status',
+            title: '状态',
+            width: 100,
+            cellRender: {
+              name: 'CellDict',
+              props: { type: DICT_TYPE.IM_MESSAGE_STATUS },
+            },
+          },
+          {
+            field: 'receiptStatus',
+            title: '回执',
+            width: 110,
+            cellRender: {
+              name: 'CellDict',
+              props: { type: DICT_TYPE.IM_MESSAGE_RECEIPT_STATUS },
+            },
+          },
+        ]
+      : []),
+    {
+      field: 'sendTime',
+      title: '发送时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      title: '操作',
+      width: 100,
+      fixed: 'right',
+      slots: { default: 'actions' },
+    },
+  ];
+}
diff --git a/apps/web-ele/src/views/im/manager/message/group/index.vue b/apps/web-ele/src/views/im/manager/message/group/index.vue
new file mode 100644
index 000000000..1d9555399
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/message/group/index.vue
@@ -0,0 +1,110 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerGroupMessageApi } from '#/api/im/manager/message/group';
+
+import { ref } from 'vue';
+import { useRoute } from 'vue-router';
+
+import { Page } from '@vben/common-ui';
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
+import { getManagerGroupMessagePage } from '#/api/im/manager/message/group';
+import {
+  formatGroupLabel,
+  formatUserLabel,
+} from '#/views/im/manager/utils/format';
+import { MESSAGE_GROUP_READ_ENABLED } from '#/views/im/utils/config';
+import {
+  IM_AT_ALL_NICKNAME,
+  IM_AT_ALL_USER_ID,
+} from '#/views/im/utils/constants';
+
+import { MessageContentPreview } from '..';
+import { useGroupGridColumns, useGroupGridFormSchema } from '../data';
+import Detail from './modules/detail.vue';
+
+defineOptions({ name: 'ImGroupMessage' });
+
+const route = useRoute();
+const detailRef = ref<InstanceType<typeof Detail>>();
+
+/** 打开详情 */
+function handleDetail(row: ImManagerGroupMessageApi.GroupMessage) {
+  detailRef.value?.open(row);
+}
+
+const [Grid] = useVbenVxeGrid({
+  formOptions: {
+    schema: useGroupGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useGroupGridColumns(MESSAGE_GROUP_READ_ENABLED),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerGroupMessagePage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            groupId: route.query.groupId ? Number(route.query.groupId) : undefined,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerGroupMessageApi.GroupMessage>,
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <Detail ref="detailRef" />
+    <Grid table-title="群聊消息列表">
+      <template #group="{ row }">
+        {{ formatGroupLabel(row.groupName, row.groupId) }}
+      </template>
+      <template #sender="{ row }">
+        {{ formatUserLabel(row.senderNickname, row.senderId) }}
+      </template>
+      <template #atUsers="{ row }">
+        <template v-if="row.atUserIds?.length">
+          <span v-for="(userId, index) in row.atUserIds" :key="userId">
+            <span v-if="index > 0">、</span>
+            <template v-if="userId === IM_AT_ALL_USER_ID">@{{ IM_AT_ALL_NICKNAME }}</template>
+            <template v-else>@{{ row.atUserNicknames?.[index] || userId }}</template>
+          </span>
+        </template>
+        <span v-else>-</span>
+      </template>
+      <template #content="{ row }">
+        <MessageContentPreview
+          :content="row.content"
+          :sender-nickname="row.senderNickname"
+          :type="row.type"
+        />
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: '详情',
+              link: true,
+              icon: ACTION_ICON.VIEW,
+              auth: ['im:manager:message:query'],
+              onClick: handleDetail.bind(null, row),
+            },
+          ]"
+        />
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/message/group/modules/detail.vue b/apps/web-ele/src/views/im/manager/message/group/modules/detail.vue
new file mode 100644
index 000000000..f9df132ba
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/message/group/modules/detail.vue
@@ -0,0 +1,92 @@
+<script lang="ts" setup>
+import type { ImManagerGroupMessageApi } from '#/api/im/manager/message/group';
+
+import { ref } from 'vue';
+
+import { DICT_TYPE } from '@vben/constants';
+
+import { ElDescriptions, ElDescriptionsItem, ElDialog } from 'element-plus'
+
+import { DictTag } from '#/components/dict-tag';
+import {
+  formatDateTimeText,
+  formatGroupLabel,
+  formatJsonText,
+  formatUserLabel,
+} from '#/views/im/manager/utils/format';
+import { MESSAGE_GROUP_READ_ENABLED } from '#/views/im/utils/config';
+import {
+  IM_AT_ALL_NICKNAME,
+  IM_AT_ALL_USER_ID,
+} from '#/views/im/utils/constants';
+
+import { MessageContentPreview } from '../..';
+
+const visible = ref(false);
+const detail = ref<ImManagerGroupMessageApi.GroupMessage>({} as ImManagerGroupMessageApi.GroupMessage);
+
+/** 打开详情 */
+function open(row: ImManagerGroupMessageApi.GroupMessage) {
+  detail.value = row;
+  visible.value = true;
+}
+
+defineExpose({ open });
+</script>
+
+<template>
+  <ElDialog v-model="visible" title="群聊消息详情" width="700px">
+    <ElDescriptions bordered :column="2">
+      <ElDescriptionsItem label="编号">{{ detail.id }}</ElDescriptionsItem>
+      <ElDescriptionsItem label="客户端编号">
+        {{ detail.clientMessageId || '-' }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="群">
+        {{ formatGroupLabel(detail.groupName, detail.groupId) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="发送人">
+        {{ formatUserLabel(detail.senderNickname, detail.senderId) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="类型">
+        <DictTag :type="DICT_TYPE.IM_CONTENT_TYPE" :value="detail.type" />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="状态">
+        <DictTag :type="DICT_TYPE.IM_MESSAGE_STATUS" :value="detail.status" />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem v-if="MESSAGE_GROUP_READ_ENABLED" label="回执" :span="2">
+        <DictTag
+          :type="DICT_TYPE.IM_MESSAGE_RECEIPT_STATUS"
+          :value="detail.receiptStatus"
+        />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="@用户" :span="2">
+        <template v-if="detail.atUserIds?.length">
+          <span v-for="(userId, index) in detail.atUserIds" :key="userId">
+            <span v-if="index > 0">、</span>
+            <template v-if="userId === IM_AT_ALL_USER_ID">
+              @{{ IM_AT_ALL_NICKNAME }}
+            </template>
+            <template v-else>
+              @{{ detail.atUserNicknames?.[index] || userId }}
+              <span class="text-gray-400">({{ userId }})</span>
+            </template>
+          </span>
+        </template>
+        <span v-else>-</span>
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="发送时间" :span="2">
+        {{ formatDateTimeText(detail.sendTime) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="消息内容" :span="2">
+        <MessageContentPreview
+          :content="detail.content"
+          :sender-nickname="detail.senderNickname"
+          :type="detail.type"
+        />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="原始 JSON" :span="2">
+        <pre class="m-0 whitespace-pre-wrap break-all rounded bg-gray-100 p-2 font-mono text-xs">{{ formatJsonText(detail.content) }}</pre>
+      </ElDescriptionsItem>
+    </ElDescriptions>
+  </ElDialog>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/message/index.ts b/apps/web-ele/src/views/im/manager/message/index.ts
new file mode 100644
index 000000000..63c961ac9
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/message/index.ts
@@ -0,0 +1 @@
+export { default as MessageContentPreview } from './content-preview.vue';
diff --git a/apps/web-ele/src/views/im/manager/message/private/index.vue b/apps/web-ele/src/views/im/manager/message/private/index.vue
new file mode 100644
index 000000000..0308451f0
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/message/private/index.vue
@@ -0,0 +1,101 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerPrivateMessageApi } from '#/api/im/manager/message/private';
+
+import { ref } from 'vue';
+import { useRoute } from 'vue-router';
+
+import { Page } from '@vben/common-ui';
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
+import { getManagerPrivateMessagePage } from '#/api/im/manager/message/private';
+import { formatUserLabel } from '#/views/im/manager/utils/format';
+import { MESSAGE_PRIVATE_READ_ENABLED } from '#/views/im/utils/config';
+
+import { MessageContentPreview } from '..';
+import {
+  usePrivateGridColumns,
+  usePrivateGridFormSchema,
+} from '../data';
+import Detail from './modules/detail.vue';
+
+defineOptions({ name: 'ImPrivateMessage' });
+
+const route = useRoute();
+const detailRef = ref<InstanceType<typeof Detail>>();
+
+/** 打开详情 */
+function handleDetail(row: ImManagerPrivateMessageApi.PrivateMessage) {
+  detailRef.value?.open(row);
+}
+
+const [Grid] = useVbenVxeGrid({
+  formOptions: {
+    schema: usePrivateGridFormSchema(),
+  },
+  gridOptions: {
+    columns: usePrivateGridColumns(MESSAGE_PRIVATE_READ_ENABLED),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerPrivateMessagePage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            senderId: route.query.senderId
+              ? Number(route.query.senderId)
+              : undefined,
+            receiverId: route.query.receiverId
+              ? Number(route.query.receiverId)
+              : undefined,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerPrivateMessageApi.PrivateMessage>,
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <Detail ref="detailRef" />
+    <Grid table-title="私聊消息列表">
+      <template #sender="{ row }">
+        {{ formatUserLabel(row.senderNickname, row.senderId) }}
+      </template>
+      <template #receiver="{ row }">
+        {{ formatUserLabel(row.receiverNickname, row.receiverId) }}
+      </template>
+      <template #content="{ row }">
+        <MessageContentPreview
+          :content="row.content"
+          :sender-nickname="row.senderNickname"
+          :type="row.type"
+        />
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: '详情',
+              link: true,
+              icon: ACTION_ICON.VIEW,
+              auth: ['im:manager:message:query'],
+              onClick: handleDetail.bind(null, row),
+            },
+          ]"
+        />
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/message/private/modules/detail.vue b/apps/web-ele/src/views/im/manager/message/private/modules/detail.vue
new file mode 100644
index 000000000..30a0adfb9
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/message/private/modules/detail.vue
@@ -0,0 +1,75 @@
+<script lang="ts" setup>
+import type { ImManagerPrivateMessageApi } from '#/api/im/manager/message/private';
+
+import { ref } from 'vue';
+
+import { DICT_TYPE } from '@vben/constants';
+
+import { ElDescriptions, ElDescriptionsItem, ElDialog } from 'element-plus'
+
+import { DictTag } from '#/components/dict-tag';
+import {
+  formatDateTimeText,
+  formatJsonText,
+  formatUserLabel,
+} from '#/views/im/manager/utils/format';
+import { MESSAGE_PRIVATE_READ_ENABLED } from '#/views/im/utils/config';
+
+import { MessageContentPreview } from '../..';
+
+const visible = ref(false);
+const detail = ref<ImManagerPrivateMessageApi.PrivateMessage>(
+  {} as ImManagerPrivateMessageApi.PrivateMessage,
+);
+
+/** 打开详情 */
+function open(row: ImManagerPrivateMessageApi.PrivateMessage) {
+  detail.value = row;
+  visible.value = true;
+}
+
+defineExpose({ open });
+</script>
+
+<template>
+  <ElDialog v-model="visible" title="私聊消息详情" width="700px">
+    <ElDescriptions bordered :column="2">
+      <ElDescriptionsItem label="编号">{{ detail.id }}</ElDescriptionsItem>
+      <ElDescriptionsItem label="客户端编号">
+        {{ detail.clientMessageId || '-' }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="发送人">
+        {{ formatUserLabel(detail.senderNickname, detail.senderId) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="接收人">
+        {{ formatUserLabel(detail.receiverNickname, detail.receiverId) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="类型">
+        <DictTag :type="DICT_TYPE.IM_CONTENT_TYPE" :value="detail.type" />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="状态">
+        <DictTag :type="DICT_TYPE.IM_MESSAGE_STATUS" :value="detail.status" />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem v-if="MESSAGE_PRIVATE_READ_ENABLED" label="回执">
+        <!-- 回执状态（私聊 / 群聊共用 im_message_receipt_status），与源端私聊详情「回执」对齐 -->
+        <DictTag
+          :type="DICT_TYPE.IM_MESSAGE_RECEIPT_STATUS"
+          :value="detail.receiptStatus"
+        />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="发送时间" :span="2">
+        {{ formatDateTimeText(detail.sendTime) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="消息内容" :span="2">
+        <MessageContentPreview
+          :content="detail.content"
+          :sender-nickname="detail.senderNickname"
+          :type="detail.type"
+        />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="原始 JSON" :span="2">
+        <pre class="m-0 whitespace-pre-wrap break-all rounded bg-gray-100 p-2 font-mono text-xs">{{ formatJsonText(detail.content) }}</pre>
+      </ElDescriptionsItem>
+    </ElDescriptions>
+  </ElDialog>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/rtc/data.ts b/apps/web-ele/src/views/im/manager/rtc/data.ts
new file mode 100644
index 000000000..a46fe59d0
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/rtc/data.ts
@@ -0,0 +1,144 @@
+import type { VbenFormSchema } from '#/adapter/form';
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+
+import { markRaw } from 'vue';
+
+import { DICT_TYPE } from '@vben/constants';
+import { getDictOptions } from '@vben/hooks';
+
+import { getRangePickerDefaultProps } from '#/utils';
+import { UserSelect } from '#/views/system/user/components';
+
+/** 通话记录搜索表单 */
+export function useRtcGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'inviterUserId',
+      label: '发起人',
+      component: markRaw(UserSelect),
+      componentProps: {
+        placeholder: '请选择发起人',
+      },
+    },
+    {
+      fieldName: 'conversationType',
+      label: '会话类型',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_RTC_CALL_CONVERSATION_TYPE, 'number'),
+        placeholder: '请选择会话类型',
+      },
+    },
+    {
+      fieldName: 'mediaType',
+      label: '媒体类型',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_RTC_CALL_MEDIA_TYPE, 'number'),
+        placeholder: '请选择媒体类型',
+      },
+    },
+    {
+      fieldName: 'status',
+      label: '通话状态',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_RTC_CALL_STATUS, 'number'),
+        placeholder: '请选择通话状态',
+      },
+    },
+    {
+      fieldName: 'endReason',
+      label: '结束原因',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.IM_RTC_CALL_END_REASON, 'number'),
+        placeholder: '请选择结束原因',
+      },
+    },
+    {
+      fieldName: 'startTime',
+      label: '发起时间',
+      component: 'RangePicker',
+      componentProps: {
+        ...getRangePickerDefaultProps(),
+        clearable: true,
+      },
+    },
+  ];
+}
+
+/** 通话记录字段 */
+export function useRtcGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    {
+      field: 'id',
+      title: '编号',
+      width: 100,
+    },
+    {
+      title: '发起人',
+      minWidth: 160,
+      slots: { default: 'inviter' },
+    },
+    {
+      field: 'conversationType',
+      title: '会话类型',
+      width: 110,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_RTC_CALL_CONVERSATION_TYPE },
+      },
+    },
+    {
+      title: '群',
+      minWidth: 160,
+      slots: { default: 'group' },
+    },
+    {
+      field: 'mediaType',
+      title: '媒体类型',
+      width: 110,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_RTC_CALL_MEDIA_TYPE },
+      },
+    },
+    {
+      field: 'status',
+      title: '通话状态',
+      width: 110,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.IM_RTC_CALL_STATUS },
+      },
+    },
+    {
+      field: 'endReason',
+      title: '结束原因',
+      width: 120,
+      slots: { default: 'endReason' },
+    },
+    {
+      title: '通话时长',
+      width: 120,
+      slots: { default: 'duration' },
+    },
+    {
+      field: 'startTime',
+      title: '发起时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      title: '操作',
+      width: 100,
+      fixed: 'right',
+      slots: { default: 'actions' },
+    },
+  ];
+}
diff --git a/apps/web-ele/src/views/im/manager/rtc/index.vue b/apps/web-ele/src/views/im/manager/rtc/index.vue
new file mode 100644
index 000000000..2597dfc7f
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/rtc/index.vue
@@ -0,0 +1,98 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerRtcApi } from '#/api/im/manager/rtc';
+
+import { ref } from 'vue';
+
+import { Page } from '@vben/common-ui';
+import { DICT_TYPE } from '@vben/constants';
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
+import { getManagerRtcCallPage } from '#/api/im/manager/rtc';
+import { DictTag } from '#/components/dict-tag';
+import {
+  formatGroupLabel,
+  formatUserLabel,
+} from '#/views/im/manager/utils/format';
+import { resolveCallDuration } from '#/views/im/utils/time';
+
+import { useRtcGridColumns, useRtcGridFormSchema } from './data';
+import Detail from './modules/detail.vue';
+
+defineOptions({ name: 'ImManagerRtcCall' });
+
+const detailRef = ref<InstanceType<typeof Detail>>();
+
+/** 打开详情 */
+function handleDetail(row: ImManagerRtcApi.RtcCall) {
+  detailRef.value?.open(row);
+}
+
+const [Grid] = useVbenVxeGrid({
+  formOptions: {
+    schema: useRtcGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useRtcGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerRtcCallPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerRtcApi.RtcCall>,
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <Detail ref="detailRef" />
+    <Grid table-title="通话记录列表">
+      <template #inviter="{ row }">
+        {{ formatUserLabel(row.inviterNickname, row.inviterUserId) }}
+      </template>
+      <template #group="{ row }">
+        {{ formatGroupLabel(row.groupName, row.groupId) }}
+      </template>
+      <template #endReason="{ row }">
+        <DictTag
+          v-if="row.endReason"
+          :type="DICT_TYPE.IM_RTC_CALL_END_REASON"
+          :value="row.endReason"
+        />
+        <span v-else>-</span>
+      </template>
+      <template #duration="{ row }">
+        {{ resolveCallDuration(row.acceptTime, row.endTime) }}
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: '详情',
+              link: true,
+              icon: ACTION_ICON.VIEW,
+              auth: ['im:manager:rtc:query'],
+              onClick: handleDetail.bind(null, row),
+            },
+          ]"
+        />
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/rtc/modules/detail.vue b/apps/web-ele/src/views/im/manager/rtc/modules/detail.vue
new file mode 100644
index 000000000..99bb62096
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/rtc/modules/detail.vue
@@ -0,0 +1,114 @@
+<script lang="ts" setup>
+import type { ImManagerRtcApi } from '#/api/im/manager/rtc';
+
+import { computed, ref } from 'vue';
+
+import { DICT_TYPE } from '@vben/constants';
+
+import { ElDescriptions, ElDescriptionsItem, ElDrawer, ElTable, ElTableColumn } from 'element-plus'
+
+import { getManagerRtcCallParticipantList } from '#/api/im/manager/rtc';
+import { DictTag } from '#/components/dict-tag';
+import {
+  formatDateTimeText,
+  formatGroupLabel,
+  formatUserLabel,
+} from '#/views/im/manager/utils/format';
+import { resolveCallDuration } from '#/views/im/utils/time';
+
+const visible = ref(false);
+const detail = ref<ImManagerRtcApi.RtcCall>({} as ImManagerRtcApi.RtcCall);
+const loading = ref(false);
+const participants = ref<ImManagerRtcApi.RtcParticipant[]>([]);
+
+const duration = computed(() =>
+  resolveCallDuration(detail.value.acceptTime, detail.value.endTime),
+);
+
+/** 打开详情 */
+async function open(row: ImManagerRtcApi.RtcCall) {
+  detail.value = row;
+  visible.value = true;
+  loading.value = true;
+  try {
+    participants.value = await getManagerRtcCallParticipantList(row.id);
+  } finally {
+    loading.value = false;
+  }
+}
+
+defineExpose({ open });
+</script>
+
+<template>
+  <ElDrawer v-model="visible" destroy-on-close title="通话记录详情" width="900">
+    <ElDescriptions bordered :column="2">
+      <ElDescriptionsItem label="编号">{{ detail.id }}</ElDescriptionsItem>
+      <ElDescriptionsItem label="业务通话编号">{{ detail.room }}</ElDescriptionsItem>
+      <ElDescriptionsItem label="发起人">
+        {{ formatUserLabel(detail.inviterNickname, detail.inviterUserId) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="会话类型">
+        <DictTag :type="DICT_TYPE.IM_RTC_CALL_CONVERSATION_TYPE" :value="detail.conversationType" />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="群">
+        {{ formatGroupLabel(detail.groupName, detail.groupId) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="媒体类型">
+        <DictTag :type="DICT_TYPE.IM_RTC_CALL_MEDIA_TYPE" :value="detail.mediaType" />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="通话状态">
+        <DictTag :type="DICT_TYPE.IM_RTC_CALL_STATUS" :value="detail.status" />
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="结束原因">
+        <DictTag
+          v-if="detail.endReason"
+          :type="DICT_TYPE.IM_RTC_CALL_END_REASON"
+          :value="detail.endReason"
+        />
+        <span v-else>-</span>
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="发起时间">
+        {{ formatDateTimeText(detail.startTime) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="接通时间">
+        {{ formatDateTimeText(detail.acceptTime) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="结束时间">
+        {{ formatDateTimeText(detail.endTime) }}
+      </ElDescriptionsItem>
+      <ElDescriptionsItem label="通话时长">{{ duration }}</ElDescriptionsItem>
+    </ElDescriptions>
+
+    <div class="mb-4 mt-5 font-bold">参与者列表</div>
+    <ElTable
+      v-loading="loading"
+      :data="participants"
+      bordered
+      row-key="id"
+      size="small"
+    >
+      <ElTableColumn label="用户编号" prop="userId" width="120" />
+      <ElTableColumn label="昵称" prop="userNickname" />
+      <ElTableColumn label="参与角色" width="120">
+        <template #default="{ row }">
+          <DictTag :type="DICT_TYPE.IM_RTC_PARTICIPANT_ROLE" :value="row.role" />
+        </template>
+      </ElTableColumn>
+      <ElTableColumn label="参与状态" width="120">
+        <template #default="{ row }">
+          <DictTag :type="DICT_TYPE.IM_RTC_PARTICIPANT_STATUS" :value="row.status" />
+        </template>
+      </ElTableColumn>
+      <ElTableColumn label="被邀请时间" width="180">
+        <template #default="{ row }">{{ formatDateTimeText(row.inviteTime) }}</template>
+      </ElTableColumn>
+      <ElTableColumn label="接听时间" width="180">
+        <template #default="{ row }">{{ formatDateTimeText(row.acceptTime) }}</template>
+      </ElTableColumn>
+      <ElTableColumn label="离开时间" width="180">
+        <template #default="{ row }">{{ formatDateTimeText(row.leaveTime) }}</template>
+      </ElTableColumn>
+    </ElTable>
+  </ElDrawer>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/sensitiveword/data.ts b/apps/web-ele/src/views/im/manager/sensitiveword/data.ts
new file mode 100644
index 000000000..54601bb70
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/sensitiveword/data.ts
@@ -0,0 +1,119 @@
+import type { VbenFormSchema } from '#/adapter/form';
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+
+import { CommonStatusEnum, DICT_TYPE } from '@vben/constants';
+import { getDictOptions } from '@vben/hooks';
+
+import { z } from '#/adapter/form';
+import { getRangePickerDefaultProps } from '#/utils';
+
+/** 新增/修改的表单 */
+export function useFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'id',
+      component: 'Input',
+      dependencies: {
+        triggerFields: [''],
+        show: () => false,
+      },
+    },
+    {
+      fieldName: 'word',
+      label: '敏感词',
+      component: 'Input',
+      componentProps: {
+        maxlength: 64,
+        placeholder: '请输入敏感词',
+      },
+      rules: 'required',
+    },
+    {
+      fieldName: 'status',
+      label: '状态',
+      component: 'RadioGroup',
+      componentProps: {
+        options: getDictOptions(DICT_TYPE.COMMON_STATUS, 'number'),
+        isButton: true,
+      },
+      rules: z.number().default(CommonStatusEnum.ENABLE),
+    },
+  ];
+}
+
+/** 列表的搜索表单 */
+export function useGridFormSchema(): VbenFormSchema[] {
+  return [
+    {
+      fieldName: 'word',
+      label: '敏感词',
+      component: 'Input',
+      componentProps: {
+        clearable: true,
+        placeholder: '请输入敏感词',
+      },
+    },
+    {
+      fieldName: 'status',
+      label: '状态',
+      component: 'Select',
+      componentProps: {
+        clearable: true,
+        options: getDictOptions(DICT_TYPE.COMMON_STATUS, 'number'),
+        placeholder: '请选择状态',
+      },
+    },
+    {
+      fieldName: 'createTime',
+      label: '创建时间',
+      component: 'RangePicker',
+      componentProps: {
+        ...getRangePickerDefaultProps(),
+        clearable: true,
+      },
+    },
+  ];
+}
+
+/** 列表的字段 */
+export function useGridColumns(): VxeTableGridOptions['columns'] {
+  return [
+    { type: 'checkbox', width: 40 },
+    {
+      field: 'id',
+      title: '编号',
+      width: 100,
+    },
+    {
+      field: 'word',
+      title: '敏感词',
+      minWidth: 180,
+    },
+    {
+      field: 'status',
+      title: '状态',
+      width: 100,
+      cellRender: {
+        name: 'CellDict',
+        props: { type: DICT_TYPE.COMMON_STATUS },
+      },
+    },
+    {
+      field: 'creatorName',
+      title: '创建人',
+      minWidth: 120,
+    },
+    {
+      field: 'createTime',
+      title: '创建时间',
+      minWidth: 180,
+      formatter: 'formatDateTime',
+    },
+    {
+      title: '操作',
+      width: 160,
+      fixed: 'right',
+      slots: { default: 'actions' },
+    },
+  ];
+}
diff --git a/apps/web-ele/src/views/im/manager/sensitiveword/index.vue b/apps/web-ele/src/views/im/manager/sensitiveword/index.vue
new file mode 100644
index 000000000..b77fd62ae
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/sensitiveword/index.vue
@@ -0,0 +1,172 @@
+<script lang="ts" setup>
+import type { VxeTableGridOptions } from '#/adapter/vxe-table';
+import type { ImManagerSensitiveWordApi } from '#/api/im/manager/sensitiveword';
+
+import { ref } from 'vue';
+
+import { confirm, Page, useVbenModal } from '@vben/common-ui';
+import { isEmpty } from '@vben/utils';
+
+import { ElLoading, ElMessage } from 'element-plus'
+
+import { ACTION_ICON, TableAction, useVbenVxeGrid } from '#/adapter/vxe-table';
+import {
+  deleteManagerSensitiveWord,
+  deleteManagerSensitiveWordList,
+  getManagerSensitiveWordPage,
+} from '#/api/im/manager/sensitiveword';
+import { $t } from '#/locales';
+
+import { useGridColumns, useGridFormSchema } from './data';
+import Form from './modules/form.vue';
+
+defineOptions({ name: 'ImManagerSensitiveWord' });
+
+const [FormModal, formModalApi] = useVbenModal({
+  connectedComponent: Form,
+  destroyOnClose: true,
+});
+
+/** 刷新表格 */
+function handleRefresh() {
+  gridApi.query();
+}
+
+/** 创建敏感词 */
+function handleCreate() {
+  formModalApi.setData(null).open();
+}
+
+/** 编辑敏感词 */
+function handleEdit(row: ImManagerSensitiveWordApi.SensitiveWord) {
+  formModalApi.setData(row).open();
+}
+
+/** 删除敏感词 */
+async function handleDelete(row: ImManagerSensitiveWordApi.SensitiveWord) {
+  const loadingInstance = ElLoading.service({
+    text: $t('ui.actionMessage.deleting', [row.word]),
+  });
+  try {
+    await deleteManagerSensitiveWord(row.id);
+    ElMessage.success($t('ui.actionMessage.deleteSuccess', [row.word]));
+    handleRefresh();
+  } finally {
+    loadingInstance.close();
+  }
+}
+
+const checkedIds = ref<number[]>([]);
+
+/** 表格选中变化 */
+function handleRowCheckboxChange({
+  records,
+}: {
+  records: ImManagerSensitiveWordApi.SensitiveWord[];
+}) {
+  checkedIds.value = records.map((item) => item.id);
+}
+
+/** 批量删除敏感词 */
+async function handleDeleteBatch() {
+  await confirm($t('ui.actionMessage.deleteBatchConfirm'));
+  const loadingInstance = ElLoading.service({
+    text: $t('ui.actionMessage.deletingBatch'),
+  });
+  try {
+    await deleteManagerSensitiveWordList(checkedIds.value);
+    checkedIds.value = [];
+    ElMessage.success($t('ui.actionMessage.deleteSuccess'));
+    handleRefresh();
+  } finally {
+    loadingInstance.close();
+  }
+}
+
+const [Grid, gridApi] = useVbenVxeGrid({
+  formOptions: {
+    schema: useGridFormSchema(),
+  },
+  gridOptions: {
+    columns: useGridColumns(),
+    height: 'auto',
+    keepSource: true,
+    proxyConfig: {
+      ajax: {
+        query: async ({ page }, formValues) => {
+          return await getManagerSensitiveWordPage({
+            pageNo: page.currentPage,
+            pageSize: page.pageSize,
+            ...formValues,
+          });
+        },
+      },
+    },
+    rowConfig: {
+      keyField: 'id',
+      isHover: true,
+    },
+    toolbarConfig: {
+      refresh: true,
+      search: true,
+    },
+  } as VxeTableGridOptions<ImManagerSensitiveWordApi.SensitiveWord>,
+  gridEvents: {
+    checkboxAll: handleRowCheckboxChange,
+    checkboxChange: handleRowCheckboxChange,
+  },
+});
+</script>
+
+<template>
+  <Page auto-content-height>
+    <FormModal @success="handleRefresh" />
+    <Grid table-title="敏感词列表">
+      <template #toolbar-tools>
+        <TableAction
+          :actions="[
+            {
+              label: $t('ui.actionTitle.create', ['敏感词']),
+              type: 'primary',
+              icon: ACTION_ICON.ADD,
+              auth: ['im:manager:sensitive-word:create'],
+              onClick: handleCreate,
+            },
+            {
+              label: $t('ui.actionTitle.deleteBatch'),
+              type: 'danger',
+              icon: ACTION_ICON.DELETE,
+              auth: ['im:manager:sensitive-word:delete'],
+              disabled: isEmpty(checkedIds),
+              onClick: handleDeleteBatch,
+            },
+          ]"
+        />
+      </template>
+      <template #actions="{ row }">
+        <TableAction
+          :actions="[
+            {
+              label: $t('common.edit'),
+              link: true,
+              icon: ACTION_ICON.EDIT,
+              auth: ['im:manager:sensitive-word:update'],
+              onClick: handleEdit.bind(null, row),
+            },
+            {
+              label: $t('common.delete'),
+              link: true,
+              type: 'danger',
+              icon: ACTION_ICON.DELETE,
+              auth: ['im:manager:sensitive-word:delete'],
+              popConfirm: {
+                title: $t('ui.actionMessage.deleteConfirm', [row.word]),
+                confirm: handleDelete.bind(null, row),
+              },
+            },
+          ]"
+        />
+      </template>
+    </Grid>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/sensitiveword/modules/form.vue b/apps/web-ele/src/views/im/manager/sensitiveword/modules/form.vue
new file mode 100644
index 000000000..0e476f513
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/sensitiveword/modules/form.vue
@@ -0,0 +1,83 @@
+<script lang="ts" setup>
+import type { ImManagerSensitiveWordApi } from '#/api/im/manager/sensitiveword';
+
+import { computed, ref } from 'vue';
+
+import { useVbenModal } from '@vben/common-ui';
+
+import { ElMessage } from 'element-plus'
+
+import { useVbenForm } from '#/adapter/form';
+import {
+  createManagerSensitiveWord,
+  getManagerSensitiveWord,
+  updateManagerSensitiveWord,
+} from '#/api/im/manager/sensitiveword';
+import { $t } from '#/locales';
+
+import { useFormSchema } from '../data';
+
+const emit = defineEmits(['success']);
+const formData = ref<ImManagerSensitiveWordApi.SensitiveWord>();
+const getTitle = computed(() => {
+  return formData.value?.id ? '修改敏感词' : '新增敏感词';
+});
+
+const [Form, formApi] = useVbenForm({
+  commonConfig: {
+    componentProps: {
+      class: 'w-full',
+    },
+    formItemClass: 'col-span-2',
+    labelWidth: 80,
+  },
+  layout: 'horizontal',
+  schema: useFormSchema(),
+  showDefaultActions: false,
+});
+
+const [Modal, modalApi] = useVbenModal({
+  async onConfirm() {
+    const { valid } = await formApi.validate();
+    if (!valid) {
+      return;
+    }
+    modalApi.lock();
+    const data = (await formApi.getValues()) as ImManagerSensitiveWordApi.SensitiveWord;
+    try {
+      await (formData.value?.id
+        ? updateManagerSensitiveWord(data)
+        : createManagerSensitiveWord(data));
+      await modalApi.close();
+      emit('success');
+      ElMessage.success($t('ui.actionMessage.operationSuccess'));
+    } finally {
+      modalApi.unlock();
+    }
+  },
+  async onOpenChange(isOpen: boolean) {
+    if (!isOpen) {
+      formData.value = undefined;
+      await formApi.resetForm();
+      return;
+    }
+    const data = modalApi.getData<ImManagerSensitiveWordApi.SensitiveWord>();
+    if (!data || !data.id) {
+      return;
+    }
+    modalApi.lock();
+    try {
+      formData.value = await getManagerSensitiveWord(data.id);
+      await formApi.setValues(formData.value);
+    } finally {
+      modalApi.unlock();
+    }
+  },
+});
+</script>
+
+<template>
+  <Modal :title="getTitle" class="w-1/3">
+    <Form class="mx-4" />
+  </Modal>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/statistics/components/distribution-chart.vue b/apps/web-ele/src/views/im/manager/statistics/components/distribution-chart.vue
new file mode 100644
index 000000000..59665b381
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/statistics/components/distribution-chart.vue
@@ -0,0 +1,119 @@
+<script lang="ts" setup>
+import type { EchartsUIType } from '@vben/plugins/echarts';
+
+import { nextTick, onMounted, ref } from 'vue';
+
+import { DICT_TYPE } from '@vben/constants';
+import { getDictObj } from '@vben/hooks';
+import { EchartsUI, useEcharts } from '@vben/plugins/echarts';
+
+import { ElCard } from 'element-plus'
+
+import {
+  getGroupSizeDistribution,
+  getMessageTypeDistribution,
+  getTopSenders,
+} from '#/api/im/manager/statistics';
+
+const props = defineProps<{
+  type: 'groupSize' | 'messageType' | 'topSenders';
+}>();
+
+const titleMap = {
+  groupSize: '群规模分布',
+  messageType: '消息类型分布',
+  topSenders: '消息发送 TOP 10',
+};
+
+const loading = ref(false);
+const chartRef = ref<EchartsUIType>();
+const { renderEcharts } = useEcharts(chartRef);
+
+/** 加载图表数据 */
+async function loadData() {
+  loading.value = true;
+  try {
+    await nextTick();
+    if (props.type === 'groupSize') {
+      const data = await getGroupSizeDistribution();
+      await renderEcharts({
+        tooltip: { trigger: 'axis' },
+        grid: { left: 24, right: 24, bottom: 16, top: 28, containLabel: true },
+        xAxis: { type: 'category', data: data.map((item) => item.range) },
+        yAxis: { type: 'value', name: '群组数' },
+        series: [
+          {
+            type: 'bar',
+            data: data.map((item) => item.count),
+            itemStyle: { color: '#18a058', borderRadius: [4, 4, 0, 0] },
+            barMaxWidth: 48,
+          },
+        ],
+      });
+      return;
+    }
+    if (props.type === 'messageType') {
+      const data = await getMessageTypeDistribution();
+      const items = data.map((item) => ({
+        name:
+          getDictObj(DICT_TYPE.IM_CONTENT_TYPE, String(item.type))?.label ||
+          `未知(${item.type})`,
+        value: item.value,
+      }));
+      await renderEcharts({
+        tooltip: { trigger: 'item', formatter: '{b}: {c} ({d}%)' },
+        legend: { orient: 'vertical', right: 8, top: 'middle' },
+        series: [
+          {
+            type: 'pie',
+            radius: ['42%', '70%'],
+            data: items,
+            itemStyle: { borderColor: '#fff', borderRadius: 4, borderWidth: 2 },
+            label: { show: false },
+          },
+        ],
+      });
+      return;
+    }
+    const data = await getTopSenders();
+    const sorted = data.toSorted((a, b) => a.messageCount - b.messageCount);
+    await renderEcharts({
+      tooltip: { trigger: 'axis', axisPointer: { type: 'shadow' } },
+      grid: { left: 24, right: 24, bottom: 16, top: 20, containLabel: true },
+      xAxis: { type: 'value', name: '消息数' },
+      yAxis: {
+        type: 'category',
+        data: sorted.map((item) => `${item.nickname || item.userId}(${item.userId})`),
+        axisLabel: { overflow: 'truncate', width: 110 },
+      },
+      series: [
+        {
+          type: 'bar',
+          data: sorted.map((item) => item.messageCount),
+          itemStyle: { color: '#2f7df6', borderRadius: [0, 4, 4, 0] },
+          barMaxWidth: 18,
+        },
+      ],
+    });
+  } finally {
+    loading.value = false;
+  }
+}
+
+onMounted(loadData);
+</script>
+
+<template>
+  <ElCard :body-style="{ padding: '12px 16px 16px' }">
+    <template #header>{{ titleMap[type] }}</template>
+    <div class="relative min-h-[320px]">
+      <EchartsUI ref="chartRef" height="320px" />
+      <div
+        v-if="loading"
+        class="absolute inset-0 flex items-center justify-center bg-card/70 text-sm text-muted-foreground"
+      >
+        加载中
+      </div>
+    </div>
+  </ElCard>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/statistics/components/index.ts b/apps/web-ele/src/views/im/manager/statistics/components/index.ts
new file mode 100644
index 000000000..c7228a32c
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/statistics/components/index.ts
@@ -0,0 +1,3 @@
+export { default as DistributionChart } from './distribution-chart.vue';
+export { default as OverviewCards } from './overview-cards.vue';
+export { default as TrendChart } from './trend-chart.vue';
diff --git a/apps/web-ele/src/views/im/manager/statistics/components/overview-cards.vue b/apps/web-ele/src/views/im/manager/statistics/components/overview-cards.vue
new file mode 100644
index 000000000..f97a09cf3
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/statistics/components/overview-cards.vue
@@ -0,0 +1,105 @@
+<script lang="ts" setup>
+import type { ImManagerStatisticsApi } from '#/api/im/manager/statistics';
+
+import { computed } from 'vue';
+
+import { IconifyIcon } from '@vben/icons';
+
+import { ElCard } from 'element-plus'
+
+defineOptions({ name: 'ImManagerStatisticsOverviewCards' });
+
+const props = defineProps<{
+  overview: ImManagerStatisticsApi.Overview;
+}>();
+
+/** 计算环比 */
+function calcRatio(today: number, yesterday: number) {
+  if (!yesterday) {
+    return { label: '无昨日数据', className: 'text-gray-400' };
+  }
+  const diff = ((today - yesterday) / yesterday) * 100;
+  const sign = diff >= 0 ? '+' : '';
+  return {
+    label: `${sign}${diff.toFixed(1)}%`,
+    className: diff >= 0 ? 'text-green-500' : 'text-red-500',
+  };
+}
+
+const cards = computed(() => {
+  const overview = props.overview;
+  const totalMsgToday =
+    (overview.privateMessageToday || 0) + (overview.groupMessageToday || 0);
+  const totalMsgYesterday =
+    (overview.privateMessageYesterday || 0) +
+    (overview.groupMessageYesterday || 0);
+  const msgRatio = calcRatio(totalMsgToday, totalMsgYesterday);
+  return [
+    {
+      title: '总用户',
+      value: overview.totalUser || 0,
+      icon: 'lucide:user',
+      color: '#2f7df6',
+      metaLabel: '今日新增',
+      metaValue: `+${overview.newUserToday || 0}`,
+      metaClass: 'text-green-500',
+    },
+    {
+      title: '总群组',
+      value: overview.totalGroup || 0,
+      icon: 'lucide:messages-square',
+      color: '#18a058',
+      metaLabel: '今日新增',
+      metaValue: `+${overview.newGroupToday || 0}`,
+      metaClass: 'text-green-500',
+    },
+    {
+      title: '日活用户',
+      value: overview.activeUserDaily || 0,
+      icon: 'lucide:timer',
+      color: '#f59e0b',
+      metaLabel: '周/月活',
+      metaValue: `${overview.activeUserWeekly || 0} / ${overview.activeUserMonthly || 0}`,
+      metaClass: 'text-gray-500',
+    },
+    {
+      title: '今日消息',
+      value: totalMsgToday,
+      suffix: `（P ${overview.privateMessageToday}/G ${overview.groupMessageToday}）`,
+      icon: 'lucide:message-circle',
+      color: '#64748b',
+      metaLabel: '环比昨日',
+      metaValue: msgRatio.label,
+      metaClass: msgRatio.className,
+    },
+  ];
+});
+</script>
+
+<template>
+  <div class="grid grid-cols-4 gap-4 max-xl:grid-cols-2 max-md:grid-cols-1">
+    <ElCard v-for="card in cards" :key="card.title" :body-style="{ padding: '16px' }">
+      <div class="flex items-center">
+        <div
+          class="mr-3 flex size-12 shrink-0 items-center justify-center rounded"
+          :style="{ backgroundColor: card.color }"
+        >
+          <IconifyIcon :icon="card.icon" class="size-6 text-white" />
+        </div>
+        <div class="min-w-0 flex-1">
+          <div class="mb-1 text-sm text-muted-foreground">{{ card.title }}</div>
+          <div class="truncate text-2xl font-semibold leading-none">
+            {{ card.value }}
+            <span v-if="card.suffix" class="ml-1 text-xs font-normal text-gray-400">
+              {{ card.suffix }}
+            </span>
+          </div>
+          <div class="mt-2 text-xs text-gray-400">
+            {{ card.metaLabel }}：
+            <span :class="card.metaClass">{{ card.metaValue }}</span>
+          </div>
+        </div>
+      </div>
+    </ElCard>
+  </div>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/statistics/components/trend-chart.vue b/apps/web-ele/src/views/im/manager/statistics/components/trend-chart.vue
new file mode 100644
index 000000000..46f2b89a4
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/statistics/components/trend-chart.vue
@@ -0,0 +1,144 @@
+<script lang="ts" setup>
+import type { EChartsOption, EchartsUIType } from '@vben/plugins/echarts';
+
+import { nextTick, onMounted, ref } from 'vue';
+
+import { EchartsUI, useEcharts } from '@vben/plugins/echarts';
+
+import { ElCard, ElOption, ElSelect } from 'element-plus'
+
+import {
+  getMessageTrend,
+  getUserTrend,
+} from '#/api/im/manager/statistics';
+
+const props = defineProps<{
+  type: 'message' | 'user';
+}>();
+
+const title =
+  props.type === 'message'
+    ? '消息趋势（私聊 + 群聊）'
+    : '用户趋势（新增注册 + 日活）';
+
+const days = ref(7);
+const loading = ref(false);
+const chartRef = ref<EchartsUIType>();
+const { renderEcharts } = useEcharts(chartRef);
+
+/** 获取图表配置 */
+function buildOptions(
+  dates: string[],
+  series: Record<string, number[]>,
+): EChartsOption {
+  if (props.type === 'message') {
+    return {
+      tooltip: { trigger: 'axis' },
+      legend: { data: ['私聊消息', '群聊消息'], top: 0 },
+      grid: { left: 24, right: 24, bottom: 16, top: 42, containLabel: true },
+      xAxis: {
+        type: 'category',
+        data: dates,
+        axisLabel: { formatter: (value: string) => value.slice(5, 10) },
+      },
+      yAxis: { type: 'value', name: '消息量' },
+      series: [
+        {
+          name: '私聊消息',
+          type: 'line',
+          smooth: true,
+          data: series.private || [],
+          itemStyle: { color: '#2f7df6' },
+          areaStyle: { color: 'rgba(47,125,246,0.12)' },
+        },
+        {
+          name: '群聊消息',
+          type: 'line',
+          smooth: true,
+          data: series.group || [],
+          itemStyle: { color: '#18a058' },
+          areaStyle: { color: 'rgba(24,160,88,0.12)' },
+        },
+      ],
+    };
+  }
+  return {
+    tooltip: { trigger: 'axis' },
+    legend: { data: ['新增注册', '日活'], top: 0 },
+    grid: { left: 24, right: 32, bottom: 16, top: 42, containLabel: true },
+    xAxis: {
+      type: 'category',
+      data: dates,
+      axisLabel: { formatter: (value: string) => value.slice(5, 10) },
+    },
+    yAxis: [
+      { type: 'value', name: '新增注册', position: 'left' },
+      { type: 'value', name: '日活', position: 'right' },
+    ],
+    series: [
+      {
+        name: '新增注册',
+        type: 'bar',
+        yAxisIndex: 0,
+        data: series.register || [],
+        itemStyle: { color: '#f59e0b' },
+        barMaxWidth: 24,
+      },
+      {
+        name: '日活',
+        type: 'line',
+        yAxisIndex: 1,
+        smooth: true,
+        data: series.active || [],
+        itemStyle: { color: '#ef4444' },
+      },
+    ],
+  };
+}
+
+/** 加载图表数据 */
+async function loadData() {
+  loading.value = true;
+  try {
+    const data =
+      props.type === 'message'
+        ? await getMessageTrend(days.value)
+        : await getUserTrend(days.value);
+    await nextTick();
+    await renderEcharts(buildOptions(data.dates, data.series));
+  } finally {
+    loading.value = false;
+  }
+}
+
+onMounted(loadData);
+</script>
+
+<template>
+  <ElCard :body-style="{ padding: '12px 16px 16px' }">
+    <template #header>
+      <div class="flex items-center justify-between">
+        <span>{{ title }}</span>
+        <ElSelect
+          v-model="days"
+          class="w-28"
+          size="small"
+          @change="loadData"
+        >
+          <ElOption label="近 7 天" :value="7" />
+          <ElOption label="近 15 天" :value="15" />
+          <ElOption label="近 30 天" :value="30" />
+        </ElSelect>
+      </div>
+    </template>
+    <div class="relative min-h-[320px]">
+      <EchartsUI ref="chartRef" height="320px" />
+      <div
+        v-if="loading"
+        class="absolute inset-0 flex items-center justify-center bg-card/70 text-sm text-muted-foreground"
+      >
+        加载中
+      </div>
+    </div>
+  </ElCard>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/statistics/index.vue b/apps/web-ele/src/views/im/manager/statistics/index.vue
new file mode 100644
index 000000000..0d73d52ae
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/statistics/index.vue
@@ -0,0 +1,45 @@
+<script lang="ts" setup>
+import type { ImManagerStatisticsApi } from '#/api/im/manager/statistics';
+
+import { onMounted, ref } from 'vue';
+
+import { Page } from '@vben/common-ui';
+
+import { getStatisticsOverview } from '#/api/im/manager/statistics';
+
+import {
+  DistributionChart,
+  OverviewCards,
+  TrendChart,
+} from './components';
+
+defineOptions({ name: 'ImManagerStatistics' });
+
+const overview = ref<ImManagerStatisticsApi.Overview>();
+
+/** 加载概览数据 */
+async function loadOverview() {
+  overview.value = await getStatisticsOverview();
+}
+
+onMounted(loadOverview);
+</script>
+
+<template>
+  <Page auto-content-height>
+    <div class="space-y-4">
+      <OverviewCards v-if="overview" :overview="overview" />
+
+      <div class="grid grid-cols-2 gap-4 max-xl:grid-cols-1">
+        <TrendChart type="message" />
+        <TrendChart type="user" />
+      </div>
+
+      <div class="grid grid-cols-3 gap-4 max-2xl:grid-cols-2 max-xl:grid-cols-1">
+        <DistributionChart type="messageType" />
+        <DistributionChart type="groupSize" />
+        <DistributionChart type="topSenders" />
+      </div>
+    </div>
+  </Page>
+</template>
diff --git a/apps/web-ele/src/views/im/manager/utils/format.ts b/apps/web-ele/src/views/im/manager/utils/format.ts
new file mode 100644
index 000000000..e7f53f451
--- /dev/null
+++ b/apps/web-ele/src/views/im/manager/utils/format.ts
@@ -0,0 +1,55 @@
+import { formatDateTime } from '@vben/utils';
+
+/** 展示用户名称 */
+export function formatUserLabel(
+  nickname: string | undefined,
+  userId: number | undefined,
+) {
+  if (!userId) {
+    return '-';
+  }
+  return `${nickname || '-'} (${userId})`;
+}
+
+/** 展示群名称 */
+export function formatGroupLabel(
+  name: string | undefined,
+  groupId: number | undefined,
+) {
+  if (!groupId) {
+    return '-';
+  }
+  return `${name || '-'} (${groupId})`;
+}
+
+/** 展示日期时间 */
+export function formatDateTimeText(value?: Date | number | string) {
+  return value ? (formatDateTime(value) as string) : '-';
+}
+
+/** 格式化 JSON */
+export function formatJsonText(content?: string) {
+  if (!content) {
+    return '';
+  }
+  try {
+    return JSON.stringify(JSON.parse(content), null, 2);
+  } catch {
+    return content;
+  }
+}
+
+/** 探测图片尺寸 */
+export function probeImageSize(url: string) {
+  return new Promise<{ height: number; width: number }>((resolve, reject) => {
+    const img = new Image();
+    img.addEventListener('load', () => {
+      resolve({
+        width: img.naturalWidth || img.width,
+        height: img.naturalHeight || img.height,
+      });
+    });
+    img.addEventListener('error', reject);
+    img.src = url;
+  });
+}
diff --git a/apps/web-ele/src/views/im/utils/auth.ts b/apps/web-ele/src/views/im/utils/auth.ts
new file mode 100644
index 000000000..e56761cee
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/auth.ts
@@ -0,0 +1,14 @@
+import { useAccessStore, useUserStore } from '@vben/stores'
+
+// TODO DONE @AI：已使用 Vben 的 useUserStore / useAccessStore 获取登录信息；
+
+/** 获取当前用户编号 */
+export function getCurrentUserId(): number {
+  const userInfo = useUserStore().userInfo
+  return Number(userInfo?.id ?? userInfo?.userId ?? 0)
+}
+
+/** 获取刷新令牌 */
+export function getRefreshToken(): null | string {
+  return useAccessStore().refreshToken
+}
diff --git a/apps/web-ele/src/views/im/utils/channel.ts b/apps/web-ele/src/views/im/utils/channel.ts
new file mode 100644
index 000000000..5276fb257
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/channel.ts
@@ -0,0 +1,18 @@
+import { useChannelStore } from '../home/store/channelStore'
+import { ImConversationType } from './constants'
+
+/**
+ * 构建频道会话描述（type / targetId / name / avatar）
+ *
+ * 优先用 channelStore 拉到的真实名称 / 头像；本地缓存还没拉到时退化为「频道 N」占位文案。
+ * 抽到 utils/channel.ts 后，useMessagePuller / websocketStore 共用同一份占位逻辑，避免多处复制；类似 utils/user.ts 取昵称的工具集。
+ */
+export const buildChannelConversationStub = (channelId: number) => {
+  const channel = useChannelStore().getChannel(channelId)
+  return {
+    type: ImConversationType.CHANNEL,
+    targetId: channelId,
+    name: channel?.name || `频道 ${channelId}`,
+    avatar: channel?.avatar || ''
+  }
+}
diff --git a/apps/web-ele/src/views/im/utils/config.ts b/apps/web-ele/src/views/im/utils/config.ts
new file mode 100644
index 000000000..6d153f006
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/config.ts
@@ -0,0 +1,133 @@
+/**
+ * IM 前端运行参数 / UI 阈值
+ *
+ * 与 constants.ts 的分工：
+ * - constants.ts：协议枚举（与后端 enum 一一对应）+ 协议契约值（如 IM_AT_ALL_USER_ID）
+ * - config.ts：可调节的策略数值，包括镜像后端 ImProperties 的默认值与纯前端 UI 阈值
+ *
+ * 标注「后端镜像」的常量与 yudao.im.* 配置默认值一致；调整后端配置时需同步修改这里
+ */
+
+// ==================== 后端镜像（与 ImProperties 默认值对齐） ====================
+
+/** 群最大成员人数（对齐 yudao.im.group.max-member） */
+export const GROUP_MAX_MEMBER = 500
+
+/** 单群管理员人数上限（对齐 yudao.im.group.admin-max-count） */
+export const GROUP_ADMIN_MAX_COUNT = 3
+
+/** 单群置顶消息条数上限（对齐 yudao.im.group.pin-max-count） */
+export const GROUP_PIN_MAX_COUNT = 5
+
+/**
+ * 是否启用私聊已读功能（对齐 yudao.im.message.private-read-enabled）
+ *
+ * 关闭后：进入私聊会话不再上报已读位置；气泡的「已读 / 未读」标签隐藏；
+ * 管理后台私聊消息列表的「状态」列与详情中的状态字段隐藏
+ */
+export const MESSAGE_PRIVATE_READ_ENABLED = true
+
+/**
+ * 是否启用群聊已读功能（含群消息回执，对齐 yudao.im.message.group-read-enabled）
+ *
+ * 关闭后：进入群会话不再上报已读位置；输入框的「发送回执消息」入口隐藏；
+ * 群消息气泡上的「N 人已读」popover 隐藏；管理后台群消息列表的「状态」「回执」列与详情中对应字段隐藏
+ */
+export const MESSAGE_GROUP_READ_ENABLED = true
+
+/** 消息撤回时间限制（分钟，对齐 yudao.im.message.recall-timeout-minutes） */
+export const MESSAGE_RECALL_TIMEOUT_MINUTES = 5
+
+/** 私聊离线消息最大拉取天数（对齐 yudao.im.message.private-pull-max-days） */
+export const MESSAGE_PRIVATE_PULL_MAX_DAYS = 30
+
+/** 群聊离线消息最大拉取天数（对齐 yudao.im.message.group-pull-max-days） */
+export const MESSAGE_GROUP_PULL_MAX_DAYS = 30
+
+// ==================== 前端独有：拉取 / 分页 ====================
+
+/** 每次拉取私聊消息的最大条数（后端上限 1000，前端取保守值 100） */
+export const MESSAGE_PRIVATE_PULL_SIZE = 100
+
+/** 每次拉取群聊消息的最大条数（后端上限 1000，前端取保守值 100） */
+export const MESSAGE_GROUP_PULL_SIZE = 100
+
+/** 「我相关」好友申请列表的单次拉取条数（游标分页 page size） */
+export const FRIEND_REQUEST_PAGE_SIZE = 100
+
+/** 「我相关」加群申请列表的单次拉取条数 */
+export const GROUP_REQUEST_PAGE_SIZE = 100
+
+// ==================== 上传安全策略 ====================
+// 数值与后端 Spring multipart 配置对齐（`spring.servlet.multipart.max-file-size = 16MB`）
+// 后端调大后这里同步调；不要单边放宽，否则用户上传完到后端 413
+
+/** 图片 / 视频 / 普通文件单文件上限（MB），对齐后端 max-file-size */
+export const MESSAGE_IMAGE_MAX_MB = 16
+export const MESSAGE_VIDEO_MAX_MB = 16
+export const MESSAGE_FILE_MAX_MB = 16
+/** 语音单文件上限（MB）：60s @ 64kbps 约 0.5MB，5MB 已远超录制可能产出的大小 */
+export const MESSAGE_VOICE_MAX_MB = 5
+
+/** 可执行 / 脚本类扩展名黑名单；接收端点击下载后本地双击就跑，html 本地打开还能执行脚本 */
+export const DANGEROUS_FILE_EXTENSIONS = [
+  'exe',
+  'bat',
+  'cmd',
+  'com',
+  'msi',
+  'scr',
+  'pif',
+  'vbs',
+  'vbe',
+  'wsf',
+  'ws',
+  'js',
+  'jse',
+  'jar',
+  'sh',
+  'app',
+  'ps1',
+  'reg',
+  'html',
+  'htm'
+]
+
+// ==================== 前端独有：UI 阈值 ====================
+
+/** 消息之间渲染「时间分隔条」的阈值：10 分钟 */
+export const MESSAGE_TIME_TIP_GAP_MS = 10 * 60 * 1000
+
+/**
+ * 撤回菜单可见的时间窗：自己发送的消息超过这个时长就不能再撤回，菜单回退为「删除」
+ *
+ * 比后端 MESSAGE_RECALL_TIMEOUT_MINUTES（5 分钟）严格，对齐微信 PC 的 2 分钟
+ */
+export const MESSAGE_RECALL_WINDOW_MS = 2 * 60 * 1000
+
+/** 合并转发消息（MERGE 类型）气泡内预览的最大行数（对齐微信「聊天记录」气泡） */
+export const MESSAGE_MERGE_PREVIEW_LINES = 3
+
+/** 最近转发会话 key 列表的最大保留数量（对齐微信 PC 横向头像区可见容量） */
+export const CONVERSATION_RECENT_FORWARD_MAX = 12
+
+// ==================== 前端独有：RTC 通话兜底 ====================
+
+/**
+ * 振铃超时兜底；通话存活期间 timer 调用 noAnswerCallCheck 接口的间隔；
+ * 实际超时阈值由后端 yudao.im.rtc.invite-timeout-minutes 决定，前端仅决定触发频率
+ */
+export const RTC_NO_ANSWER_CALL_CHECK_INTERVAL_MS = 60 * 1000
+
+// ==================== 前端独有：WebSocket 自动重连 ====================
+// 指数退避：base * 2^attempt，上限封顶；每次再叠加 0~jitter ms 随机偏移
+// 避免服务端重启时全量客户端在同一秒打过来形成「惊群」；不设次数上限，持续重连直到链路恢复
+
+/** 首次重连等待，单位 ms */
+export const WS_RECONNECT_BASE_MS = 1000
+
+/** 退避上限，单位 ms；连续失败 5 次后稳定在 30s 不再增长 */
+export const WS_RECONNECT_MAX_MS = 30 * 1000
+
+/** 退避叠加的随机抖动上限，单位 ms */
+export const WS_RECONNECT_JITTER_MS = 1000
diff --git a/apps/web-ele/src/views/im/utils/constants.ts b/apps/web-ele/src/views/im/utils/constants.ts
new file mode 100644
index 000000000..895571eba
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/constants.ts
@@ -0,0 +1,296 @@
+/** IM 内容类型枚举（对齐后端 ImContentTypeEnum） */
+export const ImContentType = {
+  // ========== 用户聊天消息（101-105 直接复用 OpenIM 段位编号） ==========
+  TEXT: 101, // 文本（对应 OpenIM Text=101）
+  IMAGE: 102, // 图片（对应 OpenIM Picture=102）
+  VOICE: 103, // 语音（对应 OpenIM Sound=103）
+  VIDEO: 104, // 视频（对应 OpenIM Video=104）
+  FILE: 105, // 文件（对应 OpenIM File=105）
+  MERGE: 107, // 合并转发（对应 OpenIM Merger=107；payload 内嵌完整快照）
+  CARD: 108, // 名片（对应 OpenIM Card=108）
+  FACE: 115, // 表情贴图（对应 OpenIM Face=115；Unicode emoji 仍走 TEXT）
+  // ========== 频道消息扩展段（125+；OpenIM 122 之后未占用，作为频道 / 公众号类消息扩展） ==========
+  MATERIAL: 125, // 频道素材（图文卡片：title + coverUrl + summary + url；详情拉 get-content）
+  // ========== 信号类（2101 / 2200 直接复用 OpenIM 段位编号；2201 自有扩展） ==========
+  RECALL: 2101, // 撤回（对应 OpenIM RevokeNotification=2101）
+  RECEIPT: 2200, // 回执（对应 OpenIM HasReadReceipt=2200）
+  READ: 2201, // 已读（多端同步，OpenIM 无对应；自有扩展）
+  // ========== 实时通话信令（1601-1605 段位与 OpenIM 对齐；1610+ 自有扩展） ==========
+  RTC_CALL: 1601, // 通话信令统一入口（对应 OpenIM SignalingNotification=1601）
+  RTC_PARTICIPANT_CONNECTED: 1602, // 通话参与者加入（对应 OpenIM RoomParticipantsConnectedNotification=1602）
+  RTC_PARTICIPANT_DISCONNECTED: 1603, // 通话参与者离开（对应 OpenIM RoomParticipantsDisconnectedNotification=1603）
+  // 1604-1609 OpenIM 已用 / 留作扩展，本系统暂不使用
+  RTC_CALL_START: 1610, // 通话开始（自有扩展，OpenIM 无；仅群聊；与 END 两段式配对）
+  RTC_CALL_END: 1611, // 通话结束（自有扩展，OpenIM 无；私聊 / 群聊）
+  // ========== 好友通知（1201-1210 直接复用 OpenIM 段位编号） ==========
+  FRIEND_REQUEST_APPROVED: 1201, // 好友申请被同意
+  FRIEND_REQUEST_REJECTED: 1202, // 好友申请被拒绝
+  FRIEND_REQUEST_RECEIVED: 1203, // 收到新的好友申请
+  FRIEND_ADD: 1204, // 新增好友（双方建立关系）
+  FRIEND_DELETE: 1205, // 好友被删除
+  // 1206 对应 OpenIM FriendRemarkSetNotification；本系统并入 FRIEND_UPDATE(1210) 统一推送，单一字段变更不再独立通道
+  FRIEND_BLOCK: 1207, // 加入黑名单
+  FRIEND_UNBLOCK: 1208, // 移出黑名单
+  FRIEND_INFO_UPDATED: 1209, // 好友资料变更（昵称 / 头像）
+  FRIEND_UPDATE: 1210, // 好友信息批量更新（silent / pinned）
+  // ========== 群事件（1501-1520 直接复用 OpenIM 段位编号；1530+ 自有扩展段） ==========
+  GROUP_CREATE: 1501, // 群创建
+  GROUP_INFO_UPDATE: 1502, // 群信息变更（NAME / NOTICE 之外字段兜底）
+  GROUP_REQUEST_RECEIVED: 1503, // 收到新的入群申请（私聊定向推送给群主 + 全部管理员）
+  GROUP_MEMBER_QUIT: 1504, // 成员退群
+  GROUP_REQUEST_APPROVED: 1505, // 入群申请被同意（私聊推给申请人 + 群主 + 全部管理员）
+  GROUP_REQUEST_REJECTED: 1506, // 入群申请被拒绝（同上）
+  GROUP_OWNER_TRANSFER: 1507, // 群主转让
+  GROUP_MEMBER_KICK: 1508, // 成员被移出
+  GROUP_MEMBER_INVITE: 1509, // 成员加入
+  GROUP_MEMBER_ENTER: 1510, // 自由进群（FREE 模式或申请通过后；全员广播）
+  GROUP_DISSOLVE: 1511, // 群解散
+  GROUP_MEMBER_MUTED: 1512, // 单成员禁言
+  GROUP_MEMBER_CANCEL_MUTED: 1513, // 单成员取消禁言
+  GROUP_MUTED: 1514, // 全群禁言
+  GROUP_CANCEL_MUTED: 1515, // 全群取消禁言
+  GROUP_MEMBER_NICKNAME_UPDATE: 1516, // 成员昵称变更（窄化到 displayUserName）
+  GROUP_ADMIN_ADD: 1517, // 添加管理员
+  GROUP_ADMIN_REMOVE: 1518, // 撤销管理员
+  GROUP_NOTICE_UPDATE: 1519, // 群公告变更
+  GROUP_NAME_UPDATE: 1520, // 群名变更
+  // ========== 自有扩展段（1530+，OpenIM 1500-1520 段位无对应物） ==========
+  GROUP_MEMBER_SETTING_UPDATE: 1530, // 群成员个人设置变更：silent / groupRemark 个人多端同步
+  GROUP_MESSAGE_PIN: 1531, // 群消息置顶（自有扩展，OpenIM 无）
+  GROUP_MESSAGE_UNPIN: 1532, // 群消息取消置顶（自有扩展，OpenIM 无）
+  GROUP_BANNED: 1533 // 群封禁变更（自有扩展，OpenIM 无）
+} as const
+
+/** 判断是否「群广播事件」：[GROUP_CREATE, GROUP_BANNED] 段位都算，仅 GROUP_MEMBER_SETTING_UPDATE 是个人信号排除 */
+export function isGroupNotification(type: number): boolean {
+  return (
+    type >= ImContentType.GROUP_CREATE &&
+    type <= ImContentType.GROUP_BANNED &&
+    type !== ImContentType.GROUP_MEMBER_SETTING_UPDATE
+  )
+}
+
+/** 判断是否「好友通知事件」：1201-1210 段位 */
+export function isFriendNotification(type: number): boolean {
+  return type >= ImContentType.FRIEND_REQUEST_APPROVED && type <= ImContentType.FRIEND_UPDATE
+}
+
+/** 判断是否「加群申请通知事件」：1503/1505/1506 */
+export function isGroupRequestNotification(type: number): boolean {
+  return (
+    type === ImContentType.GROUP_REQUEST_RECEIVED ||
+    type === ImContentType.GROUP_REQUEST_APPROVED ||
+    type === ImContentType.GROUP_REQUEST_REJECTED
+  )
+}
+
+/** 判断是否「会话内的好友事件气泡」：FRIEND_ADD / FRIEND_DELETE 直接渲染成灰色提示，与群事件同处理 */
+export function isFriendChatTip(type: number): boolean {
+  return type === ImContentType.FRIEND_ADD || type === ImContentType.FRIEND_DELETE
+}
+
+/** 判断是否「会话内的通话事件气泡」：RTC_CALL_START / RTC_CALL_END 渲染成灰色提示 */
+export function isRtcCallTip(type: number): boolean {
+  return type === ImContentType.RTC_CALL_START || type === ImContentType.RTC_CALL_END
+}
+
+/**
+ * IM 普通内容类型集合（normal vs event 二分；与后端 ImContentTypeEnum.normal 字段语义一致）
+ *
+ * 这个集合在多处被复用，新增类型前先确认所有副作用都符合预期：
+ * 1. 后端发送入口校验（Im{Private,Group}MessageSendReqVO.isNormalType）—— 用户发送的内容类型必须 normal=true
+ * 2. 前端接收侧未读 / 提示音（websocketStore）—— normal 消息计入会话未读数 + 触发声音
+ * 3. 前端会话列表 lastType / @ 标签（ConversationItem）—— 只有 normal 才算「最后一条聊天消息」
+ * 4. 前端群消息置顶菜单（message-item.vue 的 canPin）—— normal 才允许群主 / 管理员置顶
+ *
+ * 名片（CARD）/ 表情（FACE）都是「用户主动发的聊天消息」，1/2/3 都符合预期；4 同时放开 = 群主可置顶，语义合理
+ */
+const ImContentTypeNormals = new Set<number>([
+  ImContentType.CARD,
+  ImContentType.FACE,
+  ImContentType.FILE,
+  ImContentType.IMAGE,
+  ImContentType.MATERIAL, // 频道素材计入未读数 + 进会话列表
+  ImContentType.MERGE,
+  ImContentType.TEXT,
+  ImContentType.VIDEO,
+  ImContentType.VOICE
+])
+
+/** 判断是否"普通消息" */
+export function isNormalMessage(type: number): boolean {
+  return ImContentTypeNormals.has(type)
+}
+
+/** IM 媒体内容类型集合：发送依赖本地 File 上传，刷新后 _localFile 丢失即不可恢复 */
+const ImContentTypeMedia = new Set<number>([
+  ImContentType.FILE,
+  ImContentType.IMAGE,
+  ImContentType.VIDEO,
+  ImContentType.VOICE
+])
+
+/** 判断是否「媒体消息」：图片 / 文件 / 语音 / 视频 */
+export function isMediaMessageType(type: number): boolean {
+  return ImContentTypeMedia.has(type)
+}
+
+/**
+ * IM 消息状态枚举（对齐后端 ImMessageStatusEnum，前端扩展 SENDING + FAILED）
+ *
+ * 生命周期：FAILED(-2) → SENDING(-1) → NORMAL(0) → RECALL(2)
+ */
+export const ImMessageStatus = {
+  FAILED: -2, // 发送失败（前端独有）
+  SENDING: -1, // 发送中（前端独有）
+  NORMAL: 0, // 正常
+  RECALL: 2 // 已撤回
+} as const
+
+/** IM 会话类型枚举 */
+export const ImConversationType = {
+  NONE: 0, // 无会话
+  PRIVATE: 1, // 私聊
+  GROUP: 2, // 群聊
+  CHANNEL: 3 // 频道 / 公众号
+} as const
+
+/** ImConversationType 取值（用于消息 payload 字段类型收窄） */
+export type ImConversationTypeValue = (typeof ImConversationType)[keyof typeof ImConversationType]
+
+/** 是否私聊会话；同时收窄类型 */
+export function isPrivateConversation(type: number | undefined): boolean {
+  return type === ImConversationType.PRIVATE
+}
+
+/** 是否群聊会话；同时收窄类型 */
+export function isGroupConversation(type: number | undefined): boolean {
+  return type === ImConversationType.GROUP
+}
+
+/** 是否频道会话；同时收窄类型 */
+export function isChannelConversation(type: number | undefined): boolean {
+  return type === ImConversationType.CHANNEL
+}
+
+/** IM 通话媒体类型（对齐后端 ImRtcCallMediaTypeEnum） */
+export const ImRtcCallMediaType = {
+  VOICE: 1,
+  VIDEO: 2
+} as const
+
+/** IM 通话状态（对齐后端 ImRtcCallStatusEnum） */
+export const ImRtcCallStatus = {
+  CREATED: 10, // 创建：私聊等被叫接听；群聊发起人已进房等其他人加入
+  RUNNING: 20, // 进行中：第一个非发起人接通后进入
+  ENDED: 30 // 已结束
+} as const
+
+/** IM 通话结束原因（对齐后端 ImRtcCallEndReasonEnum） */
+export const ImRtcCallEndReason = {
+  HANGUP: 1, // 接通后任一方主动挂断
+  REJECT: 2, // 被叫接通前点拒接
+  CANCEL: 3, // 主叫接通前主动取消
+  NO_ANSWER: 4, // 振铃超时未接通
+  BUSY: 5, // 私聊呼叫时对方正忙
+  ERROR: 9 // 网络中断 / 设备失败
+} as const
+
+/** ImRtcCallEndReason 取值类型 */
+export type ImRtcCallEndReasonValue = (typeof ImRtcCallEndReason)[keyof typeof ImRtcCallEndReason]
+
+/** IM 通话参与者状态（对齐后端 ImRtcParticipantStatusEnum）；同时作为 RTC_CALL 信令 status 字段取值 */
+export const ImRtcParticipantStatus = {
+  INVITING: 10, // 来电邀请
+  JOINED: 20, // 接听 / 已加入
+  REJECTED: 30, // 拒接
+  NO_ANSWER: 40, // 主叫取消，被邀请方未应答
+  LEFT: 50 // 挂断离开
+} as const
+
+/** ImRtcParticipantStatus 取值类型 */
+export type ImRtcParticipantStatusValue =
+  (typeof ImRtcParticipantStatus)[keyof typeof ImRtcParticipantStatus]
+
+/**
+ * IM 通话 UI 阶段；前端独有，用于驱动 inviting / incoming / running 三种弹窗切换；
+ * 跟后端 ImRtcCallStatus 不是 1:1 映射，stage 多了「自己是主叫还是被叫」的角色维度
+ */
+export const ImRtcCallStage = {
+  IDLE: 'idle', // 空闲；后端无对应（本端无活跃通话）
+  INVITING: 'inviting', // 主叫等待对方接受；对应后端 ImRtcCallStatus.CREATED（自己是主叫）
+  INCOMING: 'incoming', // 被叫来电响铃；对应后端 ImRtcCallStatus.CREATED（自己是被叫）
+  RUNNING: 'running' // 通话中；对应后端 ImRtcCallStatus.RUNNING
+} as const
+
+/** ImRtcCallStage 取值类型 */
+export type ImRtcCallStageValue = (typeof ImRtcCallStage)[keyof typeof ImRtcCallStage]
+
+/** IM WebSocket 外层帧类型 */
+export const ImWebSocketMessageType = {
+  NOTIFICATION: 'im-notification' // IM 通知
+} as const
+
+/** IM 消息回执状态枚举（对齐后端 ImMessageReceiptStatusEnum） */
+export const ImMessageReceiptStatus = {
+  NO_RECEIPT: 0, // 不需要回执
+  PENDING: 1, // 待完成
+  DONE: 2 // 已完成
+} as const
+
+/** 群成员角色（对齐后端 ImGroupMemberRoleEnum） */
+export const ImGroupMemberRole = {
+  OWNER: 1, // 群主
+  ADMIN: 2, // 管理员
+  NORMAL: 3 // 普通成员
+} as const
+
+/** 加群来源（对齐后端 ImGroupAddSourceEnum） */
+export const ImGroupAddSource = {
+  SEARCH: 1, // 搜索
+  INVITE: 2, // 邀请
+  QR_CODE: 3, // 扫码
+  SHARE_LINK: 4 // 分享链接
+} as const
+
+/** 加群申请处理结果（对齐后端 ImGroupRequestHandleResultEnum） */
+export const ImGroupRequestHandleResult = {
+  UNHANDLED: 0, // 未处理
+  AGREED: 1, // 同意
+  REFUSED: 2 // 拒绝
+} as const
+
+/** 好友添加来源（对齐后端 ImFriendAddSourceEnum） */
+export const ImFriendAddSource = {
+  SEARCH: 1, // 搜索
+  GROUP: 2, // 群聊
+  QR_CODE: 3, // 扫码
+  CARD: 4 // 名片
+} as const
+
+/** 好友申请处理结果（对齐后端 ImFriendRequestHandleResultEnum） */
+export const ImFriendRequestHandleResult = {
+  UNHANDLED: 0, // 未处理
+  AGREED: 1, // 同意
+  REFUSED: 2 // 拒绝
+} as const
+
+/**
+ * @全体成员 的特殊 userId 标识：atUserIds 中包含 -1 表示 @ 全体成员
+ *
+ * 与后端约定：群消息 atUserIds 数组里出现 -1 时，所有成员都收到提醒
+ * MentionPicker 渲染虚拟项 + conversationStore.applyAt 判定 atAll 都靠这个值
+ */
+export const IM_AT_ALL_USER_ID = -1
+
+/** @全体成员 的展示名（对齐微信 PC） */
+export const IM_AT_ALL_NICKNAME = '所有人'
+
+/** 转发模式：SINGLE 逐条原样转 / MERGE 打包成 MergeMessage */
+export const ImForwardMode = {
+  SINGLE: 'single',
+  MERGE: 'merge'
+} as const
+
+/** ImForwardMode 取值类型 */
+export type ImForwardModeValue = (typeof ImForwardMode)[keyof typeof ImForwardMode]
diff --git a/apps/web-ele/src/views/im/utils/conversation.ts b/apps/web-ele/src/views/im/utils/conversation.ts
new file mode 100644
index 000000000..f84670536
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/conversation.ts
@@ -0,0 +1,177 @@
+// ====================================================================
+// IM 会话 / 撤回展示 utility
+// ====================================================================
+// 基于 conversation 上下文 + sender 信息实时算"展示文案"。
+// 1. 发送人名一律由 utils/user.getSenderDisplayName 实时算，本文件只负责拼"撤回 tip / 摘要"等文案。
+// 2. fallbackName 由调用方传入（典型来源：Conversation.lastSenderDisplayName 快照），透传到 getSenderDisplayName 内部，算不出真名时兜底
+// ====================================================================
+
+import type { Message } from '../home/types'
+
+import { ImContentType, ImConversationType, isFriendChatTip, isGroupNotification, isRtcCallTip } from './constants'
+import {
+  type CardMessage,
+  type FaceMessage,
+  type FileMessage,
+  getCardLabelInfo,
+  type MaterialMessage,
+  parseMessage,
+  segmentsToText,
+  type TextMessage,
+  tipMention,
+  type TipSegment,
+  tipText
+} from './message'
+import { resolveFriendNotificationText, resolveGroupNotificationText, resolveRtcCallLastContent } from './message'
+import { getSenderDisplayName } from './user'
+
+/** 会话主键：`type-targetId` 拼成稳定字符串，给 v-for :key、active 比对、map key 等场景共用 */
+export function getConversationKey(conversation: { targetId: number; type: number; }): string {
+  return `${conversation.type}-${conversation.targetId}`
+}
+
+/** 按昵称模糊过滤会话列表：空 keyword 原样返回，命中走 toLowerCase 不区分大小写 */
+export function filterConversationsByKeyword<T extends { name?: string }>(
+  list: T[],
+  keyword: string
+): T[] {
+  const trimmed = keyword.trim().toLowerCase()
+  if (!trimmed) {
+    return list
+  }
+  return list.filter((c) => (c.name || '').toLowerCase().includes(trimmed))
+}
+
+/**
+ * 表情消息的统一文本预览：摘要 / 历史搜索 / 引用块 / 管理后台预览共用一份
+ * 有 name 时走 `[表情] name`（系统包），无 name 时走 `[表情]`（个人表情通常无 name）
+ */
+export function buildFacePreviewText(facePayload: null | undefined | { name?: string }): string {
+  return facePayload?.name ? `[表情] ${facePayload.name}` : '[表情]'
+}
+
+/**
+ * 撤回提示 segments
+ *
+ * senderId 缺失时不挂 mention 段，避免点出错号；算不出真名降级为「对方」纯文本
+ */
+export function buildRecallTipSegments(
+  senderId: number,
+  selfSend: boolean,
+  conversationType: number,
+  conversationTargetId: number,
+  fallbackName?: string
+): TipSegment[] {
+  if (selfSend) {
+    return [tipText('你撤回了一条消息')]
+  }
+  const senderDisplayName = getSenderDisplayName(
+    senderId,
+    conversationType,
+    conversationTargetId,
+    fallbackName
+  )
+  if (!senderId) {
+    return [tipText(`${senderDisplayName || '对方'} 撤回了一条消息`)]
+  }
+  return [
+    tipMention(senderId, senderDisplayName || '对方'),
+    tipText(' 撤回了一条消息')
+  ]
+}
+
+/** 撤回提示文案：自己撤回固定文案，对方撤回带 sender 名（实时算 + fallbackName 兜底） */
+export function buildRecallTip(
+  senderId: number,
+  selfSend: boolean,
+  conversationType: number,
+  conversationTargetId: number,
+  fallbackName?: string
+): string {
+  return segmentsToText(
+    buildRecallTipSegments(senderId, selfSend, conversationType, conversationTargetId, fallbackName)
+  )
+}
+
+/**
+ * 单条消息的纯文本摘要；不依赖 conversation 上下文
+ *
+ * - withFileName=true 时文件消息附带文件名（合并转发详情用）
+ * - 不处理 RECALL / 群广播 / 好友通知，由调用方包一层
+ */
+export function summarizeMessageContent(
+  message: Pick<Message, 'content' | 'type'>,
+  opts?: { withFileName?: boolean }
+): string {
+  switch (message.type) {
+    case ImContentType.CARD: {
+      return `[${getCardLabelInfo(parseMessage<CardMessage>(message.content)).label}]`
+    }
+    case ImContentType.FACE: {
+      return buildFacePreviewText(parseMessage<FaceMessage>(message.content))
+    }
+    case ImContentType.FILE: {
+      if (opts?.withFileName) {
+        const file = parseMessage<FileMessage>(message.content)
+        return file?.name ? `[文件] ${file.name}` : '[文件]'
+      }
+      return '[文件]'
+    }
+    case ImContentType.IMAGE: {
+      return '[图片]'
+    }
+    case ImContentType.MATERIAL: {
+      const material = parseMessage<MaterialMessage>(message.content)
+      return material?.title ? `[频道] ${material.title}` : '[频道]'
+    }
+    case ImContentType.MERGE: {
+      return '[聊天记录]'
+    }
+    case ImContentType.RTC_CALL_END:
+    case ImContentType.RTC_CALL_START: {
+      return '[语音通话]'
+    }
+    case ImContentType.TEXT: {
+      return parseMessage<TextMessage>(message.content)?.content ?? ''
+    }
+    case ImContentType.VIDEO: {
+      return '[视频]'
+    }
+    case ImContentType.VOICE: {
+      return '[语音]'
+    }
+    default: {
+      return ''
+    }
+  }
+}
+
+/** 会话列表最后一条摘要：RECALL 走 buildRecallTip + fallbackName；其它按内容类型派生 */
+export function resolveConversationLastContent(
+  message: Message,
+  conversationType: number,
+  conversationTargetId: number,
+  fallbackName?: string
+): string {
+  if (message.type === ImContentType.RECALL) {
+    return buildRecallTip(
+      message.senderId,
+      message.selfSend,
+      conversationType,
+      conversationTargetId,
+      fallbackName
+    )
+  }
+  if (isFriendChatTip(message.type)) {
+    return resolveFriendNotificationText(message)
+  }
+  if (isGroupNotification(message.type)) {
+    return resolveGroupNotificationText(message, (id) =>
+      getSenderDisplayName(id, ImConversationType.GROUP, message.targetId ?? 0)
+    )
+  }
+  if (isRtcCallTip(message.type)) {
+    return resolveRtcCallLastContent(message, conversationType)
+  }
+  return summarizeMessageContent(message)
+}
diff --git a/apps/web-ele/src/views/im/utils/db.ts b/apps/web-ele/src/views/im/utils/db.ts
new file mode 100644
index 000000000..b3d1bcdf1
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/db.ts
@@ -0,0 +1,537 @@
+import type { MessageDO, SettingDO } from '../home/types'
+
+import { toRaw } from 'vue'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { ImConversationType } from './constants'
+
+export const DB_SCHEMA_VERSION = 2
+
+export type DbStoreName =
+  | 'channels'
+  | 'conversationReads'
+  | 'conversations'
+  | 'friendRequests'
+  | 'friends'
+  | 'groupMembers'
+  | 'groupRequests'
+  | 'groups'
+  | 'messages'
+  | 'settings'
+
+export type DbTransaction = IDBTransaction
+
+/** IM 本地存储 key */
+export const StorageKeys = {
+  localStorage: {
+    /** 侧边栏宽度，三个 Tab 共用一份记忆 */
+    asideWidth: 'im:aside',
+    /** 会话列表置顶折叠展开态 */
+    conversationPinnedExpanded: 'im:conversation:pinnedExpanded'
+  },
+  settings: {
+    /** 私聊消息拉取游标 */
+    privateMessageMaxId: 'privateMessageMaxId',
+    /** 群聊消息拉取游标 */
+    groupMessageMaxId: 'groupMessageMaxId',
+    /** 频道消息拉取游标 */
+    channelMessageMaxId: 'channelMessageMaxId',
+    /** 最近转发会话 key 列表 */
+    recentForwardConversationKeys: 'recentForwardConversationKeys',
+    // 状态事件补偿增量拉取游标：与上面消息 maxId 游标共用同一 settings keyspace，统一登记在此避免撞 key；
+    // 走 update_time + id 复合游标（非单条 maxId），故用 PullCursor 后缀区分语义
+    /** 好友关系增量拉取游标 */
+    friendPullCursor: 'friendPullCursor',
+    /** 好友申请增量拉取游标 */
+    friendRequestPullCursor: 'friendRequestPullCursor',
+    /** 加群申请增量拉取游标 */
+    groupRequestPullCursor: 'groupRequestPullCursor',
+    /** 会话读位置增量拉取游标 */
+    conversationReadPullCursor: 'conversationReadPullCursor'
+  }
+} as const
+
+let currentDb: IDBDatabase | null = null
+let currentUserId: null | number = null
+let currentSession = 0
+
+/** 校验当前 IM IndexedDB session 仍有效 */
+export function isCurrentDbSession(session: number): boolean {
+  return session === currentSession
+}
+
+/** 获取当前 IM IndexedDB session */
+export function getDbSession(): number {
+  return currentSession
+}
+
+/** 拼接当前用户 IM DB 名称 */
+function getDbName(userId: number): string {
+  return `im:${userId}`
+}
+
+/** 包装 IndexedDB request */
+function requestToPromise<T = unknown>(request: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    request.addEventListener('success', () => resolve(request.result))
+    request.addEventListener('error', () => reject(request.error))
+  })
+}
+
+/** 等待事务完成 */
+function transactionDone(transaction: DbTransaction): Promise<void> {
+  return new Promise((resolve, reject) => {
+    transaction.addEventListener('complete', () => resolve())
+    transaction.addEventListener('error', () => reject(transaction.error))
+    transaction.addEventListener('abort', () => reject(transaction.error))
+  })
+}
+
+/** 创建索引 */
+function createIndex(
+  store: IDBObjectStore,
+  name: string,
+  keyPath: string | string[],
+  options?: IDBIndexParameters
+) {
+  if (!store.indexNames.contains(name)) {
+    store.createIndex(name, keyPath, options)
+  }
+}
+
+/** 初始化 schema */
+function upgradeSchema(db: IDBDatabase) {
+  if (!db.objectStoreNames.contains('conversations')) {
+    const store = db.createObjectStore('conversations', { keyPath: 'clientConversationId' })
+    createIndex(store, 'lastSendTime', 'lastSendTime')
+  }
+  if (!db.objectStoreNames.contains('conversationReads')) {
+    const store = db.createObjectStore('conversationReads', { keyPath: 'clientConversationId' })
+    createIndex(store, 'conversationType+targetId', ['conversationType', 'targetId'], {
+      unique: true
+    })
+  }
+  if (!db.objectStoreNames.contains('messages')) {
+    const store = db.createObjectStore('messages', { keyPath: 'messageKey' })
+    createIndex(store, 'clientConversationId', 'clientConversationId')
+    createIndex(store, 'clientConversationId+sendTime', ['clientConversationId', 'sendTime'])
+    createIndex(store, 'clientMessageId', 'clientMessageId', { unique: true })
+  }
+  if (!db.objectStoreNames.contains('friends')) {
+    const store = db.createObjectStore('friends', { keyPath: 'id' })
+    createIndex(store, 'friendUserId', 'friendUserId', { unique: true })
+    createIndex(store, 'status', 'status')
+  }
+  if (!db.objectStoreNames.contains('friendRequests')) {
+    const store = db.createObjectStore('friendRequests', { keyPath: 'id' })
+    createIndex(store, 'status', 'status')
+    createIndex(store, 'createTime', 'createTime')
+  }
+  if (!db.objectStoreNames.contains('groups')) {
+    const store = db.createObjectStore('groups', { keyPath: 'id' })
+    createIndex(store, 'name', 'name')
+    createIndex(store, 'status', 'status')
+  }
+  if (!db.objectStoreNames.contains('groupMembers')) {
+    const store = db.createObjectStore('groupMembers', { keyPath: 'id' })
+    createIndex(store, 'groupId', 'groupId')
+    createIndex(store, 'groupId+userId', ['groupId', 'userId'], { unique: true })
+  }
+  if (!db.objectStoreNames.contains('groupRequests')) {
+    const store = db.createObjectStore('groupRequests', { keyPath: 'id' })
+    createIndex(store, 'status', 'status')
+    createIndex(store, 'createTime', 'createTime')
+  }
+  if (!db.objectStoreNames.contains('channels')) {
+    const store = db.createObjectStore('channels', { keyPath: 'id' })
+    createIndex(store, 'status', 'status')
+    createIndex(store, 'sort', 'sort')
+  }
+  if (!db.objectStoreNames.contains('settings')) {
+    db.createObjectStore('settings', { keyPath: 'key' })
+  }
+}
+
+/** 打开 IM IndexedDB */
+function openDb(name: string): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(name, DB_SCHEMA_VERSION)
+    // 创建或升级对象仓库
+    request.addEventListener('upgradeneeded', () => upgradeSchema(request.result))
+    // 返回可复用连接
+    request.addEventListener('success', () => resolve(request.result))
+    request.addEventListener('error', () => reject(request.error))
+  })
+}
+
+/** 初始化当前用户 IM DB */
+export async function initDb(): Promise<void> {
+  const userId = getCurrentUserId()
+  if (!Number.isFinite(userId) || userId <= 0) {
+    throw new Error('当前用户不存在，无法初始化 IM DB')
+  }
+  if (currentDb && currentUserId === userId) {
+    return
+  }
+  currentDb?.close()
+  currentSession++
+  currentUserId = userId
+  currentDb = await openDb(getDbName(userId))
+}
+
+/** 关闭当前 IM DB 连接 */
+function closeDbConnection() {
+  currentDb?.close()
+  currentDb = null
+  currentUserId = null
+}
+
+/** 获取当前 IM DB */
+function getRawDb(): IDBDatabase {
+  if (!currentDb) {
+    throw new Error('IM DB 未初始化')
+  }
+  return currentDb
+}
+
+/** 校验单次写入 session */
+function guardSession(session: number) {
+  if (!isCurrentDbSession(session)) {
+    throw new Error('IM DB session 已失效')
+  }
+}
+
+/** 克隆可入库对象 */
+function toDbValue<T>(value: T): T {
+  return cloneDbValue(value) as T
+}
+
+/** 转换为 IndexedDB 可克隆对象 */
+function cloneDbValue(value: unknown): unknown {
+  const raw = toRaw(value)
+  if (Array.isArray(raw)) {
+    return raw.map((item) => cloneDbValue(item))
+  }
+  if (!raw || typeof raw !== 'object') {
+    return raw
+  }
+  const prototype = Object.getPrototypeOf(raw)
+  if (prototype !== Object.prototype && prototype !== null) {
+    return raw
+  }
+  return Object.fromEntries(
+    Object.entries(raw as Record<string, unknown>).map(([key, item]) => [key, cloneDbValue(item)])
+  )
+}
+
+class DbClient {
+  /** 清空 store 记录 */
+  async clearStore(storeName: DbStoreName, tx?: DbTransaction): Promise<void> {
+    if (tx) {
+      await requestToPromise(tx.objectStore(storeName).clear())
+      return
+    }
+    await this.transaction([storeName], 'readwrite', (tx) => this.clearStore(storeName, tx))
+  }
+
+  /** 删除记录 */
+  async delete(storeName: DbStoreName, key: IDBValidKey, tx?: DbTransaction): Promise<void> {
+    if (tx) {
+      await requestToPromise(tx.objectStore(storeName).delete(key))
+      return
+    }
+    await this.transaction([storeName], 'readwrite', (tx) => this.delete(storeName, key, tx))
+  }
+
+  /** 按索引删除记录 */
+  async deleteByIndex(
+    storeName: DbStoreName,
+    indexName: string,
+    query: IDBKeyRange | IDBValidKey,
+    tx?: DbTransaction
+  ): Promise<void> {
+    if (!tx) {
+      await this.transaction([storeName], 'readwrite', (tx) =>
+        this.deleteByIndex(storeName, indexName, query, tx)
+      )
+      return
+    }
+    const index = tx.objectStore(storeName).index(indexName)
+    await new Promise<void>((resolve, reject) => {
+      const request = index.openCursor(query)
+      request.addEventListener('error', () => reject(request.error))
+      request.addEventListener('success', () => {
+        const cursor = request.result
+        if (!cursor) {
+          resolve()
+          return
+        }
+        cursor.delete()
+        cursor.continue()
+      })
+    })
+  }
+
+  /** 获取单条记录 */
+  async get<T>(
+    storeName: DbStoreName,
+    key: IDBValidKey,
+    tx?: DbTransaction
+  ): Promise<T | undefined> {
+    if (tx) {
+      return requestToPromise<T | undefined>(tx.objectStore(storeName).get(key))
+    }
+    return this.transaction<T | undefined>([storeName], 'readonly', (tx) =>
+      this.get<T>(storeName, key, tx)
+    )
+  }
+
+  /** 获取 store 全量记录 */
+  async getAll<T>(storeName: DbStoreName, tx?: DbTransaction): Promise<T[]> {
+    if (tx) {
+      return requestToPromise<T[]>(tx.objectStore(storeName).getAll())
+    }
+    return this.transaction<T[]>([storeName], 'readonly', (tx) => this.getAll<T>(storeName, tx))
+  }
+
+  /** 按索引获取记录列表 */
+  async getAllByIndex<T>(
+    storeName: DbStoreName,
+    indexName: string,
+    query?: IDBKeyRange | IDBValidKey,
+    tx?: DbTransaction
+  ): Promise<T[]> {
+    if (tx) {
+      return requestToPromise<T[]>(tx.objectStore(storeName).index(indexName).getAll(query))
+    }
+    return this.transaction<T[]>([storeName], 'readonly', (tx) =>
+      this.getAllByIndex<T>(storeName, indexName, query, tx)
+    )
+  }
+
+  /** 按唯一索引获取单条记录 */
+  async getByIndex<T>(
+    storeName: DbStoreName,
+    indexName: string,
+    query: IDBKeyRange | IDBValidKey,
+    tx?: DbTransaction
+  ): Promise<T | undefined> {
+    if (tx) {
+      return requestToPromise<T | undefined>(tx.objectStore(storeName).index(indexName).get(query))
+    }
+    return this.transaction<T | undefined>([storeName], 'readonly', (tx) =>
+      this.getByIndex<T>(storeName, indexName, query, tx)
+    )
+  }
+
+  /** 按会话分页获取消息 */
+  async getMessageListByConversation(
+    clientConversationId: string,
+    options?: { beforeSendTime?: number; limit?: number },
+    tx?: DbTransaction
+  ): Promise<MessageDO[]> {
+    const limit = options?.limit ?? 50
+    const upper = options?.beforeSendTime ?? Number.MAX_SAFE_INTEGER
+    const range = IDBKeyRange.bound(
+      [clientConversationId, 0],
+      [clientConversationId, upper],
+      false,
+      true
+    )
+    const read = async (tx: DbTransaction): Promise<MessageDO[]> => {
+      const index = tx.objectStore('messages').index('clientConversationId+sendTime')
+      const out: MessageDO[] = []
+      await new Promise<void>((resolve, reject) => {
+        // 从新到旧读取一页
+        const request = index.openCursor(range, 'prev')
+        request.addEventListener('error', () => reject(request.error))
+        request.addEventListener('success', () => {
+          const cursor = request.result
+          if (!cursor || out.length >= limit) {
+            resolve()
+            return
+          }
+          out.push(cursor.value as MessageDO)
+          cursor.continue()
+        })
+      })
+      // 气泡渲染需要按时间升序
+      return out.toReversed()
+    }
+    if (tx) {
+      return read(tx)
+    }
+    return this.transaction<MessageDO[]>(['messages'], 'readonly', read)
+  }
+
+  /** 读取设置 */
+  async getSetting<T>(key: string, tx?: DbTransaction): Promise<T | undefined> {
+    const item = await this.get<SettingDO<T>>('settings', key, tx)
+    return item?.value
+  }
+
+  /** 写入记录 */
+  async put<T>(storeName: DbStoreName, value: T, tx?: DbTransaction): Promise<void> {
+    if (tx) {
+      await requestToPromise(tx.objectStore(storeName).put(toDbValue(value)))
+      return
+    }
+    await this.transaction([storeName], 'readwrite', (tx) => this.put(storeName, value, tx))
+  }
+
+  /** 写入设置 */
+  async setSetting<T>(key: string, value: T, tx?: DbTransaction): Promise<void> {
+    await this.put<SettingDO<T>>('settings', { key, value, updateTime: Date.now() }, tx)
+  }
+
+  /** 执行事务 */
+  async transaction<T>(
+    storeNames: DbStoreName[],
+    mode: IDBTransactionMode,
+    runner: (tx: DbTransaction) => Promise<T>
+  ): Promise<T> {
+    // 开启事务前校验 session
+    const session = getDbSession()
+    guardSession(session)
+    const tx = getRawDb().transaction(storeNames, mode)
+    const done = transactionDone(tx)
+    let result: T
+    try {
+      // 事务内只执行 IndexedDB request 链
+      result = await runner(tx)
+    } catch (error) {
+      try {
+        tx.abort()
+      } catch {}
+      await done.catch(() => undefined)
+      throw error
+    }
+    // commit 后再次校验 session
+    await done
+    guardSession(session)
+    return result
+  }
+}
+
+const dbClient = new DbClient()
+
+/** 获取当前 IM DB client */
+export function getDb(): DbClient {
+  return dbClient
+}
+
+/** 当前用户会话主键 */
+export function getClientConversationId(type: number, targetId: number): string {
+  return `${type}:${targetId}`
+}
+
+/** 解析当前用户会话主键 */
+export function parseClientConversationId(
+  clientConversationId: string
+): null | { targetId: number; type: number; } {
+  const [typeText, targetIdText] = clientConversationId.split(':')
+  const type = Number(typeText)
+  const targetId = Number(targetIdText)
+  if (!Number.isFinite(type) || !Number.isFinite(targetId) || targetId <= 0) {
+    return null
+  }
+  return { type, targetId }
+}
+
+/** 服务端消息主键 */
+export function getServerMessageKey(conversationType: number, id: number): string {
+  return `${conversationType}:${id}`
+}
+
+/** 客户端临时消息主键 */
+export function getClientMessageKey(clientMessageId: string): string {
+  return `client:${clientMessageId}`
+}
+
+/** 解析本地消息主键 */
+export function parseMessageKey(
+  messageKey: string
+):
+  | null
+  | { clientMessageId: string; kind: 'client'; }
+  | { conversationType: number; id: number; kind: 'server'; } {
+  if (!messageKey) {
+    return null
+  }
+  if (messageKey.startsWith('client:')) {
+    const clientMessageId = messageKey.slice('client:'.length)
+    return clientMessageId ? { kind: 'client', clientMessageId } : null
+  }
+  const [conversationTypeText, idText] = messageKey.split(':')
+  const conversationType = Number(conversationTypeText)
+  const id = Number(idText)
+  if (!Number.isFinite(conversationType) || !Number.isFinite(id) || id <= 0) {
+    return null
+  }
+  return { kind: 'server', conversationType, id }
+}
+
+/** 更新消息拉取游标 */
+export async function setMessageMaxId(
+  conversationType: number,
+  maxId: number | undefined,
+  tx?: DbTransaction
+): Promise<void> {
+  if (!maxId) {
+    return
+  }
+  let key: string
+  switch (conversationType) {
+    case ImConversationType.CHANNEL: {
+      key = StorageKeys.settings.channelMessageMaxId
+      break
+    }
+    case ImConversationType.GROUP: {
+      key = StorageKeys.settings.groupMessageMaxId
+      break
+    }
+    case ImConversationType.PRIVATE: {
+      key = StorageKeys.settings.privateMessageMaxId
+      break
+    }
+    default: {
+      throw new Error(`未知 IM 会话类型：${conversationType}`)
+    }
+  }
+  const db = getDb()
+  const current = (await db.getSetting<number>(key, tx)) || 0
+  if (maxId > current) {
+    await db.setSetting(key, maxId, tx)
+  }
+}
+
+/** 停止当前 IM DB session */
+export async function stopRequests(): Promise<void> {
+  currentSession++
+  const [
+    { useMessageStoreWithOut },
+    { useConversationStoreWithOut },
+    { useFriendStoreWithOut },
+    { useGroupStoreWithOut },
+    { useChannelStoreWithOut },
+    { useGroupRequestStoreWithOut },
+    { useFaceStoreWithOut }
+  ] = await Promise.all([
+    import('../home/store/messageStore'),
+    import('../home/store/conversationStore'),
+    import('../home/store/friendStore'),
+    import('../home/store/groupStore'),
+    import('../home/store/channelStore'),
+    import('../home/store/groupRequestStore'),
+    import('../home/store/faceStore')
+  ])
+  useMessageStoreWithOut().clear()
+  useConversationStoreWithOut().clear()
+  useFriendStoreWithOut().clear()
+  useGroupStoreWithOut().clear()
+  useChannelStoreWithOut().clear()
+  useGroupRequestStoreWithOut().clear()
+  useFaceStoreWithOut().clear()
+  closeDbConnection()
+}
diff --git a/apps/web-ele/src/views/im/utils/emoji.ts b/apps/web-ele/src/views/im/utils/emoji.ts
new file mode 100644
index 000000000..2a25315e8
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/emoji.ts
@@ -0,0 +1,21 @@
+/**
+ * IM 常用 Unicode emoji 列表
+ *
+ * 所见即所得（不依赖图片资源），由表情面板（FacePicker 的 emoji tab）使用；
+ * Unicode emoji 选中后由调用方插入到输入框走 TEXT 通道，不走 FACE 内容类型
+ */
+export const IM_EMOJI_LIST: string[] = [
+  '😀', '😁', '😂', '🤣', '😃', '😄', '😅', '😆', '😉', '😊',
+  '😋', '😎', '😍', '😘', '😗', '😙', '😚', '🙂', '🤗', '🤩',
+  '🤔', '🤨', '😐', '😑', '😶', '🙄', '😏', '😣', '😥', '😮',
+  '🤐', '😯', '😪', '😫', '😴', '😌', '😛', '😜', '😝', '🤤',
+  '😒', '😓', '😔', '😕', '🙃', '🤑', '😲', '☹️', '🙁', '😖',
+  '😞', '😟', '😤', '😢', '😭', '😦', '😧', '😨', '😩', '🤯',
+  '😬', '😰', '😱', '🥵', '🥶', '😳', '🤪', '😵', '😡', '😠',
+  '🤬', '😷', '🤒', '🤕', '🤢', '🤮', '🤧', '😇', '🤠', '🥳',
+  '👍', '👎', '👌', '✌️', '🤞', '🤟', '🤘', '🤙', '👈', '👉',
+  '👆', '👇', '✋', '🤚', '🖐', '🖖', '👋', '🤝', '🙏', '💪',
+  '❤️', '🧡', '💛', '💚', '💙', '💜', '🖤', '💔', '💕', '💖',
+  '🎉', '🎊', '🎁', '🎂', '🍰', '🌹', '🌷', '🌸', '🎵', '🎶',
+  '⭐', '🌟', '✨', '💫', '🔥', '💯', '✅', '❌', '⚠️', '❓'
+]
diff --git a/apps/web-ele/src/views/im/utils/group.ts b/apps/web-ele/src/views/im/utils/group.ts
new file mode 100644
index 000000000..ddc53fa8e
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/group.ts
@@ -0,0 +1,289 @@
+import type { FriendLite } from '../home/types'
+
+import { loadImage } from './image'
+import { getAvatarBgColor, getAvatarText } from './user'
+
+/** 默认群名生成：所选好友前 4 个名字拼接，超过补「等 N 人」；为空兜底「群聊」 */
+export function buildDefaultGroupName(members: FriendLite[]): string {
+  if (members.length === 0) {
+    return '群聊'
+  }
+  const names = members.slice(0, 4).map((m) => m.displayName || m.nickname || '')
+  const head = names.filter(Boolean).join('、')
+  if (members.length > 4) {
+    // members 只含被选好友，+1 把创建者也计入实际成员数
+    return `${head}等${members.length + 1}人`
+  }
+  return head || '群聊'
+}
+
+/** 群头像单格的输入：头像 URL + 名字 ，至少给一个，二者都缺时走灰底空格 */
+export interface GroupAvatarMember {
+  /** 头像 URL；缺失或加载失败时按 name 画色卡 */
+  avatar?: string
+  /** 显示名（昵称 / 备注）；色卡文字 + 底色 hash 来源 */
+  name?: string
+}
+
+/** 群头像拼接的可选参数 */
+export interface BuildGroupAvatarOptions {
+  /** 输出画布边长（像素）；默认 64 */
+  targetSize?: number
+  /** 单格之间的间隔（像素）；默认 1 */
+  divider?: number
+  /** 画布底色；默认透明，让上下留白透出宿主容器底色 */
+  background?: string
+}
+
+/** 单格在画布上的位置 + 尺寸 */
+interface CellRect {
+  x: number
+  y: number
+  w: number
+  h: number
+}
+
+/** 单格的最终绘制内容 */
+type Cell =
+  | { bg: string; kind: 'color'; text: string; }
+  | { img: HTMLImageElement; kind: 'image'; }
+
+/**
+ * 把群成员头像拼成一张方形群头像 dataURL，按 1 ~ 9 张走九宫格变体布局
+ *
+ * - 仅取前 9 个成员
+ * - 单格 avatar 为空 / 加载失败：按 name 在 canvas 上画色卡兜底
+ * - 跨域要求图片源开启 CORS（img.crossOrigin = 'anonymous'）
+ */
+export async function buildGroupAvatar(
+  members: GroupAvatarMember[],
+  options: BuildGroupAvatarOptions = {}
+): Promise<string> {
+  const targetSize = options.targetSize ?? 64
+  const divider = options.divider ?? 1
+  const background = options.background
+
+  const top = members.slice(0, 9)
+  if (top.length === 0) {
+    return ''
+  }
+
+  const cells = await Promise.all(top.map((m) => resolveCell(m)))
+  const rects = computeCellRects(cells.length, targetSize, divider)
+
+  const canvas = document.createElement('canvas')
+  canvas.width = targetSize
+  canvas.height = targetSize
+  const ctx = canvas.getContext('2d')
+  if (!ctx) {
+    return ''
+  }
+  if (background) {
+    ctx.fillStyle = background
+    ctx.fillRect(0, 0, targetSize, targetSize)
+  }
+  cells.forEach((cell, idx) => {
+    const rect = rects[idx]
+    if (!rect) {
+      return
+    }
+    drawCell(ctx, rect, cell)
+  })
+  return canvas.toDataURL('image/png')
+}
+
+/** 群头像 dataURL 缓存上限：每条约 5 ~ 30KB，200 条软封顶约 5MB 常驻 */
+const MERGED_AVATAR_CACHE_MAX = 200
+const mergedAvatarCache = new Map<string, string>()
+
+/** 取群头像 dataURL 缓存；命中时按 LRU 提到末尾 */
+export function getCachedGroupAvatar(key: string): string | undefined {
+  const cached = mergedAvatarCache.get(key)
+  if (cached === undefined) {
+    return undefined
+  }
+  mergedAvatarCache.delete(key)
+  mergedAvatarCache.set(key, cached)
+  return cached
+}
+
+/** 写群头像 dataURL 缓存；超上限时丢弃最早一条（Map 迭代顺序 = 插入顺序，配合 get 的提升即 LRU） */
+export function setCachedGroupAvatar(key: string, value: string): void {
+  if (mergedAvatarCache.has(key)) {
+    mergedAvatarCache.delete(key)
+  } else if (mergedAvatarCache.size >= MERGED_AVATAR_CACHE_MAX) {
+    const oldest = mergedAvatarCache.keys().next().value
+    if (oldest !== undefined) {
+      mergedAvatarCache.delete(oldest)
+    }
+  }
+  mergedAvatarCache.set(key, value)
+}
+
+/** 单成员 → Cell：有 avatar 且加载成功走 image，否则走 color */
+async function resolveCell(member: GroupAvatarMember): Promise<Cell> {
+  if (member.avatar) {
+    const img = await loadImage(member.avatar)
+    if (img) {
+      return { kind: 'image', img }
+    }
+  }
+  return {
+    kind: 'color',
+    text: getAvatarText(member.name),
+    bg: getAvatarBgColor(member.name)
+  }
+}
+
+/** 把单个 Cell 画到 ctx 上指定格子里；image 走 cover 裁剪保比例，color 走 fillRect + 居中文字 */
+function drawCell(
+  ctx: CanvasRenderingContext2D,
+  rect: CellRect,
+  cell: Cell
+): void {
+  const { x, y, w, h } = rect
+  if (cell.kind === 'image') {
+    drawImageCover(ctx, cell.img, x, y, w, h)
+    return
+  }
+  ctx.fillStyle = cell.bg
+  ctx.fillRect(x, y, w, h)
+  if (!cell.text) {
+    return
+  }
+  // 字号按短边算；单字 0.42、双字 0.34
+  const baseSize = Math.min(w, h)
+  const fontSize = Math.floor(baseSize * (cell.text.length > 1 ? 0.34 : 0.42))
+  ctx.fillStyle = '#FFFFFF'
+  ctx.font = `500 ${fontSize}px -apple-system, BlinkMacSystemFont, "PingFang SC", "Microsoft YaHei", sans-serif`
+  ctx.textAlign = 'center'
+  ctx.textBaseline = 'middle'
+  ctx.fillText(cell.text, x + w / 2, y + h / 2)
+}
+
+/** cover 裁剪：从源图中心裁出与目标矩形同比例的子区域，画到目标矩形（保持比例不变形） */
+function drawImageCover(
+  ctx: CanvasRenderingContext2D,
+  img: HTMLImageElement,
+  dx: number,
+  dy: number,
+  dw: number,
+  dh: number
+): void {
+  const srcAspect = img.width / img.height
+  const dstAspect = dw / dh
+  let sx = 0
+  let sy = 0
+  let sw = img.width
+  let sh = img.height
+  if (srcAspect > dstAspect) {
+    sw = sh * dstAspect
+    sx = (img.width - sw) / 2
+  } else if (srcAspect < dstAspect) {
+    sh = sw / dstAspect
+    sy = (img.height - sh) / 2
+  }
+  ctx.drawImage(img, sx, sy, sw, sh, dx, dy, dw, dh)
+}
+
+/**
+ * 按张数计算每格的位置 + 尺寸
+ *
+ * - 1 张：占满画布
+ * - 2~4 张：2 列 2 行正方形单格
+ * - 5~6 张：3 列 2 行正方形单格 + 垂直居中
+ * - 7~9 张：3 列 3 行正方形单格
+ */
+function computeCellRects(count: number, target: number, divider: number): CellRect[] {
+  if (count <= 0) {
+    return []
+  }
+  if (count === 1) {
+    return [{ x: 0, y: 0, w: target, h: target }]
+  }
+  if (count <= 4) {
+    return computeCellRectsSmall(count, target, divider)
+  }
+  if (count <= 6) {
+    return computeCellRectsMedium(count, target, divider)
+  }
+  return computeCellRectsLarge(count, target, divider)
+}
+
+/** 2~4 张：2 列 2 行正方形 */
+function computeCellRectsSmall(count: number, target: number, divider: number): CellRect[] {
+  const s = (target - 3 * divider) / 2
+  const step = s + divider
+  const rects: CellRect[] = []
+  switch (count) {
+    case 2: {
+      // 居中 1 行（留上下空白）
+      const y = target / 4
+      rects.push({ x: divider, y, w: s, h: s }, { x: divider + step, y, w: s, h: s })
+      break
+    }
+    case 3: {
+      // 上 1 居中 + 下 2
+      rects.push({ x: target / 4, y: divider, w: s, h: s })
+      const y1 = divider + step
+      rects.push({ x: divider, y: y1, w: s, h: s }, { x: divider + step, y: y1, w: s, h: s })
+      break
+    }
+    case 4: {
+      // 2×2 满铺
+      rects.push({ x: divider, y: divider, w: s, h: s }, { x: divider + step, y: divider, w: s, h: s })
+      const y1 = divider + step
+      rects.push({ x: divider, y: y1, w: s, h: s }, { x: divider + step, y: y1, w: s, h: s })
+      break
+    }
+  }
+  return rects
+}
+
+/** 5~6 张：3 列 2 行正方形单格 + 垂直居中；上下留白由透明背景透出 GroupAvatar 容器底色 */
+function computeCellRectsMedium(count: number, target: number, divider: number): CellRect[] {
+  const s = (target - 4 * divider) / 3
+  const step = s + divider
+  const xs = [divider, divider + step, divider + 2 * step] as const
+  // 2 行高 + 1 行间 div
+  const totalH = 2 * s + divider
+  const y0 = (target - totalH) / 2
+  const y1 = y0 + step
+  const rects: CellRect[] = []
+  if (count === 5) {
+    // 上 2 居中（左右对称留白） + 下 3 左右贴边
+    const upX0 = (target - 2 * s - divider) / 2
+    rects.push({ x: upX0, y: y0, w: s, h: s }, { x: upX0 + step, y: y0, w: s, h: s }, { x: xs[0], y: y1, w: s, h: s }, { x: xs[1], y: y1, w: s, h: s }, { x: xs[2], y: y1, w: s, h: s })
+    return rects
+  }
+  // count === 6：上 3 + 下 3 满铺
+  rects.push({ x: xs[0], y: y0, w: s, h: s }, { x: xs[1], y: y0, w: s, h: s }, { x: xs[2], y: y0, w: s, h: s }, { x: xs[0], y: y1, w: s, h: s }, { x: xs[1], y: y1, w: s, h: s }, { x: xs[2], y: y1, w: s, h: s })
+  return rects
+}
+
+/** 7~9 张：3 列 3 行正方形单格 */
+function computeCellRectsLarge(count: number, target: number, divider: number): CellRect[] {
+  const s = (target - 4 * divider) / 3
+  const step = s + divider
+  const xs = [divider, divider + step, divider + 2 * step] as const
+  const ys = [divider, divider + step, divider + 2 * step] as const
+  const rects: CellRect[] = []
+  if (count === 7) {
+    // 上 1 居中 + 中 3 + 下 3
+    rects.push({ x: xs[1], y: ys[0], w: s, h: s }, { x: xs[0], y: ys[1], w: s, h: s }, { x: xs[1], y: ys[1], w: s, h: s }, { x: xs[2], y: ys[1], w: s, h: s }, { x: xs[0], y: ys[2], w: s, h: s }, { x: xs[1], y: ys[2], w: s, h: s }, { x: xs[2], y: ys[2], w: s, h: s })
+    return rects
+  }
+  if (count === 8) {
+    // 上 2 居中 + 中 3 + 下 3
+    const upX0 = (target - 2 * s - divider) / 2
+    rects.push({ x: upX0, y: ys[0], w: s, h: s }, { x: upX0 + step, y: ys[0], w: s, h: s }, { x: xs[0], y: ys[1], w: s, h: s }, { x: xs[1], y: ys[1], w: s, h: s }, { x: xs[2], y: ys[1], w: s, h: s }, { x: xs[0], y: ys[2], w: s, h: s }, { x: xs[1], y: ys[2], w: s, h: s }, { x: xs[2], y: ys[2], w: s, h: s })
+    return rects
+  }
+  // count === 9：3×3 满铺
+  for (const y of ys) {
+    for (const x of xs) {
+      rects.push({ x, y, w: s, h: s })
+    }
+  }
+  return rects
+}
diff --git a/apps/web-ele/src/views/im/utils/image.ts b/apps/web-ele/src/views/im/utils/image.ts
new file mode 100644
index 000000000..207947db0
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/image.ts
@@ -0,0 +1,57 @@
+// ====================================================================
+// IM 图片工具
+// ====================================================================
+// - probeImageSize：加载本地 File 或远程 URL，读出 naturalWidth / naturalHeight
+// - loadImage：加载远程 URL 到 HTMLImageElement（失败返回 null，不抛错），供 canvas 绘制使用
+// ====================================================================
+
+/** 默认占位尺寸：probe 失败 / 解码异常时兜底，避免 width/height 为 0 让消息渲染塌掉 */
+const DEFAULT_FALLBACK_SIZE = { width: 200, height: 200 } as const
+
+/** 加载远程 URL 到 HTMLImageElement，失败返回 null；canvas 绘制要求 crossOrigin=anonymous（默认开） */
+export function loadImage(
+  src: string,
+  options: { crossOrigin?: 'anonymous' | 'use-credentials' | null } = {}
+): Promise<HTMLImageElement | null> {
+  const crossOrigin = options.crossOrigin === undefined ? 'anonymous' : options.crossOrigin
+  return new Promise((resolve) => {
+    const img = new Image()
+    if (crossOrigin) {
+      img.crossOrigin = crossOrigin
+    }
+    img.addEventListener('load', () => resolve(img))
+    img.addEventListener('error', () => resolve(null))
+    img.src = src
+  })
+}
+
+/**
+ * 加载本地 File 或远程 URL，解出 naturalWidth / naturalHeight
+ *
+ * - File：内部 createObjectURL + revokeObjectURL，避免内存累积
+ * - 远程 URL：直接走 <img>.src 触发浏览器加载（受 CORS 影响；只读尺寸不需要画 canvas，跨域也能拿到）
+ * - 解码失败 / 不是图片：返回 200×200 兜底
+ */
+export function probeImageSize(source: File | string): Promise<{ height: number; width: number; }> {
+  const isFile = source instanceof File
+  const src = isFile ? URL.createObjectURL(source) : source
+  return new Promise((resolve) => {
+    const img = new Image()
+    img.addEventListener('load', () => {
+      if (isFile) {
+        URL.revokeObjectURL(src)
+      }
+      resolve({
+        width: img.naturalWidth || DEFAULT_FALLBACK_SIZE.width,
+        height: img.naturalHeight || DEFAULT_FALLBACK_SIZE.height
+      })
+    })
+    img.addEventListener('error', () => {
+      if (isFile) {
+        URL.revokeObjectURL(src)
+      }
+      resolve({ ...DEFAULT_FALLBACK_SIZE })
+    })
+    img.src = src
+  })
+}
diff --git a/apps/web-ele/src/views/im/utils/message.ts b/apps/web-ele/src/views/im/utils/message.ts
new file mode 100644
index 000000000..5dfb3944c
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/message.ts
@@ -0,0 +1,1033 @@
+import type { Conversation, GroupLite, Message, QuoteMessage, User } from '../home/types'
+
+import { useUserStore } from '@vben/stores'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { useFriendStore } from '../home/store/friendStore'
+import { useGroupStore } from '../home/store/groupStore'
+import {
+  ImContentType,
+  ImConversationType,
+  type ImConversationTypeValue,
+  ImRtcCallEndReason
+} from './constants'
+import { formatCallDuration } from './time'
+
+export type { QuoteMessage } from '../home/types'
+
+// ====================================================================
+// IM 消息 content 编解码 & 展示工具
+// ====================================================================
+// 约定：消息的 content 字段统一存 JSON 字符串，字段名、结构对齐后端
+// cn.iocoder.yudao.module.im.service.websocket.notification.message.* 下的 DTO。
+// 各类消息 payload interface 字段对齐后端；解析统一用 parseMessage<T>，
+// 序列化直接 JSON.stringify(payload)。
+// ====================================================================
+
+// ==================== 客户端 ID ====================
+
+/** 生成客户端消息 ID（纯 UUID），用于前端去重 & ACK 回写 */
+export const generateClientMessageId = (): string => {
+  if (globalThis.crypto?.randomUUID) {
+    return globalThis.crypto.randomUUID()
+  }
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replaceAll(/[xy]/g, (char) => {
+    const random = Math.trunc(Math.random() * 16)
+    const value = char === 'x' ? random : (random & 0x3) | 0x8
+    return value.toString(16)
+  })
+}
+
+// ==================== 私聊对端 userId ====================
+
+/**
+ * 私聊消息 / DTO 的对端 userId：自己发的对端是 receiver，别人发的对端是 sender
+ *
+ * 收口 4 处旧 inline（websocketStore.convertPrivateMessage / handlePrivateMessage / computeFriendPeerId
+ * 和 useMessagePuller.getPrivatePeerId），结构类型只要 senderId / receiverId 两个字段，REST 与 WS DTO 都满足
+ */
+export function getPrivateMessagePeerId(
+  message: { receiverId: number; senderId: number; },
+  currentUserId: number
+): number {
+  return message.senderId === currentUserId ? message.receiverId : message.senderId
+}
+
+// ==================== 文本片段（tip 文案 + TEXT 气泡共用） ====================
+// 既用于灰条 tip（"XX 邀请 YY 加入群聊"），也用于 TEXT 气泡正文（@xxx 高亮 + URL 自动识别）。
+// mention 段携带 userId 用于挂点击弹 UserInfoCard；link 段携带 href 用于 <a> 跳转；
+// text 段是纯文本兜底。渲染层（tip-segments.vue）按 type 分发统一处理。
+
+export type TipSegment =
+  | { href: string; text: string; type: 'link'; }
+  | { text: string; type: 'mention'; userId: number; }
+  | { text: string; type: 'text'; }
+
+export const tipText = (text: string): TipSegment => ({ type: 'text', text })
+
+export const tipMention = (userId: number, text: string): TipSegment => ({
+  type: 'mention',
+  userId,
+  text
+})
+
+export const tipLink = (href: string, text: string): TipSegment => ({
+  type: 'link',
+  href,
+  text
+})
+
+export const segmentsToText = (segments: TipSegment[]): string =>
+  segments.map((s) => s.text).join('')
+
+/** 多个 userId 用同一个分隔符插值成 segments，每个 user 单独成 mention 段 */
+export function joinMentionSegments(
+  userIds: number[],
+  separator: string,
+  resolveName: (userId: number) => string
+): TipSegment[] {
+  return userIds.flatMap((id, index) =>
+    index === 0
+      ? [tipMention(id, resolveName(id))]
+      : [tipText(separator), tipMention(id, resolveName(id))]
+  )
+}
+
+/** mention 候选；name 用于匹配文本字面量，displayName 用于覆盖渲染（不传则按 name 渲染） */
+export interface MentionCandidate {
+  userId: number
+  /** 用来在 content 中前缀匹配的字面量（不含 @） */
+  name: string
+  /**
+   * 渲染时强制使用的显示名（不含 @）
+   *
+   * 用于「历史消息 content 里写的是备注名 / 群昵称，但接收端要按真实昵称渲染」的场景；
+   * 候选可以携带多种字面量（match 用），但 displayName 统一指向 nickname，
+   * 让所有历史 / 新消息的 @ 都收敛到一致的展示
+   */
+  displayName?: string
+  /**
+   * 歧义标记：同 name 对应多个 userId 时为 true
+   *
+   * parser 仍会按 name 命中（最长优先），但命中后整段吃成普通文本——
+   * 避免「@张三」被剔除后，短前缀候选「@张」抢匹配错绑
+   */
+  ambiguous?: boolean
+}
+
+/** URL 锚定正则；终止于空白、中文、@（避免吞掉下一个 mention）、< > " '（防 HTML / 引号串入）；y 标志走 sticky 匹配，省 text.slice */
+const URL_STICKY_REGEX = /(https?:\/\/[^\s一-龥@<>"']+|www\.[^\s一-龥@<>"']+)/iy
+
+/** URL 末尾常见标点剔除，避免吞掉句末中英文标点 */
+const URL_TRAILING_PUNCTUATION = /[.,!?;:)\]、，。！？；：）】]+$/
+
+/** 最短 URL：`www.ab` / `http:/` 这种孤段不算链接 */
+const URL_MIN_LENGTH = 6
+
+/**
+ * 文本气泡 content 拆段：mention 段按候选最长前缀匹配，URL 段走锚定正则，剩余归 text
+ *
+ * mentions 不传或匹配不上时，@xxx 退化为普通 text；解析与渲染解耦，工具函数本身不依赖 store
+ */
+export function parseTextSegments(text: string, mentions: MentionCandidate[] = []): TipSegment[] {
+  if (!text) {
+    return []
+  }
+  // 「@张三丰」不能被「@张三」截胡，候选按 name 长度倒序
+  const sortedMentions =
+    mentions.length > 1 ? mentions.toSorted((a, b) => b.name.length - a.name.length) : mentions
+  const out: TipSegment[] = []
+  let buffer = ''
+
+  const flush = () => {
+    if (buffer) {
+      out.push(tipText(buffer))
+      buffer = ''
+    }
+  }
+
+  let i = 0
+  while (i < text.length) {
+    if (text[i] === '@' && sortedMentions.length > 0) {
+      const matched = sortedMentions.find((m) => m.name && text.startsWith(m.name, i + 1))
+      if (matched) {
+        if (matched.ambiguous) {
+          // 同字面量对应多 userId，无法判定意图；整段累入 buffer 让短前缀候选没机会再扫这段
+          buffer += '@' + matched.name
+        } else {
+          flush()
+          // 渲染统一走 displayName（即真实昵称），让历史 content 里残留的备注 / 群昵称也收敛到 nickname
+          out.push(tipMention(matched.userId, '@' + (matched.displayName || matched.name)))
+        }
+        i += 1 + matched.name.length
+        continue
+      }
+    }
+    const head = text[i]
+    if (head === 'h' || head === 'H' || head === 'w' || head === 'W') {
+      URL_STICKY_REGEX.lastIndex = i
+      const linkMatch = URL_STICKY_REGEX.exec(text)
+      if (linkMatch) {
+        const urlText = linkMatch[0].replace(URL_TRAILING_PUNCTUATION, '')
+        if (urlText.length >= URL_MIN_LENGTH) {
+          flush()
+          const href = /^https?:\/\//i.test(urlText) ? urlText : `https://${urlText}`
+          out.push(tipLink(href, urlText))
+          i += urlText.length
+          continue
+        }
+      }
+    }
+    buffer += text[i]
+    i += 1
+  }
+  flush()
+  return out
+}
+
+// ==================== 引用消息 ====================
+
+/** 引用容器：5 种普通消息(TEXT / IMAGE / FILE / VOICE / VIDEO)都可携带 quote */
+interface Quotable {
+  quote?: QuoteMessage
+}
+
+// ==================== 消息 payload ====================
+
+/** 文本消息 payload（对齐后端 TextMessage） */
+export interface TextMessage extends Quotable {
+  content: string
+}
+
+/** 图片消息 payload（对齐后端 ImageMessage） */
+export interface ImageMessage extends Quotable {
+  url: string
+  /** 缩略图 URL */
+  thumbnailUrl?: string
+  /** 图片宽度 */
+  width?: number
+  /** 图片高度 */
+  height?: number
+  /** 文件大小（字节） */
+  size?: number
+}
+
+/** 语音消息 payload（对齐后端 AudioMessage；ImContentType 保留 VOICE 命名） */
+export interface AudioMessage extends Quotable {
+  url: string
+  /** 时长（秒） */
+  duration: number
+  /** 文件大小（字节） */
+  size?: number
+}
+
+/** 文件消息 payload（对齐后端 FileMessage） */
+export interface FileMessage extends Quotable {
+  url: string
+  name: string
+  size: number
+  /** MIME 类型 */
+  type?: string
+}
+
+/** 视频消息 payload（对齐后端 VideoMessage；暂未接入渲染） */
+export interface VideoMessage extends Quotable {
+  url: string
+  /** 封面 URL */
+  coverUrl?: string
+  /** 时长（秒） */
+  duration?: number
+  width?: number
+  height?: number
+  /** 文件大小（字节） */
+  size?: number
+}
+
+/**
+ * 名片消息 payload（对齐后端 CardMessage）
+ *
+ * 按 targetType 区分用户名片 / 群名片：
+ * - PRIVATE：targetId = 用户编号，name = 用户昵称（取真实昵称，非备注）
+ * - GROUP：targetId = 群编号，name = 群名，可带 memberCount
+ */
+export interface CardMessage extends Quotable {
+  /** 名片对象类型 */
+  targetType: ImConversationTypeValue
+  /** 目标对象编号：PRIVATE 时 = userId；GROUP 时 = groupId */
+  targetId: number
+  /** 显示名快照：PRIVATE 时 = 用户昵称；GROUP 时 = 群名 */
+  name: string
+  /** 头像（快照） */
+  avatar?: string
+  /** 群成员数（仅 targetType = GROUP；接收端展示「N 人群聊」） */
+  memberCount?: number
+}
+
+/**
+ * 名片转发的源对象（RecommendCardDialog 入参）；字段与 CardMessage 1:1，无 quote
+ */
+export type CardTarget = Omit<CardMessage, 'quote'>
+
+/** 用户对象 → 用户名片源（PRIVATE）；缺 id 返回 null 让调用方 v-bind 绑定为不渲染 */
+export function toUserCardTarget(user: null | undefined | User): CardTarget | null {
+  if (!user?.id) {
+    return null
+  }
+  return {
+    targetType: ImConversationType.PRIVATE,
+    targetId: user.id,
+    name: user.nickname || '',
+    avatar: user.avatar
+  }
+}
+
+/** 群对象 → 群名片源（GROUP）；缺 id 返回 null */
+export function toGroupCardTarget(group: GroupLite | null | undefined): CardTarget | null {
+  if (!group?.id) {
+    return null
+  }
+  return {
+    targetType: ImConversationType.GROUP,
+    targetId: group.id,
+    name: group.name || '',
+    avatar: group.showImage || group.showImageThumb,
+    memberCount: group.memberCount
+  }
+}
+
+/**
+ * 名片标签 + 图标（按 targetType 二分），统一聊天气泡 / 引用预览 / 历史摘要 / 后台预览的文案与图标
+ *
+ * 缺失 / 非法 targetType 走「个人名片」兜底，避免老消息或脏数据导致 UI 空白
+ */
+export function getCardLabelInfo(card: null | undefined | { targetType?: number }): {
+  icon: string
+  label: string
+} {
+  if (card?.targetType === ImConversationType.GROUP) {
+    return { label: '群名片', icon: 'ant-design:usergroup-outlined' }
+  }
+  return { label: '个人名片', icon: 'ant-design:user-outlined' }
+}
+
+/** 表情消息 payload（对齐后端 FaceMessage；Unicode emoji 仍走 TEXT，本类型只承载贴图 / 自定义表情包） */
+export interface FaceMessage extends Quotable {
+  /** 表情图 URL */
+  url: string
+  /** 渲染宽度（像素），避免布局抖动；可选，缺失时调用方走 CSS max-w 兜底 */
+  width?: number
+  /** 渲染高度（像素），可选 */
+  height?: number
+  /** 表情名（系统包通常有，个人表情包通常无） */
+  name?: string
+}
+
+/** 合并转发的单条内嵌消息快照（对齐后端 MergeMessage.Item） */
+export interface MergeMessageItem {
+  /** 原消息编号；仅做溯源标识 */
+  messageId: number
+  /** 发送人编号 */
+  senderId: number
+  /** 发送人昵称快照；对端可能不在原会话里，无法实时查到 */
+  senderNickname: string
+  /** 发送人头像快照 */
+  senderAvatar?: string
+  /** 内容类型，对齐 ImContentType */
+  type: number
+  /** 原消息 content（JSON）；嵌套合并消息时仍按本结构层层展开 */
+  content: string
+  /** 发送时间戳（毫秒） */
+  sendTime: number
+}
+
+/** 合并转发消息 payload（对齐后端 MergeMessage） */
+export interface MergeMessage {
+  title: string // 合并标题；例：「张三和李四的聊天记录」「群聊的聊天记录」
+  messages: MergeMessageItem[] // 内嵌的完整消息快照
+}
+
+/** 频道素材消息 payload（对齐后端 MaterialMessage） */
+export interface MaterialMessage {
+  materialId?: number
+  channelId?: number // 频道编号；转发后渲染卡片底部的频道头像 + 名称
+  title?: string
+  coverUrl?: string
+  summary?: string
+  url?: string // 跳转链接；为空时点击在客户端内置详情页按 materialId 拉 content 渲染；非空则跳 url
+}
+
+// ==================== 合并转发 payload 构造 ====================
+
+/** 单个发送人的快照昵称 / 头像 */
+interface SenderSnapshot {
+  nickname: string
+  avatar: string
+}
+
+/**
+ * 一次性构造 senderId → SenderSnapshot 映射；避免 N 条消息逐条 find 群成员
+ *
+ * 群聊从 group.members 一次性 indexBy；私聊只需 self + friend；外加全体 senderId 上做 friend 兜底
+ */
+function buildSenderSnapshotMap(
+  senderIds: number[],
+  conversation: Conversation
+): Map<number, SenderSnapshot> {
+  const userStore = useUserStore()
+  const friendStore = useFriendStore()
+  const selfUserId = getCurrentUserId()
+  const result = new Map<number, SenderSnapshot>()
+
+  let groupMembers: Map<number, { avatar?: string; nickname: string; }> | null = null
+  if (conversation.type === ImConversationType.GROUP) {
+    const group = useGroupStore().getGroup(conversation.targetId)
+    groupMembers = new Map((group?.members || []).map((m) => [m.userId, m]))
+  }
+
+  for (const senderId of senderIds) {
+    if (result.has(senderId)) {
+      continue
+    }
+    if (senderId === selfUserId) {
+      result.set(senderId, {
+        nickname: userStore.userInfo?.nickname || String(senderId),
+        avatar: userStore.userInfo?.avatar || ''
+      })
+      continue
+    }
+    const member = groupMembers?.get(senderId)
+    if (member?.nickname) {
+      result.set(senderId, { nickname: member.nickname, avatar: member.avatar || '' })
+      continue
+    }
+    const friend = friendStore.getFriend(senderId)
+    result.set(senderId, {
+      nickname: friend?.nickname || String(senderId),
+      avatar: friend?.avatar || ''
+    })
+  }
+  return result
+}
+
+/** 把单条 Message 转成 MergeMessageItem 快照；剥离 quote 防引用穿透 */
+function mapMessageToMergeItem(
+  message: Message,
+  senderSnapshots: Map<number, SenderSnapshot>
+): MergeMessageItem {
+  const snapshot = senderSnapshots.get(message.senderId)
+  return {
+    messageId: message.id || 0,
+    senderId: message.senderId,
+    senderNickname: snapshot?.nickname ?? String(message.senderId),
+    senderAvatar: snapshot?.avatar ?? '',
+    type: message.type,
+    content: removeQuotePayload(message.content),
+    sendTime: message.sendTime
+  }
+}
+
+/** 合并转发标题：私聊「{对方} 和 {自己} 的聊天记录」；群聊「{群名} 的聊天记录」 */
+export function buildMergeTitle(conversation: Conversation): string {
+  if (conversation.type === ImConversationType.GROUP) {
+    return `${conversation.name || '群聊'} 的聊天记录`
+  }
+  const myName = useUserStore().userInfo?.nickname || '我'
+  return `${conversation.name || '对方'} 和 ${myName} 的聊天记录`
+}
+
+/** 把一组 Message 打包成 MergeMessage payload；调用方负责按 sendTime 排序后传入 */
+export function buildMergeMessagePayload(
+  messages: Message[],
+  conversation: Conversation
+): MergeMessage {
+  const senderIds = messages.map((m) => m.senderId)
+  const senderSnapshots = buildSenderSnapshotMap(senderIds, conversation)
+  return {
+    title: buildMergeTitle(conversation),
+    messages: messages.map((m) => mapMessageToMergeItem(m, senderSnapshots))
+  }
+}
+
+/** 「添加到表情」的可发起源：FACE / IMAGE 都允许（GIF 图片也常被收藏） */
+export interface AddableFacePayload {
+  url: string
+  width: number
+  height: number
+  name?: string
+}
+
+/**
+ * 从消息抽取「添加到表情」的 payload；当前内容类型不可添加返回 null
+ *
+ * 调用方（MessageItem 的右键菜单）按 nullable 决定是否展示「添加到表情」入口
+ */
+export function extractAddableFace(message: Message): AddableFacePayload | null {
+  if (message.type === ImContentType.FACE) {
+    const face = parseMessage<FaceMessage>(message.content)
+    if (!face?.url) {
+      return null
+    }
+    return { url: face.url, width: face.width || 200, height: face.height || 200, name: face.name }
+  }
+  if (message.type === ImContentType.IMAGE) {
+    const image = parseMessage<ImageMessage>(message.content)
+    if (!image?.url) {
+      return null
+    }
+    return { url: image.url, width: image.width || 200, height: image.height || 200 }
+  }
+  return null
+}
+
+/** 解析消息 content（JSON 字符串）为指定 payload，非法 JSON 返回 null */
+export const parseMessage = <T>(content: string): null | T => {
+  try {
+    return JSON.parse(content) as T
+  } catch {
+    return null
+  }
+}
+
+/** 序列化消息 payload 为 content JSON 字符串；与 parseMessage 对称 */
+export const serializeMessage = <T>(payload: T): string => JSON.stringify(payload)
+
+/** `URL.createObjectURL(file)` 生成的 URL 前缀；占位 / revoke / 重传旧值识别共用 */
+export const BLOB_URL_PREFIX = 'blob:'
+
+/**
+ * 媒体 payload 里可能包含 blob URL 的字段（图片/文件/视频/语音都对齐这套 url 字段命名）
+ *
+ * 跟随 ImageMessage / VideoMessage / FileMessage / AudioMessage interface 定义同步：
+ * - url：主体资源（占位时是 blob URL，ack 后是真实 URL）
+ * - coverUrl：视频封面（commit 后是真实 URL；占位阶段不设以避免传 blob 当 poster 在部分浏览器退化）
+ * - thumbnailUrl：图片缩略图（当前未占位时使用 blob，预留）
+ */
+const MEDIA_BLOB_URL_FIELDS = ['url', 'coverUrl', 'thumbnailUrl'] as const
+
+/**
+ * 释放 content 中媒体 payload 字段上的 blob URL 内存映射
+ *
+ * 仅扫描 url / coverUrl / thumbnailUrl 三个已知字段，避免 regex 全文 grep 误伤 quote.content 里嵌套的同名 blob URL。
+ * 仅对当前 document 内创建的 blob URL 有效；IndexedDB 恢复出来的旧 blob URL 已随旧 document 失效，调它无害但无意义
+ */
+export const revokeBlobUrlsInContent = (content: string): void => {
+  if (!content || !content.includes(BLOB_URL_PREFIX)) {
+    return
+  }
+  const payload = parseMessage<Record<string, unknown>>(content)
+  if (!payload) {
+    return
+  }
+  for (const field of MEDIA_BLOB_URL_FIELDS) {
+    const value = payload[field]
+    if (typeof value === 'string' && value.startsWith(BLOB_URL_PREFIX)) {
+      URL.revokeObjectURL(value)
+    }
+  }
+}
+
+// ==================== 引用消息 helper ====================
+
+/** 把 quote 合进 payload(序列化前调用);quote 缺失时原样返回 */
+export const withQuotePayload = <T extends Quotable>(payload: T, quote?: QuoteMessage): T => {
+  if (!quote) {
+    return payload
+  }
+  return { ...payload, quote }
+}
+
+/**
+ * 从 content JSON 字符串里清掉 quote 字段
+ *
+ * 客户端乐观渲染构造 quote 时调用,避免"回复一条带引用的消息"造成 quote 嵌套滚雪球;
+ * 与后端 ImMessageUtils.removeQuote 对齐
+ */
+export const removeQuotePayload = (content: string): string => {
+  if (!content || !content.includes('"quote"')) {
+    return content
+  }
+  const parsed = parseMessage<Record<string, unknown>>(content)
+  if (!parsed || !('quote' in parsed)) {
+    return content
+  }
+  delete parsed.quote
+  return JSON.stringify(parsed)
+}
+
+/** 由 Message 派生 QuoteMessage 用于乐观渲染;ack 后会被服务端权威版本覆盖 */
+export const buildQuoteFromMessage = (message: Message): QuoteMessage => {
+  return {
+    messageId: message.id || 0,
+    senderId: message.senderId,
+    type: message.type,
+    content: removeQuotePayload(message.content)
+  }
+}
+
+/** 从已序列化 message.content 中解出 quote;非 JSON / 无 quote 返回 null */
+export const getQuoteFromMessage = (content: string): null | QuoteMessage => {
+  // 长会话每条消息渲染都走 quote computed,非引用消息字符串预扫直接返回,免一次 JSON.parse
+  if (!content || !content.includes('"quote"')) {
+    return null
+  }
+  const parsed = parseMessage<Quotable>(content)
+  return parsed?.quote ?? null
+}
+
+// ==================== 撤回 ====================
+
+/**
+ * 从后端下发的撤回 RecallMessage content 中解析出被撤回的原消息 id
+ * content 形如 `{"messageId": 123}`，若不含 messageId 则返回 0（表示这条不是撤回消息）
+ */
+export const parseRecallMessageId = (content: string): number => {
+  try {
+    const parsed = JSON.parse(content)
+    return parsed?.messageId == null ? 0 : Number(parsed.messageId)
+  } catch {
+    return 0
+  }
+}
+
+// ==================== 新消息提示音 ====================
+
+import tipAudioUrl from '#/assets/audio/im/message-tip.mp3'
+
+/**
+ * 新消息提示音，带 1 秒节流：短时间内多条消息只响一次，避免疲劳轰炸。
+ *
+ * 浏览器自动播放策略要求页面有过用户交互；若无法播放会静默失败。
+ */
+let __lastPlayAudioTipAt = 0
+let __tipAudio: HTMLAudioElement | null = null
+export const playAudioTip = () => {
+  const now = Date.now()
+  if (now - __lastPlayAudioTipAt < 1000) {
+    return
+  }
+  __lastPlayAudioTipAt = now
+  try {
+    if (!__tipAudio) {
+      __tipAudio = new Audio(tipAudioUrl)
+      __tipAudio.preload = 'auto'
+    }
+    __tipAudio.currentTime = 0
+    const playPromise = __tipAudio.play()
+    if (playPromise && typeof playPromise.catch === 'function') {
+      playPromise.catch((error) => console.debug('[IM] playAudioTip 失败', error))
+    }
+  } catch (error) {
+    console.debug('[IM] playAudioTip 失败', error)
+  }
+}
+
+// ==================== 文件图标 ====================
+
+/**
+ * 按文件扩展名挑文件图标 + 颜色，对齐微信观感
+ *
+ * message-item.vue（主气泡）和 reply-preview.vue（引用预览）共用同一份映射，避免视觉两处不一致
+ */
+export function getFileIconInfo(filename: string | undefined): { color: string; icon: string; } {
+  const ext = (filename || '').split('.').pop()?.toLowerCase() || ''
+  if (ext === 'pdf') {
+    return { icon: 'ant-design:file-pdf-filled', color: '#ed5757' }
+  }
+  if (['doc', 'docx'].includes(ext)) {
+    return { icon: 'ant-design:file-word-filled', color: '#2b7cd3' }
+  }
+  if (['xls', 'xlsx'].includes(ext)) {
+    return { icon: 'ant-design:file-excel-filled', color: '#1f7244' }
+  }
+  if (['ppt', 'pptx'].includes(ext)) {
+    return { icon: 'ant-design:file-ppt-filled', color: '#d24726' }
+  }
+  if (['7z', 'gz', 'rar', 'tar', 'zip'].includes(ext)) {
+    return { icon: 'ant-design:file-zip-filled', color: '#f0ad4e' }
+  }
+  if (['bmp', 'gif', 'jpeg', 'jpg', 'png', 'svg', 'webp'].includes(ext)) {
+    return { icon: 'ant-design:file-image-filled', color: '#9c27b0' }
+  }
+  if (['avi', 'flv', 'mkv', 'mov', 'mp4', 'wmv'].includes(ext)) {
+    return { icon: 'ant-design:video-camera-filled', color: '#9c27b0' }
+  }
+  if (['aac', 'flac', 'mp3', 'ogg', 'wav'].includes(ext)) {
+    return { icon: 'ant-design:audio-filled', color: '#9c27b0' }
+  }
+  if (['json', 'log', 'md', 'txt', 'xml'].includes(ext)) {
+    return { icon: 'ant-design:file-text-filled', color: '#909399' }
+  }
+  return { icon: 'ant-design:file-filled', color: '#909399' }
+}
+
+// ==================== 管理后台展示工具 ====================
+
+/** 详情弹窗里把 content JSON 美化成 2 缩进 */
+export const formatJson = (content?: string): string => {
+  if (!content) return ''
+  try {
+    return JSON.stringify(JSON.parse(content), null, 2)
+  } catch {
+    return content
+  }
+}
+
+// ==================== 群广播事件 payload + 文案 ====================
+
+// 群广播事件 payload；对齐后端 GroupNotificationMessage 子类聚合字段
+export type GroupNotificationPayload = {
+  addSource?: number
+  // 全群封禁
+  banned?: boolean
+  displayUserName?: string
+  // 自由进群事件
+  entrantUserId?: number
+  memberUserIds?: number[]
+  // PIN 事件携带的被置顶消息展示数据
+  message?: {
+    atUserIds?: number[]
+    content: string
+    groupId: number
+    id: number
+    receiverUserIds?: number[]
+    senderId: number
+    sendTime: string
+    type: number
+  }
+  messageId?: number
+  // 禁言事件
+  mutedUserId?: number
+  muteEndTime?: string
+  newAvatar?: string
+  newName?: string
+  newNotice?: string
+  newOwnerUserId?: number
+  oldAvatar?: string
+  oldName?: string
+  oldNotice?: string
+  operatorUserId?: number
+}
+
+/**
+ * 群广播事件 segments
+ *
+ * resolveName 由调用方注入（默认场景传 getSenderDisplayName）；
+ * operatorNameOverride 仅覆盖 operator 段文案，mention userId 仍用 payload.operatorUserId
+ */
+export function resolveGroupNotificationSegments(
+  message: { content?: string; targetId?: number; type?: number; },
+  resolveName: (userId: number) => string,
+  operatorNameOverride?: string
+): TipSegment[] {
+  let payload: GroupNotificationPayload
+  try {
+    payload = JSON.parse(message.content || '{}')
+  } catch {
+    return []
+  }
+  // ENTER 主语是 entrant 而非 operator，独立处理；其它 case 都以 operatorUserId 为主语
+  if (message.type === ImContentType.GROUP_MEMBER_ENTER) {
+    const entrantId = payload.entrantUserId ?? payload.operatorUserId
+    return entrantId ? [tipMention(entrantId, resolveName(entrantId)), tipText(' 加入了群聊')] : []
+  }
+  if (!payload.operatorUserId) {
+    return []
+  }
+  const operatorSegment = tipMention(
+    payload.operatorUserId,
+    operatorNameOverride ?? resolveName(payload.operatorUserId)
+  )
+  const memberSegments = joinMentionSegments(payload.memberUserIds || [], '、', resolveName)
+
+  switch (message.type) {
+    case ImContentType.GROUP_ADMIN_ADD: {
+      return [operatorSegment, tipText(' 将 '), ...memberSegments, tipText(' 设为管理员')]
+    }
+    case ImContentType.GROUP_ADMIN_REMOVE: {
+      return [operatorSegment, tipText(' 撤销了 '), ...memberSegments, tipText(' 的管理员身份')]
+    }
+    case ImContentType.GROUP_BANNED: {
+      return [operatorSegment, tipText(payload.banned ? ' 封禁了该群' : ' 解封了该群')]
+    }
+    case ImContentType.GROUP_CANCEL_MUTED: {
+      return [operatorSegment, tipText(' 关闭了全群禁言')]
+    }
+    case ImContentType.GROUP_CREATE: {
+      return [operatorSegment, tipText(' 创建了群聊')]
+    }
+    case ImContentType.GROUP_DISSOLVE: {
+      return [operatorSegment, tipText(' 解散了群聊')]
+    }
+    case ImContentType.GROUP_INFO_UPDATE: {
+      return payload.newAvatar
+        ? [operatorSegment, tipText(' 更换了群头像')]
+        : [operatorSegment, tipText(' 更新了群信息')]
+    }
+    case ImContentType.GROUP_MEMBER_CANCEL_MUTED: {
+      return payload.mutedUserId
+        ? [
+            operatorSegment,
+            tipText(' 解除了 '),
+            tipMention(payload.mutedUserId, resolveName(payload.mutedUserId)),
+            tipText(' 的禁言')
+          ]
+        : []
+    }
+    case ImContentType.GROUP_MEMBER_INVITE: {
+      return [operatorSegment, tipText(' 邀请 '), ...memberSegments, tipText(' 加入群聊')]
+    }
+    case ImContentType.GROUP_MEMBER_KICK: {
+      return [operatorSegment, tipText(' 移出了 '), ...memberSegments]
+    }
+    case ImContentType.GROUP_MEMBER_MUTED: {
+      return payload.mutedUserId
+        ? [
+            operatorSegment,
+            tipText(' 将 '),
+            tipMention(payload.mutedUserId, resolveName(payload.mutedUserId)),
+            tipText(' 禁言')
+          ]
+        : []
+    }
+    case ImContentType.GROUP_MEMBER_NICKNAME_UPDATE: {
+      return [operatorSegment, tipText(` 修改群昵称为 "${payload.displayUserName ?? ''}"`)]
+    }
+    case ImContentType.GROUP_MEMBER_QUIT: {
+      return [operatorSegment, tipText(' 退出了群聊')]
+    }
+    case ImContentType.GROUP_MESSAGE_PIN: {
+      return [operatorSegment, tipText(' 置顶了一条消息')]
+    }
+    case ImContentType.GROUP_MESSAGE_UNPIN: {
+      return [operatorSegment, tipText(' 取消了一条置顶消息')]
+    }
+    case ImContentType.GROUP_MUTED: {
+      return [operatorSegment, tipText(' 开启了全群禁言')]
+    }
+    case ImContentType.GROUP_NAME_UPDATE: {
+      return [operatorSegment, tipText(` 将群名修改为 "${payload.newName ?? ''}"`)]
+    }
+    case ImContentType.GROUP_NOTICE_UPDATE: {
+      return [operatorSegment, tipText(' 更新了群公告')]
+    }
+    case ImContentType.GROUP_OWNER_TRANSFER: {
+      return payload.newOwnerUserId
+        ? [
+            operatorSegment,
+            tipText(' 已将群主转让给 '),
+            tipMention(payload.newOwnerUserId, resolveName(payload.newOwnerUserId))
+          ]
+        : []
+    }
+    default: {
+      return []
+    }
+  }
+}
+
+/** 群广播事件中文文案 */
+export function resolveGroupNotificationText(
+  message: { content?: string; targetId?: number; type?: number; },
+  resolveName: (userId: number) => string,
+  operatorNameOverride?: string
+): string {
+  return segmentsToText(
+    resolveGroupNotificationSegments(message, resolveName, operatorNameOverride)
+  )
+}
+
+// ==================== 好友事件 ====================
+
+/** 会话内好友事件 segments */
+export function resolveFriendNotificationSegments(message: { type?: number }): TipSegment[] {
+  switch (message.type) {
+    case ImContentType.FRIEND_ADD: {
+      return [tipText('你们已经是好友了，开始聊天吧')]
+    }
+    case ImContentType.FRIEND_DELETE: {
+      return [tipText('你已删除好友')]
+    }
+    default: {
+      return []
+    }
+  }
+}
+
+/** 会话内好友事件文案：FRIEND_ADD / FRIEND_DELETE 渲染成灰色提示气泡，文案固定不依赖 payload */
+export function resolveFriendNotificationText(message: { type?: number }): string {
+  return segmentsToText(resolveFriendNotificationSegments(message))
+}
+
+// ==================== RTC 通话事件 ====================
+
+// RTC_CALL_START payload；仅群聊；用于聊天 tip 文案「{inviter} 发起了{voice/video}通话」
+export type RtcCallStartPayload = {
+  conversationType?: number
+  inviterAvatar?: string
+  inviterNickname?: string
+  inviterUserId?: number
+  mediaType?: number
+  room?: string
+}
+
+// RTC_CALL_END payload；私聊准气泡 + 群聊「通话已结束 [时长 X]」共用
+export type RtcCallEndPayload = {
+  conversationType?: number
+  durationSeconds?: number
+  endReason?: number
+  mediaType?: number
+  operatorAvatar?: string
+  operatorNickname?: string
+  operatorUserId?: number
+  room?: string
+}
+
+/** 解析 RTC_CALL_START / RTC_CALL_END 消息 content；解析失败返回 null */
+export function parseRtcCallPayload(
+  content?: string
+): null | (RtcCallEndPayload & RtcCallStartPayload) {
+  return content ? parseMessage<RtcCallEndPayload & RtcCallStartPayload>(content) : null
+}
+
+/**
+ * 会话内通话事件 segments（RTC_CALL_START / RTC_CALL_END）
+ * <p>
+ * 群聊两段式：START「{inviter} 发起了语音通话」+ END「语音通话已经结束」
+ * <p>
+ * 私聊气泡走 {@link resolveRtcCallPrivateBubbleText}
+ */
+export function resolveRtcCallTipSegments(message: {
+  content?: string
+  selfSend?: boolean
+  type?: number
+}): TipSegment[] {
+  const payload = parseRtcCallPayload(message.content)
+  if (!payload) {
+    return []
+  }
+  if (message.type === ImContentType.RTC_CALL_START) {
+    return payload.inviterUserId
+      ? [
+          tipMention(payload.inviterUserId, resolveRtcInviterLabel(payload)),
+          tipText(' 发起了语音通话')
+        ]
+      : []
+  }
+  if (message.type === ImContentType.RTC_CALL_END) {
+    return [tipText('语音通话已经结束')]
+  }
+  return []
+}
+
+/** 取 RTC 通话发起人展示名；昵称为空时回退「用户 {id}」 */
+function resolveRtcInviterLabel(payload: RtcCallStartPayload): string {
+  return payload.inviterNickname?.trim() || `用户 ${payload.inviterUserId ?? ''}`
+}
+
+/**
+ * 会话列表最后一条预览文案（RTC_CALL_START / RTC_CALL_END）
+ * <p>
+ * 私聊：START / END 都展示「[语音通话]」，对齐 [图片] / [语音] 风格
+ * <p>
+ * 群聊：START「{inviter} 发起了语音通话」、END「语音通话已经结束」，与聊天 tip 同源
+ */
+export function resolveRtcCallLastContent(
+  message: { content?: string; type?: number; },
+  conversationType: number
+): string {
+  if (conversationType === ImConversationType.PRIVATE) {
+    return '[语音通话]'
+  }
+  if (message.type === ImContentType.RTC_CALL_END) {
+    return '语音通话已经结束'
+  }
+  if (message.type === ImContentType.RTC_CALL_START) {
+    const payload = parseRtcCallPayload(message.content)
+    if (payload) {
+      return `${resolveRtcInviterLabel(payload)} 发起了语音通话`
+    }
+  }
+  return ''
+}
+
+/**
+ * 私聊 RTC_CALL_END 气泡内文案；按 operatorUserId 是不是自己渲染两端不同文案（对齐微信）
+ * <p>
+ * 文案规则：
+ *   HANGUP duration > 0 → 「通话时长 N」（双方一致）
+ *   HANGUP duration ≤ 0 → 「通话中断」（未接通的兜底）
+ *   CANCEL → 操作者「已取消」/ 另一方「对方已取消」
+ *   REJECT → 操作者「已拒绝」/ 另一方「对方已拒绝」
+ *   BUSY → 操作者「忙线未接听」/ 另一方「对方忙线中」
+ *   NO_ANSWER → 操作者「未接听」/ 另一方「对方未接听」（振铃超时 Job 触发）
+ *   ERROR → 「通话中断 [N]」（接通后异常断开；duration > 0 时带时长）
+ */
+export function resolveRtcCallPrivateBubbleText(payload: null | RtcCallEndPayload): string {
+  if (!payload) {
+    return '通话已结束'
+  }
+  const duration = payload.durationSeconds ?? 0
+  const hasDuration = duration > 0
+  const isOperator = payload.operatorUserId === getCurrentUserId()
+  switch (payload.endReason) {
+    case ImRtcCallEndReason.BUSY: {
+      return isOperator ? '忙线未接听' : '对方忙线中'
+    }
+    case ImRtcCallEndReason.CANCEL: {
+      return isOperator ? '已取消' : '对方已取消'
+    }
+    case ImRtcCallEndReason.ERROR: {
+      return hasDuration ? `通话中断 ${formatCallDuration(duration)}` : '通话中断'
+    }
+    case ImRtcCallEndReason.HANGUP: {
+      return hasDuration ? `通话时长 ${formatCallDuration(duration)}` : '通话中断'
+    }
+    case ImRtcCallEndReason.NO_ANSWER: {
+      return isOperator ? '未接听' : '对方未接听'
+    }
+    case ImRtcCallEndReason.REJECT: {
+      return isOperator ? '已拒绝' : '对方已拒绝'
+    }
+    default: {
+      return hasDuration ? `通话时长 ${formatCallDuration(duration)}` : '通话已结束'
+    }
+  }
+}
+
+/** 会话内通话事件文案 */
+export function resolveRtcCallTipText(message: {
+  content?: string
+  selfSend?: boolean
+  type?: number
+}): string {
+  return segmentsToText(resolveRtcCallTipSegments(message))
+}
+
+/**
+ * RTC_CALL_END 结束原因兜底文案；前端 toast / console 兜底用
+ * <p>
+ * 缺 operator 信息（同步响应 + WS push 兜底场景）时的通用文案；细分文案（按发送方视角）走 {@link resolveRtcCallPrivateBubbleText}
+ */
+export function resolveCallEndReasonText(reason: number | undefined): string {
+  switch (reason) {
+    case ImRtcCallEndReason.BUSY: {
+      return '对方忙线中'
+    }
+    case ImRtcCallEndReason.CANCEL: {
+      return '对方已取消'
+    }
+    case ImRtcCallEndReason.ERROR: {
+      return '通话异常'
+    }
+    case ImRtcCallEndReason.HANGUP: {
+      return '通话已结束'
+    }
+    case ImRtcCallEndReason.REJECT: {
+      return '对方已拒绝'
+    }
+    default: {
+      return '通话已断开'
+    }
+  }
+}
diff --git a/apps/web-ele/src/views/im/utils/pull.ts b/apps/web-ele/src/views/im/utils/pull.ts
new file mode 100644
index 000000000..4e3ec11db
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/pull.ts
@@ -0,0 +1,155 @@
+import { getDb } from './db'
+
+/**
+ * IM 状态事件补偿（增量拉取）通用编排
+ *
+ * 各业务模块（好友、群、申请、读位置）共用一套 update_time + id 正向游标：
+ * 从持久化游标出发循环拉取变更并合并进本地 store，直到某页不满（没有更多），
+ * 用于 WebSocket 漏推后的兜底补偿（进入 IM、断线重连时触发）
+ */
+
+/** 增量拉取游标：上次拉到的位置 */
+export interface PullCursor {
+  lastUpdateTime?: number
+  lastId?: number
+}
+
+/** 可作为游标的拉取记录：服务端按 update_time + id 返回，客户端取最后一条推进游标 */
+interface PullRecord {
+  id: number
+  updateTime?: number
+}
+
+/** 单次拉取条数（与后端 limit 上限对齐） */
+const PULL_PAGE_SIZE = 100
+/** 单轮最多翻页数，兜底防御异常游标导致的死循环 */
+const PULL_MAX_PAGES = 100
+/** 状态事件拉取回扫窗口，覆盖同秒内旧行更新和客户端 / 服务端时钟精度差 */
+const PULL_OVERLAP_MS = 5000
+/** 消息类 minId 拉取的单轮翻页上限，兜底防御异常游标死翻；消息量可能远大于状态事件，放宽到 1000 */
+const MIN_ID_PULL_MAX_PAGES = 1000
+
+/** 读取某模块的拉取游标；无则返回空游标（首次拉全量） */
+export async function getPullCursor(key: string): Promise<PullCursor> {
+  return (await getDb().getSetting<PullCursor>(key)) ?? {}
+}
+
+/**
+ * 通用增量拉取：从持久化游标出发，循环拉取并应用变更，直到某页不满
+ *
+ * @param cursorKey 游标在 settings 里的 key（每个模块一份）
+ * @param fetchPage 按游标拉一页（调对应 pull 接口，返回 VO 列表）
+ * @param apply 把一页变更合并进本地 store；返回 false 表示本页未完全落地（如账号已切、依赖资源补拉失败），
+ *              此时不推进游标并终止本轮，避免游标越过未落地的记录、导致后续增量永久漏拉。可返回 Promise
+ */
+export async function runIncrementalPull<T extends PullRecord>(
+  cursorKey: string,
+  fetchPage: (params: { lastId?: number; lastUpdateTime?: number; limit: number }) => Promise<T[]>,
+  apply: (records: T[]) => boolean | Promise<boolean>,
+  isActive?: () => boolean
+): Promise<void> {
+  const storedCursor = await getPullCursor(cursorKey)
+  const highWater = { ...storedCursor }
+  let cursor =
+    storedCursor.lastUpdateTime == null
+      ? {}
+      : { lastUpdateTime: Math.max(0, storedCursor.lastUpdateTime - PULL_OVERLAP_MS), lastId: 0 }
+  for (let page = 0; page < PULL_MAX_PAGES; page++) {
+    if (isActive && !isActive()) {
+      return
+    }
+    const list = await fetchPage({
+      lastUpdateTime: cursor.lastUpdateTime,
+      lastId: cursor.lastId,
+      limit: PULL_PAGE_SIZE
+    })
+    if (isActive && !isActive()) {
+      return
+    }
+    if (list.length > 0) {
+      // apply 未完全落地（返回 false）时直接终止：游标只能跟着已落地的数据走，否则会跳过本页记录
+      if ((await apply(list)) === false) {
+        return
+      }
+      if (isActive && !isActive()) {
+        return
+      }
+      // 推进游标到本页最后一条并持久化：下次从这里接着拉
+      const last = list[list.length - 1]
+      if (!last) {
+        return
+      }
+      if (last.updateTime == null) {
+        return
+      }
+      cursor = { lastUpdateTime: last.updateTime, lastId: last.id }
+      if (
+        highWater.lastUpdateTime == null ||
+        cursor.lastUpdateTime > highWater.lastUpdateTime ||
+        (cursor.lastUpdateTime === highWater.lastUpdateTime &&
+          cursor.lastId > (highWater.lastId ?? 0))
+      ) {
+        highWater.lastUpdateTime = cursor.lastUpdateTime
+        highWater.lastId = cursor.lastId
+        await getDb().setSetting(cursorKey, highWater)
+      }
+    }
+    // 不满一页 = 没有更多变更
+    if (list.length < PULL_PAGE_SIZE) {
+      return
+    }
+  }
+  console.warn(`[IM pull] ${cursorKey} 达到单轮翻页上限，提前结束本轮补偿`)
+}
+
+/**
+ * 消息类增量拉取通用编排：按单调 minId 游标循环翻页，直到空页或游标不再前进
+ *
+ * 与 runIncrementalPull 的区别：消息游标是单调消息 id（非 update_time + id 复合游标），且 messageMaxId 的持久化
+ * 跟随消息入库在 applyPage 内完成（messageStore），故本函数只负责「循环翻页机制」，不碰 settings，也不掺消息业务。
+ *
+ * @param initialMinId 起始游标：上次入库的最大消息 id
+ * @param pageSize     单页条数
+ * @param fetchPage    按 minId 拉一页
+ * @param applyPage    处理本页（建会话 / 分发 / 入库 + 推进 messageMaxId）；返回 false 表示本页未落地，停止且不推进游标
+ * @param isActive     每次 await 前后自检：取消 / 切账号时返回 false，丢弃本批不入库、不再翻页
+ * @param maxPages     单轮翻页上限
+ */
+export async function runMinIdPull<T extends { id?: number }>(options: {
+  applyPage: (records: T[], nextMinId?: number) => Promise<boolean> | Promise<void>
+  fetchPage: (params: { minId: number; size: number }) => Promise<T[]>
+  initialMinId: number
+  isActive?: () => boolean
+  maxPages?: number
+  pageSize: number
+}): Promise<void> {
+  const { initialMinId, pageSize, fetchPage, applyPage, isActive } = options
+  const maxPages = options.maxPages ?? MIN_ID_PULL_MAX_PAGES
+  let minId = initialMinId || 0
+  for (let page = 0; page < maxPages; page++) {
+    if (isActive && !isActive()) {
+      return
+    }
+    const list = await fetchPage({ minId, size: pageSize })
+    // 拉取期间取消 / 切账号：丢弃本批不入库，也不再翻页
+    if (isActive && !isActive()) {
+      return
+    }
+    if (!list || list.length === 0) {
+      return
+    }
+    // 本批最大消息 id 作为下次游标；无有效 id 则本批 apply 后停（无法继续翻页）
+    const validIds = list.map((record) => record.id).filter((id): id is number => id != null)
+    const nextMinId = validIds.length > 0 ? Math.max(...validIds) : undefined
+    // applyPage 返回 false：本页未落地（如入库失败），不推进游标并终止，避免漏消息
+    if ((await applyPage(list, nextMinId)) === false) {
+      return
+    }
+    // 无有效 id，或游标没前进（后端契约是 id > minId，理论不会出现）：停，防御死翻
+    if (nextMinId == null || nextMinId <= minId) {
+      return
+    }
+    minId = nextMinId
+  }
+  console.warn('[IM pull] runMinIdPull 达到单轮翻页上限，提前结束本轮')
+}
diff --git a/apps/web-ele/src/views/im/utils/time.ts b/apps/web-ele/src/views/im/utils/time.ts
new file mode 100644
index 000000000..7c5b6e83f
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/time.ts
@@ -0,0 +1,128 @@
+import dayjs from 'dayjs'
+
+// ====================================================================
+// IM 时间格式化
+// ====================================================================
+// 4 类场景，文案规则各有差异；统一走 dayjs，避免 raw Date 散点写法
+
+const WEEKDAY_NAMES_FULL = ['星期日', '星期一', '星期二', '星期三', '星期四', '星期五', '星期六']
+const WEEKDAY_NAMES_SHORT = ['周日', '周一', '周二', '周三', '周四', '周五', '周六']
+
+/**
+ * 消息列表的时间分隔条
+ *
+ * - 今天：HH:mm
+ * - 昨天：昨天 HH:mm
+ * - 一周内：周X HH:mm
+ * - 超过一周：MM-DD HH:mm
+ */
+export function formatTimeTip(timestamp: number): string {
+  if (!timestamp) {
+    return ''
+  }
+  const target = dayjs(timestamp)
+  const now = dayjs()
+  const time = target.format('HH:mm')
+  if (target.isSame(now, 'day')) {
+    return time
+  }
+  if (target.isSame(now.subtract(1, 'day'), 'day')) {
+    return `昨天 ${time}`
+  }
+  const diffDays = now.startOf('day').diff(target.startOf('day'), 'day')
+  if (diffDays >= 2 && diffDays <= 6) {
+    return `${WEEKDAY_NAMES_SHORT[target.day()]} ${time}`
+  }
+  return target.format('MM-DD HH:mm')
+}
+
+/**
+ * 会话列表里的时间（无 HH:mm 后缀，只展示日期粒度）
+ *
+ * - 今天：HH:mm
+ * - 昨天：昨天 HH:mm
+ * - 本周内（2-6 天前）：星期X
+ * - 同年其他：MM/DD
+ * - 跨年：YYYY/MM/DD
+ */
+export function formatConversationTime(timestamp: number): string {
+  if (!timestamp) {
+    return ''
+  }
+  const target = dayjs(timestamp)
+  const now = dayjs()
+  if (target.isSame(now, 'day')) {
+    return target.format('HH:mm')
+  }
+  if (target.isSame(now.subtract(1, 'day'), 'day')) {
+    return `昨天 ${target.format('HH:mm')}`
+  }
+  // 用 startOf('day') 兜底跨时间点的差值，避免接近凌晨时取到 1.x → diff 算成 1 漏掉昨天分支
+  const diffDays = now.startOf('day').diff(target.startOf('day'), 'day')
+  if (diffDays >= 2 && diffDays <= 6) {
+    return WEEKDAY_NAMES_FULL[target.day()] || ''
+  }
+  return target.year() === now.year() ? target.format('MM/DD') : target.format('YYYY/MM/DD')
+}
+
+/**
+ * 历史消息搜索列表的时间：展示绝对日期
+ *
+ * - 同年：M月D日 HH:mm
+ * - 跨年：YYYY年M月D日 HH:mm
+ */
+export function formatHistoryTime(timestamp: number): string {
+  if (!timestamp) {
+    return ''
+  }
+  const target = dayjs(timestamp)
+  return target.year() === dayjs().year()
+    ? target.format('M月D日 HH:mm')
+    : target.format('YYYY年M月D日 HH:mm')
+}
+
+/** 合并消息详情列表里每行的时间：MM-DD HH:mm */
+export function formatMergeItemTime(timestamp: number): string {
+  if (!timestamp) {
+    return ''
+  }
+  return dayjs(timestamp).format('MM-DD HH:mm')
+}
+
+/** RTC 通话时长（秒）→ "00:06" / "1:23:45" */
+export function formatCallDuration(seconds: number | undefined): string {
+  const total = Math.max(0, Math.floor(seconds || 0))
+  const h = Math.floor(total / 3600)
+  const m = Math.floor((total % 3600) / 60)
+  const s = total % 60
+  const pad = (n: number) => String(n).padStart(2, '0')
+  return h > 0 ? `${h}:${pad(m)}:${pad(s)}` : `${pad(m)}:${pad(s)}`
+}
+
+/** 秒数格式化为 mm:ss */
+export function formatSeconds(seconds?: number): string {
+  const value = Math.max(0, Number(seconds || 0))
+  const minute = Math.floor(value / 60)
+  const second = Math.floor(value % 60)
+  return `${minute.toString().padStart(2, '0')}:${second.toString().padStart(2, '0')}`
+}
+
+/** 格式化日期 */
+export function formatDate(
+  date?: Date | number | string,
+  format = 'YYYY-MM-DD HH:mm:ss'
+) {
+  return dayjs(date).format(format)
+}
+
+/** 接通到结束的通话时长；任一时间缺失返回 '-' */
+export function resolveCallDuration(
+  acceptTime: Date | string | undefined,
+  endTime: Date | string | undefined
+): string {
+  if (!acceptTime || !endTime) {
+    return '-'
+  }
+  const seconds = Math.floor((new Date(endTime).getTime() - new Date(acceptTime).getTime()) / 1000)
+  return seconds > 0 ? formatCallDuration(seconds) : '-'
+}
diff --git a/apps/web-ele/src/views/im/utils/user.ts b/apps/web-ele/src/views/im/utils/user.ts
new file mode 100644
index 000000000..b614b82b0
--- /dev/null
+++ b/apps/web-ele/src/views/im/utils/user.ts
@@ -0,0 +1,367 @@
+// ====================================================================
+// IM 用户展示 utility
+// ====================================================================
+// 职责：统一回答"某个用户在 UI 上应该如何展示"，包含：
+// 1. 显示名（getFriendDisplayName / getMemberDisplayName / getGroupDisplayName / getSenderDisplayName 等）
+// 2. 上下文感知名（tryGetSenderDisplayName / getSenderRealNickname）：渲染时按 conversation 上下文实时查 friendStore / groupStore / userStore，让备注 / 群昵称 / 真实昵称变更后所有历史消息立即响应式刷新
+// 3. 性别图标 / 颜色（getGenderIcon / getGenderColor）：男蓝、女粉，未知不展示，所有 UserInfo 卡片 / 列表行共用
+//
+// 命名约定：显示名相关函数一律使用 displayName，与 friend.displayName / member.displayUserName 字段对齐
+// ====================================================================
+
+import type { Conversation, Friend, Group, User } from '../home/types'
+
+import { CommonStatusEnum } from '@vben/constants'
+import { useUserStore } from '@vben/stores'
+
+import { getCurrentUserId } from '#/views/im/utils/auth'
+
+import { useConversationStore } from '../home/store/conversationStore'
+import { useFriendStore } from '../home/store/friendStore'
+import { useGroupStore } from '../home/store/groupStore'
+import { useImUiStore } from '../home/store/uiStore'
+import {
+  IM_AT_ALL_NICKNAME,
+  IM_AT_ALL_USER_ID,
+  ImConversationType,
+  ImFriendAddSource
+} from './constants'
+import { type MentionCandidate } from './message'
+
+const SystemUserSexEnum = {
+  FEMALE: 2,
+  MALE: 1,
+  UNKNOWN: 0
+} as const
+
+// 候选缺失场景的稳定空数组；让 textMentions computed 在非 TEXT / 非群聊 / 无 @ 时返回同一引用，
+// MessageBubble 的 textSegments 才不会跟着无谓重算
+const EMPTY_MENTIONS: MentionCandidate[] = []
+
+/**
+ * 是否历史退群群：joinStatus 为 DISABLE（已退群 / 被移除）
+ *
+ * /im/group/list 会带回历史退群群（供展示历史消息的群名 / 头像）；这类群应禁止发送、隐藏群操作入口、不可被转发 / 推荐选中
+ */
+export function isGroupQuit(group?: Group | null): boolean {
+  return group?.joinStatus === CommonStatusEnum.DISABLE
+}
+
+/**
+ * 私聊好友显示名：备注 > 真实昵称
+ *
+ * displayName 是「我对这个人的私人称呼」属于我的数据，删好友（DISABLE）也保留；删了再加回来时备注自然延续，历史消息里仍以备注辨识
+ */
+export function getFriendDisplayName(friend: Pick<Friend, 'displayName' | 'nickname'>): string {
+  return friend.displayName || friend.nickname
+}
+
+/**
+ * 群成员显示名：好友备注 > 用户群备注（displayUserName） > 真实昵称
+ *
+ * WeChat 优先级：好友备注是"我"对该成员的私人称呼，最高优先；其次是 ta 在群内自定义昵称；最后真实昵称兜底；调用方拿到 friend 才传入，没拿到（陌生人）就只用 member 字段降级
+ */
+export function getMemberDisplayName(
+  member: { displayUserName?: string; nickname: string },
+  friend?: null | Pick<Friend, 'displayName'>
+): string {
+  return friend?.displayName || member.displayUserName || member.nickname
+}
+
+/** 群显示名：当前用户对该群的备注（groupRemark） > 群名（name） */
+export function getGroupDisplayName(group: Pick<Group, 'groupRemark' | 'name'>): string {
+  return group.groupRemark || group.name
+}
+
+/**
+ * 消息发送者显示名（严格版）：算不出真名返回 undefined
+ *
+ * 给需要"是否真名"信号的调用方用——比如 conversationStore 决定要不要写 lastSenderDisplayName 快照、要不要触发 fetchGroupMemberList 兜底拉成员
+ *
+ * GROUP 场景下 member 已就位优先 displayUserName / 好友备注 / 真实昵称；member 缺失时区分两种 sender：
+ * - self → 直接拿 userStore.nickname 兜底（本端永远知道自己的昵称，不需要 fetch；同时避免 self 退群后 GROUP_MEMBER_QUIT 通知触发兜底拉成员 → 403）
+ * - 其他人 → 返回 undefined，让 deriveLastSenderDisplayName 走兜底拉成员
+ */
+export function tryGetSenderDisplayName(
+  senderId: number,
+  conversationType: number,
+  conversationTargetId: number
+): string | undefined {
+  if (conversationType === ImConversationType.GROUP) {
+    const group = useGroupStore().getGroup(conversationTargetId)
+    const member = group?.members?.find((m) => m.userId === senderId)
+    if (member) {
+      const friend = useFriendStore().getFriend(senderId)
+      return getMemberDisplayName(member, friend)
+    }
+    if (senderId === getCurrentUserId()) {
+      return useUserStore().userInfo?.nickname || undefined
+    }
+    return undefined
+  }
+
+  // PRIVATE / 未知会话类型：self 走 userStore，对方走 friend
+  if (senderId === getCurrentUserId()) {
+    return useUserStore().userInfo?.nickname || undefined
+  }
+  if (conversationType === ImConversationType.PRIVATE) {
+    const friend = useFriendStore().getFriend(senderId)
+    return friend ? getFriendDisplayName(friend) : undefined
+  }
+  return undefined
+}
+
+/**
+ * 消息发送者显示名：渲染时实时算，按 WeChat 优先级
+ *
+ * - 自己：userStore.nickname
+ * - 私聊对方：好友备注 > 真实昵称
+ * - 群聊对方：好友备注 > 群备注（displayUserName） > 真实昵称
+ * - 查不到：fallbackName || (self 走 userStore.nickname) || String(senderId)
+ */
+export function getSenderDisplayName(
+  senderId: number,
+  conversationType: number,
+  conversationTargetId: number,
+  fallbackName?: string
+): string {
+  const real = tryGetSenderDisplayName(senderId, conversationType, conversationTargetId)
+  if (real) {
+    return real
+  }
+  if (fallbackName) {
+    return fallbackName
+  }
+  // self 在 GROUP members 没加载时，至少用真实昵称兜底渲染（比 String(senderId) 友好）；兜底拉成员由 conversationStore 触发，回来后 try 版本能命中真名自然刷新
+  const userStore = useUserStore()
+  if (senderId === getCurrentUserId()) {
+    return userStore.userInfo?.nickname || String(senderId)
+  }
+  return String(senderId)
+}
+
+/**
+ * 消息发送者「真实昵称」：永远是 nickname，不掺备注
+ *
+ * - 自己：userStore.nickname
+ * - 私聊对方：friend.nickname
+ * - 群聊对方：member.nickname
+ *
+ * 专给 UserAvatar 的 :name 用——色卡首字母 / alt 文本要保证同一个人在所有界面一致，不跟备注变
+ */
+export function getSenderRealNickname(
+  senderId: number,
+  conversationType: number,
+  conversationTargetId: number
+): string {
+  const userStore = useUserStore()
+  const selfUserId = getCurrentUserId()
+
+  // 群聊先走 member.nickname（self 也是 member），异常时再走 self / senderId 兜底
+  if (conversationType === ImConversationType.GROUP) {
+    const group = useGroupStore().getGroup(conversationTargetId)
+    const member = group?.members?.find((m) => m.userId === senderId)
+    if (member?.nickname) {
+      return member.nickname
+    }
+    if (senderId === selfUserId) {
+      return userStore.userInfo?.nickname || String(senderId)
+    }
+    return String(senderId)
+  }
+
+  if (conversationType === ImConversationType.PRIVATE) {
+    if (senderId === selfUserId) {
+      return userStore.userInfo?.nickname || String(senderId)
+    }
+    const friend = useFriendStore().getFriend(senderId)
+    return friend?.nickname || String(senderId)
+  }
+
+  if (senderId === selfUserId) {
+    return userStore.userInfo?.nickname || String(senderId)
+  }
+  return String(senderId)
+}
+
+/**
+ * 消息发送者头像；按 conversation 上下文实时查 group.members / friend / userStore
+ *
+ * - 自己：userStore.avatar
+ * - 私聊对方：friend.avatar
+ * - 群聊对方：先 member.avatar，缺则降级 friend.avatar
+ * - 查不到：返回空串，调用方走 UserAvatar 色卡兜底
+ */
+export function getSenderAvatar(
+  senderId: number,
+  conversationType: number,
+  conversationTargetId: number
+): string {
+  const userStore = useUserStore()
+  if (senderId === getCurrentUserId()) {
+    return userStore.userInfo?.avatar || ''
+  }
+  if (conversationType === ImConversationType.GROUP) {
+    const group = useGroupStore().getGroup(conversationTargetId)
+    const member = group?.members?.find((m) => m.userId === senderId)
+    if (member?.avatar) {
+      return member.avatar
+    }
+  }
+  return useFriendStore().getFriend(senderId)?.avatar || ''
+}
+
+/**
+ * 群消息 @ mention 候选：按 atUserIds 反查群成员，name 收集所有可能字面量（含好友备注 / 群自定义昵称），displayName 统一指向真实昵称
+ *
+ * 同字面量被多 userId 共享时标记 ambiguous，由 parser 整段吃成普通文本；
+ * 直接剔除会让短前缀候选（如「@张」）抢吃「@张三」的前缀，错绑到唯一的「张」用户
+ */
+export function getMentionCandidates(
+  atUserIds: number[] | undefined,
+  conversation: null | Pick<Conversation, 'targetId' | 'type'> | undefined
+): MentionCandidate[] {
+  if (!atUserIds || atUserIds.length === 0) {
+    return EMPTY_MENTIONS
+  }
+  if (!conversation || conversation.type !== ImConversationType.GROUP) {
+    return EMPTY_MENTIONS
+  }
+  // 群成员预建 Map，避免每个 atUserId 走一次 array find（@全体成员场景下成员数 × atUserIds 是 N²）
+  const members = useGroupStore().getGroup(conversation.targetId)?.members || []
+  const memberById = new Map(members.map((m) => [m.userId, m]))
+  const friendStore = useFriendStore()
+  const candidates: MentionCandidate[] = []
+  const seen = new Set<string>()
+  for (const userId of atUserIds) {
+    // @全体成员是虚拟伪成员，userId = -1 在 group.members 里查不到，注入字面量「所有人」候选
+    if (userId === IM_AT_ALL_USER_ID) {
+      const key = `${IM_AT_ALL_USER_ID}#${IM_AT_ALL_NICKNAME}`
+      if (!seen.has(key)) {
+        seen.add(key)
+        candidates.push({
+          userId: IM_AT_ALL_USER_ID,
+          name: IM_AT_ALL_NICKNAME,
+          displayName: IM_AT_ALL_NICKNAME
+        })
+      }
+      continue
+    }
+    const member = memberById.get(userId)
+    const friend = friendStore.getFriend(userId)
+    const nickname = (member?.nickname || friend?.nickname || '').trim()
+    if (!nickname) {
+      continue
+    }
+    for (const literal of [nickname, friend?.displayName, member?.displayUserName]) {
+      const trimmed = (literal || '').trim()
+      if (!trimmed) {
+        continue
+      }
+      const key = `${userId}#${trimmed}`
+      if (seen.has(key)) {
+        continue
+      }
+      seen.add(key)
+      candidates.push({ userId, name: trimmed, displayName: nickname })
+    }
+  }
+  const nameCount = new Map<string, number>()
+  for (const candidate of candidates) {
+    nameCount.set(candidate.name, (nameCount.get(candidate.name) ?? 0) + 1)
+  }
+  for (const candidate of candidates) {
+    if ((nameCount.get(candidate.name) ?? 0) > 1) {
+      candidate.ambiguous = true
+    }
+  }
+  return candidates
+}
+
+/**
+ * 文本 / tip 里 mention 段点击的统一入口：派生 User 弹 UserInfoCard
+ *
+ * 头像走 getSenderAvatar；昵称取真实昵称，friend / member 都查不到时用 fallbackName 兜底（如灰条 tip 段的字面量文本）；
+ * addSource 群聊带 GROUP + 群名（用于「加为好友」的来源 + 备注弹文案），私聊降级 SEARCH；
+ * @全体成员 是广播 mention 没有具体用户实体，对齐微信 PC 不弹卡片
+ */
+export function openMentionUserInfoCardAtEvent(
+  userId: number,
+  event: MouseEvent,
+  fallbackName?: string
+): void {
+  if (userId === IM_AT_ALL_USER_ID) {
+    return
+  }
+  const conversation = useConversationStore().activeConversation
+  const isGroup = conversation?.type === ImConversationType.GROUP
+  const group = isGroup && conversation ? useGroupStore().getGroup(conversation.targetId) : undefined
+  const member = group?.members?.find((m) => m.userId === userId)
+  const friend = useFriendStore().getFriend(userId)
+  const user: User = {
+    id: userId,
+    nickname: friend?.nickname || member?.nickname || fallbackName || String(userId),
+    avatar: getSenderAvatar(userId, conversation?.type ?? 0, conversation?.targetId ?? 0)
+  }
+  useImUiStore().openUserInfoCardAtEvent(
+    user,
+    event,
+    isGroup ? ImFriendAddSource.GROUP : ImFriendAddSource.SEARCH,
+    isGroup ? group?.name || '' : ''
+  )
+}
+
+/** 性别图标；UNKNOWN / null / undefined 一律不展示，对齐微信留白 */
+export function getGenderIcon(sex?: number): string {
+  if (sex === SystemUserSexEnum.MALE) {
+    return 'mdi:human-male'
+  }
+  if (sex === SystemUserSexEnum.FEMALE) {
+    return 'mdi:human-female'
+  }
+  return ''
+}
+
+/** 性别图标主题色：男蓝、女粉 */
+export function getGenderColor(sex?: number): string {
+  if (sex === SystemUserSexEnum.MALE) {
+    return '#5b97f5'
+  }
+  if (sex === SystemUserSexEnum.FEMALE) {
+    return '#f56c92'
+  }
+  return ''
+}
+
+/** 头像色卡底色调色板（参考微信） */
+const AVATAR_BG_COLORS = ['#07C160', '#1A95FF', '#FA9D3B', '#9163E0', '#F76760', '#1ABC9C']
+
+/** 头像色卡文字：中文取首字、英文取前 2 字母大写、其他取首字大写、空名返回空串 */
+export function getAvatarText(name?: string): string {
+  const trimmed = name?.trim()
+  if (!trimmed) {
+    return ''
+  }
+  const first = trimmed.charAt(0)
+  const code = first.codePointAt(0) ?? 0
+  if (code >= 0x4E_00 && code <= 0x9F_A5) {
+    return first
+  }
+  const letters = trimmed.match(/[A-Za-z]/g)
+  if (!letters || letters.length === 0) {
+    return first.toUpperCase()
+  }
+  return letters.slice(0, 2).join('').toUpperCase()
+}
+
+/** 头像色卡底色：按 name charCode 之和取调色板色，空名走默认灰 */
+export function getAvatarBgColor(name?: string): string {
+  if (!name) {
+    return '#909399'
+  }
+  let hash = 0
+  for (let i = 0; i < name.length; i++) {
+    hash += name.codePointAt(i) ?? 0
+  }
+  return AVATAR_BG_COLORS[hash % AVATAR_BG_COLORS.length] || '#909399'
+}
diff --git a/apps/web-ele/src/views/system/user/components/select.vue b/apps/web-ele/src/views/system/user/components/select.vue
index be28ba7a9..53773adca 100644
--- a/apps/web-ele/src/views/system/user/components/select.vue
+++ b/apps/web-ele/src/views/system/user/components/select.vue
@@ -7,7 +7,7 @@ import { CircleX, Search } from '@vben/icons';
 
 import { ElInput, ElTooltip } from 'element-plus';
 
-import { getUser } from '#/api/system/user';
+import { getUserList } from '#/api/system/user';
 
 import UserSelectDialog from './select-dialog.vue';
 
@@ -17,56 +17,84 @@ const props = withDefaults(
   defineProps<{
     clearable?: boolean;
     disabled?: boolean;
-    modelValue?: number;
+    modelValue?: null | number | number[];
+    multiple?: boolean;
     placeholder?: string;
   }>(),
   {
     clearable: true,
     disabled: false,
     modelValue: undefined,
+    multiple: false,
     placeholder: '请选择用户',
   },
 );
 
 const emit = defineEmits<{
-  change: [item: SystemUserApi.User | undefined];
-  'update:modelValue': [value: number | undefined];
+  change: [item: SystemUserApi.User | SystemUserApi.User[] | undefined];
+  'update:modelValue': [value: number | number[] | undefined];
 }>();
 
 const attrs = useAttrs();
 const dialogRef = ref<InstanceType<typeof UserSelectDialog>>();
 const hovering = ref(false);
-const selectedItem = ref<SystemUserApi.User>();
+const selectedItems = ref<SystemUserApi.User[]>([]);
 
-const displayLabel = computed(
-  () => selectedItem.value?.nickname ?? selectedItem.value?.username ?? '',
+const displayLabel = computed(() =>
+  selectedItems.value
+    .map((item) => item.nickname || item.username || item.id)
+    .join('、'),
 );
 
 const showClear = computed(
-  () =>
-    props.clearable &&
-    !props.disabled &&
-    hovering.value &&
-    props.modelValue !== null,
+  () => props.clearable && !props.disabled && hovering.value && hasValue(),
 );
 
-/** 根据编号单条查询用户信息（用于编辑回显） */
-async function resolveItemById(id: number | undefined) {
-  if (!id) {
-    selectedItem.value = undefined;
-    return;
+/** 获取已选用户编号 */
+function getSelectedIds(value: null | number | number[] | undefined) {
+  if (Array.isArray(value)) {
+    return props.multiple ? value : value.slice(0, 1);
   }
-  if (selectedItem.value?.id === id) {
-    return;
-  }
-  selectedItem.value = await getUser(id);
+  return value === null || value === undefined ? [] : [value];
 }
 
-watch(() => props.modelValue, resolveItemById, { immediate: true });
+/** 是否已有选中值 */
+function hasValue() {
+  return getSelectedIds(props.modelValue).length > 0;
+}
+
+/** 根据编号查询用户信息（用于编辑回显） */
+async function resolveItemsById(value: null | number | number[] | undefined) {
+  const ids = getSelectedIds(value);
+  if (ids.length === 0) {
+    selectedItems.value = [];
+    return;
+  }
+  if (
+    selectedItems.value.length === ids.length &&
+    selectedItems.value.every(
+      (item) => item.id !== undefined && ids.includes(item.id),
+    )
+  ) {
+    return;
+  }
+  const userList = await getUserList(ids);
+  const userMap = new Map(userList.map((item) => [item.id, item]));
+  selectedItems.value = ids
+    .map((id) => userMap.get(id))
+    .filter((item): item is SystemUserApi.User => !!item);
+}
+
+watch(() => props.modelValue, resolveItemsById, { deep: true, immediate: true });
 
 /** 清空已选用户 */
 function clearSelected() {
-  selectedItem.value = undefined;
+  selectedItems.value = [];
+  if (props.multiple) {
+    emit('update:modelValue', []);
+    emit('change', []);
+    return;
+  }
   emit('update:modelValue', undefined);
   emit('change', undefined);
 }
@@ -82,19 +110,29 @@ function handleClick(event: MouseEvent) {
     clearSelected();
     return;
   }
-  const selectedIds = (
-    props.modelValue === null ? [] : [props.modelValue]
-  ) as number[];
-  dialogRef.value?.open(selectedIds, { multiple: false });
+  dialogRef.value?.open(getSelectedIds(props.modelValue), {
+    multiple: props.multiple,
+  });
 }
 
 /** 弹窗选中回调 */
 function handleSelected(rows: SystemUserApi.User[]) {
-  const item = rows[0];
-  if (!item) {
+  if (rows.length === 0) {
     return;
   }
-  selectedItem.value = item;
+  if (props.multiple) {
+    selectedItems.value = rows;
+    emit(
+      'update:modelValue',
+      rows
+        .map((item) => item.id)
+        .filter((id): id is number => id !== undefined),
+    );
+    emit('change', rows);
+    return;
+  }
+  const item = rows[0]!;
+  selectedItems.value = [item];
   emit('update:modelValue', item.id);
   emit('change', item);
 }
@@ -109,12 +147,19 @@ function handleSelected(rows: SystemUserApi.User[]) {
     @mouseenter="hovering = true"
     @mouseleave="hovering = false"
   >
-    <ElTooltip :disabled="!selectedItem" placement="top" :show-after="500">
+    <ElTooltip :disabled="selectedItems.length === 0" placement="top" :show-after="500">
       <template #content>
-        <div v-if="selectedItem" class="leading-6">
-          <div>用户名称：{{ selectedItem.username || '-' }}</div>
-          <div>用户昵称：{{ selectedItem.nickname || '-' }}</div>
-          <div>手机号码：{{ selectedItem.mobile || '-' }}</div>
+        <div v-if="selectedItems.length > 0" class="flex gap-3">
+          <div
+            v-for="selectedItem in selectedItems"
+            :key="selectedItem.id"
+            class="leading-6"
+          >
+            <div>用户名称：{{ selectedItem.username || '-' }}</div>
+            <div>用户昵称：{{ selectedItem.nickname || '-' }}</div>
+            <div>部门：{{ selectedItem.deptName || '-' }}</div>
+            <div>手机号码：{{ selectedItem.mobile || '-' }}</div>
+          </div>
         </div>
       </template>
       <ElInput