宠物医疗管理系统 - 项目总结
一、项目背景
随着宠物行业的快速发展，宠物主人对宠物健康管理的需求日益增长。传统的宠物医疗记录方式存在信息分散、查询困难、疫苗接种提醒不及时等问题。为此，我开发了 宠物医疗管理系统 ，旨在为宠物主人提供一站式的宠物健康管理平台，同时为宠物医院/诊所提供高效的后台管理工具。
二、技术选型
前端技术栈
| 技术 | 说明 |
|---|---|
| HTML5 + CSS3 | 页面结构与响应式样式 |
| JavaScript | 前端交互逻辑 |
| Axios | 异步 HTTP 请求 |
后端技术栈
| 技术 | 说明 |
|---|---|
| Python 3.12 | 开发语言 |
| FastAPI | 高性能异步 Web 框架 |
| SQLAlchemy ORM | 数据库操作 |
| Pydantic | 数据验证与序列化 |
| JWT (JSON Web Token) | 无状态身份认证 |
| MySQL | 关系型数据库 |
AI 集成
| 技术 | 说明 |
|---|---|
| Dify 工作流 | AI 能力集成 |
| httpx | 异步 HTTP 客户端 |
三、系统架构
技术架构
架构特点
- 前后端分离 ：前端与后端通过 RESTful API 通信，可独立部署和扩展
- 关注点分离 ：各模块职责清晰，便于维护和团队协作
- 异步处理 ：FastAPI + httpx 实现全链路异步，提升并发性能
四、核心功能模块
4.1 用户端功能
| 模块 | 功能描述 |
|---|---|
| 宠物档案管理 | 添加/编辑宠物信息，支持多品种选择，记录宠物生日、性别、毛色等 |
| 商品商城 | 浏览宠物商品，支持分类筛选和关键词搜索（模糊匹配算法） |
| 购物车与结算 | 添加商品到购物车，支持余额支付和先用后付两种支付方式 |
| 订单管理 | 查看订单状态，确认收货，查看订单历史 |
| AI 智能助手 | 接入 Dify 实现智能问诊、宠物取名、健康咨询 |
| 健康记录 | 体重记录追踪、疫苗计划及记录、医疗记录 |
4.2 管理端功能
| 模块 | 功能描述 |
|---|---|
| 数据仪表盘 | 用户、商品、订单、宠物数据统计，近 7 日订单趋势可视化图表 |
| 用户管理 | 查看用户列表，余额充值，会员等级管理 |
| 商品管理 | 商品 CRUD 操作，图片上传，上下架管理 |
| 订单管理 | 查看所有订单，修改订单状态（待付款→已发货→已完成） |
| 宠物管理 | 代用户添加宠物，宠物分类管理 |
| 疫苗管理 | AI 智能计算疫苗接种计划，疫苗记录管理 |
| 管理员管理 | 查看管理员列表，修改个人信息（用户名/密码） |
五、数据库设计
系统采用 MySQL 数据库，主要数据表如下：
| 表名 | 说明 | 核心字段 |
|---|---|---|
| users | 用户表 | id, username, phone, balance, member_level |
| admins | 管理员表 | id, username, password_hash, permissions |
| products | 商品表 | id, name, brand, category, price, stock, sales |
| orders | 订单表 | id, user_id, total, status, pay_method |
| order_items | 订单明细 | id, order_id, product_id, name, price, qty |
| pets | 宠物档案 | id, user_id, category_id, name, breed, birthday |
| pet_categories | 宠物分类 | id, name, description |
| vaccines | 疫苗记录 | id, pet_id, vaccine_name, inject_date, next_date |
| medical_records | 医疗记录 | id, pet_id, diagnosis, treatment, visit_date |
| weight_records | 体重记录 | id, pet_id, weight, date |
| ai_chats | AI 对话 | id, user_id, title, created_at |
| ai_messages | AI 消息 | id, chat_id, role, content, created_at |
| recharge_records | 充值记录 | id, user_id, amount, status |
六、项目亮点
6.1 AI 智能疫苗接种计划
接入 Dify 工作流平台，根据疫苗类型和首次接种日期，自动计算后续接种时间：
- 猫三联/四联：间隔 21 天
- 犬联疫苗：间隔 21 天
- 狂犬疫苗：间隔 365 天
6.2 商品搜索优化
实现三级搜索策略：
- 精确子串匹配 ：搜索词直接出现在商品名中
- 分词匹配 ：搜索词的每个字都出现在商品名中
- 编辑距离相似度 ：阈值 0.5，处理拼写错误和简称
6.3 先用后付支付流程
完整的先用后付支付链路：
- 用户选择先用后付下单
- 管理员发货
- 用户确认收货
- 系统自动扣费
6.4 数据可视化
管理端仪表盘展示近 7 日订单趋势，使用纯 CSS 柱状图，无需第三方图表库。
七、项目结构
前端文件结构
后端文件结构
八、开发过程中遇到的问题与解决方案
问题 1：时区导致订单日期错误
现象 ：种子数据使用 UTC 时间，查询使用北京时间，导致 5 月 31 日的订单显示为 6 月 1 日。
解决 ：
- 修改种子数据生成逻辑，统一使用北京时间
- 简化查询逻辑，只按北京时间查询
问题 2：AI 疫苗接种计划计算错误
现象 ：狂犬疫苗提示词中写"1 年"，但代码只处理"天"和"月"，导致日期不变。
解决 ：修改 Dify 提示词，将"年"统一改为"365 天"。
问题 3：管理员退出登录报 403 错误
现象 ：管理员退出时调用用户专属的清除聊天记录接口。
解决 ：退出时判断角色，只有用户角色才调用清除接口。
九、项目总结
宠物医疗管理系统是一个功能完整的宠物健康管理平台，采用前后端分离架构，集成 AI 智能服务。项目实现了用户端和管理端的完整业务流程，包括宠物档案管理、商品商城、订单管理、疫苗接种、AI 问诊等核心功能。
技术收获
- 掌握了 FastAPI 框架的使用，理解了异步编程的优势
- 学习了 SQLAlchemy ORM 的使用，理解了数据模型设计
- 实践了 JWT 认证机制，理解了无状态认证的原理
- 集成了 Dify AI 平台，体验了 AI 工作流的强大能力
- 实现了前后端分离架构，理解了 RESTful API 设计规范
未来展望
- 前端可升级为 Vue框架，提升开发效率
- 后端可引入 Redis 缓存，提升查询性能
- 可增加微信小程序端，方便用户移动端使用
- 可接入短信/邮件通知，实现疫苗接种提醒
