kangda-robot-backend/ruoyi-fastapi-backend/doc/architecture_documentation.md

# 康达机器人系统架构文档

## 1. 系统概述

康达机器人系统是一个集机器人控制、人脸识别、门禁管理、文档检索和智能对话于一体的综合性管理平台。系统采用前后端分离架构，集成了多种外部服务和AI能力，为用户提供全面的机器人管理和控制解决方案。

## 2. 系统架构图

```mermaid
flowchart TD
    subgraph 客户端层
        Web控制台["Web控制台\n(管理界面)"]
        Pad控制端["Pad控制端\n(现场操作)"]
    end

    subgraph 后端服务层
        FastAPI["FastAPI后端服务\n(核心业务逻辑)"]
        Redis["Redis缓存\n(会话、数据缓存)"]
        Database[("数据库\n(MySQL/PostgreSQL)")]
    end

    subgraph 外部服务层
        RAGFlow["RAGFlow\n(文档检索与智能对话)"]
        SearchAPI["搜索API\n(SerpAPI)"]
        Compreface["Compreface\n(人脸识别)"]
        HaiKang["海康平台\n(门禁控制)"]
    end

    subgraph 设备层
        Robot["机器人\n(执行动作、采集数据)"]
        Door["门禁设备\n(开关控制)"]
        Camera["摄像头\n(图像采集)"]
    end

    %% 连接关系
    Web控制台 -->|HTTP请求| FastAPI
    Pad控制端 -->|HTTP请求| FastAPI
    FastAPI -->|读写数据| Database
    FastAPI -->|缓存操作| Redis
    FastAPI -->|调用接口| RAGFlow
    FastAPI -->|搜索增强| SearchAPI
    FastAPI -->|人脸识别| Compreface
    FastAPI -->|门禁控制| HaiKang
    FastAPI -->|控制指令| Robot
    HaiKang -->|控制| Door
    Camera -->|图像数据| Compreface
    Robot -->|状态反馈| FastAPI
    Door -->|状态反馈| HaiKang
    HaiKang -->|状态更新| FastAPI

    %% 大模型服务
    RAGFlow -->|调用| LLM["大语言模型\n(云上服务)"]
    SearchAPI -->|调用| SearchEngine["搜索引擎\n(第三方)"]
```

## 3. 系统组件说明

### 3.1 客户端层

#### Web控制台
- **功能**：提供系统管理、用户管理、角色管理、机器人配置、讲解内容管理等功能
- **技术**：Vue.js + Element Plus
- **访问方式**：浏览器访问

#### Pad控制端
- **功能**：现场控制机器人、查看实时状态、处理识别记录
- **技术**：Web应用（适配Pad设备）
- **访问方式**：Pad浏览器或专用应用

### 3.2 后端服务层

#### FastAPI后端服务
- **核心功能**：
  - 提供RESTful API接口
  - 处理业务逻辑
  - 集成各种外部服务
  - 权限管理与认证
  - 系统监控与日志
- **主要模块**：
  - 用户管理模块
  - 角色管理模块
  - 机器人信息管理模块
  - 机器人动作管理模块
  - 门禁设备管理模块
  - 识别记录管理模块
  - RAGFlow文档管理模块
  - 人脸识别管理模块
  - 系统统计模块

#### Redis缓存
- **功能**：
  - 会话管理
  - 数据缓存
  - 分布式锁
  - 消息队列（可选）

#### 数据库
- **功能**：存储系统配置、用户信息、机器人数据、识别记录等持久化数据
- **支持类型**：MySQL、PostgreSQL

### 3.3 外部服务层

#### RAGFlow
- **功能**：
  - 文档检索与管理
  - 智能对话（基于大语言模型）
  - 知识库管理
- **集成方式**：API调用

#### 搜索API
- **功能**：
  - 增强智能对话的搜索能力
  - 提供实时信息查询
- **技术**：SerpAPI

#### Compreface
- **功能**：
  - 人脸识别
  - 人脸比对
  - 人脸检测
