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

# 检澜（DockScope）

**检澜 DockScope** 是面向**桥梁安全隐患智能检测**的一体化工作台：围绕「媒体 / 模型 / **模型训练** / 检测任务 / 结果与指标 / 台账与报告」闭环，提供 Web 端界面与 REST API。本仓库为检澜**前后端源码**——前端 **Vue 3 + Element Plus + ECharts**（`bridge-disease-frontend-main`）；后端 **Flask + SQLAlchemy + MySQL**（`BridgeDiseaseBackend-main`），检测推理基于 **Ultralytics YOLO**，对影像中的结构隐患区域进行识别、标注与量化评估。

![检澜 界面](images/0数据看板.png)

---

## 检澜核心功能

### 账号与权限

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

### 数据看板（`/home`）

- 登录后的默认工作台：侧栏导航、面包屑、**数据洞察**与**社群快捷入口**等壳层组件，以及基于 ECharts 的**历史统计图表**（`StatisticsCharts`）。

### 模型训练（`/model-training`）

- **`ADMIN` / `DEVELOPER` 可见**（侧栏紧跟在「数据看板」之后）：上传 Ultralytics **YOLO 格式**数据集（ZIP，内含 `data.yaml`），选择 YOLOv8n/s/m-seg 基线权重启动**分割**训练。
- 训练在 Flask 进程内以后台线程执行（**无需单独起训练服务**）；任务列表展示排队 / 训练中 / 已完成 / 失败，支持刷新与自动恢复排队任务。
- 完成后可将 `best.pt` **自动注册到模型库**（含 mAP 等指标）；任务元数据持久化于 `data/training_meta/jobs.json`。
- 数据与产物目录：`BridgeDiseaseBackend-main/data/datasets`、`data/training_runs`、`app/static/models`。
- 文档与模板：[`docs/TRAINING_DATASET.md`](BridgeDiseaseBackend-main/docs/TRAINING_DATASET.md)、[`training_templates/data.yaml.example`](BridgeDiseaseBackend-main/training_templates/data.yaml.example)。
- 试跑演示 ZIP：`cd BridgeDiseaseBackend-main && python scripts/create_demo_dataset.py` → `training_templates/bridge_hazard_demo.zip`（CPU 建议 `yolov8n-seg`、`epochs=5`、`batch=2`）。

### 桥梁安全隐患检测（`/disease-detection`）

- 三步向导：选择 **检测模型**（`.pt`）→ 选择 **媒体**（图像或视频）→ 发起 **安全隐患检测**。
- 后端调用 YOLO 推理，生成**标注结果图**并计算隐患指标（数量、周长、面积、形状复杂度、纹理粗糙度、裂缝宽度、平均色调等），综合得到**严重度得分与隐患等级**（轻 / 中 / 重 / 严重）。
- 支持任务状态（待处理、检测中、已完成、失败）与实时进度展示。

### 安全隐患检测记录（`/detection-records`）

- 分页列表：模型名、媒体名、任务状态、严重度、隐患等级、检测标注结果、检测时间、所属用户等。
- 支持筛选、导出 Excel、详情对话框查看指标明细与耗时。
- 管理员 / 开发人员可查看**全量**记录；普通用户通常仅能看到**本人**记录。

### 批量安全隐患检测（`/batch-detection`）

- 一次选择模型与多条媒体，以队列方式模拟批量检测任务（开发演示）。
- 支持自动 / 手动推进进度，完成后可将结果写入**安全隐患台账**。
- 数据持久化于浏览器 `localStorage`（`dockscope_professional_v1`），**非后端 API**。

### 安全隐患台账（`/defect-ledger`）

- 汇聚 AI 检测与批量任务发现的隐患，支持复核、确认、处置与销项。
- 可从检测记录导入、按状态 / 等级筛选。
- 数据同样为前端 `localStorage` 演示，便于产品演示与流程验证。

### 报告中心（`/report-center`）

- 巡检周报、专项检测报告、监测预警汇总等模板，生成记录并导出 **Excel**。
- 报告数据基于上述前端专业模块 store 汇总，**非后端持久化**。

### 媒体库（`/media-library`）

- 上传与管理巡检**图片**（png/jpg/jpeg）与**视频**（mp4），写入服务器静态目录并在数据库登记元数据。
- 列表预览通过 **`/file/...`** 访问（需后端可访问对应文件）。
- 可使用 `scripts/seed_medias.py` 导入真实桥梁照片种子（见「数据种子脚本」）。

### 模型库（`/model-library`）

- 上传与管理 **YOLO 权重**（`.pt`），供检测页选用。
- 侧栏**仅对 `DEVELOPER` 可见**；`ADMIN` 与普通用户不展示该入口。

