jiebanke/README.md

解班客 - 宠物认领平台

一个基于Vue.js和Node.js的宠物认领平台，帮助流浪动物找到温暖的家。

项目概述

解班客是一个专业的宠物认领平台，致力于为流浪动物提供一个温暖的归宿。平台通过现代化的Web技术，为用户提供便捷的宠物发布、搜索、认领服务，同时为管理员提供完善的后台管理功能。

核心功能

• 用户系统: 完整的用户注册、登录、个人信息管理
• 动物管理: 动物信息发布、编辑、状态管理
• 认领流程: 在线认领申请、审核、跟踪
• 地图定位: 基于地理位置的动物搜索和展示
• 管理后台: 用户管理、动物管理、数据统计、文件管理
• 消息通知: 实时消息推送和邮件通知
• 数据统计: 详细的业务数据分析和报表

技术架构

前端技术栈

• 框架: Vue.js 3.x + Composition API
• UI组件: Element Plus
• 状态管理: Pinia
• 路由: Vue Router 4
• 构建工具: Vite
• HTTP客户端: Axios
• 样式: SCSS + CSS Modules

后端技术栈

• 运行时: Node.js 18+
• 框架: Express.js
• 数据库: MySQL 8.0
• 缓存: Redis 6.0
• 认证: JWT + Passport
• 文件处理: Multer + Sharp
• 日志: Winston
• 测试: Jest + Supertest

基础设施

• 容器化: Docker + Docker Compose
• 反向代理: Nginx
• 进程管理: PM2
• 监控: Prometheus + Grafana
• 日志收集: ELK Stack
• CI/CD: GitHub Actions

🗂️ 项目结构

jiebanke/
├── 📁 backend/           # 后端服务 (Node.js + Express)
├── 📁 admin-system/      # 后台管理系统 (Vue 3 + Element Plus)
├── 📁 website/           # 官方网站 (Vue 3)
├── 📁 mini-program/      # 微信小程序矩阵 (原生小程序)
├── 📁 docs/              # 项目文档
├── 📁 scripts/           # 工具脚本
├── 📁 test/              # 测试文件目录
└── 📄 README.md          # 项目说明 (当前文件)

🚀 快速开始

环境要求

• Node.js 16.x+
• MySQL 8.0+
• npm 8.x+

安装依赖

# 安装后端依赖
cd backend && npm install

# 安装后台管理依赖  
cd admin-system && npm install

# 安装官网依赖
cd website && npm install

# 安装小程序依赖
cd mini-program && npm install

启动开发环境

# 启动后端服务
cd backend && npm run dev

# 启动后台管理 (新终端)
cd admin-system && npm run dev

# 启动官方网站 (新终端)
cd website && npm run dev

📖 项目文档

所有详细文档位于 docs/ 目录：

📖 快速导航

文档类型	文档名称	描述	适用人员
🚀 快速开始	系统集成和部署文档	环境搭建、部署流程	开发者、运维
🔧 开发指南	前端开发文档	前端开发规范和指南	前端开发者
🔧 开发指南	后端开发文档	后端开发规范和指南	后端开发者
📋 API参考	API接口文档	完整的API接口文档	全栈开发者
🗄️ 数据设计	数据库设计文档	数据库结构设计	后端开发者、DBA
👨‍💼 管理功能	管理员后台系统API文档	管理后台功能说明	管理员、开发者
📁 文件系统	文件上传系统文档	文件上传和管理	全栈开发者
🔍 监控运维	错误处理和日志系统文档	错误处理和日志	开发者、运维
🧪 质量保证	测试文档	测试策略、用例设计和质量保证	测试工程师、开发者
🔒 安全管理	安全和权限管理文档	安全策略、权限控制、安全防护措施	安全工程师、系统管理员
⚡ 性能优化	性能优化文档	系统性能优化策略、监控方案和优化实践	性能工程师、运维工程师
🚀 部署运维	部署和运维文档	系统部署流程和运维管理方案	运维工程师、DevOps工程师
📊 项目管理	项目开发进度报告	项目进度和规划	项目经理、开发者
📝 开发规范	开发规范和最佳实践	代码规范和标准	全体开发者

核心文档

• 📄 项目概述 - 项目背景、目标和整体介绍
• 📄 系统架构文档 - 系统架构设计和技术栈
• 📄 API接口文档 - 完整的API接口说明
• 📄 数据库设计文档 - 数据库表结构和关系设计
• 📄 开发指南 - 开发环境搭建和开发规范
• 📄 部署指南 - 开发、测试、生产环境部署指南

