# Superpowers-ZH 实战：图书管理系统

**Repository Path**: javaweb-dev-tech/library-superpowers

## Basic Information

- **Project Name**: Superpowers-ZH 实战：图书管理系统
- **Description**: Trae IDE + Superpowers-ZH 从零 AI 辅助开发的全栈图书管理系统（Spring Boot 3.2 + JWT + RBAC），完整展示 AI 驱动开发的标准工作流。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Superpowers-ZH 实战：图书管理系统

> 本项目是 **Trae IDE + Superpowers-ZH** 技能框架的完整实战案例——从零开始，全程 AI 辅助开发一个全栈图书管理系统。从需求分析 → 系统设计 → UI 设计 → 实现计划 → 逐任务编码 → 前后端对接 → 调试修复，严格遵循 Superpowers-ZH 的 5 阶段标准工作流。

一个基于 Spring Boot 3.2 + 原生 HTML/CSS/JS 的全栈图书管理系统，支持用户管理、图书管理、借阅管理三大核心功能，采用 JWT 认证和 RBAC 权限控制。

## Superpowers-ZH 开发过程

本项目完整保留了 Superpowers-ZH 框架的全部开发过程产物，是理解 AI 驱动开发工作流的参考案例：

```
docs/superpowers/
├── specs/
│   ├── 2026-05-26-library-management-system-design.md  # 系统设计文档（架构、API、数据库）
│   └── 2026-05-26-library-management-system-ui-design.md # UI 设计文档（布局、配色、页面交互）
├── plans/
│   └── 2026-05-26-library-management-system.md  # 实现计划（11 个任务拆分，逐任务编码指导）
├── aichat_history/
│   └── 前端UI设计及前后端对接调试.md  # 完整 AI 对话记录（UI 设计 + 前后端对接全流程）
└── ui/                                     # UI 原型文件（已复制到 static/ 集成进项目）
```

**复现此开发环境**（需先安装 Node.js）：

```bash
npx superpowers-zh --tool trae
```

> 更多使用方法见 [Superpowers-ZH使用指南.md](./Superpowers-ZH使用指南.md)


## 技术栈

| 层级 | 技术 |
|------|------|
| **后端框架** | Spring Boot 3.2.5 |
| **持久层** | MyBatis 3.0.3 |
| **数据库** | MySQL 8.0（生产） / H2（开发） |
| **认证鉴权** | Spring Security + JWT (jjwt 0.12.5) |
| **前端** | 原生 HTML + CSS + JavaScript |
| **构建工具** | Maven |
| **AI 开发** | Trae IDE + Superpowers-ZH |
| **JDK** | 17+ |

## 功能模块

### 用户模块
- 用户注册 / 登录（JWT Token）
- 管理员：用户列表查询（分页 + 多条件搜索）
- 获取当前登录用户信息

### 图书模块
- 图书查询（所有已登录用户可查，支持分页 + 标题搜索）
- 图书新增、编辑、删除（仅 ADMIN）
- 图书状态管理（可借 / 已借出）

### 借阅模块
- 借书（所有已登录用户）
- 还书（仅借阅者本人）
- 所有借阅记录查询（仅 ADMIN，支持分页 + 标题/用户名/状态多条件搜索）
- 个人借阅记录查询（分页）

### 前端页面
- `login.html` — 登录页
- `register.html` — 注册页
- `dashboard.html` — 仪表盘（系统概览统计）
- `books.html` — 图书管理
- `borrows.html` — 借阅管理
- `users.html` — 用户管理
- `index.html` — 入口页（自动判断登录状态跳转）

## 项目结构

```
demo/
├── .trae/
│   ├── rules/
│   │   └── superpowers-zh.md       # Superpowers-ZH 全局规则
│   └── skills/                     # 20 个 Skill 定义
│       ├── brainstorming/
│       ├── writing-plans/
│       ├── subagent-driven-development/
│       └── ...（其余 17 个）
├── backend/
│   ├── pom.xml
│   └── src/main/
│       ├── java/com/example/library/
│       │   ├── config/           # 配置类（SecurityConfig, MyBatisConfig）
│       │   ├── controller/       # 控制器（User, Book, Borrow）
│       │   ├── service/          # 服务层
│       │   ├── mapper/           # MyBatis 接口
│       │   ├── entity/           # 实体类（User, Book, BorrowRecord）
│       │   ├── dto/
│       │   │   ├── request/      # 请求 DTO
│       │   │   └── response/     # 响应 DTO（含 PageResponse 分页）
│       │   ├── enums/            # 枚举（Role, BookStatus）
│       │   ├── security/         # JWT 认证（TokenProvider, Filter）
│       │   ├── exception/        # 全局异常处理
│       │   └── LibraryApplication.java
│       └── resources/
│           ├── application.yml          # MySQL 配置
│           ├── application-dev.yml      # H2 开发环境配置
│           ├── schema.sql               # MySQL 建表脚本
│           ├── schema-h2.sql            # H2 建表 + 初始数据
│           ├── mapper/                  # MyBatis XML 映射
│           └── static/                  # 前端静态资源
│               ├── css/                 # 样式（common.css, auth.css）
│               ├── js/                  # 脚本（api.js, auth.js, sidebar.js, utils.js）
│               └── *.html               # 页面文件
├── docs/
│   └── superpowers/                # Superpowers-ZH 产出物
│       ├── specs/                  # 设计文档（系统设计 + UI 设计）
│       ├── plans/                  # 实现计划
│       ├── aichat_history/         # AI 对话记录
│       └── ui/                     # UI 原型文件
├── README.md
└── Superpowers-ZH使用指南.md
```

