simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6be361fb63783520f5dcfd7cce386ac9b5523d4f
wecom_it_smart_desk/docs/07-项目管理/任务说明书/IT智能服务台-项目管理主文档.md
T
Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交） 
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
2026-08-07 22:31:32 +08:00

348 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 企微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，先读这个文件就懂上下文。
Reference in New Issue View Git Blame Copy Permalink