基于Python与Vue的校园流浪动物领养募捐系统设计与实现

晚上十一点从实验室出来，那窝流浪猫又蹲在垃圾桶边上等投喂。橘猫的右后腿好像瘸了，想送去医院又怕耽误项目答辩，更担心治完没人管、猫还是回到原处流浪。这种两难的心情，校园里几乎每个路过的人都经历过——想帮，但不知道帮到哪一只；捐了钱，看不到去向；想领养，又不知道流程该怎么走。跟社团几位同学聊了几轮，最后决定做一套校园流浪动物领养募捐系统，用 Python 做后端、Vue 做前端，把"领养申请"和"募捐公开"两条线完整落地。这篇文章把整套设计与实现拆开讲，包括需求分析、数据建模、前后端实现、部署细节和我实际踩过的坑，给正在做同类课程设计、毕业设计，或者想给学校流浪动物组织搭信息系统的同学当参考。

这个项目听起来像普通的"管理后台"，但真正做起来就会发现它跟图书管理系统、学生管理系统完全不一样。它有三个角色在同时使用系统，三套流程互相穿插，稍不留神就把权限和状态搅成一锅粥。

1. 为什么校园流浪动物系统不能照搬"通用管理后台"

1.1 这个项目真正的难点不在代码量

我见过不少同学拿到这类题目之后，先打开一个 Vue 后台管理模板，画几个增删改查页面，再对着宠物表做一套 CRUD 接口，就认为完成了。这其实只做了外壳，没有做内核。流浪动物领养系统表面上要管的是一只猫的信息，实际上要管的是信任、流程和善意的闭环。

拿最实际的场景说：学生A在系统里看到一只流浪猫，觉得投缘，申请领养。管理员接受了申请，此猫状态变成"已被领养"。半个月后，如果学生A因为宿舍不让养又偷偷把猫放回校园，系统能记录这个事实吗？下一次有人再申请领养，管理员能提前看到这个人之前有过"弃养记录"吗？这就是状态机和用户行为记录的用武之地，不是单纯改一个is_adopted字段就能解决的。

再看看募捐侧。社团在系统里发了一个"为橘猫做腿部手术筹款"的项目，目标金额 2000 元。捐款人B捐了 50 元，系统需要同时做两件事：给项目累计金额加 50，同时生成一条属于B的捐款凭证。如果其中任何一步失败，账就对不上。这种“双写一致性”问题，在真实的募捐场景里非常敏感。

1.2 标题里藏着的三类用户冲突

系统涉及三类核心用户，需求是互相拉扯的：

• 普通学生 / 领养申请者：希望页面好看、操作简单、能快速看到动物的照片和健康信息，申请后随时能查进度。
• 社团管理员 / 志愿者：希望后台能高效处理申请、批量更新动物状态、导出募捐明细，同时权限分明、操作可追溯。
• 关注者 / 捐赠人：希望看到每一笔钱用在哪里、募捐进度实时更新、领养结果公开透明。

这个冲突从一开始就决定了：你不能只在后端做一套通用接口，前面套一个通用模板。必须给前台访客设计一个信息透明、低门槛的展示端，给管理员设计一个高密度、可审核的管理端，两边逻辑分层，但共享同一套业务数据。

2. 技术栈选型：为什么是 Vue 配 Python 而不是别的组合

2.1 后端框架取舍：Flask 还是 Django

收到这类题目，很多人会纠结 Flask 和 Django。我的建议是：如果项目规定"基于 Python 实现"，优先考虑 Flask + SQLAlchemy 组合，除非你确实需要 Django Admin 来快速搭建运营后台。

为什么？这个项目本质是 API 服务。Vue 负责渲染页面，后端只需要提供 JSON 数据。Flask 足够轻、够直观，一个文件能跑通，中间件和扩展自己挑，代码读起来像讲故事。Django 自带 Admin、ORM、迁移、认证，确实一套很全，但对于纯前后端分离项目，很多内置能力用不上，模型和序列化反而要额外处理，学习曲线对初学者并不友好。

当然这绝不是一刀切。如果你对 Django 更熟，完全可以用 Django REST Framework 写。核心业务逻辑的难度不在框架本身，而在你对流程状态和权限边界的理解。我这次选用 Flask，理由很实在：代码量少、调试直观、团队里另外几个同学能快速看懂，上服务器部署也不用为静态文件另做一套处理。

2.2 前端搭配：Vue 3 + Element Plus 的适配度

