# 校园闲置物品交易平台 — 概要设计

## 1. 系统架构

采用前后端分离架构：

- **前端**：Vue3 + ElementPlus，Web 端适配移动端
- **后端**：SpringBoot + MyBatis + PageHelper
- **存储层**：关系型数据库 + 本地文件存储（`./upload`）
- **认证方案**：Session

```mermaid
graph TB
    subgraph 客户端层
        C[C端 买家/卖家<br/>Vue3 + ElementPlus]
        B[B端 后台管理员<br/>Vue3 + ElementPlus]
    end
    subgraph 服务端层
        API[API 接口层<br/>SpringBoot]
        US[用户服务]
        IS[物品服务]
        OS[订单服务]
        MS[消息服务]
        RS[审核服务]
    end
    subgraph 存储层
        DB[(MySQL 数据库)]
        FS[本地文件存储<br/>./upload]
    end
    C --> API
    B --> API
    API --> US & IS & OS & MS & RS
    US --> DB
    IS --> DB & FS
    OS --> DB
    MS --> DB & FS
    RS --> DB
```

---

## 2. 功能模块划分

### 2.1 用户模块
| 子功能 | 说明 |
|--------|------|
| 注册 | 学号 + 姓名 + 密码 + 校园卡照片上传 |
| 登录 | 学号 + 密码，Session 会话管理 |
| 个人资料管理 | 头像/昵称/个性签名修改 |
| 密码管理 | 修改密码（旧密码验证） |
| 认证状态 | 标记未认证/待审核/已认证 |

### 2.2 物品模块
| 子功能 | 说明 |
|--------|------|
| 物品发布 | 图片/标题/描述/价格/分类/交易方式（自提/送货上门） |
| 物品列表 | 首页按发布时间倒序展示，PageHelper 分页 |
| 物品搜索 | 按标题/描述模糊匹配 |
| 分类筛选 | 按分类查询物品 |
| 物品详情 | 图文/价格/卖家昵称/交易方式 |
| 物品状态 | 售卖中/已下架/已售出 |
| 我的发布 | 卖家查看和管理自己的发布（下架/删除） |

### 2.3 订单模块
| 子功能 | 说明 |
|--------|------|
| 生成订单 | 买家点击"我想要"，继承卖家交易方式 |
| 订单状态机 | 待接单 → 待面交 → 已完成 / 已取消 |
| 卖家接单/拒单 | 确认接单或拒绝订单 |
| 卖家确认交货 | 线下面交完成后标记 |
| 买家确认收货 | 线下收到物品后确认 |
| 我的订单 | 双视角：我买到的 / 我卖出的 |

### 2.4 消息模块
| 子功能 | 说明 |
|--------|------|
| 站内私信 | 文本 + 图片 |
| 联系卖家 | 买家从物品详情页发起会话 |

### 2.5 审核模块（后台 Web）
| 子功能 | 说明 |
|--------|------|
| 实名认证审核 | 查看校园卡照片，通过/驳回（驳回需填原因） |
| 物品上架审核 | 通过上架/驳回下架 |
| 用户管理 | 封禁/解封用户 |
| 密码重置 | 管理员手动重置用户密码 |
| 分类管理 | 新增/修改/禁用物品分类 |

---

## 3. 数据库概念设计

### 3.1 核心实体关系

```mermaid
erDiagram
    User ||--o{ Item : "发布"
    User ||--o{ Order : "买家"
    User ||--o{ Order : "卖家"
    User ||--o{ Message : "发送"
    User ||--o{ Message : "接收"
    User ||--o{ Review : "审核对象"
    User ||--o{ Review : "审核人"
    Category ||--o{ Item : "属于"
    Item ||--o{ Order : "生成"
    Item ||--o{ Message : "关联"
```

### 3.2 主要数据表

> 所有外键均为 **逻辑外键**，不建立物理外键约束。

