# 校园闲置物品交易平台 (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. 数据库初始化

```bash
# 登录 MySQL
mysql -u root -p

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

默认数据库配置：
- 数据库名：`campus_idle_item_trading_platform`
- 用户名：`root`
- 密码：`root`

### 2. 配置文件修改

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

```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. 构建与运行

```bash
# 编译项目
./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>` 包装：

```json
{
  "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`）

## 许可证

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