前端项目介绍

本章节面向前端开发人员，介绍 hertz_server_diango_ui_2 这一 Vue3 管理端工程的整体结构、技术选型和核心业务模块，方便在技术文档平台中作为“前端项目总览”使用。

工程定位：

作为 Hertz System 的 管理后台 + 检测端 + AI 端 前端，实现账号体系、权限路由、主题系统、知识库、AI 助手、YOLO 全流程（模型 / 数据集 / 训练 / 告警 / 历史）等功能。

一、前端技术栈

框架：Vue 3（Composition API，<script setup> 写法）
语言：TypeScript
构建工具：Vite
路由：Vue Router 4
状态管理：Pinia
UI 组件库：Ant Design Vue
图表库：ECharts
HTTP 客户端：Axios
其他依赖：
- socket.io-client：实时通信（如告警推送、实时检测）。
- jszip：前端 ZIP 压缩/解压处理。
- onnxruntime-web：预留 Web 端推理能力。

开发 & 构建脚本（见 package.json）：

npm run dev：本地开发调试。
npm run build：类型检查 + 生产构建。
npm run preview：本地预览生产构建产物。

二、项目目录结构（前端工程）

前端工程位于：hertz_server_diango_ui_2/，其主要目录结构如下：

text

hertz_server_diango_ui_2/
├── public/                      # 公共静态资源（不经过打包）
├── src/                         # 源代码目录
│   ├── api/                     # 接口定义（auth / yolo / knowledge / captcha / ai ...）
│   ├── assets/                  # 静态资源
│   ├── components/              # 通用业务组件
│   ├── config/                  # 模块配置（如模块开关）
│   ├── locales/                 # 国际化文案
│   ├── router/                  # 路由与菜单配置
│   ├── stores/                  # Pinia Store
│   ├── styles/                  # 全局样式与主题变量
│   ├── types/                   # TypeScript 类型定义
│   ├── utils/                   # 工具方法 & 基础设施
│   ├── views/                   # 所有页面
│   ├── App.vue                  # 应用根组件
│   └── main.ts                  # 入口文件
├── components.d.ts              # 自动导入组件的类型声明
├── vite.config.ts               # Vite 配置（别名、代理等）
├── eslint.config.js             # ESLint 配置
├── index.html                   # 单页入口模板
└── package.json                 # 依赖与脚本

其中 src/views/ 和 src/api/、src/router/、src/utils/、src/stores/ 是前端开发的主要关注点，下面分别展开。

2.1 路由与菜单（router/）

router/index.ts：
- 创建 Vue Router 实例，挂载全局路由守卫（登录校验、模块选择校验等）。
- 将管理端和用户端的路由树合并，并处理 404 重定向。
router/admin_menu.ts：
- 使用统一的 ADMIN_MENU_CONFIG 配置管理端菜单和路由。
- 根据 moduleKey 与 hertz_modules.ts 联动，支持按模块开关裁剪菜单。
- 暴露自动生成的路由配置和菜单配置，供布局和侧边栏使用。
router/user_menu_ai.ts：
- 描述用户端（检测端 + AI 端）菜单结构，包括 YOLO 检测、系统监控、AI 助手、知识库等。
- 与 user_pages/ 下的页面组件一一对应。

2.2 国际化（locales/）

locales/index.ts：
- 创建并导出 i18n 实例，在 main.ts 中注册。
- 负责语言切换与默认语言配置。
locales/zh-CN.ts / locales/en-US.ts：
- 提供中英文文案键值表，覆盖菜单标题、按钮文字、提示信息等。
- 管理端与用户端页面共用同一套 key，以便多语言切换。

2.3 类型定义（types/）

types/env.d.ts：
- 对 Vite 环境变量（如 VITE_API_BASE_URL、VITE_TEMPLATE_SETUP_MODE）进行类型声明。
- 方便在代码中通过 import.meta.env 获取变量时具备类型提示。
types/hertz_types.ts：
- 汇总项目中常用的业务类型，例如用户信息、菜单配置、通用响应结构等。
- API 层和视图层可复用这些类型，减少重复定义。

三、管理后台核心模块说明

1. 仪表盘（Dashboard）

展示整体系统运行情况，包括：
- 检测任务统计
- 告警统计
- 最近任务 & 最近告警列表
视觉风格：简洁浅色、圆角卡片、阴影，与 YOLO 模块保持统一设计语言。

2. 用户 & 权限管理