前端选 Vue 3 有几个很现实的考量：

• Vue 3 的 Composition API 在处理复杂表单和复用逻辑时很舒服，比如领养申请信息、动物筛选条件、分页状态。把这些抽成useAnimalList、useAdoptionApplication之类的组合式函数，页面代码一下子变得干净。
• Element Plus 是一套现成的组件库，表格、表单、弹窗、上传组件都有，能省掉大量样式时间。校园系统不需要炫酷的前端动效，稳定、清晰、好用才是第一位的。
• 和后端 API 结合的生态成熟，axios加拦截器、vue-router加路由守卫、pinia存用户状态，这一套组合在同类项目里几乎算标准答案，遇到问题社区里都有现成方案。

2.3 数据库选型与部署成本

数据上用 MySQL，理由不多说，就是稳、通用、任何服务器都有运维经验。ORM 用 SQLAlchemy，迁移工具用 Alembic。开发阶段用 SQLite 跑单元测试，部署时切到 MySQL，只需要改一个连接地址，ORM 层基本上不用动。

开发环境装出来大约是：

选完这套组合，我心里的一块石头落了地：这个项目既不会因为技术栈太冷门而查不到资料，也不会因为框架太笨重而拖慢进度。

3. 需求拆解：从"领养"和"募捐"两个动作倒推数据表

3.1 领养流程的状态机设计

领养不是一锤子买卖。我在需求阶段画过一版流程，发现从"看到动物"到"真正带回家"至少要经过六个状态：

待审核 → 待沟通 → 待交接 → 已领养 → 已被退回 → 已结束

"待沟通"是很多第一次做的人最容易丢的环节。领养人提交申请后，管理员需要线下沟通（问宿舍条件、问家人意见、问饲养经验），聊完才决定是否批准。如果系统里直接表单一提交就变成"已领养"，那管理员后续想拒绝都没有中间状态可以使用。

对应的动物状态也要跟着变：

• 待领养：正常展示在首页
• 已申请：该动物有人提交申请，但未完成审核（这里要注意，不一定锁定不能看，只是减少重复申请）
• 已领养：完成交接，属于"已离校"
• 暂不开放：动物在治疗中、性格观察期或暂时无人照看

每个状态变更都要记录adoption_logs，字段包括“谁操作的、从什么状态变到什么状态、备注原因”。这不仅是审计需求，也是给普通用户看的"进度可见"基础。没有日志，管理员说"审批通过了"，用户凭什么相信？有了日志，每次变更都带时间戳和操作人，信任感就建立起来了。

3.2 募捐模块的边界：做模拟支付还是对接真实渠道

这是合规问题，也是权益问题。校园社团一般不具备公开募捐资质，如果我在系统里直接对接真实支付通道，会碰红线。所以我当时和团队定的方案是：系统内置"模拟捐赠"功能，生成虚拟订单并记录捐赠人信息，不实际收款，为将来接入合规渠道预留好接口。

设计捐赠表的时候就要做好扩展：

class DonationOrder(Base): __tablename__ = "donation_order" id = Column(Integer, primary_key=True) project_id = Column(Integer, ForeignKey("donation_project.id"), nullable=False) user_id = Column(Integer, ForeignKey("user.id"), nullable=False) amount = Column(Numeric(10, 2), nullable=False) status = Column(String(20), default="pending") # pending / paid / refunded channel = Column(String(20), default="mock") transaction_no = Column(String(64), unique=True, index=True) created_at = Column(DateTime, default=datetime.utcnow)

status虽然叫支付状态，但在模拟场景下就是一个流程标记；transaction_no生成唯一单号，为将来真的接第三方支付做准备。这个设计让项目在演示时完整可用，又不会引火烧身。

3.3 用户权限的漏斗式设计

系统的用户角色我设置了三个：admin、volunteer、user。admin 拥有全部权限，volunteer 可以处理领养申请、编辑动物资料、管理自己的募捐项目，普通 user 只能浏览、申请领养、查看捐赠记录。

但角色不等于权限。我刻意避免在接口里只依赖is_admin这种二值判断。而是用"最小权限"原则写了两个装饰器：

def role_required(*roles): def decorator(f): @wraps(f) def wrapper(*args, **kwargs): current_user = get_jwt_identity() user = User.query.get(current_user["user_id"]) if user.role not in roles: return jsonify({"code": 403, "msg": "没有权限操作"}), 403 return f(*args, **kwargs) return wrapper return decorator

