wecom_it_smart_desk/.workbuddy/memory/MEMORY.md

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

## 设计决策（锁定）
- AI交互：小段多回合；术语："人工"=用户呼叫坐席，"摇人"=坐席呼叫坐席
- 原型：坐席v5.3 + H5 v1.1；UI：企微浅色扁平，accent=#07C160
- 统一入口 `/itportal/` → user/agent/admin；admin需OTP

## 技术架构
- 前端：坐席(Vue3+Element Plus) / H5(Vue3+Vant4) / 管理后台(Vue3+Element+Tailwind)
- 后端：FastAPI + SQLAlchemy + PostgreSQL + Redis（代码在 `app/`）
- 字段映射：后端`id`/`sender_type` → 前端`message_id`/`message_type`（`conversation.ts` 的 `mapMessage()`）
- WS双连接池：`active_connections`(agent) + `employee_connections`(H5)

## 部署
- 正式服务器：itsupport.servyou.com.cn (10.90.5.110)，出口IP `218.75.34.87`
- 堡垒机：sxn@10.212.189.210:2222 (OTP)，脚本 `C:\Users\simon\.workbuddy\skills\jumpserver-ops\scripts\jms_ops.py`
- 后端卷挂载：`./app:/app/app`，`.py`变更→`docker compose restart backend`；env变更→`up -d backend`
- 前端：rm旧→tar解压dist/→`restart nginx`；Nginx: H5→`/html/h5` / Agent→`/html/itagent` / Admin→`/html/itadmin`
- Docker bind mount铁律：rm后重建必须重启容器
- 部署工具：`jms_ops.py pack-upload <local_dir> <remote_dir>`（≥100KB用此）
- httpx.Timeout须含default：`httpx.Timeout(timeout=30.0, connect=10.0, read=30.0)`

## 外部集成
- 企微通讯录：Secret `BM6iosc3gKnPqkEXmsQN3ErJUpfO-whfMUN646eezB8`，Redis key=`wecom:contact_access_token`
- Dify：`http://yw-dify.dc.servyou-it.com/v1/chat-messages`；审批意图Key `app-7jkRkAzvX4QM9v9SM3P8mMEO`
- RAGFlow：生产 `http://10.80.0.85:8080/` / API `:9380`
- 映射策略：联软(主) > aTrust(VPN) > eHR(静态)

## 群聊系统
- 摇人(`collaborating_agent_ids`) / 邀请(`participants`)；四角色权限
- 参与者展开/缩略双模式；头像代理 `/api/avatar/proxy` 解决 COEP/CSP

## 审批流程系统（2026-07-10上线）
- 12种审批类型 / 18个流程；意图识别三级链路：关键词→Dify→降级
- 卡片导航用 `window.location.href`（同窗口）

## 代办事项真实数据源集成（2026-07-11部署+修复完成）
- **PRD**：`docs/02-产品需求/prd_todo_integration.md`
- **后端**：`todo_source_service.py` / `itsm_service.py` / `todo_aggregator_service.py`(Redis缓存45s)
- **前端**：`TodoPanel.vue` / `todo.ts`(API+Store)
- **企微审批API**：`getapprovalinfo`（旧`getapprovaldata`已废弃404）→ Semaphore(10)并发`getapprovaldetail` → 代码层过滤template_id
- **Token方案**：统一用 `TokenManager`（IT支持应用Secret，IP已在白名单）
- **缓存策略**：初始+60s自动=用缓存(无_force) / 手动🔄=跳过缓存(_force=1) / TTL=45s
- **8个Bug修复链**：env未注入→Redis密码→bind mount丢失→API废弃→token decode→IP白名单60020→filter参数301025→**_extract_current_approver字段名全错**
- **企微API实际字段名**（dump确认）：`sp_record[].sp_status`（非status）/ `details[].approver.userid`（非approver[].userid）
- **验证**：sxn名下2条审批单正确返回（IT资产外修申请）
- **ITSM**：工单详情API已实现，代办列表API待抓包；签名 app_id+app_secret+SHA1
- **测试**：40/40通过

## IT资产升级审批推送（待部署）
- 模板ID：`Bs7ucTGsPuFhxfk8pn8EydxrWxkVetB4JR8Pb6PHS`
- 新建 `asset_service.py`；修改 `approval.py`(+urge端点) / `config.py`(+asset_excel_path)
- 资产Excel：12月度sheet，编码列(2)匹配，日期列(41)算年限

## 语音识别转文字（2026-07-11部署）
- 手机企微=JS-SDK / PC企微=百度ASR(AppID=123947532) / Mac=隐藏
- H5内联录音：🎤→⏹→⏳(disabled)

## 坐席端截图+拍照（2026-07-11部署）
- 截图编辑器(马赛克/文字/箭头/矩形/撤销)；拍照(getUserMedia→兜底input capture)
- 铁律：`.selection-box`必须`pointer-events:none`；文字工具CSS类切换非v-if；`getDisplayMedia()`必须同步调用

## 复杂场景重构（2026-07-11部署）
- P0~P3：任务中断恢复/信息更正/上下文压缩/多轮纠错
- 路由前缀`/itportal/automation/`；迁移链修复041→028_merge_heads

## 知识库迭代（待确认）
- 技术方案：`docs/03-技术架构/增量设计-知识库迭代与痛点缓解-20260711.md`
- 原型图：`docs/01-产品设计/知识库迭代-未实现功能原型设计-20260711.md`

## 近期修复 (2026-07)
- H5非企微环境→扫码登录页；Vue版本不一致白屏→重装+`ElMessage._context`
- 消息重复/头像COEP/OAuth残留→已修

## 运维工具
- SOP：`docs/10-项目管理/IT智能服务台-标准作业流程SOP.md`
- 故障排查：`docs/09-部署运维/00-标准故障排查手册.md`