# 2026-05-21 工作记录

## 企微 IT 服务台架构咨询

用户背景：6000 人上市公司，已有企微 + 千问 + RAGFlow + Dify 的 AI IT 助手，痛点在于员工绕过 AI 直接转人工、转人工后需开新窗口、无法跨主体企业共享。

### 三方案可行性分析
- **方案一**（企微员工服务 + 自建应用）：不可行，企微员工服务 API 独立，无法与自建应用消息流打通，痛点解决率 1/3
- **方案二**（自建应用消息 + 自研坐席后台）：推荐，完整解决三个痛点，需自研坐席后台，开发量中等
- **方案三**（企微 WebView + 开源客服如 Chatwoot）：可行，速度快但灵活度受限，跨企业共享有配置复杂度

### 零基础开发能力评估
- 方案三：零基础 + AI 辅助，约 3 个月可上线（推荐入手点）
- 方案二：需 4-6 个月，学习曲线更陡
- 核心学习路径：Python → HTTP/企微 API → Docker 部署 → Flask 消息网关 → AI 集成

### 硬件资源需求
- 方案三：单台 8 核 8GB 内存 100GB SSD 服务器（约 2-4 万元）
- 方案二：2 台服务器，合计 8-16 核 16GB 内存 300GB SSD
- AI 推理（千问）：已有设施则不需额外采购；如新采购建议 Qwen2.5-14B + A30/双 RTX 4090

### 用户修正的三步演进路径
- 第一步：测试环境完成企微消息接管 + 极简坐席，先不接入AI，验证消息回调链路
- 第二步：将千问+Dify+RAGFlow机器人消息接入极简坐席
- 第三步：会话日志人工+AI混合标注与校正，迭代优化AI知识库

### 并行协作模式设计
- 用户核心创新：AI和人工并行而非串行，所有会话消息AI全程可见
- 会话标记系统：VIP图标、举手标记（关键词"转人工"）、情绪识别（关键词规则优先）、紧急度评分（综合公式）、置顶/代办
- 坐席看板分区：AI自主处理区（折叠）、举手等待区（核心关注）、人工处理区、已结单区

### 双面板AI助手设计（用户已确认）
- 用户端AI助手面板（最右侧，H5双栏方式B）：相似问题、审批流程链接、软件下载快捷入口、知识库搜索
- 坐席端AI助手面板（最右侧）：AI建议回复（采纳/编辑/忽略）、快速回复模板、问题解决操作步骤、风险提示、用户特点和其他注意事项
- 后端同一AI引擎，按角色路由不同数据schema输出

### 原型优化确认（6/2）
- 用户信息去重：左栏去掉办公地点，中栏去掉部门/岗位/用户等级
- 新增"需介入"标签：同一问题追问次数多或AI判断需要人工时自动触发
- 用户端选方式B（H5双栏），功能未实现前预留占位符+"即将上线"提示
- 原型美化：添加emoji图标和颜色区分

### 第一步逐天开发清单（6/2更新）
- 6周30天计划：第1周基础+企微对接 → 第2周消息路由+标记系统 → 第3周坐席工作台 → 第4周AI助手面板(坐席端) → 第5周用户端H5双栏 → 第6周联调测试
- 新增功能：举手/需介入/情绪/VIP标记、彩色标签会话列表、AI助手坐席端5模块、H5双栏+OAuth
- 新增「摇人」按钮（6/2）：用户端输入框左侧的转人工快捷键，橙色渐变铃铛+红点+摇晃动画，一键呼叫IT坐席
- 摇人趣味话术体系（6/2）：点击→"大哥，俺这就去摇人，稍等..."；排队→"人还在路上，别急别急～"；接入→"人摇来了！IT坐席为您服务"；关键词→"收到！这就帮您摇位大神来"；超时→"坐席都在忙，不过AI还在呢"；话术存配置表支持后台动态修改

### 开发团队SOP执行（6/2）
- 团队：software-it-service-desk，主理人齐活林 + 产品经理许清楚 + 架构师高见远 + 工程师寇豆码 + QA严过关
- PRD完成：`C:\Users\simon\wecom_it_smart_desk\PRD.md`，含31项需求(P0/P1/P2)、7个用户故事、完整数据模型
- 架构设计完成：`ARCHITECTURE.md`，9张表DDL + 7组API + 4张时序图 + 5个任务分解
- T01基础设施完成：57个文件（Docker/模型/Schema/前后端脚手架）
- T02后端核心完成：16个文件（企微加解密/消息路由/评分/摇人话术/7组API）
- T03坐席前端完成：20个文件（三栏布局/会话列表/对话区/AI助手5模块/登录页）
- T04 H5用户端完成：12个文件（双栏布局/摇人按钮/审批链接/软件下载/占位符/OAuth2）
- QA测试完成：93个测试用例（7个模块），Bug1(await缺失)已修复
- 已知问题：PostgreSQL特有类型(JSONB/gen_random_uuid)与SQLite测试环境不兼容，需适配
- 用户确认：坐席用户名密码登录、支持文本+图片+文件消息、企微应用已创建有凭证

### 兼容性修复 & database.py 重构（6/3）
- 9个模型文件全部兼容SQLite：UUID→String(36)+default=lambda:str(uuid.uuid4())，JSONB→JSON，移除server_default/postgresql_using/postgresql_where
- database.py重构为懒加载：_get_engine()和_get_session_factory()延迟创建引擎，避免测试导入时触发asyncpg连接
- main.py和wecom_callback.py已同步更新引用（async_session_factory→_get_session_factory()）
- pytest无法在sandbox中运行（子进程输出/文件写入均被拦截），需用户本地终端手动运行验证
- 第一步全部代码完成：110+文件，待本地pytest验证

### 测试验证通过（6/3）
- **116/116 pytest 全部通过**（1.71秒），测试过程中发现并修复7个Bug：
  1. message_router.py 缺少 await
  2. main.py 中文引号导致 SyntaxError
  3. wecom_callback.py WecomCrypto 模块级初始化失败 → 懒加载
  4. conftest.py Redis mock 路径错误
  5. conftest.py create_test_conversation 缺少参数
  6. session_service.py UUID/String(36) 类型不匹配
  7. scoring_service.py 关键词大小写不敏感 + VIP短路缺失
- **第一步开发完整交付**，可进入部署阶段