wecom_it_smart_desk/docs/archive/PRD-v53-incremental.md

# 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 天 |