campusUsedBookTradingSystem

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

系统架构

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 图

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 下开发测试。

# 设置 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

项目结构

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 分析

设计文档

• 需求文档
• 详细设计文档
• 服务端设计文档
• UI 设计文档
• AGENTS.md — 开发助手配置

注意事项

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