3-宠物领养系统 - 功能说明

项目概述

宠物领养系统是一个面向流浪与待领养宠物救助场景的前后端分离 Web 应用，围绕「宠物档案管理 → 领养信息发布 → 领养申请与审核 → 寄养/救助信息流转」组织业务，同时提供管理员后台与普通用户前台两套界面。系统后端基于 Django 3.2 + Django REST Framework 3.14 提供 RESTful API，前端基于 Vue 3.4.29 + Element Plus 2.8.4 + Vite 5.3.1 构建单页应用，数据库使用 MySQL（库名 d_3_adoption_system，utf8mb4），认证采用自定义 JWT Token（PyJWT 2.7.0，HS256），并通过 Token 拦截中间件 + 角色类型（type：ADMIN / USER）实现双角色权限分离。

---

项目概览

✨ 创新点

1. 双角色双界面架构

• 角色由 JWT 承载：登录成功后 Token 的 payload 写入 id、username、type（ADMIN / USER），后续所有请求由中间件解出 request.type。
• 两套独立布局：AdminLayout.vue（后台，左侧管理菜单）与 FrontLayout.vue（前台，顶部导航），登录后按 type 跳转 /admin 或 /。
• 互相隔离：普通用户访问后台会被重定向回前台，管理员访问前台会被重定向回后台。

2. 自定义 JWT 认证与 Token 拦截中间件

• 非标准传递方式：Token 通过请求头 token 字段传递（TokenInterceptorMiddleware 读取 HTTP_TOKEN），前端 axios 请求拦截器统一注入。
• 白名单机制：/common/login、/common/register、/common/retrievePassword 等精确路径与 /uploads/、/static/、/swagger/、/django-admin/ 前缀免登录。
• 有效期 30 天：create_token 默认 timeout=60*24*30 分钟，密钥复用 Django SECRET_KEY，算法 HS256；非法或过期 Token 返回 code=401 由前端跳转登录页。

3. 审核驱动的状态流转与业务联动

• 申请审核接口：领养/寄养申请均提供 approve、reject 两个动作接口，拒绝时必须填写 reject_reason。
• 审核结果自动回写主表：领养申请通过后自动把对应 adoption.adoption_status 置为「已领养」；寄养申请通过后自动把对应 foster.foster_status 置为「已寄养」。
• 前端按状态显隐操作：后台审核页仅在状态为「待审核」时显示「通过 / 拒绝」按钮，并用 el-tag 区分状态颜色。

4. 逻辑外键 + 序列化器连表展示

• 无物理外键：9 张表之间全部使用 xx_id 逻辑关联（如 pet.category_id、adoption.pet_id、foster.owner_id、rescue.publisher_id）。
• 序列化器补全名称：PetSerializer.category_name、AdoptionSerializer.pet_name / pet_breed / pet_image / category_name、FosterSerializer.owner_name、RescueSerializer.publisher_name、AdoptionApplicationSerializer.adoption_title / user_name 等通过 SerializerMethodField 连表查询返回可读名称。

5. 统一响应、全局异常与自动时间戳

• 统一响应体：ResponseMessage 提供 success / failed / other / jump，固定返回 code、msg、data 三字段，前端 axios 响应拦截器按 code 统一提示与跳转。
• 全局异常处理器：utils/exception_handler.py 依次处理自定义异常、Django 内置异常、DRF 异常与未知异常，统一输出标准结构（配合 utils/custom_exception.py 的 NotFound / PermissionDenied / Unauthorized / Validation / Business 异常）。
• 创建时间自动写入：各模型通过 pre_save 信号 pre_save_timestamp_handler 在新增时自动填充 create_time。

6. 配套 Java 代码生成器