### 物联网监测（前端演示）

以下四个模块共用 `localStorage`（`dockscope_iot_monitoring_v1`），用于展示监测业务界面，**未接后端**：

| 路由 | 功能 |
|------|------|
| `/sensor-management` | 传感器登记、阈值与在线状态 |
| `/data-collection` | 采集任务与原始数据浏览 |
| `/data-processing` | 清洗、聚合与特征处理 |
| `/alert-management` | 预警规则、分级与处置 |

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

- 面向 **管理员或开发人员**：用户列表、状态与角色维护。

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

- 面向 **管理员或开发人员**：登录、检测执行、失败原因等审计记录（`Operation` 实体）。

### 开发辅助：列表 Mock

- 当前端设置 `VITE_USE_LIST_MOCK=true` 时，**安全隐患检测记录**与**媒体库**列表可走本地 `src/mocks/detectionAndMediaMockData.js`，无需后端即可调试表格布局。

---

## 角色与界面

### 侧栏菜单顺序（`SidebarMenu.vue`）

1. 数据看板  
2. **模型训练**（仅 `ADMIN` / `DEVELOPER`）  
3. 桥梁安全隐患检测  
4. 安全隐患检测记录  
5. 批量安全隐患检测  
6. 安全隐患台账  
7. 报告中心  
8. 媒体库  
9. 传感器管理 → 数据采集 → 数据处理 → 预警管理（物联网演示）  
10. 模型库（仅 `DEVELOPER`）  
11. 用户管理、系统操作日志（`ADMIN` / `DEVELOPER`）

### 角色可见入口

| 角色 | 典型可见菜单 |
|------|----------------|
| `USER` | 数据看板、桥梁安全隐患检测、安全隐患检测记录、批量检测、安全隐患台账、报告中心、媒体库、物联网监测四模块 |
| `DEVELOPER` | 上述 + **模型训练**（第 2 项）+ **模型库** + 用户管理 + 系统操作日志 |
| `ADMIN` | 与 `USER` 相同业务菜单 + **模型训练**（第 2 项）+ 用户管理 + 系统操作日志（**无模型库**） |

路由见 `bridge-disease-frontend-main/src/router/index.js`；菜单见 `src/components/SidebarMenu.vue`。产品对外文案常量见 `src/shellConstants.js`（副标题：**桥梁安全隐患智能检测工作台**）。

---

## 检澜技术架构

### 总体部署视图

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

### 逻辑分层

| 层级 | 前端 | 后端 |
|------|------|------|
| 表现层 | `views/*.vue`、`components/**` | Flask 路由（各 `*_route.py`） |
| 应用状态 | `stores/*`（用户、资源列表、IoT、专业模块等） | JWT、`Operation`、限流 |
| 领域与数据 | Axios `src/utils/request.js` | SQLAlchemy Models（`User`、`Media`、`Model`、`Detection`、`Operation`） |
| 推理 | — | `detection_route` 中 **Ultralytics YOLO**、OpenCV / Pillow 等 |

### 后端 API 蓝图前缀

| URL 前缀 | 职责概要 |
|----------|-----------|
| `/user` | 注册、登录、令牌刷新、用户资料 |
| `/media` | 媒体上传与分页列表 |
| `/model` | 模型上传与分页列表 |
| `/detection` | 发起安全隐患检测、检测记录分页查询等 |
| `/training` | 数据集上传、YOLOv8 训练任务、进度/日志、恢复排队任务（`ADMIN` / `DEVELOPER`） |
| `/operation` | 操作日志分页（高权限） |
| `/file` | 静态文件访问（头像、媒体、结果图等） |

### 检测任务数据流

```mermaid
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 与推理服务 |
| `BridgeDiseaseBackend-main/scripts/` | 媒体/检测/训练数据集种子、编码修复等运维脚本 |
| `BridgeDiseaseBackend-main/docs/TRAINING_DATASET.md` | 模型训练数据集格式说明 |
| `BridgeDiseaseBackend-main/training_templates/` | `data.yaml` 模板与演示 ZIP |
| `scripts/start-backend.ps1` | 释放 5000 端口并启动检澜后端（Windows） |
| `BridgeDiseaseBackend-main/seed_assets/` | 真实照片源文件（媒体种子） |
| `BridgeDiseaseBackend-main/sql/` | `init_db.sql`（最小种子）、`seed_snapshot.sql`（完整演示库） |
| `BridgeDiseaseBackend-main/seed_assets/snapshot/` | 可提交的演示静态资源与训练元数据快照 |
| `docker/` | 镜像构建、Nginx、后端 bootstrap |
| `docker-compose.yml` | MySQL、后端、前端编排 |
| `images/` | README 界面截图 |
| `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（建议 `utf8mb4`）

