# CampusLostFound

**Repository Path**: weitw/campus-lost-found

## Basic Information

- **Project Name**: CampusLostFound
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-28
- **Last Updated**: 2026-10-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 拾遗 · 校园失物招领平台

基于 Vue3 + Spring Boot 的校园失物招领平台，已完成从注册登录、帖子发布与检索、图片上传、收藏、认领沟通、消息提醒，到管理员审核、用户管理、统计看板与前端联调验收的完整业务闭环。

## 技术栈

- 后端：Spring Boot 2.7、Java 8、MyBatis-Plus、MySQL 8.0、Spring Validation、JWT（HS256）、BCrypt、Knife4j
- 前端：Vue3、Vite、Element Plus、Axios、Pinia、Vue Router、ECharts
- 数据库：MySQL 8.0（InnoDB / utf8mb4）

## 目录结构

```text
.
├── backend/                    # Spring Boot 后端工程
│   ├── src/main/java/com/campus/lostfound/
│   │   ├── common/             # ApiResponse、PageResult
│   │   ├── config/             # CORS、Jackson、MyBatis-Plus、Knife4j、BCrypt
│   │   ├── controller/         # 认证、文件、帖子、收藏、认领、消息、管理端、统计
│   │   ├── dto/                # 各业务模块请求参数
│   │   ├── entity/             # 用户、文件、帖子、图片、收藏、认领、消息、审核记录
│   │   ├── enums/              # 角色、帖子类型/状态、认领状态、消息类型
│   │   ├── exception/          # 业务异常与全局异常处理器
│   │   ├── mapper/             # MyBatis-Plus Mapper
│   │   ├── security/           # JwtUtil、AuthInterceptor、UserContext、@RequireRole
│   │   ├── service/            # 各业务服务及实现
│   │   └── vo/                 # 接口展示对象
│   └── src/main/resources/application.yml
├── frontend/                   # Vue3 前端工程
│   └── src/
│       ├── api/                # Axios 实例与各模块接口封装
│       ├── components/         # 认证布局、图片上传、站点导航、错误重试
│       ├── router/             # 路由与登录/管理员守卫
│       ├── store/              # Pinia 会话与未读消息状态
│       ├── styles/             # 全局样式
│       ├── utils/              # 帖子/认领字典、ECharts 按需入口
│       └── views/              # 全部业务页面
├── sql/init.sql                # MySQL 8.0 初始化脚本
└── README.md
```

## 环境要求

- JDK 8 / 17 / 21（项目编译目标为 Java 8，已在 JDK 21 验证）
- Maven 3.6+
- Node.js 18+、npm 9+
- MySQL 8.0

## 1. 初始化数据库

```bash
mysql -uroot -p < sql/init.sql
```

脚本会创建数据库 `campus_lost_found` 及 8 张表：

`t_user`、`t_file`、`t_post`、`t_post_image`、`t_favorite`、`t_claim`、`t_message`、`t_post_audit`

所有表均包含公共字段 `id`、`created_at`、`updated_at`、`deleted`，表名统一 `t_` 前缀，字段统一 snake_case，不建立外键。

## 2. 启动后端

```bash
cd backend

# 默认连接 localhost:3306/campus_lost_found，用户名 root，密码 root
# 可通过环境变量覆盖：MYSQL_HOST、MYSQL_PORT、MYSQL_DATABASE、MYSQL_USERNAME、MYSQL_PASSWORD
mvn spring-boot:run
```

启动成功后：

- 健康检查：<http://localhost:8080/api/health>
- 接口文档：<http://localhost:8080/doc.html>

