# AIChatController 交互流程图

## 1. AI流式问答流程 (/ai/chat/stream)

### 1.1 流程图

```mermaid
flowchart TD
    A[开始: 用户发起AI问答] --> B{用户已登录?}
    B -->|否| C[返回错误: 用户未登录]
    B -->|是| D{用户信息获取成功?}
    D -->|否| E[返回错误: 用户信息获取失败]
    D -->|是| F[获取部门信息]
    F --> G[获取用户可访问知识库]
    G --> H{知识库列表为空?}
    H -->|是| I[返回错误: 没有可用的知识库]
    H -->|否| J[获取或生成session_id]
    J --> K[从数据库获取历史记录]
    K --> L[调用AI服务进行流式问答]
    L --> M[返回SseEmitter流式响应]
    C --> N[结束]
    E --> N
    I --> N
    M --> N
```

### 1.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant AI as AIChatController
    participant Auth as AuthService
    participant Dept as DepartmentService
    participant KB as KnowledgeBasePathService
    participant Chat as ChatService
    participant AIChat as AiChatService

    Client->>+AI: POST /ai/chat/stream
    AI->>+Auth: validateToken(token)
    Auth-->>-AI: User对象

    AI->>+Dept: getDepartmentById(deptId)
    Dept-->>-AI: Department

    AI->>+KB: getUserAccessibleKnowledgeBaseNames(userId, deptId, deptCode)
    KB-->>-AI: List<String> collections

    alt 知识库为空
        AI-->>Client: 错误: 没有可用的知识库
    end

    AI->>+Chat: getSessionMessagesAsHistory(sessionId)
    Chat-->>-AI: List<HistoryItem>

    AI->>+AIChat: streamFromRagService(request, userId, deptId)
    loop 流式响应
        AIChat-->>Client: SSE事件流
    end
    AIChat-->>-AI: SseEmitter

    AI-->>-Client: SseEmitter流式响应
```

### 1.3 流程说明

| 步骤 | 说明 | 代码位置 |
|------|------|----------|
| 1. 用户发起请求 | POST /ai/chat/stream | AIChatController:56 |
| 2. 验证登录状态 | 检查Authorization header | AIChatController:61-73 |
| 3. 验证用户信息 | validateToken获取用户 | AIChatController:75-87 |
| 4. 获取部门信息 | 根据deptId获取Department | AIChatController:94-104 |
| 5. 获取知识库列表 | getUserAccessibleKnowledgeBaseNames | AIChatController:106 |
| 6. 生成session_id | 无session_id时生成新的 | AIChatController:123-127 |
| 7. 获取历史记录 | getSessionMessagesAsHistory | AIChatController:134-140 |
| 8. 调用AI服务 | streamFromRagService | AIChatController:145 |

---

## 2. 获取用户会话列表 (/ai/sessions)

### 2.1 流程图

```mermaid
flowchart TD
    A[开始: 获取会话列表] --> B{用户已登录?}
    B -->|否| C[返回: success=false, 用户未登录]
    B -->|是| D[获取用户所有会话]
    D --> E[实现简单分页]
    E --> F[返回会话列表及分页信息]
    C --> G[结束]
    F --> G
```

### 2.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant AI as AIChatController
    participant Auth as AuthService
    participant Chat as ChatService

    Client->>+AI: GET /ai/sessions
    AI->>+Auth: validateToken(token)
    Auth-->>-AI: User对象

    AI->>+Chat: getUserSessions(userId)
    Chat-->>-AI: List<ChatSession>

    Note over AI: 实现简单分页<br/>计算start/end

    AI-->>-Client: 返回会话列表及分页信息
```

### 2.3 流程说明

| 步骤 | 说明 | 代码位置 |
|------|------|----------|
| 1. 用户发起请求 | GET /ai/sessions | AIChatController:163 |
| 2. 验证登录状态 | getCurrentUserId | AIChatController:170-175 |
| 3. 获取会话列表 | chatService.getUserSessions | AIChatController:177 |
| 4. 分页处理 | 计算start/end | AIChatController:179-185 |
| 5. 返回结果 | 返回data/total/page等信息 | AIChatController:187-192 |

---

## 3. 获取会话详情 (/ai/session/{sessionId})

### 3.1 流程图

```mermaid
flowchart TD
    A[开始: 获取会话详情] --> B{用户已登录?}
    B -->|否| C[返回: 用户未登录]
    B -->|是| D[获取用户所有会话]
    D --> E{会话属于当前用户?}
    E -->|否| F[返回: 无权访问该会话]
    E -->|是| G[获取会话消息列表]
    G --> H[实现简单分页]
    H --> I[返回会话详情及分页信息]
    C --> J[结束]
    F --> J
    I --> J
```

### 3.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant AI as AIChatController
    participant Auth as AuthService
    participant Chat as ChatService

    Client->>+AI: GET /ai/session/{sessionId}
    AI->>+Auth: validateToken(token)
    Auth-->>-AI: User对象

    AI->>+Chat: getUserSessions(userId)
    Chat-->>-AI: List<ChatSession>

    Note over AI: 验证会话所属权

    alt 会话不属于用户
        AI-->>Client: 错误: 无权访问该会话
    else 会话属于用户
        AI->>+Chat: getSessionMessages(sessionId)
        Chat-->>-AI: List<ChatMessage>
        Note over AI: 实现简单分页
        AI-->>-Client: 返回会话详情及分页信息
    end
