MianyVue/docs/frontend-technical-overview.md

前端技术路线文档

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 提供统一的通知描述，保持日志与提示文案一致。
• 新增页面需按“配置 → 组件 → 仪表板页注册”的流程接入，保证页面切换逻辑集中管理。