wecom_it_smart_desk/.workbuddy/memory/2026-06-23.md

# 2026-06-23 工作日志

## 修复截图发送超时Bug

### 问题分析
截图发送流程：html2canvas截取 → 裁剪选区 → 上传图片(60s超时) → 发送消息(10s超时)
- 前端 apiClient 默认超时10秒，对图片/文件消息发送过短
- 坐席端发消息时，即使是image类型也创建Redis连接（不必要）
- H5端消息发送会触发AI/Dify处理，可能超过10秒

### 修改内容

**前端（4个文件）：**
1. `frontend-agent/src/api/message.ts` — sendMessage 超时 10s→30s
2. `frontend-h5/src/api/conversation.ts` — sendMessage 超时 10s→30s
3. `frontend-agent/src/api/index.ts` — apiClient 默认超时 10s→20s
4. `frontend-h5/src/api/index.ts` — apiClient 默认超时 10s→20s

**后端（1个文件）：**
5. `backend/app/api/messages.py` — 非text消息跳过Redis连接（image/file等不调用企微API推送）

### 编译验证
- frontend-agent: vite build ✅ (4.63s)
- frontend-h5: vite build ✅ (1.75s)
- backend: py_compile ✅

---

## 修复员工端消息不显示Bug + 后端WS广播

### 问题分析
用户报告：员工端消息发送后没有出现在会话列表里。

**根因发现**：
1. **字段名不匹配**：后端 MessageResponse 返回 `id`/`sender_type`，但 H5 前端 Message 接口期望 `message_id`/`message_type`
2. **Vue 渲染失败**：`MessageBubble` 使用 `:key="msg.message_id"`，但后端返回的是 `id`，导致所有 key 为 undefined
3. **消息类型丢失**：`message_type` 为 undefined，CSS class 错误（如 `message-bubble--undefined`）
4. **WS handleNewMessage 错误**：使用了 `data.msg_type`（content type: text/image/file）而非 `data.sender_type`（sender type: employee/agent/ai）

### 修改内容

**H5前端（2个文件）：**
1. `frontend-h5/src/api/conversation.ts` — 新增 `mapMessage()`/`mapMessages()` 映射函数：
   - `id` → `message_id`
   - `sender_type` → `message_type`
   - `sendMessage()` 和 `pollMessages()` 返回数据经过映射

2. `frontend-h5/src/stores/conversation.ts` — 修复 `handleNewMessage()`：
   - `message_type` 从 `data.msg_type`（text/image）改为 `data.sender_type`（employee/agent/ai）
   - 同时正确映射 `msg_type`（content type）

**后端（1个文件）：**
3. `backend/app/api/h5.py` — 新增 WebSocket 广播：
   - 导入 `ws_manager`
   - 员工发消息后向坐席端推送 `new_message` 事件（用户消息 + AI回复）
   - 同时推送 `conversation_updated` 事件（状态变更）
   - 异常捕获：WS广播失败不阻塞消息存储

### 核心原理
后端 `MessageResponse` schema（`app/schemas/message.py`）定义的字段名是 `id`/`sender_type`，这是与坐席端（Agent）对齐的格式。H5 前端有自己独立的 `Message` 接口（`message_id`/`message_type`），需要在 API 层做字段映射。

### 编译验证
- frontend-h5: vite build ✅ (1.70s)
- backend: py_compile ✅

### 服务重启
- 使用 `uvicorn app.main:app --reload` 重启后端
- 工作目录：`D:\资料\03-项目开发\wecom_it_smart_desk\backend`

### 启动问题修复
重启过程中遇到多个问题并逐一修复：

1. **slowapi 模块缺失** → 安装 `slowapi==0.1.9`
2. **slowapi 0.1.9 不支持 `env_file` 参数** → 移除 `env_file=None`（3个文件）
   - `backend/app/api/agents.py`
   - `backend/app/api/h5.py`
   - `backend/app/main.py`
3. **缺少依赖注入函数** → 在 `dependencies.py` 中新增：
   - `get_shared_redis()` / `get_shared_wecom_service()` / `get_shared_ai_handler()`
   - `dep_redis()` / `dep_wecom_service()` / `dep_ai_handler()` / `dep_wingman_service()`
   - `init_shared_services()` / `cleanup_shared_services()`
