simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
50cb946e9af9029286cade883f2c3fccdc6efc94
wecom_it_smart_desk/.workbuddy/memory/MEMORY.md
T

6.3 KiB
Raw Blame History

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/远程文件 ./本地路径

使用方式

# 第一次执行（自动登录并缓存会话）
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
  • 保留未改：目录树展示（历史快照）、归档文档内旧路径、历史任务标题
Reference in New Issue View Git Blame Copy Permalink