# 校园二手书交易系统 — 服务端详细设计文档

> 版本：1.0  
> 对应设计：`design.md` 第 4 章

---

## 1. 分层架构

```
space.anyi.server
├── ServerApplication.java          — Spring Boot 入口
├── config/                         — 配置层
│   ├── WebConfig.java              — CORS 跨域配置
│   ├── MyBatisPlusConfig.java      — MyBatis-Plus 分页插件
│   └── GlobalExceptionHandler.java — 全局异常处理
├── controller/                     — Controller 层（REST 接口）
│   ├── UserController.java
│   ├── BookController.java
│   ├── TransactionController.java
│   ├── StatisticsController.java
│   └── AiController.java
├── service/                        — Service 接口层
│   ├── UserService.java
│   ├── BookService.java
│   ├── TransactionService.java
│   ├── StatisticsService.java
│   └── AiService.java
├── service/impl/                   — Service 实现层
│   ├── UserServiceImpl.java
│   ├── BookServiceImpl.java
│   ├── TransactionServiceImpl.java
│   ├── StatisticsServiceImpl.java
│   └── AiServiceImpl.java
└── mapper/                         — Mapper 层（数据访问）
    ├── UserMapper.java
    ├── BookMapper.java
    ├── TransactionRecordMapper.java
    └── StatisticsMapper.java
```

### 1.1 各层职责

| 层次 | 职责 |
|------|------|
| **Config** | CORS 跨域、MyBatis-Plus 分页拦截器、全局异常处理 |
| **Controller** | `@RestController`，请求映射、参数解析、调用 Service 并封装 `R<T>` 响应 |
| **Service 接口** | 业务逻辑抽象，继承 `IService` 获得通用 CRUD |
| **Service 实现** | 核心业务逻辑、事务控制（`@Transactional`）、组合 Mapper 调用 |
| **Mapper** | `BaseMapper` 扩展提供 CRUD，`@Select` 自定义 SQL 提供统计查询 |

### 1.2 依赖关系

```
Controller → Service → Mapper → MySQL
```

所有 API 返回统一响应格式 `R<T>`（定义在 `common` 模块）。

### 1.3 Maven 依赖（server/pom.xml）

| 依赖 | 说明 |
|------|------|
| `spring-boot-starter-web` | Spring Boot Web 容器 |
| `mybatis-plus-spring-boot3-starter` | MyBatis-Plus ORM（适配 Spring Boot 3） |
| `mybatis-plus-jsqlparser` | MyBatis-Plus SQL 解析器（分页插件依赖） |
| `mysql-connector-j` | MySQL JDBC 驱动 |
| `lombok` | 编译期注解生成 getter/setter |
| `common` | 项目共享模块（实体、DTO、枚举） |

---

## 2. 配置层

### 2.1 WebConfig.java — CORS 跨域

允许所有来源的跨域请求，用于开发环境 JavaFX 客户端直连服务端。

```java
registry.addMapping("/**")
        .allowedOriginPatterns("*")
        .allowedMethods("*")
        .allowedHeaders("*")
        .allowCredentials(true);
```

### 2.2 MyBatisPlusConfig.java — 分页插件

注册 `PaginationInnerInterceptor(DbType.MYSQL)`，自动拦截并改写分页 SQL。

配合 `application.yml` 配置：

```yaml
mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
  global-config:
    db-config:
      id-type: auto
```

### 2.3 GlobalExceptionHandler.java — 全局异常处理

| 异常 | 响应 |
|------|------|
| `DuplicateKeyException` | `R.error("用户名已存在")` → code=400 |
| `IllegalArgumentException` | `R.error(e.getMessage())` → code=400 |
| `Exception`（兜底） | `R.error("服务器内部错误: " + e.getMessage())` → code=500 |

---

## 3. 公共模块（common）

### 3.1 实体类（`space.anyi.common.entity`）

#### User

| 字段 | 类型 | 说明 |
|------|------|------|
| `userid` | Integer | PK，自增 |
| `username` | String | 用户名 |
| `password` | String | 密码 |
| `nickname` | String | 昵称 |
| `email` | String | 邮箱 |
| `phone` | String | 电话 |
| `dept` | String | 院系 |
| `credit` | Integer | 信用分，默认 100 |
| `role` | Integer | 角色（0=学生, 1=管理员） |
| `isSeller` | Integer | `@TableField("is_seller")`，是否为卖家（0=否, 1=是） |
| `createdAt` | LocalDateTime | 注册时间 |

#### Book

