# 灵BI-智能BI平台

**Repository Path**: Clscu2022/lingbi

## Basic Information

- **Project Name**: 灵BI-智能BI平台
- **Description**: 基于 Spring Boot+ MQ+ AIGC 的智能数据分析平台。区别于传统 Bl，用户只需要导入原始数据集、并输入分析诉求，就能自动生成可视化图表及分析结论，实现数据分析的降本增效
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-03-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🌟 LingBI — 智能数据分析平台

> 上传 Excel，输入目标，AI 自动生成图表与分析结论。

---

## 📖 项目简介

**LingBI（灵BI）** 是一个基于 Spring Boot 构建的智能 BI（商业智能）后端平台。用户只需上传 Excel 数据文件并描述分析目标，系统将自动调用阿里云通义千问大模型，生成可直接渲染的 **ECharts v5 图表配置** 与**数据分析结论**，帮助用户快速完成数据洞察，无需手动编写任何图表代码。

---

## ✨ 核心特性

- 🤖 **AI 智能分析**：接入阿里云 DashScope（通义千问 `qwen-plus`），自动生成 ECharts JSON 配置及文字结论
- ⚡ **三种分析模式**：同步调用 / 异步线程池 / 异步消息队列（RabbitMQ），灵活应对不同并发场景
- 🛡️ **限流保护**：基于 Redisson + Redis 令牌桶，对每个用户独立限流（每秒最多 2 次）
- 📬 **消息队列**：RabbitMQ Direct Exchange，异步解耦 AI 任务，支持任务持久化与状态追踪
- 👥 **用户权限体系**：支持普通用户（`user`）与管理员（`admin`）角色，AOP 注解鉴权
- ☁️ **文件存储**：集成腾讯云 COS 对象存储
- 📄 **接口文档**：集成 Knife4j，在线 Swagger UI 自动生成
- 🗑️ **逻辑删除**：MyBatis-Plus 全局软删除，数据安全可追溯

---

## 🛠️ 技术栈

| 分类 | 技术 |
|------|------|
| 后端框架 | Spring Boot 2.x |
| 持久层 | MyBatis-Plus（分页 + 逻辑删除） |
| 数据库 | MySQL 8.x |
| 缓存 / 限流 | Redis + Redisson |
| 消息队列 | RabbitMQ（Direct Exchange） |
| AI 服务 | 阿里云 DashScope（通义千问 qwen-plus） |
| 文件存储 | 腾讯云 COS |
| Excel 解析 | EasyExcel |
| 接口文档 | Knife4j（Swagger3） |
| 工具库 | Hutool、Apache Commons |

---

## 📁 项目结构

```
src/main/java/com/shiqi/lingbi/
├── MainApplication.java              # 启动类
├── annotation/                       # 自定义注解（@AuthCheck）
├── aop/                              # AOP 切面（权限拦截 / 请求日志）
├── bimq/                             # BI 消息队列
│   ├── BiInitMain.java               # MQ 初始化（启动前执行一次）
│   ├── BiMessageProducer.java        # 消息生产者
│   ├── BiMessageConsumer.java        # 消息消费者
│   └── BiMqConstant.java             # 常量定义
├── common/                           # 通用响应体 / 错误码 / 分页
├── config/                           # 组件配置（CORS / COS / Redis / 线程池等）
├── controller/                       # REST 控制器
│   ├── ChartController.java          # 图表接口（含 AI 分析）
│   ├── UserController.java           # 用户接口
│   └── FileController.java           # 文件上传接口
├── exception/                        # 全局异常处理
├── manager/                          # 核心业务管理
│   ├── AiManager.java                # AI 调用封装
│   ├── RedisLimiterManager.java      # Redis 限流
│   └── CosManager.java               # COS 文件操作
├── model/                            # 实体 / DTO / VO
├── service/                          # 业务逻辑层
└── utils/                            # 工具类（ExcelUtils 等）
```

---

## 🚀 快速开始

### 前置依赖

- JDK 8+
- MySQL 8.x
- Redis
- RabbitMQ
- 阿里云 DashScope API Key

### 1. 克隆项目

```bash
git clone <repository-url>
cd lingbi
```

### 2. 初始化数据库

创建数据库并导入建表 SQL：

```sql
CREATE DATABASE lingbi DEFAULT CHARACTER SET utf8mb4;
```

