# 康桥 -  检澜（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 …`。
- **个人中心**：查看与维护当前用户资料、头像等（具体字段以后端 `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`。

---

## 检澜技术架构

### 总体部署视图

```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)]
    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` | 静态文件访问（头像、媒体、结果图等） |

### 检测任务数据流（简图）

```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 与推理服务（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）** 实际界面截图（按文件名排序）。若需与具体页面一一对应，可将文件重命名为可读名称并同步修改下列路径。

![检澜 界面 0](images/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)


---

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

在**项目根目录**执行（需已安装 [Docker](https://docs.docker.com/get-docker/) 与 [Node.js](https://nodejs.org/)，用于执行根目录脚本）：

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

此流程会：

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

启动完成后：

- **检澜** Web：<http://localhost:8080>  
- **检澜** API（Flask）：<http://127.0.0.1:5000>  

停止并移除容器：

```bash
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. 数据库与后端

1. 安装 **MySQL 8**，创建数据库（例如 `bridge_disease`）。  
2. Python **3.11+** 建议与 `Dockerfile` 一致。  

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

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

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

4. 启动应用：

```bash
python run.py
```

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

### 2. 前端

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

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

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

启动开发服务器：

```bash
npm run serve
```

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

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

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

```env
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 网页）查看；不影响项目运行。

---

## 授权与声明

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