# 图书管理系统

**Repository Path**: ninesenz/library-management-system

## Basic Information

- **Project Name**: 图书管理系统
- **Description**: Spring Boot + Vue + Ant Design Vue + MySQL 的图书后台管理系统。系统支持多用户、角色权限、超级管理员用户管理、图书增删改查，以及 MySQL 到飞书多维表格的单向同步日志。
可以作为前后端新项目的初始模版 
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Book Admin

Book Admin 是一个基于 Spring Boot、Vue 3、Ant Design Vue 和 MySQL 的图书管理系统。项目包含公开图书检索首页和管理员后台，适合用于图书数据维护、权限管理、用户管理，以及将 MySQL 图书数据单向同步到飞书多维表格。

系统当前已支持服务端分页，图书管理页和首页搜索页不会一次性加载全量图书数据；在数据量较大时，前端只渲染当前页，后端只查询当前页。

## 功能范围

- 公开首页：无需登录即可按书名或作者搜索图书。
- 账号密码登录，JWT 鉴权。
- 超级管理员拥有全部权限。
- 用户管理：创建用户、设置密码、启停账号、分配角色。
- 角色权限：按角色分配权限。
- 图书管理：书名、作者的新增、分页查询、编辑、直接删除。
- 权限点：`book:create`、`book:read`、`book:update`、`book:delete`。
- 飞书同步：MySQL 到飞书多维表格单向同步，新增、编辑、删除图书时同步飞书记录，支持一键同步未同步图书、查看同步日志并标记重试。

## 页面入口

- 公开图书检索：首页 `http://localhost:5173/`
- 管理员登录页：`http://localhost:5173/login`
- 图书管理后台：`http://localhost:5173/books`
- 用户管理：`http://localhost:5173/users`
- 角色权限：`http://localhost:5173/roles`
- 飞书同步日志：`http://localhost:5173/feishu`

## 目录

```text
backend/   Spring Boot 后端
frontend/  Vue 3 + Vite 前端
scripts/   数据初始化和维护脚本
.vscode/   VS Code 任务配置
```

## 环境要求

- JDK 21
- Maven 3.9+
- Node.js 20+ 或 24+
- npm
- MySQL 8+

## 数据库初始化

1. 创建并初始化数据库：

```bash
mysql -u root -p < backend/src/main/resources/schema.sql
```

2. 复制后端配置示例，并修改本地数据库连接：

```bash
cp backend/src/main/resources/application.example.yml backend/src/main/resources/application.yml
```

实际运行配置在 `backend/src/main/resources/application.yml`，该文件包含本地数据库密码和飞书密钥，已加入 `.gitignore`，不要提交到仓库。

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/book_admin?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: root
    password: root
```

应用首次启动时会自动创建默认数据：

- 用户名：`admin`
- 密码：`admin123`
- 角色：`SUPER_ADMIN`

## 本地运行

后端：

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

前端：

```bash
cd frontend
npm install
npm run dev
```

访问前端默认地址：`http://localhost:5173`

前端开发服务器通过 `frontend/vite.config.js` 代理 `/api` 到后端 `http://localhost:8080`。

## 默认账号

应用首次启动时会自动创建超级管理员账号：

```text
用户名：admin
密码：admin123
```

首次部署后建议立即修改默认密码。

## 核心接口

后端统一以 `/api` 作为上下文路径。

```text
POST   /api/auth/login                         登录
GET    /api/auth/profile                       当前用户信息

GET    /api/public/books/search     公开分页搜索图书，参数：keyword、page、size

GET    /api/books?page=1&size=20                管理端分页查询图书
POST   /api/books                               新增图书
PUT    /api/books/{id}                          编辑图书
DELETE /api/books/{id}                          直接删除图书
POST   /api/books/sync-feishu                   一键同步未同步图书到飞书

GET    /api/users                               用户列表
GET    /api/roles                               角色列表
GET    /api/permissions                         权限列表
GET    /api/feishu/sync-logs                    飞书同步日志
```

分页接口返回结构示例：

```json
{
    "content": [],
    "totalElements": 1000,
    "totalPages": 50,
    "page": 1,
    "size": 20
}
```

## 构建验证

后端编译：

```bash
cd backend
mvn test -DskipTests
```

前端构建：

```bash
cd frontend
npm run build
```

## 大数据量说明

当前版本已经避免了全表加载：

- 管理端图书列表使用后端分页：`/api/books?page=1&size=20`。
- 公开图书搜索使用后端分页：`/api/public/books/search?keyword=xxx&page=1&size=20`。
- 前端表格使用服务端分页，只展示当前页数据。
- 表格区域固定高度，数据较多时在表格内部滚动。

如果图书表达到千万级数据，建议继续做以下优化：

1. 普通列表避免深分页，优先改成游标分页：

```sql
SELECT *
FROM book
WHERE id < :lastId
ORDER BY id DESC
LIMIT 20;
```

2. 公开搜索不要长期使用 `%keyword%` 模糊匹配。MySQL 8 可添加全文索引：

```sql
ALTER TABLE book ADD FULLTEXT INDEX ft_book_title_author (title, author);
```

然后将搜索改为全文检索：

```sql
SELECT *
FROM book
WHERE MATCH(title, author) AGAINST (:keyword IN NATURAL LANGUAGE MODE)
LIMIT 20;
```

3. 如果搜索体验要求更高，建议引入 Elasticsearch、OpenSearch 或 Meilisearch，由 MySQL 保存主数据，搜索引擎负责检索。

4. 千万级场景下实时 `COUNT(*)` 可能变慢。如果总页数不是必须准确，可以使用 `Slice` 或游标分页，只返回是否还有下一页。

## 飞书配置

飞书同步默认关闭。启用时设置环境变量或修改 `application.yml`：

```bash
APP_FEISHU_ENABLED=true
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=xxx
FEISHU_APP_TOKEN=base_xxx
FEISHU_TABLE_ID=tbl_xxx
```

飞书多维表格字段需要包含：

- `书名`
- `作者`

同步行为：

- 新增图书会在飞书多维表格创建记录，并把返回的 `record_id` 保存到 `book.feishu_record_id`。
- 编辑图书时，如果已有 `feishu_record_id`，会更新飞书记录；如果没有，会先创建飞书记录。
- 删除图书时，如果已有 `feishu_record_id`，会删除飞书对应记录。
- 图书管理页的“一键同步到飞书”按钮会批量同步所有 `feishu_record_id` 为空的图书，并返回同步成功和失败数量。
- 批量同步入口需要 `feishu:retry` 权限或超级管理员权限。

## 数据维护脚本

仓库提供 `scripts/seed-chinese-books.ps1`，用于清空 `book` 表并导入 1000 条中文图书样例数据：

```powershell
& .\scripts\seed-chinese-books.ps1
```

脚本会读取 `backend/src/main/resources/application.yml` 中的数据库密码，通过 MySQL CLI 直接批量写入数据库。直接写库不会触发后端飞书同步；导入后如需同步到飞书，请在图书管理页点击“一键同步到飞书”。

## 云服务器部署建议

1. 在服务器安装 JDK 21、Node.js、MySQL、Nginx。
2. 执行 schema 初始化并配置生产数据库账号。
3. 后端打包：

```bash
cd backend
mvn clean package -DskipTests
java -jar target/book-admin-backend-0.0.1-SNAPSHOT.jar
```

4. 前端打包并由 Nginx 托管：

```bash
cd frontend
npm install
npm run build
```

5. Nginx 反向代理示例：

```nginx
server {
    listen 80;
    server_name your-domain.com;

    root /opt/book-admin/frontend/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:8080/api/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```