# 企微IT智能服务台 — 项目管理主文档

> **版本**: v2.7 | **日期**: 2026-07-20 | **维护人**: Duckula

---

## 一、项目状态总览

> **一句话总览**：v0.7.1 已上线运行，生产稳定。AI 对话链路全栈改造 Phase 1-6 全部完成并部署。H5 v4 人工坐席交互改造已部署。历史会话开关功能已部署。

### 已完成 (v0.7.1)
- ✅ 企微入口 SSO
- ✅ 管理后台 RBAC（6处装饰器修复）
- ✅ 敏感词检测（隐私正则修复）
- ✅ 扫码登录优化
- ✅ 文档优化专项

### v0.7.2 知识库迭代（全部交付）
- ✅ AI 辅助功能增强
- ✅ 排查流程优化
- ✅ 知识库迭代

### v0.7.3 AI 对话链路全栈改造 + 上下文感知诊断 + H5 v4（全部部署）
- ✅ AI 对话链路 Phase 1-6（Dify JSON 输出 / 统一消息架构 / VisionService 接入 / 坐席端适配 / 诊断闭环）
- ✅ 上下文感知智能诊断→修复闭环（三层诊断 / 三段排队 / 答题插队 / 五场景关闭）
- ✅ 坐席端布局优化 v2.0（QuickReplyBar / ReplyBox / 右栏模式切换 / 键盘快捷键 v2.3）
- ✅ 知识库迭代 3（分诊交互 / 拓扑预览 / 代答排除）
- ✅ H5 v4 人工坐席交互改造（文案统一 / 按钮重定位 / 删 CallAgentModal / 截图提示改版）

### v0.7.4 历史会话开关（2026-07-13 部署）✅
- ✅ 坐席端会话窗口 UserInfoBar 新增「历史会话」开关
- ✅ 跨会话消息聚合（同一员工所有会话合并为时间线）
- ✅ 游标分页懒加载（后端 `get_employee_history_messages` API）
- ✅ 会话分隔条组件（显示首条消息摘要 + 当前会话高亮）
- ✅ 28/28 测试全部通过

### v0.7.5 批次重构 + D1合并 + 文档重组（2026-07-18~19 部署）✅
- ✅ 批次1（P0）：超时预算切分（native/proxy超时12s）、RecommendCard崩溃修复、WS全字段透传
- ✅ 批次2（P1基础）：AIService真单例、统一Dify调用点、Matcher优先级修正、WS死路由清理、Redis密码轮换+APP_ENV传递
- ✅ 批次3（P1核心）：process_h5_ai_reply管线化重构（9步骤函数）、结单确认功能断链修复
- ✅ 批次4（P2收尾）：死代码大扫除（H5 Triage三件套/死端点/孤儿模块/.bak文件）
- ✅ D1合并：后端双模支持（intent_type/business_category字段透传）、kfid路由窗口配置化（12个窗口）
- ✅ C7/C8修复：employees.last_login_ip列缺失、redis decode兼容
- ✅ Dify上下文窗口超限自动重置会话
- ✅ 文档重组：docs目录从9类→10类（新增运营文档）、PRD合并、技术文档关联REQ编号

### 版本迭代

| 版本 | 状态 | 主要内容 | 日期 |
|------|------|----------|------|
| v0.7.0 | ✅ 已上线 | 企微SSO、MFA、RBAC | 2026-06 |
| v0.7.1 | ✅ 已上线 | 敏感词检测、token修复、扫码登录优化 | 2026-07-04 |
| v0.7.2 | ✅ 已完成 | backlog候选（AI辅助、排查流程，知识库迭代） | 2026-07+ |
| v0.7.3 | ✅ 已部署 | AI对话链路Phase1-6、上下文感知诊断、坐席布局v2.0、H5 v4人工坐席改造 | 2026-07-12~13 |
| v0.7.4 | ✅ 已部署 | 坐席端历史会话开关（跨会话聚合+游标分页+分隔条） | 2026-07-13 |
| v0.7.5 | ✅ 已部署 | 批次重构(P0~P2)+D1合并+kfid路由+C7C8修复+文档重组 | 2026-07-18~19 |
| v0.8.0 | ⏸️ 暂停 | 安全策略检查平台（OpenClaw合规检测+通用框架）— 必要性未确认 | 2026-07 |

