检澜.桥梁安全训练检测系统

eric.w e99b7698ac 初始化项目		2 hafta önce
images	e99b7698ac 初始化项目	2 hafta önce
README.md	e99b7698ac 初始化项目	2 hafta önce

康桥 - 检澜（DockScope）

** 康桥桥梁检测检澜 DockScope** 是面向桥梁结构缺陷智能分析的一体化工作台：围绕「媒体 / 模型 / 检测任务 / 结果与指标」闭环，提供 Web 端界面与 REST API。本仓库即检澜的前后端源码——前端为 Vue 3 + Element Plus + ECharts（bridge-disease-frontend-main）；后端为 Flask + SQLAlchemy + MySQL（BridgeDiseaseBackend-main），检测分割管线使用 Ultralytics YOLO 等完成推理与结果落盘。

检澜核心功能

账号与权限

注册 / 登录 / 忘记密码：表单提交至后端，成功后下发 JWT（Access + Refresh），前端持久化于 localStorage 并在 Axios 拦截器中自动携带 Authorization: Bearer …。
个人中心：查看与维护当前用户资料、头像等（具体字段以后端 User 模型与路由为准）。
角色模型：ADMIN（管理员）、DEVELOPER（开发人员）、USER（普通用户）。部分菜单与列表接口仅对管理员或开发开放（见下节「角色与界面」）。

数据看板（`/home`）

登录后的默认工作台：侧栏导航、面包屑、数据洞察与社群快捷入口等壳层组件，以及基于 ECharts 的历史统计图表（StatisticsCharts），用于总览业务数据趋势（依赖后端统计数据接口）。

病害检测分割（`/disease-detection`）

选择已上传的模型（.pt）与媒体（图像或视频），发起一次检测分割任务。
后端创建或更新 Detection 记录，加载 YOLO 权重与媒体文件，执行推理后将结果图/掩码等写入配置的 RESULTS_FOLDER，并计算多项病害形态与严重度指标（数量、周长、面积、形状复杂度、纹理粗糙度、裂缝宽度、平均色调等），综合得到严重度分数与等级（轻 / 中 / 重 / 危急等枚举）。
支持任务状态流转（如待处理、进行中、已完成、失败），便于列表筛选与详情展示。

检测分割记录（`/detection-records`）

分页列表：模型名、媒体名、状态、严重度、等级、结果路径、媒体类型、更新时间、所有者等。
条件筛选与详情对话框：查看单次任务的指标明细与耗时（总耗时、帧均耗时等）。
管理员 / 开发人员可查看全量记录；普通用户通常仅能看到本人相关记录（以后端分页接口逻辑为准）。

媒体库（`/media-library`）

上传与管理检澜业务中的巡检图片（如 png/jpg/jpeg）与视频（mp4），写入服务器静态目录并在数据库中登记路径与元数据。
列表预览通过 /file/... 静态访问路径拼接媒体相对路径（需后端可访问对应文件）。

模型库（`/model-library`）

上传与管理 YOLO 权重（.pt），供检测页下拉选用。
侧栏中该菜单仅对 DEVELOPER 角色可见（visible: isDeveloper）；ADMIN 与普通用户不展示该入口（见 SidebarMenu.vue）。

用户管理（`/user-management`）

面向 管理员或开发人员：用户列表、状态与角色相关维护能力（具体能力以后端 user_route 为准）。

系统操作日志（`/operation-logs`）

面向 管理员或开发人员：审计类操作记录（登录、执行检测、失败原因等），与业务上的 Operation 实体对应，便于排障与合规留痕。

开发辅助：列表 Mock

当前端设置 VITE_USE_LIST_MOCK=true 时，检测分割记录与媒体库列表可走本地 src/mocks/detectionAndMediaMockData.js 分页数据，无需后端即可调试表格与布局（预览图仍依赖 /file/... 时可能裂图）。

角色与界面

角色	典型可见菜单（与当前侧栏逻辑一致）
`USER`	数据看板、病害检测分割、检测分割记录、媒体库
`DEVELOPER`	上述 + 模型库 + 用户管理 + 系统操作日志
`ADMIN`	数据看板、病害检测分割、检测分割记录、媒体库 + 用户管理 + 系统操作日志（无模型库入口）

路由定义见 bridge-disease-frontend-main/src/router/index.js；菜单过滤见 src/components/SidebarMenu.vue。

检澜技术架构

总体部署视图

