# 系统架构设计 — 历史会话开关功能

> 架构师：高见远（Bob）  
> 日期：2026-07-01  
> 基于 PRD v1.0 + 现有代码结构分析

---

## Part A: 系统设计

### 1. 实现方案 + 框架选型

#### 1.1 核心技术挑战

| 挑战 | 说明 | 方案 |
|------|------|------|
| 跨会话消息聚合 | 需要将同一员工的所有会话消息合并为一条时间线，按时间排序 | 后端新增按 `employee_id` 聚合查询的接口，JOIN conversations + messages 表，按 `created_at` 全局排序 |
| 分隔条主题提取 | 分隔条显示该会话中员工首条消息摘要（前20字），不新增数据库字段 | 后端在聚合查询时，对每个会话查找 `sender_type='employee'` 的最早一条消息，截取前20字作为 `conversation_summaries` 返回 |
| 游标分页（跨会话） | 向上滚动加载更多历史消息，需跨会话游标分页 | 使用 `before` 参数（消息ID），后端根据该消息的 `created_at` 查询更早的消息，全局时间线分页 |
| 模式切换无闪烁 | 开关切换时正常模式↔历史模式，消息列表无缝切换 | Store 新增 `displayMessages` computed，根据 `historyMode` 返回不同数据源；前端 `v-if` 切换加载态 |
| 历史模式只读 | 历史模式下隐藏输入框、回复建议区 | ChatArea 中用 `historyMode` 控制 `ReplyBox` / `ReplySuggestArea` 的 `v-if` |
| 会话切换自动重置 | 切换会话时关闭历史模式 | Store 的 `selectConversation()` 中调用 `resetHistoryState()` |

#### 1.2 框架与库选型

| 层 | 技术 | 说明 |
|----|------|------|
| 后端 | FastAPI + SQLAlchemy 2.0 (async) | 沿用现有技术栈，新增一个 GET 接口 |
| 前端 | Vue 3 + Pinia + Element Plus | 沿用现有技术栈，新增一个组件 + Store 扩展 |
| 分页 | 游标分页（`before` 参数） | 与现有 `getMessages()` 的分页方式一致，前端向上滚动触发 |

#### 1.3 后端新接口设计

**`GET /api/employees/{employee_id}/history-messages`**

| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `employee_id` | path (str) | — | 员工企微 UserID |
| `limit` | query (int) | 50 | 每页消息数量（1~100） |
| `before` | query (str?) | null | 游标：加载此消息ID之前的消息（向上翻页） |
| `current_conversation_id` | query (str?) | null | 当前会话ID（用于标记当前会话的分隔条） |

**响应体：**
```json
{
  "code": 200,
  "data": {
    "items": [ /* Message[] — 按时间倒序（最新在前），前端 reverse 后展示 */ ],
    "has_more": true,
    "conversation_summaries": {
      "conv-uuid-1": "VPN连接不上怎么办急",
      "conv-uuid-2": "邮箱登录失败提示密码"
    }
  }
}
```

**后端查询逻辑：**
1. 查询 `conversations` 表中 `employee_id = ?` 的所有会话，获取会话ID列表
2. 查询 `messages` 表中 `conversation_id IN (会话ID列表)` 的消息
3. 如有 `before` 参数，获取该消息的 `created_at`，只查更早的消息
4. 按 `created_at DESC` 排序，取 `limit + 1` 条（多取1条判断 `has_more`）
5. 对涉及的每个会话，查询其 `sender_type='employee'` 的最早一条消息，取前20字作为摘要
6. 返回消息列表 + `has_more` + `conversation_summaries`

#### 1.4 前端组件改动方案

