# pet-adoption-website

**Repository Path**: david__zhang/pet-adoption-website

## Basic Information

- **Project Name**: pet-adoption-website
- **Description**:     - 宠物浏览与搜索
    - 在线领养申请
    - 领养故事分享
    - 社区论坛交流
    - 用户管理
    - 宠物信息管理
    - 领养订单审核
    - 内容管理（轮播图、热门推荐、领养故事）
    - 论坛内容管理
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-08
- **Last Updated**: 2026-03-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 宠物领养网站项目文档

本文档为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导，同时也作为项目的技术文档。

## 项目简介

这是一个完整的宠物领养平台系统，旨在为流浪宠物提供领养服务，连接爱心人士与需要家庭的宠物。

### 系统组成

项目采用前后端分离架构，包含三个主要应用：

- **wx_hadluo-pet_web**: 用户端前端应用
    - 宠物浏览与搜索
    - 在线领养申请
    - 领养故事分享
    - 社区论坛交流

- **wx_hadluo-pet-admin**: 管理后台应用
    - 用户管理
    - 宠物信息管理
    - 领养订单审核
    - 内容管理（轮播图、热门推荐、领养故事）
    - 论坛内容管理

- **wx_hadluo-pet-server**: 后端 API 服务
    - RESTful API 接口
    - 数据持久化
    - 身份认证与授权
    - 文件上传管理
    - 邮件通知服务

### 技术栈

**前端技术：**

- Vue 3 - 渐进式 JavaScript 框架
- Vue Router 4 - 官方路由管理器
- Element Plus - Vue 3 UI 组件库
- Axios - HTTP 客户端
- Vite - 新一代前端构建工具
- Pinia - Vue 状态管理（管理后台）

**后端技术：**

- Spring Boot 2.7.5 - Java 应用框架
- Spring Security - 安全框架
- MyBatis / MyBatis-Plus - 持久层框架
- MySQL 8.0 - 关系型数据库
- Redis - 缓存与会话管理
- Druid - 数据库连接池
- JWT - 无状态身份认证
- Swagger 3.0 - API 文档
- Kaptcha - 验证码生成

## 快速开始

### 环境要求

**后端开发环境：**

- JDK 1.8 或更高版本
- Maven 3.6+
- MySQL 8.0+
- Redis 5.0+

**前端开发环境：**

- Node.js 14.0+
- npm 6.0+ 或 yarn 1.22+

### 项目初始化

1. **数据库初始化**

```bash
# 创建数据库并导入初始数据
mysql -u root -p < wx_hadluo_pet.sql
```

2. **配置后端**
   编辑 `wx_hadluo-pet-server/src/main/resources/application.yml`：

- 修改数据库连接信息
- 修改 Redis 连接信息
- 修改文件上传路径（根据操作系统调整）
- 配置邮件服务（如需使用）

3. **启动 Redis**

```bash
redis-server
```

## 开发命令

### 后端服务器 (wx_hadluo-pet-server)

```bash
cd wx_hadluo-pet-server

# 运行应用
mvn spring-boot:run

# 构建项目
mvn clean package

# 运行测试
mvn test

# 跳过测试构建
mvn clean package -DskipTests
```

服务器默认运行在 8080 端口。Swagger UI 可通过 `http://localhost:8080/swagger-ui/` 访问

### 用户前端 (wx_hadluo-pet_web)

```bash
cd wx_hadluo-pet_web

# 安装依赖
npm install

# 运行开发服务器
npm run dev

# 生产环境构建
npm run build

# 预览生产构建
npm run preview
```

### 管理后台 (wx_hadluo-pet-admin)

```bash
cd wx_hadluo-pet-admin

# 安装依赖
npm install

# 运行开发服务器
npm run dev

# 生产环境构建
npm run build

# 预览生产构建
npm run preview
```

## 核心功能模块

### 用户端功能

- **首页展示**: 轮播广告、热门宠物推荐、领养故事
- **宠物浏览**: 分类筛选、搜索、详情查看
- **领养申请**: 在线提交领养申请、查看申请状态
- **用户中心**: 个人信息管理、我的领养记录
- **社区论坛**: 发帖、评论、交流养宠经验
- **用户认证**: 注册、登录、邮箱验证

### 管理端功能

- **数据统计**: 仪表盘展示关键指标
- **用户管理**: 用户列表、状态管理
- **宠物管理**: 宠物信息 CRUD、分类管理
- **订单管理**: 领养申请审核、状态更新
- **内容管理**: 轮播图、热门推荐、领养故事
- **论坛管理**: 帖子审核、内容管理

## 架构说明

### 后端架构 (Spring Boot)

后端采用经典的三层架构模式：

**控制器层** (`com.hadluo.pet.controller`)

