猫咪如厕检测与分类识别系统系列【十四】 项目结构重新整理-即将开源完整算法

猫咪如厕检测与分类识别系统系列 项目结构重新整理-即将开源完整算法【十三】

前情提要

---

家里养了三只猫咪，其中一只布偶猫经常出入厕所。但因为平时忙于学业，没法时刻关注牠的行为。我知道猫咪的如厕频率和时长与健康状况密切相关，频繁如厕可能是泌尿问题，停留过久也可能是便秘或不适。为了更科学地了解牠的如厕习惯，我计划搭建一个基于视频监控和AI识别的系统，自动识别猫咪进出厕所的行为，记录如厕时间和停留时长，并区分不同猫咪。这样即使我不在家，也能掌握猫咪的健康状态，更安心地照顾它们。

🎓 各位的关注与点赞是我持续分享的最大动力，衷心感谢大家的支持！

📢 欢迎正在攻读硕博学位的同学，或是对人工智能充满热情的朋友们，关注我的个人公众号。在这里，我将持续更新博士期间阅读的前沿论文解读、项目实战经验分享，以及我对AI技术趋势的思考与探讨。

✨ 无论你是科研工作者、工程开发者，还是AI初学者，都能在这里找到干货与灵感。让我们一起交流、成长、探索人工智能的无限可能！

已完成工作：

✅猫咪如厕检测与分类识别系统系列【一】 功能需求分析及猫咪分类特征提取

✅猫咪如厕检测与分类识别系统系列【二】多图上传及猫咪分类特征提取更新

✅猫咪如厕检测与分类识别系统系列【三】 融合yolov11目标检测

✅猫咪如厕检测与分类识别系统系列【四】融合检测日志输出及前端展示界面制作

✅猫咪如厕检测与分类识别系统系列【五】信息存储数据库改进+添加猫咪页面制作+猫咪躯体匹配算法架构更新

✅猫咪如厕检测与分类识别系统系列【六】分类模型训练+混合检测分类+未知目标自动更新

✅猫咪如厕检测与分类识别系统系列【七】 当前阶段总结报告

✅猫咪如厕检测与分类识别系统系列【八】 检测推理事件整合+视频推流架构分析

✅猫咪如厕检测与分类识别系统系列【九】 视频检测区域在线绘制+支持摄像头+网络摄像头+整体构建【上】

✅猫咪如厕检测与分类识别系统系列【九】 视频检测区域在线绘制+支持摄像头+网络摄像头+整体构建【下】

✅猫咪如厕检测与分类识别系统系列【十】 视频检测区域动态监测及实时更新

✅猫咪如厕检测与分类识别系统系列【十一】区域进入事件相应逻辑鲁棒性更新

✅猫咪如厕检测与分类识别系统系列【十二】猫咪进出事件逻辑及日志优化【上】

✅猫咪如厕检测与分类识别系统系列【十三】猫咪进出事件逻辑及日志优化【下】

本小节继续更新猫咪进出事件逻辑及日志优化

---

本次目标：整理项目结构、优化检测任务管理流程、修复首页记录图片访问问题，并清理缺失图片对应的历史记录。

一、更新概览

本次更新主要围绕"项目可维护性"和"检测任务可管理性"展开。项目原先存在入口分散、配置路径硬编码、任务运行状态不透明、首页历史记录图片失效等问题。更新后，系统拆分出更清晰的算法服务入口，完善任务启动、停止、重启、删除、状态同步等流程，同时对首页图片记录做了兜底和清理。

二、核心更新内容

模块	更新内容	结果
项目结构	补充 README、requirements、环境变量模板和忽略文件	项目启动和交接更清晰
算法服务	新增独立 algorithm_server.py，保留 back_up.py 兼容入口	算法接口更明确
配置管理	将数据库、模型、图片、ffmpeg 等路径改为配置驱动	降低本地路径耦合
数据库	新增数据库结构初始化工具，补齐任务类型字段和交通记录表	启动时可自动补齐必要表结构
检测任务	优化任务创建、编辑、启动、停止、重启、删除和状态同步	管理页面能看到更真实的运行状态
图片记录	修复 /records/... 图片访问路径，增加缺图占位响应	首页不再出现破图
历史数据	备份后清理缺失图片对应的历史记录	当前首页记录数据更干净
外部依赖	Kafka、MinIO、ffmpeg 改为按配置启用或自动探测	缺少外部服务时不会阻塞基础页面

三、检测任务管理优化

本次重点优化了检测任务管理部分，主要包括：

