Files

T

Simon 44e77dcb0e chore(docs): docs/ 目录全面重新编号 + 重组

**重构前**（旧编号 02-11）：
- docs/02-产品需求/      → 00 产品规划/PRD
- docs/03-技术架构/      → 01-05 子目录散落
- docs/04-原型设计/      → 01-02 产品设计（HTML 原型）
- docs/05-原型设计/      → screens/
- docs/06-测试素材/      → 02-E2E / 03-功能 / 04-版本测试
- docs/07-项目管理/      → 任务说明书/日报/计划
- docs/08-安全审计/      → 审计报告
- docs/09-堡垒运维/      → toolbox / deploy
- docs/10-项目管理/      → 任务说明书（重复）
- docs/11-历史归档/      → deploy-nas-archived

**重构后**（新编号 00-07，语义化）：
- docs/00-产品开发流程与文档管理规范.md
- docs/00-版本迭代总览.md
- docs/01-产品文档/      （PRD/原型/认证/会话/AI 服务/坐席/集成）
- docs/02-技术文档/      （技术方案/架构图/重构记录/前端改造/实现配置）
- docs/03-测试文档/      （E2E/功能用例/版本报告/缺陷单）
- docs/04-运维文档/      （部署运维/运维指南）
- docs/05-运营文档/      （品牌推广/用户手册）
- docs/06-安全审计/      （审计报告）
- docs/07-项目管理/      （任务说明书/日报/计划/看板）

**净收益**：
- 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号）
- 消除 02-产品需求 与 10-项目管理 的编号重叠
- 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录）
- 把运维/安全/项目管理从 0X 散落改为 04/06/07

合计 494 文件 + 78495 行 / - 14076 行

2026-08-03 18:46:55 +08:00

9.9 KiB

Raw Blame History

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 满载跑批产出,待评审

9.9 KiB Raw Blame History