- 用户端控制器：`PetController`、`UserController`、`ForumController`、`IndexController`、`FileController`、`CityController`
- 管理端控制器位于 `admin/` 子目录：`AdminPetController`、`AdminOrderController`、`AdminCategoryController` 等
- 控制器返回 `ApiResponse` 对象以保持 API 响应的一致性

**服务层** (`com.hadluo.pet.service`)

- 业务逻辑实现
- 服务接口及其 `impl/` 子目录中的实现类

**数据访问层** (`com.hadluo.pet.mapper`)

- MyBatis/MyBatis-Plus 数据访问层
- XML 映射文件位于 `src/main/resources/mapper/`

**实体层** (`com.hadluo.pet.entity`)

- 领域模型和 POJO
- VO（值对象）类位于 `entity/vo/` 子目录

**配置类** (`com.hadluo.pet.config`)

- `SwaggerConfig`: API 文档配置
- `RedisConfig`: Redis 缓存配置
- `CorsConfig`: 跨域资源共享配置
- `KaptchaConfig`: 验证码配置
- `MybatisPlusConfig`: MyBatis-Plus 分页等功能配置

**公共类** (`com.hadluo.pet.common`)

- `ApiResponse`: 标准化的 API 响应包装器

**工具类** (`com.hadluo.pet.util`)

- `JwtUtil`: JWT 令牌生成和验证

### 前端架构 (Vue 3)

两个前端应用都使用 Vue 3 组合式 API、Vue Router 和 Element Plus。

**用户前端结构：**

- `src/views/`: 页面组件（Home、PetList、PetDetail、Forum、ArticleDetail、About、Register、MyAdoptions）
- `src/components/`: 可复用组件，包括 `auth/LoginDialog.vue`
- `src/api/`: API 服务模块
- `src/router/`: Vue Router 配置
- `src/utils/`: 工具函数

**管理后台结构：**

- `src/views/`: 按功能组织的管理页面
    - `Dashboard.vue`: 主仪表盘
    - `UserManagement.vue`: 用户管理
    - `adoption/`: 宠物领养管理（CategoryManagement、PetManagement、OrderManagement、OrderDetail、OrderEdit）
    - `home/`: 首页内容管理（BannerManagement、HotPetsManagement、StoriesManagement）
    - `forum/`: 论坛管理
- `src/components/`: 可复用组件，如 `PetSelector.vue`
- `src/api/`: API 模块（adminApi、category、pet、order、banner、forum、upload）
- `src/utils/request.js`: 带拦截器的 Axios 实例
- `src/router/`: 路由定义及认证守卫

### 关键技术细节

**身份认证：**

- 后端使用 JWT 令牌配合 Spring Security
- 管理后台将令牌存储在 localStorage 中，键名为 `admin_token`
- 路由守卫在访问受保护路由前检查认证状态
- JWT 密钥和过期时间在 `application.yml` 中配置

**数据库：**

- MySQL 数据库，使用 MyBatis 进行数据访问
- Druid 连接池提升性能
- 数据库配置在 `application.yml` 中（当前指向远程服务器）
- SQL 建表脚本为 `wx_hadluo_pet.sql`

**文件上传：**

- 文件存储在 `application.yml` 中指定的本地路径（`file.upload.path`）
- 默认路径：`D:\ftp\wx_hadluo_pet`（Windows 路径，其他操作系统需调整）
- 通过 `/api/file/get` 端点访问文件
- 最大文件大小：500MB

**Redis：**

- 用于缓存和会话管理
- 配置在 `application.yml` 中（默认 localhost:6379）

**邮件服务：**

- 配置为 QQ 邮箱 SMTP
- 用于通知和验证
- 配置在 `application.yml` 中

## 重要注意事项

**数据库连接：**
`application.yml` 当前指向远程数据库服务器。本地开发时，您可能需要：

1. 将 `wx_hadluo_pet.sql` 导入本地 MySQL 实例
2. 更新 `application.yml` 中的数据源 URL、用户名和密码

**文件上传路径：**
文件上传路径配置为 Windows 路径（`D:\ftp\wx_hadluo_pet`）。在 macOS/Linux 上，需要在 `application.yml` 中更新为有效的本地目录路径。

**Redis 依赖：**
后端需要 Redis 运行。运行服务器前请先安装并启动 Redis，或者如果不需要可以注释掉 Redis 相关配置。

**API 基础 URL：**

- 后端 API：`http://localhost:8080`
- 前端开发服务器运行在 Vite 的默认端口
- 查看各前端项目的 `vite.config.js` 了解代理配置

**管理员凭据：**
默认管理员密码在 `application.yml` 中配置为 `admin-pwd: 123456`

## 代码规范

**后端：**

- 实体类使用 Lombok 注解（`@Data`、`@Getter`、`@Setter`）
- 遵循 RESTful API 规范
- 管理端接口以 `/admin` 为前缀
- 所有控制器响应使用 `ApiResponse` 包装
- 复杂查询使用 MyBatis XML 映射器，简单 CRUD 使用 MyBatis-Plus

