chore(docs): docs/ 目录全面重新编号 + 重组

**重构前**（旧编号 02-11）： - docs/02-产品需求/ → 00 产品规划/PRD - docs/03-技术架构/ → 01-05 子目录散落 - docs/04-原型设计/ → 01-02 产品设计（HTML 原型） - docs/05-原型设计/ → screens/ - docs/06-测试素材/ → 02-E2E / 03-功能 / 04-版本测试 - docs/07-项目管理/ → 任务说明书/日报/计划 - docs/08-安全审计/ → 审计报告 - docs/09-堡垒运维/ → toolbox / deploy - docs/10-项目管理/ → 任务说明书（重复） - docs/11-历史归档/ → deploy-nas-archived **重构后**（新编号 00-07，语义化）： - docs/00-产品开发流程与文档管理规范.md - docs/00-版本迭代总览.md - docs/01-产品文档/ （PRD/原型/认证/会话/AI 服务/坐席/集成） - docs/02-技术文档/ （技术方案/架构图/重构记录/前端改造/实现配置） - docs/03-测试文档/ （E2E/功能用例/版本报告/缺陷单） - docs/04-运维文档/ （部署运维/运维指南） - docs/05-运营文档/ （品牌推广/用户手册） - docs/06-安全审计/ （审计报告） - docs/07-项目管理/ （任务说明书/日报/计划/看板） **净收益**： - 目录编号与产品文档管理规范对齐（按文档阶段 01-07 编号） - 消除 02-产品需求与 10-项目管理的编号重叠 - 子目录按文档类型分组（如 01-产品文档/00-产品规划、01-产品文档/01-认证与登录） - 把运维/安全/项目管理从 0X 散落改为 04/06/07 合计 494 文件 + 78495 行 / - 14076 行
2026-08-03 18:46:55 +08:00
parent 3a44141eac
commit 44e77dcb0e
494 changed files with 78494 additions and 14075 deletions
@@ -0,0 +1,83 @@
+# 智能回复系统深度重构总方案（v4.0）
+
+> **日期**：2026-07-17
+> **前置版本**：v3.0（后端 ApprovalMatcher 统一匹配）/ v3.1（Dify 无 action 降级 + 超时降级）
+> **问题基线**：20 项已验证问题（后端 8 + 前端 6 + 配置 6），全部对照源码核实
+> **用户决策**：Redis 密码立即轮换 ✅ / Triage 分诊链路整体删除 ✅ / D1 意图合并采用激进方案 ✅
+> **工作方式**：敏捷批次交付 + DevOps（文档与代码同 PR、每批次 RELEASE-NOTES）
+
+---
+
+## 一、目标分层架构
+
+```
+接入层 Ingress（h5.py / ws.py）
+  └─ 只鉴权、落库用户消息、立即返回、投递任务
+编排层 Orchestration（h5_ai_task.py 管线化）
+  └─ 只做流程编排，不直接发起外部调用
+推理层 Inference（ai_service.py，全系统唯一 Dify 调用点）
+  └─ 真单例；native 12s + proxy 12s 超时预算；一次调用返回 intent/路由/审批字段
+匹配层 Matching（approval_matcher.py，纯函数）
+  └─ match_and_build_card / match_by_keywords / get_all_categories
+渲染层 Rendering（前端纯渲染）
+  └─ WS 契约单点 build_message_ws_payload()；审批卡片渲染点 ≤ 2 处
+```
+
+**单一职责红线**：ApprovalMatcher 不碰 WS/DB；AIService 不认识"审批/路由/BYOD"；编排层不 new httpx；WS 推送统一出口。
+
+## 二、关键设计决策
+
+| # | 决策 | 理由 |
+|---|------|------|
+| D1 | 意图识别并入主 Dify 调用 | routing detect 与主对话是同一 Dify 应用同一 key，消除 15s+30s 串行叠加（最坏 45s → ~15s） |
+| D2 | 超时预算内化 httpx | native 12s + proxy 12s < wait_for 30s，修复 proxy 兜底数学不可达问题 |
+| D3 | 匹配失败不静默 | ApprovalMatcher 末路返回全量卡片（get_all_categories），前端永不空白 |
+| D4 | WS 消息契约单点化 | 修复 new_message 前端白名单丢字段（坐席图片/文件不渲染） |
+| D5 | triage 分诊链路删除 | 前端零挂载点（已确认，grep 无引用） |
+| D6 | 快捷申请走新端点 | `GET /approval/all-categories-card`，修复 showApprovalCard 空白气泡 P0 |
+
+## 三、批次计划
+
+### 批次 1（P0，~2 天，彼此独立可单独上线）
+| 项 | 内容 | 工作量 |
+|----|------|--------|
+| P0-1 | 生产 workers=2 → 1（删除/修改 override 与 deploy-server compose） | 0.5d |
+| P0-2 | DIFY_NATIVE_* 生产配置（compose environment + .env.production） | 0.5d |
+| P0-3 | 快捷申请空白气泡修复（新 all-categories-card 端点 + store 改造） | 0.5d |
+| P0-4 | RecommendCard invokeApproval ReferenceError 修复 | 0.5d |
+| P0-5 | WS new_message 前端全字段透传 | 1d |
+| P0-6 | 超时预算切分（native 12s / proxy 12s） | 1d |
+
+**上线前 git tag `pre-v4-refactor`**；文档同步：本目录 `01-批次1-P0执行记录.md` + RELEASE-NOTES v4.0.0。
+
+### 批次 2（P1 基础，~3 天）
+P1-1 AIService 真单例（修复 httpx 连接泄漏）→ P1-2 统一 Dify 调用点（删除 approval/byod detect-intent 死链路、routing 改调 chat_native）→ P1-4 Matcher 死分支删除 + 失败兜底（D3）→ P1-7 配置治理（APP_ENV=production、**Redis 密码轮换（低峰期）**、os.getenv 旁路收敛、3 个潜伏 bug 修复：app_root/AsyncIOSScheduler 拼写/config.py logger）→ P1-6 dynamic_recommend 死逻辑清理。
+
+文档同步：架构文档 v2 §15.4.5 重写（v3.0 纯渲染架构）。
+
+### 批次 3（P1 核心，~4 天，观察 24h）
+P1-3 编排层管线化（**D1 激进合并**：先 5 条真实消息验证 Dify intent 字段稳定性，不稳定退回 gather 并行）→ P1-5 WS 死路由清理（ai_reply_chunk/pending_close_request/quiz_diagnostic_answer）。
+
+观察指标：AI 回复到达率 ≥99%、平均响应 ≤20s、转人工率不升。文档同步：架构文档新增「智能回复链路 v4」章节。
+
+### 批次 4（P2，按需）
+P2-1 死代码大扫除（含 3 个 .bak 文件、构建产物目录入库）→ P2-2 triage 整链删除 → P2-4 测试补齐 → P2-3 前端 store 拆分 → P2-5 审批回调 TODO 收口。
+
+## 四、验收清单
+
+- [ ] 生产 `--workers 1`，AI 回复 WS 到达率 100%
+- [ ] 日志走「Dify 原生 API」，无 proxy 路径、无 [object Object]
+- [ ] Dify 调用点全系统唯一
+- [ ] `process_h5_ai_reply` < 100 行，try/except ≤ 3 对；路由消息端到端 < 35s
+- [ ] ApprovalMatcher 任意输入均有卡片输出（无 None）
+- [ ] H5 快捷申请/AI 卡片/关键词兜底三场景渲染一致
+- [ ] 坐席发图片/文件，H5 WS 实时渲染
+- [ ] pytest + `npm run build` 全绿；/version 返回真实 git hash
+
+## 五、回滚策略
+
+每批次独立 PR + 独立部署；git tag `pre-v4-refactor` 全量回滚点；配置类（DIFY_NATIVE/APP_ENV/Redis）改回旧值重启即可；批次 3 异常回滚至批次 2 状态。
+
+---
+
+**执行记录**：见本目录 `01-批次1-P0执行记录.md`（批次 1 完成后填写）等。
@@ -0,0 +1,57 @@
+# v4.0 重构 — 问题验证清单（20 项）
+
+> **日期**：2026-07-17
+> **验证方式**：逐项对照源码核实（文件 + 行号）
+> **用途**：新会话快速理解重构问题基线，无需重新探索
+
+---
+
+## 一、后端问题（B1-B8）
+
+| # | 问题 | 证据（文件:行号） | 现状 |
+|---|------|------------------|------|
+| B1 | 9 个匹配/识别入口（5 活 4 死） | 活：Dify 主 action、ApprovalMatcher、routing detect、Neo4j 图谱、关键词预过滤；死：`approval.py:1060`、`byod.py:348`、DifyTriageService、matchers.IntentMatcher | 待 P1-2 收敛 |
+| B2 | 双重超时致 proxy 兜底不可达 | `ai_service.py` httpx timeout=30s（`config.py:115`）= `h5_ai_task.py:1197` wait_for(30)；native→proxy 串行最坏 60s | 待 P0-6 |
+| B3 | ApprovalMatcher 死分支 | `approval_matcher.py:66-69` 优先级 5 与 50-53 优先级 2 同调 `_match_by_keyword(approval_type)`，不可达 | 待 P1-4 |
+| B4 | Matcher 匹配失败仅 warning | `h5_ai_task.py:461`，action 无 card_data 透传 → 前端空白 | 待 P1-4（D3 兜底） |
+| B5 | 同一 Dify 调用代码复制 3 遍 | `approval.py:999-1057`（死）、`routing_service.py:120-189`（活）、`byod.py:243-300`（死），各自新建 httpx.AsyncClient | 待 P1-2 |
+| B6 | 路由 detect 与主 Dify 串行 45s | `h5_ai_task.py:1060` detect（15s 超时）→ `:1197` 主调用（30s） | 待 P1-3（D1 合并） |
+| B7 | 26 对 try/except | `h5_ai_task.py` 主函数 11 对，最深 4 层缩进（L1037→1196→1205→1227） | 待 P1-3 管线化 |
+| B8 | 死代码 9 项 | 见 v4.0 方案 §3 表格（get_reply_stream、detect-intent×2、dynamic_recommend 死分支、matcher P5、前端死 API×2、handle_message 死分支、回调 TODO、.bak 文件） | 待 P2-1 |
+| B9 | get_shared_ai_handler 伪单例 | `dependencies/__init__.py:98-106` 每次新建 AIHandler+AIService+2 个 httpx 池，从不 close | 待 P1-1 |
+
+## 二、前端问题（F1-F6）
+
+| # | 问题 | 证据 | 现状 |
+|---|------|------|------|
+| F1 | ~~showApprovalCard 空白气泡（P0）~~ **误报** | `stores/conversation.ts:900-917` 构造空 extra_data。**但 InputBox.vue 是孤儿组件（ChatPanel.vue:96 实际用 InputBar.vue），showApprovalCard 无人调用，此 bug 在用户界面不存在**。all-categories-card 端点保留备用，InputBox+showApprovalCard 列入批次4死代码 | ⚠️ 误报，批次4清理 |
+| F2 | RecommendCard invokeApproval 崩溃（P0） | `RecommendCard.vue:178` 调用未定义函数（grep 确认无定义/导入/emit） | 待 P0-4 |
+| F3 | WS new_message 白名单丢字段（P0） | `stores/conversation.ts:395-429` 只取 7 字段；后端 `messages.py:278` 已下发全量 | 待 P0-5 |
+| F4 | WS 3 种死路由 | `useH5WebSocket.ts:392/477/489`（ai_reply_chunk/pending_close_request/quiz_diagnostic_answer），后端零产出 | 待 P1-5 |
+| F5 | ApprovalCardModal 3 处渲染点 | `MessageBubble.vue:19/82/103`，L82 text 分支自 v2.4 已死；approval_card msg_type 后端从未产出 | 待 P1-5 |
+| F6 | 大量死代码 | store 死状态（approvalCardVisible 等）、MessageItem.vue 孤儿组件、死 CSS、前端死 API（conversation.ts:430/486/505） | 待 P2-1 |
+
+## 三、配置/部署问题（C1-C6）
+
+| # | 问题 | 证据 | 现状 |
+|---|------|------|------|
+| C1 | DIFY_NATIVE_* 生产从未配置 | 根 compose environment 无此 2 项；`.env.production`、`deploy-server/.env.production`、`backend/.env.example` 均无 → v2.1 原生直连未上线 | 待 P0-2 |
+| C2 | workers=2 破坏单 worker 铁律 | `docker-compose-override.yml:4`、`deploy-server/docker-compose.yml:115`、`docker-compose-green.yml:46` 均 `--workers 2`；主文件已 1 但被 override 覆盖 | 待 P0-1 |
+| C3 | APP_ENV 未传 | `config.py:182` 默认 dev → 生产 UA 校验/IP 白名单不生效 | ✅ P1-7 已完成（2026-07-18，`APP_ENV=production` 已注入容器） |
+| C4 | Redis 密码硬编码两处 | 根 compose L51（requirepass 明文）、L120（URL 编码硬编码）；`.env` 的 REDIS_PASSWORD 未被引用；密码已进 git | ✅ P1-7 已完成（2026-07-18 轮换为 32 位随机密码，老密码 WRONGPASS 验证失效） |
+| C5 | 15+ 处 os.getenv 旁路 | upload.py:35/49/51、auth_wecom_sso.py:65/83/161、dev_auth.py:42 等；DEV_MODE 判定重复 4 处 | 待 P1-7 |
+| C6 | 3 个潜伏 bug | ① `main.py:1020` `app_root` 未定义 → /version 永远 unknown；② `tasks/scheduler.py:21` `AsyncIOSScheduler` 拼写错误（多一个 S，且零导入）；③ `config.py:409` 使用未定义 `logger` | ✅ P1-7 已完成（2026-07-18 全部修复并部署） |
+| C7 | employees.last_login_ip 列缺失 | OAuth 回调 WARNING：`column employees.last_login_ip does not exist`（model 有该字段但表缺列，schema 迁移缺失）。仅 WARNING 不阻塞登录 | ✅ 已完成（2026-07-18 ALTER TABLE 补列，验证 EXISTS） |
+| C8 | redis decode 兼容警告 | `wecom_service.py:83`：`decode_responses=True` 返回 str 后代码再调 `.decode()` → WARNING 走降级。不致命 | ✅ 已完成（2026-07-18 修复 7 处裸 decode：wecom_service×2/employee_directory×3/auth_wecom_sso×2，统一 isinstance 保护） |
+
+## 四、已完成的修复（v3.0/v3.1/批次 0，勿重复）
+
+| 日期 | 修复 | 位置 |
+|------|------|------|
+| v3.0 | 后端 ApprovalMatcher 统一匹配；前端 ApprovalCardModal 纯渲染；APPROVAL_TEMPLATES 扩展 icon/desc/category；删除前端 APPROVAL_OPTIONS / APPROVAL_URL_MAP / getApprovalKeywords API | `approval_matcher.py`、`approval.py`、`ApprovalCardModal.vue`、`MessageBubble.vue`、`RecommendCard.vue`、`conversation.ts` |
+| v3.1 | Dify 无 action 降级（h5_ai_task.py:1252-1272）+ 超时降级（:1205-1241）；修复 `message_content` 未定义 bug（3 处改 `content`） | `h5_ai_task.py` |
+| 批次 0 | dify_main_chat_prompt v1.2 同步线上；DEPLOY-GUIDE §4.3 部署铁律；2 个 prompt 文档标废弃；本目录归档 | `docs/` |
+
+---
+
+**参考**：完整方案见 `00-v4.0重构总方案.md`；批次执行记录见 `01-批次1-P0执行记录.md` 等。
@@ -0,0 +1,91 @@
+# 02-技术文档/重构记录 — 目录索引与执行状态看板
+
+> **创建**：2026-07-17
+> **目的**：智能回复系统 v4.0 深度重构的全部记录。当前会话不可用时，新会话读本目录即可继续推进。
+> **工作方式**：敏捷批次交付 + DevOps（文档与代码同 PR）
+
+---
+
+## 一、新会话快速上手指引（3 步）
+
+1. **读方案**：`00-v4.0重构总方案.md`（分层架构、批次计划、验收清单）
+2. **读问题**：`01-问题验证清单.md`（20 项问题 + 源码行号证据 + 已完成修复清单）
+3. **看状态**：本文 §三（执行状态看板），找到「待开始」的任务说明书，按 `docs/07-项目管理/任务说明书/` 执行
+
+## 二、目录结构
+
+```
+docs/02-技术文档/重构记录/
+├── 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/07-项目管理/任务说明书/任务说明书-78/79/84/85/86/87/88/89/90`
+- 部署铁律：`docs/04-运维文档/部署运维/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 | ✅ 已部署（死端点 404 验证通过） | 2026-07-18 |
+| 批次 2 | P1-4 Matcher 死分支+失败兜底全量卡片 | #84 | ✅ 已部署（含 18 模板字段补全，7 项测试通过） | 2026-07-18 |
+| 批次 2 | P1-7(部分) 3 个潜伏 bug 修复 | #84 | ✅ 已部署（启动无 ImportError） | 2026-07-18 |
+| 批次 2 | P1-7(剩余) APP_ENV 传递+Redis 密码轮换 | #84 | ✅ 已部署（老密码 WRONGPASS 失效，新密码 PONG/读写正常） | 2026-07-18 |
+| 批次 2 | P1-6 recommend 死逻辑清理 | #84 | ✅ 已部署（v18，含结单确认断链修复） | 2026-07-18 |
+| 批次 3 | P1-3 编排层管线化（主函数312→76行）+ D1 止血（15s→8s） | #85 | ✅ 已部署（端到端验证一致，进入 24h 观察期） | 2026-07-18 |
+| 批次 3 | D1 正式合并（后端双模 + Prompt v1.3） | #85 | ✅ 已上线（[D1] 路由意图(主Dify) 日志确认，45s→10s；联系人表空待配置） | 2026-07-18 |
+| 批次 4 | 死代码大扫除（triage 三件套 + /approval/keywords + scheduler.py 孤儿 + 3 个 .bak + get_reply_stream ~96行） | #86 | ✅ 已部署（keywords 404，H5 200，无 ImportError） | 2026-07-18 |
+
+### 待部署清单（堡垒机恢复后一次性部署）
+
+~~后端 9 文件 + 前端 v17~~ **已全部部署完成（2026-07-18 01:35）**：
+- 后端：`docker compose restart backend` 无 ImportError；detect-intent 双端点 404 ✅；health 200 ✅
+- 前端：v17（`index-BxOIE0ES.js`），H5 HTTP 200，新 JS 已加载 ✅
+- 部署通道记录：`jms_ops.py upload` 的 elFinder 通道 GBK bug（`jumpserver_sftp_upload_v98.py` print emoji 崩溃）；>100KB 文件改用 `pack-upload`（目录直传）绕过
+
+## 四、关键上下文（新会话必读）
+
+### 4.1 部署铁律（详 `docs/04-运维文档/部署运维/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-V2\scripts\v2_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 全部任务书面化 |
@@ -0,0 +1,377 @@
+# 智能IT支持系统重构方案
+
+> 项目定位：基于企业微信自建应用的知识图谱驱动智能IT支持系统  
+> 文档版本：v1.0  
+> 日期：2026-07-03
+
+---
+
+## 一、项目背景与定位
+
+### 1.1 当前现状
+
+- 已有部分代码开发（Vue + WebSocket + Python 技术栈）
+- 核心问题：消息调通不稳定、UI 细节体验差（截图突兀、粘贴图片、头像）
+- 现有系统：ITSM/工单系统、AD/资产/零信任/杀毒等均已存在
+- 企业微信已作为企业内部 IM 通讯工具
+
+### 1.2 项目定位
+
+在企业微信工作台中构建自建 H5 应用，作为**智能 IT 支持系统**的统一入口，实现：
+
+- 员工通过在线咨询方式获取 IT 支持
+- AI 智能引导问题定位和处理
+- 对接现有 ITSM/工单、资产、AD、零信任等外部系统
+- 最大程度减少人工坐席介入，实现最快处理效率
+
+---
+
+## 二、核心设计理念
+
+### 2.1 交互模式：AI 增强人类客服（类萝卜快跑）
+
+不是传统的"机器人 → 转人工"模式，而是从一开始就**模糊机器人和人工的界限**：
+
+```
+用户视角：看到的只有一个"客服"
+背后实际：AI 实时辅助 + 真人客服确认
+```
+
+类比：萝卜快跑无人网约车——看似无人驾驶，背后有安全员随时准备接管。
+
+### 2.2 知识驱动：知识图谱替代决策树
+
+**不使用传统线性决策树**，而是采用**知识图谱驱动的动态探索**：
+
+| 维度 | 决策树 | 知识图谱 |
+|------|--------|----------|
+| 结构 | 线性的、固定的、单向的 | 网状的、动态的、多向的 |
+| 调整方式 | 修改一棵固定树 | 动态增删节点/关系 |
+| 学习能力 | 静态，需手动维护 | 自进化，AI 自动优化 |
+| 路径探索 | 唯一路径 | 多路径同时探索 |
+
+### 2.3 运作机制
+
+```
+用户输入 → 图谱匹配入口节点 → 弹出选择卡片 → 人机协同聚焦 → 自动执行 → 反馈优化图谱
+```
+
+整个过程中，用户、AI、坐席共同选择、聚焦、纠偏，最终得到目标结果。AI 通过这个过程不断扩大、优化、修正知识图谱。
+
+---
+
+## 三、系统架构
+
+### 3.1 四层架构
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                    接入层：企业微信 H5                         │
+│                    (OAuth2 登录，工作台入口)                    │
+├──────────────────────────────────────────────────────────────┤
+│                    客服层：GoFlyLiveChat                       │
+│              (坐席工作台 + 实时聊天 + AI 推荐回复)              │
+├──────────────────────────────────────────────────────────────┤
+│                    AI 推理层                                   │
+│         Dify (Agent 编排) + Neo4j (知识图谱) + RAG            │
+├──────────────────────────────────────────────────────────────┤
+│                    集成执行层                                  │
+│              中间件 (处理外部系统 API 调用)                     │
+│              现有系统：ITSM/工单/AD/资产/零信任/杀毒...         │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 3.2 各层职责
+
+| 层级 | 组件 | 职责 |
+|------|------|------|
+| 接入层 | 企业微信自建应用 | 统一入口、用户认证 |
+| 客服层 | GoFlyLiveChat | 实时聊天、坐席工作台、消息管理 |
+| AI 推理层 | Dify | 对话编排、Agent 调度、选择卡片生成 |
+| AI 推理层 | Neo4j | 知识图谱存储、Cypher 图遍历、路径推理 |
+| AI 推理层 | RAG | 文档检索（手册/FAQ/知识库文章） |
+| 集成执行层 | 自建中间件 | API 编排、自动化触发、数据转换 |
+| 集成执行层 | 现有系统 | ITSM/工单、AD、资产、零信任、杀毒 |
+
+---
+
+## 四、技术选型
+
+### 4.1 核心组件
+
+| 组件 | 产品 | 协议/成本 | 选择理由 |
+|------|------|----------|----------|
+| 客服系统 | GoFlyLiveChat | MIT/免费 | 开箱即用，消息调通，坐席工作台 |
+| AI 编排 | Dify | 开源免费 | 可视化工作流，Agent 编排，多 LLM 支持 |
+| 知识图谱 | Neo4j Community | 免费 | 原生图数据库，Cypher 查询，适合关系推理 |
+| LLM | DeepSeek/通义千问 | API 按量付费 | 国产模型，性价比高 |
+| 接入 | 企业微信自建应用 | 免费 | 统一入口，OAuth2 身份认证 |
+
+### 4.2 为什么不用微语
+
+| 对比项 | 微语 | 本方案 |
+|--------|------|--------|
+| 定位 | IM + 客服 + 工单全家桶 | 纯客服 + 知识图谱驱动 |
+| 成本 | ¥49,800（企业版买断） | 免费 |
+| 源码 | 商业开源，源码版额外付费 | 完全开源，自由修改 |
+| 定制 | 对话流有限 | Dify + Neo4j 灵活定制 |
+| 适配 | 单体架构 | 四层分离，现有系统不变 |
+
+### 4.3 组件职责矩阵
+
+| 组件 | 对话流 | 知识图谱 | 消息 | 坐席 | 文档检索 | 外部 API |
+|------|--------|----------|------|------|----------|----------|
+| GoFlyLiveChat | | | ✅ | ✅ | | |
+| Dify | ✅ | | | | | |
+| Neo4j | | ✅ | | | | |
+| RAG | | | | | ✅ | |
+| 中间件 | | | | | | ✅ |
+
+---
+
+## 五、知识图谱设计
+
+### 5.1 数据模型（Neo4j）
+
+#### 节点设计
+
+| 类型 | 标签 | 示例 |
+|------|------|------|
+| 业务域 | Domain | 网络域、安全域、设备域、账号域、应用域 |
+| 问题 | Issue | VPN 连不上、密码过期、电脑卡顿 |
+| 操作 | Action | 开通 VPN、重置密码、查资产信息 |
+| 系统 | System | 资产系统、AD、零信任、杀毒 |
+
+#### 边设计
+
+| 关系类型 | 含义 | 示例 |
+|----------|------|------|
+| BELONGS_TO | 属于 | 问题 → 业务域 |
+| CAUSES | 导致 | 密码过期 → VPN 不可用 |
+| REQUIRES | 需要 | 开通 VPN → 权限审批 |
+| LINKS_TO | 关联 | 问题 → 外部系统 API |
+| RECOMMENDS | 推荐 | 问题 → 建议操作 |
+
+#### 权重属性
+
+每条边维护：
+- `hit_count`：路径被选中的次数
+- `success_rate`：路径最终解决率
+- `last_used`：最近使用时间
+
+### 5.2 知识图谱与 RAG 协作
+
+| 能力 | 知识图谱（Neo4j） | RAG |
+|------|-------------------|-----|
+| 处理内容 | 结构化关系（节点-边） | 非结构化文档 |
+| 典型数据 | 业务域/问题/操作/系统 | IT 手册、FAQ、技术文档 |
+| 查询方式 | Cypher 图遍历 | 语义相似度搜索 |
+| 作用 | 定位路径、推理关联 | 检索答案内容 |
+
+**协作示例**：
+```
+用户："VPN 连不上"
+
+Neo4j 图谱遍历 → 定位到"VPN 问题 → 密码过期"路径
+        ↓
+RAG 检索 → 找到"如何重置 VPN 密码"的操作文档
+        ↓
+    合并输出：原因 + 操作步骤
+```
+
+### 5.3 冷启动策略
+
+- 从现有工单系统导出历史数据
+- 从 IT 团队经验文档提取
+- 整理常见 FAQ
+- 目标：初始导入 200-500 个节点
+
+---
+
+## 六、核心交互流程
+
+### 6.1 五步闭环
+
+| 步骤 | 动作 | 示例 |
+|------|------|------|
+| **1. 输入** | 用户输入问题描述 | "VPN 连不上" |
+| **2. 匹配** | LLM 理解意图 → Cypher 查询图谱 | 匹配到"VPN 问题"入口节点 |
+| **3. 选择** | 弹出确认卡片 + 邻居节点供选择 | "是密码过期？还是客户端错误？" |
+| **4. 聚焦** | 人 + AI + 坐席共同定位路径 | 选择 → 确认 → 纠正 → 聚焦 |
+| **5. 执行+反馈** | 到达终点节点 → 自动执行 → 反馈优化 | 执行操作 + 更新图谱权重 |
+
+### 6.2 完整场景示例
+
+**场景：员工开通 VPN 账号**
+
+| 步骤 | 交互 |
+|------|------|
+| 用户 | "我想开 VPN" |
+| AI 推理 | Neo4j 匹配到"VPN 账号开通"节点 → 弹出确认卡片 |
+| 用户 | 点击"确认" |
+| AI 推理 | 沿图谱边展开邻居节点 → 弹出选择："个人 / 团队 / 项目" |
+| 用户 | 选择"个人" |
+| 中间件 | 自动查询 AD 组织架构、资产信息、安全状态 |
+| AI 推理 | 条件满足 → 自动审批通过 |
+| 中间件 | 调用零信任 API 开通账号 |
+| 结果 | "您的 VPN 账号已开通，密码见邮件" |
+| 反馈 | 本次路径记录成功 → Neo4j 更新权重 |
+
+---
+
+## 七、外部系统集成
+
+### 7.1 集成清单
+
+| 系统 | 集成方式 | 数据用途 |
+|------|----------|----------|
+| 现有 ITSM/工单 | REST API / 同步 | 工单创建、状态同步、历史查询 |
+| AD/LDAP | LDAP API | 组织架构、用户身份 |
+| 资产系统 | REST API | 设备信息、资产归属 |
+| 零信任/VPN | REST API | 权限查询、账号开通 |
+| 网络准入 | REST API | 准入状态、违规记录 |
+| 杀毒系统 | REST API / 日志 | 终端安全状态 |
+| 监控系统 | Webhook | 告警信息 |
+
+### 7.2 中间件设计
+
+```
+┌─────────────────────────────────────────┐
+│              中间件 (Python)             │
+│  ┌─────────────────────────────────────┐│
+│  │          API 编排引擎               ││
+│  │  • 并行调用多个系统 API             ││
+│  │  • 数据聚合和格式转换               ││
+│  └─────────────────────────────────────┘│
+│  ┌─────────────────────────────────────┐│
+│  │          自动化规则引擎             ││
+│  │  • 条件触发（满足 X 则执行 Y）       ││
+│  │  • 工作流编排                       ││
+│  └─────────────────────────────────────┘│
+│  ┌─────────────────────────────────────┐│
+│  │         工单同步引擎                 ││
+│  │  • 双向同步（创建/状态/评论/附件）   ││
+│  │  • Webhook 实时推送                 ││
+│  └─────────────────────────────────────┘│
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 八、坐席工作台设计
+
+### 8.1 坐席视角
+
+| 区域 | 功能 |
+|------|------|
+| 对话窗口 | 与用户实时聊天 |
+| AI 推荐回复区 | AI 实时推荐话术/答案 |
+| 知识图谱导航 | 展示当前图谱节点和可选路径 |
+| 外部系统信息 | 资产/账号/安全状态等 |
+| 一键操作 | 发送推荐回复、触发自动化 |
+
+### 8.2 用户视角
+
+- 无机器人标识
+- 无感知 AI 存在
+- 对话体验如真人
+- 真人客服把关每条回复
+
+---
+
+## 九、分阶段实施计划
+
+### P0：MVP 原型（1-2 个月）
+
+| 任务 | 内容 |
+|------|------|
+| GoFlyLiveChat 部署 | Docker 部署，消息调通 |
+| 企业微信 H5 集成 | OAuth2 登录，工作台入口 |
+| Neo4j 搭建 | Docker 部署，初始数据导入 |
+| 基础对话流 | 用户输入 → 图谱匹配 → 选择卡片 |
+
+### P1：核心功能（3-4 个月）
+
+| 任务 | 内容 |
+|------|------|
+| LLM 推理集成 | Dify + DeepSeek 部署 |
+| RAG 知识库 | 企业 IT 文档导入 |
+| 选择卡片交互 | 多轮确认、路径聚焦 |
+| 坐席纠偏功能 | 人工修正路径 |
+
+### P2：智能化（5-6 个月）
+
+| 任务 | 内容 |
+|------|------|
+| 外部系统集成 | AD/资产/零信任等对接 |
+| 自动化处理 | 审批、开通、工单生成 |
+| 图谱权重优化 | 基于反馈更新边权重 |
+| 绩效统计 | 响应时长、解决率 |
+
+### P3：自进化（7-8 个月）
+
+| 任务 | 内容 |
+|------|------|
+| AI 自动扩展图谱 | 未知问题 → 自动新增节点 |
+| 自动淘汰噪音 | 低命中路径自动衰减 |
+| 批量自动化 | 批量处理常见问题 |
+| 多租户/权限 | 多部门隔离 |
+
+---
+
+## 十、硬件与部署
+
+### 10.1 服务器配置
+
+| 组件 | 最低配置 | 推荐配置 |
+|------|----------|----------|
+| GoFlyLiveChat | 2核 4GB | 4核 8GB |
+| Neo4j | 2核 4GB | 4核 8GB |
+| Dify | 4核 8GB | 8核 16GB |
+| 中间件 | 2核 2GB | 2核 4GB |
+| **总计** | **约 10核 18GB** | **约 18核 36GB** |
+
+### 10.2 部署方式
+
+- 所有组件 Docker 容器化
+- Kubernetes 编排（可选，满足微服务架构需求）
+- 内网部署，数据不外泄
+
+---
+
+## 十一、成本估算
+
+| 项目 | 成本 |
+|------|------|
+| GoFlyLiveChat | 免费 |
+| Neo4j Community | 免费 |
+| Dify | 免费 |
+| DeepSeek API | 按量（约 ¥500-2000/月） |
+| 服务器 | 按企业现有资源 |
+| 开发人力 | 约 2-3 人，8 个月 |
+| **软件总成本** | **约 ¥500-2000/月** |
+
+---
+
+## 十二、技术风险与应对
+
+| 风险 | 应对措施 |
+|------|----------|
+| 知识图谱冷启动 | 从历史工单 + 团队经验导入 |
+| LLM 推理不确定性 | 坐席兜底机制，AI 推荐而非自动发送 |
+| 多系统集成复杂度 | 先对接核心系统，逐步扩展 |
+| 企微内置浏览器兼容 | H5 适配，避免使用不兼容特性 |
+
+---
+
+## 十三、总结
+
+本方案核心解决了以下问题：
+
+1. **入口统一**：企业微信工作台自建应用
+2. **消息可靠**：GoFlyLiveChat 开源成熟方案
+3. **智能定位**：知识图谱 + RAG 替代传统决策树
+4. **人机协同**：AI 增强人类客服，而非替代
+5. **系统集成**：对接现有 ITSM/工单/AD/资产/零信任等
+6. **自进化**：使用反馈持续优化知识图谱
+7. **开源免费**：核心组件全部免费，成本可控