```

---

## 4. 删除单个会话 (/ai/session/{sessionId})

### 4.1 流程图

```mermaid
flowchart TD
    A[开始: 删除单个会话] --> B{用户已登录?}
    B -->|否| C[返回: 用户未登录]
    B -->|是| D[获取用户所有会话]
    D --> E{会话属于当前用户?}
    E -->|否| F[返回: 无权删除该会话]
    E -->|是| G[执行删除操作]
    G --> H{删除成功?}
    H -->|是| I[返回: 删除成功]
    H -->|否| J[返回: 删除失败]
    C --> K[结束]
    F --> K
    I --> K
    J --> K
```

### 4.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant AI as AIChatController
    participant Auth as AuthService
    participant Chat as ChatService

    Client->>+AI: DELETE /ai/session/{sessionId}
    AI->>+Auth: validateToken(token)
    Auth-->>-AI: User对象

    AI->>+Chat: getUserSessions(userId)
    Chat-->>-AI: List<ChatSession>

    Note over AI: 验证会话所属权

    alt 会话不属于用户
        AI-->>Client: 错误: 无权删除该会话
    else 会话属于用户
        AI->>+Chat: deleteSession(sessionId, userId)
        Chat-->>-AI: boolean success
        alt 删除成功
            AI-->>Client: {success: true, message: "删除成功"}
        else 删除失败
            AI-->>Client: {success: false, message: "删除失败"}
        end
    end
```

---

## 5. 批量删除会话 (/ai/sessions)

### 5.1 流程图

```mermaid
flowchart TD
    A[开始: 批量删除会话] --> B{用户已登录?}
    B -->|否| C[返回: 用户未登录]
    B -->|是| D{sessionIds列表有效?}
    D -->|否| E[返回: 会话ID列表不能为空]
    D -->|是| F[获取用户所有会话]
    F --> G[提取用户会话ID集合]
    G --> H{所有会话属于用户?}
    H -->|否| I[返回: 无权删除部分会话]
    H -->|是| J[执行批量删除]
    J --> K{删除成功?}
    K -->|是| L[返回: 批量删除成功]
    K -->|否| M[返回: 批量删除失败]
    C --> N[结束]
    E --> N
    I --> N
    L --> N
    M --> N
```

### 5.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant AI as AIChatController
    participant Auth as AuthService
    participant Chat as ChatService

    Client->>+AI: DELETE /ai/sessions
    AI->>+Auth: validateToken(token)
    Auth-->>-AI: User对象

    alt sessionIds为空
        AI-->>Client: 错误: 会话ID列表不能为空
    end

    AI->>+Chat: getUserSessions(userId)
    Chat-->>-AI: List<ChatSession>

    Note over AI: 提取用户会话ID集合<br/>验证所有会话属于用户

    alt 部分会话不属于用户
        AI-->>Client: 错误: 无权删除部分会话
    else 所有会话属于用户
        AI->>+Chat: deleteSessions(sessionIds, userId)
        Chat-->>-AI: boolean success
        alt 删除成功
            AI-->>Client: {success: true, deletedCount: N}
        else 删除失败
            AI-->>Client: {success: false, message: "批量删除失败"}
        end
    end
```

---

## 6. 中断AI流式问答 (/ai/chat/stop)

### 6.1 流程图

```mermaid
flowchart TD
    A[开始: 中断AI问答] --> B{用户已登录?}
    B -->|否| C[返回: 用户未登录]
    B -->|是| D[调用sseEmitterManager.stop]
    D --> E{中断成功?}
    E -->|是| F[返回: 已中断AI回答]
    E -->|否| G[返回: 未找到活跃AI进程]
    C --> H[结束]
    F --> H
    G --> H
```

### 6.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant AI as AIChatController
    participant Auth as AuthService
    participant SSE as SseEmitterManager

    Client->>+AI: POST /ai/chat/stop
    AI->>+Auth: validateToken(token)
    Auth-->>-AI: User对象

    AI->>+SSE: stop(sessionId)
    SSE-->>-AI: boolean success

    alt 中断成功
        AI-->>Client: {success: true, message: "已中断AI回答"}
    else 中断失败
        AI-->>Client: {success: false, message: "未找到活跃的AI进程或已结束"}
    end
```

---

## 核心服务调用关系

```mermaid
flowchart LR
    subgraph Controller
        AI[AIChatController]
    end

    subgraph Service
        AS[AuthService]
        CS[ChatService]
        ACS[AiChatService]
        SS[SseEmitterManager]
        KBS[KnowledgeBasePathService]
        DS[DepartmentService]
    end

    subgraph Entity
        U[User]
        D[Department]
        CS1[ChatSession]
        CM[ChatMessage]
        CR[ChatReference]
    end

    subgraph Database
        DB[(MySQL)]
    end

    AI --> AS
    AI --> CS
    AI --> ACS
    AI --> SS
    AI --> KBS
    AI --> DS

    AS --> U
    CS --> CS1
    CS --> CM
    CS --> CR
    KBS --> DB
    DS --> U
    DS --> D
```

---

## 接口汇总

| 接口 | 方法 | 路径 | 功能 |
|------|------|------|------|
| chatStream | POST | /ai/chat/stream | AI流式问答 |
| getUserSessions | GET | /ai/sessions | 获取用户会话列表 |
| getSessionDetail | GET | /ai/session/{sessionId} | 获取会话详情 |
| getMessageReferences | GET | /ai/message/{messageId}/references | 获取消息引用 |
| getSessionReferences | GET | /ai/session/{sessionId}/references | 获取会话引用 |
| deleteSession | DELETE | /ai/session/{sessionId} | 删除单个会话 |
| deleteSessions | DELETE | /ai/sessions | 批量删除会话 |
| stopChatStream | POST | /ai/chat/stop | 中断AI流式问答 |
