chore: initial baseline with P0-safety .gitignore
This commit is contained in:
Simon
@@ -0,0 +1,914 @@
|
||||
# IT智能服务台 · 坐席工作台 v5.3 增量架构设计
|
||||
|
||||
> **版本**: v5.3-incremental
|
||||
> **日期**: 2026-06-06
|
||||
> **作者**: 高见远（Gao）· 架构师
|
||||
> **状态**: 待评审
|
||||
> **基线**: 现有坐席工作台 v5.2 三栏布局
|
||||
|
||||
---
|
||||
|
||||
## 1. 实现方案与框架选型
|
||||
|
||||
### 1.1 核心技术挑战
|
||||
|
||||
| # | 挑战 | 难度 | 应对策略 |
|
||||
|---|------|------|---------|
|
||||
| 1 | CSS 变量驱动双主题系统，需确保所有现有硬编码色值迁移完成 | ⭐⭐ | 分层替换：先定义变量体系 → 替换 `global.css` → 逐组件迁移 inline style |
|
||||
| 2 | 右栏 5-Tab → 上下两区重构，需保持快速回复键盘导航的焦点管理 | ⭐⭐⭐ | 使用 `useKeyboardShortcuts` composable 统一管理快捷键，避免各组件各自监听 |
|
||||
| 3 | 中栏视图切换（聊天↔任务详情），需保持 WebSocket 连接和 Store 状态不丢失 | ⭐⭐ | 纯前端 `v-if`/`v-show` 切换，不销毁 Store；用 `workspaceView` 状态控制 |
|
||||
| 4 | 排查步骤决策树 JSON 渲染，需支持判断节点 + 分支缩进 + 动画展开 | ⭐⭐⭐ | 递归组件 `FlowchartNode.vue`，`max-height` 过渡 + `overflow: hidden` |
|
||||
| 5 | 会话列表 6 区 → 3 段折叠，数据映射需重新定义 computed 属性 | ⭐⭐ | 新增 `myConversations`/`colleagueConversations`/`historyConversations` 三个 computed |
|
||||
|
||||
### 1.2 框架选型（沿用 + 增量）
|
||||
|
||||
| 层 | 框架/库 | 版本 | 说明 |
|
||||
|----|--------|------|------|
|
||||
| 前端框架 | Vue 3 | ^3.4 | Composition API + `<script setup>` |
|
||||
| UI 组件库 | Element Plus | ^2.7 | 沿用，少量自定义样式覆盖 |
|
||||
| 状态管理 | Pinia | ^2.1 | 新增 `useTodoStore`、`useThemeStore` |
|
||||
| 构建工具 | Vite | ^5.x | 沿用 |
|
||||
| CSS 方案 | CSS Variables | 原生 | 双主题核心，不引入额外 CSS-in-JS |
|
||||
| 后端框架 | FastAPI | ^0.111 | 沿用 |
|
||||
| ORM | SQLAlchemy 2.0 | ^2.0 | 异步模式，新增模型 |
|
||||
| 数据验证 | Pydantic v2 | ^2.7 | 沿用，新增 Schema |
|
||||
|
||||
> **决策**：不引入新 UI 框架或 CSS-in-JS 方案。双主题完全通过 CSS 变量 + `data-theme` 属性切换实现，与 Element Plus 主题变量共存。
|
||||
|
||||
### 1.3 架构模式
|
||||
|
||||
沿用现有 **MVVM + Composable** 模式：
|
||||
|
||||
```
|
||||
View (Vue SFC)
|
||||
↕ 双向绑定 / 事件
|
||||
ViewModel (Pinia Store + Composables)
|
||||
↕ API 调用
|
||||
Model (TypeScript 接口 ↔ Pydantic Schema ↔ SQLAlchemy Model)
|
||||
```
|
||||
|
||||
新增 Composable 层：
|
||||
- `useTheme.ts` — 主题切换 + 持久化
|
||||
- `useKeyboardShortcuts.ts` — 全局快捷键注册/卸载
|
||||
|
||||
---
|
||||
|
||||
## 2. 文件列表及相对路径
|
||||
|
||||
> 变更类型标记：🆕新增 / ✏️修改 / 🔄重写 / 🗑️废弃
|
||||
|
||||
### 2.1 前端文件
|
||||
|
||||
| # | 相对路径（基于 `frontend-agent/src/`） | 变更 | 说明 |
|
||||
|---|--------------------------------------|------|------|
|
||||
| 1 | `styles/global.css` | ✏️ | 新增深色主题 CSS 变量块 + 双主题色值体系；替换硬编码色为 `var()` |
|
||||
| 2 | `composables/useTheme.ts` | 🆕 | 主题切换 composable（读取/写入 localStorage + 设置 `data-theme`） |
|
||||
| 3 | `composables/useKeyboardShortcuts.ts` | 🆕 | 全局快捷键统一管理（Ctrl+1/2/3, Alt+1~5, ↑↓, Enter, /） |
|
||||
| 4 | `stores/theme.ts` | 🆕 | 主题 Pinia Store（currentTheme 响应式 + toggle 方法） |
|
||||
| 5 | `stores/todo.ts` | 🆕 | 待办事项 Pinia Store（todoList + fetch/更新状态） |
|
||||
| 6 | `api/todo.ts` | 🆕 | 待办事项 API（GET 列表/详情, PUT 状态） |
|
||||
| 7 | `api/troubleshooting.ts` | 🆕 | 排查模板 API（GET 列表/详情） |
|
||||
| 8 | `api/conversation.ts` | ✏️ | Conversation 接口新增 `impact_scope`/`is_blocking`/`emotion_state` 字段 |
|
||||
| 9 | `views/Workspace.vue` | ✏️ | 顶部栏抽离为 `TopBar.vue`；新增 `workspaceView` 状态控制视图切换 |
|
||||
| 10 | `components/layout/TopBar.vue` | 🆕 | 独立顶栏组件（系统名称 FE-09 + 主题切换 + 坐席状态 + 应急模式） |
|
||||
| 11 | `components/conversation/ConversationList.vue` | 🔄 | 三段折叠 + 搜索标签 + 底部待办面板挂载点 |
|
||||
| 12 | `components/conversation/ConversationItem.vue` | ✏️ | 新增优先级图标（⛔👥⭐🔁）；移除旧标签部分 |
|
||||
| 13 | `components/conversation/TodoPanel.vue` | 🆕 | 左栏底部待办事项面板 |
|
||||
| 14 | `components/chat/ChatArea.vue` | ✏️ | 顶部替换为 `UserInfoBar`；底部挂载 `TroubleshootBar`；新增视图切换逻辑 |
|
||||
| 15 | `components/chat/UserInfoBar.vue` | 🆕 | 用户信息栏（chips + 展开详情 6 卡片） |
|
||||
| 16 | `components/chat/ItLevelBadge.vue` | 🆕 | IT 等级徽标组件（7 级段位 + 渐变 + 王者发光） |
|
||||
| 17 | `components/chat/AiRecommendInline.vue` | 🆕 | 聊天区内 AI 推荐回复（Ctrl+1/2/3） |
|
||||
| 18 | `components/chat/TroubleshootBar.vue` | 🆕 | 排查步骤栏（路径视图 + 可展开流程图） |
|
||||
| 19 | `components/chat/FlowchartNode.vue` | 🆕 | 决策树递归渲染节点 |
|
||||
| 20 | `components/chat/TaskDetailView.vue` | 🆕 | 任务详情视图（工单/审批/设备三种子视图） |
|
||||
| 21 | `components/assistant/AiAssistantPanel.vue` | 🔄 | 完全重写：移除 5 Tab，改为上下两区 |
|
||||
| 22 | `components/assistant/AiSuggestReply.vue` | ✏️ | 适配右栏上方 AI 推荐区样式；增加置信度 + 快捷键提示 |
|
||||
| 23 | `components/assistant/QuickReplyPanel.vue` | 🔄 | 重写：搜索置顶 + Alt 分类 + ↑↓ 导航 + Enter 确认 + 键盘指南 |
|
||||
| 24 | `components/assistant/RiskAlert.vue` | 🗑️ | 废弃，不再引用 |
|
||||
| 25 | `components/assistant/UserInfoPanel.vue` | 🗑️ | 废弃，功能并入 `UserInfoBar.vue` |
|
||||
|
||||
### 2.2 后端文件
|
||||
|
||||
| # | 相对路径（基于 `backend/app/`） | 变更 | 说明 |
|
||||
|---|-------------------------------|------|------|
|
||||
| 1 | `models/employee.py` | ✏️ | 新增 `it_level`/`it_level_source`/`notes` 字段 |
|
||||
| 2 | `models/conversation.py` | ✏️ | 新增 `impact_scope`/`is_blocking`/`emotion_state` 字段 |
|
||||
| 3 | `models/todo_item.py` | 🆕 | TodoItem 模型（id/type/title/priority/description/status/...） |
|
||||
| 4 | `models/troubleshooting_template.py` | 🆕 | TroubleshootingTemplate 模型（id/name/category/path_steps/flowchart/...） |
|
||||
| 5 | `schemas/employee.py` | ✏️ | EmployeeResponse 新增字段；新增 `ItLevelUpdateRequest` Schema |
|
||||
| 6 | `schemas/conversation.py` | ✏️ | ConversationResponse/ConversationTags 新增字段 |
|
||||
| 7 | `schemas/todo_item.py` | 🆕 | TodoItem CRUD Schema |
|
||||
| 8 | `schemas/troubleshooting_template.py` | 🆕 | TroubleshootingTemplate CRUD Schema |
|
||||
| 9 | `api/employees.py` | ✏️ | 新增 `PUT /api/employees/{id}/it-level` 端点 |
|
||||
| 10 | `api/conversations.py` | ✏️ | 响应包含新字段（无需新端点） |
|
||||
| 11 | `api/todo_items.py` | 🆕 | GET 列表/详情 + PUT 状态更新 |
|
||||
| 12 | `api/troubleshooting_templates.py` | 🆕 | GET 列表/详情 + POST/PUT/DELETE（管理员） |
|
||||
| 13 | `api/router.py` | ✏️ | 注册新路由 |
|
||||
| 14 | `models/__init__.py` | ✏️ | 导入新模型（确保 SQLite 自动建表） |
|
||||
|
||||
### 2.3 文档与配置文件
|
||||
|
||||
| # | 相对路径 | 变更 | 说明 |
|
||||
|---|---------|------|------|
|
||||
| 1 | `docs/ARCHITECTURE-v53-incremental.md` | 🆕 | 本文档 |
|
||||
| 2 | `docs/sequence-diagram.mermaid` | 🆕 | 时序图 |
|
||||
| 3 | `docs/class-diagram.mermaid` | 🆕 | 类图 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 数据结构与接口
|
||||
|
||||
### 3.1 类图
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
direction TB
|
||||
|
||||
class Employee {
|
||||
+str id
|
||||
+str corp_id
|
||||
+str employee_id
|
||||
+str name
|
||||
+str department
|
||||
+str position
|
||||
+str mobile
|
||||
+str email
|
||||
+str avatar
|
||||
+int status
|
||||
+str it_level ★NEW
|
||||
+str it_level_source ★NEW
|
||||
+dict notes ★NEW
|
||||
+datetime last_login_at
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
|
||||
class Conversation {
|
||||
+str id
|
||||
+str corp_id
|
||||
+str employee_id
|
||||
+str employee_name
|
||||
+str department
|
||||
+str status
|
||||
+bool is_vip
|
||||
+bool is_pinned
|
||||
+bool is_todo
|
||||
+int urgency_score
|
||||
+dict tags
|
||||
+str assigned_agent_id
|
||||
+list collaborating_agent_ids
|
||||
+int impact_scope ★NEW
|
||||
+bool is_blocking ★NEW
|
||||
+str emotion_state ★NEW
|
||||
+datetime last_message_at
|
||||
+str last_message_summary
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
|
||||
class TodoItem {
|
||||
+str id
|
||||
+str type
|
||||
+str title
|
||||
+str priority
|
||||
+dict description
|
||||
+str status
|
||||
+str assigned_agent_id
|
||||
+str corp_id
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
|
||||
class TroubleshootingTemplate {
|
||||
+str id
|
||||
+str name
|
||||
+str category
|
||||
+list path_steps
|
||||
+dict flowchart
|
||||
+bool is_active
|
||||
+datetime created_at
|
||||
+datetime updated_at
|
||||
}
|
||||
|
||||
Employee "1" --> "*" Conversation : has
|
||||
Conversation "1" --> "*" TodoItem : may generate
|
||||
TroubleshootingTemplate "1" --> "0..1" Conversation : applied to
|
||||
|
||||
note for Employee "it_level: bronze|silver|gold|platinum|diamond|star|king\nit_level_source: system|manual"
|
||||
note for Conversation "impact_scope: 受影响人数\nis_blocking: 是否阻断性\nemotion_state: normal|anxious|angry|urgent"
|
||||
note for TodoItem "type: ticket|approval|device\npriority: urgent|high|normal\nstatus: pending|processing|resolved"
|
||||
note for TroubleshootingTemplate "category: vpn|email|system|account\npath_steps: [{label, status}]\nflowchart: 递归树结构"
|
||||
```
|
||||
|
||||
### 3.2 前端 TypeScript 接口新增
|
||||
|
||||
```typescript
|
||||
// ---- api/conversation.ts 新增字段 ----
|
||||
export interface Conversation {
|
||||
// ... 现有字段 ...
|
||||
impact_scope: number // ★NEW 影响范围（受影响人数）
|
||||
is_blocking: boolean // ★NEW 阻断性标记
|
||||
emotion_state: string // ★NEW 情绪状态: normal/anxious/angry/urgent
|
||||
}
|
||||
|
||||
// ---- api/todo.ts ----
|
||||
export interface TodoItem {
|
||||
id: string
|
||||
type: 'ticket' | 'approval' | 'device'
|
||||
title: string
|
||||
priority: 'urgent' | 'high' | 'normal'
|
||||
description: Record<string, any>
|
||||
status: 'pending' | 'processing' | 'resolved'
|
||||
assigned_agent_id: string | null
|
||||
corp_id: string
|
||||
created_at: string
|
||||
updated_at: string
|
||||
}
|
||||
|
||||
// ---- api/troubleshooting.ts ----
|
||||
export interface PathStep {
|
||||
label: string
|
||||
status: 'done' | 'current' | 'pending'
|
||||
}
|
||||
|
||||
export interface FlowchartNode {
|
||||
id: string
|
||||
type: 'step' | 'decision'
|
||||
label: string
|
||||
status?: 'done' | 'current' | 'pending'
|
||||
children?: FlowchartNode[]
|
||||
yes_branch?: FlowchartNode
|
||||
no_branch?: FlowchartNode
|
||||
}
|
||||
|
||||
export interface TroubleshootingTemplate {
|
||||
id: string
|
||||
name: string
|
||||
category: 'vpn' | 'email' | 'system' | 'account'
|
||||
path_steps: PathStep[]
|
||||
flowchart: FlowchartNode
|
||||
is_active: boolean
|
||||
created_at: string
|
||||
updated_at: string
|
||||
}
|
||||
|
||||
// ---- stores/theme.ts ----
|
||||
export type ThemeMode = 'light' | 'dark'
|
||||
|
||||
// ---- stores/todo.ts ----
|
||||
export interface TodoState {
|
||||
todoList: TodoItem[]
|
||||
loading: boolean
|
||||
}
|
||||
```
|
||||
|
||||
### 3.3 后端 Pydantic Schema 新增
|
||||
|
||||
```python
|
||||
# ---- schemas/employee.py 新增 ----
|
||||
class ItLevelUpdateRequest(BaseModel):
|
||||
it_level: str = Field(..., pattern="^(bronze|silver|gold|platinum|diamond|star|king)$")
|
||||
source: str = Field(default="manual", pattern="^(system|manual)$")
|
||||
|
||||
# ---- schemas/todo_item.py ----
|
||||
class TodoItemResponse(BaseModel):
|
||||
id: str
|
||||
type: str # ticket/approval/device
|
||||
title: str
|
||||
priority: str # urgent/high/normal
|
||||
description: Dict[str, Any]
|
||||
status: str # pending/processing/resolved
|
||||
assigned_agent_id: Optional[str] = None
|
||||
corp_id: str
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
model_config = {"from_attributes": True}
|
||||
|
||||
class TodoStatusUpdateRequest(BaseModel):
|
||||
status: str = Field(..., pattern="^(pending|processing|resolved)$")
|
||||
|
||||
# ---- schemas/troubleshooting_template.py ----
|
||||
class TroubleshootingTemplateResponse(BaseModel):
|
||||
id: str
|
||||
name: str
|
||||
category: str
|
||||
path_steps: List[Dict[str, Any]]
|
||||
flowchart: Dict[str, Any]
|
||||
is_active: bool
|
||||
created_at: datetime
|
||||
updated_at: datetime
|
||||
model_config = {"from_attributes": True}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 程序调用流程
|
||||
|
||||
### 4.1 主题切换流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 坐席
|
||||
participant TB as TopBar.vue
|
||||
participant TS as useThemeStore
|
||||
participant UT as useTheme.ts
|
||||
participant DOM as document.documentElement
|
||||
participant LS as localStorage
|
||||
|
||||
U->>TB: 点击 ☀️/🌙 切换开关
|
||||
TB->>TS: toggleTheme()
|
||||
TS->>TS: currentTheme = currentTheme === 'light' ? 'dark' : 'light'
|
||||
TS->>UT: applyTheme(currentTheme)
|
||||
UT->>DOM: setAttribute('data-theme', theme)
|
||||
UT->>LS: setItem('theme', theme)
|
||||
DOM-->>DOM: CSS 变量自动切换（`:root` / `[data-theme="dark"]`）
|
||||
DOM-->>U: 300ms 过渡动画，界面变色
|
||||
|
||||
Note over U,LS: 页面加载时
|
||||
U->>UT: 首次进入页面
|
||||
UT->>LS: getItem('theme')
|
||||
LS-->>UT: 'dark' | 'light' | null
|
||||
UT->>DOM: setAttribute('data-theme', theme || 'light')
|
||||
```
|
||||
|
||||
### 4.2 待办事项点击 → 中间栏视图切换
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 坐席
|
||||
participant TP as TodoPanel.vue
|
||||
participant TDS as useTodoStore
|
||||
participant WS as Workspace.vue
|
||||
participant TDV as TaskDetailView.vue
|
||||
|
||||
U->>TP: 点击待办条目（type=ticket）
|
||||
TP->>TDS: selectTodoItem(item)
|
||||
TDS->>TDS: currentTodoItem = item
|
||||
TDS->>WS: conversationStore.workspaceView = 'task'
|
||||
WS->>WS: v-if 判断 workspaceView
|
||||
WS->>TDV: 渲染 TaskDetailView(type='ticket')
|
||||
TDV->>TDV: 根据 type 渲染对应子视图
|
||||
|
||||
Note over U,TDV: 返回聊天视图
|
||||
U->>TDV: 点击 "← 返回会话"
|
||||
TDV->>WS: conversationStore.workspaceView = 'chat'
|
||||
WS->>WS: 切回 ChatArea 渲染
|
||||
```
|
||||
|
||||
### 4.3 排查步骤展开流程
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 坐席
|
||||
participant TSB as TroubleshootBar.vue
|
||||
participant TS as troubleshooting API
|
||||
participant FN as FlowchartNode.vue
|
||||
|
||||
Note over TSB: 默认显示路径方块（横向滚动）
|
||||
TSB->>TS: GET /api/troubleshooting-templates?category=vpn
|
||||
TS-->>TSB: 返回模板列表
|
||||
TSB->>TSB: 渲染 path_steps 横向方块
|
||||
|
||||
U->>TSB: 点击 "▶ 展开全流程图"
|
||||
TSB->>TSB: expanded = true
|
||||
TSB->>FN: 递归渲染 flowchart 节点
|
||||
FN->>FN: type='step' → 渲染步骤节点
|
||||
FN->>FN: type='decision' → 渲染判断节点(❓黄底)
|
||||
FN->>FN: 递归渲染 yes_branch / no_branch
|
||||
|
||||
Note over TSB: max-height 过渡 0.35s 展开
|
||||
```
|
||||
|
||||
### 4.4 AI 推荐内联回复填入
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 坐席
|
||||
participant CA as ChatArea.vue
|
||||
participant ARI as AiRecommendInline.vue
|
||||
participant RB as ReplyBox.vue
|
||||
participant CS as conversationStore
|
||||
|
||||
CA->>ARI: 坐席未回复 + 有用户消息 → 显示
|
||||
ARI->>ARI: 渲染 1-3 条 AI 推荐卡片
|
||||
|
||||
alt 快捷键 Ctrl+1
|
||||
U->>ARI: Ctrl+1 按下
|
||||
ARI->>CS: pendingReplyText = recommendations[0].content
|
||||
CS-->>RB: watch pendingReplyText → 填入输入框并聚焦
|
||||
else 点击卡片
|
||||
U->>ARI: 点击第 N 张卡片
|
||||
ARI->>CS: pendingReplyText = recommendations[N].content
|
||||
CS-->>RB: 填入输入框并聚焦
|
||||
end
|
||||
|
||||
U->>RB: 发送回复
|
||||
RB->>ARI: 坐席已回复 → 自动隐藏
|
||||
```
|
||||
|
||||
### 4.5 右栏快速回复键盘导航
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant U as 坐席
|
||||
participant KS as useKeyboardShortcuts
|
||||
participant QRP as QuickReplyPanel.vue
|
||||
participant CS as conversationStore
|
||||
|
||||
Note over KS: 全局注册（仅在输入框未聚焦时生效）
|
||||
|
||||
alt Alt+1 切换分类
|
||||
U->>KS: Alt+1 按下
|
||||
KS->>QRP: activeCategory = categories[0]
|
||||
QRP->>QRP: 重新渲染当前分类回复列表
|
||||
end
|
||||
|
||||
alt ↑↓ 导航条目
|
||||
U->>KS: ↓ 按下
|
||||
KS->>QRP: selectedIndex++
|
||||
QRP->>QRP: 高亮下一条回复
|
||||
end
|
||||
|
||||
alt Enter 确认填入
|
||||
U->>KS: Enter 按下
|
||||
KS->>QRP: 使用选中条目
|
||||
QRP->>CS: pendingReplyText = selected.content
|
||||
CS-->>QRP: ReplyBox 填入
|
||||
end
|
||||
|
||||
alt / 聚焦搜索
|
||||
U->>KS: / 按下
|
||||
KS->>QRP: focusSearchInput()
|
||||
end
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 任务列表
|
||||
|
||||
### 5.1 所需依赖包
|
||||
|
||||
```yaml
|
||||
# 前端（npm）— 无新增包
|
||||
# CSS 变量 + 原生 DOM API 实现主题，无需额外依赖
|
||||
|
||||
# 后端（pip）— 无新增包
|
||||
# SQLAlchemy 2.0 / Pydantic v2 / FastAPI 已包含所需功能
|
||||
|
||||
# 开发依赖（可选）
|
||||
# - @vue/test-utils: 单元测试（如需）
|
||||
```
|
||||
|
||||
> **说明**：本次增量无需新增任何 npm/pip 依赖。主题系统使用原生 CSS 变量，快捷键使用原生 `addEventListener`，决策树渲染使用 Vue 递归组件。
|
||||
|
||||
### 5.2 任务分解
|
||||
|
||||
---
|
||||
|
||||
#### T01: 项目基础设施 — 主题系统 + 后端模型扩展 + 入口改造
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **优先级** | P0 |
|
||||
| **依赖** | 无 |
|
||||
| **预估文件数** | ~14 |
|
||||
| **关键变更点** | |
|
||||
|
||||
**前端文件**:
|
||||
- `styles/global.css` — 新增深色主题 CSS 变量块，替换硬编码色为 `var(--bg-primary)` 等
|
||||
- `composables/useTheme.ts` — 主题切换逻辑
|
||||
- `stores/theme.ts` — 主题 Pinia Store
|
||||
- `views/Workspace.vue` — 应用 `data-theme`，移除顶部栏到 TopBar
|
||||
- `components/layout/TopBar.vue` — 新建顶栏（系统名称 + 主题切换 + 坐席状态 + 应急模式）
|
||||
|
||||
**后端文件**:
|
||||
- `models/employee.py` — 新增 `it_level`/`it_level_source`/`notes`
|
||||
- `models/conversation.py` — 新增 `impact_scope`/`is_blocking`/`emotion_state`
|
||||
- `models/todo_item.py` — 新建 TodoItem 模型
|
||||
- `models/troubleshooting_template.py` — 新建 TroubleshootingTemplate 模型
|
||||
- `models/__init__.py` — 导入新模型
|
||||
- `schemas/employee.py` — 新增 `ItLevelUpdateRequest`
|
||||
- `schemas/conversation.py` — ConversationResponse 新增字段
|
||||
- `schemas/todo_item.py` — 新建
|
||||
- `schemas/troubleshooting_template.py` — 新建
|
||||
|
||||
**验收标准**:
|
||||
1. `document.documentElement.setAttribute('data-theme', 'dark')` 后全局色值切换
|
||||
2. 刷新页面后主题持久化
|
||||
3. 后端新增字段在 API 响应中返回
|
||||
4. SQLite 自动建表包含 `todo_items` 和 `troubleshooting_templates` 表
|
||||
|
||||
---
|
||||
|
||||
#### T02: 左栏改造 — 三段折叠 + 优先级图标 + 待办面板
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **优先级** | P0 |
|
||||
| **依赖** | T01 |
|
||||
| **预估文件数** | ~7 |
|
||||
| **关键变更点** | |
|
||||
|
||||
**前端文件**:
|
||||
- `components/conversation/ConversationList.vue` — 重构为 3 段折叠 + 搜索标签
|
||||
- `components/conversation/ConversationItem.vue` — 新增优先级图标渲染
|
||||
- `components/conversation/TodoPanel.vue` — 新建待办事项面板
|
||||
- `stores/todo.ts` — 新建待办 Pinia Store
|
||||
- `api/todo.ts` — 新建待办 API
|
||||
- `api/conversation.ts` — Conversation 接口新增 `impact_scope`/`is_blocking`/`emotion_state`
|
||||
|
||||
**后端文件**:
|
||||
- `api/todo_items.py` — 新建待办 CRUD API（含 Mock 数据）
|
||||
- `api/router.py` — 注册待办路由
|
||||
|
||||
**数据映射规则**（6 区 → 3 段）:
|
||||
|
||||
| 原 6 区 | 新 3 段 | 映射逻辑 |
|
||||
|---------|---------|---------|
|
||||
| 待接单 (queued) | 📌 我的会话 | `is_mine || status === 'queued'` |
|
||||
| 我的会话 (serving + is_mine) | 📌 我的会话 | `status === 'serving' && is_mine` |
|
||||
| 协作会话 | 📌 我的会话 | `is_collaborator` |
|
||||
| 其他坐席会话 | 👥 同事会话 | `!is_mine && status === 'serving'` |
|
||||
| AI 处理区 | 👥 同事会话 | `status === 'ai_handling'` |
|
||||
| 已结单 | 🕐 历史会话 | `status === 'resolved'` |
|
||||
|
||||
**验收标准**:
|
||||
1. 三段折叠：📌我的默认展开，👥同事/🕐历史默认折叠
|
||||
2. 优先级图标：⛔ 阻断性红底、👥 影响范围黄底、⭐ 角色等级紫底、🔁 重复问题橙底
|
||||
3. 搜索标签：全部/待处理/进行中/已完成 药丸筛选
|
||||
4. 待办面板 max-height: 220px，内部滚动
|
||||
5. 点击待办条目 → `workspaceView = 'task'`
|
||||
|
||||
---
|
||||
|
||||
#### T03: 中栏改造 — 用户信息栏 + AI 推荐内联 + 排查步骤栏
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **优先级** | P0 |
|
||||
| **依赖** | T01 |
|
||||
| **预估文件数** | ~8 |
|
||||
| **关键变更点** | |
|
||||
|
||||
**前端文件**:
|
||||
- `components/chat/ChatArea.vue` — 替换顶部栏为 `UserInfoBar`；底部挂载 `TroubleshootBar`；消息中插入 `AiRecommendInline`
|
||||
- `components/chat/UserInfoBar.vue` — 新建（chips + 展开详情 6 卡片）
|
||||
- `components/chat/ItLevelBadge.vue` — 新建（7 级段位徽标）
|
||||
- `components/chat/AiRecommendInline.vue` — 新建（内联 AI 推荐）
|
||||
- `components/chat/TroubleshootBar.vue` — 新建（路径视图 + 流程图）
|
||||
- `components/chat/FlowchartNode.vue` — 新建（递归决策树节点）
|
||||
- `composables/useKeyboardShortcuts.ts` — 新建（Ctrl+1/2/3 注册）
|
||||
- `api/troubleshooting.ts` — 新建排查模板 API
|
||||
|
||||
**后端文件**:
|
||||
- `api/troubleshooting_templates.py` — 新建排查模板 CRUD API（含 Mock 数据 5-8 套模板）
|
||||
- `api/router.py` — 注册排查模板路由
|
||||
- `api/employees.py` — 新增 `PUT /api/employees/{id}/it-level` 端点
|
||||
|
||||
**验收标准**:
|
||||
1. UserInfoBar 常驻显示 chips（情绪+时长+轮次+重复+备注+IT等级）
|
||||
2. 点击展开 6 卡片 3 列 grid，max-height 动画 0.35s
|
||||
3. AI 推荐仅在坐席未回复时显示，Ctrl+1/2/3 快捷填入
|
||||
4. TroubleshootBar 始终可见，默认路径方块；展开流程图含判断节点
|
||||
5. 快捷键仅在输入框未聚焦时生效
|
||||
|
||||
---
|
||||
|
||||
#### T04: 右栏改造 + 任务详情视图
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **优先级** | P0 |
|
||||
| **依赖** | T01, T02 |
|
||||
| **预估文件数** | ~5 |
|
||||
| **关键变更点** | |
|
||||
|
||||
**前端文件**:
|
||||
- `components/assistant/AiAssistantPanel.vue` — 完全重写（上下两区）
|
||||
- `components/assistant/AiSuggestReply.vue` — 适配新布局 + 置信度显示
|
||||
- `components/assistant/QuickReplyPanel.vue` — 重写（搜索置顶 + Alt 分类 + ↑↓ 导航 + Enter + 键盘指南）
|
||||
- `components/chat/TaskDetailView.vue` — 新建（工单/审批/设备 3 种子视图）
|
||||
|
||||
**废弃文件**:
|
||||
- `components/assistant/RiskAlert.vue` — 移除引用
|
||||
- `components/assistant/UserInfoPanel.vue` — 移除引用
|
||||
|
||||
**验收标准**:
|
||||
1. 右栏上方 ~1/3 AI 推荐区，下方 ~2/3 快速回复区
|
||||
2. Alt+1~5 切换分类，↑↓ 导航条目，Enter 确认填入，/ 聚焦搜索
|
||||
3. 底部常驻键盘指南条
|
||||
4. TaskDetailView 支持 3 种子视图（工单/审批/设备），"← 返回会话" 切回聊天
|
||||
5. RiskAlert.vue、UserInfoPanel.vue 不再被任何组件引用
|
||||
|
||||
---
|
||||
|
||||
#### T05: 集成联调 + 快捷键完善 + 样式打磨
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **优先级** | P1 |
|
||||
| **依赖** | T01, T02, T03, T04 |
|
||||
| **预估文件数** | ~3 |
|
||||
| **关键变更点** | |
|
||||
|
||||
**前端文件**:
|
||||
- `composables/useKeyboardShortcuts.ts` — 完善全局快捷键注册/卸载（与 T03 初版合并后打磨）
|
||||
- `styles/global.css` — 主题过渡动画完善 + 深色模式边缘 case 修复
|
||||
- `views/Workspace.vue` — 最终集成调整（视图切换状态管理 + 双主题适配验证）
|
||||
|
||||
**验收标准**:
|
||||
1. 主题切换过渡 ≤ 300ms，所有组件双主题无色值遗漏
|
||||
2. 快捷键全局生效：Ctrl+1/2/3（AI 推荐）、Alt+1~5（快速回复分类）、↑↓ Enter /（快速回复操作）
|
||||
3. 快捷键与输入框不冲突（输入框聚焦时快捷键不触发）
|
||||
4. 视图切换（聊天↔任务）状态不丢失，WebSocket 保持连接
|
||||
5. 王者徽标 `king-glow` 发光动画正常
|
||||
|
||||
---
|
||||
|
||||
### 5.3 任务依赖图
|
||||
|
||||
```mermaid
|
||||
graph LR
|
||||
T01[T01: 基础设施<br/>主题+模型+TopBar] --> T02[T02: 左栏改造<br/>三段折叠+待办面板]
|
||||
T01 --> T03[T03: 中栏改造<br/>用户信息栏+AI推荐+排查]
|
||||
T01 --> T04[T04: 右栏+任务视图<br/>AI助手重构+TaskDetail]
|
||||
T02 --> T04
|
||||
T01 --> T05[T05: 集成联调<br/>快捷键+样式打磨]
|
||||
T02 --> T05
|
||||
T03 --> T05
|
||||
T04 --> T05
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 共享知识
|
||||
|
||||
### 6.1 CSS 变量命名规范
|
||||
|
||||
```css
|
||||
:root {
|
||||
/* 背景 */
|
||||
--bg-primary: #f5f7fa; /* 主背景 */
|
||||
--bg-secondary: #ffffff; /* 次背景（卡片/面板） */
|
||||
--bg-tertiary: #f0f2f5; /* 三级背景（段头/分区） */
|
||||
--bg-hover: #e8eaed; /* 悬停背景 */
|
||||
--bg-active: #d9dce0; /* 激活/选中背景 */
|
||||
--bg-accent-soft: #ecf5ff; /* 强调色浅底 */
|
||||
|
||||
/* 文字 */
|
||||
--text-primary: #303133; /* 主文字 */
|
||||
--text-secondary: #606266; /* 次文字 */
|
||||
--text-tertiary: #909399; /* 辅助文字 */
|
||||
--text-placeholder: #c0c4cc;/* 占位文字 */
|
||||
|
||||
/* 边框 */
|
||||
--border-color: #e4e7ed;
|
||||
--border-light: #ebeef5;
|
||||
|
||||
/* 强调色 */
|
||||
--accent: #409eff;
|
||||
--accent-hover: #66b1ff;
|
||||
--accent-soft: #ecf5ff;
|
||||
|
||||
/* 语义色 */
|
||||
--color-success: #67c23a;
|
||||
--color-warning: #e6a23c;
|
||||
--color-danger: #f56c6c;
|
||||
--color-info: #909399;
|
||||
|
||||
/* 深色主题覆盖 */
|
||||
}
|
||||
|
||||
[data-theme="dark"] {
|
||||
--bg-primary: #0f1923;
|
||||
--bg-secondary: #151f2b;
|
||||
--bg-tertiary: #1a2736;
|
||||
--bg-hover: #1e3044;
|
||||
--bg-active: #243b52;
|
||||
--bg-accent-soft: rgba(77, 166, 255, 0.12);
|
||||
|
||||
--text-primary: #e8edf2;
|
||||
--text-secondary: #8ba1b7;
|
||||
--text-tertiary: #5c7a94;
|
||||
--text-placeholder: #3d5568;
|
||||
|
||||
--border-color: #243b52;
|
||||
--border-light: #1e3044;
|
||||
|
||||
--accent: #4da6ff;
|
||||
--accent-hover: #73b9ff;
|
||||
--accent-soft: rgba(77, 166, 255, 0.12);
|
||||
|
||||
--color-success: #52c41a;
|
||||
--color-warning: #faad14;
|
||||
--color-danger: #ff4d4f;
|
||||
--color-info: #8ba1b7;
|
||||
}
|
||||
```
|
||||
|
||||
**使用规则**：
|
||||
- 所有新增组件**必须**使用 CSS 变量，禁止硬编码色值
|
||||
- 现有组件在修改时逐步替换硬编码为变量
|
||||
- Element Plus 组件的主题覆盖通过 `:deep()` 选择器 + CSS 变量实现
|
||||
|
||||
### 6.2 组件通信模式
|
||||
|
||||
| 场景 | 模式 | 示例 |
|
||||
|------|------|------|
|
||||
| 跨组件快捷键填入 | `conversationStore.pendingReplyText` | AI推荐/快速回复 → ReplyBox |
|
||||
| 视图切换 | `conversationStore.workspaceView` | TodoPanel → Workspace → ChatArea/TaskDetailView |
|
||||
| 主题切换 | `useThemeStore.currentTheme` + `data-theme` 属性 | TopBar → 全局 DOM |
|
||||
| 待办事项选中 | `useTodoStore.currentTodoItem` | TodoPanel → TaskDetailView |
|
||||
| 排查模板选中 | `local ref` in TroubleshootBar | 不需跨组件，局部状态 |
|
||||
|
||||
### 6.3 Store 状态结构约定
|
||||
|
||||
```typescript
|
||||
// ---- conversationStore 扩展 ----
|
||||
{
|
||||
// ... 现有状态 ...
|
||||
workspaceView: 'chat' | 'task' // ★NEW 中间栏当前视图
|
||||
}
|
||||
|
||||
// ---- themeStore ----
|
||||
{
|
||||
currentTheme: 'light' | 'dark'
|
||||
toggleTheme(): void
|
||||
}
|
||||
|
||||
// ---- todoStore ----
|
||||
{
|
||||
todoList: TodoItem[]
|
||||
currentTodoItem: TodoItem | null
|
||||
loading: boolean
|
||||
fetchTodoList(): Promise<void>
|
||||
selectTodoItem(item: TodoItem): void
|
||||
updateTodoStatus(id: string, status: string): Promise<void>
|
||||
}
|
||||
```
|
||||
|
||||
### 6.4 API 响应格式约定
|
||||
|
||||
沿用现有 `{code, data, message}` 格式：
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": { ... },
|
||||
"message": "success"
|
||||
}
|
||||
```
|
||||
|
||||
### 6.5 IT 等级枚举映射
|
||||
|
||||
```typescript
|
||||
const IT_LEVELS = [
|
||||
{ key: 'bronze', label: '青铜', level: 1, cssClass: 'bronze' },
|
||||
{ key: 'silver', label: '白银', level: 2, cssClass: 'silver' },
|
||||
{ key: 'gold', label: '黄金', level: 3, cssClass: 'gold' },
|
||||
{ key: 'platinum', label: '铂金', level: 4, cssClass: 'platinum' },
|
||||
{ key: 'diamond', label: '钻石', level: 5, cssClass: 'diamond' },
|
||||
{ key: 'star', label: '星耀', level: 6, cssClass: 'star' },
|
||||
{ key: 'king', label: '王者', level: 7, cssClass: 'king' },
|
||||
] as const
|
||||
```
|
||||
|
||||
### 6.6 优先级图标映射
|
||||
|
||||
```typescript
|
||||
const PRIORITY_ICONS = [
|
||||
{ key: 'is_blocking', icon: '⛔', cssClass: 'pi-blocked', bg: '#f56c6c' },
|
||||
{ key: 'impact_scope', icon: '👥', cssClass: 'pi-impact', bg: '#e6a23c', highThreshold: 5 },
|
||||
{ key: 'role_level', icon: '⭐', cssClass: 'pi-role', bg: '#9b59b6' },
|
||||
{ key: 'is_repeat', icon: '🔁', cssClass: 'pi-repeat', bg: '#f59e0b' },
|
||||
] as const
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 待明确事项
|
||||
|
||||
| # | 事项 | 影响范围 | 建议默认值 | 优先级 |
|
||||
|---|------|---------|-----------|--------|
|
||||
| 1 | **情绪状态识别方式**：AI 自动分析 vs 坐席手动标记？ | BE-02, FE-04 | P0 先坐席手动标记，P1 加 AI 辅助 | P0 |
|
||||
| 2 | **影响范围数据来源**：坐席标记 vs 系统自动判断？ | BE-02, FE-02 | P0 坐席手动标记，`impact_scope` 默认 0 | P0 |
|
||||
| 3 | **原 6 区→3 段映射**：协作会话归入"我的会话"还是"同事会话"？ | FE-02 | 协作会话归入"📌我的会话"（因为坐席仍在参与） | P0 |
|
||||
| 4 | **排查模板匹配方式**：自动匹配 vs 坐席手动选择？ | BE-04, FE-06 | P0 坐席手动选择，P2 做自动匹配 | P0 |
|
||||
| 5 | **同事会话范围**：全部坐席 vs 同组坐席？ | FE-02 | P0 全部坐席（前端过滤可后续加） | P1 |
|
||||
| 6 | **排查步骤栏最小/最大高度** | FE-06 | 最小 44px（路径方块），最大 300px（展开流程图） | P1 |
|
||||
| 7 | **AI 推荐回复触发时机**：每条用户消息后都触发？ | FE-05 | 仅坐席未回复时显示（已确认） | P0 |
|
||||
| 8 | **IT 等级在用户端显示方式**：完整徽标 vs 简化文本？ | FE-04 | 需与用户端产品确认，坐席端先用完整徽标 | P2 |
|
||||
| 9 | **Element Plus 深色主题适配**：EP 组件（ElInput/ElTag 等）在深色模式下的样式覆盖策略 | 全局 | 通过 `:deep()` + CSS 变量覆盖 EP 的 `--el-*` 变量 | P1 |
|
||||
| 10 | **排查模板 Mock 数据结构**：flowchart JSON 的具体递归结构定义 | BE-04 | 需定义标准节点结构（见 §3.2 FlowchartNode） | P0 |
|
||||
|
||||
---
|
||||
|
||||
## 附录 A：关键组件 Props/Emits 定义
|
||||
|
||||
### TopBar.vue
|
||||
|
||||
```typescript
|
||||
// Props
|
||||
interface TopBarProps {
|
||||
agentName: string
|
||||
agentStatus: 'online' | 'busy' | 'offline'
|
||||
emergencyMode: boolean
|
||||
}
|
||||
|
||||
// Emits
|
||||
interface TopBarEmits {
|
||||
toggleTheme: []
|
||||
changeStatus: [status: string]
|
||||
toggleEmergency: [enabled: boolean]
|
||||
logout: []
|
||||
}
|
||||
```
|
||||
|
||||
### UserInfoBar.vue
|
||||
|
||||
```typescript
|
||||
// Props
|
||||
interface UserInfoBarProps {
|
||||
employeeName: string
|
||||
department: string
|
||||
position: string
|
||||
itLevel: string
|
||||
emotionState: string
|
||||
waitDuration: number // 秒
|
||||
conversationCount: number
|
||||
isRepeat: boolean
|
||||
hasNotes: boolean
|
||||
}
|
||||
|
||||
// Emits
|
||||
interface UserInfoBarEmits {
|
||||
adjustItLevel: [newLevel: string]
|
||||
}
|
||||
```
|
||||
|
||||
### TroubleshootBar.vue
|
||||
|
||||
```typescript
|
||||
// Props
|
||||
interface TroubleshootBarProps {
|
||||
category?: 'vpn' | 'email' | 'system' | 'account'
|
||||
}
|
||||
|
||||
// 无 Emits — 坐席交互仅影响组件内部状态
|
||||
```
|
||||
|
||||
### TaskDetailView.vue
|
||||
|
||||
```typescript
|
||||
// Props
|
||||
interface TaskDetailViewProps {
|
||||
todoItem: TodoItem
|
||||
}
|
||||
|
||||
// Emits
|
||||
interface TaskDetailViewEmits {
|
||||
back: [] // 返回聊天视图
|
||||
statusChanged: [id: string, newStatus: string]
|
||||
}
|
||||
```
|
||||
|
||||
### AiRecommendInline.vue
|
||||
|
||||
```typescript
|
||||
// Props
|
||||
interface AiRecommendInlineProps {
|
||||
recommendations: Array<{
|
||||
id: string
|
||||
content: string
|
||||
confidence: number
|
||||
}>
|
||||
visible: boolean // 仅坐席未回复时 true
|
||||
}
|
||||
|
||||
// Emits
|
||||
interface AiRecommendInlineEmits {
|
||||
fillReply: [content: string]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 附录 B：数据库迁移注意事项
|
||||
|
||||
### SQLite（本地开发）
|
||||
|
||||
SQLite 使用 `Base.metadata.create_all` 自动建表，新增模型只需在 `models/__init__.py` 中导入即可。新增字段需注意：
|
||||
|
||||
- SQLite 不支持 `ALTER TABLE ADD COLUMN` 添加带 `NOT NULL` 且无默认值的列
|
||||
- 所有新增字段**必须**设置 `default` 值（已在模型定义中保证）
|
||||
|
||||
### PostgreSQL（生产）
|
||||
|
||||
使用 Alembic 迁移：
|
||||
|
||||
```bash
|
||||
alembic revision --autogenerate -m "v53_add_it_level_impact_scope_todo_troubleshooting"
|
||||
alembic upgrade head
|
||||
```
|
||||
|
||||
新增表：`todo_items`、`troubleshooting_templates`
|
||||
新增列：`employees.it_level`、`employees.it_level_source`、`employees.notes`、`conversations.impact_scope`、`conversations.is_blocking`、`conversations.emotion_state`
|
||||
@@ -0,0 +1,546 @@
|
||||
# IT智能服务台 · 坐席工作台 v5.3 增量 PRD
|
||||
|
||||
> **版本**: v5.3 增量迭代
|
||||
> **日期**: 2026-06-06
|
||||
> **作者**: 许清楚（Xu）· 产品经理
|
||||
> **状态**: 待评审
|
||||
> **原型版本**: agent-workspace-v5_3.html（已锁定）
|
||||
|
||||
---
|
||||
|
||||
## 1. 项目信息
|
||||
|
||||
| 字段 | 值 |
|
||||
|------|-----|
|
||||
| **项目名称** | it_smart_desk_workspace_v53 |
|
||||
| **技术栈** | 前端: Vue3 + TypeScript + Element Plus + Pinia + Vite / 后端: FastAPI + SQLAlchemy |
|
||||
| **语言** | 中文 |
|
||||
| **原型文件** | `agent-workspace-v5_3.html` |
|
||||
| **项目根目录** | `C:\Users\simon\wecom_it_smart_desk\` |
|
||||
|
||||
### 原始需求复述
|
||||
|
||||
对企微 IT 智能服务台的坐席工作台进行 UI/UX 全面升级（v5.3 增量迭代）。现有系统已具备会话管理、消息收发、AI 助手（5 Tab 结构）、快速回复等基础功能，本次迭代需根据 v5.3 原型图实现：主题系统、左栏会话列表改造（三段折叠 + 优先级图标 + 待办面板）、中栏聊天区改造（用户信息栏 + AI 推荐内联 + 排查步骤栏 + 视图切换）、右栏 AI 助手面板重构（移除 Tab 改上下两区）、后端模型扩展等 7 大模块变更。
|
||||
|
||||
### 现有系统基线
|
||||
|
||||
当前坐席工作台采用三栏布局：
|
||||
|
||||
- **左栏（280px）**：`ConversationList.vue` — 6 区会话列表（待接单/我的/协作/其他/AI/已结单），基础搜索
|
||||
- **中栏（flex-1）**：`ChatArea.vue` — 顶部标题栏 + 消息区 + 回复输入框
|
||||
- **右栏（320px）**：`AiAssistantPanel.vue` — 5 Tab（AI 副驾驶/快速回复/操作步骤/风险提示/用户信息）
|
||||
|
||||
后端模型：`Conversation`（含 urgency_score/tags/assigned_agent_id 等）、`Employee`（基础字段）、`Agent`、`Message`、`QuickReplyTemplate`
|
||||
|
||||
---
|
||||
|
||||
## 2. 产品定义
|
||||
|
||||
### 2.1 产品目标
|
||||
|
||||
1. **提升坐席效率**：通过 AI 推荐回复（Ctrl+1/2/3 快捷填入）、键盘驱动的快速回复（Alt+1~5 + ↑↓ + Enter）、排查步骤流程图，将坐席平均响应时间降低 30%
|
||||
2. **增强信息感知**：通过优先级图标体系（⛔阻断性/👥影响范围/⭐角色等级/🔁重复问题）、用户情绪状态芯片、IT 等级徽标，让坐席在 3 秒内掌握会话全貌
|
||||
3. **统一工作闭环**：通过待办事项面板 + 中间栏视图切换，将工单/审批/设备异常等任务类型整合到同一工作台，消除多系统切换成本
|
||||
|
||||
### 2.2 用户故事
|
||||
|
||||
| # | 用户故事 |
|
||||
|---|---------|
|
||||
| US-1 | **As a** IT 坐席, **I want** 在会话列表每条会话上直接看到阻断性/影响范围/角色等级/重复问题等优先级图标, **so that** 我能快速判断哪些会话需要优先处理，不必逐一点开查看详情 |
|
||||
| US-2 | **As a** IT 坐席, **I want** 在聊天区顶部常驻显示用户情绪、等待时长、IT 等级等信息芯片，点击展开 6 卡片详情, **so that** 我在对话过程中始终掌握用户画像，及时调整沟通策略 |
|
||||
| US-3 | **As a** IT 坐席, **I want** 在聊天区内看到 1-3 条 AI 推荐回复并支持 Ctrl+1/2/3 快捷填入, **so that** 我能快速回复常见问题，减少手动输入时间 |
|
||||
| US-4 | **As a** IT 坐席, **I want** 点击左侧待办事项时中间栏切换为任务类型专属页面（工单/审批/设备异常）, **so that** 我无需切换到其他系统即可一站式处理所有任务 |
|
||||
| US-5 | **As a** IT 坐席, **I want** 在右栏通过 Alt+1~5 切换快速回复分类、↑↓ 导航、Enter 确认填入, **so that** 我可以在不离开键盘的情况下高效完成回复 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 需求池（P0/P1/P2）
|
||||
|
||||
### P0 — 必须完成（核心体验）
|
||||
|
||||
---
|
||||
|
||||
#### FE-01 主题系统
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **需求** | 浅色/深色主题切换 |
|
||||
| **交互** | 顶部工具栏右侧添加 ☀️/🌙 切换开关（Track + Thumb 滑块样式），点击即切换 |
|
||||
| **实现** | `data-theme="light\|dark"` 属性切换；CSS 变量驱动两套配色（`:root` 浅色 / `[data-theme="dark"]` 深色） |
|
||||
| **持久化** | 切换后写入 `localStorage`，页面加载时读取恢复 |
|
||||
| **约束** | 切换即时生效，过渡时长 ≤ 300ms（`transition: background 0.3s, color 0.3s`）；所有新增组件必须兼容双主题 |
|
||||
| **设计规格** | 深色主题：主背景 `#0f1923`，次背景 `#151f2b`，三级背景 `#1a2736`，悬停 `#1e3044`，激活 `#243b52`；主文字 `#e8edf2`，次文字 `#8ba1b7`；强调色 `#4da6ff` |
|
||||
| **变更范围** | `Workspace.vue` 顶部栏重构为独立 `TopBar.vue`；新增 `composables/useTheme.ts`；`global.css` 新增深色 CSS 变量 |
|
||||
|
||||
---
|
||||
|
||||
#### FE-02 左栏会话列表 — 三段折叠 + 搜索增强 + 优先级图标
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **三段折叠** | 替代原 6 区结构，改为 3 段：📌 我的会话（默认展开）/ 👥 同事会话（默认折叠）/ 🕐 历史会话（默认折叠） |
|
||||
| **段头交互** | 段头背景 `var(--bg-tertiary)`，hover 变 `var(--bg-hover)`；显示条目数量（药丸徽标）+ 折叠箭头（▼ 旋转 -90° 收起）；点击整行切换折叠 |
|
||||
| **搜索增强** | 搜索框 placeholder "搜索用户、关键词..."；下方增加快捷筛选标签：全部/待处理/进行中/已完成（药丸样式，active 态 `var(--accent-soft)` + `var(--accent)` 色） |
|
||||
| **优先级图标** | 每条会话名称右侧显示：⛔ 阻断性（`is_blocking`，红底）、👥 影响范围（`impact_scope`，>5 人用高对比色）、⭐ 角色等级、🔁 重复问题。**不显示 IT 等级徽标** |
|
||||
| **优先级图标规格** | 16×16px 圆角方块，8px 字体；`pi-blocked` 红底、`pi-impact` 黄底（high 变红底）、`pi-role` 紫底、`pi-repeat` 橙底 |
|
||||
| **会话条目规格** | 条目间距 `margin: 1px 6px`，padding `8px 10px`；active 态 `var(--accent-soft)` + accent 边框；"待回复" 红色药丸标签 |
|
||||
| **变更范围** | `ConversationList.vue` 重构分区逻辑 + 搜索标签；`ConversationItem.vue` 新增优先级图标渲染 |
|
||||
|
||||
---
|
||||
|
||||
#### FE-03 左栏底部 — 待办事项面板
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **位置** | 左栏底部，`border-top: 1px solid var(--border)`，`max-height: 220px`，内部滚动 |
|
||||
| **标题** | "待办事项" + 紧急数量红色标记（如 "5 紧急"） |
|
||||
| **条目** | 每条显示：优先级圆点（urgent 红 / high 黄）+ 文本 + 类型标签（工单/审批/设备）+ 时间 |
|
||||
| **类型标签样式** | 工单：蓝底蓝字蓝边框；审批：紫底紫字紫边框；设备：橙底橙字橙边框（9px 字体） |
|
||||
| **点击交互** | 点击条目 → 中间栏切换为对应任务类型详情视图 |
|
||||
| **底部统计** | 在线/忙碌/离线坐席数（带状态圆点） |
|
||||
| **变更范围** | `ConversationList.vue` 底部新增 `TodoPanel.vue` |
|
||||
|
||||
---
|
||||
|
||||
#### FE-04 中栏聊天区 — 用户信息栏
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **常驻区** | 替代原顶部标题栏，显示：头像（36px 圆形渐变）+ 姓名·部门岗位 + IT 等级徽标 + 信息 chips + 展开箭头 |
|
||||
| **信息 chips** | 😟 情绪（黄底黄边）、⏱ 等待时长、💬 对话轮次、🔁 重复标记（红底红边）、📝 备注标记（紫底紫边）；默认态灰底 |
|
||||
| **展开详情** | 点击整行展开/收起 6 卡片详情面板（3 列 grid 布局）：① 情绪状态 ② 会话详情 ③ 问题分析 ④ IT 技能等级 ⑤ 历史工单 ⑥ 其他备注 |
|
||||
| **IT 等级徽标** | 7 级段位（见 §4.2），显示在用户名行 + 详情卡片 ④ 中 |
|
||||
| **动画** | 展开箭头旋转 180°，详情面板 `max-height` 动画过渡 0.35s |
|
||||
| **变更范围** | 新增 `UserInfoBar.vue` + `ItLevelBadge.vue`；`ChatArea.vue` 替换顶部栏 |
|
||||
|
||||
---
|
||||
|
||||
#### FE-05 中栏聊天区 — AI 推荐回复（内联）
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **位置** | 聊天消息流中，用户消息之后、坐席回复之前 |
|
||||
| **触发条件** | 仅坐席未回复时显示；坐席发送回复后自动隐藏 |
|
||||
| **样式** | 虚线边框（`1px dashed var(--accent)`）+ 浅蓝背景，全宽 |
|
||||
| **内容** | "🤖 AI 推荐回复" 标签 + 1-3 个推荐选项卡片（横向排列，flex:1） |
|
||||
| **快捷键** | Ctrl+1 / Ctrl+2 / Ctrl+3 快捷填入回复框 |
|
||||
| **点击** | 点击卡片内容填入回复框并聚焦 |
|
||||
| **变更范围** | 新增 `AiRecommendInline.vue`；修改 `ChatArea.vue` 消息渲染逻辑 |
|
||||
|
||||
---
|
||||
|
||||
#### FE-06 中栏聊天区 — 排查步骤栏
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **位置** | 聊天输入框下方，始终可见（不可整体收起） |
|
||||
| **栏头** | "🔧 排查步骤" + "▶ 展开全流程图" 按钮（accent 色边框药丸） |
|
||||
| **默认视图** | 最优路径横向方块：① 确认版本 → ② 清除缓存 → ③ 远程排查 → ...（可横向滚动） |
|
||||
| **路径方块规格** | padding `7px 14px`，圆角方块；done 态绿底、current 态蓝底、默认灰底；hover 变 accent 边框 |
|
||||
| **展开视图** | 点击 "展开全流程图" → 按钮文字变 "▼ 收起全流程图"，下方展开完整决策树 |
|
||||
| **决策树规格** | 纵向步骤：圆点节点（22px）+ 连接线（2px）；判断节点（❓ 判断）黄底方块；分支用虚线左侧缩进；当前步骤蓝色节点，已完成绿色节点 |
|
||||
| **动画** | 流程图区 `max-height` 过渡 0.35s；按钮箭头旋转 90° |
|
||||
| **数据源** | 静态模板库（`TroubleshootingTemplate` 模型），P0 坐席手动选择模板 |
|
||||
| **变更范围** | 新增 `TroubleshootBar.vue`；`ChatArea.vue` 底部挂载 |
|
||||
|
||||
---
|
||||
|
||||
#### FE-07 中栏 — 任务详情视图切换
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **触发** | 点击左栏待办事项条目 → 中间栏从聊天视图切换为任务详情视图 |
|
||||
| **返回** | "← 返回会话" 按钮，切换回聊天视图 |
|
||||
| **运维工单页** | 📋 工单描述卡片（标题/类型/优先级/上报人/时间/描述）+ 📍 处理进度卡片（状态/接单人/SLA）+ 操作按钮：📥 接单 / 🔧 开始处理 / ✅ 结单 / 🔄 转派 |
|
||||
| **审批单页** | 📝 审批内容卡片 + ✏️ 审批意见输入区（textarea）+ 操作按钮：✅ 审批通过 / ❌ 拒绝审批 / 🔄 转交审批 |
|
||||
| **设备异常页** | 🖥 设备状态网格（2×3 grid：名称/型号/在线状态/最后在线/IP/告警次数）+ 🔧 处理记录卡片 + 操作按钮：📝 一键开单 / 🚚 派工 / ✅ 标记恢复 / 📅 加入巡检 |
|
||||
| **卡片规格** | 白底 + border + `radius-lg`(10px) + padding `14px 16px`；标签行 `tic-label`(70px) + `tic-value` |
|
||||
| **状态色值** | 正常=success绿、告警=warning黄、异常=danger红 |
|
||||
| **变更范围** | 新增 `TaskDetailView.vue`（含 3 种子视图）；`ChatArea.vue` 同级添加视图切换逻辑 |
|
||||
|
||||
---
|
||||
|
||||
#### FE-08 右栏 AI 助手面板重构
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **重构** | 移除现有 5 Tab 结构（`ElTabs`），改为上下两个区域 |
|
||||
| **上方 ~1/3** | 🤖 AI 智能推荐区（`flex-shrink:0`，border-bottom 分隔）：标题栏（左侧蓝色竖线 3×12px + "🤖 AI 智能推荐"）+ 1-3 张推荐卡片 |
|
||||
| **推荐卡片** | 灰底 + border，hover 变 accent 边框；卡片头：方案名称 + 置信度药丸（如 "92%"）；卡片文本：2 行截断；快捷键提示 `Ctrl+1/2/3` |
|
||||
| **下方 ~2/3** | 快速回复区（`flex:1`，内部列布局）：搜索栏置顶 + 分类标签栏 + 回复条目列表 + 底部键盘指南 |
|
||||
| **分类标签** | 横向排列，每个标签带 `Alt+N` 提示；active 态 `var(--accent-soft)` + accent 边框；如 "VPN/网络 Alt+1"、"邮箱/办公 Alt+2" 等 |
|
||||
| **回复条目** | 左侧图标 + 文本 + 序号提示；selected 态蓝底蓝边框；hover 灰底 |
|
||||
| **键盘导航** | Alt+1~5 切换分类；↑↓ 选中条目；Enter 确认填入；/ 聚焦搜索框 |
|
||||
| **键盘指南** | 底部常驻：`Alt+1-5 切换` / `↑↓ 选择` / `Enter 填入` / `/ 搜索` |
|
||||
| **移除** | 风险提示 Tab（`RiskAlert.vue` 废弃）、用户信息 Tab（`UserInfoPanel.vue` 废弃，功能已并入聊天区） |
|
||||
| **变更范围** | `AiAssistantPanel.vue` 完全重写；`QuickReplyPanel.vue` 重写交互逻辑 |
|
||||
|
||||
---
|
||||
|
||||
#### FE-09 系统名称
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **顶部栏** | 左侧：logo 方块 "IT"（渐变紫蓝 26×26px）+ "IT智能服务台"（渐变文字）+ "· 坐席工作台 — AI驱动 · 多系统对接 · 一站式处理"（10px 灰色副标题，max-width 280px 溢出省略） |
|
||||
| **变更范围** | `TopBar.vue`（从 `Workspace.vue` 顶部栏独立） |
|
||||
|
||||
---
|
||||
|
||||
#### BE-01 Employee 模型扩展
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **新增字段** | `it_level`: IT 等级枚举（bronze/silver/gold/platinum/diamond/star/king），默认 silver；`it_level_source`: 等级来源（system/manual），默认 system；`notes`: 备注 JSON |
|
||||
| **API** | 新增 `PUT /api/employees/{id}/it-level` 坐席手动调整 IT 等级端点；修改 `GET /api/employees/{id}` 返回新字段 |
|
||||
| **变更范围** | `models/employee.py` 新增 3 字段；`schemas/` 新增/修改；`api/` 新增端点 |
|
||||
|
||||
---
|
||||
|
||||
#### BE-02 Conversation 模型扩展
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **新增字段** | `impact_scope`: 影响范围（整数，受影响人数，默认 0）；`is_blocking`: 阻断性标记（布尔，默认 False）；`emotion_state`: 情绪状态（枚举 normal/anxious/angry/urgent，默认 normal） |
|
||||
| **API** | 修改 `GET /api/conversations` 和 `GET /api/conversations/{id}` 响应包含新字段 |
|
||||
| **变更范围** | `models/conversation.py` 新增 3 字段；`schemas/conversation.py` 修改；`api/conversations.py` 修改 |
|
||||
|
||||
---
|
||||
|
||||
#### BE-03 TodoItem 模型 + CRUD API
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **新增模型** | `TodoItem`：id(UUID), type(ticket/approval/device), title, priority(urgent/high/normal), description(JSON), status(pending/processing/resolved), assigned_agent_id(nullable), corp_id, created_at, updated_at |
|
||||
| **API** | `GET /api/todo-items`（列表）、`GET /api/todo-items/{id}`（详情）、`PUT /api/todo-items/{id}/status`（更新状态）|
|
||||
| **数据** | Mock 数据先行，预置 5-10 条示例待办 |
|
||||
| **变更范围** | 新增 `models/todo_item.py` + `schemas/todo_item.py` + `api/todo_items.py` |
|
||||
|
||||
---
|
||||
|
||||
#### BE-04 TroubleshootingTemplate 模型 + CRUD API
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **新增模型** | `TroubleshootingTemplate`：id(UUID), name, category(vpn/email/system/account), path_steps(JSON 最优路径), flowchart(JSON 完整决策树), is_active(布尔), created_at, updated_at |
|
||||
| **API** | `GET /api/troubleshooting-templates`（列表）、`GET /api/troubleshooting-templates/{id}`（详情）、`POST/PUT/DELETE`（管理员增删改） |
|
||||
| **数据** | 预置常见问题模板（VPN 连接失败、邮箱配置、系统登录、账号权限等 5-8 套） |
|
||||
| **变更范围** | 新增 `models/troubleshooting_template.py` + `schemas/troubleshooting_template.py` + `api/troubleshooting_templates.py` |
|
||||
|
||||
---
|
||||
|
||||
### P1 — 应该完成（体验增强）
|
||||
|
||||
---
|
||||
|
||||
#### FE-10 快捷键系统完善
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **需求** | 全局快捷键注册与统一管理 |
|
||||
| **快捷键列表** | Ctrl+1/2/3（AI 推荐填入）、Alt+1~5（快速回复分类切换）、↑↓（快速回复条目导航）、Enter（确认填入）、/（聚焦快速回复搜索框） |
|
||||
| **约束** | 快捷键仅在未聚焦输入框时生效（避免与打字冲突）；需提供快捷键提示 UI（右栏底部键盘指南） |
|
||||
| **变更范围** | 新增 `composables/useKeyboardShortcuts.ts` |
|
||||
|
||||
---
|
||||
|
||||
#### FE-11 IT 等级手动调整交互
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **需求** | 坐席可在用户信息详情卡片中手动调整用户 IT 等级 |
|
||||
| **交互** | 在 IT 等级详情卡片旁提供「调整」按钮，弹出 7 级选择器（下拉/弹窗） |
|
||||
| **约束** | 调整后需记录 `it_level_source=manual`；前端立即更新显示，后端异步保存 |
|
||||
| **变更范围** | `UserInfoBar.vue` 详情面板中新增调整交互 |
|
||||
|
||||
---
|
||||
|
||||
#### FE-12 主题切换过渡动画
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **需求** | 主题切换时的平滑过渡效果 |
|
||||
| **实现** | `body` 添加 `transition: background 0.3s, color 0.3s`；所有 CSS 变量驱动的属性自动跟随过渡 |
|
||||
| **约束** | 过渡时长 ≤ 300ms，不影响交互流畅度 |
|
||||
|
||||
---
|
||||
|
||||
#### BE-05 IT 等级自动评分逻辑（框架）
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **需求** | 为后续迭代搭建自动评分框架 |
|
||||
| **实现** | 定义评分维度和权重接口，当前仅返回默认值（silver）或手动值 |
|
||||
| **约束** | 不在 P0 实现完整评分，仅搭建扩展点 |
|
||||
|
||||
---
|
||||
|
||||
### P2 — 锦上添花（远期优化）
|
||||
|
||||
---
|
||||
|
||||
#### FE-13 排查步骤进度同步
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **需求** | 排查步骤的当前步骤与对话内容自动同步 |
|
||||
| **实现** | 根据消息内容关键词自动推进步骤状态（如坐席说"清除缓存"→ 步骤 ② 标记 done） |
|
||||
|
||||
#### FE-14 待办事项实时推送
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **需求** | 通过 WebSocket 实时推送新的待办事项 |
|
||||
| **实现** | 扩展 WS 消息类型，新增 `todo_item_created` 事件 |
|
||||
|
||||
#### FE-15 IT 等级完整自动评分
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **需求** | 基于用户历史工单、自助解决率、操作复杂度等维度自动计算 IT 等级 |
|
||||
| **实现** | 后台定时任务 + 评分服务 |
|
||||
|
||||
#### FE-16 排查步骤模板管理后台
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| **需求** | 管理员可在后台增删改排查模板 |
|
||||
| **实现** | 独立管理页面或嵌入现有管理后台 |
|
||||
|
||||
---
|
||||
|
||||
## 4. UI 设计草案
|
||||
|
||||
### 4.1 整体布局（三栏 + 顶栏）
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ [IT] IT智能服务台 · 坐席工作台 — AI驱动 · 多系统对接 · 一站式处理 │ ☀️/🌙 │ 坐席: 陈思远 │
|
||||
├──────────┬──────────────────────────────────┬───────────────────────┤
|
||||
│ │ 👤 张伟 · 研发一部 🥇黄金 │ 🤖 AI 智能推荐 │
|
||||
│ 🔍 搜索 │ 😟焦虑 ⏱8分32秒 💬6轮 🔁重复 │ ┌─────────────────┐ │
|
||||
│ 全部|待处 │ ▼ [6卡片详情展开区] │ │ 92% 远程协助方案 │ │
|
||||
│ |进行|已完│──────────────────────────────────│ │ 85% 备用方案 │ │
|
||||
│ │ │ └─────────────────┘ │
|
||||
│ 📌我的会话│ [用户消息气泡] │───────────────────────│
|
||||
│ ⛔👥👑🔁 │ [坐席消息气泡] │ 🔍 搜索快速回复 / │
|
||||
│ 张伟 │ 🤖 AI推荐回复 │ Alt+1│Alt+2│... │
|
||||
│ 👥👑 │ ┌────────────────────────────┐ │ ┌─────────────────┐ │
|
||||
│ 陈芳 │ │①确认版本 → ②清除缓存 → ...│ │ │ VPN连接失败... │ │
|
||||
│ │ └────────────────────────────┘ │ │ VPN证书过期... │ │
|
||||
│ 👥同事会话│ 💬 [回复输入框] [发送] │ └─────────────────┘ │
|
||||
│ (折叠) │──────────────────────────────────│ Alt+1~5 ↑↓ Enter / │
|
||||
│ │ 🔧 排查步骤 [▶展开全流程图] │ │
|
||||
│ 🕐历史会话│ ①确认版本→②清除缓存→③远程排查→.. │ │
|
||||
│ (折叠) │ │ │
|
||||
│──────────│ │ │
|
||||
│ 📋待办事项│ │ │
|
||||
│ 🔴工单 │ │ │
|
||||
│ 🟣审批 │ │ │
|
||||
│ 🟠设备 │ │ │
|
||||
├──────────┤ │ │
|
||||
│ 在线4 忙2│ │ │
|
||||
└──────────┴──────────────────────────────────┴───────────────────────┘
|
||||
```
|
||||
|
||||
### 4.2 IT 等级徽标设计
|
||||
|
||||
| 等级 | 标识 | 配色 | CSS 类名 | 说明 |
|
||||
|------|------|------|---------|------|
|
||||
| 青铜 | 🛡️ 青铜 Lv.1 | 棕色渐变 `#78350f→#92400e`，文字 `#fef3c7`，边框 `#b45309` | `.bronze` | 基础操作需指导 |
|
||||
| 白银 | 🛡️ 白银 Lv.2 | 灰色渐变 `#374151→#6b7280`，文字 `#f3f4f6`，边框 `#9ca3af` | `.silver` | 能完成常规操作 |
|
||||
| 黄金 | 🥇 黄金 Lv.3 | 金色渐变 `#92400e→#d97706`，文字 `#fffbeb`，边框 `#f59e0b` | `.gold` | 熟练使用，高级操作需指导 |
|
||||
| 铂金 | 💎 铂金 Lv.4 | 青蓝渐变 `#164e63→#0e7490`，文字 `#cffafe`，边框 `#22d3ee` | `.platinum` | 独立解决大部分问题 |
|
||||
| 钻石 | 💎 钻石 Lv.5 | 靛蓝渐变 `#312e81→#4338ca`，文字 `#e0e7ff`，边框 `#818cf8` | `.diamond` | 高级排障能力 |
|
||||
| 星耀 | ⭐ 星耀 Lv.6 | 粉紫渐变 `#831843→#be185d`，文字 `#fce7f3`，边框 `#ec4899` | `.star` | 技术专家级 |
|
||||
| 王者 | 👑 王者 Lv.7 | 橙红渐变 `#7c2d12→#c2410c`，文字 `#ffedd5`，边框 `#f97316` + **发光动画** | `.king` | IT 管理员级 |
|
||||
|
||||
> 王者徽标特有动画：`king-glow`，`box-shadow` 在 `0 0 4px` 和 `0 0 10px` 之间交替，2s 循环
|
||||
|
||||
### 4.3 待办事项 → 中间栏视图切换
|
||||
|
||||
```
|
||||
点击左侧「工单」→ 中间栏切换为：
|
||||
┌──────────────────────────────────────────────┐
|
||||
│ ← 返回会话 工单 #20240606001 [运维工单] │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ 📋 工单描述 │
|
||||
│ 标题: CEO办公室 - 投屏设备故障 │
|
||||
│ 优先级: 🔴 紧急 SLA: ⏰ 剩余 12 分钟 │
|
||||
│ ...描述详情... │
|
||||
│ │
|
||||
│ 📍 处理进度 │
|
||||
│ 状态: ⏳ 待接单 接单人: 未分配 │
|
||||
├──────────────────────────────────────────────┤
|
||||
│ [📥 接单] [🔧 开始处理] [✅ 结单] [🔄 转派] │
|
||||
└──────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 数据模型变更
|
||||
|
||||
### 5.1 Employee 模型新增字段
|
||||
|
||||
```python
|
||||
# 新增字段（在 models/employee.py 中追加）
|
||||
it_level: Mapped[str] = mapped_column(
|
||||
String(20), nullable=False, default="silver",
|
||||
comment="IT技能等级: bronze/silver/gold/platinum/diamond/star/king"
|
||||
)
|
||||
it_level_source: Mapped[str] = mapped_column(
|
||||
String(20), nullable=False, default="system",
|
||||
comment="等级来源: system(系统初评)/manual(坐席手动)"
|
||||
)
|
||||
notes: Mapped[dict] = mapped_column(
|
||||
JSON, nullable=False, default=dict,
|
||||
comment="坐席备注(JSON): {pregnancy, preferred_time, special_needs, ...}"
|
||||
)
|
||||
```
|
||||
|
||||
### 5.2 Conversation 模型新增字段
|
||||
|
||||
```python
|
||||
# 新增字段（在 models/conversation.py 中追加）
|
||||
impact_scope: Mapped[int] = mapped_column(
|
||||
Integer, nullable=False, default=0,
|
||||
comment="影响范围(受影响人数)"
|
||||
)
|
||||
is_blocking: Mapped[bool] = mapped_column(
|
||||
Boolean, nullable=False, default=False,
|
||||
comment="阻断性标记: 是否导致用户无法工作"
|
||||
)
|
||||
emotion_state: Mapped[str] = mapped_column(
|
||||
String(20), nullable=False, default="normal",
|
||||
comment="情绪状态: normal/anxious/angry/urgent"
|
||||
)
|
||||
```
|
||||
|
||||
### 5.3 新增 TodoItem 模型
|
||||
|
||||
```python
|
||||
class TodoItem(Base):
|
||||
__tablename__ = "todo_items"
|
||||
id: Mapped[str] # UUID 主键
|
||||
type: Mapped[str] # ticket/approval/device
|
||||
title: Mapped[str] # 标题
|
||||
priority: Mapped[str] # urgent/high/normal
|
||||
description: Mapped[dict] # JSON，类型专属详情
|
||||
status: Mapped[str] # pending/processing/resolved
|
||||
assigned_agent_id: Mapped[str | None] # 分配坐席
|
||||
corp_id: Mapped[str] # 企业ID
|
||||
created_at: Mapped[datetime]
|
||||
updated_at: Mapped[datetime]
|
||||
```
|
||||
|
||||
### 5.4 新增 TroubleshootingTemplate 模型
|
||||
|
||||
```python
|
||||
class TroubleshootingTemplate(Base):
|
||||
__tablename__ = "troubleshooting_templates"
|
||||
id: Mapped[str] # UUID 主键
|
||||
name: Mapped[str] # 模板名称，如 "VPN连接失败"
|
||||
category: Mapped[str] # 分类：vpn/email/system/account
|
||||
path_steps: Mapped[list] # JSON，最优路径步骤 [{label, status}]
|
||||
flowchart: Mapped[dict] # JSON，完整决策树（含判断节点、分支）
|
||||
is_active: Mapped[bool] # 是否启用
|
||||
created_at: Mapped[datetime]
|
||||
updated_at: Mapped[datetime]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. API 变更概要
|
||||
|
||||
### 6.1 新增端点
|
||||
|
||||
| 方法 | 路径 | 说明 |
|
||||
|------|------|------|
|
||||
| GET | `/api/todo-items` | 获取当前坐席待办列表 |
|
||||
| GET | `/api/todo-items/{id}` | 获取待办详情 |
|
||||
| PUT | `/api/todo-items/{id}/status` | 更新待办状态 |
|
||||
| GET | `/api/troubleshooting-templates` | 获取排查模板列表 |
|
||||
| GET | `/api/troubleshooting-templates/{id}` | 获取排查模板详情 |
|
||||
| POST | `/api/troubleshooting-templates` | 新增排查模板（管理员） |
|
||||
| PUT | `/api/troubleshooting-templates/{id}` | 修改排查模板（管理员） |
|
||||
| DELETE | `/api/troubleshooting-templates/{id}` | 删除排查模板（管理员） |
|
||||
| PUT | `/api/employees/{id}/it-level` | 坐席手动调整 IT 等级 |
|
||||
|
||||
### 6.2 修改端点
|
||||
|
||||
| 方法 | 路径 | 变更说明 |
|
||||
|------|------|---------|
|
||||
| GET | `/api/conversations` | 响应新增 `impact_scope`, `is_blocking`, `emotion_state` 字段 |
|
||||
| GET | `/api/conversations/{id}` | 同上 |
|
||||
| GET | `/api/employees/{id}` | 响应新增 `it_level`, `it_level_source`, `notes` 字段 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 组件变更矩阵
|
||||
|
||||
| 组件 | 变更类型 | 说明 |
|
||||
|------|---------|------|
|
||||
| `Workspace.vue` | **重构** | 顶部栏独立为 `TopBar.vue`；移除应急模式横幅到 TopBar；三栏布局微调 |
|
||||
| `ConversationList.vue` | **重构** | 三段折叠替代原六段；搜索区增加筛选标签；底部新增待办事项面板 |
|
||||
| `ConversationItem.vue` | **修改** | 新增优先级图标渲染（⛔👥⭐🔁）；移除 IT 等级徽标 |
|
||||
| `ChatArea.vue` | **重构** | 顶部栏替换为 `UserInfoBar.vue`；底部新增 `TroubleshootBar.vue`；新增视图切换逻辑（聊天/任务详情） |
|
||||
| `AiAssistantPanel.vue` | **完全重写** | 移除 5 Tab，改为上下两区（AI 推荐 ~1/3 + 快速回复 ~2/3） |
|
||||
| `QuickReplyPanel.vue` | **重写** | 搜索栏置顶 + Alt 分类切换 + ↑↓ 键盘导航 + Enter 确认填入 + 底部键盘指南 |
|
||||
| `RiskAlert.vue` | **废弃** | 功能移除 |
|
||||
| `UserInfoPanel.vue` | **废弃** | 功能并入 `UserInfoBar.vue` |
|
||||
| `AiSuggestReply.vue` | **修改** | 移至右栏上方 AI 推荐区；增加置信度显示 + Ctrl 快捷键 |
|
||||
| `TopBar.vue` | **新增** | 独立顶栏组件（系统名称 + 主题切换 + 坐席信息 + 应急模式） |
|
||||
| `UserInfoBar.vue` | **新增** | 聊天区顶部用户信息栏（chips + 展开详情 6 卡片） |
|
||||
| `AiRecommendInline.vue` | **新增** | 聊天区内 AI 推荐回复（Ctrl+1/2/3 快捷填入） |
|
||||
| `TroubleshootBar.vue` | **新增** | 排查步骤栏（路径视图 + 可展开流程图） |
|
||||
| `TodoPanel.vue` | **新增** | 左栏底部待办事项面板 |
|
||||
| `TaskDetailView.vue` | **新增** | 中间栏任务详情视图（工单/审批/设备三种子视图） |
|
||||
| `ItLevelBadge.vue` | **新增** | IT 等级徽标组件（7 级段位 + 渐变配色 + 王者发光动画） |
|
||||
| `useKeyboardShortcuts.ts` | **新增** | 全局快捷键管理 composable |
|
||||
| `useTheme.ts` | **新增** | 主题切换 composable（CSS 变量 + localStorage 持久化） |
|
||||
| `stores/todo.ts` | **新增** | 待办事项 Pinia Store |
|
||||
| `stores/theme.ts` | **新增** | 主题 Pinia Store |
|
||||
| `api/todo.ts` | **新增** | 待办事项 API |
|
||||
| `api/troubleshooting.ts` | **新增** | 排查模板 API |
|
||||
|
||||
---
|
||||
|
||||
## 8. 待确认问题
|
||||
|
||||
| # | 问题 | 影响范围 | 建议 |
|
||||
|---|------|---------|------|
|
||||
| 1 | **情绪状态识别方式**：由 AI 自动分析消息内容识别，还是由坐席手动标记？ | BE-02, FE-04 | 建议先 AI 自动识别 + 坐席可手动修正 |
|
||||
| 2 | **影响范围数据来源**：是员工自行填写、系统自动判断（如根据部门人数），还是坐席标记？ | BE-02 | 建议坐席手动标记为主，后续迭代增加 AI 辅助判断 |
|
||||
| 3 | **排查模板与问题分类的关联**：排查模板如何匹配到当前会话？是按标签自动匹配还是坐席手动选择？ | BE-04, FE-06 | 建议 P0 坐席手动选择模板，P2 再做自动匹配 |
|
||||
| 4 | **待办事项与外部系统对接时机**：工单/审批/设备的真实系统 API 何时对接？ | BE-03 | 已确认 Mock 先行，前端 UI 做完整交互 |
|
||||
| 5 | **IT 等级在用户端显示方式**：用户端看到的 IT 等级是完整徽标还是简化文本？ | FE-04, BE-01 | 需与用户端（H5）产品确认 |
|
||||
| 6 | **同事会话区的数据筛选**：「同事会话」是显示所有其他坐席的进行中会话，还是仅显示同组/同部门坐席的？ | FE-02 | 建议先显示同组坐席，后续可配置 |
|
||||
| 7 | **排查步骤栏的高度**：排查步骤栏始终可见会占用聊天区空间，是否需要设置最小/最大高度？ | FE-06 | 参考原型：默认路径视图 ~44px，展开流程图最大 300px |
|
||||
| 8 | **AI 推荐回复的触发时机**：是每条用户消息后都触发，还是有条件触发？ | FE-05 | 已确认仅坐席未回复时显示 |
|
||||
| 9 | **原 6 区到 3 段的数据映射**：原"待接单"区并入"我的会话"还是独立显示？原"协作会话"区并入哪个段？ | FE-02 | 需确认分区数据映射规则 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 关键决策记录
|
||||
|
||||
| # | 决策 | 依据 |
|
||||
|---|------|------|
|
||||
| 1 | 外部系统对接 Mock 先行，前端 UI 做完整交互 | 避免被外部系统 API 阻塞前端开发进度 |
|
||||
| 2 | IT 等级采用混合模式（系统初评 + 坐席手动调整） | 系统自动评分不够准确，需坐席校准 |
|
||||
| 3 | 排查步骤数据源为静态模板库 | 预置常见问题模板即可满足 MVP，后续可扩展为动态生成 |
|
||||
| 4 | 右栏移除 5 Tab 结构，改为上下两区 | 原型验证：坐席主要使用 AI 推荐和快速回复，其他功能使用频率低 |
|
||||
| 5 | 会话列表不显示 IT 等级徽标 | 避免信息过载，IT 等级在聊天区详情展示更合适 |
|
||||
| 6 | 排查步骤栏整体不可收起 | 确保坐席始终能看到排查进度，避免遗漏步骤 |
|
||||
| 7 | 原型样式已锁定（v5.3 版），调整样式前必须与用户确认 | 保证开发产出与设计稿一致 |
|
||||
|
||||
---
|
||||
|
||||
## 10. 里程碑建议
|
||||
|
||||
| 阶段 | 范围 | 预估周期 |
|
||||
|------|------|---------|
|
||||
| **Phase 1 — 基础框架** | FE-01 主题系统 + FE-09 系统名称 + BE-01/02 模型扩展 + 数据库迁移 | 2-3 天 |
|
||||
| **Phase 2 — 左栏改造** | FE-02 三段折叠 + 优先级图标 + FE-03 待办面板 + BE-03 TodoItem API | 2-3 天 |
|
||||
| **Phase 3 — 中栏改造** | FE-04 用户信息栏 + FE-05 AI 推荐内联 + FE-06 排查步骤栏 | 3-4 天 |
|
||||
| **Phase 4 — 右栏改造** | FE-08 AI 助手面板重构 + BE-04 排查模板 API | 2-3 天 |
|
||||
| **Phase 5 — 任务视图** | FE-07 视图切换 + 工单/审批/设备 3 种子页面 | 2-3 天 |
|
||||
| **Phase 6 — 增强打磨** | FE-10 快捷键 + FE-11 IT 等级调整 + FE-12 过渡动画 + 联调测试 | 2-3 天 |
|
||||
@@ -0,0 +1,219 @@
|
||||
# wecom_it_smart_desk 目录清理报告
|
||||
|
||||
**执行时间**：2026-06-06 23:50
|
||||
**执行人**：AI Assistant
|
||||
**确认方式**：用户确认「全部执行（推荐）」
|
||||
|
||||
---
|
||||
|
||||
## 一、清理前后对比
|
||||
|
||||
| 指标 | 清理前 | 清理后 | 释放 |
|
||||
|------|--------|--------|------|
|
||||
| 总大小 | ~524 MB | ~25 MB | **~499 MB (95%)** |
|
||||
| 根目录文件数 | 102 个 | ~25 个 | -77 个 |
|
||||
| 子目录数 | 6 个 | 6 个（结构不变） | — |
|
||||
|
||||
---
|
||||
|
||||
## 二、已删除文件清单
|
||||
|
||||
### ✅ 类别 A：可重生成缓存/构建产物（~519 MB）
|
||||
|
||||
| 路径 | 大小 | 说明 |
|
||||
|------|------|------|
|
||||
| `itdesk-images.tar` | 222.74 MB | Docker 镜像，可重新 build |
|
||||
| `itdesk.tar.gz` | 1.50 MB | 项目归档，已过期 |
|
||||
| `frontend-agent/node_modules/` | ~125 MB | `npm install` 重装 |
|
||||
| `frontend-h5/node_modules/` | ~77 MB | `npm install` 重装 |
|
||||
| `backend/venv/` | ~94 MB | `python -m venv` 重建 |
|
||||
| `frontend-agent/dist/` | ~1.6 MB | `npm run build` 重建 |
|
||||
| `frontend-h5/dist/` | ~0.3 MB | `npm run build` 重建 |
|
||||
| `backend/__pycache__/` | ~0.03 MB | Python 字节码缓存 |
|
||||
| `frontend-agent/src/__pycache__/` | 少量 | Python 字节码缓存 |
|
||||
| `backend/.pytest_cache/` | ~0.03 MB | pytest 缓存 |
|
||||
|
||||
### ✅ 类别 B：空文件（0 字节，~10 个）
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `api_test_agent_conv.json` | 空文件 |
|
||||
| `backend_stderr.txt` | 空文件 |
|
||||
| `backend_stdout.txt` | 空文件 |
|
||||
| `npm_result.txt` ~ `npm_result3.txt` | 空文件 x3 |
|
||||
| `py_test.txt` ~ `py_test3.txt` | 空文件 x3 |
|
||||
| `syntax_check.txt` | 空文件 |
|
||||
|
||||
### ✅ 类别 C：根目录重复诊断/测试脚本（~50 个 .py）
|
||||
|
||||
删除了根目录下所有临时诊断/测试脚本，仅保留以下 5 个有用脚本并归档至 `scripts/archive/`：
|
||||
|
||||
**保留并归档至 `scripts/archive/`：**
|
||||
- `simulate_wecom_enhanced.py` — 企业微信模拟（增强版）
|
||||
- `simulate_wecom.py` — 企业微信模拟
|
||||
- `import_knowledge_base.py` — 知识库导入
|
||||
- `start_8001.py` — 启动 8001 端口
|
||||
- `analyze_report.py` — 报告分析
|
||||
|
||||
**已删除（重复/临时诊断脚本）：**
|
||||
- `diagnose.py`, `diagnose2.py`, `diag3.py`
|
||||
- `check_db.py`, `check_deps.py`, `check_syntax.py`, `check_tables.py`
|
||||
- `fix_messages_table.py`, `fix_sqlite_schema.py`
|
||||
- `run_tests.py`, `run_tests_v2.py`, `run_tests_direct.py`, `run_tests_temp.py`, `run_to_tests.py`, `run_final.py`, `run_inline.py`, `run_compact.py`, `run_pytest_inline.py`, `run_report.py`
|
||||
- `restart_and_test.py`, `restart_v4.py`, `restart_backend.ps1`, `start_and_test.py`, `start_backend.bat`
|
||||
- `test_api_debug.py`, `test_db_debug.py`, `test_direct.py`, `test_fe_build2.py`, `test_fe_build3.py`, `test_frontend_build.py`, `test_imports.py`, `test_install_ws.py`, `test_route.py`, `test_ws_check.py`, `test_ws_full.py`, `test_ws_functional.py`, `test_ws_prereq.py`, `test_ws_prereq2.py`, `test_ws_v3.py`, `test_ws_verification.py`
|
||||
- `extract_docx.py`, `kill_port.py`, `quick_test.py`, `import_test.py`
|
||||
|
||||
### ✅ 类别 D：后端根目录诊断脚本（~20 个 `_*.py`）
|
||||
|
||||
| 文件模式 | 说明 |
|
||||
|----------|------|
|
||||
| `_check_models.py`, `_crud_test.py`, `_debug_uuid.py` ... | 后端诊断脚本全部删除 |
|
||||
|
||||
### ✅ 类别 E：过期日志/输出文件（~20 个 .txt）
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `backend_log_8001.txt`, `backend_log.txt` | 后端日志（已过期） |
|
||||
| `fe_build_final.txt`, `fe_build_out.txt`, `fe_build_out2.txt` | 前端构建输出 |
|
||||
| `node_check.txt`, `node_test.txt`, `node_test2.txt` | Node 检查输出 |
|
||||
| `test_api_debug_results.txt`, `test_db_debug_results.txt` | 测试结果输出 |
|
||||
| `test_prereq_results.txt`, `test_ws_final_results.txt`, `test_ws_results.txt`, `test_ws_v3_results.txt` | 测试结果输出 |
|
||||
| `uvicorn_check.txt`, `uvicorn_exe_check.txt`, `uvicorn_ver.txt`, `uvicorn_ver2.txt` | Uvicorn 检查输出 |
|
||||
|
||||
### ✅ 类别 F：遗留系统代码（~2.3 MB）
|
||||
|
||||
| 路径 | 说明 |
|
||||
|------|------|
|
||||
| `docs/existing_system_code/` | 旧 Django 系统代码（本项目要替换的目标系统，非当前项目组成部分） |
|
||||
|
||||
---
|
||||
|
||||
## 三、保留文件清单
|
||||
|
||||
### 根目录（配置文件 + 文档 + 有用脚本）
|
||||
|
||||
| 文件 | 大小 | 说明 |
|
||||
|------|------|------|
|
||||
| `.env` | 2.8 KB | 根环境变量（docker-compose 用） |
|
||||
| `.env.example` | 2.7 KB | 环境变量模板 |
|
||||
| `.env.production` | 1.9 KB | 生产环境变量 |
|
||||
| `docker-compose.yml` | 6.7 KB | Docker Compose 配置 |
|
||||
| `README.md` | 7.4 KB | 项目说明 |
|
||||
| `ARCHITECTURE.md` | 79.9 KB | 架构文档 |
|
||||
| `PRD.md` | 36.0 KB | 产品需求文档 |
|
||||
| `QA_TEST_REPORT.md` | 11.3 KB | QA 测试报告（最新） |
|
||||
| `TESTING_CALL_AGENT.md` | 3.6 KB | 呼叫坐席测试文档 |
|
||||
|
||||
### `backend/` 目录（核心后端代码）
|
||||
|
||||
| 子目录 | 说明 |
|
||||
|----------|------|
|
||||
| `app/api/` | 15 个 API 路由模块 |
|
||||
| `app/models/` | 12 个 SQLAlchemy 模型 |
|
||||
| `app/schemas/` | 10 个 Pydantic schema |
|
||||
| `app/services/` | 11 个业务逻辑服务 |
|
||||
| `alembic/versions/` | 3 个数据库迁移 |
|
||||
| `tests/` | 15 个 pytest 测试文件 |
|
||||
| `it_smart_desk.db` | SQLite 数据库（304 KB） |
|
||||
| `.env`, `.env.example`, `requirements.txt` | 后端配置 |
|
||||
|
||||
### `frontend-agent/` 目录（坐席前端 Vue3）
|
||||
|
||||
| 子目录 | 说明 |
|
||||
|----------|------|
|
||||
| `src/views/` | Login.vue, Workspace.vue |
|
||||
| `src/components/chat/` | 12 个聊天相关组件 |
|
||||
| `src/components/assistant/` | 6 个 AI 辅助面板组件 |
|
||||
| `src/stores/` | 5 个 Pinia store |
|
||||
| `src/api/` | 8 个 API 模块 |
|
||||
| `src/data/` | 快速回复数据（qrData.ts） |
|
||||
|
||||
### `frontend-h5/` 目录（员工 H5 前端 Vue3 + Vant）
|
||||
|
||||
| 子目录 | 说明 |
|
||||
|----------|------|
|
||||
| `src/views/` | Login.vue, ChatView.vue |
|
||||
| `src/components/chat/` | 5 个聊天组件 |
|
||||
| `src/stores/` | 2 个 Pinia store |
|
||||
|
||||
### `docs/` 目录（项目文档）
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `01-项目总览与部署手册.md` | 部署手册 |
|
||||
| `团队沟通文档-架构消息知识库.md` | 架构设计 |
|
||||
| `摇人-多坐席协作-技术方案.md` | 协作方案 |
|
||||
| `正式环境独立部署架构方案.md` | 生产部署 |
|
||||
| `ARCHITECTURE-v53-incremental.md` | 增量架构 |
|
||||
| `PRD-v53-incremental.md` | 增量 PRD |
|
||||
| `*.mermaid` | 5 个架构图表 |
|
||||
| `现有系统交接文档内容.txt` | 遗留系统交接说明 |
|
||||
|
||||
### `scripts/` 目录（构建/部署脚本）
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `build.sh` | 构建脚本 |
|
||||
| `deploy.sh` | 部署脚本 |
|
||||
| `read_docx.py` | docx 读取工具 |
|
||||
| `archive/` | 5 个归档脚本 |
|
||||
|
||||
### `nginx/` 目录
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `nginx.conf` | 反向代理配置 |
|
||||
|
||||
---
|
||||
|
||||
## 四、迁移注意事项
|
||||
|
||||
### ✅ 迁移前需要重新生成的内容
|
||||
|
||||
| 内容 | 生成方式 |
|
||||
|------|----------|
|
||||
| `frontend-agent/node_modules/` | `cd frontend-agent && npm install` |
|
||||
| `frontend-h5/node_modules/` | `cd frontend-h5 && npm install` |
|
||||
| `backend/venv/` | `cd backend && python -m venv venv && .\venv\Scripts\activate && pip install -r requirements.txt` |
|
||||
| `frontend-agent/dist/` | `cd frontend-agent && npm run build` |
|
||||
| `frontend-h5/dist/` | `cd frontend-h5 && npm run build` |
|
||||
|
||||
### ⚠️ 迁移后需要检查/重新配置的项
|
||||
|
||||
1. **`.env` 文件**：数据库连接、Dify API Key、企业微信配置等敏感信息需要重新填写
|
||||
2. **`backend/.env`**：后端环境变量需要重新配置
|
||||
3. **`docker-compose.yml`**：服务器 IP、端口映射等可能需要调整
|
||||
4. **`nginx/nginx.conf`**：服务器域名/IP 可能需要调整
|
||||
|
||||
### 📦 建议迁移方式
|
||||
|
||||
**方式一：直接复制清理后的目录（推荐）**
|
||||
```bash
|
||||
# 清理后只剩 ~25 MB，直接打包迁移
|
||||
cd C:\Users\simon
|
||||
Compress-Archive -Path wecom_it_smart_desk -DestinationPath wecom_it_smart_desk_clean.zip
|
||||
```
|
||||
|
||||
**方式二：Git 克隆（如果已推送到远程仓库）**
|
||||
```bash
|
||||
git clone <repo_url> wecom_it_smart_desk_new
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、清理验证
|
||||
|
||||
执行以下命令验证清理结果：
|
||||
|
||||
```powershell
|
||||
# 查看总大小
|
||||
Get-ChildItem "C:\Users\simon\wecom_it_smart_desk" -Recurse -File -ErrorAction SilentlyContinue | Measure-Object -Property Length -Sum | Select-Object @{n="TotalMB";e={[math]::Round($_.Sum/1MB,2)}}
|
||||
|
||||
# 查看根目录文件（应该只剩配置文件+文档）
|
||||
Get-ChildItem "C:\Users\simon\wecom_it_smart_desk" -File | Format-Table Name, @{n="SizeKB";e={[math]::Round($_.Length/1KB,1)}}, LastWriteTime
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*清理报告结束*
|
||||
@@ -0,0 +1,125 @@
|
||||
# 企微IT智能服务台 — 第一步开发交付概览
|
||||
|
||||
## TL;DR
|
||||
|
||||
企微IT智能服务台第一步（消息接管 + 极简坐席台）全部代码已完成并通过测试，共 **110+ 文件**，**116/116 测试全部通过**，覆盖后端 API、坐席工作台、用户端 H5 三个子系统。
|
||||
|
||||
## 交付状态
|
||||
|
||||
| 阶段 | 状态 | 产出 |
|
||||
|------|------|------|
|
||||
| PRD | ✅ 完成 | `PRD.md` — 31 需求（P0/P1/P2），7 用户故事 |
|
||||
| 架构设计 | ✅ 完成 | `docs/ARCHITECTURE.md` — 9 表 DDL，7 API 组，4 时序图，5 任务分解 |
|
||||
| T01 项目脚手架 | ✅ 完成 | 57 文件 — docker-compose, nginx, .env, 后端/前端骨架 |
|
||||
| T02 后端核心服务 | ✅ 完成 | 16 文件 — 企微加解密, 消息路由, 评分, 会话, 趣味话术, 7 API 路由 |
|
||||
| T03 坐席工作台 | ✅ 完成 | 25 文件 — 三栏布局, 会话管理, 聊天, AI助手面板(5Tab) |
|
||||
| T04 用户端H5 | ✅ 完成 | 12 文件 — 聊天面板, 摇人按钮, AI助手, 审批链接, 软件下载 |
|
||||
| QA 测试用例 | ✅ 完成 | 8 文件, 116 测试用例（原 93 + 新增 23） |
|
||||
| Bug 修复 | ✅ 完成 | 7 个 Bug 修复（详见下方） |
|
||||
| PostgreSQL/SQLite兼容 | ✅ 完成 | 9 个模型文件全部兼容 SQLite |
|
||||
| database.py 懒加载 | ✅ 完成 | 避免测试导入时连接 PostgreSQL |
|
||||
| WecomCrypto 懒加载 | ✅ 完成 | 避免默认 AES Key 导入报错 |
|
||||
| **pytest 全量验证** | **✅ 116/116 通过** | 1.71 秒完成，0 失败 |
|
||||
|
||||
## 关键文件
|
||||
|
||||
```
|
||||
wecom_it_smart_desk/
|
||||
├── README.md # 项目主文档（GitHub 首页）
|
||||
├── docker-compose.yml # Docker Compose 容器编排
|
||||
├── .env # 环境变量（数据库密码等，不提交 Git）
|
||||
├── backend/ # FastAPI 后端服务
|
||||
│ ├── app/
|
||||
│ │ ├── main.py # FastAPI 应用入口
|
||||
│ │ ├── config.py # 配置管理（从 .env 读取）
|
||||
│ │ ├── database.py # 懒加载数据库引擎
|
||||
│ │ ├── models/ # 11 个 ORM 模型（兼容 PostgreSQL/SQLite）
|
||||
│ │ ├── schemas/ # Pydantic Schema（请求/响应校验）
|
||||
│ │ ├── utils/
|
||||
│ │ │ └── wecom_crypto.py # 企微消息加解密（AES-CBC-256）
|
||||
│ │ ├── services/
|
||||
│ │ │ ├── wecom_service.py # 企微回调处理
|
||||
│ │ │ ├── message_router.py # 消息路由 + 评分 + 举手检测
|
||||
│ │ │ ├── scoring_service.py # 紧急度评分引擎
|
||||
│ │ │ ├── session_service.py # 会话生命周期管理
|
||||
│ │ │ └── funny_phrase_service.py # 摇人趣味话术生成
|
||||
│ │ └── api/ # 8 个 API 路由模块
|
||||
│ └── tests/ # 116+ 个测试用例
|
||||
├── frontend-agent/ # 坐席工作台（Vue 3 + Element Plus）
|
||||
│ └── src/
|
||||
│ ├── views/ # LoginView + WorkspaceView
|
||||
│ ├── components/
|
||||
│ │ ├── TopBar/ # 顶部栏（主题切换 + 用户信息）
|
||||
│ │ ├── conversation/ # 会话列表 + 会话条目
|
||||
│ │ ├── chat/ # 聊天区 + 消息气泡 + 输入框
|
||||
│ │ ├── assistant/ # AI 推荐内联组件
|
||||
│ │ ├── troubleshooting/ # 排查步骤栏（FlowchartNode）
|
||||
│ │ ├── quickreply/ # 快速回复面板（三层导航）
|
||||
│ │ └── todo/ # 待办面板 + 任务详情视图
|
||||
│ ├── stores/ # Pinia Store（conversation/agent/quickReply/theme/todo）
|
||||
│ └── api/ # API 调用模块
|
||||
├── frontend-h5/ # 员工端 H5（Vue 3 + Vant）
|
||||
│ └── src/
|
||||
│ ├── views/ # ChatView
|
||||
│ └── components/ # ChatPanel + 摇人按钮 + AI助手
|
||||
├── nginx/ # Nginx 反向代理配置
|
||||
│ └── nginx.conf
|
||||
├── scripts/ # 部署和运维脚本
|
||||
│ ├── start_backend.bat # Windows 快速启动后端（相对路径）
|
||||
│ └── restart_backend.ps1 # Windows 重启后端（自动查找 PG/Redis/Python）
|
||||
└── docs/ # 项目文档（全部文档统一存放）
|
||||
├── PRD.md # 产品需求文档 v1.0
|
||||
├── PRD-v53-incremental.md # v5.3 增量需求
|
||||
├── ARCHITECTURE.md # 系统架构设计（合并版）
|
||||
├── 01-项目总览与部署手册.md # 管理者视角部署手册
|
||||
├── 开发交付概览.md # 开发交付状态总览
|
||||
├── IT智能服务台-项目迁移文档.md # 工作区迁移记录
|
||||
├── testing/ # 测试报告目录
|
||||
│ └── QA_COMPREHENSIVE_REPORT.md # 综合 QA 报告
|
||||
├── diagrams/ # Mermaid 图表
|
||||
│ ├── sequence-diagram.mermaid
|
||||
│ ├── sequence-shake.mermaid
|
||||
│ ├── sequence-scoring.mermaid
|
||||
│ ├── sequence-polling.mermaid
|
||||
│ └── class-diagram.mermaid
|
||||
└── prototypes/ # 原型文件
|
||||
├── agent-workspace-v5_3.html # 当前锁定版本（v5.3）
|
||||
├── qr_data_full.json # 快速回复数据（180条）
|
||||
└── archive/ # 历史原型归档
|
||||
```
|
||||
|
||||
## Bug 修复清单（7 个）
|
||||
|
||||
| # | 文件 | 问题 | 修复 |
|
||||
|---|------|------|------|
|
||||
| 1 | `message_router.py` | `calculate_urgency()` 是 async 但未 `await` | 添加 `await` |
|
||||
| 2 | `app/main.py` | 中文引号 `""` 嵌入 Python 双引号字符串，SyntaxError | 转义引号 |
|
||||
| 3 | `wecom_callback.py` | `WecomCrypto` 模块级初始化，默认 AES Key 不合法导致 `binascii.Error` | 改为懒加载单例 `_get_wecom_crypto()` |
|
||||
| 4 | `tests/conftest.py` | `aioredis.from_url` mock 路径错误 | 修正为 `redis.asyncio.from_url` |
|
||||
| 5 | `tests/conftest.py` | `create_test_conversation()` 缺少 `is_pinned`/`is_todo` 参数 | 添加可选参数 |
|
||||
| 6 | `session_service.py` | `conversation_id` UUID 对象 vs String(36) 列类型不匹配 | 先转字符串再查询 |
|
||||
| 7 | `scoring_service.py` | 关键词大小写不敏感缺失 + `_check_vip` 缺短路 | `.lower()` + 短路返回 |
|
||||
|
||||
## 用户下一步操作
|
||||
|
||||
1. **（已验证）pytest 全量通过**：116/116 测试已在开发环境验证通过，本地无需再跑
|
||||
|
||||
2. **配置企微应用凭证**：
|
||||
- 复制 `.env.example` 为 `.env`
|
||||
- 填入企微应用的 CorpID、AgentID、Secret、Token、EncodingAESKey
|
||||
|
||||
3. **Docker Compose 启动**（需 PostgreSQL + Redis）：
|
||||
```powershell
|
||||
cd C:\Users\simon\wecom_it_smart_desk
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
4. **前端开发启动**：
|
||||
```powershell
|
||||
# 坐席工作台
|
||||
cd frontend-agent && npm install && npm run dev
|
||||
# 用户端 H5
|
||||
cd frontend-h5 && npm install && npm run dev
|
||||
```
|
||||
|
||||
5. **企微回调配置**：在企微管理后台配置消息回调 URL 指向你的服务器
|
||||
Reference in New Issue
Block a user