然后在具体接口上标清楚哪些角色能调用，比如：

• 提交领养申请：user或更高
• 审核领养申请：volunteer或admin
• 创建募捐项目：volunteer或admin
• 删除用户：仅admin

这个漏斗式的设计看似简单，实际上避免了很多事故。后面前端就算有人绕过按钮直接调接口，权限判断依然在后端兜底。

4. 后端实现：从零搭一个能真正跑起来的服务端

4.1 用户认证与 JWT 踩坑

认证方案我选了 JWT，原因很简单：前后端分离架构下，JWT 不需要服务端保存会话信息，用户信息直接放进 token，客户端每次请求带上Authorization: Bearer <token>。Flask 生态里现成库是flask-jwt-extended。

登录接口的核心逻辑：

@app.post("/api/login") def login(): data = request.get_json() user = User.query.filter_by(username=data.get("username")).first() if user and check_password_hash(user.password_hash, data.get("password")): access_token = create_access_token( identity={"user_id": user.id, "role": user.role}, expires_delta=timedelta(hours=12) ) return jsonify({"code": 0, "data": {"access_token": access_token, "role": user.role}}) return jsonify({"code": 40001, "msg": "用户名或密码错误"}), 401

这里有个容易踩的点：identity如果只放user_id，每次请求要重新查库才能拿到角色；如果直接把整个用户对象塞进 token，token 就会很长。最佳实践是把user_id和role两个值放进去，既不臃肿又能快速做权限判断。

还有密码安全。我曾见过有人直接把明文密码存在数据库里，这是万万不行的。用werkzeug.security自带的generate_password_hash和check_password_hash已经足够，没必要自己写加密算法。

4.2 动物信息管理的上传思路

动物信息除了基本字段（名称、种类、性别、年龄、毛色、绝育情况、健康状况），最核心的是图片。前端用 Element Plus 的el-upload传到后端，后端不能直接把文件存进数据库字段，但也不能随便往项目根目录一通乱存。

我的做法是：

UPLOAD_FOLDER = os.path.join( os.path.dirname(__file__), "static/uploads" ) @app.post("/api/animal/image") @jwt_required() @role_required("admin", "volunteer") def upload_animal_image(): file = request.files.get("file") if not file: return jsonify({"code": 40000, "msg": "未收到文件"}), 400 suffix = os.path.splitext(file.filename)[1].lower() if suffix not in {".jpg", ".jpeg", ".png", ".webp"}: return jsonify({"code": 40000, "msg": "仅支持图片格式"}), 400 filename = str(int(time.time() * 1000)) + suffix file.save(os.path.join(UPLOAD_FOLDER, filename)) return jsonify({"code": 0, "data": {"url": f"/static/uploads/{filename}"}}), 201

文件名用时间戳加毫秒级随机串，避免重名覆盖。上传目录用变量UPLOAD_FOLDER指出来，部署时直接改配置，不把路径写死。这里我发现一个常见的坑：开发时图片能正常显示，部署后图片全裂，原因多半是静态文件没有交给 Nginx 处理，后面会专门讲。

4.3 捐赠记录与统计的并发处理

募捐进度不能拍脑袋加。每当有人捐赠成功，donation_project.raised_amount和donation_order必须保持一致。如果同时有 10 个人都在捐赠，两个请求同时读到旧的raised_amount，各自加 50，最后只加了 50，而不是 500。这就是并发更新丢失。

SQLAlchemy 层面的解法是用with_for_update()对项目行加锁：

@app.post("/api/donation/project/<int:project_id>/donate") @jwt_required() def donate(project_id): project = DonationProject.query.filter_by(id=project_id).with_for_update().first() ... project.raised_amount = project.raised_amount + amount db.session.add(DonationOrder(...)) db.session.commit()

注意把两条写操作放在同一个事务里，任何一个失败就回滚。实际演示的时候，我用十线程并发各捐 1 元做了一个 10 元募捐测试，确认最终金额是 10 元而不是 1 元，这个测试很能说明问题。

5. 前端实现：Vue 项目结构与核心页面拆解

5.1 前台展示页面的交互设计

前台首页是访客见到系统的第一眼，承载了"展示当前待领养动物"和"募捐项目进度"两大功能。这里我不建议做太花哨的轮播图，因为动物信息是实时变化的，今天这只被领养了，明天又新救助了一只。做一组卡片流更合适：每只动物一张卡片，显示图片、名字、健康状况标签、状态徽标，下面放"查看详情"和"申请领养"两个入口。

