# 4 前端状态审计报告 + 统一优化路线

**审计日期**: 2026-06-15
**审计人**: Claude
**关联**: [[阶段1-已实现盘点]] / [[Wingman设计]] / 风险跟踪表

---

## 📌 1. 4 前端总览

| 前端 | 路径 | UI 框架 | 角色 | 视图数 | dist 大小(估) | 路由前缀 |
|---|---|---|---|---|---|---|
| **admin** | `frontend-admin/` | Element Plus + Tailwind | 管理员 | 13+ | 大 | `/itadmin/` |
| **agent** | `frontend-agent/` | Element Plus | 坐席 | 2(主) | 中 | `/itagent/` |
| **h5** | `frontend-h5/` | Vant 4 | 员工 | 3 | 小 | `/itdesk/` |
| **portal** | `frontend-portal/` | Element Plus | 统一入口 | 2 | 小 | `/itportal/` |

**技术栈统一度**: 🟢 高(Vue 3 + Vite + TypeScript + Pinia + Vue Router + Axios)

---

## 📌 2. frontend-admin 管理端

### 2.1 视图清单

| 路径 | 名称 | 状态 | 备注 |
|---|---|---|---|
| `/login` | 管理员登录 | ✅ | |
| `/dashboard` | 运营总览 | ✅ | 统计卡片 |
| `/configs` | 功能开关 | ✅ | |
| `/agents` | 坐席管理 | ✅ | |
| `/roles` | 角色管理 | ✅ | |
| `/integrations` | 系统集成 | ✅ | 火绒/联软/aTrust/eHR |
| `/quick-replies` | 快速回复 | ✅ | |
| `/assignment-mode` | 分配模式 | ✅ | |
| `/flowcharts` | 流程图 | ✅ | |
| `/terminal-security` | 终端安全 | ✅ | |
| `/session-audit` | 会话审计 | ✅ | |
| `/system-logs` | 系统日志 | ✅ | |
| `/agent-performance` | 坐席绩效 | ✅ | 阶段 4 数据看板扩展 |
| `/monitor` | 监控 | ✅ | |

### 2.2 状态评估

- 🟢 **完成度高**:13+ 视图,功能齐全
- 🟢 **使用 Element Plus + Tailwind**:UI 统一
- 🟡 **缺失**:单元测试(Vitest 未配)
- 🟡 **缺失**:E2E 测试(Playwright 未配)
- 🟡 **缺失**:i18n(国际化)

### 2.3 已知问题

| # | 问题 | 严重度 | 解决 |
|---|---|---|---|
| A-1 | `/agent-performance` 是阶段 4 才有数据,目前空 | 🟡 | 阶段 4 实现 |
| A-2 | `/system-logs` 没用虚拟滚动,日志多时卡 | 🟡 | vue-virtual-scroller |
| A-3 | 角色管理权限粒度粗(没 RBAC) | 🟠 | 阶段 4 加 RBAC |
| A-4 | 集成页只展示无配置 | 🟡 | 加配置表单 |

---

## 📌 3. frontend-agent 坐席端

### 3.1 视图清单

| 路径 | 名称 | 状态 | 备注 |
|---|---|---|---|
| `/login` | 坐席登录 | ✅ | 用户ID + 姓名 + password |
| `/workspace` | 坐席工作台 | ✅ | 三栏(会话列表 / 对话 / 助手面板) |

### 3.2 组件清单(Workspace 包含)

| 组件 | 路径 | 状态 |
|---|---|---|
| ConversationList | `components/conversation/` | ✅ 6 分区 |
| MessageBubble | `components/chat/` | ✅ 4 种气泡 |
| ReplyBox | `components/chat/` | ✅ 输入框 + 草稿 |
| AiAssistantPanel | `components/assistant/` | ✅ AI 助手面板 |
| AiSuggestReply | `components/assistant/` | ✅ AI 草稿 |
| AiDraftBubble | `components/chat/` | ✅ AI 草稿气泡 |
| AiRecommendInline | `components/chat/` | ✅ AI 推荐内联 |
| OperationSteps | `components/assistant/` | ✅ 操作步骤 |
| RiskAlert | `components/assistant/` | ✅ 风险提示 |
| UserInfoPanel | `components/assistant/` | ✅ 用户信息 |
| QuickReplyPanel | `components/assistant/` | ✅ 快速回复 |
| TroubleshootBar | `components/chat/` | ✅ 排查栏 |
| TroubleshootProgress | (在 H5) | ✅ 员工端 |
| TroubleshootFlow | (在 H5) | ✅ 员工端 |
| FlowchartNode | `components/chat/` | ✅ 流程图节点 |
| ScreenshotEditor | `components/chat/` | ✅ 截图编辑 |
| InviteDialog | `components/conversation/` | ✅ 邀请弹窗 |
| ParticipantBar | `components/conversation/` | ✅ 参与者栏 |
| TodoPanel | `components/conversation/` | ✅ Todo 面板 |
| TaskDetailView | `components/chat/` | ✅ 任务详情 |
| TicketDetail | `components/chat/task/` | ✅ 工单详情 |
| DeviceDetail | `components/chat/task/` | ✅ 设备详情 |
| ApprovalDetail | `components/chat/task/` | ✅ 审批详情 |

