docs/IT%E6%99%BA%E8%83%BD%E6%9C%8D%E5%8A%A1%E5%8F%B0-%E9%A1%B9%E7%9B%AE%E8%BF%81%E7%A7%BB%E6%96%87%E6%A1%A3.md

# IT智能服务台 — 项目迁移文档
**生成时间**：2026-06-06  
**来源项目**：`C:\Users\simon\wecom_it_smart_desk`  
**原型文件**：`C:\Users\simon\WorkBuddy\2026-05-21-16-57-26\agent-workspace-v5_3.html`

---

## 一、项目概览

| 项目 | 路径 | 技术栈 |
|------|------|---------|
| 后端 | `C:\Users\simon\wecom_it_smart_desk\backend` | Python 3.12 + FastAPI + SQLAlchemy |
| 前端（坐席工作台） | `C:\Users\simon\wecom_it_smart_desk\frontend-agent` | Vue 3 + TypeScript + Vite + Element Plus + Pinia |
| 原型 HTML | `C:\Users\simon\WorkBuddy\2026-05-21-16-57-26\agent-workspace-v5_3.html` | 单文件，v5.3 定版 |
| 服务器 | `10.80.0.129` | Docker Compose (postgres + redis + backend + nginx) |

---

## 二、锁定的设计决策（迁移后必须遵守）

### 2.1 原型规范
- ✅ **原型 v5.3 已锁定**（`agent-workspace-v5_3.html`），调整样式前必须与用户确认
- ✅ 用户偏好**深色科技风 UI**，原型**必须使用中文**
- ✅ 所有修改基于现有面板内调整，**不另开新页面**
- ✅ 聊天区域应缩小，给侧栏更多空间

### 2.2 布局架构（三栏）
```
┌──────────┬────────────────────────┬──────────────┐
│  左栏     │       中栏              │  右栏          │
│  (240px) │   (flex:1 自适应)     │  (320px)      │
│          │                        │                │
│ 会话列表  │  UserInfoBar          │  AI 智能推荐   │
│ 搜索框    │  TroubleshootBar      │  快速回复       │
│ 待办事项  │  消息列表             │  (三层导航)    │
│          │  ReplyBox (输入框)     │                │
└──────────┴────────────────────────┴──────────────┘
```

### 2.3 关键交互规则
| 功能 | 规则 |
|------|------|
| 排查步骤栏 | 始终可见（不可收起），位于 UserInfoBar 下方、消息列表上方 |
| 全流程图 | 默认收起，通过 `▶` / `▼` 三角图标切换 |
| 用户信息栏展开箭头 | 收起 `▶`（向右）→ 展开 `▼`（向下，CSS `rotate(90deg)`） |
| AI 推荐 | **仅在右边栏**，不在中间栏内联显示 |
| 快速回复 | 三层渐进导航：L1(7列grid) → L2(chip流式) → L3(列表) |
| 主题切换 | 浅色(`:root`) / 深色(`[data-theme="dark"]`) 双主题 |
| 输入框 | `resize: vertical` 手动拖拽 + `autosize` 最大 8 行 + `max-height: 200px` |

---

## 三、原型 v5.3 布局细节（已确认的终版）

> **文件**：`C:\Users\simon\WorkBuddy\2026-05-21-16-57-26\agent-workspace-v5_3.html`

### 3.1 中间栏（center-column）DOM 顺序
```html
<div class="center-column">
  <div class="chat-view">              <!-- 整个聊天视图容器 -->
    <div class="user-info-bar">        <!-- 用户信息栏（含6卡片展开详情） -->
    <div class="user-detail-panel">    <!-- 展开详情（默认收起） -->
    <div class="troubleshoot-bar" id="tsBar">  <!-- 排查步骤（紧跟用户信息栏） -->
      <div class="ts-header">          <!-- 标题行：[🔧 排查步骤] [①→②→③→④→⑤] [▶] -->
    <div class="chat-messages">        <!-- 消息列表 -->
    <div class="chat-input-area">      <!-- 输入框区域 -->
      <textarea autosize maxRows=8 resize=vertical>
  </div>                              <!-- chat-view 闭合标签 -->
  <div class="sidebar-right">          <!-- 右边栏（AI推荐 + 快速回复） -->
</div>
```