---

## 检澜界面截图

![检澜 界面 1](images/1.0桥梁安全隐患训练.png)

![检澜 界面 1](images/1桥梁安全隐患检测.png)

![检澜 界面 2](images/2.1大模型检测中.png)

![检澜 界面 2](images/2.2检测记录.png)

![检澜 界面 2](images/2.3批量检测.png)

![检澜 界面 2](images/2.4检测台账.png)

![检澜 界面 3](images/3报告中心.png)

![检澜 界面 4](images/4媒体库.png)

![检澜 界面 5](images/5传感器管理.png)

![检澜 界面 6](images/6数据采集.png)

![检澜 界面 7](images/7数据处理.png)

![检澜 界面 8](images/8预警管理.png)

![检澜 界面 9](images/9用户管理.png)

![检澜 界面 10](images/10系统操作日志.png)

---

## 启动检澜

### 方式 A：本地开发（推荐，启动快）

完整 Docker 堆栈需构建 PyTorch/CUDA 镜像，在 Windows 上可能极慢。日常开发建议 **仅 Docker 跑 MySQL**，本机启动前后端。

**1. MySQL（Docker）**

```powershell
# 项目根目录
docker compose -p bridge-disease up -d db
```

- 端口：**3307** → 容器 3306
- 密码：`bridgedisease_root`
- 库名：`bridge_disease`

**2. 后端**

```powershell
cd BridgeDiseaseBackend-main
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

$env:SQLALCHEMY_DATABASE_URI="mysql+pymysql://root:bridgedisease_root@127.0.0.1:3307/bridge_disease?charset=utf8mb4"
python run.py
```

- API：<http://127.0.0.1:5000>
- Windows 下若登录报 `ZoneInfoNotFoundError: Asia/Shanghai`，需已安装 `tzdata`（已写入 `requirements.txt`）。

**3. 前端**

```powershell
cd bridge-disease-frontend-main
npm install
```

创建 `bridge-disease-frontend-main/.env.local`：

```env
VITE_API_BASE_URL=http://127.0.0.1:5000
```

```powershell
npm run serve
```

- Web：<http://localhost:5173>

**4. 初始化演示数据（首次或空库）**

**方式 A — 一键快照（推荐，与维护者演示效果一致）**

仓库已包含导出的 `sql/seed_snapshot.sql` 与 `seed_assets/snapshot/`（媒体、模型、检测结果、训练任务元数据）：

```powershell
cd BridgeDiseaseBackend-main
$env:SQLALCHEMY_DATABASE_URI="mysql+pymysql://root:bridgedisease_root@127.0.0.1:3307/bridge_disease?charset=utf8mb4"
python scripts/import_db_snapshot.py
python run.py
```

维护者更新快照：`python scripts/export_db_snapshot.py` 后提交 `sql/seed_snapshot.sql` 与 `seed_assets/snapshot/`。说明见 [`seed_assets/snapshot/README.md`](BridgeDiseaseBackend-main/seed_assets/snapshot/README.md)。

**方式 B — 分步种子（体积极小，需联网下载照片）**

```powershell
cd BridgeDiseaseBackend-main
$env:SQLALCHEMY_DATABASE_URI="mysql+pymysql://root:bridgedisease_root@127.0.0.1:3307/bridge_disease?charset=utf8mb4"

python run.py   # 首次会 db.create_all()，空库可再导入 sql/init_db.sql

python scripts/download_real_medias.py   # 可选
python scripts/seed_medias.py
python scripts/seed_models.py
python scripts/seed_detections.py
```

若中文姓名、隐患类别显示为 `??`，说明历史写入时连接未带 UTF-8，可执行修复脚本：

```powershell
python scripts/fix_user_names.py
python scripts/fix_model_texts.py
```

> **注意**：连接字符串务必包含 `?charset=utf8mb4`；后端 `config.py` 会在未指定时自动补全。

---

### 方式 B：Docker 一键堆栈

在**项目根目录**（需 Docker + Node.js）：

```bash
npm install
npm run up
```

此流程会：

1. 以 `DOCKER_BUILDKIT=0` 构建镜像（降低中文路径下 Compose Bake 错误概率）。
2. 启动 **MySQL**、**后端**（`:5000`）、**前端 Nginx**（`:8080`）。
3. 数据库为空时由 bootstrap 执行 `db.create_all()` 并导入 `sql/init_db.sql`。

| 服务 | 地址 |
|------|------|
| 检澜 Web | <http://localhost:8080> |
| 检澜 API | <http://127.0.0.1:5000> |

