# FileController 交互流程图

## 接口总览

| 接口 | 方法 | 路径 | 功能 |
|------|------|------|------|
| pageFiles | GET | /file/page | 分页查询文件 |
| getFileById | GET | /file/{id} | 查询文件详情 |
| uploadFile | POST | /file/upload | 上传文件 |
| ragStream | POST | /file/rag/stream | RAG流式问答 |
| downloadFile | GET | /file/download/{id} | 下载文件（已禁用） |
| getFileContent | GET | /file/content/{id} | 获取文件内容（已禁用） |
| getFileInfo | GET | /file/info/{id} | 获取文件详细信息 |
| deleteFile | DELETE | /file/{id} | 删除文件 |
| approveFile | POST | /file/audit/approve/{id} | 审核通过 |
| rejectFile | POST | /file/audit/reject/{id} | 审核拒绝 |
| getPendingFiles | GET | /file/audit/pending | 查询待审核文件列表 |
| updateFileInfo | PUT | /file/{id} | 更新文件信息 |

---

## 1. 分页查询文件 (/file/page)

### 1.1 流程图

```mermaid
flowchart TD
    A[开始: 分页查询文件] --> B{用户已登录?}
    B -->|否| C[返回: 用户未登录]
    B -->|是| D{用户信息获取成功?}
    D -->|否| E[返回: 用户信息获取失败]
    D -->|是| F[调用fileService.pageFiles]
    F --> G[返回分页结果]
    C --> H[结束]
    E --> H
    G --> H
```

### 1.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant FC as FileController
    participant Auth as AuthService
    participant FS as FileService

    Client->>+FC: GET /file/page
    FC->>+Auth: validateToken(token)
    Auth-->>-FC: User对象

    FC->>+FS: pageFiles(pageNum, pageSize, fileName, user)
    FS-->>-FC: PageResult<FileVO>

    FC-->>-Client: 返回分页结果
```

---

## 2. 查询文件详情 (/file/{id})

### 2.1 流程图

```mermaid
flowchart TD
    A[开始: 查询文件详情] --> B{用户已登录?}
    B -->|否| C[返回: 用户未登录]
    B -->|是| D{用户信息获取成功?}
    D -->|否| E[返回: 用户信息获取失败]
    D -->|是| F[调用fileService.getFileById]
    F --> G[返回文件详情]
    C --> H[结束]
    E --> H
    G --> H
```

### 2.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant FC as FileController
    participant Auth as AuthService
    participant FS as FileService

    Client->>+FC: GET /file/{id}
    FC->>+Auth: validateToken(token)
    Auth-->>-FC: User对象

    FC->>+FS: getFileById(id, user)
    FS-->>-FC: FileVO

    FC-->>-Client: 返回文件详情
```

---

## 3. 上传文件 (/file/upload)

### 3.1 流程图

```mermaid
flowchart TD
    A[开始: 上传文件] --> B[校验文件]
    B --> C{文件校验通过?}
    C -->|否| D[返回错误信息]
    C -->|是| E{用户已登录?}
    E -->|否| F[返回: 用户未登录]
    E -->|是| G{用户信息获取成功?}
    G -->|否| H[返回: 用户信息获取失败]
    G -->|是| I[调用fileService.uploadFile]
    I --> J{有文件描述?}
    J -->|是| K[更新文件描述]
    K --> L[返回FileVO]
    J -->|否| L[返回FileVO]
    D --> M[结束]
    F --> M
    H --> M
    L --> M
```

### 3.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant FC as FileController
    participant FU as FileUtil
    participant Auth as AuthService
    participant FS as FileService

    Client->>+FC: POST /file/upload
    FC->>+FU: validateFile(file)
    alt 文件校验失败
        FU-->>-FC: 抛出异常
        FC-->>Client: 返回错误信息
    end

    FC->>+Auth: validateToken(token)
    Auth-->>-FC: User对象

    FC->>+FS: uploadFile(file, userId, deptId, userType, targetDeptId, isPublic)
    FS-->>-FC: FileVO

    alt 有描述信息
        FC->>+FS: updateFileDescription(fileId, description)
        FS-->>-FC: void
    end

    FC-->>-Client: 返回FileVO
