工程化完善：TS 强类型、模块化 API、统一请求封装、权限化菜单/路由
设计统一：全局“超现代风格”主题，卡片 / 弹窗 / 按钮 / 输入 / 分页风格一致
业务可复用：
- 知识库管理：分类树 + 列表搜索 + 编辑/发布
- YOLO 模型：模型管理、模型类别管理、告警处理中心、检测历史管理
- AI 助手：多会话列表 + 消息记录 + 多布局对话界面（含错误调试信息）
- 认证体系：登录/注册、验证码
可扩展：清晰的目录划分和命名规范，方便直接加模块或替换现有实现

🧩 技术栈

构建：Vite
语言：TypeScript
框架：Vue 3（Composition API）
UI：Ant Design Vue
状态：Pinia
路由：Vue Router

📦 项目结构与职责

根目录：通用大模型模板/

通用大模型模板/
└─ hertz_server_diango_ui_2/              # 前端工程（Vite）
   ├─ public/                             # 公共静态资源（不走打包器）
   ├─ src/
   │  ├─ api/                             # 接口定义（auth / yolo / knowledge / captcha / ai ...）
   │  │   └─ yolo.ts                      # YOLO 模型 & 检测 & 类别相关 API
   │  ├─ locales/                         # 国际化文案
   │  ├─ router/                          # 路由与菜单配置
   │  │   ├─ admin_menu.ts                # 管理端菜单 + 路由映射（权限 key）
   │  │   ├─ user_menu_ai.ts              # 用户端菜单 + 路由映射（含 AI 助手）
   │  │   └─ index.ts                     # Vue Router 实例 + 全局路由守卫
   │  ├─ stores/                          # Pinia Store
   │  │   ├─ hertz_app.ts                 # 全局应用设置（语言、布局、菜单折叠等）
   │  │   ├─ hertz_user.ts                # 用户 / 鉴权状态
   │  │   └─ hertz_theme.ts               # 主题配置与 CSS 变量
   │  ├─ styles/                          # 全局样式与变量
   │  │   ├─ index.scss                   # 全局组件风格覆盖（Button / Table / Modal ...）
   │  │   └─ variables.scss               # 主题色、阴影、圆角等变量
   │  ├─ utils/                           # 工具方法 & 基础设施
   │  │   ├─ hertz_request.ts             # Axios 封装（baseURL、拦截器、错误提示）
   │  │   ├─ hertz_url.ts                 # 统一 URL 构造（API / 媒体 / WebSocket）
   │  │   ├─ hertz_env.ts                 # 读取 & 校验 env 变量
   │  │   └─ hertz_router_utils.ts        # 路由相关工具 & 调试
   │  ├─ views/                           # 所有页面
   │  │   ├─ admin_page/                  # 管理端页面
   │  │   │   ├─ ModelManagement.vue      # YOLO 模型管理
   │  │   │   ├─ AlertLevelManagement.vue # 模型类别管理
   │  │   │   ├─ DetectionHistoryManagement.vue # 检测历史管理
   │  │   │   └─ ...                      # 其他管理端模块
   │  │   ├─ user_pages/                  # 用户端页面（检测端 + AI 助手）
   │  │   │   ├─ index.vue                # 用户端主布局 + 顶部导航
   │  │   │   ├─ AiChat.vue               # AI 助手对话页面
   │  │   │   ├─ YoloDetection.vue        # 离线检测页面
   │  │   │   ├─ LiveDetection.vue        # 实时检测页面（WebSocket）
   │  │   │   └─ ...                      # 告警中心 / 通知中心 / 知识库等
   │  │   ├─ Login.vue                    # 登录页
   │  │   └─ register.vue                 # 注册页
   │  ├─ App.vue                          # 应用根组件
   │  └─ main.ts                          # 入口文件（挂载 Vue / 路由 / Pinia）
   ├─ .env.development                    # 开发环境变量（前端专用）
   ├─ .env.production                     # 生产构建环境变量
   ├─ vite.config.ts                      # Vite 配置（代理、构建、别名等）
   └─ package.json

📁 文件与命名规范（建议）

组件 / 页面
- 页面：src/views/admin_page/FooBarManagement.vue，以业务 + Management 命名
- 纯组件：放到 src/components/，使用大驼峰命名，如 UserSelector.vue
接口文件
- 同一业务一个文件：src/api/yolo.ts、src/api/auth.ts
- 内部导出 xxxApi 对象 + TS 类型：type AlertLevel, type YoloModel 等
样式
- 全局或主题相关：放 src/styles/（注意不要在这里写页面私有样式）
- 单页面样式：使用 <style scoped lang="scss"> 写在对应 .vue 内
工具函数
- 通用工具：src/utils/ 下按领域拆分，如 hertz_url.ts、hertz_env.ts

🌐 后端 IP / 域名配置指引（前端视角最重要）

当前工程已经统一了后端地址配置，只需要 改 2 个地方：