动物详情页要完整展示档案信息，包括最近一次驱虫时间、疫苗记录、性格描述，替换掉冷冰冰的列表。细节上有一个值得做的功能：把领养进度条展示出来。这里展示的不是募捐进度，而是这只动物的领养状态流转时间线，让人觉得系统是"活"的。

募捐进度条用 Element Plus 的el-progress配合百分比显示，后端返回raised_amount和target_amount两个字段，前端除法算百分比。前端不要直接计算再传给后端，避免脏数据。

5.2 后台管理页面的表格、表单与弹窗

管理端我做了四个核心页面：动物管理、领养申请处理、募捐项目管理、用户管理。整体用一个侧边栏布局，Vue Router 配置嵌套路由，两侧菜单跟权限挂钩。

动物管理页面的表格列我花了心思。除了基础信息外，加了一个"来源"列，记录是同学发现的还是社团救助的。这一列对志愿者来说很有价值，因为能看出校园里哪些区域流浪动物比较集中，方便安排诱捕绝育工作。

申请处理页面是整个后台最重要的部分。管理员点进一条申请，能看到申请人的完整资料（学号、宿舍楼栋、养宠经验说明）、申请的动物信息、申请时间和当前状态。审核操作是三个按钮：通过、待沟通、拒绝。每次点击后调后端接口，同时更新adoption_logs，这样在前台用户端才能看到进度。

5.3 与后端对接的请求层封装

Vue 侧的请求层我用了一个 axios 实例统一管理：

import axios from 'axios' const service = axios.create({ baseURL: '/api', timeout: 10000 }) service.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) { config.headers.Authorization = `Bearer ${token}` } return config }) service.interceptors.response.use( response => response.data, error => { if (error.response && error.response.status === 401) { localStorage.removeItem('token') window.location.href = '/login' } return Promise.reject(error) } )

这个封装有两个关键点。第一，baseURL设成/api，开发时用 Vite 的 proxy 代理到本地 Flask，部署时用 Nginx 反向代理到 Gunicorn，前端代码一行不用改。第二，响应拦截器里统一处理 401，token 过期或者未登录就直接送到登录页，避免每个页面重复写判断。

路由守卫我加了一重校验，访问需要权限的页面时先看localStorage里有没有 token 和角色信息，没有就跳登录。但这层只是交互优化，真正安全永远以后端为准。

6. 最容易翻车的几个点（实测教训）

6.1 图片上传的存储路径与环境切换

开发时上传的图片放在本机static/uploads，一张张都能看。到了部署机上，FLASK_APP启动目录跟sys.path不一样，__file__相对路径算错，图片就被存到了一个完全找不到的地方。我的解决办法是写一个配置函数：

BASE_DIR = os.path.abspath(os.path.dirname(__file__)) UPLOAD_FOLDER = os.path.join(BASE_DIR, "static", "uploads") ALLOWED_EXTENSIONS = {"png", "jpg", "jpeg", "webp"}

凡是用到文件路径的地方，一律基于BASE_DIR拼，不依赖当前工作目录。部署后还要检查static/uploads目录的写权限，服务器上没给www-data写权限的话，上传接口会直接 500。

6.2 跨域配置与请求拦截

前后端分离开发时，"跨域"几乎必出。Flask 后端设置Access-Control-Allow-Origin的方式很多，但如果你在 Vite 里已经配置了代理，开发阶段实际上没有跨域问题。真正的跨域出现在部署后：

前端在http://xxx.com，后端 Gunicorn 在http://xxx.com:5000。如果直接让前端调http://xxx.com:5000/api/...，浏览器会拦截跨域请求。我在实测中最省心的方案是不让前端直连后端端口，而是用 Nginx 把https://xxx.com/api/反向代理到127.0.0.1:5000：

location /api/ { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }

这样前端代码里所有请求都走同源，不存在跨域问题，也顺便把后端的端口对外隐藏了。

6.3 数据权限：不能让普通用户直接调管理员接口

有次做内部测试，我在浏览器控制台手动执行了一段 fetch，访问管理员接口修改了某只动物的状态。这提醒我一个严肃的问题：前端隐藏入口只是一层遮羞布，后端权限校验才是真正的锁。