| 字段 | 类型 | 说明 |
|------|------|------|
| `bookId` | Integer | PK，自增 |
| `sellerId` | Integer | 卖家 ID（逻辑外键 → user.userid） |
| `title` | String | 书名 |
| `author` | String | 作者 |
| `category` | String | 分类 |
| `originalPrice` | BigDecimal | 原价 |
| `sellingPrice` | BigDecimal | 售价 |
| `imageUrl` | String | 图片 URL（预留） |
| `createdAt` | LocalDateTime | 上架时间 |
| `stock` | Integer | 库存数量 |
| `status` | Integer | `@TableField("status")`，0=待审核, 1=已上架, 2=已下架 |

#### TransactionRecord

| 字段 | 类型 | 说明 |
|------|------|------|
| `transId` | Integer | PK，自增 |
| `bookId` | Integer | 书籍 ID（逻辑外键 → book.book_id） |
| `buyerId` | Integer | 买家 ID（逻辑外键 → user.userid） |
| `transactionNum` | Integer | 购买数量 |
| `transactionPrice` | BigDecimal | 交易总价（= sellingPrice × quantity） |
| `transactionTime` | LocalDateTime | 交易时间 |

### 3.2 DTO 类（`space.anyi.common.dto`）

#### R\<T\> — 统一响应

```json
{"code": 200, "message": "success", "data": ...}
```

| 静态方法 | 说明 |
|----------|------|
| `R.ok(data)` | 成功，code=200 |
| `R.ok()` | 成功无数据 |
| `R.error(message)` | 错误，code=400 |
| `R.error(code, message)` | 自定义错误码 |

#### PageResult\<T\> — 分页结果

```json
{"records": [...], "total": 100, "size": 20, "current": 1}
```

#### LoginRequest

```json
{"username": "string", "password": "string"}
```

#### RegisterRequest

```json
{"username": "string", "password": "string", "nickname": "string", "email": "string", "phone": "string", "dept": "string"}
```

#### SalesRecordDTO

| 字段 | 类型 | 说明 |
|------|------|------|
| `bookId` | Integer | 书籍ID |
| `title` | String | 书名 |
| `buyerId` | Integer | 买家ID |
| `buyerName` | String | 买家昵称（JOIN user 表） |
| `quantity` | Integer | 购买数量 |
| `totalPrice` | BigDecimal | 成交金额 |
| `transactionTime` | LocalDateTime | 交易时间 |

#### StatisticsSummary

| 字段 | 类型 | 说明 |
|------|------|------|
| `totalAmount` | BigDecimal | 交易总金额 |
| `totalCount` | long | 交易总笔数 |

#### DeptSalesDTO

| 字段 | 类型 | 说明 |
|------|------|------|
| `dept` | String | 院系名称 |
| `salesAmount` | BigDecimal | 销售额 |

#### HotBookDTO

| 字段 | 类型 | 说明 |
|------|------|------|
| `bookId` | Integer | 书籍ID |
| `title` | String | 书名 |
| `author` | String | 作者 |
| `totalSold` | int | 总销量 |

#### DeptDiscountDTO

| 字段 | 类型 | 说明 |
|------|------|------|
| `dept` | String | 院系名称 |
| `avgDiscountRate` | BigDecimal | 平均折扣率（百分比） |

### 3.3 枚举类（`space.anyi.common.enums`）

#### UserRole

| 常量 | 值 | 说明 |
|------|:----:|------|
| `STUDENT` | 0 | 学生 |
| `ADMIN` | 1 | 管理员 |

提供 `fromValue(int)` 工厂方法。

---

## 4. RESTful API 接口定义

所有接口基路径：`/api`（通过 `server.servlet.context-path` 配置）

### 4.1 用户模块 — `/api/user`

| 方法 | 路径 | 请求 | 响应 | 说明 |
|------|------|------|------|------|
| POST | `/api/user/login` | `LoginRequest` JSON | `R<User>` | 登录认证 |
| POST | `/api/user/register` | `RegisterRequest` JSON | `R<User>` | 注册新用户 |
| GET | `/api/user` | `?page=&size=` | `R<IPage<User>>` | 分页获取用户列表（Admin） |
| GET | `/api/user/{id}` | | `R<User>` | 获取单个用户 |
| PUT | `/api/user/{id}` | `User` JSON | `R<User>` | 更新用户信息 |
| DELETE | `/api/user/{id}` | | `R<Void>` | 删除用户（Admin） |

**Controller：** `UserController.java`