用户管理：
- 用户列表、搜索、创建/编辑、启用/禁用
部门管理：
- 树形结构展示部门层级
- 列间距和样式为本项目中表格的设计基准
角色管理：
- 角色列表、权限分配
菜单管理：
- 左侧菜单配置管理
- 已按部门管理的样式美化，去掉“创建时间”列，聚焦核心信息

3. 文章管理

原“知识库管理”统一改名为“文章管理”：
- 菜单标题、路由名称、页面文案均已同步调整
功能：
- 分类 + 文档列表
- 新增 / 编辑 / 删除文章
界面优化：
- 缩短分类与文档列表之间的间距
- 文档列表中的操作按钮全部展示（不再折叠下拉）

4. 通知与日志

通知管理：
- 通知列表、类型筛选、状态筛选
- 表格列间距和样式参照部门管理，并显示创建时间（仅展示日期）
操作日志：
- 管理端操作行为审计，支持时间范围和关键字查询

5. 公共与辅助页面（顶层 views）

Home.vue：系统入口页或重定向中转页。
Login.vue / register.vue：登录与注册页面，接入验证码与后台鉴权接口。
ModuleSetup.vue：模块选择向导页，结合 hertz_modules.ts，用于在模板模式下选择启用哪些模块。
NotFound.vue：404 页面，在路由未命中时展示。

四、YOLO 模块整体设计

YOLO 模块由 模型管理 + 数据集管理 + 训练管理 + 告警/历史 组成，统一挂在侧边栏父菜单 “YOLO模型” 下。

1. YOLO 模型管理（ModelManagement.vue）

模型列表：名称、版本、大小、状态（启用/未启用）、上传时间等。
操作：
- 上传模型：通过 yoloApi.uploadModel 上传权重文件。
- 启用模型：yoloApi.enableModel 用于切换当前在线模型。
- 编辑信息 / 删除模型。
与检测模块联动：检测请求会优先使用当前启用的模型。

2. YOLO 数据集管理（DatasetManagement.vue）

使用 yoloApi 中的数据集接口：
- uploadDataset：上传 YOLO 格式 ZIP 数据集。
- getDatasets：获取数据集列表。
- getDatasetDetail：获取数据集详情（类别、图片/标注数量、路径）。
- getDatasetSamples：按 train/val/test 分页获取样本并展示标注框。
- deleteDataset：删除数据集。
主要视图：
1. 列表视图：
  - 卡片包含名称、版本、创建日期、描述、train/val/test 图片数量等。
  - 风格与仪表盘一致：白色圆角卡片 + 阴影。
2. 详情视图：
  - 显示类别列表、根目录和 data.yaml 配置路径。
  - 显示 train/val/test 图片和标注的数量分布条形图。
3. 样本浏览视图：
  - 可选择 train/val/test 分割。
  - 显示缩略图、文件名、大小、标注目标数量及类别标签。
  - 点击样本可打开大图预览，并在图片上叠加 YOLO 标注框。

3. YOLO 训练管理（YoloTrainManagement.vue）

这是本次重点改造的模块，对应 YOLO 训练接口文档，分为：

训练任务列表视图
训练任务详情视图
创建训练任务视图

3.1 训练任务列表视图

顶部：
- 左侧为状态筛选按钮组：全部任务 / 进行中 / 已完成。
- 右侧为“刷新任务”按钮（接口层面仍可强制刷新列表）。
每个训练任务卡片展示：
- 标题：训练任务 #ID + 状态 Tag（排队中/训练中/已完成/失败/已取消）。
- 副标题：数据集名称 + YOLO 版本/尺寸 + 创建时间。
- 训练进度：
  - 展示为百分比数字 + 进度条。
  - 使用前端缓冲动画：
    - 实际进度来自后端 progress 字段。
    - 前端维护 jobDisplayProgress，以 1% 步长平滑追踪真实进度，使进度条不会突然从 50% 跳到 100%。
- 训练参数概览：epochs、imgsz、batch、optimizer 等。
- 底部：运行时长和操作按钮：
  - 查看详情
  - 进行中：取消训练
  - 已结束：删除任务

3.2 训练任务详情视图

顶部横向信息：
- 返回列表按钮。
- 标题：训练任务 #ID + 状态 Tag。
- 副标题：数据集名称、模型版本+尺寸、创建时间。
- 右侧操作：
  - 进行中：取消训练。
  - 已完成：下载结果 ZIP。
  - 永久删除任务。