### 常用环境变量

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `MYSQL_HOST` | `localhost` | MySQL 地址 |
| `MYSQL_PORT` | `3306` | MySQL 端口 |
| `MYSQL_DATABASE` | `campus_lost_found` | 数据库名 |
| `MYSQL_USERNAME` | `root` | 数据库用户名 |
| `MYSQL_PASSWORD` | `root` | 数据库密码 |
| `JWT_SECRET` | 内置开发密钥 | JWT HS256 签名密钥，至少 32 字节 |
| `JWT_EXPIRE_MINUTES` | `120` | JWT 有效期（分钟） |
| `FILE_UPLOAD_DIR` | `./uploads` | 本地文件存储目录 |
| `POST_AUTO_APPROVE` | `false` | 演示开关：`true` 时新帖直接审核通过，默认进入 `PENDING` |
| `CORS_ALLOWED_ORIGINS` | `http://localhost:5173,http://127.0.0.1:5173` | 允许跨域的前端地址 |

## 3. 启动前端

```bash
cd frontend
npm install
npm run dev
```

访问 <http://localhost:5173>。Vite 已将 `/api` 代理到 `http://localhost:8080`，可通过 `VITE_PROXY_TARGET` 环境变量修改代理目标。

生产构建：

```bash
npm run build
```

## 4. 测试与构建

```bash
# 后端单元 / 接口测试
cd backend && mvn test

# 前端生产构建
cd frontend && npm run build
```

后端测试覆盖认证、帖子、文件、收藏、认领、消息、管理端、统计与权限守卫等模块；前端构建会执行 Vue 模板编译与依赖打包。

## 5. 管理员账号

注册默认角色为 `USER`。完成注册后，在数据库中将目标账号提升为管理员：

```sql
UPDATE campus_lost_found.t_user
SET role = 'ADMIN'
WHERE username = 'your_admin_username';
```

重新登录或刷新页面后，`/api/auth/me` 会返回最新角色、动态菜单与权限标识，顶部导航出现“帖子审核、认领管理、用户管理、统计看板”入口。

## 6. 页面路由

| 路由 | 页面 | 访问要求 |
| --- | --- | --- |
| `/` | 首页 | 公开 |
| `/login` | 登录 | 公开 |
| `/register` | 注册 | 公开 |
| `/posts` | 帖子列表 | 公开 |
| `/posts/:id` | 帖子详情 | 公开（非公开帖子仅作者/管理员可见） |
| `/posts/create` | 发布帖子 | 登录 |
| `/posts/mine` | 我的发布 | 登录 |
| `/favorites` | 我的收藏 | 登录 |
| `/claims/mine` | 我的认领 | 登录 |
| `/claims/received` | 收到的认领 | 登录 |
| `/claims/:id` | 认领详情与沟通 | 登录且为参与方/管理员 |
| `/messages` | 消息中心 | 登录 |
| `/profile` | 个人中心 | 登录 |
| `/admin/posts` | 帖子审核 | 管理员 |
| `/admin/claims` | 认领管理 | 管理员 |
| `/admin/users` | 用户管理 | 管理员 |
| `/admin/stats` | 统计看板 | 管理员 |

## 7. 核心接口