---

## 二、任务管理文档体系

本项目采用四级任务管理文档体系：

| 级别 | 文档 | 用途 |
|------|------|------|
| L1 | **项目状态看板** | 驾驶舱仪表盘，当前正在做+待办 |
| L2 | **项目任务状态报告** | 历史全量任务清单 |
| L3 | **需求候选池** | 未来版本候选功能 |
| L4 | **PRD需求池** | 完整需求来源 |

---

## 三、快速导航

### 🔴 现在做什么？
查看 **项目状态看板** 的「正在做」和「P0必做」区

### 📜 历史全部任务？
查看 **项目任务状态报告**

### 📋 未来计划？
查看 **需求候选池** (v0.7.2+)

### 📖 需求来源？
查看 **PRD需求文档**

### 📅 每日工作记录？
查看 `.workbuddy/memory/` 目录

---

## 四、项目状态看板

### 正在做 (in_progress)

（暂无）

### ✅ 已完成

| # | 任务 | 说明 | 完成日期 |
|---|---|---|---|
| - | 批次1 P0重构 | 超时预算切分(dify_native/proxy_timeout=12s)、RecommendCard崩溃修复、WS全字段透传、摇人Bug修复 | 2026-07-18 |
| - | 批次2 P1基础重构 | AIService真单例(修复连接泄漏)、统一Dify调用点(删死链路)、Matcher优先级修正(title→category→关键词)、WS死路由清理、Redis密码轮换+APP_ENV传递 | 2026-07-18 |
| - | 批次3 P1核心重构 | process_h5_ai_reply管线化(9步骤函数)、结单确认功能断链修复(WS类型resolve_confirm) | 2026-07-18 |
| - | 批次4 P2收尾 | 死代码大扫除(H5 Triage三件套/死端点/孤儿组件/store死代码) | 2026-07-18 |
| - | D1合并 | 后端双模支持(intent_type/business_category字段透传)、kfid路由窗口配置化(12窗口)、C7(last_login_ip列缺失)、C8(redis decode兼容)、Dify上下文超限自动重置会话 | 2026-07-18 |
| - | 文档重组 | docs目录9类→10类(新增运营文档)、PRD合并(复杂场景/统一路由/邀请功能)、技术文档关联REQ编号 | 2026-07-19 |
| #117 | Neo4j 知识图谱连接修复 | 🐛 异步调用未await + CONTAINS语法错误，双向模糊匹配，3测试用例通过 | 2026-07-16 |
| #82 | 坐席端 500 错误 | 🐛 bind mount 未生效导致 rewrite 循环，重建 nginx 容器修复 | 2026-07-16 |
| #118 | 粘贴图片边框问题 | 🐛 坐席端/H5端粘贴图片预览边框从1px减少到0.5px（注：原#81编号修正） | 2026-07-16 |
| #80 | 企微图片消息无法预览 | 🐛 后端新增download_temp_media方法，企微图片下载到本地media目录 | 2026-07-16 |
| #107 | 后端部署卷挂载改造 | 方案C：镜像烘焙→代码卷挂载，消除两份代码不同步根因 | 2026-07-10 |
| #48 | v1.0 收窄 set_real_ip_from | nginx.conf 已配置精确内网网段(10.0.0.0/8等)，不再0.0.0.0/0 | 2026-07-14 |
| #88 | 管理后台 RBAC 角色权限 | 粗粒度3角色(admin/agent/user)已满足需求，细粒度权限不需要 | 2026-07-14 |
| #75 | 头像同步功能完善 | 登录强制同步 + 前端首字降级，测试通过 | 2026-07-14 |
| #116 | H5 v4 人工坐席交互改造 | ✨ 三态文案统一"人工坐席"/按钮位置上移/删除CallAgentModal弹窗/截图提示改版/移动端CSS隐藏/后端DB同步 | 2026-07-13 |
| #59-69 | AI 对话链路全栈改造 Phase 1-6 | ✨ Dify JSON输出/统一消息架构/VisionService接入/坐席端适配/诊断闭环协调/性能监控 | 2026-07-12 |
| #115+ | 上下文感知智能诊断→修复闭环 | ✨ 三层诊断(API→Script→AI)/三段排队/答题插队/五场景关闭/迁移052(6表+6列) | 2026-07-12 |
| #113+ | 坐席端布局优化 v2.0 | ✨ QuickReplyBar L1+L2悬浮/ReplyBox左右分区/右栏260↔560px/键盘快捷键v2.3 | 2026-07-12 |
| #113+ | 知识库迭代 3 | ✨ 分诊交互/拓扑预览(ECharts)/代答排除(4种匹配器)/44文件43测试/迁移051 | 2026-07-12 |
| #111 | 坐席端消息头像不显示Bug | 🐛 后端消息接口未返回sender_avatar → Schema添加字段 + API填充员工/AI头像 + 前端显示 | 2026-07-10 |
| #112 | 坐席端消息布局调整 | ✨ 头像和名字位置互换（头像在前、名字在后） | 2026-07-10 |
| #113 | 审批类型扩展与卡片URL直跳 | ✨ 审批类型 5→12种/18流程，后端静态模板+关键词扩展，前端卡片12类17选项URL直跳，Dify v2 System Prompt覆盖全部12类 | 2026-07-10 |
| #114 | 审批卡片同窗口导航改造 | ✨ window.open(\_blank) → window.location.href，企微原生返回按钮，COEP/CSP安全头分析 | 2026-07-10 |
| #115 | 企微跨应用免登录研究 | 📋 同corpid下IT服务台H5与运维平台各自独立OAuth2 snsapi_base静默授权，结论已归档 | 2026-07-10 |
| #108 | H5消息重复Bug | 🐛 员工发送消息后自己看到两条 → sendNewMessage未更新lastMessageId导致轮询重复拉取 → 已修复并部署 | 2026-07-10 |
| #109 | H5消息自动滚动 | ✨ 收到新消息时自动滚动到底部 → 已实现并部署 | 2026-07-10 |
| #110 | WebSocket Token认证修复 | 🐛 QR码登录存储user:token:*但WS只查agent:token:* → 支持两种格式查询 | 2026-07-10 |
| #105 | 摇人消息推送到通知栏Bug | 🐛 删除shake/call_agent函数中的企微消息推送调用，修复完成并已部署 | 2026-07-10 |
| #124 | 坐席端接单按钮状态优化 | 🚀 接单按钮改为持续显示，已接单时显示"已接单"并禁用 | 2026-07-24 |