状态概览卡片（3 列）：
- 任务状态。
- 训练进度（使用 detailDisplayProgress，与列表进度同步、平滑动画）。
- 运行时长。
左侧 配置信息卡片：
- 模型版本（YOLOv8/YOLO11/YOLO12 等）、模型尺寸（n/s/m/l/x）。
- 训练轮数、图像尺寸、批次大小、设备、优化器、关联数据集等。
- 底部展示模型配置文件路径（只读输入框）。
右侧 训练日志卡片：
- 深色背景的日志窗口，滚动条自动吸底。
- 日志内容来自 yoloApi.getTrainJobLogs(job_id, { offset, max })：
  - 使用 offset 增量拉取，并附带 finished 标记。
  - 每次追加 content 后调用 scrollLogsToBottom() 自动滚动到底部。
- 自动轮询：
  - 常量 LOG_POLL_INTERVAL = 2000 毫秒。
  - startLogsPolling() 在进入详情视图时启动，stopLogsPolling() 在离开详情或卸载组件时停止。
  - 每轮轮询流程：
    1. 调用 getTrainJobLogs 追加新日志内容。
    2. 调用 getTrainJobDetail 同步最新任务状态与 progress。
    3. 如果任务状态为 completed，强制将列表和详情中的显示进度设置为 100%。

3.3 创建训练任务视图

头部：返回列表 + 标题 创建训练任务 + 副标题。
表单内容分为两块：
1. 基础配置：
  - 数据集：从 getTrainOptions 返回的 datasets 渲染下拉框。
  - 模型版本：从 versions 渲染 YOLOv8 / YOLO11 / YOLO12 等选项。
2. 训练参数：
  - 训练轮数（Epochs）：默认 100，可配置范围 1–500。
  - 图像尺寸（Image Size）：默认 640，可配置范围 64–2048。
  - 批次大小（Batch Size）：默认 16。
  - 设备（Device）：默认 0（GPU 0），也可填 cpu。
  - 优化器（Optimizer）：SGD（推荐）/Adam/AdamW/RMSProp。
底部按钮：
- 取消：重置为默认参数。
- 开始训练：
  - 调用 startTrainJob(payload) 创建训练任务。
  - 成功后切回列表视图并刷新任务列表。

五、YOLO 训练相关接口封装

在 src/api/yolo.ts 中新增/整合了以下接口和类型，以配合训练管理页面：

1. 类型定义

YoloTrainStatus：queued | running | canceling | completed | failed | canceled。
YoloTrainDatasetOption：训练数据集下拉选项。
YoloTrainVersionOption：YOLO 版本和可选模型尺寸配置。
YoloTrainingJob：训练任务实体，包含：
- id, dataset, dataset_name, model_family, model_size
- status, progress, epochs, imgsz, batch, device, optimizer
- logs_path, runs_path, best_model_path, last_model_path
- created_at, started_at, finished_at, error_message 等。
StartTrainingPayload：创建训练任务的请求体。
YoloTrainLogsResponse：训练日志接口返回结构（content, next_offset, finished）。

2. 接口方法

getTrainOptions()：获取训练可选的数据集和模型版本信息。
getTrainJobs()：获取训练任务列表。
startTrainJob(payload)：创建并启动训练任务。
getTrainJobDetail(id)：获取训练任务详情。
getTrainJobLogs(id, params)：分页读取训练日志。
cancelTrainJob(id)：取消训练任务。
downloadTrainJobResult(id)：获取训练结果 ZIP 下载地址。
deleteTrainJob(id)：删除训练任务记录及相关输出文件。

六、交互与视觉统一性

所有新改造页面（数据集管理、训练管理）遵循与仪表盘一致的设计：
- 背景：浅灰色 #f5f5f7。
- 内容容器：白色圆角卡片 + 适度阴影。
- 标题区使用图标+主标题+描述文案。
表格与卡片间距、字体大小、颜色风格都参考部门管理和仪表盘，保证统一体验。
YOLO 系列页面在左侧菜单下集中，便于使用者快速理解“模型 → 数据集 → 训练 → 告警/历史”的完整链路。

七、后端无关的扩展方向（YOLO 模块）

训练日志高亮与结构化展示：
- 解析 YOLO 日志中的表格行（epoch 指标）、速度信息，提取为结构化数据，在详情页以表格和图表形式展示，同时保留原始文本日志。
训练指标可视化：
- 使用 ECharts 绘制 mAP / precision / recall / loss 随 epoch 变化的曲线图。
任务队列与资源视图：
- 展示 GPU 资源占用情况、队列中任务数，支持优先级调整。
一键复训 / 迁移学习：
- 在训练详情中新增“以此任务为模板创建新任务”的能力，自动继承上一次的参数与数据集。