### 3.3 Composables

- `useWebSocket.ts` (在别处)
- `useTheme.ts` ✅
- `useKeyboardShortcuts.ts` ✅
- `useScreenCapture.ts` ✅

### 3.4 状态评估

- 🟢 **完成度极高**:23 组件 + 4 composables
- 🟢 **三栏工作台**:会话 + 对话 + 助手,布局清晰
- 🟢 **AI 集成**:AiSuggestReply / AiDraftBubble / AiRecommendInline 三个 AI 组件
- 🟡 **缺失**:Vitest 单元测试
- 🟡 **缺失**:操作步骤/风险提示数据源(等后端字段)
- 🟡 **缺失**:坐席绩效统计(阶段 4)

### 3.5 已知问题

| # | 问题 | 严重度 | 解决 |
|---|---|---|---|
| A-5 | `useWebSocket.ts` token 用 subprotocol(P0 修复已加) | 🟢 | 已修 |
| A-6 | ReplyBox 大量重渲染(200+ 消息卡) | 🟡 | 虚拟列表 |
| A-7 | ScreenshotEditor 依赖 `html2canvas-pro` 体积大 | 🟡 | 改用 `dom-to-image` |
| A-8 | mock 数据仍在用(`mock/data.ts`) | 🟡 | 删,接真实 API |

---

## 📌 4. frontend-h5 员工端

### 4.1 视图清单

| 路径 | 名称 | 状态 | 备注 |
|---|---|---|---|
| `/` | ChatView(聊天) | ✅ | 默认首页 |
| `/login` | 降级登录 | ✅ | 本地开发用 |
| `/wework-only` | 企微拦截 | ✅ | 非企微环境显示 |

### 4.2 组件清单

| 组件 | 状态 |
|---|---|
| ChatPanel | ✅ |
| ShakeButton(敲桌子) | ✅ 7 种 SVG |
| TroubleshootProgress | ✅ |
| TroubleshootFlow | ✅ |
| ScreenshotEditor | ✅ |
| ParticipantList | ✅ |
| AiHelperPanel | ✅ |
| ApprovalLinks | ✅ |
| SoftwareDownloads | ✅ |
| RightPanel | ✅ |
| ComingSoon | ✅ 占位 |

### 4.3 状态评估

- 🟢 **完成度高**:11 组件
- 🟢 **Vant 4 移动端 UI**:适配好
- 🟡 **缺失**:Vitest 单元测试
- 🟡 **缺失**:摇人按钮(阶段 2 加)
- 🟡 **缺失**:满意度评价(阶段 2 加)
- 🟡 **缺失**:AI 回复展示(等 Dify 集成)

### 4.4 已知问题

| # | 问题 | 严重度 | 解决 |
|---|---|---|---|
| A-9 | OAuth2 callback 路径二次校验缺失(风险跟踪表 H-9 衍生) | 🟠 | 加 state 参数 |
| A-10 | H5 不支持长连接(用轮询降级) | 🟡 | 优先 WS |
| A-11 | Vant 4 vs Vant 3 API 差异,部分组件可能错版 | 🟡 | 走通测试 |

---

## 📌 5. frontend-portal 统一入口

### 5.1 视图清单

| 路径 | 名称 | 状态 | 备注 |
|---|---|---|---|
| `/select` | 角色选择 | ✅ | 跳 admin / agent |
| `/loading` | 加载中 | ✅ | 中转页 |

### 5.2 状态评估

- 🟢 **简单但有效**:2 视图
- 🟢 **集成 OAuth2**(走 admin/agent 的 token 传递)
- 🟡 **缺失**:跳过 Portal 直跳有问题(必须先 select)

### 5.3 已知问题

| # | 问题 | 严重度 | 解决 |
|---|---|---|---|
| A-12 | token 传递用 URL ?token= 风险(同 WS) | 🟠 | 改 sessionStorage |
| A-13 | `/loading` 没超时,卡死无 fallback | 🟡 | 10s 后回 `/select` |

---

## 📌 6. 跨前端共性问题

### 6.1 主题