### P0 必做 (下一个 sprint)

| # | 任务 | 重要程度 | 说明 |
|---|---|---|---|
| #81 | 敏感词检测 + 语气优化 | 🔴 P0 | v0.7.1 开发内容，文本安全过滤，延后1周，07-21到期 |
| #104 | 运行期结构化日志查看页（D） | ✅ 已结案 | **2026-08-07 生产实测结案**（jumpserver-V2 四项证据：管理页 200 / 前端 chunk 含筛选+下载 / 后端端点已挂载 / 日志源 JSON 写入）。文档收口 2026-08-04：原型 v1.1 + PRD v1.3 + 架构 prod.md v1.2.1 / sysdesign.md v1.3.1 |

### 近期完成 (2026-07-15~16)

| # | 任务 | 说明 | 完成日期 |
|---|---|---|---|
| #117 | Neo4j 知识图谱连接修复 | 修复异步调用+CONTAINS语法，双向模糊匹配，验证通过 | 2026-07-16 |

### P1 重要

| # | 任务 | 说明 |
|---|---|---|
| #73 | 修后端文件未真正覆盖 | `yes | cp -f` 路径 |
| #86 | 排查流程图零依赖部分 review | 把 Mermaid 流程图从代码里剥离 |

### 等用户决策（阻塞项）

| # | 事项 | 说明 |
|---|---|---|
| - | 企微会议室Secret | 会议室预定系统依赖，延后 |
| - | ITSM API授权 | 工单系统集成依赖，延后 |
| - | 联软网络不通 | 生产服务器无法访问联软192.168.0.53:3098，暂不处理 |

### P1/P2 功能开发任务

#### 阶段2 - P1功能

| # | 功能 | 状态 |
|---|---|---|
| P1-24 | 摇人按钮 | ✅已完成 |
| P1-25 | 满意度评价 | ✅已完成 |
| P1-26 | 排队系统 | ✅已完成 |
| P1-27 | 快速回复 | ✅已完成 |
| P1-28 | 知识库(基础) | ✅已完成 |

#### 阶段3 - P2功能

