Simon
259 lines
10 KiB
Markdown
259 lines
10 KiB
Markdown
# 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 的所有工作内容。*
|