# 校园闲置物品交易平台 - 前端

> Campus Idle Item Trading Platform - Frontend

一个专为校园场景设计的二手物品交易平台前端项目，提供完整的C端交易功能和B端管理后台。

## 技术栈

| 类别 | 技术 |
|------|------|
| 核心框架 | Vue 3 + TypeScript (严格模式) |
| 构建工具 | Vite 6 |
| UI 组件库 | Element Plus 2.13+ |
| 状态管理 | Pinia 3.0 + pinia-plugin-persistedstate |
| 路由 | Vue Router 4 |
| API 生成 | Orval 7.0 (OpenAPI自动生成) |
| HTTP 客户端 | Axios |

## 功能特性

### C端用户功能

| 模块 | 功能描述 |
|------|----------|
| 首页 | 搜索栏、分类Tabs、物品网格展示、分页 |
| 物品详情 | 图片轮播、物品信息、卖家信息、联系卖家、创建订单 |
| 搜索 | 关键词搜索、分类筛选、结果列表 |
| 发布物品 | 标题、描述、价格、分类、交易方式、多图上传 |
| 我的物品 | Tabs筛选（售卖中/已下架/已售出）、下架/删除操作 |
| 我的订单 | Tabs筛选（我买到的/我卖出的）、订单状态标签 |
| 订单详情 | 订单信息、状态时间线、操作按钮（接单/拒单/确认交货/确认收货） |
| 消息中心 | 会话列表、未读红点、最后消息预览 |
| 即时聊天 | 消息气泡、文本/图片消息、自动滚动 |
| 个人资料 | 头像修改、昵称/个性签名编辑 |
| 修改密码 | 旧密码验证、新密码设置 |

### B端管理后台

| 模块 | 功能描述 |
|------|----------|
| 实名审核 | 待审核用户列表、通过/驳回操作、校园卡照片预览 |
| 物品审核 | 待审核物品列表、上架/驳回操作、物品详情查看 |
| 用户管理 | 用户列表、搜索、封禁/解封、重置密码 |
| 分类管理 | 分类列表、新增/编辑、排序、启用/禁用开关 |

## 项目结构

```
src/
├── api/
│   ├── endpoints/          # Orval生成的API端点
│   │   ├── auth.ts
│   │   ├── items.ts
│   │   ├── orders.ts
│   │   ├── messages.ts
│   │   ├── reviews.ts
│   │   ├── users.ts
│   │   ├── user-management.ts
│   │   ├── categories.ts
│   │   └── attachment.ts
│   └── models/             # Orval生成的TypeScript类型
├── components/
│   ├── ImageUploader.vue   # 图片上传组件
│   └── EmptyState.vue      # 空状态组件
├── layout/
│   ├── UserLayout.vue      # C端布局（含移动端TabBar）
│   └── AdminLayout.vue     # B端管理后台布局
├── router/
│   └── index.ts            # 路由配置
├── store/
│   ├── user.ts             # 用户状态管理
│   ├── meta.ts             # 站点配置
│   └── index.ts            # Store导出
├── util/
│   ├── axios-instance.ts   # Axios实例配置
│   └── index.ts            # 工具函数
├── view/                   # 页面视图
│   ├── Home.vue            # 首页
│   ├── ItemDetail.vue      # 物品详情
│   ├── Search.vue          # 搜索
│   ├── Publish.vue         # 发布物品
│   ├── MyItems.vue         # 我的物品
│   ├── MyOrders.vue        # 我的订单
│   ├── OrderDetail.vue     # 订单详情
│   ├── Messages.vue        # 消息中心
│   ├── Chat.vue            # 即时聊天
│   ├── Profile.vue         # 个人资料
│   ├── ChangePassword.vue  # 修改密码
│   ├── Login.vue           # 登录
│   └── admin/              # 管理后台
│       ├── ReviewUser.vue  # 实名审核
│       ├── ReviewItem.vue  # 物品审核
│       ├── UserManage.vue  # 用户管理
│       └── CategoryManage.vue # 分类管理
├── App.vue
├── main.ts
└── style.css
```

## 快速开始

### 环境要求

- Node.js 18+
- 后端服务运行在 `http://localhost:8090`

### 安装依赖

```bash
npm install
```

### 开发模式

```bash
npm run dev
```

服务将启动在 `http://localhost:3000`，API请求会自动代理到后端 `http://localhost:8090`。

### 构建生产环境

```bash
npm run build
```