• 自动化生成：仓库内 CodeGenerator/ 提供基于 Spring Boot + MyBatis-Plus + Velocity 的生成器（DjangoCodeGenerator、VueCodeGenerator、BatchCodeGenerator）。
• 一键产出：根据数据库表生成 Django 的 models / serializer / views / urls 与 Vue3 管理页面模板（page.vue.vm），并自动注册到 settings.py、urls.py、前端路由与后台菜单。

---

✨ 项目亮点

一、 业务功能亮点

1. 完整的领养闭环：从宠物档案建档、发布领养信息、用户提交领养申请，到管理员审核通过后自动把领养信息置为「已领养」，全流程可追溯。
2. 寄养服务双向撮合：用户可发布寄养需求（含寄养起止日期与每日费用），其他用户提交寄养申请，管理员审核通过后主表状态自动流转为「已寄养」。
3. 救助信息公益板块：用户可自主发布救助信息（救助地点、救助时间、描述、联系方式），并在个人中心维护自己发布的救助记录，后台统一管理救助状态。
4. 个人中心一站式管理：个人信息、我的领养申请、我的寄养申请、我的救助发布、我的寄养发布五个子页面集中管理个人数据。

二、 技术实现亮点

1. 现代化前端技术栈：采用 Vue 3.4.29（Composition API + <script setup>）+ Element Plus 2.8.4 + Vite 5.3.1 + Vue Router 4.4.3 + Pinia 2.2.2 + Axios 1.7.5。
2. 稳定可靠的后端架构：基于 Django 3.2 + Django REST Framework 3.14.0（APIView 风格）+ PyJWT 2.7.0，配合 drf-yasg 1.21.7 自动生成 Swagger 文档。
3. 完善的数据库设计：9 张核心表，全部采用逻辑外键设计、状态字段用中文描述、主键为 bigint 自增、金额字段用 DECIMAL(10,2)，模型统一 managed = False 由 SQL 脚本建表。
4. 丰富的第三方集成：ECharts 5.5.1（数据可视化）、wangEditor 5.1.14（富文本组件）、@wocwin/t-ui-plus 1.4.13（UI 组件库）、sass-embedded 1.83.4（样式编译）。
5. 安全性设计：JWT Token 认证 + 请求头 token 校验、未授权统一返回 401、CORS 白名单请求头仅放行 token 与 content-type、自定义异常统一兜底、修改密码与重置密码均校验操作人身份。

三、 用户体验亮点

1. 双界面设计：后台面向管理员提供完整 CRUD 与审核功能，前台面向用户提供卡片式浏览、详情申请与个人中心，两套布局各自优化。
2. 响应式布局：前台布局内置 @media (max-width: 768px) 断点（隐藏用户名文本、隐藏菜单文字），个人中心使用 Element Plus 栅格 :xs / :sm / :md 自适应。
3. 交互优化：
   • 友好的加载提示和错误提示。
   • 重要操作的确认弹窗。
   • 及时的全局消息提示。
   • 严谨的前后端表单验证。
4. 文件上传体验：统一的 MyUpload.vue 组件，支持图片卡片式列表、点击预览弹窗（图片/视频/音频）、limit=1 时「点击替换」、超出数量提示，并与表单 v-model 双向绑定。

管理员

数据看板

首页统计：查看 4 项核心指标（宠物数量、用户数量、待领养数量、救助信息数量）与 4 张 ECharts 图表（宠物分类分布饼图、领养状态分布柱状图、申请状态分布环形图、近 7 天动态趋势折线图）

账号管理

管理员管理：管理管理员账号，支持新增（未填密码时默认密码 123456）、编辑、单个/批量删除、按用户名与联系方式搜索，可将指定管理员密码重置为 123456

用户管理：管理普通用户账号，支持新增、编辑、单个/批量删除、按用户名与联系方式搜索，可将指定用户密码重置为 123456

宠物管理

宠物分类管理：管理宠物分类（分类名称、分类描述），支持新增、编辑、单个/批量删除、按分类名称搜索

