mint/dashboard-v4/documents/development/chat

聊天系统数据库设计文档

1. 项目概述

本项目旨在实现一个类似 Claude 的聊天系统，支持以下核心功能：

• 多轮对话管理
• Function Call 集成
• 消息树结构（支持消息分支和版本控制）
• 用户可修改问题并生成新的回答分支
• 支持切换不同版本的回答
• 支持更换模型重新回答同一问题
• 消息生成参数跟踪（temperature、tokens 等）

2. 核心设计理念

2.1 消息组织结构

• Chat: 每次点击"新建聊天"创建一个独立的消息树
• Session: 将相关的消息组织成会话段，前端显示为一个消息组
• Message Tree: 通过 parent_id 维护消息间的依赖关系
• Version Control: 支持同一节点的多个版本，用户可切换查看

2.2 Function Call 集成

系统支持标准的 Function Call 流程：

user → assistant(tool_calls) → tool(result) → assistant(final_response)

所有相关消息归属同一个 session，前端显示为一个完整的 AI 回复。

2.3 软删除机制

系统采用软删除策略，保护用户数据安全：

• 所有删除操作仅标记 deleted_at 字段
• 查询时默认过滤已删除数据
• 支持数据恢复和审计需求

3. 数据库表设计

3.1 chats 表（聊天会话）

存储每个独立的聊天会话。

CREATE TABLE chats (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    uid CHAR(36) NOT NULL UNIQUE COMMENT 'UUID唯一标识',
    title VARCHAR(255) NOT NULL COMMENT '聊天标题',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP NULL COMMENT '软删除时间戳',
    user_id CHAR(36) COMMENT '用户ID',

    INDEX idx_chats_uid (uid),
    INDEX idx_chats_user_id (user_id),
    INDEX idx_chats_created_at (created_at),
    INDEX idx_chats_deleted_at (deleted_at)
) COMMENT '聊天会话表';

3.2 chat_messages 表（消息节点）

存储所有消息，支持树形结构和版本控制。role=system 为消息树的唯一根节点。不可修改，不可删除。

CREATE TABLE chat_messages (
    id BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '自增主键，提供天然时间排序',
    uid CHAR(36) NOT NULL UNIQUE COMMENT 'UUID唯一标识',
    chat_id CHAR(36) NOT NULL COMMENT '关联chats.uid',
    parent_id CHAR(36) COMMENT '关联chat_messages.uid，NULL表示根节点',
    session_id CHAR(36) NOT NULL COMMENT '会话段ID，同一消息组共享',

    role ENUM('system','user', 'assistant', 'tool') NOT NULL COMMENT '消息角色',
    content TEXT COMMENT '消息内容',
    model_id CHAR(36) COMMENT '使用的模型id（assistant消息）',
    tool_calls JSON COMMENT '函数调用信息（assistant消息）',
    tool_call_id VARCHAR(100) COMMENT '工具调用ID（tool消息）',
    metadata JSON COMMENT '消息元数据：生成参数、token统计等',

    is_active BOOLEAN DEFAULT TRUE COMMENT '是否为当前激活版本',
    editor_id CHAR(36) COMMENT '最后编辑用户ID',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted_at TIMESTAMP NULL COMMENT '软删除时间戳',

    INDEX idx_messages_uid (uid),
    INDEX idx_messages_chat_id (chat_id),
    INDEX idx_messages_parent_id (parent_id),
    INDEX idx_messages_session_id (session_id),
    INDEX idx_messages_active (chat_id, is_active),
    INDEX idx_messages_deleted_at (deleted_at)
) COMMENT '聊天消息表';

4. 数据结构说明

4.1 字段详解

chats 表字段

• id: 自增主键，数据库内部使用
• uid: UUID 标识，用于外部引用和 API
• title: 聊天标题，可从首条消息自动生成
• user_id: 用户标识（可选，如果需要多用户支持）
• deleted_at: 软删除时间戳，NULL 表示未删除

chat_messages 表字段

• id: 自增主键，提供天然的消息时间顺序
• uid: UUID 标识，用于 parent_id 引用，保证跨系统稳定性
• parent_id: 指向父消息的 uid，构建技术依赖关系
• session_id: 消息组标识，相同 session_id 的消息在前端显示为一组
• role: 消息类型（user 用户/assistant 助手/tool 工具结果）
• tool_calls: JSON 格式存储函数调用信息
• tool_call_id: 关联 tool 消息到具体的函数调用
• metadata: 消息生成相关参数和统计信息
• is_active: 标记用户当前查看的版本
• deleted_at: 软删除时间戳，NULL 表示未删除