```

---

## 4. RAG流式问答 (/file/rag/stream)

### 4.1 流程图

```mermaid
flowchart TD
    A[开始: RAG流式问答] --> B{用户已登录?}
    B -->|否| C[返回错误: 用户未登录]
    B -->|是| D{用户信息获取成功?}
    D -->|否| E[返回错误: 用户信息获取失败]
    D -->|是| F[设置collections为public_kb]
    F --> G[生成session_id]
    G --> H[调用aiChatService.streamFromRagService]
    H --> I[返回SseEmitter流式响应]
    C --> J[结束]
    E --> J
    I --> J
```

### 4.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant FC as FileController
    participant Auth as AuthService
    participant AI as AiChatService

    Client->>+FC: POST /file/rag/stream
    FC->>+Auth: validateToken(token)
    Auth-->>-FC: User对象

    Note over FC: 设置collections<br/>collections.add("public_kb")<br/>生成session_id

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

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

---

## 5. 删除文件 (/file/{id})

### 5.1 流程图

```mermaid
flowchart TD
    A[开始: 删除文件] --> B[调用fileService.deleteFile]
    B --> C[返回成功]
```

### 5.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant FC as FileController
    participant FS as FileService

    Client->>+FC: DELETE /file/{id}
    FC->>+FS: deleteFile(id)
    FS-->>-FC: void

    FC-->>-Client: 返回成功
```

---

## 6. 审核通过文件 (/file/audit/approve/{id})

### 6.1 流程图

```mermaid
flowchart TD
    A[开始: 审核通过] --> B{用户已登录?}
    B -->|否| C[返回: 用户未登录]
    B -->|是| D{用户信息获取成功?}
    D -->|否| E[返回: 用户信息获取失败]
    D -->|是| F{有管理员权限?}
    F -->|否| G[返回: 无权限]
    F -->|是| H[调用fileService.approveFile]
    H --> I[返回成功]
    C --> J[结束]
    E --> J
    G --> J
    I --> J
```

### 6.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 管理员
    participant FC as FileController
    participant Auth as AuthService
    participant FS as FileService

    Client->>+FC: POST /file/audit/approve/{id}
    FC->>+Auth: validateToken(token)
    Auth-->>-FC: User对象

    Note over FC: 检查userType==1或userType==2

    alt 无管理员权限
        FC-->>Client: 返回: 无权限执行此操作
    else 有管理员权限
        FC->>+FS: approveFile(id, userId)
        FS-->>-FC: void
        FC-->>Client: 返回成功
    end
```

---

## 7. 审核拒绝文件 (/file/audit/reject/{id})

### 7.1 流程图

```mermaid
flowchart TD
    A[开始: 审核拒绝] --> B{用户已登录?}
    B -->|否| C[返回: 用户未登录]
    B -->|是| D{用户信息获取成功?}
    D -->|否| E[返回: 用户信息获取失败]
    D -->|是| F{有管理员权限?}
    F -->|否| G[返回: 无权限]
    F -->|是| H[调用fileService.rejectFile]
    H --> I[返回成功]
    C --> J[结束]
    E --> J
    G --> J
    I --> J
```

### 7.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 管理员
    participant FC as FileController
    participant Auth as AuthService
    participant FS as FileService

    Client->>+FC: POST /file/audit/reject/{id}
    FC->>+Auth: validateToken(token)
    Auth-->>-FC: User对象

    Note over FC: 检查userType==1或userType==2

    alt 无管理员权限
        FC-->>Client: 返回: 无权限执行此操作
    else 有管理员权限
        FC->>+FS: rejectFile(id, userId)
        FS-->>-FC: void
        FC-->>Client: 返回成功
    end
```

---

## 8. 查询待审核文件列表 (/file/audit/pending)

### 8.1 流程图

```mermaid
flowchart TD
    A[开始: 查询待审核列表] --> B{用户已登录?}
    B -->|否| C[返回: 用户未登录]
    B -->|是| D{用户信息获取成功?}
    D -->|否| E[返回: 用户信息获取失败]
    D -->|是| F{有管理员权限?}
    F -->|否| G[返回: 无权限]
    F -->|是| H[调用fileService.getPendingFiles]
    H --> I[返回分页结果]
    C --> J[结束]
    E --> J
    G --> J
    I --> J
```

