TrainEye源码解读-00. 总览与阅读方法（必读）

本系列是 TrainEye 项目的逐行源码讲解从浏览器前端一路讲到数据库覆盖每个功能模块的完整请求流程。阅读前提你会一点 Python 和 JavaScript 基础不会也没关系本系列每段代码都逐行解释。配套阅读先看《LEARNING_GUIDE.md》20 章入门指南把系统跑起来再来读本系列。一、本系列文档目录编号文档覆盖内容状态00本文件总览与阅读方法前置知识、阅读方法、请求流程图✅ 已完成01登录认证 · 前端篇login.html、auth-utils.js、main.js认证函数✅ 已完成02登录认证 · 后端篇run.py、main.py、api.py、deps.py、auth.py、crud/user.py、models/user.py、schemas/user.py、session.py、config.py、audit_middleware.py✅ 已完成03前端骨架 · main.js 与 index.htmlmain.js全部 800 行、index.html结构✅ 已完成04数据集管理全流程dataset-manager.js→datasets.py→dataset_service.py→crud_dataset.py✅ 已完成05模型管理全流程model-manager.js→models.py→model_service.py✅ 已完成06训练管理全流程training-manager.js→training.py→training_service.py→process_monitor.py1.1.0 版迭代训练 / 指标可视化 / 指标对比 / PyCharm 调试修复✅ 已完成1.1.0 版07模型检测全流程detection-manager.js→detection.py→detection_service.py→model_cache.py✅ 已完成初稿08在线标注全流程annotation*.js→annotation.py→annotation_service.py✅ 已完成初稿09图像处理全流程opencv-tools.js→opencv.py→opencv_service.py待写10视频处理全流程video-processor.js→video.py→stream_service.py待写11监控/用户/设置全流程monitoring*.js→monitoring.py→monitoring_service.py、user-manager.js、settings待写12进阶专题SSE 流式检测、算法注册表、目标追踪、计数、剪枝/导出/分析待写每一篇都遵循同一个阅读框架页面按钮 → JS 事件 → fetch 请求 → 路由 → 服务层 → 数据层 → 数据库 → 返回 JSON → 页面渲染。二、前置知识速查看不懂就回来翻这里1. HTTP 是什么HTTP 是浏览器和服务器之间的快递协议。一次请求包含方法动作GET查询、POST新增/提交、PUT整体更新、PATCH部分更新、DELETE删除URL地址如/api/auth/tokenHeaders头附加信息如Authorization: Bearer xxx携带令牌、Content-Type: application/json声明数据格式Body身体POST/PUT 时携带的数据JSON 或表单2. 状态码服务器回复的结果编号状态码含义常见场景200成功查询/更新成功201创建成功新建用户成功400请求参数错误用户名已存在401未认证没登录/令牌失效令牌过期403已登录但没权限普通用户访问管理员接口404资源不存在查一个不存在的用户422数据校验失败密码长度不够500服务器内部错误代码出 bug3. JSON前后端交流的语言{username:admin,role:admin,id:1}Python 侧user.dict()把对象转成字典FastAPI 自动转成 JSONJS 侧response.json()把 JSON 转成 JS 对象4. 浏览器两大仓库前端存数据的地方名称特点本项目用途localStorage永久保存关浏览器还在存access_token登录令牌、currentPage当前页面Cookie每次请求自动发给服务器备用认证方式access_tokencookie5. fetch 与 Promise前端调接口的方式fetch(/api/xxx,{method:POST,headers:{...},body:...}).then(response{// 服务器有响应了成功失败都进这里if(!response.ok)thrownewError(失败);returnresponse.json();// 解析 JSON}).then(data{// 拿到数据渲染页面console.log(data);}).catch(error{// 出错网络错误/上面 throw 的console.error(error);});fetch返回一个Promise承诺对象“我现在去请求了结果稍后给你”.then(回调函数)结果到了之后执行.catch(回调函数)出错了执行记住.then里拿到 response 不代表成功要检查response.ok200~2996. Python 装饰器开头的那一行router.get(/token)deflogin():...作用给下面的函数登记注册——告诉 FastAPI这个函数负责处理 GET /token 请求就像给饭店服务员挂牌“这道菜由 3 号厨师做”7. 依赖注入 DependsFastAPI 的特色db:SessionDepends(get_db)current_user:UserDepends(get_current_active_user)含义“我需要的工具请框架自动帮我准备好并传进来”Depends(get_db)→ 自动打开一个数据库会话请求结束后自动关闭Depends(get_current_active_user)→ 自动检查登录令牌解析出当前用户没登录直接返回 401根本不会执行下面的函数体——这就是全局认证的实现方式8. 类型标注变量: 类型这种写法defget_user(db:Session,user_id:int)-Optional[User]:db: Session 说清楚参数类型帮助 IDE 提示错误- Optional[User] 返回值可能是 User 对象也可能是 None运行时不强制检查纯粹是说明书但 FastAPI 会用它做数据校验比如user_id: int传入 “abc” 会返回 422三、全项目请求流程图每篇都会套用这个框架┌─ 前端浏览器─────────────────────────────────────────────┐ │ 1. index.html 的按钮/表单 → 触发 JS 事件 │ │ 2. JS 模块如 dataset-manager.js调用 authenticatedFetch() │ │ 3. authenticatedFetch 自动在请求头加 Authorization: Bearer xxx│ │ 4. fetch() 发出 HTTP 请求 → /api/... │ ├─ 中间件每请求必经的安检门────────────────────────────────┤ │ 5. AuditMiddleware写操作(POST/PUT/DELETE/PATCH)记录审计日志 │ ├─ 后端FastAPI────────────────────────────────────────────┤ │ 6. api.py 路由注册 → 找到对应 endpoints/xxx.py 的路由函数 │ │ 7. Depends 认证依赖解析 JWT → 查用户 → 查权限不过则 401/403│ │ 8. 路由函数收到已校验的参数 │ │ 9. 调用 services/xxx_service.py业务逻辑 │ │ 10. 调用 crud/xxx.py拼装数据库操作 │ │ 11. SQLAlchemy ORM → PostgreSQL 执行 SQL │ │ 12. 数据层层返回 → FastAPI 序列化成 JSON → 响应给浏览器 │ └────────────────────────────────────────────────────────────┘ 13. 前端 .then(data ...) 收到 JSON → 动态生成 HTML → 页面更新四、阅读本系列的正确姿势先跑起来确保系统在运行python run.py边读边在浏览器/数据库里验证对照着读把文档里引用的文件同时打开左代码右讲解读一行想一行先自己猜这行干什么再看讲解动手验证每篇末尾有验证任务F12 看请求、pgAdmin 查表、改代码观察变化本系列约定代码块中行号与源码文件真实行号一致▶ 讲解表示对该行/该段的解释⚠️ 表示容易踩的坑 表示延伸思考