4.2 metadata 字段结构

metadata 字段存储与消息生成相关的参数和统计信息：

{
  // AI生成参数（assistant消息）
  "generation_params": {
    "temperature": 0.7,
    "max_tokens": 2048,
    "top_p": 0.9,
    "frequency_penalty": 0.0,
    "presence_penalty": 0.0
  },

  // Token使用统计
  "token_usage": {
    "prompt_tokens": 150,
    "completion_tokens": 320,
    "total_tokens": 470
  },

  // 性能指标
  "performance": {
    "response_time_ms": 1250,
    "first_token_time_ms": 450
  },

  // 工具调用统计（如适用）
  "tool_stats": {
    "total_calls": 2,
    "successful_calls": 2,
    "execution_time_ms": 340
  },

  // 其他扩展信息
  "custom_data": {}
}

4.3 消息关系说明

parent_id 关系（技术依赖）

维护 Function Call 的执行链：

user(id=1)
  ↓ parent_id=uuid1
assistant(id=2, tool_calls=[...])
  ↓ parent_id=uuid2
tool(id=3, tool_call_id=xxx)
  ↓ parent_id=uuid3
assistant(id=4, final_response)

session_id 关系（显示分组）

将相关消息组织成前端显示单元：

Session 1: [user消息]
Session 2: [assistant + tool + assistant] -> 显示为一个AI回复
Session 3: [user消息]

5. 软删除实现

5.1 删除操作

-- 软删除聊天（级联删除所有消息）
UPDATE chats SET deleted_at = CURRENT_TIMESTAMP WHERE uid = ?;
UPDATE chat_messages SET deleted_at = CURRENT_TIMESTAMP WHERE chat_id = ?;

-- 软删除单个消息
UPDATE chat_messages SET deleted_at = CURRENT_TIMESTAMP WHERE uid = ?;

5.2 查询过滤

所有业务查询都需要过滤已删除数据：

-- 查询示例
SELECT * FROM chats WHERE deleted_at IS NULL;
SELECT * FROM chat_messages WHERE deleted_at IS NULL;

5.3 数据恢复

-- 恢复聊天
UPDATE chats SET deleted_at = NULL WHERE uid = ?;

-- 恢复消息
UPDATE chat_messages SET deleted_at = NULL WHERE uid = ?;

6. 典型数据示例

6.1 Function Call 对话示例

-- Chat记录
INSERT INTO chats (id, uid, title) VALUES
(1, 'chat-uuid-1', '天气查询对话');

-- 消息记录
INSERT INTO chat_messages (id, uid, chat_id, parent_id, session_id, role, content, metadata) VALUES
-- Session 1: 用户提问
(1, 'msg-uuid-1', 'chat-uuid-1', NULL, 'session-uuid-1', 'user', '查询今天天气', NULL),

-- Session 2: AI处理流程
(2, 'msg-uuid-2', 'chat-uuid-1', 'msg-uuid-1', 'session-uuid-2', 'assistant', NULL,
 '{"generation_params":{"temperature":0.7,"max_tokens":2048},"token_usage":{"prompt_tokens":20,"completion_tokens":50,"total_tokens":70}}'),

(3, 'msg-uuid-3', 'chat-uuid-1', 'msg-uuid-2', 'session-uuid-2', 'tool', '今天晴天，25°C',
 '{"tool_stats":{"execution_time_ms":340}}'),

(4, 'msg-uuid-4', 'chat-uuid-1', 'msg-uuid-3', 'session-uuid-2', 'assistant', '今天天气晴朗，气温25度...',
 '{"generation_params":{"temperature":0.7},"token_usage":{"prompt_tokens":100,"completion_tokens":80,"total_tokens":180},"performance":{"response_time_ms":1250}}'),

-- Session 3: 用户继续提问
(5, 'msg-uuid-5', 'chat-uuid-1', 'msg-uuid-4', 'session-uuid-3', 'user', '那明天呢？', NULL);

6.2 tool_calls JSON 结构示例

[
  {
    "id": "call_123",
    "function": "get_weather",
    "arguments": {
      "city": "北京",
      "date": "today"
    }
  }
]

