campusIdleItemTradingPlatformServer

校园闲置物品交易平台 (Campus Idle Item Trading Platform)

一个面向校园用户的二手物品交易平台，支持物品发布、订单管理、站内私信等功能。

技术栈

• 后端框架: Spring Boot 3.5.15
• Java 版本: Java 17+
• 数据持久层: MyBatis 3.0.5 + MyBatis-Spring-Boot-Starter
• 数据库: MySQL 8.0+ (HikariCP 连接池)
• API 文档: SpringDoc OpenAPI (Swagger UI)
• 分页插件: PageHelper
• 参数校验: Spring Validation
• 安全: MD5 密码加密 + Session 认证

项目结构

server/
├── pom.xml                              # Maven 配置文件
├── sql/
│   └── init.sql                         # 数据库初始化脚本
└── src/main/
    ├── java/com/campus/trade/
    │   ├── ServerApplication.java       # 应用入口
    │   ├── config/                      # 配置类
    │   │   ├── WebMvcConfig.java        # Web MVC 配置
    │   │   └── MyBatisConfig.java       # MyBatis 配置
    │   ├── controller/                  # 控制器层
    │   │   ├── AuthController.java      # 认证相关 API
    │   │   ├── ItemController.java      # 物品相关 API
    │   │   ├── OrderController.java     # 订单相关 API
    │   │   ├── MessageController.java   # 消息相关 API
    │   │   ├── UserController.java      # 用户资料 API
    │   │   ├── CategoryController.java  # 分类相关 API
    │   │   └── admin/                   # 后台管理 API
    │   ├── service/                     # 业务逻辑层
    │   │   ├── impl/                    # 服务实现类
    │   │   └── admin/                   # 后台管理服务
    │   ├── mapper/                      # 数据访问层 (MyBatis Mapper)
    │   ├── entity/                      # 实体类
    │   ├── dto/                         # 数据传输对象 (请求参数)
    │   ├── vo/                          # 视图对象 (响应数据)
    │   ├── common/                      # 公共工具类
    │   │   ├── Result.java              # 统一响应封装
    │   │   ├── StatusCode.java          # 状态码定义
    │   │   ├── BusinessException.java   # 业务异常
    │   │   ├── GlobalExceptionHandler.java # 全局异常处理
    │   │   ├── OrderStatusMachine.java  # 订单状态机
    │   │   └── FileUploadUtil.java      # 文件上传工具
    │   └── interceptor/                 # 拦截器
    │       ├── AuthInterceptor.java     # 登录认证拦截器
    │       └── AdminInterceptor.java    # 管理员权限拦截器
    └── resources/
        ├── application.yaml             # 应用配置文件
        └── mapper/                      # MyBatis XML 映射文件

核心功能模块

1. 用户认证模块

• 用户注册（学号 + 姓名 + 密码 + 校园卡照片）
• 用户登录/登出（Session 认证）
• 实名认证（上传校园卡照片，管理员审核）
• 密码修改（需验证旧密码）

2. 物品管理模块

• 物品发布（需实名认证）
• 物品浏览（首页列表、分页）
• 物品搜索（标题/描述模糊匹配）
• 分类筛选
• 物品详情
• 我的发布列表
• 物品下架/删除

3. 订单管理模块

• 订单创建（买家点击"我想要"）

• 订单状态流转：

  PENDING → CONFIRMED → DELIVERED → COMPLETED
     ↓
  CANCELLED (卖家拒单)
  

• 买家视角：我买到的订单

• 卖家视角：我卖出的订单

• 订单操作：接单、拒单、确认交货、确认收货

4. 站内消息模块

• 会话列表（显示最后一条消息）
• 聊天记录（分页加载）
• 发送消息（文本 + 图片）
• 消息已读状态

5. 后台管理模块

• 用户管理（列表、封禁/解封、查看详情）
• 实名认证审核
• 物品审核
• 分类管理（增删改查、排序）

数据库设计

数据表清单