| # | 功能 | 状态 |
|---|---|---|
| P2-09 | AI Wingman | ✅已完成 |
| P2-10 | 会话标注 | ✅已完成 |
| P2-11 | 自动摘要 | ✅已完成 |
| P2-07~11 | 审批流程系统 | ✅已完成（详见任务说明书-78） |

#### 阶段4 - P2功能

| # | 功能 | 状态 |
|---|---|---|
| P2-12 | 数据看板 | ✅已完成 |
| P2-13 | 知识库自动迭代 | ✅已完成 |

---

## 五、最近搞定

### 2026-07-18~19
- ✅ 批次1 P0重构 — 超时预算切分(native/proxy 12s)、RecommendCard崩溃修复、WS全字段透传
- ✅ 批次2 P1基础重构 — AIService真单例(修复连接泄漏)、统一Dify调用点、Matcher优先级修正、WS死路由清理、Redis密码轮换+APP_ENV
- ✅ 批次3 P1核心重构 — process_h5_ai_reply管线化(9步骤函数)、结单确认断链修复
- ✅ 批次4 P2收尾 — 死代码大扫除(H5 Triage三件套/死端点/孤儿组件)
- ✅ D1合并 — 后端双模(intent_type/business_category)、kfid路由窗口(12窗口)、C7(last_login_ip列)、C8(redis decode)
- ✅ Dify上下文超限自动重置会话 — 检测context_overflow错误自动创建新会话
- ✅ 文档重组 — docs目录9类→10类(新增运营文档)、PRD合并、技术文档关联REQ编号

### 2026-07-16
- ✅ Neo4j 知识图谱连接修复（#117）— 修复异步调用未await + CONTAINS语法错误 + 双向模糊匹配，3测试用例通过（打印机驱动/网络连不上/邮箱无法收发）

### 2026-07-13
- ✅ H5 v4 人工坐席交互改造 + 部署（#116）— 文案统一/按钮重定位/删CallAgentModal/截图提示改版/DB同步
- ✅ 服务器部署路径修正 — 确认 `/opt/wecom-it-desk/` 项目根路径，所有前端 dist 为 ro bind mount

### 2026-07-12
- ✅ AI 对话链路全栈改造 Phase 1-6 全部完成并部署（#59-#69）
- ✅ 上下文感知智能诊断→修复闭环部署（三层诊断/三段排队/答题插队/五场景关闭）
- ✅ 坐席端布局优化 v2.0 部署（QuickReplyBar/ReplyBox/右栏模式切换/键盘快捷键v2.3）
- ✅ 知识库迭代 3 部署（分诊交互/拓扑预览/代答排除）

### 2026-07-10
- ✅ 审批类型扩展 5→12种/18流程 + 卡片URL直跳 + Dify v2 发布（#113）
- ✅ 审批卡片同窗口导航改造（#114）
- ✅ 企微跨应用免登录可行性研究（#115）
- ✅ 坐席端消息头像不显示Bug修复 + 部署（#111）
- ✅ 坐席端消息布局调整（头像在名字前） + 部署（#112）
- ✅ H5消息重复Bug修复 + 部署
- ✅ H5消息自动滚动功能 + 部署
- ✅ WebSocket Token认证修复 + 部署
- ✅ 摇人消息推送Bug修复 + 部署

### 2026-07-09
- ✅ WS 子协议修复部署生产
- ✅ 方案A E2E 通过

### 2026-07-08
- ✅ 消息发送延时 E2E 验证通过
- ✅ 头像同步功能代码交付（12/12测试通过）

### 2026-07-07
- ✅ 管理后台登录修复
- ✅ 故障排查文档整合

### 2026-07-06
- ✅ P1-25 满意度评价完成
- ✅ #90 身份认证问题修复

### 2026-07-05
- ✅ 坐席端消息列表500错误修复
- ✅ 消息发送失败修复
- ✅ 文档补充

---

## 六、风险管理

### 风险总览

| 级别 | 数量 | 已处理 | 待处理 | 处理率 |
|------|------|--------|--------|--------|
| 🔴 严重 (Critical) | 4 | 4 | 0 | **100%** |
| 🟠 高 (High) | 6 | 5 | 1 | **83%** |
| 🟡 中 (Medium) | 7 | 4 | 3 | **57%** |
| 🔵 低 (Low) | 5 | 3 | 2 | **60%** |
| **合计** | **22** | **16** | **6** | **73%** |