宠物信息管理：管理宠物档案（宠物名称、宠物分类、年龄(月)、性别、品种、毛色、健康状况、宠物照片、详细描述），支持新增、编辑、单个/批量删除、按名称搜索

领养管理

领养信息管理：管理领养信息（选择宠物、标题、领养费用、领养要求、联系方式、地址、领养状态），支持新增、编辑、单个/批量删除、按标题搜索，列表连表展示宠物名称

领养申请管理：查看全部领养申请（领养信息标题、申请人、联系方式、地址、申请理由、状态、拒绝原因、申请时间），对待审核申请执行「通过」或「拒绝」（拒绝需填写拒绝原因），支持删除与按申请人搜索

救助与寄养管理

救助信息管理：管理救助信息（标题、宠物名称、品种、性别、救助地点、救助时间、描述、联系方式、救助状态），支持新增、编辑、单个/批量删除、按标题与宠物名称搜索

寄养信息管理：管理寄养信息（标题、宠物图片、宠物名称、品种、性别、寄养起止日期、每日费用、寄养要求、描述、联系方式、寄养状态），支持新增、编辑、单个/批量删除、按标题搜索

寄养申请管理：查看全部寄养申请，对待审核申请执行「通过」或「拒绝」（拒绝需填写拒绝原因），支持删除与按申请人搜索

个人设置

个人信息：查看并修改当前管理员的用户名、昵称、联系方式、头像

修改密码：校验旧密码后设置新密码，修改成功后清空本地登录态并跳转登录页

普通用户

前台浏览

前台首页：查看轮播 Banner、4 项数据概览（待领养宠物、已成功领养、救助信息、寄养信息）以及待领养宠物、宠物救助、宠物寄养三个板块的最新卡片列表

宠物领养：卡片式浏览领养信息，可按标题搜索，查看领养费用、宠物名称、品种、领养要求与状态

领养详情：查看宠物名称、品种、年龄、性别、健康状况、领养要求、联系方式与地址，并在线提交领养申请（申请人姓名、联系方式、地址、申请理由）

宠物救助：卡片式浏览救助信息，可按标题搜索，查看救助地点、状态与描述

救助详情：查看救助信息详情

宠物寄养：卡片式浏览寄养信息，可按标题搜索，查看宠物名称、品种、每日费用、寄养起止时间与寄养状态

寄养详情：查看寄养信息详情，并在线提交寄养申请（申请人姓名、联系方式、地址、申请理由）

发布与管理

发布救助信息：填写标题、宠物图片、宠物名称、品种、年龄、性别、救助地点、救助时间、描述、联系方式、救助状态后发布

发布寄养信息：填写标题、宠物图片、宠物名称、品种、年龄、性别、寄养起止日期、每日费用、寄养要求、描述、联系方式、寄养状态后发布

我的救助发布：查看自己发布的救助信息，可查看详情、编辑、删除

我的寄养发布：查看自己发布的寄养信息，可查看详情、编辑、删除，并可跳转发布新寄养信息

我的领养申请：查看自己提交的领养申请记录及其状态，可删除记录

我的寄养申请：查看自己提交的寄养申请记录及其状态，可删除记录

个人中心

个人信息：查看用户名、昵称、邮箱、联系方式，并可跳转编辑信息与修改密码

编辑个人信息：修改昵称、联系方式、头像

修改密码：校验旧密码后设置新密码，修改成功后清空本地登录态并跳转登录页

注册账号：自助注册（选择用户类型、用户名、密码、昵称、头像），用户名重复时给出提示

找回密码：通过已注册手机号（contact）提交新密码，后端按手机号查找用户并更新密码（验证码字段仅为表单占位，代码中未做校验）

---

功能权限对照表