八、整体业务模块地图（Admin + User）

这一节从“最终使用者”的角度，梳理整个前端工程中已经实现的业务模块，方便新人快速对齐“有哪些页面、负责什么事”。

8.1 管理端（Admin）模块

入口组件：src/views/admin_page/index.vue，通过 src/router/admin_menu.ts 生成菜单和路由。

仪表盘（Dashboard）
- 实时统计：检测次数、告警数量、近 7 日趋势等。
- 快捷入口：YOLO 检测、模型管理、告警中心等。
用户 / 组织与权限
- 用户管理：账号列表、搜索、创建/编辑、重置密码、启用/禁用。
- 部门管理：树状结构管理部门层级，配置上级部门与负责人。
- 角色管理：角色-权限绑定，支持多角色分配给用户。
- 菜单管理：维护左侧管理菜单结构，与权限标识 permission 绑定。
文章管理
- 文章分类树 + 列表视图 + 编辑/发布。
- 支持富文本或 Markdown（依具体实现），用于知识库/文档内容管理。
通知与日志
- 通知管理：维护系统站内通知，含状态、类型、发送对象等。
- 日志管理：审计管理端登录/操作日志，可按时间和关键字查询。
YOLO 模块（管理端）
- 模型管理：上传/启用/删除 YOLO 模型，展示版本与元数据。
- 模型类别管理：配置每个检测类别的告警等级与颜色标签。
- 告警处理中心：查看并处理检测产生的告警记录。
- 检测历史管理：查询历史检测任务，查看图片/视频 + 检测结果。
- 数据集管理：YOLO 数据集上传、详情查看、样本浏览（含标注框预览）。
- 训练管理：训练任务列表、详情、创建任务（见前文 YOLO 章节）。

8.2 用户端（检测端 / AI 端）模块

入口：src/views/user_pages/index.vue，菜单由 src/router/user_menu_ai.ts 驱动。

系统监控（SystemMonitor.vue）
- 展示 CPU、内存、磁盘、网络等系统资源的实时使用情况。
- 与后端系统监控接口联动，以图表/指标卡形式展示。
YOLO 离线检测（YoloDetection.vue）
- 上传图像或视频文件，选择模型，执行离线检测。
- 展示检测结果叠加框、类别标签和置信度。
YOLO 实时检测（LiveDetection.vue）
- 通过 WebSocket 推流实时画面，展示实时检测框。
- 联动告警中心：当检测结果达到告警条件时推送到告警列表。
检测历史（DetectionHistory.vue）
- 面向用户的检测历史列表，可按时间、状态筛选。
- 支持查看历史检测的图片/视频及检测结果明细。
告警中心 / 通知中心（AlertCenter.vue / NoticeCenter.vue）
- 告警中心：查看由模型检测产生的告警记录，支持按类型/时间筛选、标记已读等。
- 通知中心：管理与当前登录用户相关的系统通知（未读/已读）。
消息中心（Messages.vue）
- 汇总与当前用户相关的站内消息，支持查看详情与状态更新。
AI 助手（AiChat.vue 等）
- 多会话对话界面：左侧会话列表、右侧消息流。
- 支持多布局显示模型回复、调试信息、提示词等。
知识库 / 文档中心（KnowledgeCenter.vue / KnowledgeDetail.vue / Documents.vue）
- 提供面向终端用户的知识库浏览能力。
- 支持按分类查看文章列表、查看文章详情，与管理端文章管理模块共用同一数据源。
个人中心（Profile.vue）
- 展示和编辑当前登录用户的基础信息。
- 可能包含修改密码、头像、联系方式等配置入口。

九、API 层设计总览（src/api）

所有接口文件统一放在 src/api/，通过 Axios 封装 hertz_request.ts 发送请求，单个领域一个文件：