- **集成方式**：API调用

#### 海康平台
- **功能**：
  - 门禁设备管理
  - 门禁状态查询
  - 门禁控制（开关门）
  - 门禁事件记录
- **集成方式**：API调用

### 3.4 设备层

#### 机器人
- **功能**：
  - 执行预设动作
  - 采集环境数据
  - 接收并执行控制指令
  - 反馈执行状态

#### 门禁设备
- **功能**：
  - 开关门控制
  - 状态反馈
  - 事件记录

#### 摄像头
- **功能**：
  - 图像采集
  - 视频监控
  - 人脸数据采集

## 4. 核心工作流程

### 4.1 用户认证流程

```mermaid
sequenceDiagram
    participant 用户 as 用户
    participant Web as Web控制台/Pad控制端
    participant FastAPI as FastAPI后端
    participant Redis as Redis缓存
    participant DB as 数据库

    用户->>Web: 输入用户名密码
    Web->>FastAPI: POST /system/user/login
    FastAPI->>DB: 查询用户信息
    DB-->>FastAPI: 返回用户数据
    FastAPI->>FastAPI: 验证密码
    FastAPI->>Redis: 生成并存储token
    Redis-->>FastAPI: 返回token
    FastAPI-->>Web: 返回token和用户信息
    Web->>Web: 存储token
```

### 4.2 门禁控制流程

```mermaid
sequenceDiagram
    participant Pad as Pad控制端
    participant FastAPI as FastAPI后端
    participant HaiKang as 海康平台API
    participant Door as 门禁设备

    Pad->>FastAPI: POST /system/door/control_door
    FastAPI->>HaiKang: 请求门禁控制
    HaiKang->>Door: 发送开关指令
    Door-->>HaiKang: 执行结果
    HaiKang-->>FastAPI: 返回控制结果
    FastAPI-->>Pad: 返回操作状态
```

### 4.3 人脸识别流程

```mermaid
sequenceDiagram
    participant Camera as 摄像头
    participant Compreface as Compreface
    participant FastAPI as FastAPI后端
    participant DB as 数据库
    participant Robot as 机器人

    Camera->>Compreface: 上传人脸图像
    Compreface->>Compreface: 检测人脸
    Compreface->>Compreface: 提取特征
    Compreface->>FastAPI: 返回识别结果
    FastAPI->>DB: 保存识别记录
    FastAPI->>Robot: 发送响应指令
    Robot-->>FastAPI: 执行结果
```

### 4.4 智能对话流程

```mermaid
sequenceDiagram
    participant User as 用户
    participant Web as Web/Pad客户端
    participant FastAPI as FastAPI后端
    participant Redis as Redis缓存
    participant RAGFlow as RAGFlow
    participant Search as 搜索API
    participant LLM as 大语言模型

    User->>Web: 输入问题
    Web->>FastAPI: POST /system/ragflow/converse_with_chat_assistant
    FastAPI->>Redis: 检查缓存
    alt 缓存命中
        Redis-->>FastAPI: 返回缓存结果
    else 缓存未命中
        FastAPI->>RAGFlow: 发送对话请求
        RAGFlow->>Search: 检查是否需要搜索增强
        alt 需要搜索增强
            Search->>SearchEngine: 执行搜索
            SearchEngine-->>Search: 返回搜索结果
            Search-->>RAGFlow: 返回搜索内容
        end
        RAGFlow->>LLM: 调用大语言模型
        LLM-->>RAGFlow: 返回生成内容
        RAGFlow-->>FastAPI: 返回对话结果
        FastAPI->>Redis: 存储结果到缓存
    end
    FastAPI-->>Web: 返回对话结果
    Web->>User: 显示回答
```

## 5. 系统集成与依赖

### 5.1 内部依赖

| 依赖名称 | 用途 | 版本 |
|---------|------|------|
| FastAPI | 后端框架 | 最新 |
| SQLAlchemy | ORM框架 | 最新 |
| Redis | 缓存服务 | 最新 |
| Pydantic | 数据验证 | 最新 |
| python-jose | JWT认证 | 最新 |