- `login()`: 调用 `userService.login(username, password)`，匹配则返回 User，否则 `R.error`
- `register()`: 创建 User 对象，调用 `userService.register(user)`
- `listAll()`: MyBatis-Plus `page()` 分页查询
- `getById()`: 按主键查询，不存在则返回错误
- `update()`: 设置 userId 后 `updateById()`，再返回最新数据
- `delete()`: `removeById()` 物理删除

### 4.2 书籍模块 — `/api/book`

| 方法 | 路径 | 参数 | 响应 | 说明 |
|------|------|------|------|------|
| GET | `/api/book` | keyword, category, page, size | `R<PageResult<Book>>` | 搜索书籍（仅返回 status=1） |
| GET | `/api/book/all` | | `R<List<Book>>` | 获取所有书籍（不分页） |
| GET | `/api/book/{id}` | | `R<Book>` | 获取书籍详情 |
| GET | `/api/book/my` | sellerId | `R<List<Book>>` | 卖家查看自己的书籍 |
| GET | `/api/book/{id}/sales` | | `R<List<SalesRecordDTO>>` | 查看书籍销售记录（卖家） |
| GET | `/api/book/pending` | | `R<List<Book>>` | 查看待审核书籍列表（Admin） |
| POST | `/api/book` | `Book` JSON | `R<Book>` | 创建/上架书籍（默认 status=0） |
| PUT | `/api/book/{id}` | `Book` JSON | `R<Book>` | 更新书籍 |
| PUT | `/api/book/{id}/audit` | `?status=` | `R<Book>` | 审核书籍（Admin：0 待审/1 通过/2 拒绝） |
| DELETE | `/api/book/{id}` | | `R<Void>` | 删除书籍 |

**Controller：** `BookController.java`

- `search()`: 调用 `bookService.searchBooks()`，返回 `PageResult<Book>`
- `listAll()`: 返回所有书籍（按创建时间降序）
- `getById()`: 按主键查询
- `getMyBooks()`: 按 sellerId 查询
- `getSales()`: JOIN 查询销售记录，返回 `List<SalesRecordDTO>`
- `getPendingBooks()`: 查询 `status=0` 的书籍
- `create()`: 设置 `createdAt=now`, `status=0`，保存后返回
- `update()`: 设置 bookId 后 `updateById()`
- `audit()`: 查询书籍 → 设置新 status → 更新
- `delete()`: `removeById()` 物理删除

**Service 方法：** `BookServiceImpl.java`

| 方法 | 说明 |
|------|------|
| `searchBooks(keyword, category, page, size)` | 动态条件：keyword 模糊匹配 title 或 author；category 精确匹配；仅返回 status=1；按 created_at DESC 排序 |
| `getBySellerId(sellerId)` | 按卖家 ID 查询，按创建时间降序 |
| `listAll()` | 返回所有书籍，按创建时间降序 |
| `getSalesByBookId(bookId)` | 委托 `bookMapper.selectSalesByBookId()` JOIN 查询 |
| `getPendingBooks()` | 查询 `status=0` 的书籍 |

### 4.3 交易模块 — `/api/transaction`

| 方法 | 路径 | 请求 | 响应 | 说明 |
|------|------|------|------|------|
| POST | `/api/transaction` | `{bookId, buyerId, quantity}` | `R<TransactionRecord>` | 购买（需事务） |
| GET | `/api/transaction` | `?page=&size=` | `R<IPage<TransactionRecord>>` | 分页查询所有交易 |
| GET | `/api/transaction/{id}` | | `R<TransactionRecord>` | 交易详情 |
| GET | `/api/transaction/user/{userId}` | | `R<List<TransactionRecord>>` | 用户交易记录 |
| PUT | `/api/transaction/{id}` | `TransactionRecord` JSON | `R<TransactionRecord>` | 更新交易（预留） |
| DELETE | `/api/transaction/{id}` | | `R<Void>` | 删除交易 |

**Controller：** `TransactionController.java`

- `purchase()`: 从 Map 中提取 bookId/buyerId/quantity，调用 `transactionService.purchase()`，捕获运行时异常返回错误
- `listAll()`: MyBatis-Plus 分页查询
- `getById()`: 按主键查询
- `getByUser()`: 调用 `transactionService.getByUserId()`
- `update()`/`delete()`: MyBatis-Plus 通用操作

### 4.4 统计模块 — `/api/statistics`

