初始化项目

README.md

@@ -1,92 +1,339 @@
-# Kadupul
+# 康桥 -  检澜（DockScope）
 
+** 康桥  桥梁检测     检澜 DockScope** 是面向**桥梁结构缺陷智能分析**的一体化工作台：围绕「媒体 / 模型 / 检测任务 / 结果与指标」闭环，提供 Web 端界面与 REST API。本仓库即检澜的**前后端源码**——前端为 **Vue 3 + Element Plus + ECharts**（`bridge-disease-frontend-main`）；后端为 **Flask + SQLAlchemy + MySQL**（`BridgeDiseaseBackend-main`），检测分割管线使用 **Ultralytics YOLO** 等完成推理与结果落盘。
 
+![检澜 界面](images/0数据看板.png)
 
-## Getting started
+## 检澜核心功能
 
-To make it easy for you to get started with GitLab, here's a list of recommended next steps.
+### 账号与权限
 
-Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
+- **注册 / 登录 / 忘记密码**：表单提交至后端，成功后下发 **JWT**（Access + Refresh），前端持久化于 `localStorage` 并在 Axios 拦截器中自动携带 `Authorization: Bearer …`。
+- **个人中心**：查看与维护当前用户资料、头像等（具体字段以后端 `User` 模型与路由为准）。
+- **角色模型**：`ADMIN`（管理员）、`DEVELOPER`（开发人员）、`USER`（普通用户）。部分菜单与列表接口仅对管理员或开发开放（见下节「角色与界面」）。
 
-## Add your files
+### 数据看板（`/home`）
 
-- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
-- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:
+- 登录后的默认工作台：侧栏导航、面包屑、**数据洞察**与**社群快捷入口**等壳层组件，以及基于 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
 ```
-cd existing_repo
-git remote add origin https://www.gitcc.com/eric.w/kadupul.git
-git branch -M main
-git push -uf origin main
+
+4. 启动应用：
+
+```bash
+python run.py
 ```
 
-## Integrate with your tools
+默认监听由环境变量 `FLASK_RUN_HOST` / `FLASK_RUN_PORT` 控制（见 `run.py`）。首次若需种子，可在空库时自行导入 `sql/init_db.sql`，或参考 `docker/backend/bootstrap.py` 的流程。
+
+### 2. 前端
 
-- [ ] [Set up project integrations](https://www.gitcc.com/eric.w/kadupul/-/settings/integrations)
+```bash
+cd bridge-disease-frontend-main
+npm install
+```
 
-## Collaborate with your team
+在 `bridge-disease-frontend-main` 下新增 `.env.local`（或 `.env.development`），指向本机后端：
 
-- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
-- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
-- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
-- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
-- [ ] [Set auto-merge](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)
+```env
+VITE_API_BASE_URL=http://127.0.0.1:5000
+```
 
-## Test and Deploy
+启动开发服务器：
 
-Use the built-in continuous integration in GitLab.
+```bash
+npm run serve
+```
 
-- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)
-- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
-- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
-- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
-- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
+浏览器打开终端显示的本机 URL（Vite 默认多为 `http://localhost:5173`）。API 请求会带上 `Authorization: Bearer <access_token>`（登录后由前端写入 `localStorage`）。
 
-***
+### 3. 列表模拟数据（无后端时调 UI）
 
-# Editing this README
+在 `bridge-disease-frontend-main/.env.local` 设置：
+
+```env
+VITE_USE_LIST_MOCK=true
+```
 
-When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template.
+则「检测分割记录」与「媒体库」列表会使用 `src/mocks/detectionAndMediaMockData.js` 的本地分页数据，**不**调用对应列表 API。预览图仍可能请求 `/file/...`，若无实体文件则图片可能无法显示。
 
-## Suggestions for a good README
-Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
+---
 
-## Name
-Choose a self-explaining name for your project.
+## 首次登录与种子账号
 
-## Description
-Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
+数据库由 `sql/init_db.sql` 初始化后，可使用下列测试账号（**登录框填「用户名」或「邮箱」均可**；密码见 SQL 内注释；登录成功后状态会变为已启用）：
 
-## Badges
-On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
+| 角色 | 用户名 | 邮箱（也可用于登录） | 密码 |
+|------|--------|----------------------|------|
+| 管理员 | `admin` | `admin@example.com` | `Admin123456` |
 
-## Visuals
-Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
+**若提示「用户 xxx 尚未注册」**：说明当前 MySQL 里**没有对应种子用户**，常见原因包括：① 从未成功执行过 `init_db.sql`（或 Docker 首次启动时种子失败）；② 数据库里已有旧数据，bootstrap 因「用户表非空」跳过了种子；③ 旧版种子里 `role`/`status` 与枚举不一致导致插入失败。处理方式：**清空该库后重新导入** `BridgeDiseaseBackend-main/sql/init_db.sql`，或删除 `user` 表数据后重启后端让 bootstrap 重新播种（Docker 可删卷后 `npm run up`）。**上线前务必修改全部默认密码与密钥。**
 
-## Installation
-Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
+实际部署请务必**更换密钥与密码**，并通过环境变量设置 `JWT_SECRET_KEY`、`SECRET_KEY` 与数据库 URI，不要沿用示例默认值。
 
-## Usage
-Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
+---
 
-## Support
-Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
+## 常用命令整理
 
-## Roadmap
-If you have ideas for releases in the future, it is a good idea to list them in the README.
+| 场景 | 命令 |
+|------|------|
+| 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` |
 
-## Contributing
-State if you are open to contributions and what your requirements are for accepting them.
+---
 
-For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
+## 疑难排解
 
-You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
+- **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 网页）查看；不影响项目运行。
 
-## Authors and acknowledgment
-Show your appreciation to those who have contributed to the project.
+---
 
-## License
-For open source projects, say how it is licensed.
+## 授权与声明
 
-## Project status
-If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
+各子目录可能包含第三方依赖，版权归原作者所有。若 **检澜** 或本仓库需对外发布，请补充适当的开源授权文件与数据使用声明。