在 Flask 里，每个写操作都要加上role_required装饰器，或者校验current_user.role是否在允许范围内。尤其是删除动物和删除用户这类高危操作，必须只有admin能调。这不只是安全要求，也符合"系统要有审计能力"的原始需求——出了事能追责。

还有一个小坑：删除动物时，如果有领养申请记录引用它的外键，直接删除会报 500。我最后改用软删除，给animal表加一个is_deleted字段，列表查询默认过滤掉已删除的。这样历史申请单还能看到动物曾经的信息，不会因为记录被删而出现孤儿数据。

7. 部署与验证：让系统真正跑在校园服务器上

7.1 服务器环境准备

部署环境我用的是最常规的 Ubuntu 服务器。流程分成四步：

1. 安装 Python 3.10、MySQL、Nginx。
2. 创建虚拟目录，克隆代码，用pip安装依赖。
3. 用flask db upgrade执行数据库迁移，初始化管理员账号。
4. 写一个 Gunicorn systemd 服务文件，让 Flask 进程常驻后台。

Gunicorn 是 Python 社区最常用的 WSGI 容器，直接用：

gunicorn -w 4 -b 127.0.0.1:5000 "app:create_app()"

-w 4表示开 4 个 worker，普通校园项目这边绰绰有余。注意绑定地址必须写127.0.0.1，后面交给 Nginx 转发，不要直接暴露 5000 端口公网。

前端部分，在本地服务器上执行npm run build，生成的dist目录交给 Nginx 当静态文件用。因为我的接口走/api前缀，所以 Nginx 配置里非常顺：

server { listen 80; server_name _; root /var/www/stray-animal/dist; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:5000; } location /static/ { alias /var/www/stray-animal/server/static/; } }

这里核心点在于：try_files ... /index.html交给 Vue Router 处理前端路由，/api反代给后端，/static指到上传图片的目录。三个 location 各司其职，前端路由刷新后不会 404，图片放大后不会失效。

7.2 配置完成后的冒烟测试清单

部署完不能只看"主页能打开"就宣布完工。我列了一张冒烟测试清单，逐条过，每条都涉及项目核心功能：

这九条过完，系统基本具备可演示、可提交、可上线的状态。我实测中卡得最久的是第五项：用户取消申请后，动物状态要能从"已申请"恢复成"待领养"。最初我没有做这个反向状态流转，管理员只能手动去改，这明显不符合实际需求，后来在状态机里补了一条"取消申请"的合法迁移路径才解决。

7.3 验收时容易被问到的几个问题

做完项目给导师验收或者给社团负责人演示时，对方通常会问几个"为什么"：

• "为什么募捐不直接收钱？"——答：校园社团不具备公开募捐资质，系统设计为模拟捐赠并预留支付接口，是合规且可扩展的做法。
• "怎么保证领养人不是冲动领养？"——答：申请表单里强制填写养宠经验、宿舍情况、紧急联系人字段，管理员需要线下沟通后才批准，系统内记录完整审核日志。
• "数据多久能备份一次？"——答：MySQL 每天定时备份，同时项目核心数据（动物档案、领养记录、捐赠明细）通过 Flask 管理命令可导出 Excel，方便线下归档。

这几个回答最好事先在文档里写好，因为它们是系统设计深度的体现，甚至比代码本身更能说明你理解了需求。

最后说几句实际体会

整套系统从需求梳理到部署上线，前后改了三轮。第一轮纠结技术栈，第二轮纠结状态机，第三轮才发现最花时间的不是代码，而是把"流程"理顺。校园流浪动物这件事，真正做起来涉及的细节远超预期：一只猫的救助记录可能有"目击——诱捕——体检——驱虫——治疗——静养——待领养——交接"八个阶段，中间任何一环断掉，都不算完整闭环。

我自己最满意的一个功能改动是加"退回记录"。系统允许管理员在动物被领养后继续跟踪，如果领养人因故退回，动物会重新进入待领养列表，同时保留一段 "shelter_previously_adopted" 的标签。这样其他申请者能看到这只动物有过一次退回经历，对它的性格和饲养难度提前有预期，避免二次退回的恶性循环。

如果你也要做类似的项目，我的建议是：先围着你身边的真实流浪动物救助组织转一圈，看看他们处在哪个环节最痛，然后把你看到的那条真实流程原封不动搬进系统。哪怕这个系统最终只是能在校园里帮十几个人完成领养审批，它的价值也远远大于一个功能完整的演示Demo。技术永远是为具体的生活服务的，这也是我后来每次复盘这个项目时最深的体会。