### 3.2 排查步骤栏（ts-header 单行布局）
```html
<div class="ts-header">
  <span class="ts-title">🔧 排查步骤</span>
  <el-select>...</el-select>           <!-- 模板选择下拉 -->
  <div class="ts-path-inline">         <!-- 内联路径步骤 -->
    <span class="path-step-inline done">① 确认版本</span>
    <span class="path-arrow-inline">→</span>
    ...
  </div>
  <span class="ts-flowchart-toggle">▶</span>  <!-- 三角切换图标 -->
</div>
```

### 3.3 用户信息栏展开箭头
```css
.user-info-bar.expanded .expand-icon {
  transform: rotate(90deg);   /* ▶ 旋转后变成 ▼ */
}
```
```html
<span class="expand-icon">▶</span>  <!-- 收起时向右，展开时向下 -->
```

---

## 四、Vue 3 项目 — 已修改文件清单

### 4.1 核心视图
| 文件 | 修改内容 |
|------|---------|
| `src/views/Workspace.vue` | `onMounted` 添加 `fetchConversations()` + 自动选第一个会话；`assistantVisible` 默认 `true` |
| `src/components/chat/ChatArea.vue` | 移除 `AiRecommendInline`；`TroubleshootBar` 位置调整到 `UserInfoBar` 下方；移除重复的第一个 `TroubleshootBar` |

### 4.2 聊天组件
| 文件 | 修改内容 |
|------|---------|
| `src/components/chat/UserInfoBar.vue` | 展开箭头 `▶` → `▼`（rotate 90deg），之前方向反了 |
| `src/components/chat/TroubleshootBar.vue` | 路径步骤合并到标题行；展开按钮简化为三角 `▶`/`▼` |
| `src/components/chat/ReplyBox.vue` | `autosize` 上限 4→8 行；`resize: none` → `resize: vertical`；支持手动拖拽 |
| `src/components/chat/AiRecommendInline.vue` | 已从 `ChatArea.vue` 移除引用（AI推荐仅保留右边栏） |

### 4.3 右边栏组件
| 文件 | 修改内容 |
|------|---------|
| `src/components/assistant/AiAssistantPanel.vue` | 右边栏主容器（AI推荐 + 快速回复） |
| `src/components/assistant/QuickReplyPanel.vue` | 三层渐进导航，L1 七类，数据源 `src/data/qrData.ts` |
| `src/components/assistant/RiskAlert.vue` | 风险告警组件 |
| `src/components/assistant/OperationSteps.vue` | 操作步骤组件 |

### 4.4 状态管理（Stores）
| 文件 | 修改内容 |
|------|---------|
| `src/stores/conversation.ts` | `fetchConversations()` DEV 环境 Mock 兜底；自动选中第一个会话 |
| `src/stores/agent.ts` | `initAuth()` 检查 localStorage token |
| `src/stores/todo.ts` | 待办事项 Mock 数据 |
| `src/composables/useWebSocket.ts` | WebSocket 直连后端 `ws://localhost:8000/ws/{agentId}` |

### 4.5 样式
| 文件 | 修改内容 |
|------|---------|
| `src/styles/global.css` | `.reply-box .el-textarea__inner { max-height: 200px; }`；`.message-list-scroll { flex: 1; overflow-y: auto; }` |

### 4.6 数据
| 文件 | 说明 |
|------|------|
| `src/data/qrData.ts` | 快速回复 180 条（7大类 × 28子类），TypeScript 类型化 |

---

## 五、后端关键修改（参考）

> 路径：`C:\Users\simon\wecom_it_smart_desk\backend`

| 文件 | 修改内容 |
|------|---------|
| `app/services/session_service.py` | `get_conversations()` 排序改为 Python 侧（SQLite 不支持 JSONB 操作符） |
| `app/main.py` | 添加 `dify_conversation_id` 列（PostgreSQL） |
| `app/models/todo_item.py` | TodoItem 模型 |
| `app/models/troubleshooting_template.py` | TroubleshootingTemplate 模型 |

---

## 六、已修复的关键 Bug（迁移后注意）

