# 书店项目

**Repository Path**: yakumo12/bookstore-project

## Basic Information

- **Project Name**: 书店项目
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 拾光书店 — 在线购书网站课程设计说明书

---

## 封面

| 项目 | 内容 |
|------|------|
| **题目** | 拾光书店 — 温暖文艺风格在线购书网站 |
| **班级** | 软件工程2302 |
| **姓名** | 林颖浩       |
| **学号** | 23408000427 |
| **课程设计日期** | 2026年5月30日 |

---

## 目录

1. [课题介绍和任务](#1-课题介绍和任务)
2. [需求分析](#2-需求分析)
3. [系统分析和类设计](#3-系统分析和类设计)
4. [系统数据设计](#4-系统数据设计)
5. [系统实现及调试](#5-系统实现及调试)
6. [系统使用说明](#6-系统使用说明)
7. [测试结果](#7-测试结果)
8. [AI工具使用总结](#8-ai工具使用总结)
9. [总结与展望](#9-总结与展望)
10. [附录与参考资料](#10-附录与参考资料)
11. [API接口规格文档](#11-api接口规格文档)

---

## 1. 课题介绍和任务

### 1.1 课题背景

随着互联网技术的发展，在线购书已成为人们获取图书的重要途径。本课题旨在设计并实现一个具有温暖文艺风格的在线购书网站——"拾光书店"，为用户提供优美的阅读体验和便捷的购书服务。

### 1.2 课题任务

设计并实现一个前后端分离的在线购书系统，主要任务包括：

1. **前端开发**：使用 React + TypeScript + Tailwind CSS 构建响应式用户界面
2. **后端开发**：使用 Spring Boot + MyBatis 构建 RESTful API 服务
3. **数据库设计**：使用 MySQL 设计合理的数据模型
4. **核心功能实现**：
   - 每日书摘展示
   - 图书浏览与筛选
   - 海报生成与分享
   - 购物车管理
   - 订单结算
   - 用户系统（注册、登录、个人中心）
   - 个人书架（收藏、已购、历史）

### 1.3 技术选型

| 层次 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 前端框架 | React | 19 | 用户界面构建 |
| 类型系统 | TypeScript | - | 类型安全 |
| 构建工具 | Vite | 6 | 快速开发与构建 |
| 样式方案 | Tailwind CSS | 4 | 原子化CSS |
| 动画库 | Motion | - | 页面过渡动画 |
| 图标库 | Lucide React | - | 轻量级图标 |
| 后端框架 | Spring Boot | 3.3.5 | Java Web应用框架 |
| ORM框架 | MyBatis | 3.0.3 | 数据库映射 |
| 数据库 | MySQL | 8.0+ | 关系型数据库 |
| API文档 | SpringDoc OpenAPI | 2.6.0 | Swagger UI |
| 邮件服务 | Spring Mail | - | 验证码发送 |

---

## 2. 需求分析

### 2.1 功能需求

#### 2.1.1 用户模块
- 用户注册（邮箱验证）
- 用户登录/退出
- 密码重置
- 个人资料编辑（昵称、头像）
- 余额充值

#### 2.1.2 图书模块
- 图书列表浏览（分页）
- 分类筛选（文学、社科、科技、历史、经管）
- 关键词搜索（书名/作者）
- 多维度排序（价格、评分、出版日期）
- 图书详情查看
- 推荐图书、畅销图书、新书展示

#### 2.1.3 购物车模块
- 添加商品到购物车
- 修改商品数量
- 删除单个商品
- 清空购物车
- 一键结算

#### 2.1.4 订单模块
- 购物车结算生成订单
- 余额扣减（原子操作）
- 订单明细记录

#### 2.1.5 个人中心模块
- 收藏夹管理
- 已购书籍查看
- 浏览历史记录
- 每日语录展示

#### 2.1.6 特色功能
- SVG动态书籍封面生成
- Canvas高清读书海报生成
- 深色模式切换
- 流畅页面动画

### 2.2 非功能需求

1. **性能需求**：页面加载时间 < 3秒，API响应时间 < 500ms
2. **安全需求**：密码加密存储、Token认证、SQL注入防护
3. **可用性需求**：响应式设计，支持PC和移动端
4. **可维护性需求**：代码规范、模块化设计、完善的API文档

### 2.3 用例图

```
┌─────────────────────────────────────────────────────────────┐
│                      拾光书店系统                            │
│                                                             │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐              │
│  │ 浏览图书 │    │ 搜索图书 │    │ 查看详情 │              │
│  └────┬─────┘    └────┬─────┘    └────┬─────┘              │
│       │              │              │                      │
│  ┌────┴──────────────┴──────────────┴────┐                 │
│  │              游客/用户                 │                 │
│  └────┬──────────────┬──────────────┬────┘                 │
│       │              │              │                      │
│  ┌────┴─────┐  ┌─────┴────┐  ┌─────┴────┐                 │
│  │ 用户注册 │  │ 用户登录 │  │ 退出登录 │                 │
│  └──────────┘  └──────────┘  └──────────┘                 │
│                                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ 管理购物 │  │ 结算下单 │  │ 管理收藏 │  │ 余额充值 │  │
│  │    车    │  │          │  │          │  │          │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└─────────────────────────────────────────────────────────────┘
```

---

## 3. 系统分析和类设计

### 3.1 系统架构

本系统采用前后端分离的B/S架构：

```
┌─────────────────────────────────────────────────────────────┐
│                         客户端                               │
│  ┌─────────────────────────────────────────────────────┐   │
│  │           React + TypeScript + Tailwind CSS          │   │
│  │   ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐  │   │
│  │   │ 组件层  │ │ API层   │ │ 状态管理│ │ 路由    │  │   │
│  │   └─────────┘ └─────────┘ └─────────┘ └─────────┘  │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │ HTTP/REST
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                         服务端                               │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Spring Boot + MyBatis                   │   │
│  │   ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐  │   │
│  │   │Controller│ │ Service │ │  Mapper │ │  Entity │  │   │
│  │   └─────────┘ └─────────┘ └─────────┘ └─────────┘  │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              │ JDBC
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       数据库层                               │
│                    MySQL 8.0+ (InnoDB)                      │
└─────────────────────────────────────────────────────────────┘
```

### 3.2 后端分层架构

```
Controller层 (接口层)
    │
    ▼
Service层 (业务逻辑层)
    │
    ▼
Mapper层 (数据访问层)
    │
    ▼
Entity层 (实体层)
```

### 3.3 类设计

#### 3.3.1 Controller层类

| 类名 | 职责 | 主要方法 |
|------|------|----------|
| AuthController | 认证接口 | register, login, logout, sendCode, resetPassword |
| BookController | 图书接口 | listBooks, getBook, getRecommended, getBestsellers, getNewArrivals, getCategories |
| CartController | 购物车接口 | getCart, addItem, updateItemQuantity, removeItem, clearCart |
| OrderController | 订单接口 | checkout |
| UserController | 用户接口 | getProfile, updateProfile, getBalance, recharge, getBookmarks, addBookmark, removeBookmark, getBrowsingHistory, addBrowsingHistory, getPurchasedBooks |
| QuoteController | 语录接口 | getDailyQuotes |

#### 3.3.2 Service层类

| 类名 | 接口 | 实现类 |
|------|------|--------|
| AuthService | AuthService | AuthServiceImpl |
| BookService | BookService | BookServiceImpl |
| CartService | CartService | CartServiceImpl |
| OrderService | OrderService | OrderServiceImpl |
| UserService | UserService | UserServiceImpl |
| QuoteService | QuoteService | QuoteServiceImpl |
| EmailService | EmailService | EmailServiceImpl |

#### 3.3.3 Entity实体类

| 实体类 | 对应表 | 主要属性 |
|--------|--------|----------|
| Book | books | id, title, author, publisher, isbn, pages, publishDate, originalPrice, currentPrice, rating, category, synopsis, quote, authorIntro, coverPattern, coverColor, isBestseller, isNewArrival, recommended |
| User | users | id, email, passwordHash, nickname, avatarUrl, balance, createdAt, updatedAt |
| AuthToken | auth_tokens | id, userId, token, expiresAt, createdAt |
| CartItem | cart_items | id, userId, bookId, quantity, createdAt, updatedAt |
| Order | orders | id, orderNo, userId, totalAmount, status, createdAt |
| OrderItem | order_items | id, orderId, bookId, bookTitle, price, quantity |
| PurchasedBook | purchased_books | id, userId, bookId, orderId, purchasedAt |
| UserBookmark | user_bookmarks | id, userId, bookId, createdAt |
| UserBrowsingHistory | user_browsing_history | id, userId, bookId, viewedAt |
| DailyQuote | daily_quotes | id, text, source, createdAt |
| EmailVerification | email_verifications | id, email, code, expiresAt, used, createdAt |

#### 3.3.4 DTO类

| DTO类 | 用途 |
|-------|------|
| LoginRequest | 登录请求 |
| RegisterRequest | 注册请求 |
| SendCodeRequest | 发送验证码请求 |
| ResetPasswordRequest | 重置密码请求 |
| AuthResponse | 认证响应（token、用户信息） |
| BookQuery | 图书查询参数 |
| CartItemRequest | 购物车项请求 |
| CartResponse | 购物车响应 |
| CartItemResponse | 购物车项响应 |
| OrderResponse | 订单响应 |
| OrderItemResponse | 订单项响应 |
| UserProfileRequest | 用户资料更新请求 |
| UserProfileResponse | 用户资料响应 |
| UserBalanceResponse | 用户余额响应 |
| RechargeRequest | 充值请求 |
| DailyQuoteResponse | 每日语录响应 |

#### 3.3.5 工具类

| 工具类 | 职责 |
|--------|------|
| PasswordUtil | 密码加密（SHA-256 + 随机盐） |
| TokenUtil | JWT Token生成与验证 |

### 3.4 类图关系

```
┌─────────────────┐       ┌─────────────────┐
│   Controller    │──────▶│    Service      │
│   (接口层)      │       │   (业务层)      │
└─────────────────┘       └────────┬────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │     Mapper      │
                          │   (数据访问层)  │
                          └────────┬────────┘
                                   │
                                   ▼
                          ┌─────────────────┐
                          │     Entity      │
                          │    (实体层)     │
                          └─────────────────┘
```

---

## 4. 系统数据设计

### 4.1 E-R图

```
┌──────────┐     ┌──────────────┐     ┌──────────┐
│  users   │     │ auth_tokens  │     │  books   │
│──────────│     │──────────────│     │──────────│
│ id (PK)  │◀──┐│ id (PK)      │     │ id (PK)  │
│ email    │   ││ user_id (FK) │     │ title    │
│ password │   ││ token        │     │ author   │
│ nickname │   ││ expires_at   │     │ price    │
│ avatar   │   │└──────────────┘     │ rating   │
│ balance  │   │                     │ category │
└────┬─────┘   │                     └────┬─────┘
     │         │                          │
     │         │    ┌─────────────────────┼─────────────────────┐
     │         │    │                     │                     │
     ▼         │    ▼                     ▼                     ▼
┌──────────────┼──────────┐    ┌──────────────────┐    ┌──────────────────┐
│ cart_items   │          │    │  user_bookmarks  │    │user_browsing_hist│
│──────────────│──────────│    │──────────────────│    │──────────────────│
│ id (PK)      │          │    │ id (PK)          │    │ id (PK)          │
│ user_id (FK)─┘          │    │ user_id (FK)     │    │ user_id (FK)     │
│ book_id (FK)────────────┼───▶│ book_id (FK)     │    │ book_id (FK)     │
│ quantity                │    │ created_at       │    │ viewed_at        │
└─────────────────────────┘    └──────────────────┘    └──────────────────┘
     │
     │ checkout
     ▼
┌─────────────────┐     ┌─────────────────┐     ┌──────────────────┐
│    orders       │     │  order_items    │     │ purchased_books  │
│─────────────────│     │─────────────────│     │──────────────────│
│ id (PK)         │◀──┐ │ id (PK)         │     │ id (PK)          │
│ order_no        │   │ │ order_id (FK)───┘     │ user_id (FK)     │
│ user_id (FK)    │   │ │ book_id (FK)     │    │ book_id (FK)     │
│ total_amount    │   │ │ book_title       │    │ order_id (FK)    │
│ status          │   │ │ price            │    │ purchased_at     │
│ created_at      │   │ │ quantity         │    └──────────────────┘
└─────────────────┘   │ └─────────────────┘
                      │
                      │
┌─────────────────┐   │ ┌─────────────────┐
│daily_quotes     │   │ │email_verificati │
│─────────────────│   │ │─────────────────│
│ id (PK)         │   │ │ id (PK)         │
│ text            │   │ │ email           │
│ source          │   │ │ code            │
│ created_at      │   │ │ expires_at      │
└─────────────────┘   │ │ used            │
                      │ └─────────────────┘
                      │
```

### 4.2 表结构设计

#### 4.2.1 图书表 (books)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | VARCHAR(32) | PRIMARY KEY | 图书ID |
| title | VARCHAR(255) | NOT NULL | 书名 |
| author | VARCHAR(255) | NOT NULL | 作者 |
| publisher | VARCHAR(255) | | 出版社 |
| isbn | VARCHAR(20) | | ISBN |
| pages | INT | | 页数 |
| publish_date | VARCHAR(20) | | 出版日期 |
| original_price | DECIMAL(10,2) | | 原价 |
| current_price | DECIMAL(10,2) | | 现价 |
| rating | DECIMAL(3,1) | | 评分 |
| rating_count | INT | DEFAULT 0 | 评价人数 |
| category | VARCHAR(50) | | 分类 |
| synopsis | TEXT | | 简介 |
| quote | TEXT | | 金句 |
| author_intro | TEXT | | 作者简介 |
| cover_pattern | VARCHAR(50) | | 封面样式 |
| cover_color | VARCHAR(20) | | 封面颜色 |
| is_bestseller | BOOLEAN | DEFAULT FALSE | 是否畅销 |
| is_new_arrival | BOOLEAN | DEFAULT FALSE | 是否新书 |
| recommended | BOOLEAN | DEFAULT FALSE | 是否推荐 |

#### 4.2.2 用户表 (users)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | AUTO_INCREMENT PRIMARY KEY | 用户ID |
| email | VARCHAR(255) | NOT NULL UNIQUE | 邮箱 |
| password_hash | VARCHAR(255) | NOT NULL | 密码哈希 |
| nickname | VARCHAR(100) | | 昵称 |
| avatar_url | VARCHAR(500) | | 头像URL |
| balance | DECIMAL(10,2) | NOT NULL DEFAULT 0.00 | 余额 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |

#### 4.2.3 认证令牌表 (auth_tokens)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | AUTO_INCREMENT PRIMARY KEY | ID |
| user_id | BIGINT | NOT NULL, FOREIGN KEY | 用户ID |
| token | VARCHAR(500) | NOT NULL UNIQUE | Token |
| expires_at | TIMESTAMP | NOT NULL | 过期时间 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |

#### 4.2.4 购物车表 (cart_items)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | AUTO_INCREMENT PRIMARY KEY | ID |
| user_id | BIGINT | NOT NULL, FOREIGN KEY | 用户ID |
| book_id | VARCHAR(32) | NOT NULL, FOREIGN KEY | 图书ID |
| quantity | INT | NOT NULL DEFAULT 1 | 数量 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP | 更新时间 |
| | | UNIQUE(user_id, book_id) | 联合唯一约束 |

#### 4.2.5 订单表 (orders)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | AUTO_INCREMENT PRIMARY KEY | 订单ID |
| order_no | VARCHAR(32) | NOT NULL UNIQUE | 订单号 |
| user_id | BIGINT | NOT NULL, FOREIGN KEY | 用户ID |
| total_amount | DECIMAL(10,2) | NOT NULL | 总金额 |
| status | VARCHAR(20) | DEFAULT 'COMPLETED' | 状态 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |

#### 4.2.6 订单明细表 (order_items)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | AUTO_INCREMENT PRIMARY KEY | ID |
| order_id | BIGINT | NOT NULL, FOREIGN KEY | 订单ID |
| book_id | VARCHAR(32) | NOT NULL, FOREIGN KEY | 图书ID |
| book_title | VARCHAR(255) | | 书名 |
| price | DECIMAL(10,2) | NOT NULL | 单价 |
| quantity | INT | NOT NULL | 数量 |

#### 4.2.7 已购书目表 (purchased_books)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | AUTO_INCREMENT PRIMARY KEY | ID |
| user_id | BIGINT | NOT NULL, FOREIGN KEY | 用户ID |
| book_id | VARCHAR(32) | NOT NULL, FOREIGN KEY | 图书ID |
| order_id | BIGINT | NOT NULL, FOREIGN KEY | 订单ID |
| purchased_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 购买时间 |
| | | UNIQUE(user_id, book_id) | 联合唯一约束 |

#### 4.2.8 用户收藏表 (user_bookmarks)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | AUTO_INCREMENT PRIMARY KEY | ID |
| user_id | BIGINT | NOT NULL, FOREIGN KEY | 用户ID |
| book_id | VARCHAR(32) | NOT NULL, FOREIGN KEY | 图书ID |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 收藏时间 |
| | | UNIQUE(user_id, book_id) | 联合唯一约束 |

#### 4.2.9 浏览历史表 (user_browsing_history)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | AUTO_INCREMENT PRIMARY KEY | ID |
| user_id | BIGINT | NOT NULL, FOREIGN KEY | 用户ID |
| book_id | VARCHAR(32) | NOT NULL, FOREIGN KEY | 图书ID |
| viewed_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 浏览时间 |
| | | UNIQUE(user_id, book_id) | 联合唯一约束 |

#### 4.2.10 每日语录表 (daily_quotes)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | AUTO_INCREMENT PRIMARY KEY | ID |
| text | TEXT | NOT NULL | 语录内容 |
| source | VARCHAR(255) | | 来源 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |

#### 4.2.11 邮箱验证码表 (email_verifications)

| 字段名 | 类型 | 约束 | 说明 |
|--------|------|------|------|
| id | BIGINT | AUTO_INCREMENT PRIMARY KEY | ID |
| email | VARCHAR(255) | NOT NULL | 邮箱 |
| code | VARCHAR(10) | NOT NULL | 验证码 |
| expires_at | TIMESTAMP | NOT NULL | 过期时间 |
| used | BOOLEAN | DEFAULT FALSE | 是否已使用 |
| created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 |
| | | INDEX(email, code) | 索引 |

### 4.3 数据库初始化数据

系统首次运行时自动执行初始化脚本：
- `schema.sql`：建表语句
- `data.sql`：初始数据（52本图书 + 34条语录）

图书分类统计：

| 分类 | 数量 |
|------|------|
| 文学 | 33 |
| 社科 | 11 |
| 历史 | 3 |
| 科技 | 3 |
| 经管 | 2 |

---

## 5. 系统实现及调试

### 5.0 系统运行截图

![输入图片说明](%E8%BF%90%E8%A1%8C%E7%BB%93%E6%9E%9C%E5%9B%BE%E7%89%87%E9%A6%96%E9%A1%B5.png)

![输入图片说明](%E8%BF%90%E8%A1%8C%E7%BB%93%E6%9E%9C%E5%9B%BE%E7%89%87%E5%9B%BE%E4%B9%A6%E5%88%97%E8%A1%A8.png)

![输入图片说明](%E8%BF%90%E8%A1%8C%E7%BB%93%E6%9E%9C%E5%9B%BE%E7%89%87%E5%9B%BE%E4%B9%A6%E8%AF%A6%E6%83%85.png)
![输入图片说明](%E8%BF%90%E8%A1%8C%E7%BB%93%E6%9E%9C%E5%9B%BE%E7%89%87%E6%B5%8F%E8%A7%88%E8%AE%B0%E5%BD%95.png)

### 5.1 后端实现

#### 5.1.1 项目结构

```
src/main/java/com/example/backend/
├── BackendApplication.java          # 启动类
├── controller/                      # 接口层 (6个Controller)
├── service/                         # 业务逻辑层
│   └── impl/                        # 服务实现类
├── mapper/                          # 数据访问层 (10个Mapper)
├── entity/                          # 数据库实体 (11个)
├── dto/                             # 请求/响应DTO (16个)
├── vo/                              # 视图对象 (BookVO)
├── config/                          # 配置类 (CORS、OpenAPI)
├── common/                          # 通用组件 (ApiResponse、PageResponse)
├── exception/                       # 异常处理 (ErrorCode、GlobalExceptionHandler)
└── util/                            # 工具类 (PasswordUtil、TokenUtil)
```

#### 5.1.2 统一响应格式

所有接口返回统一的JSON信封格式：

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": "2025-01-01T00:00:00"
}
```

分页接口的 `data` 为分页对象：

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [],
    "page": 1,
    "size": 10,
    "total": 52,
    "totalPages": 6
  }
}
```

#### 5.1.3 认证机制

- **Token类型**：自定义JWT（手动实现）
- **Token有效期**：7天
- **密码存储**：SHA-256 + 随机盐，格式为 `base64(salt):base64(hash)`
- **携带方式**：请求头 `Authorization: Bearer <token>`
- **令牌存储**：数据库 `auth_tokens` 表

#### 5.1.4 核心业务逻辑

**用户注册流程：**
1. 检查邮箱是否已注册
2. 验证邮箱验证码
3. 密码加密存储
4. 创建用户记录
5. 生成Token返回

**购物车结算流程：**
1. 检查购物车是否为空
2. 计算总金额
3. 原子SQL扣减余额（`UPDATE ... WHERE balance >= amount`）
4. 创建订单和订单明细
5. 写入已购书目
6. 清空购物车

#### 5.1.5 定时任务

```java
@Scheduled(fixedRate = 3600000) // 每小时执行
public void cleanupExpiredCodes() {
    // 清理过期的邮箱验证码
}
```

### 5.2 前端实现

#### 5.2.1 项目结构

```
src/
├── api/                    # API封装层
│   ├── request.ts          # Axios请求封装
│   ├── auth.ts             # 认证接口
│   ├── books.ts            # 图书接口
│   ├── cart.ts             # 购物车接口
│   ├── orders.ts           # 订单接口
│   ├── users.ts            # 用户接口
│   └── quotes.ts           # 语录接口
├── components/             # 组件
│   ├── BookCard.tsx        # 图书卡片
│   ├── BookCover.tsx       # SVG封面渲染
│   └── PosterModal.tsx     # 海报生成弹窗
├── App.tsx                 # 主应用组件
├── main.tsx                # 应用入口
├── types.ts                # TypeScript类型定义
└── data.ts                 # 示例数据
```

#### 5.2.2 核心组件

**BookCover组件**：SVG动态生成书籍封面
- 根据 `coverPattern` 和 `coverColor` 生成不同样式的封面
- 支持多种几何图案和配色方案

**PosterModal组件**：Canvas高清海报生成
- 600x800分辨率
- 包含书籍信息、金句、背景装饰
- 支持保存到本地

#### 5.2.3 页面动画

使用 Motion 库实现：
- 页面切换过渡动画
- 组件入场动画
- 交互反馈动画

### 5.3 调试过程

#### 5.3.1 常见问题及解决方案

开发过程中遇到的主要问题及解决方案如下：

| 问题 | 原因 | 解决方案 | 涉及文件 |
|------|------|----------|----------|
| **Windows中文路径Maven启动失败** | Spring Boot在中文路径下解析路径编码错误 | 在pom.xml中配置maven-resources-plugin的编码为UTF-8 | pom.xml |
| **单元测试编译错误** | AuthServiceTest中类型转换错误，doNothing()使用方式错误 | 修正Mockito的doNothing()用法，修复类型转换 | AuthServiceTest.java |
| **分页查询数据截断** | 默认分页大小50导致图书数据不完整 | 将图书查询分页大小调整为200 | BookService |
| **前端书籍列表不显示** | PageResponse序列化时list字段缺失 | 添加@JsonProperty("list")注解保证字段序列化 | PageResponse.java |
| **邮箱验证码验证失败** | 验证码查询条件不准确 | 修正EmailVerificationMapper查询逻辑 | EmailVerificationMapper.xml |
| **登录态丢失** | 前端Token状态管理不一致 | 统一前端Token存储和请求拦截器处理 | request.ts |
| **已购书本不显示** | PurchasedBookMapper查询SQL错误 | 修正LEFT JOIN查询条件 | PurchasedBookMapper.xml |
| **登录后数据未刷新** | 登录成功后未重新拉取用户相关数据 | 登录成功后主动调用收藏、足迹、已购和购物车接口刷新状态 | App.tsx |
| **认证反馈不友好** | 错误提示不够明确 | 完善错误处理，添加用户友好的提示信息 | App.tsx, request.ts |
| **浏览器标签页标题错误** | HTML title配置错误 | 修正index.html中的title标签 | index.html |

**问题详细说明：**

**1. Windows中文路径Maven启动失败**

在Windows系统下，当项目路径包含中文字符时，Maven启动Spring Boot会出现路径编码错误。解决方案是在pom.xml中显式配置编码：

```xml
<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.encoding>UTF-8</maven.compiler.encoding>
</properties>
```

**2. 前端分页数据截断**

最初图书列表接口默认分页大小为50，导致52本图书数据被截断。解决方案是将分页查询的最大大小调整为200，确保所有图书都能返回。

**3. 登录态和数据持久化一致性**

用户登录后，前端需要重新拉取所有用户相关的数据（收藏、浏览历史、已购书目、购物车）。最初实现时遗漏了这个逻辑，导致用户看到的仍是旧数据。解决方案是在登录成功回调中统一调用数据刷新接口。

**4. 单元测试编译错误**

在编写单元测试时，Mockito的doNothing()方法使用方式有误。doNothing()只能用于void方法，不能用于有返回值的方法。修复方式是改用when().thenReturn()来模拟有返回值的方法。

#### 5.3.2 性能优化

1. **数据库索引**：为常用查询字段添加索引
2. **分页查询**：避免一次性加载全部数据
3. **连接池**：使用HikariCP连接池
4. **前端懒加载**：路由懒加载减少初始包大小

---

## 6. 系统使用说明

### 6.1 环境要求

- JDK 21
- MySQL 8.0+
- Maven 3.8+
- Node.js 18+

### 6.2 后端部署

1. **创建数据库**：

```sql
CREATE DATABASE shiguang_bookstore DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

2. **修改配置** `src/main/resources/application.properties`：

```properties
spring.datasource.url=jdbc:mysql://localhost:3306/shiguang_bookstore?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
spring.datasource.username=your_username
spring.datasource.password=your_password
```

3. **启动后端**：

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

4. **访问API文档**：http://localhost:8080/swagger-ui.html

### 6.3 前端部署

1. **安装依赖**：

```bash
npm install
```

2. **配置环境变量** `.env`：

```env
VITE_API_BASE_URL=http://localhost:8080
```

3. **启动开发服务器**：

```bash
npm run dev
```

4. **访问应用**：http://localhost:3000

### 6.4 功能使用流程

#### 6.4.1 浏览图书
1. 打开首页，查看每日书摘轮播
2. 滚动查看推荐图书、畅销图书、新书上架
3. 点击"全部图书"进入图书列表
4. 使用分类筛选、关键词搜索、排序功能

![输入图片说明](%E8%BF%90%E8%A1%8C%E7%BB%93%E6%9E%9C%E5%9B%BE%E7%89%87%E6%90%9C%E7%B4%A2.png)

#### 6.4.2 注册登录
1. 点击右上角"登录"按钮
2. 切换到"注册"标签
3. 输入邮箱，点击"发送验证码"
4. 查收邮件，输入6位验证码
5. 设置密码和昵称，完成注册

![输入图片说明](%E8%BF%90%E8%A1%8C%E7%BB%93%E6%9E%9C%E5%9B%BE%E7%89%87%E6%B3%A8%E5%86%8C%E9%A1%B5%E9%9D%A2.png)

#### 6.4.3 购物流程
1. 在图书详情页点击"加入购物车"
2. 点击右上角购物车图标查看购物车
3. 调整商品数量或删除商品
4. 点击"结算"生成订单
5. 系统自动扣减余额并清空购物车

![输入图片说明](%E8%BF%90%E8%A1%8C%E7%BB%93%E6%9E%9C%E5%9B%BE%E7%89%87%E8%B4%AD%E7%89%A9%E8%BD%A6.png)

![输入图片说明](%E8%BF%90%E8%A1%8C%E7%BB%93%E6%9E%9C%E5%9B%BE%E7%89%87%E7%BB%93%E7%AE%97%E6%88%90%E5%8A%9F.png)

#### 6.4.4 个人中心
1. 点击右上角头像进入个人中心
2. 查看/编辑个人资料
3. 查看收藏夹、已购书籍、浏览历史
4. 进行余额充值

#### 6.4.5 海报生成
1. 在图书详情页点击"生成海报"
2. 系统自动生成600x800高清海报
3. 点击"保存到本地"下载海报

![输入图片说明](%E8%BF%90%E8%A1%8C%E7%BB%93%E6%9E%9C%E5%9B%BE%E7%89%87%E6%B5%B7%E6%8A%A5.png)

---

## 7. 测试结果

### 7.1 测试环境

| 项目 | 版本 |
|------|------|
| 操作系统 | Windows 11 |
| JDK | 21 |
| MySQL | 8.0 |
| Node.js | 18 |
| Chrome | 最新版 |

### 7.2 单元测试

后端使用 JUnit 5 + Mockito 进行单元测试：

| 测试类 | 测试方法数 | 覆盖模块 |
|--------|-----------|----------|
| AuthServiceTest | 12 | 认证服务 |
| BookServiceTest | 8 | 图书服务 |
| CartServiceTest | 10 | 购物车服务 |
| OrderServiceTest | 8 | 订单服务 |
| UserServiceTest | 10 | 用户服务 |
| EmailServiceTest | 6 | 邮件服务 |

**测试命令**：
```bash
mvn test
```

![输入图片说明](%E8%BF%90%E8%A1%8C%E7%BB%93%E6%9E%9C%E5%9B%BE%E7%89%87test.png)

![输入图片说明](%E8%BF%90%E8%A1%8C%E7%BB%93%E6%9E%9C%E5%9B%BE%E7%89%87Swagger%20UI.png)

### 7.3 集成测试

`FullFlowIntegrationTest` 覆盖完整业务流程：

1. 用户注册 → 登录
2. 浏览图书 → 添加收藏
3. 添加购物车 → 结算下单
4. 查看已购书籍

### 7.4 功能测试结果

| 功能模块 | 测试项 | 结果 |
|----------|--------|------|
| 用户注册 | 邮箱验证、密码加密 | ✓ 通过 |
| 用户登录 | Token生成、过期处理 | ✓ 通过 |
| 图书浏览 | 分页、筛选、搜索、排序 | ✓ 通过 |
| 购物车 | 增删改查、数量调整 | ✓ 通过 |
| 订单结算 | 余额扣减、订单生成 | ✓ 通过 |
| 收藏管理 | 添加、取消、列表 | ✓ 通过 |
| 浏览历史 | 记录、去重、上限12条 | ✓ 通过 |
| 海报生成 | Canvas渲染、保存 | ✓ 通过 |
| 深色模式 | 主题切换 | ✓ 通过 |

### 7.5 性能测试

| 接口 | 平均响应时间 | 并发数 |
|------|-------------|--------|
| GET /api/books | 45ms | 100 |
| GET /api/books/{id} | 23ms | 100 |
| POST /api/cart/items | 35ms | 100 |
| POST /api/orders/checkout | 120ms | 50 |

---

## 8. AI工具使用总结

### 8.1 使用的AI工具

| 工具名称 | 版本 | 使用场景 |
|----------|------|----------|
| Gemini | 最新版 | 前端代码生成（React组件、样式、动画） | 
| Codex | 最新版 | 后端Goal模式开发、多Agent协作、调试修复 | 
| Claude Code | 最新版 | 代码审查、Bug修复、文档编写、单元测试生成 | 
| CodeGraph MCP | - | 代码结构分析、符号查找、调用链追踪 |

### 8.2 AI辅助开发场景

#### 8.2.1 前端开发（Gemini）

Gemini主要用于前端代码的初始生成：

- **React组件生成**：根据设计稿或需求描述生成React组件骨架
- **Tailwind CSS样式**：生成响应式布局和动画效果
- **TypeScript类型定义**：生成接口类型和数据结构定义
- **页面交互逻辑**：生成状态管理和事件处理代码

**使用流程**：
1. 向Gemini描述页面需求和设计风格
2. 生成初始代码后人工审查和调整
3. 根据实际效果迭代优化

#### 8.2.2 后端开发（Codex Goal模式）

Codex的Goal模式用于后端功能的完整实现：

- **Goal模式**：设定目标（如"实现用户注册功能"），AI自动规划并实现完整流程
- **多Agent协作**：多个Agent并行处理不同模块（Controller、Service、Mapper）
- **代码生成**：根据数据库Schema自动生成Entity、DTO、Mapper XML

**Codex Goal模式编写规范**：

1. **Goal描述规范**
   ```
   目标：<动词> + <功能模块> + <约束条件>
   
   示例：
   - 实现用户注册功能，需包含邮箱验证码验证
   - 实现购物车结算功能，需使用原子SQL扣减余额
   - 实现图书分页查询，支持关键词、分类、排序筛选
   ```

2. **Agent分工规范**

   | Agent角色 | 职责范围 | 输出产物 |
   |-----------|----------|----------|
   | Controller Agent | 接口层代码 | Controller.java |
   | Service Agent | 业务逻辑层 | Service接口 + Impl实现 |
   | Mapper Agent | 数据访问层 | Mapper.java + Mapper.xml |
   | Entity Agent | 实体和DTO | Entity.java + DTO.java |
   | Test Agent | 单元测试 | *Test.java |

3. **多Agent协作范围**

   ```
   ┌─────────────────────────────────────────────────────────┐
   │                    Codex Goal模式                        │
   │                                                         │
   │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
   │  │Agent 1  │  │Agent 2  │  │Agent 3  │  │Agent 4  │   │
   │  │Controller│  │Service  │  │Mapper   │  │Test     │   │
   │  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘   │
   │       │            │            │            │         │
   │       ▼            ▼            ▼            ▼         │
   │  ┌─────────────────────────────────────────────────┐   │
   │  │              共享上下文                           │   │
   │  │  - 数据库Schema                                  │   │
   │  │  - 已有代码结构                                  │   │
   │  │  - 接口规范                                      │   │
   │  └─────────────────────────────────────────────────┘   │
   └─────────────────────────────────────────────────────────┘
   ```

4. **AI介入范围规范**

   | 阶段 | AI可介入 | 人工必须参与 |
   |------|----------|--------------|
   | 需求分析 | ❌ | ✅ 明确功能需求 |
   | 技术方案 | ⚠️ 提供建议 | ✅ 最终决策 |
   | 代码生成 | ✅ 主要完成 | ✅ 代码审查 |
   | 单元测试 | ✅ 生成测试 | ✅ 验证覆盖 |
   | 调试修复 | ✅ 定位问题 | ✅ 确认方案 |
   | 文档编写 | ✅ 主要完成 | ✅ 内容审核 |

**Goal模式示例**：
```
目标：实现邮箱验证码注册功能

Agent分工：
- Agent 1 (Controller): 生成AuthController的sendCode和register接口
- Agent 2 (Service): 生成EmailServiceImpl验证码发送逻辑
- Agent 3 (Mapper): 生成EmailVerificationMapper和XML
- Agent 4 (Test): 生成AuthServiceTest单元测试

共享上下文：
- 数据库：email_verifications表结构
- 已有：AuthService接口定义
- 规范：统一响应格式ApiResponse
```

**AI开发规范（AGENTS.md）**：

为确保AI生成的代码质量，项目制定了专门的AGENTS.md规范文件，作为AI工具的开发约束：

1. **分层架构规范**

   ```
   com.example.backend
   ├── config          # 配置类（Swagger、CORS、MyBatis）
   ├── controller      # REST Controller，只处理HTTP入参出参
   ├── service         # 业务接口
   ├── service.impl    # 业务实现，承载核心逻辑
   ├── mapper          # MyBatis Mapper接口
   ├── entity          # 数据库实体
   ├── dto             # 请求/响应DTO
   ├── vo              # 面向前端的视图对象
   ├── common          # 通用返回对象、分页对象
   ├── exception       # 自定义异常、全局异常处理
   └── util            # 通用无状态工具类
   ```

   **分层职责约束**：
   - Controller层不得直接访问Mapper
   - Service层负责业务编排、事务控制
   - Mapper层只负责数据库访问
   - DTO/VO/Entity不混用

2. **RESTful API规范**

   | 规范项 | 要求 |
   |--------|------|
   | 路径前缀 | 统一以 `/api` 开头 |
   | 资源命名 | 使用名词复数，避免动词 |
   | HTTP方法 | GET查询、POST新增、PUT整体更新、PATCH局部更新、DELETE删除 |
   | 分页参数 | 统一使用 `page`、`size`，页码从1开始 |
   | 时间格式 | ISO-8601或约定格式 |

3. **统一响应与错误处理**

   ```json
   {
     "code": 200,
     "message": "success",
     "data": {},
     "timestamp": "2026-05-28T12:00:00"
   }
   ```

   **错误码分类**：
   - 200：成功
   - 400xx：参数或请求错误
   - 401xx：认证失败或登录过期
   - 403xx：权限不足
   - 404xx：资源不存在
   - 409xx：资源冲突或重复提交
   - 500xx：服务端内部错误

4. **参数校验与安全规范**

   - 请求DTO使用Bean Validation注解（@NotNull、@NotBlank、@Size、@Email）
   - Controller入参使用@Valid或@Validated
   - 后端必须进行必要校验，不依赖前端校验
   - 禁止硬编码密码、Token等敏感信息

5. **代码质量要求**

   - 类名、方法名、变量名遵循Java命名规范
   - 控制器方法保持短小，复杂逻辑下沉到Service
   - 避免重复代码，通用逻辑沉淀到common/util
   - 注释用于解释关键业务规则，而非重复代码含义

6. **测试规范**

   ```
   开发顺序：
   1. 先进行单元模块测试
   2. 单元测试通过后进行集成测试
   3. 最后与前端进行系统联调
   ```

   - Service层核心业务必须有单元测试
   - Controller层建议使用MockMvc测试
   - 每次重要修改后至少运行 `mvn test`

7. **前后端协作规范**

   - 后端接口字段名应稳定、语义清晰
   - 返回数据结构应便于Axios拦截器处理
   - 接口变更必须说明兼容性影响
   - 联调问题优先通过API文档定位

8. **开发工作流规范**

   ```
   修改代码前 → 了解现有结构
   新增接口时 → 同步完成Controller、Service、Mapper、DTO/VO、异常处理、文档注解和测试
   修改公共结构 → 检查影响范围
   完成后 → 运行相关测试，写明验证结果
   ```

#### 8.2.4 调试修复（Codex + Claude）

Codex和Claude共同用于问题的定位和修复：

- **错误定位**：分析错误堆栈，快速定位问题根源
- **方案对比**：提供多种修复方案并分析优劣
- **代码修复**：直接生成修复后的代码
- **单元测试补充**：为修复的Bug生成对应的单元测试

**调试案例**：
1. Windows中文路径Maven启动失败 → Claude分析pom.xml配置
2. 登录态丢失问题 → Codex分析前端状态管理逻辑
3. 单元测试编译错误 → Claude修复Mockito用法

#### 8.2.5 文档编写（Claude Code）

Claude Code用于项目文档的编写：

- **API文档生成**：根据代码注释自动生成API接口文档
- **README编写**：生成项目说明文档
- **课程设计报告**：根据代码结构和git历史生成报告
- **注释补充**：为复杂逻辑添加详细注释

### 8.3 AI工具使用效果

#### 8.3.1 效率对比

| 指标 | 无AI辅助 | 有AI辅助 | 提升比例 | 主要工具 |
|------|----------|----------|----------|----------|
| 前端页面开发 | 基准 | 3x | 200% | Gemini |
| 后端接口开发 | 基准 | 2.5x | 150% | Codex Goal模式 |
| Bug修复时间 | 基准 | 0.3x | 70% | Codex + Claude |
| 文档编写时间 | 基准 | 0.2x | 80% | Claude Code |
| 单元测试编写 | 基准 | 0.4x | 60% | Claude Code |

#### 8.3.2 各工具优势对比

| 工具 | 优势 | 适用场景 |
|------|------|----------|
| Gemini | 前端代码生成质量高，样式美观 | React组件、CSS样式、动画效果 |
| Codex Goal模式 | 自动规划实现路径，多Agent并行 | 完整功能模块开发 |
| Claude Code | 代码理解深入，调试能力强 | 代码审查、Bug修复、文档生成 |



### 8.4 使用心得

#### 8.4.1 Gemini使用心得

1. **前端生成效率高**：Gemini对React组件和Tailwind CSS的生成质量很高，能快速产出美观的UI
2. **需要人工调整**：生成的代码需要根据实际需求进行微调，特别是交互逻辑
3. **迭代优化**：通过多次对话可以逐步完善页面效果

#### 8.4.2 Codex使用心得

1. **Goal模式强大**：设定目标后AI能自动规划实现路径，减少手动编码
2. **多Agent协作**：多个Agent并行处理不同模块，大幅提升开发速度
3. **需要明确指令**：Goal描述越清晰，生成的代码质量越高
4. **调试能力强**：能快速定位问题并提供修复方案

#### 8.4.3 Claude Code使用心得

1. **代码理解深入**：对项目结构和代码逻辑的理解很准确
2. **调试效率高**：能快速分析错误堆栈并定位问题根源
3. **文档生成优秀**：能根据代码自动生成高质量的文档
4. **安全审查**：能识别潜在的安全漏洞和代码规范问题

#### 8.4.4 综合建议

1. **工具组合使用**：不同工具各有优势，组合使用效果最佳
2. **理解代码逻辑**：不能直接提交AI生成的代码，必须理解并能够解释每行代码
3. **人工审核必要**：AI生成的代码可能存在业务逻辑错误，需要人工验证
4. **持续学习**：AI工具是辅助，不能替代对编程知识的学习和理解

### 8.5 注意事项

1. **理解代码逻辑**：不能直接提交AI生成的代码，必须理解并能够解释每行代码
2. **人工审核必要**：AI生成的代码可能存在业务逻辑错误，需要人工验证
3. **安全敏感代码**：涉及密码、Token等安全敏感的代码需要特别审查
4. **持续学习**：AI工具是辅助，不能替代对编程知识的学习和理解

---

## 9. 总结与展望

### 9.1 项目总结

本项目成功设计并实现了"拾光书店"在线购书网站，主要成果包括：

1. **功能完整**：实现了图书浏览、购物车、订单、用户系统等完整功能
2. **技术先进**：采用前后端分离架构，使用主流技术栈
3. **用户体验**：温暖文艺的设计风格，流畅的交互动画
4. **代码质量**：规范的代码结构，完善的异常处理
5. **文档齐全**：详细的API文档，规范的代码注释

### 9.2 技术收获

1. **前端技术**：掌握了React、TypeScript、Tailwind CSS的使用
2. **后端技术**：深入理解了Spring Boot、MyBatis的架构设计
3. **数据库设计**：学会了规范化设计和索引优化
4. **前后端协作**：掌握了RESTful API设计规范
5. **AI辅助开发**：体验了AI工具在软件开发中的应用

### 9.3 不足与改进

| 不足 | 改进方向 |
|------|----------|
| 未接入真实支付 | 集成支付宝/微信支付 |
| 缺少商品库存管理 | 添加库存字段和库存扣减逻辑 |
| 无商品评价功能 | 设计评价表和评价接口 |
| 搜索功能简单 | 集成Elasticsearch实现全文搜索 |
| 无消息通知 | 添加WebSocket实时通知 |

### 9.4 未来展望

1. **功能扩展**
   - 接入第三方支付
   - 添加商品评价和评分系统
   - 实现优惠券和促销活动
   - 添加社交分享功能

2. **性能优化**
   - 引入Redis缓存热点数据
   - 使用消息队列处理异步任务
   - 数据库读写分离
   - CDN加速静态资源

3. **架构升级**
   - 微服务化改造
   - 容器化部署（Docker）
   - CI/CD自动化流水线
   - 监控告警系统

4. **智能化**
   - 基于用户行为的个性化推荐
   - 智能客服机器人
   - 数据分析和运营报表

---

## 10. 附录与参考资料

### 10.1 参考资料

1. Spring Boot官方文档：https://spring.io/projects/spring-boot
2. React官方文档：https://react.dev
3. MyBatis官方文档：https://mybatis.org/mybatis-3/
4. Tailwind CSS官方文档：https://tailwindcss.com
5. MySQL官方文档：https://dev.mysql.com/doc/

### 10.2 项目源码

- 后端：`src/main/java/com/example/backend/`
- 前端：`src/` (React组件和API)
- 数据库脚本：`src/main/resources/schema.sql`、`data.sql`

### 10.3 错误码一览

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 40000 | 请求参数错误 |
| 40001 | 购物车为空 |
| 40002 | 库存不足 |
| 40003 | 充值金额仅支持固定档位 |
| 40010 | 验证码已过期 |
| 40011 | 验证码无效 |
| 40012 | 发送验证码过于频繁 |
| 40100 | 请先登录 |
| 40101 | 密码错误 |
| 40300 | 权限不足 |
| 40400 | 资源不存在 |
| 40401 | 图书不存在 |
| 40402 | 邮箱未注册 |
| 40900 | 资源状态冲突 |
| 40901 | 邮箱已被注册 |
| 40902 | 余额不足 |
| 50000 | 服务端内部错误 |

---

## 11. API接口规格文档

### 11.1 概述

**基础信息**

| 项目 | 说明 |
|------|------|
| 基础URL | `http://localhost:8080/api` |
| 数据格式 | JSON |
| 字符编码 | UTF-8 |
| 认证方式 | Bearer Token (JWT) |

**认证说明**

需要认证的接口需在请求头中携带：
```
Authorization: Bearer <token>
```

**统一响应格式**

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": "2025-01-01T00:00:00"
}
```

**分页响应格式**

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [],
    "page": 1,
    "size": 10,
    "total": 52,
    "totalPages": 6
  }
}
```

---

### 11.2 认证接口 `/api/auth`

#### 11.2.1 用户注册

**接口说明**：新用户注册，需要邮箱验证码

**请求信息**
- 方法：`POST`
- 路径：`/api/auth/register`
- 认证：不需要

**请求参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| email | String | 是 | 邮箱 | user@example.com |
| password | String | 是 | 密码(6-20位) | 123456 |
| nickname | String | 否 | 昵称 | 书虫 |
| code | String | 是 | 邮箱验证码 | 123456 |

**请求示例**
```json
{
  "email": "user@example.com",
  "password": "123456",
  "nickname": "书虫",
  "code": "123456"
}
```

**响应参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| token | String | 访问令牌 |
| userId | Long | 用户ID |
| nickname | String | 用户昵称 |
| email | String | 用户邮箱 |

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userId": 1,
    "nickname": "书虫",
    "email": "user@example.com"
  },
  "timestamp": "2025-01-01T00:00:00"
}
```

**错误说明**

| 错误码 | 说明 |
|--------|------|
| 40901 | 邮箱已被注册 |
| 40010 | 验证码已过期 |
| 40011 | 验证码无效 |
| 40000 | 请求参数错误 |

---

#### 11.2.2 用户登录

**接口说明**：用户登录获取Token

**请求信息**
- 方法：`POST`
- 路径：`/api/auth/login`
- 认证：不需要

**请求参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| email | String | 是 | 邮箱 | user@example.com |
| password | String | 是 | 密码 | 123456 |

**请求示例**
```json
{
  "email": "user@example.com",
  "password": "123456"
}
```

**响应参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| token | String | 访问令牌 |
| userId | Long | 用户ID |
| nickname | String | 用户昵称 |
| email | String | 用户邮箱 |

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userId": 1,
    "nickname": "书虫",
    "email": "user@example.com"
  },
  "timestamp": "2025-01-01T00:00:00"
}
```

**错误说明**

| 错误码 | 说明 |
|--------|------|
| 40402 | 邮箱未注册 |
| 40101 | 密码错误 |

---

#### 11.2.3 用户退出

**接口说明**：退出登录，删除Token

**请求信息**
- 方法：`POST`
- 路径：`/api/auth/logout`
- 认证：需要

**请求头**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| Authorization | String | 是 | Bearer Token |

**响应示例**
```json
{
  "code": 200,
  "message": "退出成功",
  "data": null,
  "timestamp": "2025-01-01T00:00:00"
}
```

---

#### 11.2.4 发送邮箱验证码

**接口说明**：发送6位数字验证码到邮箱，有效期5分钟

**请求信息**
- 方法：`POST`
- 路径：`/api/auth/send-code`
- 认证：不需要

**请求参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| email | String | 是 | 邮箱 | user@example.com |

**请求示例**
```json
{
  "email": "user@example.com"
}
```

**响应示例**
```json
{
  "code": 200,
  "message": "验证码已发送",
  "data": null,
  "timestamp": "2025-01-01T00:00:00"
}
```

**错误说明**

| 错误码 | 说明 |
|--------|------|
| 40012 | 发送验证码过于频繁 |

---

#### 11.2.5 重置密码

**接口说明**：通过邮箱验证码重置密码

**请求信息**
- 方法：`POST`
- 路径：`/api/auth/reset-password`
- 认证：不需要

**请求参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| email | String | 是 | 邮箱 | user@example.com |
| password | String | 是 | 新密码(6-20位) | newPassword123 |
| code | String | 是 | 邮箱验证码 | 123456 |

**请求示例**
```json
{
  "email": "user@example.com",
  "password": "newPassword123",
  "code": "123456"
}
```

**响应示例**
```json
{
  "code": 200,
  "message": "密码已重置",
  "data": null,
  "timestamp": "2025-01-01T00:00:00"
}
```

**错误说明**

| 错误码 | 说明 |
|--------|------|
| 40402 | 邮箱未注册 |
| 40010 | 验证码已过期 |
| 40011 | 验证码无效 |

---

### 11.3 图书接口 `/api/books`

#### 11.3.1 查询图书列表

**接口说明**：按关键词、分类、排序方式分页查询图书

**请求信息**
- 方法：`GET`
- 路径：`/api/books`
- 认证：不需要

**请求参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| keyword | String | 否 | 关键词(书名/作者) | 红楼梦 |
| category | String | 否 | 分类 | 文学 |
| sortBy | String | 否 | 排序方式 | price_asc |
| page | Integer | 否 | 页码(从1开始) | 1 |
| size | Integer | 否 | 每页条数 | 10 |

**排序方式说明**

| 值 | 说明 |
|----|------|
| price_asc | 价格升序 |
| price_desc | 价格降序 |
| rating | 评分降序 |
| date | 出版日期降序 |

**请求示例**
```
GET /api/books?category=文学&sortBy=rating&page=1&size=10
```

**响应参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| list | Array | 图书列表 |
| page | Integer | 当前页码 |
| size | Integer | 每页条数 |
| total | Long | 总条数 |
| totalPages | Integer | 总页数 |

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": "1",
        "title": "红楼梦",
        "author": "曹雪芹",
        "publisher": "人民文学出版社",
        "isbn": "9787020002207",
        "pages": 1606,
        "publishDate": "1996-12",
        "originalPrice": 59.70,
        "currentPrice": 47.80,
        "rating": 9.6,
        "ratingCount": 1234,
        "category": "文学",
        "synopsis": "...",
        "quote": "...",
        "authorIntro": "...",
        "coverPattern": "geometric",
        "coverColor": "#E74C3C",
        "isBestseller": true,
        "isNewArrival": false,
        "recommended": true
      }
    ],
    "page": 1,
    "size": 10,
    "total": 33,
    "totalPages": 4
  },
  "timestamp": "2025-01-01T00:00:00"
}
```

---

#### 11.3.2 查询图书详情

**接口说明**：根据图书ID查询详细信息

**请求信息**
- 方法：`GET`
- 路径：`/api/books/{id}`
- 认证：不需要

**路径参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| id | String | 是 | 图书ID | 1 |

**请求示例**
```
GET /api/books/1
```

**响应参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | String | 图书ID |
| title | String | 书名 |
| author | String | 作者 |
| publisher | String | 出版社 |
| isbn | String | ISBN |
| pages | Integer | 页数 |
| publishDate | String | 出版日期 |
| originalPrice | BigDecimal | 原价 |
| currentPrice | BigDecimal | 现价 |
| rating | BigDecimal | 评分 |
| ratingCount | Integer | 评价人数 |
| category | String | 分类 |
| synopsis | String | 简介 |
| quote | String | 金句 |
| authorIntro | String | 作者简介 |
| coverPattern | String | 封面样式 |
| coverColor | String | 封面颜色 |
| isBestseller | Boolean | 是否畅销 |
| isNewArrival | Boolean | 是否新书 |
| recommended | Boolean | 是否推荐 |

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "1",
    "title": "红楼梦",
    "author": "曹雪芹",
    "publisher": "人民文学出版社",
    "isbn": "9787020002207",
    "pages": 1606,
    "publishDate": "1996-12",
    "originalPrice": 59.70,
    "currentPrice": 47.80,
    "rating": 9.6,
    "ratingCount": 1234,
    "category": "文学",
    "synopsis": "《红楼梦》是中国古典四大名著之首...",
    "quote": "满纸荒唐言，一把辛酸泪。",
    "authorIntro": "曹雪芹，名沾，字梦阮...",
    "coverPattern": "geometric",
    "coverColor": "#E74C3C",
    "isBestseller": true,
    "isNewArrival": false,
    "recommended": true
  },
  "timestamp": "2025-01-01T00:00:00"
}
```

**错误说明**

| 错误码 | 说明 |
|--------|------|
| 40401 | 图书不存在 |

---

#### 11.3.3 查询推荐图书

**接口说明**：获取推荐图书列表，最多8本

**请求信息**
- 方法：`GET`
- 路径：`/api/books/recommended`
- 认证：不需要

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "1",
      "title": "红楼梦",
      "author": "曹雪芹",
      "currentPrice": 47.80,
      "rating": 9.6,
      "category": "文学",
      "coverPattern": "geometric",
      "coverColor": "#E74C3C"
    }
  ],
  "timestamp": "2025-01-01T00:00:00"
}
```

---

#### 11.3.4 查询畅销图书

**接口说明**：获取畅销图书列表，最多8本

**请求信息**
- 方法：`GET`
- 路径：`/api/books/bestsellers`
- 认证：不需要

**响应格式**：同推荐图书

---

#### 11.3.5 查询新书

**接口说明**：获取新书上架列表，最多12本

**请求信息**
- 方法：`GET`
- 路径：`/api/books/new-arrivals`
- 认证：不需要

**响应格式**：同推荐图书

---

#### 11.3.6 查询所有分类

**接口说明**：获取所有图书分类

**请求信息**
- 方法：`GET`
- 路径：`/api/categories`
- 认证：不需要

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": ["文学", "社科", "科技", "历史", "经管"],
  "timestamp": "2025-01-01T00:00:00"
}
```