#### 用户表（user）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK | 用户ID |
| student_id | VARCHAR(20) UNIQUE | 学号 |
| name | VARCHAR(50) | 姓名 |
| password_hash | VARCHAR(255) | bcrypt 密码哈希 |
| nickname | VARCHAR(50) | 昵称 |
| avatar_url | VARCHAR(255) | 头像 URL（`/upload/...`） |
| signature | VARCHAR(200) | 个性签名 |
| campus_card_url | VARCHAR(255) | 校园卡照片 URL |
| auth_status | VARCHAR(20) | 未认证/待审核/已认证 |
| status | VARCHAR(20) | 正常/封禁 |
| role | VARCHAR(20) | 普通用户/管理员 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

#### 分类表（category）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK | 分类ID |
| name | VARCHAR(50) | 分类名称 |
| status | VARCHAR(20) | 启用/禁用 |
| sort_order | INT | 排序 |
| created_at | DATETIME | 创建时间 |

#### 物品表（item）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK | 物品ID |
| seller_id | BIGINT | 卖家ID（逻辑外键 → user.id） |
| category_id | BIGINT | 分类ID（逻辑外键 → category.id） |
| title | VARCHAR(100) | 标题 |
| description | TEXT | 描述 |
| price | DECIMAL(10,2) | 价格 |
| images | TEXT | 图片 URL 列表（JSON 或逗号分隔） |
| trade_method | VARCHAR(20) | 自提/送货上门 |
| status | VARCHAR(20) | 待审核/售卖中/已下架/已售出 |
| created_at | DATETIME | 发布时间 |
| updated_at | DATETIME | 更新时间 |

#### 订单表（order）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK | 订单ID |
| item_id | BIGINT | 物品ID（逻辑外键 → item.id） |
| buyer_id | BIGINT | 买家ID（逻辑外键 → user.id） |
| seller_id | BIGINT | 卖家ID（逻辑外键 → user.id） |
| trade_method | VARCHAR(20) | 自提/送货上门 |
| status | VARCHAR(20) | 待接单/待面交/已完成/已取消 |
| created_at | DATETIME | 创建时间 |
| updated_at | DATETIME | 更新时间 |

#### 消息表（message）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK | 消息ID |
| from_user_id | BIGINT | 发送方（逻辑外键 → user.id） |
| to_user_id | BIGINT | 接收方（逻辑外键 → user.id） |
| item_id | BIGINT NULL | 关联物品（逻辑外键 → item.id） |
| content | TEXT | 文本内容 |
| image_url | VARCHAR(255) NULL | 图片 URL |
| is_read | TINYINT(1) | 是否已读 |
| created_at | DATETIME | 发送时间 |

#### 审核记录表（review）
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT PK | 审核ID |
| admin_id | BIGINT | 管理员ID（逻辑外键 → user.id） |
| review_type | VARCHAR(20) | 实名认证/物品上架 |
| target_id | BIGINT | 关联ID（用户ID/物品ID） |
| result | VARCHAR(20) | 通过/驳回 |
| reason | VARCHAR(255) | 驳回原因 |
| created_at | DATETIME | 审核时间 |

---

## 4. 核心业务流程设计

### 4.1 用户认证流程

```mermaid
flowchart LR
    A[填写注册信息<br/>学号+姓名+密码+校园卡照片] --> B[提交注册]
    B --> C[状态: 待审核]
    C --> D{管理员审核}
    D -->|通过| E[状态: 已认证]
    D -->|驳回+原因| F[状态: 未认证<br/>用户可重新提交]
```

### 4.2 物品发布与交易流程

```mermaid
flowchart TB
    A[卖家发布闲置] --> B[状态: 待审核]
    B --> C{管理员审核}
    C -->|通过| D[状态: 售卖中]
    C -->|驳回| E[状态: 已下架]
    D --> F[买家浏览并点击"我想要"]
    F --> G[生成订单 状态: 待接单]
    G --> H{卖家处理}
    H -->|接单| I[状态: 待面交]
    H -->|拒单| J[状态: 已取消]
    I --> K[线下交易完成<br/>卖家确认交货]
    K --> L[买家确认收货]
    L --> M[状态: 已完成]
```