## 快速开始

### 环境要求
- JDK 17+
- Maven 3.6+
- MySQL 8.0（可选，开发环境使用内置 H2 无需安装）

### 启动方式

**方式一：开发环境（H2 内存数据库，即开即用）**

```bash
# 进入后端目录
cd backend

# 编译并启动（默认激活 dev profile，使用 H2）
mvn spring-boot:run
```

服务启动后访问：`http://localhost:8080`

**方式二：生产环境（MySQL）**

```bash
# 1. 创建 MySQL 数据库
mysql -u root -p -e "CREATE DATABASE library_db;"

# 2. 修改 application.yml 中数据源配置
# 3. 启动
cd backend
mvn spring-boot:run -Dspring-boot.run.profiles=default
```

### 默认账号

启动后系统自动初始化以下账号：

| 用户名 | 密码 | 角色 |
|--------|------|------|
| `admin` | `admin123` | ADMIN（全部权限） |
| `user` | `user123` | USER（查书 + 借阅） |

也可以访问 `http://localhost:8080/register.html` 自行注册新用户。

## API 接口

### 认证方式

除注册和登录外，所有 API 需在请求头携带 JWT Token：

```
Authorization: Bearer <token>
```

### 用户接口

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/users/register` | 公开 | 用户注册 |
| POST | `/api/users/login` | 公开 | 用户登录，返回 JWT |
| GET | `/api/users/me` | 登录用户 | 获取当前用户信息 |
| GET | `/api/users` | ADMIN | 用户列表（参数：page, size, username, email, role） |

### 图书接口

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| GET | `/api/books` | 登录用户 | 图书列表（参数：page, size, title） |
| GET | `/api/books/{id}` | 登录用户 | 图书详情 |
| POST | `/api/books` | ADMIN | 新增图书 |
| PUT | `/api/books/{id}` | ADMIN | 编辑图书 |
| DELETE | `/api/books/{id}` | ADMIN | 删除图书 |

### 借阅接口

| 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|
| POST | `/api/borrows` | 登录用户 | 借书（body: { bookId }） |
| PUT | `/api/borrows/{id}/return` | 借阅者本人 | 还书 |
| GET | `/api/borrows` | ADMIN | 全部借阅记录（参数：page, size, title, username, status） |
| GET | `/api/borrows/my` | 登录用户 | 我的借阅记录（参数：page, size） |

### 分页响应格式

```json
{
  "content": [...],
  "totalElements": 25,
  "totalPages": 3,
  "currentPage": 1,
  "pageSize": 10
}
```

## 权限模型

| 角色 | 查书 | 借书/还书 | 管理图书 | 管理借阅 | 管理用户 |
|------|------|----------|----------|----------|----------|
| USER | ✅ | ✅ | ❌ | 仅自己的 | ❌ |
| ADMIN | ✅ | ✅ | ✅ | 全部 | ✅ |

## 数据库表

### users
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK | 自增主键 |
| username | VARCHAR(50) | 用户名，唯一 |
| password | VARCHAR(255) | BCrypt 加密 |
| email | VARCHAR(100) | 邮箱 |
| role | VARCHAR(20) | ADMIN / USER |
| created_at | DATETIME | 注册时间 |

### books
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK | 自增主键 |
| title | VARCHAR(200) | 书名 |
| author | VARCHAR(100) | 作者 |
| isbn | VARCHAR(20) | ISBN |
| publisher | VARCHAR(100) | 出版社 |
| description | TEXT | 简介 |
| status | VARCHAR(20) | AVAILABLE / BORROWED |
| created_at | DATETIME | 入库时间 |

### borrow_records
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK | 自增主键 |
| user_id | BIGINT FK | 借阅用户 |
| book_id | BIGINT FK | 被借图书 |
| borrow_date | DATETIME | 借阅时间 |
| return_date | DATETIME | 归还时间（null 表示未还） |
| created_at | DATETIME | 记录创建时间 |

## H2 控制台

开发环境下可访问 `http://localhost:8080/h2-console` 查看数据库：

| 配置项 | 值 |
|--------|-----|
| JDBC URL | `jdbc:h2:mem:library_db` |
| 用户名 | `sa` |
| 密码 | 留空 |