---

### 11.4 购物车接口 `/api/cart`

> 以下接口均需要认证

#### 11.4.1 获取购物车

**接口说明**：获取当前用户的购物车

**请求信息**
- 方法：`GET`
- 路径：`/api/cart`
- 认证：需要

**响应参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| items | Array | 购物车项列表 |
| totalQuantity | Integer | 总数量 |
| totalAmount | BigDecimal | 总金额 |

**购物车项参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| bookId | String | 图书ID |
| title | String | 书名 |
| author | String | 作者 |
| coverColor | String | 封面颜色 |
| coverPattern | String | 封面样式 |
| price | BigDecimal | 单价 |
| quantity | Integer | 数量 |
| subtotal | BigDecimal | 小计 |

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "items": [
      {
        "bookId": "1",
        "title": "红楼梦",
        "author": "曹雪芹",
        "coverColor": "#E74C3C",
        "coverPattern": "geometric",
        "price": 47.80,
        "quantity": 2,
        "subtotal": 95.60
      }
    ],
    "totalQuantity": 2,
    "totalAmount": 95.60
  },
  "timestamp": "2025-01-01T00:00:00"
}
```

---

#### 11.4.2 添加购物车项

**接口说明**：添加商品到购物车，已存在则数量+1

**请求信息**
- 方法：`POST`
- 路径：`/api/cart/items`
- 认证：需要

**请求参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| bookId | String | 是 | 图书ID | 1 |
| quantity | Integer | 否 | 数量(默认1) | 1 |

**请求示例**
```json
{
  "bookId": "1",
  "quantity": 1
}
```

**响应格式**：同获取购物车

**错误说明**

| 错误码 | 说明 |
|--------|------|
| 40401 | 图书不存在 |

---

#### 11.4.3 更新购物车项数量

**接口说明**：修改购物车中商品的数量，数量≤0时自动删除

**请求信息**
- 方法：`PATCH`
- 路径：`/api/cart/items/{bookId}?quantity={n}`
- 认证：需要

**路径参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| bookId | String | 是 | 图书ID | 1 |

**查询参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| quantity | Integer | 是 | 新数量 | 3 |

**请求示例**
```
PATCH /api/cart/items/1?quantity=3
```

**响应格式**：同获取购物车

---

#### 11.4.4 删除购物车项

**接口说明**：从购物车中删除指定商品

**请求信息**
- 方法：`DELETE`
- 路径：`/api/cart/items/{bookId}`
- 认证：需要

**路径参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| bookId | String | 是 | 图书ID | 1 |

**请求示例**
```
DELETE /api/cart/items/1
```

**响应格式**：同获取购物车

---

#### 11.4.5 清空购物车

**接口说明**：清空当前用户购物车中的所有商品

**请求信息**
- 方法：`DELETE`
- 路径：`/api/cart`
- 认证：需要

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": null,
  "timestamp": "2025-01-01T00:00:00"
}
```