| 文件 | 改动类型 | 改动概述 |
|------|----------|----------|
| `UserInfoBar.vue` | 修改 | chips 区末尾（L86 备注chip之后）新增"历史会话"开关按钮，三态视觉（关闭/打开/加载中），新增 `toggle-history` emit |
| `ChatArea.vue` | 修改 | 消息列表使用 `displayMessages` 替代 `messages`；渲染时插入 `ConversationSeparator`；历史模式隐藏 `ReplyBox`/`ReplySuggestArea`；监听向上滚动触发分页 |
| `ConversationSeparator.vue` | **新增** | 会话分隔条组件，props: `summary`（首条消息摘要前20字）、`isCurrent`（是否当前会话） |
| `conversation.ts` (Store) | 修改 | 新增历史模式状态（6个 ref + 2个 computed + 4个 action） |
| `message.ts` (API) | 修改 | 新增 `getHistoryMessages()` 函数 + `HistoryMessageListData` 类型 |
| `data.ts` (Mock) | 修改 | 新增 mock 历史消息数据（开发环境 fallback） |

#### 1.5 状态管理方案（Store 新增）

**新增 State（6个 ref）：**
```typescript
historyMode: ref<boolean>(false)           // 历史模式开关
historyMessages: ref<Message[]>([])         // 历史合并时间线消息
historyLoading: ref<boolean>(false)         // 加载中状态
historyHasMore: ref<boolean>(false)         // 是否还有更多历史消息
historyConversationSummaries: ref<Record<string, string>>({}) // 会话ID→首条消息摘要
historyCursor: ref<string | null>(null)     // 分页游标（最后加载的消息ID）
```

**新增 Getters（2个 computed）：**
```typescript
displayMessages    // historyMode ? historyMessages : messages
isHistoryReadonly  // historyMode（历史模式只读）
```

**新增 Actions（4个）：**
```typescript
enableHistoryMode()      // 打开历史模式，加载初始消息
disableHistoryMode()     // 关闭历史模式，清空历史状态
loadMoreHistory()        // 向上滚动加载更多（分页）
resetHistoryState()      // 重置所有历史状态（切换会话时调用）
```

---

### 2. 文件列表及相对路径

| # | 文件路径 | 改动类型 | 改动概述 |
|---|----------|----------|----------|
| 1 | `backend/app/api/messages.py` | 修改 | 新增 `GET /employees/{employee_id}/history-messages` 路由处理函数 |
| 2 | `backend/app/services/conversation/session_query_service.py` | 修改 | 新增 `get_employee_history_messages()` 方法 |
| 3 | `backend/app/schemas/message.py` | 修改 | 新增 `HistoryMessageListResponse` Pydantic Schema |
| 4 | `frontend-agent/src/api/message.ts` | 修改 | 新增 `getHistoryMessages()` API 函数 + `HistoryMessageListData` 接口 |
| 5 | `frontend-agent/src/stores/conversation.ts` | 修改 | 新增历史模式 state/getters/actions，修改 `selectConversation` 加入重置逻辑 |
| 6 | `frontend-agent/src/mock/data.ts` | 修改 | 新增 `mockHistoryMessageData` mock 数据（开发 fallback） |
| 7 | `frontend-agent/src/components/chat/UserInfoBar.vue` | 修改 | chips 区末尾新增历史开关按钮 + `toggle-history` emit + 三态样式 |
| 8 | `frontend-agent/src/components/chat/ConversationSeparator.vue` | **新增** | 会话分隔条组件 |
| 9 | `frontend-agent/src/components/chat/ChatArea.vue` | 修改 | 消息列表切换、分隔条插入、只读模式、滚动分页、空状态提示 |

---

### 3. 数据结构和接口

#### 3.1 类图

> 详见 `docs/class-diagram.mermaid`

#### 3.2 后端 Schema（Pydantic）

```python
# backend/app/schemas/message.py — 新增

class ConversationSummary(BaseModel):
    """会话分隔条摘要信息"""
    conversation_id: str
    summary: str          # 员工首条消息前20字
    status: str           # 会话状态
    created_at: datetime  # 会话创建时间

class HistoryMessageListResponse(BaseModel):
    """历史消息列表响应（跨会话聚合）"""
    items: List[MessageResponse]                    # 消息列表（按时间倒序）
    has_more: bool                                   # 是否还有更多
    conversation_summaries: Dict[str, str]           # {conversation_id: "前20字摘要"}
```