### 3. 修改配置文件

编辑 `src/main/resources/application.yml`，填写以下配置：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/lingbi
    username: 你的用户名
    password: 你的密码
  redis:
    host: localhost
    port: 6379
  rabbitmq:
    host: localhost
    port: 5672
```

### 4. 配置环境变量

```bash
# 阿里云通义千问 API Key（必须）
export DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxx
```

### 5. 初始化 RabbitMQ（仅需一次）

运行 `BiInitMain.main()` 方法，创建 `bi_exchange` 交换机和 `bi_queue` 队列。

### 6. 启动项目

```bash
mvn spring-boot:run
```

启动成功后访问接口文档：

```
http://localhost:8101/api/doc.html
```

---

## 📡 主要接口

### 用户相关（`/api/user`）

| 接口 | 方法 | 路径 | 权限 |
|------|------|------|------|
| 用户注册 | POST | `/user/register` | 公开 |
| 用户登录 | POST | `/user/login` | 公开 |
| 用户注销 | POST | `/user/logout` | 登录用户 |
| 获取当前用户 | GET | `/user/get/login` | 登录用户 |
| 更新个人信息 | POST | `/user/update/my` | 登录用户 |

### 图表相关（`/api/chart`）

| 接口 | 方法 | 路径 | 权限 |
|------|------|------|------|
| AI 分析（同步） | POST | `/chart/gen` | 登录用户 |
| AI 分析（异步线程池） | POST | `/chart/gen/async` | 登录用户 |
| AI 分析（异步 MQ） | POST | `/chart/gen/async/mq` | 登录用户 |
| 我的图表列表 | POST | `/chart/my/list/page/vo` | 登录用户 |
| 获取图表详情 | GET | `/chart/get/vo` | 登录用户 |
| 创建图表 | POST | `/chart/add` | 登录用户 |
| 删除图表 | POST | `/chart/delete` | 本人 / 管理员 |

### AI 分析接口请求参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `file` | MultipartFile | ✅ | Excel 文件（.xls / .xlsx，最大 1MB） |
| `goal` | String | ✅ | 分析目标，如：分析近三个月用户增长趋势 |
| `chartName` | String | ❌ | 图表名称，最长 100 字符 |
| `chartType` | String | ❌ | 图表类型，如：柱状图、折线图、饼图 |

### 返回示例

```json
{
  "code": 0,
  "data": {
    "chartId": 1234567890,
    "genChart": "{ \"title\": { \"text\": \"用户增长趋势\" }, \"xAxis\": {...}, ... }",
    "genResult": "从数据来看，近三个月用户数持续上升，增长率约为 20%..."
  },
  "message": "ok"
}
```

> **注意**：异步接口（`/gen/async`、`/gen/async/mq`）立即返回 `chartId`，需轮询 `/chart/get/vo` 查询最终状态（`wait` → `running` → `succeed` / `failed`）。

---

## ⚙️ 图表任务状态

```
wait  ──▶  running  ──▶  succeed
                    └──▶  failed
```

| 状态 | 说明 |
|------|------|
| `wait` | 任务已创建，等待执行 |
| `running` | AI 正在分析处理中 |
| `succeed` | 分析完成，genChart 和 genResult 已生成 |
| `failed` | 分析失败，查看 execMessage 了解原因 |

---

## 🔒 权限说明

- **普通用户（user）**：注册后默认角色，可使用 AI 分析功能，管理自己的图表
- **管理员（admin）**：可访问所有用户数据，执行图表更新、用户管理等操作

接口级权限通过 `@AuthCheck(mustRole = "admin")` 注解 + AOP 切面实现。

---

## 📝 注意事项

1. **首次使用消息队列模式前**，必须先运行 `BiInitMain.main()` 初始化 MQ 交换机和队列
2. **限流规则**：每个用户每秒最多调用 AI 分析接口 2 次，超限返回错误码 `42900`
3. **文件限制**：上传的 Excel 文件大小不超过 **100MB**，仅支持 `.xls` 和 `.xlsx` 格式
4. **分布式 Session**：默认使用内存 Session，如需集群部署，请在配置文件中启用 `spring.session.store-type: redis`
5. **API Key 安全**：`DASHSCOPE_API_KEY` 请通过环境变量注入，勿硬编码到代码中

---

## 📄 License

本项目仅供学习交流使用。