# CampusUsedBookTradingSystem

校园二手书交易系统 — C/S 架构，JavaFX 客户端 + Spring Boot 服务端 + MySQL 数据库。

## 项目概述

为学生提供便捷的二手书籍买卖平台，支持买家浏览/搜索/购买书籍，卖家上架/管理书籍，管理员进行用户/商品/交易管理及数据分析。集成 Spring AI 提供基于 LLM 的运营分析报告。

## 技术栈

| 层次 | 技术 | 版本 |
|------|------|------|
| 客户端 UI | JavaFX + FXML + Scene Builder | 23.0.2 |
| 客户端 HTTP | `java.net.http.HttpClient` | JDK 内置 |
| JSON | Jackson (`jackson-databind` + `jackson-datatype-jsr310`) | 2.17.3 |
| 服务端框架 | Spring Boot Web | 3.4.4 |
| ORM | MyBatis-Plus (`mybatis-plus-spring-boot3-starter`) | 3.5.9 |
| 数据库 | MySQL 8.0+ (Connector 8.4.0) | |
| AI | Spring AI (OpenAI) | 1.1.8 |
| UI 主题 | BootstrapFX | 0.4.0 |
| 构建工具 | Maven (3.9+) | |
| 编译运行 | JDK 23 (Corretto-23.0.2) | |
| 注解 | Lombok 1.18.36 | |

## 系统架构

```mermaid
flowchart TB
    subgraph Client["JavaFX 客户端 (space.anyi.client)"]
        VIEW["FXML 视图层"]
        CTRL["Controller 层"]
        HSVC["HTTP Service 层"]
    end
    subgraph Server["Spring Boot 服务端 (space.anyi.server)"]
        CTL["Controller 层"]
        SVC["Service 层"]
        MPR["Mapper 层"]
    end
    subgraph DB["MySQL 8.0"]
        D[("campus_book_trade")]
    end

    Client <-->|HTTP/JSON RESTful API| Server
    MPR <--> D
```

三层 Maven 模块：
- **`common`** — 共享实体、DTO、枚举（被 `server` 和 `client` 依赖）
- **`server`** — Spring Boot 服务端 (Controller → Service → Mapper → MySQL)
- **`client`** — JavaFX 客户端 (Controller → HTTP Service → UI)

依赖：`server → common`，`client → common`。客户端与服务端仅通过 HTTP RESTful API 通信。

## 用户角色与权限

| 角色 | 权限 |
|------|------|
| **买家** (role=0, isSeller=0) | 浏览/搜索书籍、查看详情、购买、查看个人交易记录、修改个人信息 |
| **卖家** (role=0, isSeller=1) | 买家权限 + 上架/编辑/下架书籍、查看自己发布的书籍及销售记录 |
| **管理员** (role=1) | 全部权限 + 用户 CRUD/重置密码、商品审核、交易管理、数据统计、AI 分析 |

## 功能清单

### 买家功能
- 登录/注册
- 浏览书籍（卡片网格展示，支持按书名/作者关键词搜索 + 分类筛选）
- 查看书籍详情
- 购买书籍（库存校验，事务保证数据一致性）
- 查看个人交易记录
- 修改个人信息（昵称、邮箱、电话、院系、切换卖家身份）

### 卖家功能
- 上架书籍（自动进入待审核状态）
- 编辑/下架书籍
- 查看自己的书籍列表
- 查看书籍销售记录（谁在何时买了多少本）
- 销售统计概览（在售数、总库存、已售数量）

### 管理员功能
- 用户管理（浏览/添加/编辑/删除/重置密码/修改信用分）
- 商品管理（浏览所有书籍、删除书籍）
- 书籍审核（通过/拒绝待审核书籍）
- 交易管理（查看全部交易记录、删除交易）
- 数据统计（交易总金额/总笔数、热门院系 Top 3、热门书籍 Top 5、各院系平均折扣率）
- AI 分析报告（基于统计数据生成；支持流式 LLM 调用）

