# PawGuardServer

**Repository Path**: imlinnai/paw-guard-server

## Basic Information

- **Project Name**: PawGuardServer
- **Description**: PawGuard（爪印守护）一个专业的流浪猫狗救助平台 - 后端项目（初步完成）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-01
- **Last Updated**: 2025-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 毕业设计, 开发中

## README

# 🐾 PawGuard（爪印守护）

> 流浪猫狗救助平台后端服务 - 连接救助者、领养人、志愿者、捐赠者与管理员的公益型全栈平台

[![Node.js Version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)](https://nodejs.org/)
[![Express](https://img.shields.io/badge/express-4.18.2-blue.svg)](https://expressjs.com/)
[![MySQL](https://img.shields.io/badge/mysql-8.0+-orange.svg)](https://www.mysql.com/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)

## 📖 项目简介

PawGuard（爪印守护）是一个专注于流浪猫狗救助的公益平台后端服务，旨在通过数字化手段简化救助流程、促进流浪动物领养、汇聚公益力量，打造"救助-帮扶-领养-反馈"的闭环生态。

### ✨ 核心特性

- 🏠 **救助信息管理** - 发布、审核、浏览救助信息，支持紧急程度筛选和关键词搜索
- 🐕 **领养申请系统** - 完整的领养申请、审核、跟踪流程，支持状态实时更新
- 👥 **志愿者管理** - 志愿者活动发布、报名、审核与管理，支持任务分配
- 💝 **捐赠管理** - 资金与物资捐赠记录、公示与管理，支持凭证上传和审核
- 📝 **救助故事** - 图文展示救助过程、志愿者事迹、领养反馈，支持点赞和评论
- 💬 **消息系统** - 系统通知、站内消息推送，支持消息已读/未读状态
- 🔍 **全文搜索** - 基于 MySQL 全文索引的智能搜索，支持多关键词匹配
- 📊 **数据统计** - 管理员后台数据统计与报表导出（Excel格式）
- 🔐 **权限管理** - 基于角色的访问控制（RBAC），支持用户和管理员角色
- ⭐ **收藏功能** - 用户可收藏感兴趣的救助信息和故事
- 💬 **评论系统** - 支持嵌套评论、点赞功能，管理员可审核评论
- 📦 **物资管理** - 物资入库、出库、库存管理，支持库存预警
- ⚙️ **系统设置** - 可配置的系统参数管理

## 🛠️ 技术栈

### 核心框架
- **Node.js** >= 16.0.0 - JavaScript 运行时环境
- **Express.js** 4.18.2 - Web 应用框架
- **Sequelize** 6.37.1 - ORM 数据库操作
- **MySQL** >= 8.0 - 关系型数据库
- **Redis** >= 6.0 - 缓存与会话存储（可选）

### 安全与认证
- **JWT** (jsonwebtoken) - JSON Web Token 身份认证
- **bcryptjs** - 密码加密哈希
- **Helmet** - HTTP 安全头设置
- **express-rate-limit** - API 请求限流
- **XSS** - 跨站脚本攻击防护
- **express-validator** - 输入参数验证

### 工具库
- **Multer** - 文件上传处理
- **Sharp** - 图片处理与压缩
- **ExcelJS** - Excel 报表导出
- **Winston** - 日志记录系统
- **Swagger** (swagger-jsdoc + swagger-ui-express) - API 文档自动生成
- **node-cron** - 定时任务支持
- **crypto-js** - 加密工具

### 开发工具
- **ESLint** - 代码质量检查
- **Prettier** - 代码格式化
- **Jest** - 单元测试框架
- **Nodemon** - 开发热重载
- **Supertest** - API 测试工具

## 📁 项目结构

```
PawGuardServer/
├── config/                  # 配置文件
│   ├── db.js               # 数据库配置（Sequelize）
│   ├── redis.js            # Redis 配置
│   ├── logger.js           # Winston 日志配置
│   └── swagger.js          # Swagger API 文档配置
├── controllers/            # 控制器层（业务逻辑）
│   ├── userController.js
│   ├── rescueController.js
│   ├── adoptionController.js
│   ├── volunteerController.js
│   ├── donationController.js
│   ├── materialController.js
│   ├── messageController.js
│   ├── rescueStoryController.js
│   ├── commentController.js
│   ├── favoriteController.js
│   ├── searchController.js
│   ├── adminController.js
│   ├── systemController.js
│   └── ...
├── models/                 # 数据模型（Sequelize ORM）
│   ├── User.js
│   ├── RescueInfo.js
│   ├── AdoptionApplication.js
│   ├── VolunteerActivity.js
│   ├── Donation.js
│   ├── RescueMaterial.js
│   ├── Message.js
│   ├── RescueStory.js
│   ├── Comment.js
│   ├── Favorite.js
│   └── ...
├── routes/                 # 路由定义
│   ├── userRoutes.js
│   ├── rescueRoutes.js
│   ├── adoptionRoutes.js
│   ├── volunteerRoutes.js
│   ├── donationRoutes.js
│   ├── materialRoutes.js
│   ├── messageRoutes.js
│   ├── storyRoutes.js
│   ├── commentRoutes.js
│   ├── favoriteRoutes.js
│   ├── searchRoutes.js
│   ├── adminRoutes.js
│   ├── systemRoutes.js
│   ├── batchRoutes.js
│   ├── commonRoutes.js
│   ├── healthRoutes.js
│   └── logRoutes.js
├── middleware/             # 中间件
│   ├── auth.js            # JWT 认证中间件
│   ├── roleCheck.js       # 权限检查中间件
│   ├── rateLimiter.js     # 请求限流中间件
│   ├── xssProtection.js   # XSS 防护中间件
│   ├── errorHandler.js    # 全局错误处理
│   ├── accessLogger.js    # 访问日志记录
│   └── operationLog.js   # 操作日志记录
├── migrations/            # 数据库迁移脚本
│   ├── 001_*.js
│   ├── 002_*.js
│   └── ... (27个迁移文件)
├── utils/                 # 工具函数
│   ├── jwt.js            # JWT 工具（生成/验证Token）
│   ├── encryption.js     # 加密工具
│   ├── upload.js         # 文件上传工具
│   ├── imageProcessor.js # 图片处理工具
│   ├── cache.js          # Redis 缓存工具
│   ├── excelExport.js    # Excel 导出工具
│   ├── passwordValidator.js # 密码验证工具
│   └── userFormatter.js  # 用户数据格式化
├── uploads/              # 上传文件目录（图片等）
├── logs/                 # 日志文件目录
├── docs/                 # 项目文档
├── app.js                # 应用入口文件
└── package.json          # 项目依赖配置
```

## 🔧 环境要求

- **Node.js** >= 16.0.0
- **MySQL** >= 8.0
- **Redis** >= 6.0（可选，用于缓存和会话存储）
- **npm** >= 8.0.0 或 **yarn** >= 1.22.0

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone https://gitee.com/imlinnai/paw-guard-server.git
cd PawGuardServer
```

### 2. 安装依赖

```bash
npm install
```

### 3. 配置环境变量

在项目根目录创建 `.env` 文件，配置以下环境变量：

```env
# 服务器配置
PORT=3000
NODE_ENV=development
CORS_ORIGIN=*

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_NAME=pawguard
DB_USER=root
DB_PASSWORD=your_password

# Redis 配置（可选）
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# JWT 配置
JWT_SECRET=your_jwt_secret_key_at_least_32_characters_long  # JWT密钥（至少32字符，生产环境建议使用复杂字符串）
JWT_EXPIRES_IN=24h  # Token过期时间（如：7d=7天, 24h=24小时, 60m=60分钟）

# 文件上传配置
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=5242880  # 5MB

# 日志配置
LOG_LEVEL=info
```

### 4. 初始化数据库

确保 MySQL 数据库已创建，数据库迁移脚本会在应用启动时自动执行。你也可以手动运行：

```bash
# 数据库迁移脚本会在应用启动时自动执行
# 如需手动执行，可参考 migrations/ 目录下的脚本
```

### 5. 启动服务

**开发模式（热重载）：**
```bash
npm run dev
```

**生产模式：**
```bash
npm start
```

服务启动后，访问：
- 🌐 **API 服务**：http://localhost:3000
- 📚 **API 文档**：http://localhost:3000/api-docs（Swagger UI）
- 🏥 **健康检查**：http://localhost:3000/api/v1/health

## 📚 API 文档

项目集成了 Swagger UI，启动服务后访问 `/api-docs` 即可查看完整的 API 文档。

### API 模块概览

| 模块 | 路径前缀 | 功能描述 |
|------|---------|---------|
| **认证模块** | `/api/v1/auth/*` | 用户注册、登录、密码修改 |
| **用户模块** | `/api/v1/user/*` | 个人信息管理、头像上传 |
| **救助信息** | `/api/v1/rescue/*` | 救助信息发布、浏览、审核、热门推荐 |
| **领养申请** | `/api/v1/adoption/*` | 领养申请提交、审核、跟踪 |
| **志愿者** | `/api/v1/volunteer/*` | 志愿者活动管理、报名、审核 |
| **捐赠管理** | `/api/v1/donation/*` | 捐赠记录、公示、审核 |
| **物资管理** | `/api/v1/material/*` | 物资入库、出库、库存管理 |
| **救助故事** | `/api/v1/story/*` | 救助故事发布、浏览、点赞 |
| **评论模块** | `/api/v1/comment/*` | 评论添加、查看、点赞、删除 |
| **收藏模块** | `/api/v1/favorite/*` | 收藏管理 |
| **消息系统** | `/api/v1/message/*` | 系统通知、站内消息、已读状态 |
| **搜索功能** | `/api/v1/search/*` | 全文搜索、搜索建议 |
| **系统设置** | `/api/v1/system/*` | 系统参数配置 |
| **管理员** | `/api/v1/admin/*` | 后台管理、数据统计、批量操作 |
| **通用功能** | `/api/v1/common/*` | 文件上传、通用接口 |
| **批量操作** | `/api/v1/batch/*` | 批量审核、批量操作 |
| **操作日志** | `/api/v1/log/*` | 操作日志查询 |
| **健康检查** | `/api/v1/health` | 服务健康状态检查 |

### API 认证方式

大部分接口需要 JWT Token 认证，在请求头中添加：

```
Authorization: Bearer {your_jwt_token}
```

获取 Token：通过 `/api/v1/auth/login` 接口登录后获取。

### 响应格式

所有接口统一返回格式：

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {}
}
```

**状态码说明：**
- `200` - 成功
- `201` - 创建成功
- `400` - 参数错误
- `401` - 未登录或Token失效
- `403` - 权限不足
- `404` - 资源不存在
- `500` - 服务器错误

## 🔐 安全特性

- ✅ **JWT 身份认证** - 基于 Token 的无状态认证，支持 Token 过期时间配置
- ✅ **密码加密** - 使用 bcryptjs 进行密码哈希，支持密码强度验证
- ✅ **请求限流** - 防止暴力破解和 DDoS 攻击，支持登录/注册/上传接口独立限流
- ✅ **XSS 防护** - 输入数据过滤和转义，保护敏感字段
- ✅ **SQL 注入防护** - 使用 Sequelize ORM 参数化查询
- ✅ **HTTP 安全头** - 使用 Helmet 设置安全响应头（CSP、XSS Protection等）
- ✅ **CORS 配置** - 跨域请求控制，支持凭证传递
- ✅ **输入验证** - 使用 express-validator 进行参数校验
- ✅ **操作日志** - 记录管理员操作，支持审计追踪

## 📝 日志系统

项目使用 Winston 进行日志管理，支持：

- 📂 **按日期轮转** - 日志文件按天自动分割
- 📊 **多级别日志** - error、warn、info、debug
- 💾 **文件存储** - 错误日志、综合日志、异常日志、拒绝日志分别存储
- 🗜️ **自动压缩** - 旧日志文件自动压缩归档
- 📅 **保留策略** - 默认保留 30 天日志
- 📝 **访问日志** - 记录所有 HTTP 请求（使用 Morgan）

日志文件位置：`./logs/`

## 🧪 开发指南

### 代码规范

项目使用 ESLint 和 Prettier 进行代码规范检查：

```bash
# 检查代码规范
npm run lint

# 自动修复代码规范问题
npm run lint:fix

# 格式化代码
npm run format
```

### 运行测试

```bash
npm test
```

### 数据库迁移

数据库迁移脚本会在应用启动时自动执行。如需手动执行：

```bash
# 迁移脚本位于 migrations/ 目录
# 按顺序执行：001_*.js, 002_*.js, ...
```

### 添加新功能

1. 在 `models/` 目录创建数据模型
2. 在 `controllers/` 目录创建控制器
3. 在 `routes/` 目录创建路由
4. 在 `app.js` 中注册路由
5. 如需数据库变更，在 `migrations/` 目录创建迁移脚本

## 📦 部署

### 生产环境建议

1. **环境变量** - 确保所有敏感信息通过环境变量配置，不要提交 `.env` 文件
2. **数据库** - 使用生产级 MySQL 配置，启用连接池优化
3. **Redis** - 配置 Redis 持久化和高可用（如使用哨兵模式）
4. **日志** - 配置日志收集和监控（如 ELK Stack）
5. **进程管理** - 使用 PM2 或类似工具管理 Node.js 进程
6. **反向代理** - 使用 Nginx 作为反向代理，配置负载均衡
7. **HTTPS** - 配置 SSL/TLS 证书，强制 HTTPS
8. **监控** - 配置应用监控和告警（如 PM2 Plus、New Relic）
9. **备份** - 定期备份数据库和重要文件

### PM2 部署示例

```bash
# 安装 PM2
npm install -g pm2

# 启动应用
pm2 start app.js --name pawguard-backend

# 查看状态
pm2 status

# 查看日志
pm2 logs pawguard-backend

# 设置开机自启
pm2 startup
pm2 save

# 监控
pm2 monit
```

### Docker 部署（可选）

```dockerfile
# Dockerfile 示例
FROM node:16-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "app.js"]
```

### Nginx 配置示例

```nginx
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}
```

## 🎯 性能优化

- ✅ **数据库索引优化** - 为常用查询字段添加索引
- ✅ **Redis 缓存** - 缓存热点数据，减少数据库查询
- ✅ **图片压缩** - 使用 Sharp 自动压缩上传图片
- ✅ **连接池** - Sequelize 连接池配置，优化数据库连接
- ✅ **请求限流** - 防止恶意请求，保护服务器资源
- ✅ **静态文件服务** - 使用 Express 静态文件中间件
- ✅ **日志轮转** - 避免日志文件过大影响性能

## 🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 代码提交规范

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

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情

## 👥 作者

- **ImLinNai** - [Gitee](https://gitee.com/imlinnai)

## 🙏 致谢

感谢所有为流浪动物救助事业贡献力量的开发者和志愿者！

---

**⭐ 如果这个项目对你有帮助，请给一个 Star！**