### 4.3 订单状态机

```mermaid
stateDiagram-v2
    [*] --> 待接单: 买家下单
    待接单 --> 待面交: 卖家接单
    待接单 --> 已取消: 卖家拒单
    待面交 --> 已完成: 卖家确认交货 + 买家确认收货
    待面交 --> 已取消: 任意方取消
    已完成 --> [*]
    已取消 --> [*]
```

---

## 5. 前端页面结构

### 5.1 C端（买家/卖家）— Vue3 + ElementPlus

| 页面 | 路由 | 说明 |
|------|------|------|
| 登录页 | /login | 学号+密码登录，Session 会话 |
| 注册页 | /register | 学号+姓名+密码+校园卡上传 |
| 首页 | /home | 物品列表（时间倒序，ElementPlus 分页组件） |
| 物品详情 | /item/:id | 图文详情、联系卖家、我想要 |
| 物品搜索 | /search | 关键词搜索+分类筛选 |
| 物品发布 | /publish | 发布闲置表单（ElementPlus 表单组件） |
| 我的发布 | /my/items | 售卖中/已下架/已售出 Tab 切换 |
| 我的订单 | /my/orders | 我买到的/我卖出的双视角 |
| 订单详情 | /order/:id | 订单操作按钮 |
| 消息列表 | /messages | 会话列表 |
| 消息聊天 | /messages/:userId | 聊天界面 |
| 个人资料 | /profile | 查看/编辑资料 |
| 修改密码 | /profile/password | 旧密码+新密码 |

### 5.2 B端（后台Web端）— Vue3 + ElementPlus

| 页面 | 路由 | 说明 |
|------|------|------|
| 登录 | /admin/login | 管理员登录 |
| 实名审核 | /admin/review/user | 待审核列表+通过/驳回操作 |
| 物品审核 | /admin/review/item | 物品上架审核 |
| 用户管理 | /admin/users | 封禁/解封/密码重置 |
| 分类管理 | /admin/categories | 新增/修改/禁用分类 |

---

## 6. API 接口概览

### 用户相关
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/auth/register | 注册 |
| POST | /api/auth/login | 登录（创建 Session） |
| POST | /api/auth/logout | 登出（销毁 Session） |
| POST | /api/auth/change-password | 修改密码 |
| GET | /api/user/profile | 获取个人资料 |
| PUT | /api/user/profile | 修改个人资料 |

### 物品相关
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/items | 首页物品列表（PageHelper 分页+时间倒序） |
| GET | /api/items/search | 关键词搜索 |
| GET | /api/items/category/{id} | 分类筛选 |
| GET | /api/items/{id} | 物品详情 |
| POST | /api/items | 发布物品 |
| GET | /api/items/my | 我的发布列表 |
| PUT | /api/items/{id}/offline | 下架物品 |
| DELETE | /api/items/{id} | 删除物品 |

### 订单相关
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/orders | 生成订单 |
| GET | /api/orders/bought | 我买到的（PageHelper 分页） |
| GET | /api/orders/sold | 我卖出的（PageHelper 分页） |
| PUT | /api/orders/{id}/accept | 卖家接单 |
| PUT | /api/orders/{id}/reject | 卖家拒单 |
| PUT | /api/orders/{id}/deliver | 卖家确认交货 |
| PUT | /api/orders/{id}/confirm | 买家确认收货 |

### 消息相关
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/messages/conversations | 会话列表 |
| GET | /api/messages/{userId} | 聊天记录 |
| POST | /api/messages | 发送消息 |

