# smart-library

**Repository Path**: Luo_jie3/smart-library

## Basic Information

- **Project Name**: smart-library
- **Description**: 智能图书馆系统（Smart Library）是一个以 AI 智能体为核心的现代化图书馆管理平台。读者可通过自然语言与 AI 助手"书灵"对话，完成图书查询、借阅归还、个性化推荐等操作，管理员可通过数据看板实时掌握馆藏与借阅动态。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-19
- **Last Updated**: 2026-03-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能图书馆系统 Smart Library

基于 AI 智能体的图书馆管理系统，核心亮点是名为**"书灵"**的 AI 助手——读者可通过自然语言完成图书查询、借阅归还、个性化推荐等操作。

## 功能概览

| 模块 | 功能 |
|------|------|
| AI 智能体对话 | 多轮对话、Tool Calling 执行借阅/归还、RAG 语义检索、SSE 流式输出 |
| 图书管理 | 分页浏览、语义搜索、封面上传、CRUD（管理员） |
| 借阅管理 | 借阅/归还流程、逾期状态跟踪、个人借阅记录 |
| 个性化推荐 | 基于借阅历史的 LLM 推荐，无历史时降级为热门 Top10 |
| 数据看板 | 藏书量、借阅趋势、热门图书、分类占比、AI 对话统计（管理员） |
| 用户权限 | ADMIN / READER 两种角色，JWT 认证 + Redis Token 黑名单 |

## 技术栈

### 后端

| 组件 | 版本 |
|------|------|
| Java | 17 |
| Spring Boot | 3.3.5 |
| Spring AI | 1.0.0-M4 |
| Spring Security | 内置 |
| MyBatis-Plus | 3.5.9 |
| MySQL | 8.x |
| Redis | 7.x |
| jjwt | 0.12.6 |
| SpringDoc OpenAPI | 2.6.0 |
| Ollama | qwen2.5:7b + nomic-embed-text |

### 前端

| 组件 | 版本 |
|------|------|
| Vue 3 + TypeScript | ^3.5 |
| Vite | ^7.1 |
| Element Plus | ^2.11 |
| Tailwind CSS | v4 |
| ECharts | ^6.0 |
| Pinia | ^3.0 |
| axios | ^1.12 |

## 系统架构

```
前端 Vue3          后端 Spring Boot
─────────          ───────────────────────────────────
浏览器  ──HTTP/SSE──▶  REST API / SSE
                       │
                       ├── Spring Security + JWT
                       ├── AI Agent（ChatClient + Tools + RAG）
                       │     ├── Tool Calling ──▶ Business Service
                       │     ├── RAG 检索    ──▶ SimpleVectorStore
                       │     └── 对话        ──▶ Ollama qwen2.5:7b
                       └── MyBatis-Plus ──▶ MySQL
                                         Redis（缓存 + Token）
                                         本地文件系统（/uploads）
```

## 快速启动

### 前置依赖

- Java 17+
- Node.js 20.19+ / pnpm
- MySQL 8.x（创建数据库 `smart_library`，执行 `schema.sql`）
- Redis 7.x
- [Ollama](https://ollama.ai) 并拉取模型：

```bash
ollama pull qwen2.5:7b
ollama pull nomic-embed-text
```

### 后端

```bash
cd smart-library/smart-library

# 修改 src/main/resources/application.yml 中的数据库密码等配置

./mvnw spring-boot:run
# 服务启动于 http://localhost:8080
# Swagger UI: http://localhost:8080/swagger-ui/index.html
```

### 前端

```bash
cd smart-library/frontend

pnpm install
pnpm dev
# 开发服务器启动于 http://localhost:5173
```

## 关键配置（application.yml）

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/smart_library
    username: root
    password: your_password
  data:
    redis:
      host: localhost
      port: 6379
  ai:
    ollama:
      base-url: http://localhost:11434
      chat:
        model: qwen2.5:7b
      embedding:
        model: nomic-embed-text

app:
  jwt:
    secret: your-256-bit-secret-key
    expiration: 86400000
  upload-dir: ./uploads
  vector-store:
    path: ./data/vectors.json
```

## 项目结构

```
smart-library/
├── frontend/                  # Vue 3 前端（pure-admin-thin）
│   └── src/
│       ├── api/               # 接口层
│       ├── views/             # 页面（book/borrow/agent/admin/dashboard）
│       ├── components/        # BookCard、MarkdownRenderer、ChatBubble
│       └── router/modules/    # 路由按模块拆分
└── smart-library/             # Spring Boot 后端
    └── src/main/java/cn/edu/cdu/smartlibrary/
        ├── agent/             # LibraryAgent、AgentTools、AgentPrompts
        ├── controller/        # REST 控制器
        ├── service/           # 业务逻辑
        ├── mapper/            # MyBatis-Plus Mapper
        ├── entity/            # 数据库实体（8张表）
        ├── dto/               # 请求 DTO
        └── vo/                # 响应 VO
```

## AI 智能体能力

书灵支持以下 Tool Calling 工具，由 LLM 根据用户意图自动调用：

- `searchBooks` — 关键词搜索图书
- `semanticSearchBooks` — 语义搜索（RAG）
- `getBookDetail` — 获取图书详情
- `borrowBook` — 借阅图书
- `returnBook` — 归还图书
- `getMyBorrowRecords` — 查询个人借阅记录
- `getMyFavorites` — 查询收藏列表
- `addFavorite` — 收藏图书

Ollama 不可用时系统自动降级：语义搜索退化为关键词搜索，推荐退化为热门 Top10。

## 数据库表

| 表名 | 说明 |
|------|------|
| `user` | 用户（ADMIN / READER） |
| `book` | 图书（含库存、向量化描述） |
| `borrow_record` | 借阅记录（BORROWED / RETURNED / OVERDUE） |
| `user_favorite` | 用户收藏 |
| `book_review` | 图书评论评分 |
| `ai_chat_session` | AI 对话会话 |
| `ai_chat_message` | AI 对话消息（持久化历史） |
| `ai_recommendation` | AI 推荐记录 |

建表 SQL 见 `smart-library/src/main/resources/static/schema.sql`。