110 lines
7.0 KiB
Markdown
110 lines
7.0 KiB
Markdown
# 前端技术路线文档
|
||
|
||
## 1. 项目概述
|
||
- **框架基线**：基于 `Vue 3` + Composition API 构建的单页应用，入口由 `src/main.js` 创建并挂载 `App.vue`。
|
||
- **运行模式**：采用 `Vite` 作为开发服务器与构建工具，统一在 `config/vite.config.js` 配置，脚本通过 `npm run dev/build/preview` 调用。
|
||
- **部署目标**：面向工业 CAD 模型统一管理平台的前端界面，所有业务逻辑围绕 CAD 连接、模型查看、分析工具与日志监控展开。
|
||
|
||
## 2. 应用层次结构
|
||
### 2.1 启动流程
|
||
1. `main.js` 创建应用实例并加载全局依赖：`Pinia`、`Vue Router`、`Element Plus`。
|
||
2. 初始化认证状态 (`useAuthStore().initAuth()`)，确保刷新后可以恢复登录信息。
|
||
3. 启动 WebSocket 服务 (`websocketService.connect()`)，为后续日志与状态同步提供实时通道。
|
||
4. 挂载根组件 `App.vue`，其模板内仅渲染 `<router-view />`，由路由控制页面结构。
|
||
|
||
### 2.2 路由与页面
|
||
- 使用 `Vue Router 4`（Hash 模式）管理页面，路由定义于 `src/router/index.js`。
|
||
- 主要路由：`/login`（登录页）、`/dashboard`（主控制台），根路径重定向到仪表板。
|
||
- 全局前置守卫根据 `meta.requiresAuth` 校验登录状态，并同步浏览器标题。
|
||
|
||
### 2.3 主场景组织
|
||
- `DashboardView.vue` 作为仪表板容器，组合 `MainLayout` 布局，并通过动态组件与 `KeepAlive` 控制页面切换。
|
||
- 页面组件映射在本地 `pageComponentMap` 中，根据 `PAGE_TYPES`（`src/config/pages.js`）选择展示模块。
|
||
- 关键子组件：
|
||
- `AppHeader` 负责页面切换与信息面板控制。
|
||
- `CadSidebar` 管理各 CAD 软件连接入口。
|
||
- `InfoManagementPanel` 展示实时日志、状态信息。
|
||
- `components/pages` 目录承载具体业务页面（模型库、分析、导出、查看器等）。
|
||
|
||
## 3. 状态管理
|
||
- 统一使用 `Pinia`，入口在 `main.js` 注册。
|
||
- Store 设计遵循「只持久化状态，不处理 API 调用」原则。
|
||
|
||
### 3.1 认证状态 (`src/stores/auth.js`)
|
||
- 存储当前用户、token、加载状态与错误信息。
|
||
- 提供登录、登出、token 校验、错误清理等方法。
|
||
- 登录逻辑支持模拟异步，后续可平滑接入真实 API。
|
||
- 与本地存储联动，刷新后通过 `initAuth()` 恢复状态。
|
||
|
||
### 3.2 CAD 状态 (`src/stores/cad.js`)
|
||
- 根据 `config/cad.js` 中的 CAD 定义初始化连接状态列表。
|
||
- 维持单一连接原则：`setCADConnection` 会在连接新软件前断开其他连接。
|
||
- 暴露当前连接的软件信息、可显示 CAD 列表、项目名称等状态。
|
||
- 提供功能支持检查 (`cadSupportsFeature`) 与连接中状态更新等能力。
|
||
|
||
## 4. 配置体系
|
||
- 所有业务配置集中在 `src/config`：
|
||
- `cad.js`：CAD 软件定义、API 端点、通知、WebSocket、导出格式与默认参数；同时提供 URL 构建、功能支持判断等工具函数。
|
||
- `pages.js`：统一的页面类型常量与权限要求，供仪表板和导航模块引用。
|
||
- 其他配置文件（如 `auth`）为 Store 提供默认值、校验规则和超时设置。
|
||
|
||
## 5. 通信与服务层
|
||
### 5.1 HTTP 客户端 (`src/services/apiClient.js`)
|
||
- 基于 `fetch` 的统一封装，内置请求/响应拦截、Loading 遮罩、Element Plus 通知、操作日志同步与错误处理。
|
||
- 利用 `PostProcessManager` 组织后处理钩子：
|
||
- 成功/失败后自动弹出通知。
|
||
- 将操作日志通过 `websocketService.logOperation` 推送到后台，实现前后端日志统一。
|
||
- 提供 `get/post/put/delete` 便捷方法，默认读取 `config/cad.js` 中的请求头、超时等配置。
|
||
|
||
### 5.2 WebSocket 服务 (`src/services/websocketService.js`)
|
||
- 管理实时连接、自动重连、心跳以及后台消息解析。
|
||
- 维护软件列表、操作日志、统计信息等实时状态，并通过事件订阅模式向组件广播。
|
||
- 支持后台命令（启动/停止/重启软件、查询日志等）与操作记录上报。
|
||
- 登录用户信息会动态带入连接参数和日志上报，确保后台可追踪责任主体。
|
||
|
||
## 6. UI 与样式体系
|
||
- UI 组件库：全局注册 `Element Plus`，结合自研组件完成业务场景搭建。
|
||
- 样式策略：在 `src/assets/styles/theme.css` 定义 CSS 变量与通用样式，`App.vue` 导入后覆盖全局；组件内尽量使用作用域样式或复用变量，保持视觉一致性。
|
||
- 主题与布局：
|
||
- `layout` 目录包含主框架组件（头部、侧边、布局容器）。
|
||
- `pages` 目录按业务功能拆分子页面，保持单一职责。
|
||
- `model` 目录存放各 CAD 查看器，遵循统一的主题变量与交互规范。
|
||
|
||
## 7. 目录结构概览
|
||
```
|
||
src/
|
||
├── assets/ # 静态资源与全局样式
|
||
├── components/
|
||
│ ├── layout/ # 主布局与导航组件
|
||
│ ├── model/ # 针对 CAD 的模型查看器
|
||
│ ├── pages/ # 业务页面碎片，按 PAGE_TYPES 分类
|
||
│ └── ui/ # 通用 UI 组件（树形节点等）
|
||
├── config/ # 统一配置中心（CAD、页面、认证等）
|
||
├── router/ # 路由配置与守卫
|
||
├── services/ # HTTP、WebSocket、业务服务封装
|
||
├── stores/ # Pinia Store（认证、CAD 状态等）
|
||
├── utils/ # 工具函数与日志封装
|
||
└── views/ # 路由级页面容器（Dashboard、Login 等）
|
||
```
|
||
|
||
## 8. 数据与事件流
|
||
1. 用户通过 `CadSidebar` 发起连接请求，组件内调用相应服务（例如 `apiClient` + `config/cad.js` 构建 URL）。
|
||
2. API 返回后，组件根据结果调用 `cadStore.setCADConnection` 更新全局状态，并向父组件触发事件以切换页面或加载数据。
|
||
3. `apiClient` 拦截器自动发送 Element Plus 通知，并通过 WebSocket 记录操作日志；WebSocket 后台返回的最新状态又会驱动 `InfoManagementPanel` 更新展示。
|
||
4. 所有跨组件通信优先使用事件 (`emit`) 与 Pinia 状态，避免组件间直接耦合。
|
||
|
||
## 9. 构建与质量保障
|
||
- `package.json` 中定义脚本：
|
||
- `npm run dev`：开发模式。
|
||
- `npm run build`：生产构建。
|
||
- `npm run preview`：本地预览构建结果。
|
||
- `npm run lint`：执行 ESLint（配置位于 `config/eslint.config.js`），自动修复常见问题。
|
||
- `npm run format`：根据 `config/.prettierrc.json` 格式化 `src/` 目录。
|
||
- 推荐 Node 版本 `^20.19.0 || >=22.12.0`，确保与依赖兼容。
|
||
|
||
## 10. 扩展与约束原则
|
||
- 遵循 `CLAUDE.md` 中的严格开发准则：先确认需求，再最小化实现，禁止未授权的额外功能或样式更改。
|
||
- Store 只负责状态管理，API 调用留在组件或服务层，避免职责交叉。
|
||
- 与后台的交互需要通过 `operationContext` 提供统一的通知描述，保持日志与提示文案一致。
|
||
- 新增页面需按“配置 → 组件 → 仪表板页注册”的流程接入，保证页面切换逻辑集中管理。
|