auth.ts：认证相关接口
- 登录、注册、刷新 Token、登出等。
user.ts：用户管理接口
- 获取用户列表、创建/更新用户、重置密码等。
department.ts：部门树管理。
role.ts：角色 CRUD 与角色权限设置。
menu.ts：菜单/路由配置的后端接口（若启用后台驱动菜单）。
notice_user.ts：通知与用户关系（未读/已读等）。
log.ts：操作日志查询接口。
dashboard.ts：仪表盘度量/统计接口。
system_monitor.ts：系统运行状态、资源监控等接口。
knowledge.ts：文章/知识库相关接口。
ai.ts：AI 助手对话、会话历史接口。
captcha.ts：图形验证码获取与校验。
password.ts：修改密码、忘记密码相关接口。
yolo.ts：YOLO 模块全量接口（检测 / 模型 / 数据集 / 训练 / 告警 / 历史）。

所有 API 文件遵循同一约定：

默认导出 xxxApi 对象（例如 yoloApi）。
使用明确的 TS 类型（type UserInfo、type YoloTrainingJob 等）。
请求统一走 request.get/post/put/delete/upload，在拦截器中处理错误弹窗和鉴权。

十、状态管理（Pinia Stores）

路径：src/stores/。

hertz_app.ts：
- 管理全局应用设置：语言、侧边栏折叠、面包屑开关、页面加载动画等。
hertz_user.ts：
- 持久化用户信息和 Token，封装登录/登出动作，在路由守卫中使用。
hertz_theme.ts：
- 主题色、暗色模式、字体与圆角配置，与 styles/variables.scss 配合使用。

所有 Store 使用 Composition API 写法（defineStore），并通过 main.ts 在根组件挂载。

十一、工具与基础设施（src/utils）

主要文件：

hertz_request.ts：
- 基于 Axios 创建统一实例，处理 baseURL、超时、错误统一提示。
- 在开发环境使用 Vite 代理，生产环境使用 VITE_API_BASE_URL。
hertz_url.ts：
- 封装 getBackendBaseUrl / getApiBaseUrl / getMediaBaseUrl 等方法，统一拼接后端 HTTP、WebSocket 与媒体访问地址。
- 提供 getFullFileUrl(relativePath) 用于在前端展示后端图片/文件。
hertz_env.ts：
- 读取并校验环境变量，对关键信息给出默认值或错误提示。
hertz_router_utils.ts：
- 与路由和菜单相关的辅助工具，提供调试输出等功能。
其他 util：按领域拆分，如格式化时间、构造查询参数等。

十二、环境与部署要点（前端视角）

环境变量文件：.env.development / .env.production
- 关键变量：VITE_API_BASE_URL（后端服务地址）。
- 只写协议 + 域名/IP + 端口，不包含 /api，例如：http://localhost:8000。
Vite 代理与打包：
- 开发环境通过 vite.config.ts 中的 server.proxy 将 /api 和 /media 转发到后端。
- 生产环境中 Axios 直接使用 VITE_API_BASE_URL 作为 baseURL。
模块模板模式与一键裁剪：
- 通过 src/config/hertz_modules.ts + VITE_TEMPLATE_SETUP_MODE 支持在运行时选择启用哪些模块。
- npm run prune 可以根据模块配置裁剪前端代码体积（仅屏蔽或物理删除）。
快速启动：
- 安装依赖：npm i
- 开发模式：npm run dev
- 生产打包：npm run build，再由后端（如 Django/Nginx）托管 dist/ 静态文件。

前端项目介绍 ​

一、前端技术栈 ​

二、项目目录结构（前端工程） ​

2.1 路由与菜单（router/） ​

2.2 国际化（locales/） ​

2.3 类型定义（types/） ​

三、管理后台核心模块说明 ​

1. 仪表盘（Dashboard） ​

2. 用户 & 权限管理 ​

3. 文章管理 ​

4. 通知与日志 ​

5. 公共与辅助页面（顶层 views） ​

四、YOLO 模块整体设计 ​

1. YOLO 模型管理（ModelManagement.vue） ​

2. YOLO 数据集管理（DatasetManagement.vue） ​

3. YOLO 训练管理（YoloTrainManagement.vue） ​

3.1 训练任务列表视图 ​

3.2 训练任务详情视图 ​

3.3 创建训练任务视图 ​

五、YOLO 训练相关接口封装 ​

1. 类型定义 ​

2. 接口方法 ​

六、交互与视觉统一性 ​

七、后端无关的扩展方向（YOLO 模块） ​

八、整体业务模块地图（Admin + User） ​

8.1 管理端（Admin）模块 ​

8.2 用户端（检测端 / AI 端）模块 ​

九、API 层设计总览（src/api） ​

十、状态管理（Pinia Stores） ​

十一、工具与基础设施（src/utils） ​

十二、环境与部署要点（前端视角） ​