**前端：**

- 使用 Vue 3 组合式 API（`<script setup>`）
- 使用 Element Plus 作为 UI 组件库
- 使用 Axios 进行 HTTP 请求，在 `utils/request.js` 中集中配置
- 基于路由的代码分割，使用动态导入
- 认证令牌存储在 localStorage 中

## API 接口说明

### 接口规范

**请求格式：**

- Content-Type: application/json
- 认证方式: Bearer Token (JWT)
- 管理端接口前缀: `/admin`

**响应格式：**
所有接口统一返回 `ApiResponse` 格式：

```json
{
	"code": 200, // 状态码
	"message": "成功", // 提示信息
	"data": {} // 响应数据
}
```

**主要接口模块：**

- `/api/user` - 用户相关接口
- `/api/pet` - 宠物信息接口
- `/api/order` - 领养订单接口
- `/api/forum` - 论坛接口
- `/api/file` - 文件上传下载
- `/api/index` - 首页数据接口
- `/admin/*` - 管理端接口

详细 API 文档可通过 Swagger UI 查看：`http://localhost:8080/swagger-ui/`

## 数据库设计

### 核心数据表

- **user** - 用户表：存储用户基本信息、认证信息
- **pet** - 宠物表：宠物详细信息、状态
- **category** - 分类表：宠物分类信息
- **order** - 订单表：领养申请记录
- **banner** - 轮播图表：首页广告位
- **hot** - 热门推荐表：热门宠物关联
- **stories** - 领养故事表：成功案例分享
- **forum** - 论坛表：社区帖子内容

数据库建表脚本：`wx_hadluo_pet.sql`

## 部署说明

### 后端部署

1. **打包应用**

```bash
cd wx_hadluo-pet-server
mvn clean package -DskipTests
```

2. **运行 JAR 包**

```bash
java -jar target/pet-server-0.0.1-SNAPSHOT.jar
```

3. **配置生产环境**

- 修改 `application.yml` 中的数据库连接为生产环境
- 配置文件上传路径
- 确保 Redis 服务可访问
- 配置邮件服务参数

### 前端部署

1. **构建生产版本**

```bash
# 用户端
cd wx_hadluo-pet_web
npm run build

# 管理后台
cd wx_hadluo-pet-admin
npm run build
```

2. **部署静态文件**
   将 `dist` 目录部署到 Nginx 或其他 Web 服务器

3. **配置反向代理**
   配置 Nginx 将 API 请求代理到后端服务器

## 常见问题

### 后端启动失败

**问题：Redis 连接失败**

- 确认 Redis 服务已启动
- 检查 `application.yml` 中的 Redis 配置
- 如不需要 Redis，可临时注释相关配置

**问题：数据库连接失败**

- 确认 MySQL 服务已启动
- 检查数据库连接信息是否正确
- 确认数据库已创建并导入初始数据

**问题：文件上传失败**

- 检查 `file.upload.path` 配置的目录是否存在
- 确认应用有该目录的读写权限
- Windows 路径使用反斜杠或双反斜杠

### 前端开发问题

**问题：跨域请求失败**

- 检查后端 `CorsConfig` 配置
- 确认 `vite.config.js` 中的代理配置正确
- 开发环境使用代理，生产环境配置 CORS

**问题：登录后无法访问**

- 检查浏览器 localStorage 中是否有 token
- 确认 token 未过期（默认 24 小时）
- 检查路由守卫逻辑

## 开发建议

### 添加新功能

1. **后端开发流程**
    - 在 `entity` 包创建实体类
    - 在 `mapper` 包创建 Mapper 接口和 XML
    - 在 `service` 包创建服务接口和实现
    - 在 `controller` 包创建控制器
    - 使用 `ApiResponse` 包装返回结果

2. **前端开发流程**
    - 在 `api` 目录创建 API 调用函数
    - 在 `views` 目录创建页面组件
    - 在 `router` 中配置路由
    - 使用 Element Plus 组件构建 UI

### 代码提交规范

建议使用语义化提交信息：

- `feat`: 新功能
- `fix`: 修复 bug
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 重构
- `test`: 测试相关
- `chore`: 构建/工具相关

## 项目维护

### 依赖更新

定期检查并更新依赖版本，注意：

- Spring Boot 版本升级需测试兼容性
- Vue 3 和 Element Plus 保持版本匹配
- 数据库驱动与 MySQL 版本对应

### 安全注意事项

- 定期更新 JWT 密钥
- 不要将敏感信息提交到版本控制
- 生产环境关闭 Swagger 文档
- 定期备份数据库
- 实施 SQL 注入防护
- 对用户输入进行验证和过滤

## 联系方式

如有问题或建议，请联系项目维护团队。