wecom_it_smart_desk/docs/IT智能服务台-项目迁移文档.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 顺序

<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 单行布局）

<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 用户信息栏展开箭头

.user-info-bar.expanded .expand-icon {
  transform: rotate(90deg);   /* ▶ 旋转后变成 ▼ */
}

<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）

新项目中需要重新执行：

# 后端
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 的所有工作内容。