crush-level-web/docs/MessageLikeFeature.md

# 消息点赞功能实现

## 概述

本功能基于网易云信 NIM Web SDK V2 实现了聊天消息的点赞和踩功能，通过更新消息的 `serverExtension` 字段来持久化存储用户的点赞状态，使用 NIM SDK 的 `modifyMessage` API 实现服务端同步。

## 功能特性

- ✅ 支持对AI回复消息进行点赞/踩
- ✅ 简洁的状态标记：只记录用户的点赞/踩状态，不统计数量
- ✅ 视觉反馈：点赞后按钮高亮显示
- ✅ 防重复点赞：再次点击取消点赞
- ✅ 状态持久化：通过 NIM SDK 的 `serverExtension` 字段保存到云端
- ✅ 多用户支持：支持多个用户对同一消息进行独立的点赞
- ✅ 自动同步：点赞状态自动同步到所有客户端
- ✅ 轻量级：简化数据结构，减少存储空间

## 技术实现

### 1. 数据结构

#### MessageLikeStatus 枚举

```typescript
export enum MessageLikeStatus {
  None = 'none', // 未点赞/踩
  Liked = 'liked', // 已点赞
  Disliked = 'disliked', // 已踩
}
```

#### MessageServerExtension 接口（简化版）

```typescript
export interface MessageServerExtension {
  [userId: string]: MessageLikeStatus // 用户ID -> 点赞状态的直接映射
}
```

#### 工具函数

```typescript
// 解析消息的serverExtension字段
export const parseMessageServerExtension = (serverExtension?: string): MessageServerExtension

// 序列化MessageServerExtension对象
export const stringifyMessageServerExtension = (extension: MessageServerExtension): string

// 获取用户对消息的点赞状态
export const getUserLikeStatus = (message: ExtendedMessage, userId: string): MessageLikeStatus
```

### 2. 核心功能

#### NimMsgContext 扩展

在 `NimMsgContext` 中添加了 `updateMessageLikeStatus` 方法，使用 NIM SDK 的 `modifyMessage` API：

```typescript
const updateMessageLikeStatus = useCallback(
  async (conversationId: string, messageClientId: string, likeStatus: MessageLikeStatus) => {
    // 1. 获取当前登录用户ID
    const currentUserId = nim.V2NIMLoginService.getLoginUser()

    // 2. 解析当前消息的serverExtension
    const currentServerExt = parseMessageServerExtension(targetMessage.serverExtension)

    // 3. 更新用户的点赞状态（简化版）
    const newServerExt = { ...currentServerExt }
    if (likeStatus === MessageLikeStatus.None) {
      delete newServerExt[currentUserId] // 移除点赞状态
    } else {
      newServerExt[currentUserId] = likeStatus // 设置新状态
    }

    // 4. 调用NIM SDK更新消息
    const modifyResult = await nim.V2NIMMessageService.modifyMessage(targetMessage, {
      serverExtension: stringifyMessageServerExtension(newServerExt),
    })

    // 5. 更新本地状态
    addMsg(conversationId, [modifyResult.message], false)
  },
  [addMsg]
)
```

#### useMessageLike Hook

提供便捷的点赞操作方法：

```typescript
const {
  likeMessage, // 点赞消息
  dislikeMessage, // 踩消息
  cancelLikeMessage, // 取消点赞/踩
  toggleLike, // 切换点赞状态
  toggleDislike, // 切换踩状态
} = useMessageLike()
```

### 3. UI组件

#### ChatOtherTextContainer

AI消息容器组件已集成点赞功能：

- 鼠标悬停显示操作按钮
- 点赞后按钮高亮（红色）
- 踩后按钮高亮（灰色）
- 显示点赞/踩数量

## 使用方法

### 基本用法