### 5.2 外部服务依赖

| 服务名称 | 用途 | 集成方式 |
|---------|------|---------|
| RAGFlow | 文档检索与智能对话 | API调用 |
| Compreface | 人脸识别 | API调用 |
| 海康平台 | 门禁控制 | API调用 |
| SerpAPI | 搜索增强 | API调用 |

## 6. 系统特性与优势

1. **模块化设计**：系统采用模块化架构，各功能模块独立，便于维护和扩展
2. **前后端分离**：前端使用Vue.js，后端使用FastAPI，提高开发效率和系统性能
3. **多端支持**：支持Web控制台和Pad控制端，满足不同场景的使用需求
4. **AI能力集成**：集成了人脸识别、智能对话和搜索增强等AI能力，提升系统智能化水平
5. **丰富的外部接口**：与门禁系统、机器人硬件等多种外部设备和服务进行集成
6. **完善的权限管理**：支持基于角色的权限控制，确保系统安全
7. **实时监控与统计**：提供系统统计和识别记录管理，便于数据分析和决策

## 7. 系统部署架构

```mermaid
flowchart TD
    subgraph 服务器集群
        LoadBalancer["负载均衡器\n(Nginx)"]
        Backend1["FastAPI节点1"]
        Backend2["FastAPI节点2"]
        Backend3["FastAPI节点3"]
    end

    subgraph 数据层
        DB[("主数据库\n(MySQL/PostgreSQL)")]
        DB2[("从数据库\n(MySQL/PostgreSQL)")]
        RedisCluster["Redis集群\n(主从架构)"]
    end

    subgraph 外部服务
        RAGFlow["RAGFlow服务"]
        Compreface["Compreface服务"]
        HaiKang["海康平台"]
    end

    用户["用户"] -->|HTTP请求| LoadBalancer
    LoadBalancer -->|分发请求| Backend1
    LoadBalancer -->|分发请求| Backend2
    LoadBalancer -->|分发请求| Backend3
    
    Backend1 -->|读写| DB
    Backend2 -->|读写| DB
    Backend3 -->|读写| DB
    DB -->|同步| DB2
    
    Backend1 -->|缓存操作| RedisCluster
    Backend2 -->|缓存操作| RedisCluster
    Backend3 -->|缓存操作| RedisCluster
    
    Backend1 -->|API调用| RAGFlow
    Backend2 -->|API调用| RAGFlow
    Backend3 -->|API调用| RAGFlow
    
    Backend1 -->|API调用| Compreface
    Backend2 -->|API调用| Compreface
    Backend3 -->|API调用| Compreface
    
    Backend1 -->|API调用| HaiKang
    Backend2 -->|API调用| HaiKang
    Backend3 -->|API调用| HaiKang
```

## 8. 系统扩展性设计

1. **微服务架构支持**：系统可扩展为微服务架构，将不同功能模块拆分为独立服务
2. **插件化设计**：支持通过插件方式扩展系统功能
3. **API网关集成**：可集成API网关，统一管理API访问
4. **容器化部署**：支持Docker容器化部署，便于水平扩展
5. **云原生支持**：支持在Kubernetes等容器编排平台上部署

## 9. 系统安全设计

1. **身份认证与授权**：采用JWT令牌机制，支持基于角色的访问控制
2. **数据加密**：敏感数据加密存储，传输过程使用HTTPS
3. **接口安全**：所有API接口均需认证，部分接口需额外权限验证
4. **日志审计**：记录所有用户操作和系统事件，便于审计和追踪
5. **防SQL注入**：使用ORM框架和参数化查询，防止SQL注入攻击
6. **防XSS攻击**：对输入输出进行过滤，防止跨站脚本攻击

## 10. 总结

康达机器人系统采用现代化的技术架构，集成了多种AI能力和外部服务，为用户提供全面的机器人管理和控制解决方案。系统具有良好的扩展性、安全性和可维护性，能够满足不同规模和场景的使用需求。