# PawGuardClient

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

## Basic Information

- **Project Name**: PawGuardClient
- **Description**: PawGuard（爪印守护）一个专业的流浪猫狗救助平台 - 前端项目（开发中）
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

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

## README

## 🐾 PawGuard 前端项目

> 流浪猫狗救助平台前端应用 - 面向救助者、领养人、志愿者、捐赠者与管理员的公益型 SPA

[![Vue 3](https://img.shields.io/badge/vue-3.x-brightgreen.svg)](https://vuejs.org/)
[![Vite](https://img.shields.io/badge/build-vite-blue.svg)](https://vitejs.dev/)
[![Ant Design Vue](https://img.shields.io/badge/ui-Ant%20Design%20Vue-1677ff.svg)](https://antdv.com/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

PawGuard（爪印守护）是一个面向流浪猫狗救助场景的前端单页应用（SPA），用于承载救助信息展示、领养流程指引、志愿者活动、捐赠公示和运营管理后台的全部前台体验。

项目基于 **Vue 3 + Vite + Ant Design Vue** 构建，配合 Pinia 状态管理、完善的路由守卫与测试体系，适合作为中大型业务前端项目的实践范例。

---

## ✨ 核心功能

- **救助信息中心**
  - 查看最新救助信息流（首页卡片瀑布流+详情页）
  - 发布救助线索（通过首页快捷入口或救助列表“发布救助”入口）
  - 救助详情页展示动物基础信息、图片、紧急程度、救助地点等
- **领养流程**
  - 对救助对象发起领养申请
  - 查看「我的领养申请」和单条申请详情
  - 后台进行领养申请审核与结果反馈
- **救助故事 / 用户反馈**
  - 故事列表与详情页
  - 发布救助故事（需登录）
  - 首页「用户之声」模块轮播热门故事与评价
- **志愿者活动**
  - 前台活动列表与活动详情
  - 我的报名记录（需登录）
  - 管理后台发布/管理志愿活动以及报名审核
- **捐赠与物资管理**
  - 前台捐赠公示列表
  - 后台捐赠管理工作台
  - 物资列表、出入库、库存查询等运营能力
- **消息与通知**
  - 前台消息中心：消息列表与详细内容
  - 后台系统消息中心、群发消息等
- **用户中心**
  - 登录 / 注册（支持弹窗登录注册 + 图形验证码人机验证）
  - 个人资料查看与编辑、修改密码
  - 消息未读数提醒、头像及昵称展示
- **管理后台（Admin）**
  - 仪表盘（Dashboard）
  - 救助档案管理、救助故事管理、评论巡检
  - 领养申请审核、志愿者报名审核
  - 捐赠与物资管理、系统设置、用户管理、操作日志
- **系统体验与安全**
  - 首页全屏 Hero Banner、快捷操作入口、响应式布局
  - 基于路由 `meta.requiresAuth` / `requiresAdmin` 的权限控制
  - 安全指令（`v-safe-html` / `v-escape`）防止 XSS
  - PWA 支持与基础性能优化

---

## 🛠️ 技术栈

- **框架**
  - **Vue 3**（Composition API）
  - **Vue Router 4**（前端路由与守卫）
  - **Pinia**（全局状态管理）
- **UI 与交互**
  - **Ant Design Vue 4**（企业级组件库）
  - **@ant-design/icons-vue**（图标）
  - 自定义 `Less` 主题样式、响应式布局与动画效果
- **网络与工具**
  - **Axios** 请求封装（统一错误处理、鉴权拦截）
  - 业务模块化 API（`src/api/modules/*`）
  - 工具库：`dayjs`、`lodash-es` 等
- **构建与工程化**
  - **Vite**（开发与构建）
  - **ESLint + eslint-plugin-vue**（代码规范）
  - **Prettier**（统一格式化）
  - **Vitest + @vue/test-utils + Testing Library**（单元测试）
  - **Playwright**（E2E 测试与性能测试）
  - **vue-tsc**（类型检查）

---

## 📁 目录结构概览

仅列出与业务相关的核心目录，详细结构可参考源码：

- **`src/`**
  - `main.js`：应用入口，挂载 Vue 实例、注册路由、Pinia、Ant Design Vue、PWA 与安全指令
  - `App.vue`：应用根组件与基础布局
  - **`router/`**：路由表与路由守卫（鉴权、标题更新等）
  - **`store/`**：Pinia store，包含用户信息、权限、弹窗登录状态等模块
  - **`api/`**
    - `request.js`：Axios 实例封装
    - `modules/`：按领域拆分的接口模块（`auth`、`rescue`、`adoption`、`volunteer`、`donation`、`system` 等）
  - **`views/`**：页面级组件
    - `home/Index.vue`：首页（Banner、快速入口、救助信息、热门故事）
    - `rescue/*`、`adoption/*`、`story/*`、`volunteer/*`、`donation/*`、`message/*`、`user/*`
    - `admin/*`：管理后台各业务模块
  - **`components/`**
    - `layout/`：基础布局、顶部导航、页脚、后台布局等
    - `auth/AuthModal.vue`：全局登录/注册弹窗（含验证码）
    - `business/`、`common/`：业务通用组件（评论、图片、骨架屏、搜索弹窗等）
  - **`utils/`**：通用工具函数（格式化、校验、人机验证、PWA、响应式等）
  - **`composables/`**：复用逻辑（系统设置、登录弹窗控制等）
  - **`directives/`**：安全相关指令

---

## 🚀 本地开发与构建

### 环境要求

- **Node.js**：`^20.19.0` 或 `>=22.12.0`
- **npm**：建议使用 Node 自带版本或更高

### 安装依赖

```bash
npm install
```

### 启动开发环境

```bash
npm run dev
```

启动后默认访问地址一般为：`http://localhost:5173`（以控制台输出为准）。

### 构建生产包

```bash
npm run build
```

构建完成后可使用：

```bash
npm run preview
```

在本地预览生产构建产物。

---

## ✅ 质量保障

- **代码检查**
  - `npm run lint`：运行 ESLint，并按 `.gitignore` 忽略文件，自动修复可修复的问题
  - `npm run format`：使用 Prettier 统一格式化代码和文档
- **测试**
  - `npm run test:unit`：运行单元测试（Vitest）
  - `npm run test:e2e`：运行端到端测试（Playwright）
  - `npm run test:performance`：运行基于 Playwright 的性能测试
  - `npm run test:coverage`：查看单元测试覆盖率报告
- **类型检查**
  - `npm run type-check`：使用 `vue-tsc` 进行类型检查

---

## 📦 部署建议

项目打包输出为标准静态资源，可部署到任意静态文件服务器或前端托管平台，例如：

- Nginx / Apache / Caddy
- Docker 容器（Nginx 镜像 + 构建产物）
- GitHub Pages、Gitee Pages、Vercel 等

生产环境部署时建议：

- 配置 HTTPS 及 HTTP/2
- 在反向代理中开启压缩（gzip/br）
- 确保刷新路由时由前端接管（如 Nginx `try_files $uri /index.html`）

---

## 🔒 前端安全与体验

- 使用自定义安全指令（`v-safe-html` / `v-escape`）降低 XSS 风险  
- 通过路由守卫与 Pinia Store 校验登录态与权限（普通用户 / 管理员）  
- 统一 Axios 拦截器处理鉴权失效、全局错误提示、Loading 状态  
- 首页与主要模块经过响应式布局与动画优化，兼顾桌面端与移动端体验  
- 集成 PWA 能力，可在支持环境下实现基础离线缓存与安装体验  

---

## 📄 许可证

本前端项目采用 `MIT` 许可证，详见根目录 `LICENSE` 文件。

---

## ⭐ 致谢

- 感谢为 PawGuard 项目贡献代码、设计和测试的所有参与者  
- 感谢每一位关注流浪动物救助事业的人，如果这个项目对你有帮助，欢迎点亮一个 Star 支持持续维护 🙌