```typescript
import { useMessageLike } from '@/hooks/useMessageLike';
import { getUserLikeStatus, MessageLikeStatus } from '@/atoms/im';
import { useNimChat } from '@/context/NimChat/useNimChat';

const MyComponent = ({ message }: { message: ExtendedMessage }) => {
  const { toggleLike, toggleDislike } = useMessageLike();
  const { nim } = useNimChat();

  // 获取当前用户的点赞状态
  const currentUserId = nim.V2NIMLoginService.getLoginUser();
  const currentStatus = getUserLikeStatus(message, currentUserId || '');

  const handleLike = async () => {
    await toggleLike(message.conversationId, message.messageClientId, currentStatus);
  };

  const handleDislike = async () => {
    await toggleDislike(message.conversationId, message.messageClientId, currentStatus);
  };

  return (
    <div>
      <button
        onClick={handleLike}
        className={currentStatus === MessageLikeStatus.Liked ? 'active' : ''}
      >
        👍
      </button>
      <button
        onClick={handleDislike}
        className={currentStatus === MessageLikeStatus.Disliked ? 'active' : ''}
      >
        👎
      </button>
    </div>
  );
};
```

### 高级用法

```typescript
// 直接设置点赞状态
await likeMessage(conversationId, messageClientId)

// 直接设置踩状态
await dislikeMessage(conversationId, messageClientId)

// 取消所有状态
await cancelLikeMessage(conversationId, messageClientId)
```

## 状态管理

点赞状态通过以下方式管理：

1. **服务端状态**: 存储在 `message.serverExtension` 字段中，通过 NIM SDK 同步到云端
2. **多用户支持**: 每个用户的点赞状态独立存储，使用用户ID作为键
3. **简化存储**: 仅存储用户的点赞状态，不计算总数，节省存储空间
4. **状态同步**: 通过 `msgListAtom` 全局状态管理，并通过 NIM SDK 自动同步到所有客户端
5. **持久化**: 点赞状态持久化存储在 NIM 服务器，不会丢失

## 扩展建议

### 1. 消息更新监听

由于使用了 NIM SDK 的 `modifyMessage` API，建议监听消息更新事件：

```typescript
// 监听消息修改事件
nim.V2NIMMessageService.on('onMessageUpdated', (messages: V2NIMMessage[]) => {
  messages.forEach((message) => {
    // 处理点赞状态更新
    const serverExt = parseMessageServerExtension(message.serverExtension)
    if (serverExt.likes) {
      console.log('消息点赞状态已更新:', message.messageClientId, serverExt)
    }
  })
})
```

### 2. 错误处理

为点赞操作添加错误处理和重试机制：

```typescript
const updateMessageLikeStatusWithRetry = async (
  conversationId: string,
  messageClientId: string,
  likeStatus: MessageLikeStatus,
  retryCount = 3
) => {
  try {
    await updateMessageLikeStatus(conversationId, messageClientId, likeStatus)
  } catch (error) {
    if (retryCount > 0) {
      console.log(`点赞失败，剩余重试次数: ${retryCount}`, error)
      await new Promise((resolve) => setTimeout(resolve, 1000)) // 等待1秒
      return updateMessageLikeStatusWithRetry(
        conversationId,
        messageClientId,
        likeStatus,
        retryCount - 1
      )
    } else {
      throw error
    }
  }
}
```

### 3. 批量操作

对于大量消息的点赞状态批量更新：

```typescript
const batchUpdateLikes = (
  updates: Array<{
    conversationId: string
    messageClientId: string
    likeStatus: MessageLikeStatus
  }>
) => {
  // 批量更新逻辑
}
```

## 注意事项

1. **性能考虑**: 点赞状态更新会触发组件重渲染，建议使用 React.memo 优化
2. **网络请求**: 每次点赞都会调用 NIM SDK 的 `modifyMessage` API，请考虑网络状况
3. **并发控制**: 快速连续点击可能导致并发请求，建议添加防抖或节流
4. **权限验证**: NIM SDK 会自动验证用户权限，无需额外处理
5. **消息类型限制**: `modifyMessage` API 仅支持特定类型的消息，请参考 NIM 文档
6. **扩展字段大小**: `serverExtension` 字段有大小限制，请合理设计数据结构

## 相关文件

- `src/atoms/im.ts` - 数据类型定义
- `src/context/NimChat/NimMsgContext.tsx` - 核心逻辑
- `src/hooks/useMessageLike.ts` - 便捷Hook
- `src/app/(main)/chat/[aiId]/components/ChatMessageItems/ChatOtherTextContainer.tsx` - UI实现