TypeScript类型检查通过后，构建产物将输出到 `dist/` 目录。

### 预览生产构建

```bash
npm run preview
```

## API 代码生成

本项目使用 [Orval](https://orval.dev/) 根据后端 OpenAPI/Swagger 文档自动生成 API 调用代码。

### 重新生成 API

```bash
npm run api:gen
```

此命令会：
1. 从 `http://localhost:8090/v3/api-docs` 读取 OpenAPI 规范
2. 生成 `src/api/endpoints/` 下的 API 端点
3. 生成 `src/api/models/` 下的 TypeScript 类型定义
4. 使用 Prettier 自动格式化生成的代码

### 配置

Orval 配置位于 `orval.config.ts`：

```typescript
export default defineConfig({
  campusTrade: {
    input: {
      target: 'http://localhost:8090/v3/api-docs',
    },
    output: {
      mode: 'tags',           // 按标签拆分文件
      client: 'axios',        // 使用 axios
      target: './src/api/endpoints/',
      schemas: './src/api/models',
      clean: true,
      override: {
        mutator: {
          path: './src/util/axios-instance.ts',
          name: 'customAxiosInstance',
        },
      },
    },
  },
})
```

## 路由结构

### 公开页面

| 路径 | 名称 | 说明 |
|------|------|------|
| `/login` | login | 登录页 |

### C端页面（需登录）

| 路径 | 名称 | 权限要求 |
|------|------|----------|
| `/home` | home | 公开 |
| `/item/:id` | itemDetail | 公开 |
| `/search` | search | 公开 |
| `/publish` | publish | 需登录 + 需实名认证 |
| `/my/items` | myItems | 需登录 |
| `/my/orders` | myOrders | 需登录 |
| `/order/:id` | orderDetail | 需登录 |
| `/messages` | messages | 需登录 |
| `/messages/:userId` | chat | 需登录 |
| `/profile` | profile | 需登录 |
| `/profile/password` | changePassword | 需登录 |

### B端管理后台（需管理员权限）

| 路径 | 名称 | 说明 |
|------|------|------|
| `/admin/review/user` | reviewUser | 实名审核 |
| `/admin/review/item` | reviewItem | 物品审核 |
| `/admin/users` | userManage | 用户管理 |
| `/admin/categories` | categoryManage | 分类管理 |

## 认证机制

项目采用 **Session-based** 认证方式：

- 使用 `withCredentials: true` 自动携带 Session Cookie
- 无 Token 存储逻辑
- 401 响应自动跳转登录页
- 用户状态通过 Pinia 管理并持久化到 localStorage

### 用户状态结构

```typescript
{
  userId: number | null,
  nickname: string,
  signature: string,
  avatarUrl: string,
  role: string,           // 'ADMIN' | 'USER'
  authStatus: string,     // 'AUTHENTICATED' | 'PENDING' | 'UNAUTHENTICATED'
  isLoggedIn: boolean
}
```

## 开发规范

### TypeScript 严格模式

- `noUnusedLocals`: true
- `noUnusedParameters`: true
- `erasableSyntaxOnly`: true

### 响应式设计

- 使用 Element Plus 响应式工具类
- 移动端底部 TabBar（< 768px 显示）
- 网格布局自适应：xs=24 / sm=12 / md=8 / lg=6

### API 使用示例

```typescript
// 使用 Orval 生成的 API
import { getItems } from '@/api/endpoints/items'

const { getItemsList } = getItems()

// 调用 API
const response = await getItemsList({ keyword: '书籍', page: 1, size: 10 })
// response 类型为 ResultPageResultItemVO
```

## 代理配置

Vite 开发服务器配置了 API 代理：

```typescript
// vite.config.ts
server: {
  port: 3000,
  proxy: {
    '/api': {
      target: 'http://localhost:8090',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, '')
    }
  }
}
```

## 构建与部署

### 生产构建

```bash
npm run build
```

构建流程：
1. `vue-tsc -b` - TypeScript 类型检查
2. `vite build` - Vite 生产构建

### 构建产物

- 输出目录: `dist/`
- 静态资源: `dist/assets/`
- 入口文件: `dist/index.html`

## 相关链接

- [Vue 3 文档](https://vuejs.org/)
- [Element Plus 文档](https://element-plus.org/)
- [Orval 文档](https://orval.dev/)
- [Pinia 文档](https://pinia.vuejs.org/)
- [Vue Router 文档](https://router.vuejs.org/)

## 许可证

[MIT License](LICENSE)