功能模块	管理员	普通用户
后台首页统计与图表	✓	-
管理员管理	✓	-
用户管理	✓	-
宠物分类管理	✓	-
宠物信息管理	✓	-
领养信息管理	✓	-
领养申请审核（通过/拒绝）	✓	-
救助信息管理	✓	-
寄养信息管理	✓	-
寄养申请审核（通过/拒绝）	✓	-
重置他人密码	✓	-
前台首页	-	✓
领养信息浏览与详情	-	✓
提交领养申请	-	✓
我的领养申请（仅自己的）	-	✓
救助信息浏览与详情	-	✓
发布救助信息	-	✓
我的救助发布（仅自己的，可编辑/删除）	-	✓
寄养信息浏览与详情	-	✓
发布寄养信息	-	✓
我的寄养发布（仅自己的，可编辑/删除）	-	✓
提交寄养申请	-	✓
我的寄养申请（仅自己的）	-	✓
个人信息 / 修改密码	✓	✓
注册 / 找回密码	✓	✓

说明：两套界面的角色隔离由前端布局完成（AdminLayout 拒绝 USER、FrontLayout 拒绝非 USER）；后端除 /common/resetPassword 显式校验 request.type == "ADMIN" 外，其余接口统一由 Token 中间件做登录校验，并以 Token 中的用户 ID 限定「仅自己的」数据（如 foster/myPage、rescue/myPage、adoption/application/myPage）。

---

状态说明

领养信息状态（adoption.adoption_status）

• 待领养：领养信息已发布，等待用户申请（新增时未传则默认为「待领养」）
• 已领养：领养申请审核通过后由系统自动置为该状态

领养申请状态（adoption_application.application_status）

• 待审核：用户已提交申请，等待管理员处理（提交时未传则默认为「待审核」）
• 已通过：管理员审核通过，reject_reason 被清空，同时关联领养信息置为「已领养」
• 已拒绝：管理员审核拒绝，需填写 reject_reason 拒绝原因

寄养信息状态（foster.foster_status）

• 待寄养：寄养信息已发布，等待用户申请（新增时未传则默认为「待寄养」）
• 已寄养：寄养申请审核通过后由系统自动置为该状态
• 已结束：寄养周期结束（前端状态选项与初始化数据中存在该取值）

寄养申请状态（foster_application.application_status）

• 待审核：用户已提交申请，等待管理员处理（提交时未传则默认为「待审核」）
• 已通过：管理员审核通过，reject_reason 被清空，同时关联寄养信息置为「已寄养」
• 已拒绝：管理员审核拒绝，需填写 reject_reason 拒绝原因

救助信息状态（rescue.rescue_status）

• 待救助：救助信息已发布，等待救助（新增时未传则默认为「待救助」）
• 救助中：救助正在进行
• 已救助：救助已完成

---

默认账号

管理员

用户名: admin
密码: 123456
用户类型: ADMIN（登录页请选择「管理员」）

测试用户

用户名: zhangsan
密码: 123456
用户类型: USER（登录页请选择「用户」）

用户名: lisi
密码: 123456

用户名: wangwu
密码: 123456

密码在数据库中按明文存储（admin、user 表的 password 字段为 varchar(25)，登录时直接比对），以上账号来自 project/sql/sql.sql 初始化数据。project/test_data.sql 另提供 10 个测试用户（zhangsan、lisi、wangwu、zhaoliu、sunqi、zhouba、wujiu、zhengshi、liuer、liuerma）与管理员 admin、admin2，密码同为 123456。

---

核心业务流程

注册与登录流程

1. 用户在注册页填写用户类型、用户名、密码、昵称、头像，提交 PUT /common/register
2. 后端校验用户名是否重复，重名返回「用户名重复」
3. 校验通过写入 user 表（接口白名单免登录）
4. 用户在登录页选择用户类型（管理员 / 用户），提交 POST /common/login
5. 后端按类型分别查询 admin 表或 user 表，比对 password 字段
6. 比对成功生成 JWT Token（payload：id、username、type），返回用户信息 + token + type
7. 前端把 token 与 currentUser 写入 localStorage，按 type 跳转 /admin 或 /