## 服务端 REST API

所有 API 基路径：`/api`，统一响应格式 `R<T>` = `{code, message, data}`。

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

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/user/login` | 登录 |
| POST | `/api/user/register` | 注册 |
| GET | `/api/user?page=&size=` | 分页用户列表 |
| GET | `/api/user/{id}` | 获取用户 |
| PUT | `/api/user/{id}` | 更新用户 |
| DELETE | `/api/user/{id}` | 删除用户 |

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

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/book?keyword=&category=&page=&size=` | 搜索书籍（仅返回已上架） |
| GET | `/api/book/all` | 所有书籍（含卖家名） |
| GET | `/api/book/{id}` | 书籍详情 |
| GET | `/api/book/my?sellerId=` | 卖家的书籍 |
| GET | `/api/book/{id}/sales` | 销售记录 |
| GET | `/api/book/pending` | 待审核书籍 |
| GET | `/api/book/sales-summary?sellerId=` | 卖家总销量 |
| POST | `/api/book` | 上架书籍 |
| PUT | `/api/book/{id}` | 更新书籍 |
| PUT | `/api/book/{id}/audit?status=` | 审核书籍 |
| DELETE | `/api/book/{id}` | 删除书籍 |

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

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/transaction` | 购买 |
| GET | `/api/transaction?page=&size=` | 交易列表（含详情） |
| GET | `/api/transaction/{id}` | 交易详情 |
| GET | `/api/transaction/user/{userId}` | 用户交易记录 |
| GET | `/api/transaction/user/{userId}/detail` | 用户交易记录（含书名） |
| PUT | `/api/transaction/{id}` | 更新交易 |
| DELETE | `/api/transaction/{id}` | 删除交易 |

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

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/statistics/summary` | 交易总金额 & 总笔数 |
| GET | `/api/statistics/top-departments` | 销售额 Top 3 院系 |
| GET | `/api/statistics/top-books` | 销量 Top 5 书籍 |
| GET | `/api/statistics/discount-rates` | 各院系平均折扣率 |

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

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/ai/analysis` | 固定模板分析报告 |
| GET | `/api/ai/analysis/stream` | 流式 LLM 分析报告 |

## 数据库

- MySQL 8.0+，数据库 `campus_book_trade`，字符集 `utf8mb4`
- 三张表：`user`、`book`、`transaction_record`
- DDL 脚本：`sql/campus_book_trade.sql`（含示例数据）
- 默认连接：`root`/`root` @ `localhost:3306`
- 配置位置：`server/src/main/resources/application.yml`

### ER 图

```mermaid
erDiagram
    USER {
        int userid PK
        varchar username
        varchar password
        varchar nickname
        varchar email
        varchar phone
        varchar dept
        int credit
        int role
        int is_seller
        datetime created_at
    }

    BOOK {
        int book_id PK
        int seller_id FK
        varchar title
        varchar author
        varchar category
        decimal original_price
        decimal selling_price
        varchar image_url
        datetime created_at
        int stock
        int status
    }

    TRANSACTION_RECORD {
        int trans_id PK
        int book_id FK
        int buyer_id FK
        int transaction_num
        decimal transaction_price
        datetime transaction_time
    }

    USER ||--o{ BOOK : "seller"
    USER ||--o{ TRANSACTION_RECORD : "buyer"
    BOOK ||--o{ TRANSACTION_RECORD : "contains"
```

### 核心流程
- **登录**：用户名+密码匹配 → 存入客户端 `LoginUserHolder`（无 JWT）
- **注册**：创建用户，默认 credit=100, role=0, isSeller=0
- **购买**：`@Transactional` 事务 → 校验库存 → 扣减库存 → 生成交易记录
- **搜索**：动态 `LambdaQueryWrapper`，关键词模糊匹配书名/作者，分类精确匹配

## 构建与运行

**注意：必须使用 JDK 23 编译。** 本项目在 `corretto-23.0.2` 下开发测试。

```bash
# 设置 JDK
export JAVA_HOME=/home/yangyi/.jdks/corretto-23.0.2

# 初始化数据库（执行一次）
mysql -u root -p < sql/campus_book_trade.sql

# 全量构建
mvn clean install

# 单独构建公共模块（依赖模块需先安装）
mvn install -pl common

# 启动服务端（端口 8080）
mvn spring-boot:run -pl server

# 启动客户端
mvn javafx:run -pl client
```

## 项目结构

```mermaid
flowchart LR
    subgraph root["CampusUsedBookTradingSystem/"]
        POM["pom.xml<br/>父 POM（多模块）"]
        COMMON["common<br/>共享模块"]
        SERVER["server<br/>Spring Boot 服务端"]
        CLIENT["client<br/>JavaFX 客户端"]
        SQL["sql<br/>建表脚本"]
    end

    subgraph common_detail["common/"]
        C_ENTITY["entity/<br/>User, Book,<br/>TransactionRecord"]
        C_DTO["dto/<br/>R&lt;T&gt;, PageResult,<br/>各种 DTO"]
        C_ENUM["enums/<br/>UserRole"]
    end

    subgraph server_detail["server/"]
        S_APP["ServerApplication.java"]
        S_CONFIG["config/<br/>CORS, 分页, 异常处理"]
        S_CTRL["controller/<br/>User, Book, Transaction,<br/>Statistics, Ai"]
        S_SVC["service + impl/<br/>业务接口 + 实现"]
        S_MAP["mapper/<br/>MyBatis-Plus Mapper"]
    end

    subgraph client_detail["client/"]
        C_CLI["Client.java<br/>启动入口"]
        C_APP["UIApplication.java<br/>场景切换"]
        C_CTRL["controller/<br/>Login, Register, Main"]
        C_SVC["service/<br/>HTTP 调用封装"]
        C_UTIL["util/<br/>HttpClientUtil,<br/>LoginUserHolder"]
        C_RES["resources/<br/>fxml/ + css/"]
    end

    root --> COMMON --> common_detail
    root --> SERVER --> server_detail
    root --> CLIENT --> client_detail
    root --> SQL
```

## 客户端 UI

基于 JavaFX 23 + BootstrapFX 主题框架 + 自定义 `style.css` 覆盖层。

| 视图 | 说明 |
|------|------|
| **登录页** | 居中卡片，用户名/密码输入 |
| **注册页** | 表单填写（用户名、密码、昵称、邮箱、电话、院系） |
| **主界面** | 顶部导航栏 + 内容区，6 个导航标签 |
| 浏览书籍 | 搜索栏 + 图书卡片网格 + 详情面板 + 购买功能 |
| 我的交易 | 表格展示交易记录，含书名、数量、总价、时间 |
| 个人信息 | 编辑昵称/邮箱/电话/院系，切换卖家身份 |
| 卖家中心 | 书籍表格 + 统计概览 + 添加/编辑/删除书籍 + 查看销售记录 |
| 数据统计 | KPI 卡片 + 热门院系进度条 + 畅销书籍表格 + 折扣率表格 + 图表 |
| 管理 | 侧边菜单：用户管理、商品管理、待审核书籍、交易管理、AI 分析 |

## 设计文档

- [需求文档](doc/demand.md)
- [详细设计文档](doc/design.md)
- [服务端设计文档](doc/serverDesign.md)
- [UI 设计文档](doc/UIDesign.md)
- [AGENTS.md](AGENTS.md) — 开发助手配置

## 注意事项

- 当前密码明文存储，无 JWT 认证，适合校园局域网环境
- 服务端未实现权限拦截，生产环境建议引入 Spring Security
- 新上架书籍默认 `status=0`（待审核），需要管理员审核后才可被搜索到
- Spring AI 需配置 `OPENAI_API_KEY` / `OPENAI_BASE_URL` / `OPENAI_MODEL` 环境变量（详见 `application.yml`）
- 未配置 CI、测试框架、格式化/代码检查工具