表名	说明	主要字段
user	用户表	id, student_id, name, password_hash, auth_status, role, status
category	分类表	id, name, status, sort_order
item	物品表	id, seller_id, category_id, title, description, price, images, status
order	订单表	id, item_id, buyer_id, seller_id, trade_method, status
message	消息表	id, from_user_id, to_user_id, item_id, content, is_read
review	审核记录表	id, admin_id, review_type, target_id, result, reason

状态枚举说明

用户认证状态 (auth_status)

• UNAUTHENTICATED - 未认证
• PENDING - 审核中
• AUTHENTICATED - 已认证

用户账号状态 (status)

• NORMAL - 正常
• BANNED - 已封禁

物品状态 (status)

• PENDING - 待审核
• ON_SALE - 在售中
• OFF_SHELF - 已下架
• SOLD - 已售出

订单状态 (status)

• PENDING - 待确认
• CONFIRMED - 已接单
• DELIVERED - 已交货
• COMPLETED - 已完成
• CANCELLED - 已取消

分类状态 (status)

• ENABLED - 启用
• DISABLED - 禁用

快速开始

环境要求

• Java 17+
• Maven 3.6+
• MySQL 8.0+

1. 数据库初始化

# 登录 MySQL
mysql -u root -p

# 执行初始化脚本
source sql/init.sql

默认数据库配置：

• 数据库名：campus_idle_item_trading_platform
• 用户名：root
• 密码：root

2. 配置文件修改

编辑 src/main/resources/application.yaml：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/campus_idle_item_trading_platform?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: your_username
    password: your_password

3. 构建与运行

# 编译项目
./mvnw compile

# 开发模式运行（热部署）
./mvnw spring-boot:run

# 打包
./mvnw package

# 运行 jar 包
java -jar target/CampusIdleItemTradingPlatform-0.0.1-SNAPSHOT.jar

4. 访问应用

• 应用地址：http://localhost:8090
• API 文档：http://localhost:8090/swagger-ui.html
• OpenAPI JSON：http://localhost:8090/v3/api-docs

默认管理员账号

• 学号：admin
• 密码：admin (MD5: e10adc3949ba59abbe56e057f20f883e)

API 接口概览

公开接口（无需登录）

接口	方法	说明
/auth/register	POST	用户注册
/auth/login	POST	用户登录
/items	GET	物品列表
/items/{id}	GET	物品详情
/items/search	GET	搜索物品
/items/category/{id}	GET	按分类筛选
/categories	GET	分类列表

需要登录的接口

接口前缀	说明
/auth/logout	用户登出
/auth/submit-auth	提交实名认证
/auth/change-password	修改密码
/user/profile	个人资料管理
/items (POST)	发布物品
/items/my	我的发布
/orders/**	订单相关
/messages/**	站内消息

管理员接口

接口前缀	说明
/admin/users/**	用户管理
/admin/reviews/**	审核管理
/admin/categories/**	分类管理

响应格式

统一使用 Result<T> 包装：

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

状态码

状态码	说明
200	成功
400	参数错误
401	未登录
403	无权限
404	资源不存在
409	业务冲突（如学号已注册）
500	服务器内部错误

技术亮点

1. 分层架构：严格遵循 Controller → Service → Mapper → Entity 分层
2. 状态机：订单状态流转通过 OrderStatusMachine 统一管理
3. 统一响应：全局异常处理 + 统一 Result 封装
4. API 文档：基于注解的 Swagger/OpenAPI 自动生成
5. 数据校验：使用 Bean Validation 进行参数校验
6. 分页支持：PageHelper 实现分页查询
7. 文件上传：支持图片上传，配置大小限制

开发约定

• 实体类字段必须有注释说明
• Controller 必须使用 OpenAPI 注解描述 API
• 使用 DTO 接收请求参数，VO 返回响应数据
• 业务逻辑放在 Service 层，Controller 只负责转发
• MyBatis XML 使用 #{} 参数绑定
• 状态使用字符串枚举（如 PENDING, ON_SALE）

许可证

本项目仅供学习交流使用。