Files

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

17 KiB

Raw Blame History

企微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
#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

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

# 一起起所有前端
.\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，先读这个文件就懂上下文。

17 KiB Raw Blame History Unescape Escape

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

一、项目状态总览

已完成 (v0.7.1)

v0.7.2 知识库迭代（全部交付）

v0.7.3 AI 对话链路全栈改造 + 上下文感知诊断 + H5 v4（全部部署）

v0.7.4 历史会话开关（2026-07-13 部署）✅

v0.7.5 批次重构 + D1合并 + 文档重组（2026-07-18~19 部署）✅

版本迭代

二、任务管理文档体系

三、快速导航

🔴 现在做什么？

📜 历史全部任务？

📋 未来计划？

📖 需求来源？

📅 每日工作记录？

四、项目状态看板

正在做 (in_progress)

✅ 已完成

P0 必做 (下一个 sprint)

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

P1 重要

等用户决策（阻塞项）

P1/P2 功能开发任务

阶段2 - P1功能

阶段3 - P2功能

阶段4 - P2功能

五、最近搞定

2026-07-18~19

2026-07-16

2026-07-13

2026-07-12

2026-07-10

2026-07-09

2026-07-08

2026-07-07

2026-07-06

2026-07-05

六、风险管理

风险总览

七、怎么跑起来

1. 后端 dev

2. 前端 dev

3. 浏览器验证

八、文档清单

任务说明书/

SOPs-标准流程/

九、相关文档

十、版本历史

17 KiB

Raw Blame History