### 管理员相关
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | /api/admin/review/users | 待审核用户列表 |
| POST | /api/admin/review/user/{id} | 用户审核（通过/驳回） |
| GET | /api/admin/review/items | 待审核物品列表 |
| POST | /api/admin/review/item/{id} | 物品审核（通过/驳回） |
| GET | /api/admin/users | 用户管理列表 |
| PUT | /api/admin/users/{id}/ban | 封禁用户 |
| PUT | /api/admin/users/{id}/unban | 解封用户 |
| POST | /api/admin/users/{id}/reset-password | 密码重置 |
| GET | /api/admin/categories | 分类列表 |
| POST | /api/admin/categories | 新增分类 |
| PUT | /api/admin/categories/{id} | 修改分类 |
| PUT | /api/admin/categories/{id}/status | 启用/禁用分类 |

---

## 7. 非功能性设计要点

| 方面 | 方案 |
|------|------|
| 图片存储 | 本地 `./upload` 目录，URL 为 `/upload/{filename}` |
| 密码安全 | bcrypt 哈希存储 |
| 认证鉴权 | Session + Cookie |
| 分页 | PageHelper 插件，统一分页参数（pageNum, pageSize） |
| 接口规范 | 统一响应格式 `{ code, message, data }` |
| 状态码 | HTTP 200 + 业务 code（如 401 未登录，403 无权限） |

---

## 8. 后端项目结构（SpringBoot + MyBatis）

```
src/main/java/com/campus/trade
├── config
│   ├── WebMvcConfig.java          # 静态资源配置（/upload 映射）
│   ├── SessionConfig.java         # Session 配置
│   └── MyBatisConfig.java         # MyBatis + PageHelper 配置
├── controller
│   ├── AuthController.java
│   ├── UserController.java
│   ├── ItemController.java
│   ├── OrderController.java
│   ├── MessageController.java
│   └── admin
│       ├── ReviewController.java
│       ├── UserManageController.java
│       └── CategoryController.java
├── service
│   ├── AuthService.java
│   ├── UserService.java
│   ├── ItemService.java
│   ├── OrderService.java
│   ├── MessageService.java
│   └── admin
│       ├── ReviewService.java
│       ├── UserManageService.java
│       └── CategoryService.java
├── mapper
│   ├── UserMapper.java
│   ├── ItemMapper.java
│   ├── OrderMapper.java
│   ├── MessageMapper.java
│   ├── ReviewMapper.java
│   └── CategoryMapper.java
├── entity
│   ├── User.java
│   ├── Item.java
│   ├── Order.java
│   ├── Message.java
│   ├── Review.java
│   └── Category.java
├── dto
│   ├── LoginRequest.java
│   ├── RegisterRequest.java
│   ├── ItemPublishRequest.java
│   └── PageResult.java
├── interceptor
│   └── AuthInterceptor.java       # Session 登录校验拦截器
├── common
│   ├── Result.java                # 统一响应体
│   ├── StatusCode.java            # 业务状态码枚举
│   └── FileUploadUtil.java        # 本地文件上传工具类
```

---

## 9. 前端项目结构（Vue3 + ElementPlus）

```
src
├── api
│   ├── auth.js
│   ├── user.js
│   ├── item.js
│   ├── order.js
│   ├── message.js
│   └── admin.js
├── views
│   ├── Login.vue
│   ├── Register.vue
│   ├── Home.vue
│   ├── ItemDetail.vue
│   ├── Search.vue
│   ├── Publish.vue
│   ├── MyItems.vue
│   ├── MyOrders.vue
│   ├── OrderDetail.vue
│   ├── Messages.vue
│   ├── Chat.vue
│   ├── Profile.vue
│   ├── ChangePassword.vue
│   └── admin
│       ├── Login.vue
│       ├── ReviewUser.vue
│       ├── ReviewItem.vue
│       ├── UserManage.vue
│       └── CategoryManage.vue
├── router
│   └── index.js
├── stores
│   └── user.js                    # Pinia 用户状态管理
├── utils
│   └── request.js                 # Axios 封装（携带 Session Cookie）
├── App.vue
└── main.js
```