wecom_it_smart_desk/docs/12-重构记录/README.md

12-重构记录 — 目录索引与执行状态看板

创建：2026-07-17 目的：智能回复系统 v4.0 深度重构的全部记录。当前会话不可用时，新会话读本目录即可继续推进。 工作方式：敏捷批次交付 + DevOps（文档与代码同 PR）

---

一、新会话快速上手指引（3 步）

1. 读方案：00-v4.0重构总方案.md（分层架构、批次计划、验收清单）
2. 读问题：01-问题验证清单.md（20 项问题 + 源码行号证据 + 已完成修复清单）
3. 看状态：本文 §三（执行状态看板），找到「待开始」的任务说明书，按 docs/10-项目管理/任务说明书/ 执行

二、目录结构

docs/12-重构记录/
├── README.md                    ← 本文件（索引 + 状态看板）
├── 00-v4.0重构总方案.md          ← 目标架构、批次计划、验收清单、回滚策略
├── 01-问题验证清单.md            ← 20 项问题源码证据（B1-B8/F1-F6/C1-C6）
├── 02-批次1-P0执行记录.md        ← 批次 1 完成后填写
├── 03-批次2-P1基础执行记录.md
├── 04-批次3-P1核心执行记录.md
└── 99-回顾报告.md               ← 批次 3 观察 24h 后填写

配套文档：

• 任务说明书：docs/10-项目管理/任务说明书/任务说明书-78/79/84/85/86/87/88/89/90
• 部署铁律：docs/09-部署运维/DEPLOY-GUIDE.md §4.3
• Dify 主 prompt 线上版本：docs/02-产品需求/dify_main_chat_prompt_v1.md（v1.2）

三、执行状态看板

更新规则：每完成一项即更新。新会话从这里接续。

批次	任务	任务说明书	状态	完成日期
—	v3.0 后端 ApprovalMatcher + 前端纯渲染	—	✅ 已完成	2026-07-17
—	v3.1 Dify 无 action 降级 + message_content bug 修复	—	✅ 已完成	2026-07-17
批次 0	文档速修 4 项 + 本目录归档	—	✅ 已完成	2026-07-17
批次 1	P0-1 workers=2→1	#78	✅ 已完成（预防性，服务器已是1）	2026-07-17
批次 1	P0-2 DIFY_NATIVE_* 生产配置	#79	✅ 已完成（变量已注入容器）	2026-07-17
批次 1	P0-3 快捷申请空白气泡修复	#87	⚠️ 误报（InputBox 孤儿组件，端点保留备用）	2026-07-17
批次 1	P0-4 RecommendCard invokeApproval 修复	#88	✅ 已完成（v16）	2026-07-17
批次 1	P0-5 WS new_message 全字段透传	#89	✅ 已完成（v16）	2026-07-17
批次 1	P0-6 超时预算切分	#90	✅ 已完成（native/proxy 各12s，变量已注入）	2026-07-18
批次 2	P1-1 AIService/AIHandler 真单例	#84	✅ 已完成	2026-07-18
批次 2	P1-2 统一 Dify 调用点（删 detect-intent 死链路）	#84	✅ 代码完成，待部署（堡垒机已关，明天部署）	2026-07-18
批次 2	P1-4 Matcher 死分支+失败兜底全量卡片	#84	✅ 代码完成（含 18 模板字段补全，7 项测试通过），待部署	2026-07-18
批次 2	P1-7(部分) 3 个潜伏 bug 修复	#84	✅ 代码完成（app_root/Scheduler拼写/logger），待部署	2026-07-18
批次 2	P1-7(剩余) APP_ENV 传递+Redis 密码轮换	#84	⬜ 待开始（需停机窗口，低峰期执行）	—
批次 2	P1-6 recommend 死逻辑清理	#84	⬜ 待开始	—
批次 3	P1 核心（编排层管线化 + WS 路由清理）	#85	⬜ 待开始	—
批次 4	P2（死代码/triage 删除/测试）	#86	🔵 部分提前（InputBox/MessageItem 孤儿组件已删）	—

待部署清单（堡垒机恢复后一次性部署）

后端 5 个文件（上传到 /opt/wecom-it-desk/app/，注意挂载路径陷阱）：

1. backend/app/api/approval.py（P1-2 删死链路 + P1-4 补 18 模板字段）
2. backend/app/api/byod.py（P1-2 删 detect-intent 端点）
3. backend/app/services/routing_service.py（P1-2 共享 client）
4. backend/app/services/approval_matcher.py（P1-4 死分支+兜底）
5. backend/app/dependencies/__init__.py（P1-2 lifespan 关 routing client）
6. backend/app/tasks/h5_ai_task.py（P1-4 日志调整）
7. backend/app/main.py + config.py + tasks/scheduler.py（P1-7 三 bug）

前端：pnpm build → h5-dist-v17.tar.gz（P1-2 死 API + 孤儿组件清理）

部署后验证：

• docker compose restart backend 后无 ImportError
• 发"VPN账号申请"验证审批卡片正常（Matcher 兜底路径）
• 坐席端发图片/文件验证 WS 透传正常

四、关键上下文（新会话必读）

4.1 部署铁律（详 docs/09-部署运维/DEPLOY-GUIDE.md §4.3）

1. backend 必须 --workers 1（override 会覆盖主文件，务必 docker compose config | grep workers 验证）
2. .env 不会自动传入容器，新变量必须在 compose environment: 显式声明
3. Redis 密码特殊字符必须 URL 编码（@→%40 #→%23 !→%21）

4.2 服务器部署通道

• 堡垒机：sxn@10.212.189.210:2222（OTP），工具 C:\Users\simon\.workbuddy\skills\jumpserver-ops\scripts\jms_ops.py
• 服务器项目根：/opt/wecom-it-desk/；backend 卷挂载 ./app:/app/app，改 .py 后 docker compose restart backend
• 前端部署：tar 上传 → 解压到 frontend-h5/dist → docker compose up -d nginx（容器重建非 reload）

4.3 回滚点

• git tag pre-v4-refactor（批次 1 上线前打）
• 前端备份：frontend-h5/dist_bak_v13

4.4 用户已确认的决策

• Redis 密码立即轮换（批次 2，低峰期，新旧双备）
• Triage 分诊链路整体删除（批次 4）
• D1 意图合并激进方案（批次 3 先 5 条真实消息验证 Dify intent 字段，不稳定退回 gather 并行）

五、变更记录

日期	变更	说明
2026-07-17	创建目录 + 批次 0 完成	4 项文档速修 + 本索引
2026-07-17	任务说明书 #78-86 创建	批次 1-4 全部任务书面化