### 8.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 管理员
    participant FC as FileController
    participant Auth as AuthService
    participant FS as FileService

    Client->>+FC: GET /file/audit/pending
    FC->>+Auth: validateToken(token)
    Auth-->>-FC: User对象

    Note over FC: 检查userType==1或userType==2

    alt 无管理员权限
        FC-->>Client: 返回: 无权限执行此操作
    else 有管理员权限
        FC->>+FS: getPendingFiles(pageNum, pageSize)
        FS-->>-FC: PageResult<FileVO>
        FC-->>Client: 返回分页结果
    end
```

---

## 9. 更新文件信息 (/file/{id})

### 9.1 流程图

```mermaid
flowchart TD
    A[开始: 更新文件信息] --> B{用户已登录?}
    B -->|否| C[返回: 用户未登录]
    B -->|是| D{用户信息获取成功?}
    D -->|否| E[返回: 用户信息获取失败]
    D -->|是| F[获取原文件信息]
    F --> G{文件存在?}
    G -->|否| H[返回: 文件不存在]
    G -->|是| I{isPublic变更?}
    I -->|是| J[重建文件路径]
    J --> K[移动文件到新路径]
    K --> L[更新文件信息]
    I -->|否| L[直接更新文件信息]
    L --> M[返回更新后的文件]
    C --> N[结束]
    E --> N
    H --> N
    M --> N
```

### 9.2 时序图

```mermaid
sequenceDiagram
    autonumber
    participant Client as 用户
    participant FC as FileController
    participant Auth as AuthService
    participant FS as FileService
    participant Dept as DepartmentService
    participant UM as UserMapper

    Client->>+FC: PUT /file/{id}
    FC->>+Auth: validateToken(token)
    Auth-->>-FC: User对象

    FC->>+FS: getFileEntityById(id)
    FS-->>-FC: File对象

    alt 文件不存在
        FC-->>Client: 返回: 文件不存在
    end

    alt isPublic变更
        FC->>+Dept: getDepartmentFullPath(deptId)
        Dept-->>-FC: fullPath

        Note over FC: rebuildFilePath<br/>创建新路径

        FC->>FC: Files.move移动文件

        FC->>+FS: updateFileEntity(file)
        FS-->>-FC: void
    else 仅更新描述
        FC->>+FS: updateFileEntity(file)
        FS-->>-FC: void
    end

    FC->>UM: selectById(uploadUserId)
    UM-->>FC: User

    FC->>FC: convertToVO(file)

    FC-->>-Client: 返回FileVO
```

---

## 10. 已禁用的接口

### 10.1 下载文件 (/file/download/{id})

```mermaid
flowchart TD
    A[开始: 下载文件] --> B[直接返回403 Forbidden]
```

### 10.2 获取文件内容 (/file/content/{id})

```mermaid
flowchart TD
    A[开始: 获取文件内容] --> B[直接返回错误: 文件内容获取功能已禁用]
```

---

## 核心服务调用关系

```mermaid
flowchart LR
    subgraph Controller
        FC[FileController]
    end

    subgraph Service
        FS[FileService]
        AI[AiChatService]
        DS[DepartmentService]
    end

    subgraph Util
        FU[FileUtil]
    end

    subgraph Mapper
        UM[UserMapper]
    end

    subgraph Entity
        F[File]
        U[User]
        D[Department]
        FV[FileVO]
    end

    FC --> FS
    FC --> AI
    FC --> DS
    FC --> FU
    FC --> UM

    FS --> F
    FS --> FV
    DS --> D
    UM --> U
```

---

## 权限说明

| 接口 | 普通用户 | 部门管理员 | 系统管理员 |
|------|---------|-----------|-----------|
| 分页查询文件 | ✅ | ✅ | ✅ |
| 查询文件详情 | ✅ | ✅ | ✅ |
| 上传文件 | ✅ | ✅ | ✅ |
| RAG流式问答 | ✅ | ✅ | ✅ |
| 下载文件 | ❌ 已禁用 | ❌ 已禁用 | ❌ 已禁用 |
| 获取文件内容 | ❌ 已禁用 | ❌ 已禁用 | ❌ 已禁用 |
| 获取文件信息 | ✅ | ✅ | ✅ |
| 删除文件 | - | - | - |
| 审核通过 | ❌ | ✅ | ✅ |
| 审核拒绝 | ❌ | ✅ | ✅ |
| 查询待审核列表 | ❌ | ✅ | ✅ |
| 更新文件信息 | ✅ | ✅ | ✅ |