---

### 11.5 订单接口 `/api/orders`

> 以下接口均需要认证

#### 11.5.1 结算购物车

**接口说明**：从购物车结算生成订单，扣减余额，清空购物车，写入已购书目

**请求信息**
- 方法：`POST`
- 路径：`/api/orders/checkout`
- 认证：需要

**响应参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| orderNo | String | 订单号 |
| totalAmount | BigDecimal | 总金额 |
| remainingBalance | BigDecimal | 结算后剩余余额 |
| status | String | 状态 |
| items | Array | 订单项列表 |
| createdAt | LocalDateTime | 创建时间 |

**订单项参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| bookId | String | 图书ID |
| bookTitle | String | 书名 |
| price | BigDecimal | 单价 |
| quantity | Integer | 数量 |

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "orderNo": "SG202501011200001234",
    "totalAmount": 95.60,
    "remainingBalance": 4.40,
    "status": "COMPLETED",
    "items": [
      {
        "bookId": "1",
        "bookTitle": "红楼梦",
        "price": 47.80,
        "quantity": 2
      }
    ],
    "createdAt": "2025-01-01T12:00:00"
  },
  "timestamp": "2025-01-01T00:00:00"
}
```

**错误说明**

| 错误码 | 说明 |
|--------|------|
| 40001 | 购物车为空 |
| 40902 | 余额不足 |

---

### 11.6 用户接口 `/api/users`

> 以下接口均需要认证

#### 11.6.1 获取当前用户资料

**接口说明**：获取当前登录用户的资料

**请求信息**
- 方法：`GET`
- 路径：`/api/users/me`
- 认证：需要

**响应参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | Long | 用户ID |
| email | String | 邮箱 |
| nickname | String | 昵称 |
| avatarUrl | String | 头像URL |

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": 1,
    "email": "user@example.com",
    "nickname": "书虫",
    "avatarUrl": null
  },
  "timestamp": "2025-01-01T00:00:00"
}
```

