wecom_it_smart_desk/.workbuddy/memory/MEMORY.md

# IT智能服务台 - 项目记忆

## 锁定的设计决策
- **AI交互原则**：小段多回合交互，禁止一次性大段回复
- **文档管理**：统一保存 `docs/` 目录，按类型分子目录
- **资源申请流程**：所有资源申请→`docs/资源申请清单.md`
- **原型已锁定**：坐席v5.3 + H5 v1.1
- **UI偏好**：企微浅色扁平风格，accent=#07C160
- **术语统一**："人工"=用户呼叫坐席；"摇人"=坐席呼叫坐席
- **双企微应用**：正式(itsupport.servyou.com.cn) + 测试(已下线)
- **统一入口架构**：`/itportal/` 角色选择 → user/agent/admin
- **OTP双因素认证**：admin角色访问时验证

## 技术架构
- **前端**：坐席(Vue3+Element Plus) / H5(Vue3+Vant4) / 管理后台(Vue3+Element+Tailwind)
- **后端**：FastAPI + SQLAlchemy + PostgreSQL + Redis
- **本地开发**：Python 3.12 venv + SQLite
- **字段映射**：后端`id`/`sender_type` → H5前端`message_id`/`message_type`，映射层在 `frontend-h5/src/api/conversation.ts` 的 `mapMessage()`
- **WS广播**：H5发消息后通过 `ws_manager.broadcast()` 实时推送给坐席
- **API超时**：默认20s，消息发送30s，文件上传60s

## 部署
- **NAS测试**：~~itdesk.amanzac.com~~ (已下线)
- **正式服务器**：itsupport.servyou.com.cn (10.90.5.110)
- **堡垒机**：sxn@10.212.189.210:2222 (OTP)
- **文件上传**：只能通过堡垒机手动上传到 `/tmp/`

## 外部系统集成
- **火绒企业版**：HMAC-SHA1认证，核心接口 `_leak`(高危漏洞) / `_virus_events`(病毒事件)
- **联软LV7000**：三层认证，核心价值 `strusername` 字段=员工→终端映射
- **Dify**：生产 `http://yw-dify.dc.servyou-it.com/dify2openai/`
- **RAGFlow**：生产 `http://10.80.0.85:8080/` / API `:9380`
- **aTrust**：HMAC-SHA256，待获取API密钥
- **映射策略**：联软(主) > aTrust(VPN辅) > eHR(静态)

## 管理后台
- 路由前缀 `/api/admin/`；权限 require_admin
- 已实现：仪表盘/功能开关/坐席管理/分配模式/快速回复审核/集成配置/会话监控/会话审计/坐席绩效/系统日志/角色管理
- 集成三种配置模式：url_key / access_key / account_password

## H5端消息推送
- 双通道：企微消息(必达) + WebSocket(即时)
- WS端点：`/ws/h5/{employee_id}?token=xxx`
- 降级策略：WS断连→3秒轮询
- **本地消息缓存 (v0.7.4+)**：
  - 登录后优先加载本地缓存消息，立即显示历史记录
  - 同时异步从后端获取最新消息，合并去重后更新缓存
  - 缓存key：`h5_messages_cache`，有效期7天，最多100条/会话
  - 发送消息和轮询时自动更新缓存
  - 登出时清除缓存

## 近期问题修复 (2026-07)
- **OAuth重定向计数残留**：页面刷新后`oauth_redirect_count`未重置，导致误报"登录状态异常" → 在`employee.ts` store初始化时检测有效token后自动清除计数
- **API响应解析错误**：Axios拦截器返回`{code:0, data:{}, message}`包装格式，但部分API直接访问`response.xxx`而非`response.data.xxx` → 修正`conversation.ts`中`sendMessage`函数的响应映射
- **数据库缺失列**：`messages`表缺少`is_recalled`列 → `ALTER TABLE messages ADD COLUMN IF NOT EXISTS is_recalled BOOLEAN DEFAULT FALSE;`
- **数据库列类型错误**：`messages.id`列为uuid类型但代码传入varchar → `ALTER TABLE messages ALTER COLUMN id TYPE character varying(36);`
- **Nginx部署目录**：构建产物上传到`/opt/wecom-it-desk/frontend-h5/`但nginx挂载在`/opt/wecom-it-desk/html/itdesk/` → 部署时需复制文件到正确目录

## 五阶段演进
1. MVP：转人工+H5+坐席+邀请+管理后台
2. 完整流程：WS+排队+满意度+OAuth2
3. AI Wingman+排查流程图
4. 知识库+数据看板
5. 自动化闭环

## 堡垒机运维 (jumpserver-ops)

**脚本位置**：`C:\Users\simon\.workbuddy\skills\jumpserver-ops\scripts\jms_ops.py`

### ⚠️ 服务器操作规则（重要）

**在对服务器进行任何操作时，优先使用 jumpserver-ops 自动完成，而非让用户手动操作。**

| 操作类型 | 自动执行方式 |
|----------|-------------|
| 远程命令 | `python jms_ops.py exec -c "命令"` |
| 文件上传 | `python jms_ops.py upload 本地文件 /tmp/远程路径` |
| 文件下载 | `python jms_ops.py download /tmp/远程文件 ./本地路径` |

### 使用方式

```bash
# 第一次执行（自动登录并缓存会话）
python jms_ops.py exec -c "hostname"

# 连续测试：使用 --reuse 复用会话（30分钟内有效，2-3秒执行）
python jms_ops.py exec -c "uptime" --reuse
python jms_ops.py exec -c "docker ps" -c "curl -s http://localhost/api/health" --reuse

# 文件上传（自动根据大小选择方式）
# - ≤10MB: base64 编码传输（快速）
# - >10MB: elFinder Web UI（浏览器自动化）
python jms_ops.py upload local_file.txt /tmp/remote_file.txt

# 文件下载
python jms_ops.py download /tmp/remote_file.txt local_file.txt

# 批量命令
python jms_ops.py batch -f commands.txt

# 文件传输
python jms_ops.py upload local.conf /tmp/remote.conf
python jms_ops.py download /remote/path ./local.conf
```

### 性能

| 场景 | 首次执行 | --reuse 复用 |
|------|----------|--------------|
| 单命令 | ~13s | ~2s |
| 3 条命令 | ~13s | ~3s |

### 关键参数
- `--reuse`：复用上次会话（减少登录次数，30分钟有效）
- `--parallel`：并行模式（每命令独立 token+会话）
- `--cmd-timeout`：每命令超时秒数（默认 15s）

## 文档关联修复 (2026-07-05)
- **起因**：2026-07-04 docs/ 重组为数字编号子目录（01-项目总览~11-历史归档），但 mkdocs.yml nav / 文档间交叉引用 / 巡检自动化路径未同步，全面断链
- **修复**：mkdocs.yml nav 9处断链重写（移除2个归档项，纳入5份新文档）+ 11处交叉引用修复 + 索引版本号修正(v1.0→v1.3) + 巡检自动化适配
- **关键发现**：巡检 automation-1782986180887 原依赖的"小组任务书/任务执行状态看板.md"及A/B/C三组体系（认证加固16/消息系统16/AI数据19）从未创建，每日巡检必然失败；已适配为基于 01-项目状态看板.md 的状态巡检（P0/P1/等决策/进行中）
- **修复报告**：docs/01-项目总览/文档关联修复报告-20260705.md
- **保留未改**：目录树展示（历史快照）、归档文档内旧路径、历史任务标题