停止：

```bash
npm run down
```

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

| 变量 | 说明 |
|------|------|
| `MYSQL_ROOT_PASSWORD` | MySQL root 密码（默认 `bridgedisease_root`） |
| `MYSQL_DATABASE` | 数据库名（默认 `bridge_disease`） |
| `MYSQL_HOST_PORT` | 主机映射端口（默认 `3307`） |
| `VITE_API_BASE_URL` | 构建前端镜像时的 API 基地址 |

---

## 数据种子脚本

| 脚本 | 作用 |
|------|------|
| `scripts/download_real_medias.py` | 从 Wikimedia / Pexels 下载真实照片到 `seed_assets/medias/` |
| `scripts/seed_medias.py` | 导入媒体文件并同步 `media` 表 |
| `scripts/seed_detections.py` | 插入 20 条安全隐患检测演示记录（需已有 user/model/media） |
| `scripts/fix_user_names.py` | 修复用户姓名 `??` 乱码 |
| `scripts/fix_model_texts.py` | 修复模型隐患类别、检测描述乱码 |
| `scripts/seed_models.py` | 下载 YOLOv8n-seg 并复制为演示用 `.pt` 权重 |
| `scripts/create_demo_dataset.py` | 生成试跑用 `bridge_hazard_demo.zip` 与 YOLO 分割演示数据集 |
| `scripts/export_db_snapshot.py` | 将当前 MySQL + 静态资源导出到 `sql/seed_snapshot.sql` 与 `seed_assets/snapshot/` |
| `scripts/import_db_snapshot.py` | 导入上述快照（新同事一键还原演示环境） |

照片版权说明见 `BridgeDiseaseBackend-main/seed_assets/medias/ATTRIBUTION.md`。

---

## 首次登录与种子账号

数据库由 `sql/init_db.sql` 初始化后，可使用下列账号（**用户名或邮箱均可登录**；登录成功后状态变为已启用）：

| 角色 | 用户名 | 邮箱 | 密码 |
|------|--------|------|------|
| 管理员 | `admin` | `admin@example.com` | `Admin123456` |
| 开发人员 | `developer` | `dev@example.com` | `developer-WZY` |
| 普通用户 | `demo` | `user@example.com` | `user-WZY` |

**若提示「用户尚未注册」**：说明种子未成功导入。可清空库后重新导入 `init_db.sql`，或 Docker 删卷后 `npm run up`。**上线前务必修改全部默认密码与密钥**（`JWT_SECRET_KEY`、`SECRET_KEY`、数据库密码等）。

---

## 常用命令

| 场景 | 命令 |
|------|------|
| 仅启动 MySQL | `docker compose -p bridge-disease up -d db` |
| Docker 全栈 | 根目录 `npm run up` |
| Docker 停止 | 根目录 `npm run down` |
| 前端开发 | `cd bridge-disease-frontend-main && npm run serve` |
| 前端构建 | `cd bridge-disease-frontend-main && npm run build` |
| 后端开发 | `cd BridgeDiseaseBackend-main && python run.py` |
| 后端开发（Windows） | 项目根目录 `.\scripts\start-backend.ps1` |

---

## 疑难排解

| 现象 | 处理 |
|------|------|
| 中文显示 `??`（姓名、隐患类别等） | 连接串加 `charset=utf8mb4`，运行 `fix_user_names.py` / `fix_model_texts.py` |
| 登录报 `Asia/Shanghai` 时区错误 | Windows 安装 `tzdata`：`pip install tzdata` |
| Docker 在中文路径构建失败 | 使用 `npm run up`，或项目移到 ASCII 路径 |
| 列表无数据 | 确认后端已启动、`VITE_API_BASE_URL` 正确；或运行 `seed_medias.py` / `seed_detections.py` |
| 媒体库无图 | 运行 `seed_medias.py`；`static/` 已在 `.gitignore`，需本地生成 |
| 推理慢或内存不足 | PyTorch/YOLO 需足够 RAM；可选 GPU 环境 |
| 批量检测 / 台账 / 报告 / IoT 数据丢失 | 上述模块数据在浏览器 `localStorage`，清缓存会重置 |
| Mermaid 图不渲染 | 使用支持 Mermaid 的 Markdown 预览（GitHub、VS Code 插件等） |
| 模型训练一直「排队」、列表变空 | 确认 5000 为本项目后端；刷新训练页或重启后端（会恢复 pending）；`jobs.json` 损坏时可从 `jobs.json.bak` 恢复 |
| 训练完成但任务列表无数据 | 多为 `jobs.json` 写入异常，已修复 datetime 序列化；修复后刷新页面 |

---

## 授权与声明

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