领养申请审核流程

1. 管理员在「领养信息管理」新增领养信息（选择宠物、填写标题、领养费用、领养要求、联系方式、地址、领养状态）
2. 用户在「宠物领养」列表浏览，进入详情页查看宠物信息与领养要求
3. 用户填写申请人姓名、联系方式、地址、申请理由，提交 POST /adoption/application/add
4. 后端把 user_id 固定为 Token 中的当前用户，application_status 默认为「待审核」
5. 管理员在「领养申请管理」查看申请列表（连表展示领养信息标题）
6. 管理员点击「通过」POST /adoption/application/approve：申请状态置「已通过」且清空拒绝原因，关联领养信息状态自动置「已领养」
   或点击「拒绝」POST /adoption/application/reject：申请状态置「已拒绝」并记录拒绝原因
7. 用户在个人中心「我的领养申请」查看审核结果与拒绝原因

寄养发布与申请流程

1. 用户在「宠物寄养」页点击发布，填写标题、宠物图片、宠物名称、品种、年龄、性别、寄养起止日期、每日费用、寄养要求、描述、联系方式、寄养状态，提交 POST /foster/add
2. 后端把 owner_id 固定为 Token 中的当前用户，foster_status 默认为「待寄养」
3. 其他用户在寄养列表浏览并进入详情，填写联系方式、地址与申请理由，提交 POST /foster/application/add
4. 后端把 user_id 固定为当前用户，application_status 默认为「待审核」
5. 管理员在「寄养申请管理」审核：通过则申请状态置「已通过」且寄养信息状态自动置「已寄养」；拒绝则置「已拒绝」并记录原因
6. 发布者在个人中心「我的寄养发布」查看与维护自己的寄养信息，申请者在「我的寄养申请」查看结果

救助信息发布流程

1. 用户在「宠物救助」页点击发布救助信息，填写标题、宠物图片、宠物名称、品种、年龄、性别、救助地点、救助时间、描述、联系方式、救助状态
2. 提交 POST /rescue/add，后端把 publisher_id 固定为 Token 中的当前用户，rescue_status 默认为「待救助」
3. 用户在个人中心「我的救助发布」查看自己发布的记录，可编辑（PUT /rescue/update）或删除（DELETE /rescue/delete）
4. 管理员在「救助信息管理」维护全部救助信息并切换救助状态（待救助 / 救助中 / 已救助）

---

技术说明

系统架构

• 前端：Vue 3.4.29 + Element Plus 2.8.4 + Vite 5.3.1
• 后端：Django 3.2 + Django REST Framework 3.14.0
• 数据库：MySQL（库名 d_3_adoption_system，字符集 utf8mb4）
• 认证：自定义 JWT Token（PyJWT 2.7.0，HS256，请求头 token 传递）
• API 文档：drf-yasg 1.21.7（Swagger UI）

访问地址

• 后端API：http://localhost:8000
• 前端页面：http://localhost:5173（开发环境）
• API文档：http://localhost:8000/swagger/
• Django管理后台：http://localhost:8000/django-admin/

数据库

• 数据库名：d_3_adoption_system
• 字符集：utf8mb4
• 总表数：9 张表（admin、user、pet_category、pet、adoption、adoption_application、rescue、foster、foster_application）

模型类	数据表	说明
Admin	admin	管理员表
User	user	用户表
PetCategory	pet_category	宠物分类表
Pet	pet	宠物表
Adoption	adoption	领养信息表
AdoptionApplication	adoption_application	领养申请表
Rescue	rescue	救助信息表
Foster	foster	寄养信息表
FosterApplication	foster_application	寄养申请表

API接口规范

RESTful风格：
GET    /module/page          # 分页查询
POST   /module/add           # 新增
PUT    /module/update        # 更新
DELETE /module/delBatch      # 批量删除

响应格式：
{
    "code": 200,
    "msg": "操作成功",
    "data": {...}
}