4. **RateLimitExceeded 异常处理器中 `Request` 未定义** → 移除类型注解

### 服务状态
- ✅ FastAPI 已启动，运行在 `http://0.0.0.0:8000`
- ✅ 98 个路由已注册
- ✅ SQLite 数据库初始化完成
- ✅ 默认数据初始化完成

---

## Phase 2 路由选择页（Portal）构建与集成

### 背景
`frontend-portal/` 和 `backend/app/api/portal.py` 的代码已经写好，需要构建和集成。

### 已完成工作
1. **Portal 前端构建**：`npm install` + `vite build` ✅ (4.65s)
2. **PortalSelect.vue 增强**：添加 OAuth2 `?code=` 参数处理（调用 `/h5/oauth/callback` 获取 token）
3. **坐席端适配**（已完成）：路由守卫读取 `?token=` 参数，保存到 `agent_token` + `portal_token`
4. **H5端适配**（已完成）：路由守卫读取 `?token=` 参数，保存到 `h5_token`
5. **全量编译验证**：
   - frontend-portal: vite build ✅ (4.65s)
   - frontend-h5: vite build ✅ (2.00s)
   - frontend-agent: vite build ✅ (5.56s)
   - backend portal.py: py_compile ✅
   - backend h5.py: py_compile ✅

### 完整认证流程
1. 用户通过企微工作台点击 IT智能服务台 → 跳转到 `/itportal/`
2. Portal 检测到 `?code=xxx`（OAuth2 回调）→ 调用后端获取 token → 保存到 localStorage
3. Portal 调用 `/api/portal/roles` 获取用户角色列表
4. 如果仅 user 角色 → 自动跳转 `/itdesk/`；多角色 → 显示卡片选择页
5. 用户点击"进入" → Portal 将 token 通过 `?token=xxx` 传递到目标前端
6. 目标前端路由守卫读取 token → 保存到各自的 localStorage key → 正常工作

### Portal 服务配置
- Base path: `/itportal/`
- 开发端口: 5176
- 构建产物: `frontend-portal/dist/`
- 端口映射: 5173(坐席), 5174(H5), 5175(管理), 5176(Portal)

### Phase 2 部署配置完成

**Nginx 配置更新：**
- `nginx/nginx.conf` — 添加 `/itportal/` 路由（本地开发版）
- `deploy-server/nginx.conf` — 添加 `/itportal/` 路由 + 默认路径重定向到 `/itportal/`

**部署脚本更新：**
- `deploy-server/deploy.sh` — 添加 portal 前端部署步骤 + 数据库迁移步骤

**角色管理脚本：**
- `backend/scripts/init_roles.py` — 初始化三个默认角色（user/agent/admin）
- `backend/scripts/assign_role.py` — 用户角色分配/移除/查看工具

**本地开发脚本：**
- `scripts/dev-portal.sh` — Linux/Mac 快速启动脚本
- `scripts/dev-portal.ps1` — Windows PowerShell 快速启动脚本

**数据库状态：**
- roles 表已初始化（3条：user/agent/admin）
- user_roles 表已创建
- 角色分配脚本已测试通过

---

## 部署包打包完成

### 构建结果
- H5 前端: vite build ✅ (1.85s)
- Agent 前端: vite build ✅ (5.12s)
- Admin 前端: vite build ✅ (5.81s)
- Portal 前端: vite build ✅ (4.32s)

### 部署包
- 路径: `deploy-packages/it-smart-desk-deploy-20260613_102148.tar`
- 内容: 4个前端 dist + deploy.sh + nginx.conf + backend-scripts/
- 打包脚本: `deploy-packages/build-and-package.ps1`

### 部署步骤
1. 通过堡垒机上传 tar 包到服务器 `/tmp/`
2. 在服务器执行: `cd /tmp && tar -xf it-smart-desk-deploy-*.tar`
3. 执行部署脚本: `./deploy.sh`
4. 数据库迁移: `cd /opt/wecom-it-desk/backend && alembic upgrade head && python scripts/init_roles.py`
5. 角色分配: `python scripts/assign_role.py <employee_id> agent`