#### 3.3 前端 TypeScript 类型定义

```typescript
// frontend-agent/src/api/message.ts — 新增

/** 历史消息列表响应（跨会话聚合） */
export interface HistoryMessageListData {
  /** 消息列表（按时间倒序，最新在前） */
  items: Message[]
  /** 是否还有更多历史消息 */
  has_more: boolean
  /** 会话ID → 首条消息摘要（前20字） */
  conversation_summaries: Record<string, string>
}
```

```typescript
// frontend-agent/src/components/chat/ConversationSeparator.vue — Props

interface ConversationSeparatorProps {
  /** 分隔条显示文本（首条消息摘要前20字） */
  summary: string
  /** 是否为当前会话（当前会话高亮显示） */
  isCurrent: boolean
}
```

---

### 4. 程序调用流程（时序图）

> 详见 `docs/sequence-diagram.mermaid`

**核心流程：**

1. **打开历史模式**：点击开关 → Store.enableHistoryMode() → API 请求 → 渲染合并时间线
2. **向上滚动加载更多**：检测滚动到顶部 → Store.loadMoreHistory() → API 请求（before游标）→ 前插消息
3. **关闭历史模式**：点击开关 → Store.disableHistoryMode() → 恢复正常消息列表
4. **切换会话重置**：selectConversation() → resetHistoryState() → historyMode=false

---

### 5. 任务列表

| 任务ID | 任务名称 | 涉及文件 | 依赖 | 优先级 |
|--------|----------|----------|------|--------|
| T01 | 后端 — 历史消息聚合接口 | `backend/app/api/messages.py`、`backend/app/services/conversation/session_query_service.py`、`backend/app/schemas/message.py` | 无 | P0 |
| T02 | 前端数据层 — API + Store + Mock | `frontend-agent/src/api/message.ts`、`frontend-agent/src/stores/conversation.ts`、`frontend-agent/src/mock/data.ts` | T01 | P0 |
| T03 | 前端组件层 — 开关 + 分隔条 + 消息列表改造 | `frontend-agent/src/components/chat/UserInfoBar.vue`、`frontend-agent/src/components/chat/ConversationSeparator.vue`（新增）、`frontend-agent/src/components/chat/ChatArea.vue` | T02 | P0 |

---

### 6. 依赖包列表

**无需新增任何第三方依赖。**

- 后端：复用现有 FastAPI + SQLAlchemy 2.0 async
- 前端：复用现有 Vue 3 + Pinia + Element Plus + Axios

---

### 7. 共享知识（跨文件约定）

#### 7.1 消息合并时间线数据结构约定

```
历史模式 displayMessages 返回的是一维 Message[] 数组（与正常模式相同的类型），
按 created_at 升序排列（最旧在前，最新在后），与正常聊天列表一致。

前端在渲染时遍历 displayMessages，当检测到相邻两条消息的 conversation_id 不同时，
在它们之间插入一个 ConversationSeparator 组件。

conversation_summaries 是一个 Record<string, string> 映射：
  key   = conversation_id
  value = 该会话中员工首条消息的前20字摘要

分隔条的 summary 从 conversation_summaries[message.conversation_id] 获取。
```

#### 7.2 分隔条组件 Props 约定

```typescript
// ConversationSeparator.vue
interface Props {
  summary: string       // 首条消息摘要（前20字），已由后端截取
  isCurrent: boolean    // 是否为当前会话（当前会话的分隔条高亮/加粗）
}
// 无 emit，纯展示组件（P1 搁置跳转功能）
```

#### 7.3 Store 状态切换约定

```
正常模式 → 历史模式：
  1. historyMode = true
  2. historyLoading = true（触发 UI loading 态）
  3. 调用 API 加载初始50条
  4. 成功后：historyMessages = data.items.reverse()，historyHasMore = data.has_more
  5. historyCursor = historyMessages[0]?.id（最旧消息ID，用于下次分页）
  6. historyLoading = false

历史模式 → 正常模式：
  1. historyMode = false
  2. 清空 historyMessages、historyConversationSummaries、historyCursor
  3. messages ref 不受影响（正常模式数据源未变）

切换会话时：
  1. resetHistoryState() — 强制 historyMode = false，清空所有历史状态
  2. 然后执行正常的 fetchMessages()
```