1. 算法服务新增健康检查接口 /health。
2. 新增任务总状态接口 /tasks/status。
3. 新增单任务状态接口 /task/status/<task_id>。
4. base/engine.py 增加运行状态、最近错误和状态读取能力。
5. Web 任务列表会主动同步算法服务中的运行状态。
6. 任务列表新增任务类型展示，支持如厕、烟雾、无人机、交通等不同检测类型。
7. 启动、停止、重启、删除任务时返回更明确的错误信息。
8. 任务编辑页支持在线更新运行配置。
9. 任务列表增加算法服务连接状态提示，方便判断是算法未启动还是任务本身异常。

优化后的整体流程如下：
Web 任务管理页面
创建或编辑检测任务
写入 detection_tasks 数据表
调用算法服务接口
算法引擎启动检测线程
返回任务运行状态
停止、重启或删除任务

四、首页图片访问修复

首页图片无法访问的原因是数据库里的部分历史记录引用了已经不存在的图片文件，例如数据库中有 guorong_enter_1744788774.jpg，但项目目录 web/static/records 下没有对应文件。

本次处理分为两步：

1. 代码层修复
   /records/<filename> 现在会统一规范图片路径，只取安全的文件名部分，避免历史记录里带有 static/records/ 等前缀时访问失败。

2. 缺图兜底

   如果图片文件确实不存在，接口会返回 SVG 占位图，页面上显示"图片缺失"，不再出现浏览器破图。

同时，首页模板会根据图片是否存在决定展示真实图片还是缺图提示。

五、缺失记录清理

检查后发现当前数据库 toilet_logs 中共有 796 条记录，但这些记录引用的进出图片都不完整，完整记录数为 0。

处理方式：

项目	结果
清理前记录数	796
备份文件	web/db/toilet_log.before_remove_missing_records.db
备份记录数	796
当前记录数	0
是否删除图片文件	否

说明：本次只清理了数据库中的缺失记录，没有删除 web/static/records 目录下的任何图片文件。也就是说，图片文件本身没有被清空，清掉的是无法完整展示的历史数据库记录。

六、已验证内容

验证项	结果
Web 服务启动	已可在 http://127.0.0.1:5088 访问
算法服务入口	已整理为 http://127.0.0.1:5678
首页数据接口	/data_ananylize 可正常返回
存在图片访问	/records/static/records/guoqiang_enter_1744285845.jpg 可返回图片
缺失图片访问	/records/guorong_enter_1744788774.jpg 返回缺图占位图
数据库备份	已生成 web/db/toilet_log.before_remove_missing_records.db
当前如厕记录	toilet_logs 当前为 0 条

七、当前遗留问题

当前页面和任务管理流程已经可以运行，但实际 YOLO 推理任务仍可能受到本机 Python 环境影响。

已观察到的风险：

• 当前环境中的 numpy 2.4.4 与部分 matplotlib、ultralytics 二进制扩展存在兼容问题。
• 管理页面可以打开，是因为检测器改成了按任务类型懒加载。
• 如果直接启动真实 YOLO 检测任务，仍建议先统一 Python 依赖版本。

建议后续处理：

1. 固定 Python 版本和依赖版本。
2. 建议使用独立虚拟环境运行项目。
3. 将模型文件、数据库文件、截图目录和推流工具路径继续统一到 .env。
4. 增加任务运行日志页面或错误详情弹窗。
5. 给历史记录增加"图片存在性校验"和"一键清理缺失记录"操作。

八、涉及的关键文件

文件	说明
algorithm_server.py	新算法服务入口
back_up.py	兼容旧入口，转发到算法服务
base/engine.py	检测引擎状态管理
web/app1.py	Web 路由、任务管理、图片访问、数据库初始化
web/templates/task/task_list.html	任务列表与运行状态展示
web/templates/task/task_new_draw.html	新建任务页面
web/templates/task/task_edit.html	编辑任务页面
web/templates/index.html	首页历史记录展示
web/templates/index_daping.html	大屏首页历史记录展示
utils/db_init.py	数据库表结构自动初始化
utils/dispatcher.py	检测任务懒加载分发
utils/kafka_notifier.py	Kafka 可选依赖处理
utils/minio_utils.py	MinIO 可选配置处理

九、本次结论

这次更新后，项目已经从"能跑的原型"进一步整理成"可维护、可启动、可排查"的版本。任务管理流程更完整，图片缺失问题不会再影响首页展示，历史缺失记录也已备份后清理。后续如果要进入稳定运行阶段，重点需要处理 Python 依赖环境和真实检测任务的持续运行验证。