7. 核心业务场景

7.1 用户修改问题

1. 软删除原消息及其后续回答链
2. 创建新版本消息
3. 生成新的回答链，记录生成参数到 metadata

7.2 重新生成回答

1. 软删除当前 assistant 回答
2. 使用相同或不同的参数重新生成
3. 在 metadata 中记录新的生成参数和统计信息

7.3 消息分支管理

• 每个分支保持独立的 session_id
• 通过 parent_id 维护分支关系
• 软删除支持分支恢复

8. 常用查询模式

8.1 获取聊天的消息组列表

SELECT DISTINCT session_id, MIN(id) as first_message_id
FROM chat_messages
WHERE chat_id = ? AND is_active = true AND deleted_at IS NULL
ORDER BY first_message_id;

8.2 获取某个 session 的所有消息

SELECT * FROM chat_messages
WHERE session_id = ? AND is_active = true AND deleted_at IS NULL
ORDER BY id;

8.3 获取完整对话历史（用于 AI Context）

-- 获取当前激活路径的所有消息
WITH RECURSIVE active_path AS (
  SELECT * FROM chat_messages
  WHERE chat_id = ? AND parent_id IS NULL AND is_active = true AND deleted_at IS NULL

  UNION ALL

  SELECT m.* FROM chat_messages m
  JOIN active_path p ON m.parent_id = p.uid
  WHERE m.is_active = true AND m.deleted_at IS NULL
)
SELECT * FROM active_path ORDER BY id;

8.4 查询消息的所有版本（包含已删除）

SELECT *,
       CASE WHEN deleted_at IS NULL THEN 'active' ELSE 'deleted' END as status
FROM chat_messages
WHERE parent_id = ? AND role = ?
ORDER BY created_at;

8.5 Token 使用统计查询

-- 查询聊天的总token使用量
SELECT
    chat_id,
    SUM(JSON_EXTRACT(metadata, '$.token_usage.total_tokens')) as total_tokens,
    AVG(JSON_EXTRACT(metadata, '$.performance.response_time_ms')) as avg_response_time
FROM chat_messages
WHERE chat_id = ? AND role = 'assistant' AND deleted_at IS NULL
GROUP BY chat_id;

9. 性能优化建议

9.1 索引策略

• chat_id: 快速查询某个聊天的所有消息
• session_id: 快速获取消息组
• parent_id: 支持树形查询和兄弟节点查询
• (chat_id, is_active): 快速获取激活消息
• deleted_at: 快速过滤软删除数据

9.2 查询优化

• 使用递归 CTE 进行树形查询
• 考虑 materialized path 优化深层树查询
• 对于频繁的 session 查询，考虑适当的缓存策略
• metadata JSON 字段可根据需要创建虚拟列索引

9.3 软删除优化

• 定期清理长期删除的数据（如 30 天后物理删除）
• 考虑分区表优化查询性能
• 为 deleted_at 字段建立部分索引（仅索引非 NULL 值）

10. 扩展性考虑

10.1 多模态支持

• content 字段可存储 JSON，支持文本、图片、文件等多种内容类型
• tool_calls 可扩展支持更多函数类型
• metadata 可扩展记录多模态内容的处理参数

10.2 权限控制

• 通过 user_id 支持多用户隔离
• 可扩展支持聊天分享、协作等功能
• 软删除支持权限恢复场景

10.3 审计和监控

• created_at/updated_at 支持操作时间追踪
• deleted_at 提供删除审计
• metadata 记录详细的生成和性能数据
• 可扩展添加操作日志表记录详细变更历史

11. 注意事项

1. UUID 生成: 确保 uid 字段使用标准 UUID v4 格式
2. JSON 字段: 使用数据库原生 JSON 类型，支持索引和查询
3. 外键约束: 合理使用外键约束保证数据一致性
4. 软删除一致性: 确保级联删除的数据一致性
5. 并发控制: 在版本更新时注意并发冲突处理
6. 数据清理: 制定合理的物理删除策略，避免数据无限增长
7. 查询习惯: 所有业务查询都必须包含 deleted_at IS NULL 条件
8. JSON 索引: 根据实际查询需求为 metadata 字段创建合适的索引

---

文档版本: 1.1
创建时间: 2025-09-07
更新时间: 2025-09-09
修订说明: 增加 metadata 字段和软删除机制