---

## 七、怎么跑起来

### 1. 后端 dev

```powershell
cd D:\资料\03-项目开发\wecom_it_smart_desk
docker compose -f docker-compose.dev.yml --env-file .env.dev up -d
curl http://localhost:8000/api/dev/health
```

### 2. 前端 dev

```powershell
# 一起起所有前端
.\scripts\dev-frontend-start.ps1
```

### 3. 浏览器验证

| 端 | 地址 |
|---|------|
| Portal | http://localhost:5176/itportal/select |
| H5 | http://localhost:5174/itdesk/ |
| 坐席 | http://localhost:5173/itagent/ |
| 管理员 | http://localhost:5175/itadmin/ |

---

## 八、文档清单

### 任务说明书/

| 文档 | 说明 |
|------|------|
| IT智能服务台-项目管理主文档 | 本文档 |
| 02-风险跟踪表.md | 风险登记册（22项） |
| 任务说明书-01-新开发任务.md | v0.7.2 新功能开发任务 |
| 任务说明书-02-卡点任务.md | 优先级最高卡点任务 |
| 任务说明书-75-头像同步功能完善.md | 进行中的任务 |
| 任务说明书-78-审批流程系统.md | 审批类型扩展+卡片URL直跳+同窗口导航+免登录研究 |

### SOPs-标准流程/

| 文档 | 说明 |
|------|------|
| SOP-01-Gitea部署.md | Gitea 部署 SOP |
| SOP-02-Gitea备份恢复.md | Gitea 备份恢复 SOP |
| SOP-03-推送评审.md | 推送评审 SOP |
| SOP-04-应急响应.md | 应急响应 SOP |
| SOP-05-项目管理文档管理规范.md | 文档管理规范 SOP |

---

## 九、相关文档

| 类别 | 文档 | 位置 |
|------|------|------|
| 项目概览 | 项目总览与部署手册 | `01-项目总览/` |
| 产品需求 | PRD需求文档 | `02-产品需求/` |
| 技术架构 | 技术架构设计 | `03-技术架构/` |
| 测试质量 | E2E验收清单 | `03-测试文档/` |
| 部署运维 | 部署指南 | `04-运维文档/部署运维/` |

---

## 十、版本历史

| 版本 | 日期 | 变更 |
|------|------|------|
| v2.7 | 2026-07-20 | 看板更新：批次1/2/3/4重构完成、D1合并、文档重组；P0移除#117；P1移除#80；修正#81编号冲突为#118；添加v0.7.5版本记录 |
| v2.8 | 2026-07-14 | 巡检更新：#91忘记密码功能已取消，移出进行中区 |
| v2.7 | 2026-07-14 | 巡检更新：#75头像测试通过移除P1；火绒AccessKey已恢复；等用户决策区块移除火绒AccessKey |
| v2.6 | 2026-07-14 | 巡检更新：#48/#107/#88 确认已完成从看板移除；#81 延后1周；#104 排入本期；新增等用户决策区块（含会议室Secret/ITSM API/联软网络/火绒AccessKey） |
| v2.5 | 2026-07-13 | 新增 v0.7.3 版本（AI对话链路Phase1-6/上下文感知诊断/坐席布局v2.0/知识库迭代3/H5 v4），新增 #116 和 #59-69 完成任务，更新最近搞定 |
| v2.4 | 2026-07-10 | 新增 #113-115 审批流程系统任务（类型扩展+卡片导航+免登录研究），P2功能表新增审批流程系统 |
| v2.3 | 2026-07-10 | 新增 #111-112 头像显示与布局调整任务 |
| v2.2 | 2026-07-10 | 新增 #108-110 Bug修复任务（消息重复、自动滚动、WS认证） |
| v2.1 | 2026-07-10 | 看板新增 #107 后端部署卷挂载改造任务 |
| v2.0 | 2026-07-10 | 整合任务总索引、项目状态看板、任务状态报告、风险跟踪表 |
| v1.1 | 2026-07-04 | 新增产品需求变更、技术架构变更、文档管理变更 |
| v1.0 | 2026-07-04 | 初始版本 |

---

> **本文档就是项目的"驾驶舱仪表盘"。任何时候新开 session，先读这个文件就懂上下文。