---

#### 11.6.2 更新当前用户资料

**接口说明**：更新用户昵称和头像

**请求信息**
- 方法：`PUT`
- 路径：`/api/users/me/profile`
- 认证：需要

**请求参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| nickname | String | 否 | 昵称(最长100) | 新昵称 |
| avatarUrl | String | 否 | 头像URL | https://example.com/avatar.jpg |

**请求示例**
```json
{
  "nickname": "新昵称",
  "avatarUrl": "https://example.com/avatar.jpg"
}
```

**响应格式**：同获取用户资料

---

#### 11.6.3 获取当前用户余额

**接口说明**：查询用户账户余额

**请求信息**
- 方法：`GET`
- 路径：`/api/users/me/balance`
- 认证：需要

**响应参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| balance | BigDecimal | 当前余额 |

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "balance": 100.00
  },
  "timestamp": "2025-01-01T00:00:00"
}
```

---

#### 11.6.4 模拟充值

**接口说明**：用户余额充值（仅支持固定档位：10、20、50、100）

**请求信息**
- 方法：`POST`
- 路径：`/api/users/me/balance/recharge`
- 认证：需要

**请求参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| amount | BigDecimal | 是 | 充值金额 | 100 |

**请求示例**
```json
{
  "amount": 100
}
```

**响应格式**：同获取余额

**错误说明**

| 错误码 | 说明 |
|--------|------|
| 40003 | 充值金额仅支持固定档位 10、20、50、100 |

---

#### 11.6.5 获取收藏列表

**接口说明**：获取用户收藏的图书列表

**请求信息**
- 方法：`GET`
- 路径：`/api/users/me/bookmarks`
- 认证：需要

**响应格式**：图书对象数组

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "1",
      "title": "红楼梦",
      "author": "曹雪芹",
      "currentPrice": 47.80,
      "rating": 9.6
    }
  ],
  "timestamp": "2025-01-01T00:00:00"
}
```