flowchart LR
  subgraph Browser[浏览器]
    SPA[检澜前端 Vue 3 / Element Plus]
  end
  subgraph Host[宿主机或服务器]
    NG[Nginx 托管检澜静态前端]
    API[检澜 API Flask :5000]
  end
  subgraph Data[数据层]
    MySQL[(MySQL 8)]
    FS[本地静态目录\nmedias / models / results / avatars]
  end
  SPA -->|页面与 REST JSON| NG
  SPA -->|开发模式直连 API| API
  NG -.->|生产镜像中浏览器直连| API
  API --> MySQL
  API --> FS

说明：

Docker 生产形态：前端为构建后的静态资源，由容器内 Nginx 提供；浏览器根据构建期注入的 VITE_API_BASE_URL 直接请求后端（常见为宿主机 http://127.0.0.1:5000）。
Vite 开发形态：前端开发服务器与后端分离，通过环境变量将 API 指到本机 Flask。

逻辑分层

层级	前端（`bridge-disease-frontend-main`）	后端（`BridgeDiseaseBackend-main`）
表现层	`views/.vue`、`components/*`	Flask 路由函数（各 `*_route.py`）
应用状态	`stores/*`（用户、侧栏、资源列表等）	JWT 身份、`Operation` 记录、限流状态
领域与数据	Axios `src/utils/request.js`	SQLAlchemy Models（`User`、`Media`、`Model`、`Detection`、`Operation`）
基础设施	Vue Router、Vite、ECharts	`app/config.py` 路径与上传限制、`app/utils/*`（分页、指标、文件等）
推理	—	`detection_route` 中 Ultralytics YOLO、OpenCV / Pillow 等

应用工厂与横切能力见 app/__init__.py：CORS、JWT、数据库初始化、蓝图注册、全局限流、统一错误处理、日志落盘到 logs/。

后端 API 蓝图前缀

URL 前缀	职责概要
`/user`	注册、登录、令牌刷新、用户资料与权限相关接口
`/media`	媒体上传与分页列表
`/model`	模型上传与分页列表
`/detection`	发起检测分割、检测记录分页查询等
`/operation`	操作日志分页（高权限）
`/file`	静态文件访问（头像、媒体、结果图等）

检测任务数据流（简图）

sequenceDiagram
  participant U as 用户浏览器
  participant F as 检澜 API Flask
  participant DB as MySQL
  participant Y as YOLO 推理
  participant S as 静态目录

  U->>F: POST /detection/detection_segmentation（model_id, media_id）
  F->>DB: 读 Model / Media，写/更新 Detection
  F->>S: 读权重与源媒体
  F->>Y: 推理与后处理
  Y-->>F: 掩码/可视化结果
  F->>S: 写 result 文件
  F->>DB: 更新指标、等级、状态、耗时
  F-->>U: JSON（含 operation 记录等）
  U->>F: GET 列表/详情、GET /file/... 预览

目录结构

路径	说明
`bridge-disease-frontend-main/`	检澜 Web 前端（Vite + Vue 3）
`BridgeDiseaseBackend-main/`	检澜 API 与推理服务（Flask、模型与工具、`sql/init_db.sql`）
`docker/`	镜像构建、Nginx 配置、后端入口与 DB bootstrap
`docker-compose.yml`	MySQL、后端、前端编排（镜像由根脚本构建，见下）
`images/`	界面截图（README 下图集引用，文件名多为导出时的 UUID）
`.env`	Compose 与构建变量示例
`package.json`	根目录：`npm run up` / `npm run down`

技术栈概览

前端：Vue 3、Vue Router、Axios、Element Plus、ECharts、Vite 6
后端：Flask、Flask-JWT-Extended、Flask-CORS、SQLAlchemy、PyMySQL
推理与影像：OpenCV、Ultralytics、PyTorch、Pillow、scikit-image、moviepy 等（完整列表见 BridgeDiseaseBackend-main/requirements.txt）
数据库：MySQL 8

检澜界面截图

以下为 images/ 目录中的 检澜（DockScope） 实际界面截图（按文件名排序）。若需与具体页面一一对应，可将文件重命名为可读名称并同步修改下列路径。

启动检澜：Docker 一键堆栈（建议）

在项目根目录执行（需已安装 Docker 与 Node.js，用于执行根目录脚本）：

npm install
npm run up

此流程会：

以 DOCKER_BUILDKIT=0 构建镜像（降低在含中文路径的 Windows 环境下，Compose Bake / gRPC 相关错误的概率）。
启动 MySQL、后端（端口 5000）、前端 Nginx（端口 8080）。
后端首次启动且数据库为空时，会执行 db.create_all() 并以 BridgeDiseaseBackend-main/sql/init_db.sql 种子数据初始化。

启动完成后：

检澜 Web：http://localhost:8080
检澜 API（Flask）：http://127.0.0.1:5000

停止并移除容器：

npm run down

根目录环境变量（`.env`）

可复制或按项目内已有 .env 调整，常见项如下：