#### 7.4 API 响应格式约定

```
所有后端 API 响应统一使用 success_response() 包装：
{
  "code": 200,
  "data": { ... },
  "message": "success"
}

前端 apiClient 拦截器已自动解包，返回 response.data.data。
因此 getHistoryMessages() 返回的是 data 字段内容（HistoryMessageListData）。
```

#### 7.5 消息排序约定

```
后端返回：按 created_at DESC（最新在前）
前端 Store：reverse() 后存储为 ASC（最旧在前，最新在后）
前端渲染：从上到下 = 从旧到新（与正常聊天一致）
分页游标：historyCursor = 最旧消息的ID（数组第一个元素）
向上滚动：用 before=historyCursor 请求更旧的消息，prepend 到数组头部
```

#### 7.6 分隔条插入逻辑约定

```typescript
// ChatArea.vue 渲染逻辑伪代码
const renderedItems = computed(() => {
  const msgs = conversationStore.displayMessages
  const result: Array<{ type: 'separator'; data: SeparatorData } | { type: 'message'; data: Message }> = []
  let lastConvId = ''

  for (const msg of msgs) {
    if (msg.conversation_id !== lastConvId) {
      // 会话切换，插入分隔条
      result.push({
        type: 'separator',
        data: {
          summary: conversationStore.historyConversationSummaries[msg.conversation_id] || '未知会话',
          isCurrent: msg.conversation_id === conversationStore.currentConversationId,
        }
      })
      lastConvId = msg.conversation_id
    }
    result.push({ type: 'message', data: msg })
  }
  return result
})
```

---

### 8. 待明确事项

| # | 问题 | 当前假设 | 建议确认方 |
|---|------|----------|------------|
| 1 | "当前会话排在最上方"的视觉含义 | 假设为：消息按时间正序排列（旧→新，与正常聊天一致），当前会话因最新而位于列表底部（用户初始可视区域）。分隔条中当前会话高亮标记。 | 产品经理 |
| 2 | 历史模式下是否暂停消息轮询 | 假设：历史模式下暂停当前会话的消息轮询（`stopMessagePoll`），避免新消息混入历史时间线。关闭历史模式后恢复轮询。 | 产品经理 |
| 3 | 历史消息是否需要标记已读 | 假设：历史消息不触发标记已读逻辑（只读查看，不修改 is_read 状态） | 产品经理 |
| 4 | 员工无任何历史会话（仅当前会话）时的展示 | 假设：正常展示当前会话消息 + 一条当前会话的分隔条，不显示"暂无历史会话"提示 | 产品经理 |
| 5 | 分隔条中是否显示会话状态（如"已结单"） | 假设：P0 仅显示首条消息摘要，不显示状态标签。P1 可扩展。 | 产品经理 |
| 6 | 历史模式下 WebSocket 新消息推送的处理 | 假设：历史模式下收到新消息仍更新 `messages` ref（正常数据源），但不混入 `historyMessages`。关闭历史模式后即可看到。 | 架构师 |

---

### 9. 任务依赖图

```mermaid
graph TD
    T01[T01: 后端历史消息聚合接口]
    T02[T02: 前端数据层 API+Store+Mock]
    T03[T03: 前端组件层 开关+分隔条+消息列表]

    T01 --> T02
    T02 --> T03

    style T01 fill:#4CAF50,color:#fff
    style T02 fill:#2196F3,color:#fff
    style T03 fill:#FF9800,color:#fff
```

**说明：**
- T01（后端）无依赖，可最先开始
- T02（前端数据层）依赖 T01 的接口契约（URL、参数、响应格式），但可基于接口契约先行开发 mock
- T03（前端组件层）依赖 T02 的 Store API，是最终集成层