| 接口 | 方法 | 鉴权 | 说明 |
| --- | --- | --- | --- |
| `/api/auth/register` | POST | 匿名 | 注册用户，默认角色 `USER` |
| `/api/auth/login` | POST | 匿名 | 登录成功返回 `token`、用户信息、菜单与权限 |
| `/api/auth/me` | GET | 登录 | 获取最新用户信息、菜单与权限 |
| `/api/files/upload` | POST | 登录 | 上传图片，支持 jpg/jpeg/png/gif/webp |
| `/api/files/view/{id}` | GET | 匿名 | 查看图片 |
| `/api/posts` | POST | 登录 | 发布寻物 / 招领帖子，最多 9 张图片 |
| `/api/posts` | GET | 匿名 | 按类型、类别、地点、关键词、时间组合查询 |
| `/api/posts/{id}` | GET | 可选登录 | 帖子详情 |
| `/api/posts/mine` | GET | 登录 | 我的发布 |
| `/api/favorites` | GET | 登录 | 我的收藏 |
| `/api/favorites/{postId}` | POST/DELETE | 登录 | 收藏 / 取消收藏 |
| `/api/claims` | POST | 登录 | 提交认领申请（仅 `FOUND + APPROVED`） |
| `/api/claims/mine` | GET | 登录 | 我发起的认领 |
| `/api/claims/received` | GET | 登录 | 我收到的认领 |
| `/api/claims/{id}` | GET | 登录 | 认领详情 |
| `/api/claims/{id}/status` | PATCH | 登录 | 认领状态流转 |
| `/api/claims/{id}/messages` | GET/POST | 登录 | 认领留言 |
| `/api/messages` | GET | 登录 | 消息列表 |
| `/api/messages/unread-count` | GET | 登录 | 未读数量 |
| `/api/messages/{id}/read` | PATCH | 登录 | 单条已读 |
| `/api/messages/read-all` | PATCH | 登录 | 全部已读 |
| `/api/admin/posts` | GET | 管理员 | 管理端帖子分页 |
| `/api/admin/posts/{id}/approve` | PATCH | 管理员 | 审核通过 |
| `/api/admin/posts/{id}/reject` | PATCH | 管理员 | 审核驳回 |
| `/api/admin/posts/{id}/offline` | PATCH | 管理员 | 违规下架 |
| `/api/admin/claims` | GET | 管理员 | 全平台认领分页 |
| `/api/admin/users` | GET | 管理员 | 用户分页 |
| `/api/admin/users/{id}/status` | PATCH | 管理员 | 禁用 / 启用账号 |
| `/api/admin/users/{id}/role` | PATCH | 管理员 | 调整角色 |
| `/api/stats/dashboard` | GET | 管理员 | 统计看板聚合数据 |

## 8. 统一约定

- 统一返回体：`ApiResponse<T> = { code, message, data }`，成功 `code=200`、`message=success`
- 分页返回体：`PageResult<T> = { records, total, current, size }`，`page` 从 1 开始，`size` 默认 10、最大 50
- 鉴权：登录后请求头携带 `Authorization: Bearer <token>`；注册、登录、健康检查、图片查看与公开帖子查询可匿名访问
- 异常：参数校验 400、未登录 401、无权限 403、资源不存在 404、系统异常 500，均由全局异常处理器统一返回 `ApiResponse`
- 时间格式：`yyyy-MM-dd HH:mm:ss`
- 逻辑删除：`deleted=0` 正常、`deleted=1` 删除
- 前端统一使用 Axios 拦截器提示错误；401 时清理登录态，公开页面不强制跳转，受保护页面回到登录页并携带 `redirect`

## 9. 已完成范围

- 基础工程：统一返回体、分页返回体、全局异常处理、CORS、Jackson 时间格式、MyBatis-Plus 分页与逻辑删除、Knife4j 文档
- 认证与权限：注册、登录、`/api/auth/me`、JWT 签发解析、`AuthInterceptor`、`UserContext`、`@RequireRole`、动态菜单树与权限标识
- 文件：图片上传、格式与大小校验、匿名查看、本地磁盘存储
- 帖子：发布、组合查询、详情、我的发布、多图排序与封面、非公开帖子作者/管理员可见
- 收藏：收藏 / 取消收藏、状态查询、我的收藏分页
- 认领：提交申请、我的/收到的认领、详情、状态流转、留言沟通、管理员认领查询
- 消息：列表、未读数、单条/全部已读、认领进度系统通知
- 管理端：帖子审核/驳回/下架与审核记录、用户筛选/启停/角色调整、认领管理
- 统计：帖子与认领汇总、状态分布、类别分布、近 7/14/30 天趋势
- 前端页面：首页、登录、注册、帖子列表/详情/发布、我的发布、我的收藏、我的认领、收到的认领、认领详情、消息中心、个人中心、管理员四个页面
- 前端联调：两级顶部导航（失物招领 / 认领 / 管理分组下拉，窄屏分组导航）、表单校验、分页与空页回退、图片上传中禁止提交、统一错误提示与错误重试、401/403 会话处理、管理员路由守卫、移动端导航