主要API端点：
/common/login                # 登录（白名单）
/common/register             # 注册（PUT，白名单）
/common/retrievePassword     # 找回密码（白名单）
/common/currentUser          # 获取当前登录用户
/common/updateCurrentUser    # 更新当前用户信息
/common/updatePassword       # 修改密码
/common/resetPassword        # 重置密码（仅管理员）
/common/statistics           # 首页数据概览与图表数据
/file/upload                 # 文件上传

/admin/page|list|add|update|delete|detail                  # 管理员管理
/user/page|list|save|delete                                # 用户管理
/pet/page|list|add|update|delete|delBatch|detail           # 宠物信息
/pet/category/page|list|add|update|delete|delBatch|detail  # 宠物分类
/adoption/page|list|add|update|delete|delBatch|detail      # 领养信息
/adoption/application/page|myPage|list|add|update|delete|delBatch|detail|approve|reject  # 领养申请
/rescue/page|myPage|list|add|update|delete|delBatch|detail # 救助信息
/foster/page|myPage|list|add|update|delete|delBatch|detail # 寄养信息
/foster/application/page|myPage|list|add|update|delete|delBatch|detail|approve|reject    # 寄养申请

JWT Token配置

有效期: 30天（timeout = 60 * 24 * 30 分钟）
算法: HS256，密钥取 Django SECRET_KEY
传递方式: HTTP请求头 token 字段
包含信息: id、username、type（ADMIN / USER）
白名单（精确匹配）: /common/login、/common/register、/common/retrievePassword、/goods/uPage、/love、/goods/getGoodsByCategoryId、/category/list
白名单（前缀匹配）: /uploads/、/static/、/swagger/、/django-admin/

分页规范

请求参数: pageNum（页码，从 1 开始）、pageSize（每页条数，默认取 settings.PAGE_SIZE = 10）
返回结构: { "total": 总条数, "list": [...] }
前端分页可选每页条数: 后台 5 / 10 / 20 / 50；前台领养列表与救助列表 6 / 12 / 24（默认 12），前台寄养列表 12 / 24 / 36 / 48（默认 12），个人中心各列表 5 / 10 / 20（默认 10）

---

系统特色

富文本编辑

• 组件：components/MyEditor.vue，基于 @wangeditor/editor 5.1.14 + @wangeditor/editor-for-vue 5.1.12，工具栏使用 <Toolbar> + <Editor>，编辑器高度 400px。
• 上传对接：编辑器内图片/视频上传指向 VITE_APP_API_URL + "/file/upload"，请求头携带 token，字段名为 file，通过 customInsert 回填返回的 URL；视频上传配置 maxFileSize 为 100 * 1024 * 1024。
• 使用说明：该组件在 views/admin/Admin.vue、views/admin/User.vue 中被引入；当前各业务页面中的长文本字段（如领养要求、寄养要求、详细描述）均使用 el-input type="textarea" 多行文本域录入。

数据可视化

• 组件：ECharts 5.5.1
• 图表：宠物分类分布（饼图）、领养状态分布（柱状图）、申请状态分布（环形图）、近 7 天动态趋势（折线图，含新增宠物/领养信息/申请数量/救助信息四条曲线）
• 位置：管理后台首页（views/admin/Home.vue），数据来源 /common/statistics，并在窗口 resize 时自动 resize()

文件上传

• 上传接口：POST /file/upload，表单字段名 file，需携带请求头 token
• 存储方式：保存到 settings.UPLOAD_PATH（uploads\，相对于项目根目录），文件名使用 uuid4() + 原文件扩展名，目录不存在时自动创建
• 访问格式：http://127.0.0.1:8000/uploads/{唯一文件名}（由 settings.HTTP_PICTURE 拼接返回）
• 前端限制：MyUpload.vue 组件默认 limit=100，图片类型设置 accept="image/*"，支持单文件替换、预览与删除