| 方法 | 路径 | 响应 | 说明 |
|------|------|------|------|
| GET | `/api/statistics/summary` | `R<StatisticsSummary>` | 交易总金额和总笔数 |
| GET | `/api/statistics/top-departments` | `R<List<DeptSalesDTO>>` | 销售额前三的院系 |
| GET | `/api/statistics/top-books` | `R<List<HotBookDTO>>` | 销量前五的书籍 |
| GET | `/api/statistics/discount-rates` | `R<List<DeptDiscountDTO>>` | 各院系平均折扣率 |

**Controller：** `StatisticsController.java` — 直接委托 `StatisticsService` 的四个方法。

### 4.5 AI 分析模块 — `/api/ai`

| 方法 | 路径 | 响应 | 说明 |
|------|------|------|------|
| GET | `/api/ai/analysis` | `R<String>` | 触发服务端固定分析流程，返回文本分析报告 |

**Controller：** `AiController.java` — 调用 `aiService.generateAnalysis()`。

**Service 实现：** `AiServiceImpl.java`

流程：
1. 调用 `StatisticsService` 获取全部统计指标（summary、topDepartments、topBooks、discountRates）
2. 格式化拼接为纯文本分析报告
3. 报告包含：交易总览、热门院系 Top 3、热门书籍 Top 5、各院系折扣率、分析结论

---

## 5. 核心业务逻辑

### 5.1 注册流程

1. Controller 接收 `RegisterRequest`
2. 构造 `User` 对象，设置默认值：`credit=100`, `role=0`, `isSeller=0`, `createdAt=now`
3. 调用 `userService.register()` → `save(user)`
4. 返回 `R.ok(user)`（含自增 ID）

**服务端代码位置：** `UserServiceImpl.register()`

### 5.2 登录流程

1. Controller 接收 `LoginRequest`
2. 调用 `userService.login(username, password)`
3. 构建 `LambdaQueryWrapper`：`eq(username) AND eq(password)`
4. 匹配则返回 `R.ok(user)`，否则返回 `R.error("Invalid username or password")`

**服务端代码位置：** `UserServiceImpl.login()`

### 5.3 购买流程（事务）

```
@Transactional 开启事务
  1. bookService.getById(bookId) → 查询书籍
  2. 校验 stock >= quantity，否则抛异常回滚
  3. book.setStock(stock - quantity) → bookService.updateById()
  4. 创建 TransactionRecord:
     - bookId, buyerId, transactionNum
     - transactionPrice = sellingPrice × quantity
     - transactionTime = now
  5. save(record)
提交事务
```

**事务边界：** `TransactionServiceImpl.purchase()` 方法标注 `@Transactional`

### 5.4 搜索书籍流程

1. Controller 接收 keyword、category、page、size
2. 构建 `LambdaQueryWrapper<Book>`：
   - 固定条件：`eq(Book::getStatus, 1)`（仅返回已上架书籍）
   - keyword 非空 → `like(title, keyword) OR like(author, keyword)`
   - category 非空 → `eq(category)`
   - 排序：`orderByDesc(createdAt)`
3. 调用 `page(new Page<>(page, size), wrapper)` 分页查询
4. 转换为 `PageResult<Book>` 返回

**服务端代码位置：** `BookServiceImpl.searchBooks()`

---

## 6. 数据访问层

### 6.1 Mapper 结构

| Mapper | 父类 | 自定义方法 | SQL 类型 |
|--------|------|-----------|----------|
| `UserMapper` | `BaseMapper<User>` | 无 | — |
| `BookMapper` | `BaseMapper<Book>` | `selectSalesByBookId()` | `@Select` JOIN 查询 |
| `TransactionRecordMapper` | `BaseMapper<TransactionRecord>` | 无 | — |
| `StatisticsMapper` | 无（不是实体 Mapper） | 4 个统计方法 | 全部 `@Select` 自定义 SQL |

### 6.2 自定义 SQL

#### BookMapper.selectSalesByBookId()

```sql
SELECT b.book_id, b.title, t.buyer_id, u.nickname AS buyerName,
       t.transaction_num AS quantity, t.transaction_price AS totalPrice,
       t.transaction_time
FROM transaction_record t
JOIN book b ON t.book_id = b.book_id
JOIN user u ON t.buyer_id = u.userid
WHERE b.book_id = #{bookId}
ORDER BY t.transaction_time DESC
```

#### StatisticsMapper

| 方法 | SQL |
|------|-----|
| `selectSummary()` | `SELECT COALESCE(SUM(transaction_price), 0), COUNT(*) FROM transaction_record` |
| `selectTopDepartments()` | JOIN `transaction_record` + `book` + `user`，按 `user.dept` 分组，销售额前 3 |
| `selectTopBooks()` | JOIN `transaction_record` + `book`，按 `book` 分组，销量前 5 |
| `selectDeptDiscountRates()` | `AVG((original_price - unit_price) / original_price * 100)`，按 `dept` 分组 |