变量	说明
`MYSQL_ROOT_PASSWORD`	MySQL root 密码
`MYSQL_DATABASE`	数据库名称（默认 `bridge_disease`）
`MYSQL_HOST_PORT`	主机映射 MySQL 的端口（默认 `3307`，对应容器 `3306`）
`VITE_API_BASE_URL`	构建前端镜像时传入的 API 基地址（浏览器会直接请求此 URL，本机开发通常为 `http://127.0.0.1:5000`）

注意：请勿仅依赖 docker compose build 在中文路径下构建；请优先使用根目录的 npm run up，或参考 docker-compose.yml 顶部注释中的等价命令。

本地开发检澜（不使用 Docker）

1. 数据库与后端

安装 MySQL 8，创建数据库（例如 bridge_disease）。

Python 3.11+ 建议与 Dockerfile 一致。

cd BridgeDiseaseBackend-main
python -m venv .venv
# Windows: .venv\Scripts\activate
pip install -r requirements.txt

设置连接字符串（覆盖默认本地 URI），例如：

set SQLALCHEMY_DATABASE_URI=mysql+pymysql://root:你的密码@127.0.0.1:3306/bridge_disease

启动应用：
```
python run.py
```

默认监听由环境变量 FLASK_RUN_HOST / FLASK_RUN_PORT 控制（见 run.py）。首次若需种子，可在空库时自行导入 sql/init_db.sql，或参考 docker/backend/bootstrap.py 的流程。

2. 前端

cd bridge-disease-frontend-main
npm install

在 bridge-disease-frontend-main 下新增 .env.local（或 .env.development），指向本机后端：

VITE_API_BASE_URL=http://127.0.0.1:5000

启动开发服务器：

npm run serve

浏览器打开终端显示的本机 URL（Vite 默认多为 http://localhost:5173）。API 请求会带上 Authorization: Bearer <access_token>（登录后由前端写入 localStorage）。

3. 列表模拟数据（无后端时调 UI）

在 bridge-disease-frontend-main/.env.local 设置：

VITE_USE_LIST_MOCK=true

则「检测分割记录」与「媒体库」列表会使用 src/mocks/detectionAndMediaMockData.js 的本地分页数据，不调用对应列表 API。预览图仍可能请求 /file/...，若无实体文件则图片可能无法显示。

首次登录与种子账号

数据库由 sql/init_db.sql 初始化后，可使用下列测试账号（登录框填「用户名」或「邮箱」均可；密码见 SQL 内注释；登录成功后状态会变为已启用）：

角色	用户名	邮箱（也可用于登录）	密码
管理员	`admin`	`admin@example.com`	`Admin123456`

若提示「用户 xxx 尚未注册」：说明当前 MySQL 里没有对应种子用户，常见原因包括：① 从未成功执行过 init_db.sql（或 Docker 首次启动时种子失败）；② 数据库里已有旧数据，bootstrap 因「用户表非空」跳过了种子；③ 旧版种子里 role/status 与枚举不一致导致插入失败。处理方式：清空该库后重新导入 BridgeDiseaseBackend-main/sql/init_db.sql，或删除 user 表数据后重启后端让 bootstrap 重新播种（Docker 可删卷后 npm run up）。上线前务必修改全部默认密码与密钥。

实际部署请务必更换密钥与密码，并通过环境变量设置 JWT_SECRET_KEY、SECRET_KEY 与数据库 URI，不要沿用示例默认值。

常用命令整理

场景	命令
Docker 一键启动	根目录：`npm run up`
Docker 停止	根目录：`npm run down`
前端构建	`cd bridge-disease-frontend-main && npm run build`
前端预览构建结果	`cd bridge-disease-frontend-main && npm run preview`
后端开发	`cd BridgeDiseaseBackend-main && python run.py`

疑难排解

Docker 在中文路径构建失败：使用根目录 npm run up（已关闭 BuildKit 并分步 docker build），或将项目复制到纯 ASCII 路径再构建。
前端能开、列表无数据：确认 VITE_API_BASE_URL 与后端实际地址一致，且后端已启动；或暂时开启 VITE_USE_LIST_MOCK=true 验证界面。
推理很慢或内存不足：后端依赖 PyTorch / Ultralytics，请在具备足够 RAM / 可选 GPU 的环境执行，并参考官方文档调整批次与模型。
README 中 Mermaid 图不渲染：请使用支持 Mermaid 的 Markdown 预览（如 VS Code / Cursor 插件、GitHub 网页）查看；不影响项目运行。

授权与声明

各子目录可能包含第三方依赖，版权归原作者所有。若检澜或本仓库需对外发布，请补充适当的开源授权文件与数据使用声明。

README.md