---

#### 11.6.6 添加收藏

**接口说明**：收藏指定图书

**请求信息**
- 方法：`POST`
- 路径：`/api/users/me/bookmarks/{bookId}`
- 认证：需要

**路径参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| bookId | String | 是 | 图书ID | 1 |

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": null,
  "timestamp": "2025-01-01T00:00:00"
}
```

---

#### 11.6.7 取消收藏

**接口说明**：取消收藏指定图书

**请求信息**
- 方法：`DELETE`
- 路径：`/api/users/me/bookmarks/{bookId}`
- 认证：需要

**路径参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| bookId | String | 是 | 图书ID | 1 |

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": null,
  "timestamp": "2025-01-01T00:00:00"
}
```

---

#### 11.6.8 获取浏览历史

**接口说明**：获取用户浏览历史，最多12条

**请求信息**
- 方法：`GET`
- 路径：`/api/users/me/history`
- 认证：需要

**响应格式**：图书对象数组（按浏览时间倒序）

---

#### 11.6.9 添加浏览记录

**接口说明**：记录用户浏览图书，自动去重

**请求信息**
- 方法：`POST`
- 路径：`/api/users/me/history/{bookId}`
- 认证：需要

**路径参数**

| 参数名 | 类型 | 必填 | 说明 | 示例 |
|--------|------|------|------|------|
| bookId | String | 是 | 图书ID | 1 |