---

## 7. 统一响应与分页

### 7.1 响应格式

所有 API 返回统一 JSON：

```json
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
```

| code | 含义 |
|:----:|------|
| 200 | 成功 |
| 400 | 业务错误（参数错误、库存不足、用户名已存在等） |
| 500 | 服务器内部错误 |

### 7.2 分页机制

```
Client → GET /api/book?keyword=&category=&page=1&size=20
Server → MyBatis-Plus Page + LambdaQueryWrapper
       → PaginationInnerInterceptor 自动拦截改写 SQL
       → 返回 IPage<Book> → 转换为 PageResult<Book>
Client → FXCollections.observableArrayList(records) → TableView
```

分页查询步骤：
1. Controller 接收 page 和 size 参数（默认 page=1, size=20）
2. 构建 `Page<T>` 对象 + `LambdaQueryWrapper` 条件
3. MyBatis-Plus 分页插件自动添加 `LIMIT` 和 `COUNT` 子句
4. 返回 `IPage<T>`，包含 records、total、size、current

---

## 8. 运行配置

### 8.1 application.yml

```yaml
server:
  port: 8080
  servlet:
    context-path: /api

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/campus_book_trade?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&useSSL=false
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver

mybatis-plus:
  configuration:
    map-underscore-to-camel-case: true
  global-config:
    db-config:
      id-type: auto
```

### 8.2 启动入口

`ServerApplication.java`：
- `@SpringBootApplication` + `@MapperScan("space.anyi.server.mapper")`
- 运行 `main()` 监听 8080 端口

### 8.3 构建与运行

```sh
# 全量构建
JAVA_HOME=/home/yangyi/.jdks/corretto-23.0.2 mvn clean install

# 单独启动服务端
mvn spring-boot:run -pl server
```

---

## 9. 已实现功能清单与代码位置

### 9.1 基础功能

| 功能 | Controller | Service 实现 | Mapper |
|------|-----------|-------------|--------|
| 登录 | `UserController.java:22` | `UserServiceImpl.java:15` | `UserMapper` (BaseMapper) |
| 注册 | `UserController.java:31` | `UserServiceImpl.java:22` | `UserMapper` (BaseMapper) |
| 用户 CRUD | `UserController.java:44-70` | `ServiceImpl` 继承 | `UserMapper` (BaseMapper) |
| 书籍搜索 | `BookController.java:22` | `BookServiceImpl.java:24` | `BookMapper` (BaseMapper) |
| 书籍 CRUD | `BookController.java:38-98` | `ServiceImpl` 继承 | `BookMapper` (BaseMapper) |
| 购买交易 | `TransactionController.java:22` | `TransactionServiceImpl.java:26` | `TransactionRecordMapper` + `BookMapper` |
| 交易 CRUD | `TransactionController.java:35-66` | `ServiceImpl` 继承 | `TransactionRecordMapper` (BaseMapper) |
| 统计数据 | `StatisticsController.java` | `StatisticsServiceImpl.java` | `StatisticsMapper.java`（4 个 @Select） |

### 9.2 扩展功能

| 功能 | Controller | Service 实现 | Mapper |
|------|-----------|-------------|--------|
| 销售记录 | `BookController.java:56` | `BookServiceImpl.java:52` | `BookMapper.selectSalesByBookId()` |
| 待审核书籍 | `BookController.java:61` | `BookServiceImpl.java:57` | `BookMapper` (BaseMapper) |
| 审核书籍 | `BookController.java:66` | —（直接在 Controller 中操作） | `BookMapper` (BaseMapper) |
| AI 分析 | `AiController.java` | `AiServiceImpl.java` | —（依赖 StatisticsService） |

---

## 10. 设计补充说明

### 10.1 数据库约束

- 未显式声明外键约束，由应用层保证数据一致性
- `transaction_record` 和 `book` 的 `price` 字段使用 `decimal(10,2)` 确保精度

### 10.2 安全性

- 当前无 Token/JWT 机制，userId 通过请求体或参数明文传输
- 密码明文存储，后续建议引入加密和 Spring Security

### 10.3 待扩展

- 分页返回类型不一致：用户模块使用 `IPage<User>`，书籍模块使用 `PageResult<Book>`，建议统一
- `@Transactional` 仅应用于购买流程，其他批量操作未加事务
- 服务端未实现权限拦截，所有 API 均可被任意客户端调用