功能模块文档

文档名称	描述	链接
API接口文档	详细的API接口说明和使用示例	查看文档
管理员后台文档	管理员功能和操作指南	查看文档
用户认证系统文档	用户注册、登录、权限管理	查看文档
动物管理系统文档	动物信息管理和认领流程	查看文档
文件上传系统文档	文件上传、存储和管理	查看文档
数据库设计文档	数据库架构、表结构和关系设计	查看文档
错误处理和日志系统文档	错误处理机制和日志记录	查看文档
系统集成和部署文档	系统部署和运维指南	查看文档
前端开发文档	前端技术架构、组件设计和开发规范	查看文档

项目管理文档

• 项目开发进度报告 - 项目进度跟踪和里程碑规划
• 开发规范和最佳实践 - 团队开发规范和代码标准
• 测试文档 - 测试策略、用例设计和质量保证

补充文档

• 📄 变更日志 - 项目版本变更记录
• 📄 贡献指南 - 如何参与项目开发
• 📄 常见问题 - 开发和使用中的常见问题解答
• 📄 许可证 - 项目许可证信息

🛠️ 开发工具

脚本工具

项目提供了一些有用的开发脚本：

# 数据库连接测试
cd backend && npm run test-db

# API接口测试  
cd backend && npm run test-api

# 数据库初始化
cd backend && npm run db:reset

# 部署脚本 (Linux/Mac)
cd scripts && ./deploy.sh all

# 部署脚本 (Windows PowerShell)
cd scripts && .\deploy.ps1 all

环境配置

复制环境变量模板并配置：

# 后端环境配置
cp backend/.env.example backend/.env

# 后台管理环境配置  
cp admin-system/.env.example admin-system/.env

☁️ 部署

项目支持多种部署方式：

自动部署脚本

在 scripts/ 目录中提供了自动部署脚本，支持 Linux/Mac 和 Windows 系统：

# Linux/Mac 部署所有模块
cd scripts && chmod +x deploy.sh && ./deploy.sh all

# Windows PowerShell 部署所有模块
cd scripts && .\deploy.ps1 all

支持的部署选项：

• all - 部署所有模块
• backend - 部署后端服务
• admin - 部署后台管理系统
• website - 部署官方网站
• mini-program - 构建微信小程序

Docker 容器化部署

每个模块都提供了 Docker 配置文件，可以使用 docker-compose 进行部署：

# 启动所有服务
docker-compose up -d

# 启动指定服务
docker-compose up -d backend

# 查看服务状态
docker-compose ps

手动部署

每个模块也可以手动部署到服务器，具体说明请参考各模块目录中的 DEPLOYMENT.md 文件。

🌐 访问地址

• 后端API: https://webapi.jiebanke.com
• 后台管理: https://admin.jiebanke.com
• 官方网站: https://www.jiebanke.com
• 小程序: 使用微信开发者工具打开 mini-program/ 目录

📦 依赖管理

主要技术栈

后端:

• Node.js + Express.js
• Sequelize ORM
• JWT 认证
• MySQL 数据库

前端:

• Vue 3 + TypeScript
• Element Plus UI
• Vite 构建工具
• Pinia 状态管理

小程序:

• 微信原生小程序
• Vant Weapp UI
• Uni-app 框架

🔧 开发规范

代码风格

• 使用 ESLint + Prettier 统一代码风格
• 遵循 Git Commit 消息规范
• 实行代码审查流程

分支策略

• 采用 Git Flow 工作流
• 功能分支开发
• 发布分支管理

🚀 部署说明

详细部署指南请参考 DEPLOYMENT.md，包含：

• 开发环境部署
• 测试环境部署
• 生产环境部署
• 容器化部署 (Docker)
• 安全配置指南

📞 支持与维护

开发团队

• 后端开发: backend@jiebanke.com
• 前端开发: frontend@jiebanke.com
• 小程序开发: miniprogram@jiebanke.com

运维支持

• 运维团队: ops@jiebanke.com
• 紧急联系: +86-138-0013-8000

📊 版本信息

• 当前版本: v1.0.0
• Node.js: 16.20.2
• Vue: 3.3.4
• MySQL: 8.0.33

---

最后更新: 2024年 📅