### Bug 1：会话列表不显示 / 页面空白
**根因**：`Workspace.vue` `onMounted` 未调用 `fetchConversations()`，`currentConversation` 始终为 `null`，`ChatArea` 不渲染。  
**修复**：`onMounted` 中添加 `await conversationStore.fetchConversations()` + 自动选中第一个会话。

### Bug 2：AI 推荐同时出现在中间栏和右边栏
**根因**：`ChatArea.vue` 中引入了 `<AiRecommendInline />` 组件。  
**修复**：移除 `ChatArea.vue` 中的 `AiRecommendInline` 模板、import、ref、`onAiRecommend` 快捷键绑定。

### Bug 3：原型 HTML 右边栏显示在中栏内部
**根因**：`<div class="chat-view">` 缺少 `</div>` 闭合标签，浏览器把 `sidebar-right` 解析为 `center-column` 的子元素。  
**修复**：在 `chat-input-area` 关闭后补 `</div>` 闭合 `chat-view`。

### Bug 4：排查步骤栏出现两个（上下重复）
**根因**：`ChatArea.vue` 模板里有两个 `<TroubleshootBar />`（一个在 UserInfoBar 下方，一个在 ReplyBox 下方）。  
**修复**：删除 ReplyBox 下方的重复 `<TroubleshootBar />`。

### Bug 5：用户信息栏展开箭头方向反了
**根因**：收起时 `▼`，展开时 `▲`（CSS `rotate(180deg)`）。  
**修复**：收起 `▶`，展开 `▼`（CSS `rotate(90deg)`）。

### Bug 6：会话列表 API 500 错误
**根因**：`session_service.py` 用 SQL 侧 `case()` + `tags["hand_raise"].as_boolean()` 排序，SQLite 不支持 JSONB 操作符。  
**修复**：排序改为 Python 侧 `_sort_key()` 函数实现。

---

## 七、服务器部署状态

| 项目 | 状态 |
|------|------|
| 服务器地址 | `10.80.0.129` |
| Docker Compose 容器 | `postgres`, `redis`, `backend`, `nginx` |
| nginx | 已修复 301 重定向和 API 双重前缀问题 |
| PostgreSQL | 已添加 `dify_conversation_id` 列 |
| Redis | `it-desk-redis` 容器中运行中 |

---

## 八、知识库

| 项目 | 状态 |
|------|------|
| 数据源 | `IT支持知识库2026-4-24.docx` |
| 快速回复条数 | 180 条（7大类 × 28子类） |
| 前端数据文件 | `frontend-agent/src/data/qrData.ts` |
| 原型数据文件 | `agent-workspace-v5_3.html` 内联（因 file:// CORS 限制） |

---

## 九、迁移 checklist

### 备份这些文件/目录：
```
# 原型
C:\Users\simon\WorkBuddy\2026-05-21-16-57-26\agent-workspace-v5_3.html

# 前端项目（整体复制）
C:\Users\simon\wecom_it_smart_desk\frontend-agent\

# 后端项目（整体复制）
C:\Users\simon\wecom_it_smart_desk\backend\

# 项目记忆（WorkBuddy）
C:\Users\simon\WorkBuddy\2026-05-21-16-57-26\.workbuddy\memory\
```

### 新项目中需要重新配置：
- [ ] `.env` 文件（数据库连接、Redis、Dify API Key）
- [ ] `vite.config.ts` 中的 proxy 端口（当前 `5174`）
- [ ] Docker Compose 环境变量
- [ ] 服务器部署配置（`10.80.0.129`）

### 新项目中需要重新执行：
```bash
# 后端
cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
# 初始化数据库
alembic upgrade head   # 或 python -m app.db.init_db

# 前端
cd frontend-agent
npm install
npm run dev   # → http://localhost:5174/itagent/workspace
```

---

## 十、待完成任务（迁移后继续）

- [ ] 重启 dev server 验证所有修改已生效（当前修改已保存，需 Ctrl+C → npm run dev）
- [ ] 后端 AI 集成（Dify）代码修复（T02 任务）
- [ ] 前端方案评估（T03/T04）
- [ ] 企微回调服务器对接
- [ ] 生产环境部署验证

---

*此文档由 WorkBuddy 自动生成，汇总了 2026-05-21 至 2026-06-06 的所有工作内容。*