环境变量文件（推荐只改这个）
- hertz_server_diango_ui_2/.env.development
- hertz_server_diango_ui_2/.env.production
两个文件里都有一行：
```
# 示例：开发环境
VITE_API_BASE_URL=http://192.168.124.40:8022
```
约定：
- 只写协议 + 域名/IP + 端口，不要包含 /api
  - ✅ http://192.168.124.40:8022
  - ❌ http://192.168.124.40:8022/api
- 开发与生产可指向不同后端，只要保证同样的接口路径即可。

Vite 代理 & URL 工具（已接好，通常不用改）

vite.config.ts

利用 loadEnv 读取 VITE_API_BASE_URL，自动去掉末尾 /：

const env = loadEnv(mode, process.cwd(), '')
const apiBaseUrl = env.VITE_API_BASE_URL || 'http://localhost:3000'
const backendOrigin = apiBaseUrl.replace(/\/+$/, '')

开发环境通过代理转发：

server: {
  proxy: {
    '/api': { target: backendOrigin, changeOrigin: true },
    '/media': { target: backendOrigin, changeOrigin: true }
  }
}

define: {
  __VITE_API_BASE_URL__: JSON.stringify(`${backendOrigin}/api`)
}

src/utils/hertz_url.ts

统一获取后端基础地址：

export function getBackendBaseUrl(): string {
  return import.meta.env.VITE_API_BASE_URL || 'http://localhost:3000'
}

构造 HTTP / WebSocket / 媒体地址：

export function getApiBaseUrl() {
  return import.meta.env.DEV ? '' : getBackendBaseUrl()
}

export function getMediaBaseUrl() {
  if (import.meta.env.DEV) return ''
  return getBackendBaseUrl().replace('/api', '')
}

export function getFullFileUrl(relativePath: string) {
  const baseURL = getBackendBaseUrl()
  return `${baseURL}${relativePath}`
}

src/utils/hertz_request.ts

Axios 实例的 baseURL 在开发环境为空字符串（走 Vite 代理）；生产环境使用 VITE_API_BASE_URL：

const isDev = import.meta.env.DEV
const baseURL = isDev ? '' : (import.meta.env.VITE_API_BASE_URL || 'http://localhost:3000')

👉 结论：前端同事只需要改 .env.development 和 .env.production 里的 VITE_API_BASE_URL，其余 URL 都通过工具/代理自动生效，无需到处搜 localhost。

🚀 快速开始

# 进入工程目录
cd hertz_server_diango_ui_2

# 安装依赖
npm i

# 开发启动（默认 http://localhost:3001）
npm run dev

🔧 关键模块速览

主题与 Design System
- 入口：src/styles/index.scss、src/styles/variables.scss
- 内容：按钮 / 表格 / 弹窗 / 输入框等统一风格，含毛玻璃、hover、active、focus 细节
菜单与路由
- src/router/admin_menu.ts：单文件维护管理端菜单树 + 路由映射 + 权限标识
- 面包屑逻辑已整理：不再重复展示“首页/”，只保留当前层级链路
YOLO 模块
- ModelManagement.vue：模型上传 / 列表 / 启用、拖拽上传区
- AlertLevelManagement.vue：模型类别管理，支持单条 & 批量修改告警等级
- DetectionHistoryManagement.vue：检测历史列表、图片/视频预览
认证模块
- API：src/api/auth.ts
- 页面：src/views/Login.vue、src/views/register.vue
- 注册表单字段已与后端约定一致： username, password, confirm_password, email, phone, real_name, captcha, captcha_id

🧪 常见问题（FAQ）

需要改哪些地方才能连上新的后端 IP？
- 只改：.env.development 和 .env.production 的 VITE_API_BASE_URL
- 不需要：修改页面内的 http://localhost:xxxx，已统一收敛到工具函数
接口不走 / 返回字段对不上？
- 对比：src/api/*.ts 里定义的请求路径与 payload
- 打开浏览器 Network 看真实请求 URL、body 与响应
页面样式和设计稿不一致？
- 先看 src/styles/index.scss 是否有全局覆盖
- 再查对应 .vue 文件中的 scoped 样式是否有特殊处理

🛠️ 二次开发建议

新增管理模块
- 在 src/views/admin_page/ 下新增页面，如 FooBarManagement.vue
- 在 src/router/admin_menu.ts 中增加菜单配置（path + component + permission）
扩展接口
- 在 src/api/ 新增 xxx.ts，导出 xxxApi 对象
- 使用统一的 request 封装（hertz_request.ts），保持错误处理一致
改造主题 / 品牌色
- 修改 src/styles/variables.scss 中的主色、背景色、圆角、阴影
- 如需大改导航栏、卡片风格，优先在全局样式里做统一，而不是每页重新写

📜 NPM 脚本

{
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc -b && vite build",
    "preview": "vite preview"
  }
}

README.md Unescape Escape

通用大模型模板 · Hertz Admin + AI

✨ 特性（面向前端）