- 🟢 **统一**: 都有 `useTheme.ts`
- 🟡 主题切换没持久化(刷新丢)
- 🟡 没暗色模式

### 6.2 错误处理

- 🟡 4 前端**都没全局错误边界**(try-catch 不一致)
- 🟡 4 前端**错误码体系不统一**(各端自行处理)
- 🟢 4 前端**都接 axios + 拦截器**

### 6.3 状态管理

- 🟢 **统一 Pinia**
- 🟡 stores 命名不一致(有些用 `useXxxStore`,有些 `useXxx`)

### 6.4 构建产物

| 前端 | dist 大小(估) | Gzip 后 | 首屏 |
|---|---|---|---|
| admin | 2-3 MB | ~500KB | 慢 |
| agent | 1.5-2 MB | ~400KB | 中 |
| h5 | 1-1.5 MB | ~300KB | 快 |
| portal | 200KB | ~50KB | 极快 |

**优化空间**:
- Element Plus 按需引入(全量 vs tree-shaking)
- 拆 vendor chunk
- 图片用 WebP

### 6.5 测试覆盖

| 前端 | Vitest | Playwright | E2E |
|---|---|---|---|
| admin | ❌ 0% | ❌ 0% | ❌ 0% |
| agent | ❌ 0% | ❌ 0% | ❌ 0% |
| h5 | ❌ 0% | ❌ 0% | ❌ 0% |
| portal | ❌ 0% | ❌ 0% | ❌ 0% |

**全是 0%** —— 严重问题,workbuddy W-3 加 pytest 后端测试,前端 Vitest 也要加。

---

## 📌 7. 统一优化路线

### 7.1 P1 优先(2 周)

| # | 任务 | 影响 |
|---|---|---|
| U-1 | 4 前端加 Vitest(基础测试框架) | 提升质量 |
| U-2 | 全局错误边界 + 错误码体系 | 统一错误处理 |
| U-3 | Pinia store 命名规范 | 一致性 |
| U-4 | 主题持久化(localStorage) | UX 改进 |
| U-5 | 删 agent `mock/data.ts`,接真实 API | 真实数据 |

### 7.2 P2 重要(4 周)

| # | 任务 | 影响 |
|---|---|---|
| U-6 | admin `/system-logs` 虚拟滚动 | 性能 |
| U-7 | agent ReplyBox 消息虚拟化 | 性能 |
| U-8 | 4 前端加 ESLint + Prettier 一致 | 代码质量 |
| U-9 | agent ScreenshotEditor 换库 | 体积 |
| U-10 | h5 OAuth2 state 校验 | 安全 |
| U-11 | portal token 走 sessionStorage | 安全 |

### 7.3 P3 体验(2 月)

| # | 任务 | 影响 |
|---|---|---|
| U-12 | 暗色模式(全 4 前端) | UX |
| U-13 | i18n(中/英) | 国际化 |
| U-14 | PWA(offline 支持) | 体验 |
| U-15 | Storybook 组件库 | 开发效率 |
| U-16 | E2E 测试(Playwright) | 回归 |

### 7.4 性能优化(持续)

- Element Plus 按需引入
- 图片 WebP + lazy load
- Code Splitting 拆 vendor chunk
- HTTP/2 + Brotli
- 路由级代码分割(已有)

---

## 📌 8. 实施路径

### 8.1 阶段 1(本周)

- U-1 Vitest 基础(每个前端 1 模板测试)
- U-5 删 mock data

### 8.2 阶段 2(下周)

- U-2 全局错误边界 + 错误码
- U-3 Pinia 命名规范
- U-4 主题持久化

### 8.3 阶段 3(下月)

- U-6 / U-7 性能优化
- U-8 ESLint
- U-10 / U-11 安全加固

### 8.4 阶段 4(季度)

- U-12 暗色模式
- U-13 i18n
- U-14 PWA
- U-15 Storybook
- U-16 E2E

---

## 📌 9. 风险与依赖

| 风险 | 等级 | 缓解 |
|---|---|---|
| 测试覆盖 0% → 重构风险 | 🟠 高 | 强制 Vitest 模板,新代码必带测试 |
| 4 前端重复代码 | 🟡 中 | 抽公共组件库(Stage 4) |
| 性能问题(Response 卡) | 🟡 中 | 虚拟列表 + 分页 |
| 主题/暗色模式分歧 | 🟢 低 | 统一 theme store |

---

## 📌 10. 关联文档

- [[阶段1-已实现盘点]] §2.1/2.2/2.3
- [[Wingman设计]] §4 前端设计
- [[风险跟踪表]] H-9 / M-1 等
- [[外部系统集成]] - portal/agent 集成

---

*本审计是 2026-06-15 Claude 满载跑批产出,待评审*