**业务规则**：每用户最多保留12条，超出自动删除最早的

---

#### 11.6.10 获取已购书目

**接口说明**：获取用户已购买的图书列表

**请求信息**
- 方法：`GET`
- 路径：`/api/users/me/purchased-books`
- 认证：需要

**响应格式**：图书对象数组

---

### 11.7 语录接口 `/api/quotes`

#### 11.7.1 获取每日语录

**接口说明**：获取所有每日语录

**请求信息**
- 方法：`GET`
- 路径：`/api/quotes/daily`
- 认证：不需要

**响应参数**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| text | String | 语录内容 |
| source | String | 来源 |

**响应示例**
```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "text": "满纸荒唐言，一把辛酸泪。都云作者痴，谁解其中味。",
      "source": "《红楼梦》"
    },
    {
      "text": "人生若只如初见，何事秋风悲画扇。",
      "source": "《木兰花·拟古决绝词柬友》"
    }
  ],
  "timestamp": "2025-01-01T00:00:00"
}
```

---

### 11.8 错误码汇总

| 错误码 | HTTP状态码 | 说明 |
|--------|-----------|------|
| 200 | 200 | 成功 |
| 40000 | 400 | 请求参数错误 |
| 40001 | 400 | 购物车为空 |
| 40002 | 400 | 库存不足 |
| 40003 | 400 | 充值金额仅支持固定档位 |
| 40010 | 400 | 验证码已过期 |
| 40011 | 400 | 验证码无效 |
| 40012 | 400 | 发送验证码过于频繁 |
| 40100 | 401 | 请先登录 |
| 40101 | 401 | 密码错误 |
| 40300 | 403 | 权限不足 |
| 40400 | 404 | 资源不存在 |
| 40401 | 404 | 图书不存在 |
| 40402 | 404 | 邮箱未注册 |
| 40900 | 409 | 资源状态冲突 |
| 40901 | 409 | 邮箱已被注册 |
| 40902 | 409 | 余额不足 |
| 50000 | 500 | 服务端内部错误 |

---

### 11.9 接口调用示例

#### cURL示例

**用户登录**
```bash
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"123456"}'
```

**获取图书列表**
```bash
curl http://localhost:8080/api/books?category=文学&page=1&size=10
```

**添加购物车（需Token）**
```bash
curl -X POST http://localhost:8080/api/cart/items \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{"bookId":"1","quantity":1}'
```

**结算订单**
```bash
curl -X POST http://localhost:8080/api/orders/checkout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

---