simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
566bb46cd445a70f7f7bc623cea7f1d687e542dc
wecom_it_smart_desk/docs/03-技术架构/增量设计-知识库迭代与痛点缓解-20260711.md
T

2082 lines
72 KiB
Markdown
Raw Normal View History

feat: 2026-07-11 全量更新 - 代办集成+会议室预定+知识迭代修复+UI统一+Bug修复
2026-07-11 23:13:10 +08:00
# 增量设计：知识库迭代与痛点缓解
> **文档版本**：v1.0
> **创建日期**：2026-07-11
> **文档类型**：回溯文档（已部署功能）+ 前瞻设计（未实现功能）
> **测试报告引用**：`docs/06-测试质量/Tier0-测试报告-20260708.md`（89/89 通过）
> **技术栈**：FastAPI + SQLAlchemy + PostgreSQL + Redis + Neo4j / Vue3 + Element Plus + Vant4 + ECharts
---
## 目录
1. [概述](#1-概述)
2. [系统架构总览](#2-系统架构总览)
3. [各功能模块技术方案](#3-各功能模块技术方案)
- 3.1 [分诊交互](#31-分诊交互)
- 3.2 [置信门控](#32-置信门控)
- 3.3 [内联审批卡片](#33-内联审批卡片)
- 3.4 [拓扑预览](#34-拓扑预览)
- 3.5 [重复检测](#35-重复检测)
- 3.6 [代答排除](#36-代答排除)
- 3.7 [知识迭代管理](#37-知识迭代管理)
- 3.8 [图谱可视化](#38-图谱可视化)
- 3.9 [合并去重](#39-合并去重)
- 3.10 [会话关闭→建议→审核→写图](#310-会话关闭建议审核写图)
4. [功能依赖关系图](#4-功能依赖关系图)
5. [全链路数据流图](#5-全链路数据流图)
6. [未实现功能设计](#6-未实现功能设计)
7. [已知问题与后续优化方向](#7-已知问题与后续优化方向)
---
## 1. 概述
### 1.1 功能背景
IT智能服务台在持续运营中暴露出三大痛点：
1. **知识库更新滞后**：AI 回复不准确的问题需要人工发现→人工编写→人工录入，平均更新周期超过 2 周。
2. **低置信回复无兜底**：AI 回复 confidence 低于阈值时，员工无感知，直接收到低质量回答，体验差。
3. **重复知识堆积**：多个来源（会话分析、标注分析、手动录入）生成的建议缺乏去重机制，导致知识图谱中出现重复 Issue 节点。
为解决上述痛点，本项目实施了"知识库迭代与痛点缓解"功能集，包含 10 个功能模块，覆盖从 AI 回复质量保障到知识图谱自动维护的完整闭环。
### 1.2 目标
| 目标 | 衡量指标 |
|------|---------|
| 知识库自动迭代 | 会话关闭后自动生成知识建议，训练师审核后自动写入知识图谱 |
| 低置信兜底 | confidence < 0.7 时前端展示转人工入口，携带上下文快照 |
| 知识去重 | 采纳建议前检测重复，支持合并去重操作 |
| 图谱可视化 | 管理后台 ECharts 力导向图展示 Neo4j 知识图谱全貌 |
| 分步分诊 | 复杂问题拆分为分步选择题，降低员工认知负担 |
### 1.3 范围
本功能集涉及 10 个功能模块，按部署状态分为两类：
| # | 功能 | 代码状态 | 部署状态 | 文档类型 |
|---|------|---------|---------|---------|
| 1 | 分诊交互 | 仅前端组件 | 未接入后端 | 前瞻设计 |
| 2 | 置信门控 | 后端配置 + 前端组件 | 生产在线 | 回溯文档 |
| 3 | 内联审批卡片 | 后端 + 前端 | 生产在线 | 回溯文档 |
| 4 | 拓扑预览 | 仅原型 SVG | 未实现后端子图查询 API 对接 | 前瞻设计 |
| 5 | 重复检测 | 后端 + 前端 | 生产在线 | 回溯文档 |
| 6 | 代答排除 | 仅前端组件方法 | 未实现 | 前瞻设计 |
| 7 | 知识迭代管理 | 47KB 服务 + 21KB API | 生产在线 | 回溯文档 |
| 8 | 图谱可视化 | Neo4j + ECharts | Neo4j 运行中 | 回溯文档 |
| 9 | 合并去重 | 后端 + 前端 | 生产在线 | 回溯文档 |
| 10 | 会话关闭→建议→审核→写图 | 全链路 | 生产在线 | 回溯文档 |
### 1.4 术语表
| 术语 | 说明 |
|------|------|
| KnowledgeSuggestion | 知识建议，AI 分析生成的待审核知识条目 |
| Issue | 知识图谱中的问题节点（Neo4j :Issue 标签） |
| Action | 知识图谱中的动作/解决方案节点（Neo4j :Action 标签） |
| confidence | AI 生成置信度（0.0-1.0），门控阈值 0.7 |
| audience | 受众类型：employee_quick_reply（员工快捷回复）/ engineer_workguide（工程师作业指导） |
| 五态流转 | pending → queued → approved → applied → graph_synced |
| 通道 A | 会话/标注/AI不确定 → 自动生成知识建议 |
| 通道 B | 训练师手动录入知识建议 |
| 通道 C | RAGFlow 文档 ETL → 知识建议（预留，未实现） |
---
## 2. 系统架构总览
### 2.1 架构总览图
```mermaid
graph TB
subgraph "H5 员工端"
H5_Triage[分诊卡片 TriageCard]
H5_ConfGate[置信门控 ConfidenceGateBanner]
H5_Chat[AI 对话]
end
subgraph "Agent 坐席端"
AG_Approval[内联审批卡片 ApprovalInlineCard]
AG_Queue[独立审批队列 ApprovalQueue]
AG_Chat[坐席会话]
end
subgraph "Admin 管理后台"
ADM_Knowledge[知识迭代管理 KnowledgeIteration]
ADM_Graph[图谱可视化 ECharts]
end
subgraph "Backend FastAPI"
API_Conv[会话 API conversations.py]
API_KI[知识迭代 API knowledge_iteration.py]
API_Queue[审批队列 API approval_queue.py]
Svc_KI[知识迭代服务 KnowledgeIterationService]
Svc_Wingman[Wingman AI 服务]
Neo4j_Client[Neo4j 客户端]
end
subgraph "数据存储"
PG[(PostgreSQL)]
Redis[(Redis)]
Neo4j[(Neo4j 图数据库)]
Dify[Dify AI 平台]
end
%% H5 交互
H5_Chat -->|AI回复| H5_ConfGate
H5_Triage -->|分步选择| H5_Chat
H5_ConfGate -->|confidence<0.7| API_Conv
%% 会话关闭触发
AG_Chat -->|结单| API_Conv
API_Conv -->|异步触发| Svc_KI
Svc_KI -->|调用AI| Svc_Wingman
Svc_Wingman --> Dify
Svc_KI -->|写入建议| PG
%% 审批流程
AG_Approval -->|采纳/驳回/改写| API_KI
AG_Queue -->|队列审批| API_Queue
ADM_Knowledge -->|管理审核| API_KI
%% 知识落库 + 写图
API_KI --> Svc_KI
Svc_KI -->|创建KB条目| PG
Svc_KI -->|写图| Neo4j_Client
Neo4j_Client --> Neo4j
%% 图谱可视化
ADM_Graph -->|查询图数据| API_KI
API_KI --> Neo4j_Client
%% 重复检测
ADM_Knowledge -->|检查重复| API_KI
API_KI --> Svc_KI
Svc_KI -->|查SQL| PG
Svc_KI -->|查图| Neo4j_Client
style H5_Triage fill:#fff3e0,stroke:#ff9800
style H5_ConfGate fill:#e8f5e9,stroke:#4caf50
style AG_Approval fill:#e3f2fd,stroke:#2196f3
style Neo4j fill:#e8eaf6,stroke:#3f51b5
style Dify fill:#fce4ec,stroke:#e91e63
```
### 2.2 技术栈分布
| 层级 | 技术选型 | 说明 |
|------|---------|------|
| 后端框架 | FastAPI + SQLAlchemy 2.0 (async) | 异步 ORM，AsyncSession |
| 关系数据库 | PostgreSQL | knowledge_suggestions、knowledge_base 表 |
| 图数据库 | Neo4j 6.2.0 (AsyncDriver) | Issue/Action 节点 + 关系边 |
| 缓存 | Redis | 会话状态、恢复点 |
| AI 平台 | Dify (Wingman Agent) | 知识建议生成、意图识别 |
| 管理后台 | Vue3 + Element Plus + ECharts | 列表管理 + 力导向图 |
| 坐席端 | Vue3 + Element Plus | 内联审批卡片 + 队列 |
| H5 员工端 | Vue3 + Vant4 | 分诊卡片 + 置信门控横幅 |
| 风格 | 企微浅色扁平 | accent=#07C160 |
### 2.3 API 路由前缀
| 模块 | 前缀 | 说明 |
|------|------|------|
| 知识迭代管理 | `/api/admin/knowledge-iteration/*` | 12 条路由 |
| 独立审批队列 | `/api/admin/approval-queue/*` | 3 条路由 |
| 会话管理 | `/api/conversations/*` | 含结单触发 |
---
## 3. 各功能模块技术方案
---
### 3.1 分诊交互
#### 功能描述
AI 分诊式回复，将复杂 IT 问题拆分为分步选择题（是/否/含概率推荐），卡片置顶悬浮展示，支持专家模式切换。
**当前状态**：仅前端组件（`TriageCard.vue`），未接入后端 API。
#### 数据模型
```mermaid
classDiagram
class TriageStep {
+String question
+List~TriageOption~ options
+List~String~ collectedContext
}
class TriageOption {
+String label
+Boolean selected
+Number probability
+Boolean recommended
+Boolean excluded
}
class TriageCard {
+Boolean visible
+Number step
+Number total
+List~TriageStep~ steps
+Number confidence
+toggleCollapse()
+selectOption(idx)
+handleConfirm()
+handleSkip()
+setExcludedOptions(labels)
+setRecommendedOption(label)
}
TriageCard --> TriageStep : contains
TriageStep --> TriageOption : contains
```
#### API 接口设计（前瞻 — 未实现）
| 方法 | 路径 | 请求 | 响应 | 说明 |
|------|------|------|------|------|
| POST | `/api/h5/triage/start` | `{conversation_id, question}` | `{steps: TriageStep[], total: int}` | 发起分诊，AI 拆分复杂问题为分步选择题 |
| POST | `/api/h5/triage/step` | `{conversation_id, step_index, selected_label}` | `{next_step: TriageStep, collected_context: string[]}` | 提交当前步骤选择，获取下一步 |
| POST | `/api/h5/triage/skip` | `{conversation_id, step_index}` | `{next_step: TriageStep}` | 跳过当前步骤 |
| POST | `/api/h5/triage/transfer` | `{conversation_id, context: string[]}` | `{conversation_id, status: "waiting_agent"}` | 分诊上下文转人工 |
#### 核心流程（前瞻设计）
```mermaid
sequenceDiagram
participant H5 as H5 员工端
participant API as FastAPI 后端
participant Dify as Dify AI
participant DB as PostgreSQL
H5->>API: POST /api/h5/triage/start {conversation_id, question}
API->>Dify: 调用 Dify 分诊 prompt（拆分复杂问题为分步）
Dify-->>API: 返回 steps[] (question + options + probability)
API-->>H5: {steps, total}
loop 每一步
H5->>H5: 展示 TriageCard，员工选择选项
H5->>API: POST /api/h5/triage/step {step_index, selected_label}
API->>DB: 记录已收集上下文
API->>Dify: 根据选择动态调整后续步骤
Dify-->>API: 返回 next_step
API-->>H5: {next_step, collected_context}
end
alt 所有步骤完成
H5->>API: POST /api/h5/triage/complete
API->>Dify: 根据收集的上下文生成最终答案
Dify-->>API: 返回最终回复
API-->>H5: 返回 AI 回复
else 转人工
H5->>API: POST /api/h5/triage/transfer {context}
API->>DB: 会话状态 → waiting_agent
API-->>H5: 转人工成功
end
```
#### 前端交互设计
**组件文件**：`frontend-h5/src/components/TriageCard.vue`
| 交互元素 | 说明 |
|---------|------|
| 置顶悬浮 | `position: sticky; top: 0; z-index: 100` |
| 步骤进度 | "第 X/Y 步" 显示在标题栏 |
| 选项列表 | 单选模式，点击选中/取消 |
| 概率展示 | 百分比标签（≥70% 绿色高亮），不披露原始 confidence |
| 推荐标记 | ⭐推荐 标签（坐席侧设置） |
| 排除标记 | 已排除 标签 + 灰显 + 不可点击 |
| 专家模式 | van-switch 开关，开启后展示后续步骤预览 |
| 折叠/展开 | 点击标题栏切换 |
| 底部操作 | "跳过" + "下一步/完成" |
**关键设计约束（D4 硬约束）**：
- 一次给几步由 AI 判复杂度自适应
- 概率展示为百分比（不披露原始 confidence 给员工）
- 专家模式默认关（分步），老手可开一把梭
- 卡片置顶/悬浮
#### 技术选型与依赖
| 依赖 | 版本 | 用途 |
|------|------|------|
| Vue3 | ^3.4 | 响应式框架 |
| Vant4 | ^4.8 | 移动端 UI（van-switch, van-button, van-tag） |
#### 部署状态
**未实现** — 前端组件已开发（530 行），但后端 API 未实现，Dify 分诊 prompt 未配置。
---
### 3.2 置信门控
#### 功能描述
当 AI 回复的 confidence 低于全局阈值 0.7 时，在 H5 前端渲染"转人工"入口并附已收集的上下文快照。门控阈值可通过 `settings.confidence_gate_threshold` 配置。
**当前状态**：生产在线。后端配置项 + 前端组件 + composable 逻辑封装。
#### 数据模型
```mermaid
classDiagram
class ConfidenceGateConfig {
+Float confidence_gate_threshold = 0.7
+String source = "settings.confidence_gate_threshold"
}
class ConfidenceGateResult {
+Boolean triggered
+Number displayProbability
+String severity
+Boolean shouldShowTransfer
}
class useConfidenceGate {
+Ref~Float~ gateThreshold
+Ref~Number~ lastConfidence
+Ref~String[]~ contextSnapshot
+Computed~ConfidenceGateResult~ gateResult
+Computed~Boolean~ showGateBanner
+evaluateConfidence(confidence, context)
+addContext(items)
+prepareTransferToHuman() String[]
+reset()
+updateThreshold(newThreshold)
}
class ConfidenceGateBanner {
+Boolean visible
+Number confidence
+String[] contextSnapshot
+String reason
+displayProbability
+severityClass
+handleTransferToHuman()
+handleContinueAI()
}
useConfidenceGate --> ConfidenceGateResult : produces
ConfidenceGateBanner --> useConfidenceGate : consumes
```
#### 配置项
| 配置项 | 默认值 | 来源 | 说明 |
|--------|--------|------|------|
| `confidence_gate_threshold` | 0.7 | `config.py` → `CONFIDENCE_GATE_THRESHOLD` 环境变量 | 全局置信门控阈值 |
```python
# backend/app/config.py
confidence_gate_threshold: float = 0.7
```
#### 核心流程
```mermaid
sequenceDiagram
participant H5 as H5 员工端
participant Gate as useConfidenceGate
participant Banner as ConfidenceGateBanner
participant API as FastAPI 后端
H5->>API: 发送问题
API->>API: AI 回复 + confidence 值
API-->>H5: {reply, confidence: 0.45}
H5->>Gate: evaluateConfidence(0.45, context)
Gate->>Gate: triggered = 0.45 < 0.7 = true
Gate->>Gate: severity = "warning" (0.3 ≤ 0.45 < 0.5)
Gate-->>H5: gateResult = {triggered: true, shouldShowTransfer: true}
H5->>Banner: visible=true, confidence=0.45
Banner->>Banner: displayProbability = 45%
Banner->>Banner: severityClass = "warning"
Banner-->>H5: 展示横幅 + "转人工" + "继续询问 AI"
alt 员工点击转人工
Banner->>Gate: prepareTransferToHuman()
Gate-->>Banner: contextSnapshot[]
Banner->>API: POST /api/conversations/transfer {context}
API-->>Banner: 转人工成功
else 员工点击继续询问 AI
Banner->>Gate: dismissGate()
Gate-->>H5: dismissed = true
end
```
#### 前端交互设计
**组件文件**：`frontend-h5/src/components/ConfidenceGateBanner.vue`
**逻辑封装**：`frontend-h5/src/composables/useConfidenceGate.ts`
| 严重程度 | 条件 | 配色 | 图标 | 文案 |
|---------|------|------|------|------|
| critical | confidence < 0.3 | 红色背景 `#fff0f0` + 红色左边框 `#ee0a24` | 🚨 | AI 非常不确定此回复，建议转人工处理 |
| warning | 0.3 ≤ confidence < 0.5 | 橙色背景 `#fff7f0` + 橙色左边框 `#ff976a` | ⚠️ | AI 对此回复把握较低，可能需要人工协助 |
| caution | 0.5 ≤ confidence < 0.7 | 蓝色背景 `#f0f7ff` + 蓝色左边框 `#1989fa` | 💡 | AI 对此回复不太确定，你可选择转人工确认 |
**展示元素**：
- AI 把握度：百分比整数（如 "45%"），不显示原始 0.45
- 已收集上下文快照：标签列表
- 操作按钮："转人工处理"（danger）+ "继续询问 AI"（default）
- 反馈理由选项：答非所问/信息不完整/回答不准确/过于笼统/其他
#### 技术选型与依赖
| 依赖 | 版本 | 用途 |
|------|------|------|
| Vue3 | ^3.4 | Composition API |
| Vant4 | ^4.8 | van-button, van-tag |
#### 部署状态
**生产在线** — 后端配置项 `confidence_gate_threshold=0.7` 已在 config.py 中定义，前端 `ConfidenceGateBanner.vue` + `useConfidenceGate.ts` 已部署。
---
### 3.3 内联审批卡片
#### 功能描述
坐席在会话中直接审批知识建议的内联卡片，支持采纳/驳回/改写操作，展示拓扑预览、confidence、audience 下拉编辑。未处理的提案在会话关闭后进入独立审批队列。
**当前状态**：生产在线。后端 API + 前端组件完整实现。
#### 数据模型
```mermaid
classDiagram
class KnowledgeSuggestion {
+String id
+String suggestion_type
+String status
+String title
+String content
+String category
+List~String~ tags
+String source_type
+List~String~ source_data
+Float confidence
+String audience
+String issue
+String action
+String relation_type
+String parent_issue
+Dict graph_meta
+String graph_sync_status
+Boolean source_failed
+DateTime queued_at
+DateTime applied_at
+String reviewer_id
+DateTime reviewed_at
+String reject_reason
}
class SuggestionStatusEnum {
<<enumeration>>
pending
queued
approved
rejected
applied
graph_synced
expired
}
class ApprovalInlineCard {
+SuggestionData suggestion
+Boolean readonly
+DuplicateItem[] duplicates
+handleApprove()
+handleReject()
+toggleRewrite()
+submitRewrite()
+onAudienceChange()
}
ApprovalInlineCard --> KnowledgeSuggestion : displays
KnowledgeSuggestion --> SuggestionStatusEnum : status
```
#### 状态机
```mermaid
stateDiagram-v2
[*] --> pending : AI生成/手动录入
pending --> queued : 会话关闭未处理
pending --> approved : 内联审批通过
pending --> rejected : 驳回
pending --> expired : 超时
queued --> approved : 队列审批通过
queued --> rejected : 队列驳回
queued --> expired : 超时
approved --> applied : KB条目落库
approved --> rejected : 撤销
applied --> graph_synced : Neo4j写图成功
rejected --> [*] : 终态
graph_synced --> [*] : 终态
expired --> [*] : 终态
```
**合法状态转换表**（`schemas/enums.py`）：
| 当前状态 | 允许转换到 |
|---------|-----------|
| pending | queued, approved, rejected, expired |
| queued | approved, rejected, expired |
| approved | applied, rejected |
| applied | graph_synced |
| graph_synced | （终态） |
| rejected | （终态） |
| expired | （终态） |
#### API 接口设计
| 方法 | 路径 | 请求体 | 响应 | 说明 |
|------|------|--------|------|------|
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/approve` | `{}` | `{code:0, data: KnowledgeSuggestionResponse}` | 审核通过（触发 KB 落库 + Neo4j 写图） |
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/reject` | `{reject_reason: string}` | `{code:0, data: KnowledgeSuggestionResponse}` | 审核拒绝 |
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/rewrite` | `{title?, content?, category?, ...}` | `{code:0, data: KnowledgeSuggestionResponse}` | 改写提案（重置为 pending） |
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/queue` | — | `{code:0, data: KnowledgeSuggestionResponse}` | 放入独立队列 |
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/dequeue-approve` | — | `{code:0, data: KnowledgeSuggestionResponse}` | 队列中审批通过 |
| GET | `/api/admin/approval-queue/queued` | `?status=&audience=&page=&page_size=` | `{code:0, data:{total, items[]}}` | 获取队列列表 |
| GET | `/api/admin/approval-queue/queued/stats` | — | `{code:0, data:{queued_total, pending_total, by_audience, by_source_type}}` | 队列统计 |
| POST | `/api/admin/approval-queue/queued/{id}/dequeue-approve` | — | `{code:0, data: KnowledgeSuggestionResponse}` | 队列审批通过 |
#### 核心流程
```mermaid
sequenceDiagram
participant AG as 坐席端 ApprovalInlineCard
participant API as FastAPI
participant Svc as KnowledgeIterationService
participant DB as PostgreSQL
participant Neo4j as Neo4j
Note over AG: 提案 status=pending/queued
alt 采纳
AG->>API: POST /suggestions/{id}/approve
API->>Svc: approve_suggestion(db, id, reviewer_id, neo4j_client)
Svc->>Svc: 校验状态转换 pending/queued → approved
Svc->>DB: 更新 status=approved, reviewer_id, reviewed_at
Svc->>DB: 创建 KnowledgeBase 条目 → status=applied
Svc->>Neo4j: sync_to_neo4j (merge_issue + merge_action + create_relation)
alt 写图成功
Svc->>DB: status=graph_synced, graph_sync_status=synced
Svc->>DB: 回填 kb.graph_node_uuid
else 写图失败
Svc->>DB: graph_sync_status=failed
end
Svc-->>API: suggestion (graph_synced)
API-->>AG: {code:0, data: suggestion}
end
alt 驳回
AG->>API: POST /suggestions/{id}/reject {reject_reason}
API->>Svc: reject_suggestion(db, id, reviewer_id, reason)
Svc->>DB: status=rejected, reject_reason
Svc-->>API: suggestion (rejected)
API-->>AG: {code:0, data: suggestion}
end
alt 改写
AG->>API: POST /suggestions/{id}/rewrite {title, content, ...}
API->>Svc: rewrite_suggestion(db, id, reviewer_id, data)
Svc->>DB: 更新字段 + status=pending (重置)
Svc-->>API: suggestion (pending)
API-->>AG: {code:0, data: suggestion}
end
alt 入队
AG->>API: POST /suggestions/{id}/queue
API->>Svc: queue_suggestion(db, id)
Svc->>Svc: 校验 pending → queued
Svc->>DB: status=queued, queued_at
Svc-->>API: suggestion (queued)
API-->>AG: {code:0, data: suggestion}
end
```
#### 前端交互设计
**组件文件**：`frontend-agent/src/components/chat/ApprovalInlineCard.vue`
| 卡片区域 | 元素 | 说明 |
|---------|------|------|
| 头部 | 类型图标 + 类型文本 | 💡新FAQ / 🔄内容更新 / 🔀合并去重 |
| 头部 | 置信度标签 | ≥70% success / ≥50% warning / <50% danger |
| 头部 | 状态标签 | pending/queued/approved/rejected/applied/graph_synced |
| 头部 | 重复标记 | ⚠可能重复（danger, effect=dark） |
| 重复警告 | 重复项列表 | 名称 + 类型标签 + 相似度百分比 |
| 核心信息 | 标题 + 内容 | 内容截断 150 字符 |
| 拓扑预览 | SVG 缩略图 | parent_issue → issue → action 节点链 |
| 拓扑预览 | 文本流 | 蓝色 parent → 绿色 issue → 橙色 action |
| audience | 下拉选择 | employee_quick_reply / engineer_workguide |
| 改写表单 | 标题/内容/分类输入框 | 展开时显示，提交后重置 pending |
| 操作按钮 | 采纳(success) / 改写(warning) / 驳回(danger) | readonly 时显示已处理状态 |
#### 技术选型与依赖
| 依赖 | 版本 | 用途 |
|------|------|------|
| Vue3 | ^3.4 | Composition API |
| Element Plus | ^2.6 | el-tag, el-select, el-input, el-button |
#### 部署状态
**生产在线** — 后端 `knowledge_iteration.py` + `approval_queue.py` + 前端 `ApprovalInlineCard.vue` + `ApprovalQueue.vue` 均已部署。
---
### 3.4 拓扑预览
#### 功能描述
在审批卡片中展示知识建议对应的图谱拓扑结构（Issue → Action 小缩略图），帮助训练师直观理解建议的图谱关系。
**当前状态**：仅前端 SVG 原型缩略图。后端 `query_issue_subgraph` 方法已实现但未通过 API 暴露给前端调用。
#### 数据模型
拓扑预览数据来源于 `KnowledgeSuggestion` 的图字段：
```mermaid
classDiagram
class TopologyPreview {
+String parent_issue
+String issue
+String action
+String relation_type
}
class MiniGraphNode {
+Number x
+Number y
+String label
+String type
}
class MiniGraphEdge {
+Number x1
+Number y1
+Number x2
+Number y2
}
TopologyPreview --> MiniGraphNode : generates
TopologyPreview --> MiniGraphEdge : generates
```
#### 已实现部分
**前端 SVG 缩略图**（`ApprovalInlineCard.vue`）：
- 根据 `suggestion.parent_issue`、`suggestion.issue`、`suggestion.action` 三个字段生成节点
- 节点颜色：parent=蓝色 `#409eff`、issue=绿色 `#67c23a`、action=橙色 `#e6a23c`
- 节点间距 90px，半径 issue=12px / action=9px
- 虚线连线 `stroke-dasharray="4,2"`
- 标签超过 6 字符截断为 "前6字…"
**后端子图查询**（`neo4j_client.py`）：
- `query_issue_subgraph(issue_name, depth=1)` 方法已实现
- 以指定 Issue 为中心，向外扩展 depth 层关系
- 返回 ECharts 格式的 `{nodes, links}`
#### API 接口设计（前瞻 — 需新增）
| 方法 | 路径 | 请求 | 响应 | 说明 |
|------|------|------|------|------|
| GET | `/api/admin/knowledge-iteration/suggestions/{id}/topology` | — | `{code:0, data:{nodes:[], links:[]}}` | 获取建议对应的图谱子图拓扑 |
#### 前瞻设计方案
1. **新增 API 端点**：在 `knowledge_iteration.py` 中添加 `/suggestions/{id}/topology` 路由
2. **调用链**：API → `neo4j_client.query_issue_subgraph(issue_name, depth=1)` → 返回子图 JSON
3. **前端增强**：`ApprovalInlineCard.vue` 中将 SVG 缩略图替换为 ECharts mini graph（或保留 SVG + 可点击展开）
4. **交互**：点击缩略图弹出全屏子图预览 modal
#### 部署状态
**部分实现** — 前端 SVG 缩略图已实现（基于 suggestion 字段静态渲染），后端子图查询方法已实现但未通过 API 暴露。
---
### 3.5 重复检测
#### 功能描述
在采纳知识建议前检测是否存在重复，利用 Neo4j 图结构（同名 Issue）+ SQL 文本相似（标题模糊匹配）双重检测，返回重复项列表供训练师参考。
**当前状态**：生产在线。
#### 数据模型
```mermaid
classDiagram
class DuplicateResult {
+String type
+String name
+String suggestion_id
+String suggestion_type
+String issue
+String action
+String status
+Float similarity
+String source
}
class FindDuplicatesParams {
+String issue_name
+String title
+String suggestion_id
+Neo4jClient neo4j_client
}
class KnowledgeIterationService {
+find_duplicates(db, issue_name, title, suggestion_id, neo4j_client) List~DuplicateResult~
+_calc_similarity(a, b) Float
}
KnowledgeIterationService --> DuplicateResult : produces
```
#### 重复检测类型
| 类型 | 来源 | 检测方式 | 相似度计算 |
|------|------|---------|-----------|
| `same_issue` | Neo4j | 同名 Issue 节点精确匹配 | 1.0 |
| `similar_issue` | Neo4j | Issue 名称前缀匹配（前 10 字符） | 公共前缀 / 最大长度 |
| `title_similar` | SQL | 标题 ILIKE 模糊匹配（前 20 字符） | 前缀匹配 + 长度比 |
**相似度计算算法**（`_calc_similarity`）：
1. 完全匹配 → 1.0
2. 包含匹配 → 0.5 + 0.5 × (shorter / longer)
3. 公共前缀匹配 → common_prefix_len / max_len
#### API 接口设计
| 方法 | 路径 | 请求 | 响应 | 说明 |
|------|------|------|------|------|
| GET | `/api/admin/knowledge-iteration/suggestions/{id}/duplicates` | — | `{code:0, data:{suggestion_id, has_duplicates: bool, duplicates: DuplicateResult[]}}` | 检查指定建议是否存在重复 |
#### 核心流程
```mermaid
sequenceDiagram
participant ADM as 管理后台
participant API as FastAPI
participant Svc as KnowledgeIterationService
participant DB as PostgreSQL
participant Neo4j as Neo4j
ADM->>API: GET /suggestions/{id}/duplicates
API->>DB: 查询 suggestion (获取 issue, title)
DB-->>API: suggestion
API->>Svc: find_duplicates(db, issue, title, id, neo4j_client)
rect rgb(245, 247, 250)
Note over Svc,DB: 1. SQL 层面：标题模糊匹配
Svc->>DB: SELECT * FROM knowledge_suggestions WHERE status IN (approved, applied, graph_synced) AND title ILIKE '%keyword%' AND id != suggestion_id
DB-->>Svc: sql_duplicates[]
Svc->>Svc: 计算 title_similar 相似度
end
rect rgb(232, 234, 246)
Note over Svc,Neo4j: 2. Neo4j 层面：同名 Issue
Svc->>Neo4j: find_issue_by_name(issue_name)
Neo4j-->>Svc: existing_issue (含 source_suggestion_id)
Svc->>DB: 查关联 suggestion
Svc->>Svc: 记录 same_issue (similarity=1.0)
end
rect rgb(232, 234, 246)
Note over Svc,Neo4j: 3. Neo4j 层面：相似 Issue（前缀匹配）
Svc->>Neo4j: MATCH (i:Issue) WHERE i.name STARTS WITH $prefix AND i.name <> $exact_name
Neo4j-->>Svc: similar_issues[]
Svc->>Svc: 计算 similar_issue 相似度
end
Svc->>Svc: 按相似度降序排列
Svc-->>API: duplicates[]
API-->>ADM: {code:0, data:{has_duplicates, duplicates}}
```
#### 前端交互设计
| 交互 | 说明 |
|------|------|
| 触发 | 详情弹窗中点击"检查重复"按钮 |
| 结果展示 | 弹窗显示重复项表格 |
| 无重复 | 绿色文字 "✅ 未发现重复，可安全采纳" |
| 有重复 | 橙色 Alert 警告 + 重复项表格 |
| 表格列 | 名称 / 匹配类型（同名Issue/相似Issue/标题相似）/ 相似度百分比 / 操作（合并） |
| 合并操作 | 点击"合并"调用 merge API |
#### 部署状态
**生产在线** — 后端 `find_duplicates` 方法 + API 路由 + 前端重复检查弹窗均已部署。
---
### 3.6 代答排除
#### 功能描述
坐席在分诊卡片中排除某些选项，被排除的选项灰显且不可点击，引导员工选择更合适的路径。
**当前状态**：仅前端组件方法（`setExcludedOptions`），未接入后端。
#### 数据模型
```mermaid
classDiagram
class TriageOption {
+String label
+Boolean selected
+Boolean excluded
+Boolean recommended
}
class ExclusionRequest {
+String conversation_id
+List~String~ excluded_labels
+String reason
}
```
#### 已实现部分
**前端方法**（`TriageCard.vue`）：
```typescript
// 暴露方法供父组件调用
defineExpose({
/** 设置坐席排除项 */
setExcludedOptions(labels: string[]) {
currentOptions.value.forEach(o => {
if (labels.includes(o.label)) {
o.excluded = true
o.selected = false
}
})
},
/** 设置坐席推荐项 */
setRecommendedOption(label: string) {
currentOptions.value.forEach(o => {
o.recommended = o.label === label
})
},
})
```
**排除样式**：
- 边框：`#ebedf0`（灰）
- 背景：`#f5f5f5`（浅灰）
- 透明度：0.5
- 光标：`not-allowed`
- 文字：删除线
#### API 接口设计（前瞻 — 未实现）
| 方法 | 路径 | 请求 | 响应 | 说明 |
|------|------|------|------|------|
| POST | `/api/agent/triage/exclude` | `{conversation_id, excluded_labels: string[]}` | `{code:0, data:{excluded: true}}` | 坐席排除分诊选项 |
| POST | `/api/agent/triage/recommend` | `{conversation_id, recommended_label: string}` | `{code:0, data:{recommended: true}}` | 坐席推荐分诊选项 |
#### 前瞻设计方案
1. **后端新增**：在 conversations API 或新建 triage API 中添加排除/推荐端点
2. **WebSocket 推送**：坐席排除选项后，通过 WS 实时推送到 H5 员工端
3. **Dify Prompt 增强**：将排除的选项传入 Dify，影响后续步骤生成
4. **审计日志**：记录坐席排除/推荐操作
#### 部署状态
**未实现** — 前端 `TriageCard.vue` 中 `setExcludedOptions` / `setRecommendedOption` 方法已定义，但无后端 API 对接，无 WS 推送机制。
---
### 3.7 知识迭代管理
#### 功能描述
管理后台的知识迭代提案管理页面，支持提案列表（含筛选/分页）、审阅提案详情、图字段编辑（issue/action/relation/parent）、训练师手动录入入口（通道 B）、触发分析。
**当前状态**：生产在线。47KB 服务 + 21KB API + 完整前端页面。
#### 数据模型
```mermaid
classDiagram
class KnowledgeSuggestion {
+String id : UUID
+String suggestion_type : "new_faq"|"update"|"outdated"
+String status : "pending"|"queued"|"approved"|"rejected"|"applied"|"graph_synced"|"expired"
+String title
+String content
+String category : "硬件"|"软件"|"网络"|"安全"|"账号"|"其他"
+List~String~ tags : JSON
+String source_type : "annotation"|"conversation"|"ai_uncertain"|"manual"|"document_ragflow"|"merge"
+List~String~ source_data : JSON
+String reason
+Float confidence
+String audience : "employee_quick_reply"|"engineer_workguide"
+String issue
+String action
+String relation_type : "LEADS_TO"|"RELATES_TO"|"CAN_JUMP_TO"
+String parent_issue
+Dict graph_meta : JSON
+String graph_sync_status : "pending"|"synced"|"failed"
+Boolean source_failed
+DateTime queued_at
+DateTime applied_at
+String reviewer_id
+DateTime reviewed_at
+String reject_reason
+DateTime created_at
+DateTime updated_at
}
class KnowledgeBase {
+String id : UUID
+String category
+String title
+String content
+List~String~ tags : JSON
+Integer view_count
+Integer use_count
+String graph_sync_status
+String graph_node_uuid
+DateTime created_at
+DateTime updated_at
}
class KnowledgeIterationService {
+Float confidence_gate_threshold
+generate_knowledge_suggestion(db, source_type, source_data, reason) KnowledgeSuggestion
+analyze_and_generate_suggestions(db, days) Dict
+_analyze_annotation_data(db, days) Dict
+_analyze_conversation_data(db, days) Dict
+_generate_update_suggestion(db, source_type, source_data, reason) KnowledgeSuggestion
+_generate_new_faq_suggestion(db, source_type, source_data, reason) KnowledgeSuggestion
+_build_context_from_source(db, source_type, source_data) List
+_auto_tag_audience(db, source_type, source_data) AudienceEnum
+_apply_confidence_gate(confidence) Boolean
+_check_existing_suggestion(db, source_id) Boolean
+approve_suggestion(db, id, reviewer_id, neo4j_client) KnowledgeSuggestion
+reject_suggestion(db, id, reviewer_id, reason) KnowledgeSuggestion
+rewrite_suggestion(db, id, reviewer_id, data) KnowledgeSuggestion
+queue_suggestion(db, id) KnowledgeSuggestion
+dequeue_approve(db, id, reviewer_id, neo4j_client) KnowledgeSuggestion
+sync_to_neo4j(neo4j_client, suggestion) Boolean
+get_suggestion_stats(db) Dict
+get_queue_stats(db) Dict
}
KnowledgeIterationService --> KnowledgeSuggestion : manages
KnowledgeIterationService --> KnowledgeBase : creates
```
#### ER 图
```mermaid
erDiagram
knowledge_suggestions ||--o| knowledge_base : "approved → creates KB"
knowledge_suggestions {
string id PK
string suggestion_type
string status
string title
text content
string category
json tags
string source_type
json source_data
float confidence
string audience
string issue
string action
string relation_type
string parent_issue
json graph_meta
string graph_sync_status
boolean source_failed
datetime queued_at
datetime applied_at
string reviewer_id
datetime reviewed_at
text reject_reason
text reason
datetime created_at
datetime updated_at
}
knowledge_base {
string id PK
string category
string title
text content
json tags
integer view_count
integer use_count
string graph_sync_status
string graph_node_uuid
datetime created_at
datetime updated_at
}
```
#### 数据库索引
| 索引名 | 字段 | 用途 |
|--------|------|------|
| idx_suggestion_status | status | 按状态筛选 |
| idx_suggestion_type | suggestion_type | 按类型筛选 |
| idx_suggestion_created | created_at | 按时间排序 |
| idx_suggestion_audience | audience | 按受众筛选 |
| idx_suggestion_confidence | confidence | 按置信度范围筛选 |
| idx_suggestion_graph_sync | graph_sync_status | 按图同步状态筛选 |
#### API 接口设计
| 方法 | 路径 | 请求参数 | 响应 | 说明 |
|------|------|---------|------|------|
| POST | `/api/admin/knowledge-iteration/analyze` | `?days=7` | `{code:0, data:{annotations_analyzed, conversations_analyzed, suggestions_generated}}` | 触发分析并生成建议 |
| GET | `/api/admin/knowledge-iteration/suggestions` | `?status=&suggestion_type=&audience=&confidence_min=&confidence_max=&page=&page_size=` | `{code:0, data:{total, items[]}}` | 获取建议列表 |
| GET | `/api/admin/knowledge-iteration/suggestions/{id}` | — | `{code:0, data: KnowledgeSuggestionResponse}` | 获取建议详情 |
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/approve` | `{}` | `{code:0, data: KnowledgeSuggestionResponse}` | 审核通过 |
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/reject` | `{reject_reason}` | `{code:0, data: KnowledgeSuggestionResponse}` | 审核拒绝 |
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/rewrite` | `{title?, content?, ...}` | `{code:0, data: KnowledgeSuggestionResponse}` | 改写提案 |
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/queue` | — | `{code:0, data: KnowledgeSuggestionResponse}` | 放入独立队列 |
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/dequeue-approve` | — | `{code:0, data: KnowledgeSuggestionResponse}` | 队列中审批 |
| GET | `/api/admin/knowledge-iteration/stats` | — | `{code:0, data: KnowledgeSuggestionStatsResponse}` | 获取统计 |
| GET | `/api/admin/knowledge-iteration/graph` | `?limit=100&issue_name=` | `{code:0, data:{nodes:[], links:[]}}` | 获取知识图谱数据 |
| GET | `/api/admin/knowledge-iteration/suggestions/{id}/duplicates` | — | `{code:0, data:{suggestion_id, has_duplicates, duplicates[]}}` | 检查重复 |
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/merge` | `{duplicate_id}` | `{code:0, data: KnowledgeSuggestionResponse}` | 合并重复建议 |
#### 分析与生成流程
```mermaid
sequenceDiagram
participant ADM as 管理后台
participant API as FastAPI
participant Svc as KnowledgeIterationService
participant Wingman as WingmanService
participant Dify as Dify AI
participant DB as PostgreSQL
ADM->>API: POST /analyze?days=7
API->>Svc: analyze_and_generate_suggestions(db, days=7)
rect rgb(255, 245, 230)
Note over Svc,DB: 1. 分析标注数据（useless 标注 ≥3 次）
Svc->>DB: SELECT * FROM conversation_annotations WHERE feedback='useless' AND created_at >= since
DB-->>Svc: annotations[]
Svc->>Svc: 按 message_id 分组统计高频错误
loop 每个高频错误 (count ≥ 3)
Svc->>Svc: _generate_update_suggestion()
Svc->>Wingman: generate_knowledge_suggestion(context_messages)
Wingman->>Dify: 调用 Dify API
Dify-->>Wingman: {title, content, category, tags, confidence, issue, action, ...}
Wingman-->>Svc: ai_result
Svc->>Svc: 置信门控: confidence < 0.7 → source_failed=True
Svc->>Svc: audience 自动标注
Svc->>DB: INSERT knowledge_suggestion
end
end
rect rgb(230, 245, 255)
Note over Svc,DB: 2. 分析会话数据（waiting_agent/agentServing）
Svc->>DB: SELECT * FROM conversations WHERE status IN ('waiting_agent','agentServing') AND created_at >= since
DB-->>Svc: conversations[]
Svc->>Svc: 采样 min(20, len)
loop 每个采样会话
Svc->>Svc: 检查是否已有 pending 建议（避免重复）
Svc->>Svc: _generate_new_faq_suggestion()
Svc->>Wingman: generate_knowledge_suggestion(context_messages)
Wingman->>Dify: 调用 Dify API
Dify-->>Wingman: ai_result
Wingman-->>Svc: ai_result
Svc->>Svc: 置信门控 + audience 标注
Svc->>DB: INSERT knowledge_suggestion
end
end
Svc-->>API: {annotations_analyzed, conversations_analyzed, suggestions_generated}
API-->>ADM: {code:0, data: result}
```
#### audience 自动标注规则（D8）
| source_type | 判定逻辑 | audience |
|-------------|---------|----------|
| manual | 直接判定 | engineer_workguide |
| document_ragflow | 直接判定 | engineer_workguide |
| annotation | 查 Conversation → 默认 | employee_quick_reply |
| conversation | 查 Conversation → 默认 | employee_quick_reply |
| ai_uncertain | 查 Conversation → 默认 | employee_quick_reply |
| 其他/未知 | 保守默认 | employee_quick_reply |
#### 置信门控逻辑（D3）
```python
# 置信门控：confidence < 0.7 → source_failed=True
if not source_failed and confidence < self.confidence_gate_threshold:
source_failed = True
logger.info(f"置信度 {confidence} 低于门控阈值 {self.confidence_gate_threshold}，标记 source_failed")
```
**门控效果**：
- `source_failed=True` 的建议标题为 `[生成失败] 新FAQ建议` 或 `[生成失败] 优化建议`
- 前端卡片样式变红（`approval-inline-card--failed`）
- 不影响审批流程，训练师仍可手动改写后采纳
#### 前端交互设计
**页面文件**：`frontend-admin/src/views/KnowledgeIteration.vue`
| 页面区域 | 功能 |
|---------|------|
| 页面标题 | "📚 知识迭代管理" |
| 视图切换 | 列表 / 图谱（el-button-group） |
| 操作按钮 | 手动录入（通道 B）/ 触发分析 |
| 统计概要 | 待审核 / 队列中 / 已通过 / 已应用 / 已同步 |
| 筛选栏 | 状态 / 受众 / 置信度下限 / 置信度上限 |
| 提案表格 | 标题 / 类型 / 状态 / 置信度 / 受众 / 来源 / 创建时间 / 操作 |
| 操作按钮 | 采纳 / 驳回 / 详情 |
| 分页 | el-pagination |
| 详情弹窗 | 标题/内容/分类/受众编辑 + 图字段编辑（Issue/Action/关系类型/父Issue） |
| 重复检查 | 检查重复按钮 → 重复结果弹窗 |
| 手动录入 | 标题/内容/分类/受众/图字段 → 提交（confidence=1.0, source_type=manual） |
#### 部署状态
**生产在线** — 后端 12 条 API 路由已注册，47KB 服务文件完整实现，前端页面 980 行 Vue3 组件已部署。
---
### 3.8 图谱可视化
#### 功能描述
管理后台使用 ECharts 力导向图可视化 Neo4j 知识图谱，支持全图查询和按 Issue 名称的子图查询。
**当前状态**：Neo4j 运行中，ECharts 可视化已部署。
#### 数据模型
```mermaid
classDiagram
class IssueNode {
+String uuid
+String name
+String category
+DateTime created_at
+DateTime updated_at
+String source_suggestion_id
}
class ActionNode {
+String uuid
+String name
+String description
+DateTime created_at
+String source_suggestion_id
}
class RelationEdge {
+String from_uuid
+String to_uuid
+String type : "LEADS_TO"|"RELATES_TO"|"CAN_JUMP_TO"
+Integer order
+Float weight
}
class Neo4jClient {
+String uri
+String user
+String password
+String database
+AsyncDriver _driver
+initialize()
+close()
+health_check() Boolean
+execute_write_query(cypher, params)
+execute_read_query(cypher, params)
+merge_issue(name, category, props) IssueNode
+merge_action(name, props) ActionNode
+find_issue_by_name(name) IssueNode
+create_relation(from_uuid, to_uuid, rel) Boolean
+query_full_graph(limit) Dict
+query_issue_subgraph(issue_name, depth) Dict
}
Neo4jClient --> IssueNode : manages
Neo4jClient --> ActionNode : manages
Neo4jClient --> RelationEdge : manages
IssueNode --> RelationEdge : from
ActionNode --> RelationEdge : to
```
#### Neo4j 图 Schema
**约束**：
```cypher
CREATE CONSTRAINT issue_uuid IF NOT EXISTS FOR (i:Issue) REQUIRE i.uuid IS UNIQUE
CREATE CONSTRAINT action_uuid IF NOT EXISTS FOR (a:Action) REQUIRE a.uuid IS UNIQUE
```
**索引**：
```cypher
CREATE INDEX issue_category IF NOT EXISTS FOR (i:Issue) ON (i.category)
CREATE INDEX issue_name IF NOT EXISTS FOR (i:Issue) ON (i.name)
CREATE INDEX action_name IF NOT EXISTS FOR (a:Action) ON (a.name)
```
#### API 接口设计
| 方法 | 路径 | 请求参数 | 响应 | 说明 |
|------|------|---------|------|------|
| GET | `/api/admin/knowledge-iteration/graph` | `?limit=100&issue_name=` | `{code:0, data:{nodes:[], links:[]}}` | 获取知识图谱数据 |
**响应数据格式**（ECharts 力导向图兼容）：
```json
{
"code": 0,
"data": {
"nodes": [
{"id": "uuid", "name": "VPN问题", "category": "网络", "label": "VPN问题", "type": "issue"},
{"id": "uuid", "name": "个人VPN开通", "category": "", "label": "个人VPN开通", "type": "action"}
],
"links": [
{"source": "issue_uuid", "target": "action_uuid", "type": "LEADS_TO", "weight": 1.0}
]
}
}
```
#### 核心流程
```mermaid
sequenceDiagram
participant ADM as 管理后台
participant API as FastAPI
participant Client as Neo4jClient
participant Neo4j as Neo4j
ADM->>API: GET /graph?limit=200
API->>Client: get_neo4j_client()
alt Neo4j 不可用
Client-->>API: None
API-->>ADM: {code:0, data:{nodes:[], links:[]}, message:"Neo4j 不可用"}
end
alt 全图查询（无 issue_name）
Client->>Neo4j: MATCH (i:Issue) RETURN ... LIMIT $limit
Neo4j-->>Client: issue_nodes[]
Client->>Neo4j: MATCH (a:Action) RETURN ... LIMIT $limit
Neo4j-->>Client: action_nodes[]
Client->>Neo4j: MATCH (n)-[r]->(m) WHERE ... LIMIT $limit*3
Neo4j-->>Client: relations[]
else 子图查询（有 issue_name）
Client->>Neo4j: MATCH path = (center:Issue {name: $name})-[*0..1]-(neighbor) ...
Neo4j-->>Client: subgraph_nodes[]
Client->>Neo4j: MATCH (center:Issue {name: $name})-[r*1..1]-(neighbor) ...
Neo4j-->>Client: subgraph_links[]
end
Client-->>API: {nodes, links}
API-->>ADM: {code:0, data: graph_data}
```
#### 前端交互设计
| 配置项 | 值 | 说明 |
|--------|-----|------|
| 图表类型 | `graph` (force layout) | ECharts 力导向图 |
| Issue 节点 | 绿色 `#67c23a`, symbolSize=28 | 问题节点 |
| Action 节点 | 橙色 `#e6a23c`, symbolSize=22 | 动作节点 |
| 连线颜色 | `#c0c4cc`, curveness=0.3 | 曲线连线 |
| 连线宽度 | `max(0.5, weight * 1.5)` | 按 weight 粗细 |
| 排斥力 | repulsion=300 | 力导向参数 |
| 重力 | gravity=0.1 | 力导向参数 |
| 边长度 | [100, 250] | 边长度范围 |
| 缩放 | roam=true | 支持鼠标缩放平移 |
| 高亮 | focus='adjacency' | 悬停高亮相邻节点 |
| 筛选 | 按 Issue 名称筛选子图 | 留空查全图 |
| 节点/关系计数 | 实时显示 | "节点: X | 关系: Y" |
| 响应式 | ResizeObserver | 自动 resize |
#### Neo4j 连接配置
| 配置项 | 默认值 | 环境变量 |
|--------|--------|---------|
| neo4j_uri | `bolt://localhost:7687` | `NEO4J_URI` |
| neo4j_user | `neo4j` | `NEO4J_USER` |
| neo4j_password | （无默认值） | `NEO4J_PASSWORD` |
| neo4j_database | `neo4j` | `NEO4J_DATABASE` |
| neo4j_max_connection_lifetime | 3600（秒） | — |
| neo4j_max_connection_pool_size | 50 | — |
| neo4j_connection_acquisition_timeout | 30（秒） | — |
#### 部署状态
**生产在线** — Neo4j 容器 `wecom_it_neo4j` 运行中，Neo4j 6.2.0 驱动已安装，API 路由已注册，ECharts 可视化已部署。
---
### 3.9 合并去重
#### 功能描述
将重复的知识建议合并到主建议中，标签和元数据合并，重复建议标记为 rejected（合并归入）。
**当前状态**：生产在线。
#### 数据模型
```mermaid
classDiagram
class MergeRequest {
+String primary_id
+String duplicate_id
+String reviewer_id
}
class MergeResult {
+KnowledgeSuggestion primary
+KnowledgeSuggestion duplicate
}
class KnowledgeIterationService {
+merge_suggestions(db, primary_id, duplicate_id, reviewer_id) KnowledgeSuggestion
}
MergeRequest --> KnowledgeIterationService : input
KnowledgeIterationService --> MergeResult : output
```
#### API 接口设计
| 方法 | 路径 | 请求体 | 响应 | 说明 |
|------|------|--------|------|------|
| POST | `/api/admin/knowledge-iteration/suggestions/{id}/merge` | `{duplicate_id: string}` | `{code:0, data: KnowledgeSuggestionResponse}` | 合并重复建议 |
#### 核心流程
```mermaid
sequenceDiagram
participant ADM as 管理后台
participant API as FastAPI
participant Svc as KnowledgeIterationService
participant DB as PostgreSQL
ADM->>API: POST /suggestions/{primary_id}/merge {duplicate_id}
API->>Svc: merge_suggestions(db, primary_id, duplicate_id, reviewer_id)
Svc->>DB: SELECT * FROM knowledge_suggestions WHERE id = primary_id
DB-->>Svc: primary (主建议)
alt 主建议不存在
Svc-->>API: None
API-->>ADM: {code:404, message:"主建议不存在"}
end
Svc->>DB: SELECT * FROM knowledge_suggestions WHERE id = duplicate_id
DB-->>Svc: duplicate (重复建议)
alt 重复建议存在
Svc->>Svc: 合并标签: merged_tags = set(primary.tags + duplicate.tags)
Svc->>Svc: 合并 graph_meta: primary.graph_meta.update(duplicate.graph_meta)
Svc->>DB: UPDATE duplicate SET status='rejected', reject_reason='已合并至建议 {primary_id}（去重）', reviewer_id, reviewed_at
end
Svc->>DB: COMMIT
Svc->>DB: REFRESH primary
Svc-->>API: primary (合并后)
API-->>ADM: {code:0, message:"建议合并完成，重复建议已标记为已驳回（合并归入）", data: primary}
```
#### 合并规则
| 字段 | 合并策略 |
|------|---------|
| tags | 并集去重：`set(primary.tags + duplicate.tags)` |
| graph_meta | 深度合并：`primary.graph_meta.update(duplicate.graph_meta)` |
| status (duplicate) | → `rejected` |
| reject_reason (duplicate) | → `已合并至建议 {primary_id}（去重）` |
| reviewer_id (duplicate) | → 当前审核人 |
| reviewed_at (duplicate) | → 当前时间 |
| primary 其他字段 | 保持不变 |
#### 前端交互设计
| 交互 | 说明 |
|------|------|
| 触发入口 | 重复检测结果弹窗中每行的"合并"按钮 |
| 请求参数 | `suggestion_id`（主建议，URL 路径参数）+ `duplicate_id`（重复建议，请求体） |
| 成功反馈 | 关闭重复弹窗 + 刷新列表 + 刷新统计 |
#### 部署状态
**生产在线** — 后端 `merge_suggestions` 方法 + API 路由 + 前端合并操作均已部署。
---
### 3.10 会话关闭→建议→审核→写图
#### 功能描述
全链路闭环：坐席结单 → 异步触发 AI 生成知识建议 → 训练师审核 → KB 落库 → Neo4j 写图。
**当前状态**：生产在线。全链路打通。
#### 全链路数据流
```mermaid
flowchart LR
A[坐席结单] --> B[异步触发\n知识建议生成]
B --> C{Dify 可用?}
C -->|是| D[调用 Wingman AI\n生成结构化建议]
C -->|否| E[source_failed=True\n标题=生成失败]
D --> F{confidence ≥ 0.7?}
F -->|是| G[创建 KnowledgeSuggestion\nstatus=pending]
F -->|否| H[source_failed=True\n标记低置信]
E --> G
H --> G
G --> I{训练师审核}
I -->|采纳| J[status=approved]
I -->|驳回| K[status=rejected\n终态]
I -->|改写| L[重置 status=pending\n重新审核]
I -->|入队| M[status=queued\n独立队列]
M --> N[队列审批\n→ approved]
J --> O[创建 KnowledgeBase 条目\nstatus=applied]
N --> O
O --> P{Neo4j 写图}
P -->|成功| Q[status=graph_synced\ngraph_sync_status=synced\n回填 kb.graph_node_uuid]
P -->|失败| R[graph_sync_status=failed\n可重试]
Q --> S[终态：知识图谱更新]
R --> T[后续优化：\n重试队列]
style A fill:#e3f2fd
style Q fill:#e8f5e9
style S fill:#c8e6c9
style K fill:#ffebee
```
#### 详细时序图
```mermaid
sequenceDiagram
participant AG as 坐席端
participant API_Conv as 会话 API
participant Svc_KI as 知识迭代服务
participant Wingman as Wingman AI
participant Dify as Dify
participant DB as PostgreSQL
participant Neo4j as Neo4j
participant ADM as 管理后台
%% 阶段1：会话关闭 → 异步生成建议
rect rgb(227, 242, 253)
Note over AG,DB: 阶段1：会话关闭 → 异步生成建议
AG->>API_Conv: POST /api/conversations/{id}/resolve (结单)
API_Conv->>DB: 会话状态 → resolved/closed
API_Conv-->>AG: 结单成功（不阻塞）
API_Conv->>API_Conv: asyncio.ensure_future(_trigger_knowledge_suggestion())
Note over API_Conv: 独立 db session 后台任务
API_Conv->>Svc_KI: generate_knowledge_suggestion(db, "conversation", [conv_id], reason)
Svc_KI->>Svc_KI: _check_existing_suggestion() — 避免重复
Svc_KI->>Svc_KI: _build_context_from_source() — 获取消息历史
Svc_KI->>Wingman: generate_knowledge_suggestion(context_messages)
Wingman->>Dify: 调用 Dify API
Dify-->>Wingman: {title, content, confidence, issue, action, ...}
Wingman-->>Svc_KI: ai_result
Svc_KI->>Svc_KI: 置信门控: confidence < 0.7 → source_failed
Svc_KI->>Svc_KI: audience 自动标注
Svc_KI->>DB: INSERT knowledge_suggestion (status=pending)
Svc_KI-->>API_Conv: suggestion
end
%% 阶段2：训练师审核
rect rgb(255, 243, 224)
Note over ADM,DB: 阶段2：训练师审核
ADM->>Svc_KI: GET /suggestions (查看待审核列表)
Svc_KI->>DB: SELECT * FROM knowledge_suggestions WHERE status='pending'
DB-->>ADM: suggestions[]
ADM->>ADM: 训练师查看详情，编辑图字段
alt 采纳
ADM->>Svc_KI: POST /suggestions/{id}/approve
Svc_KI->>Svc_KI: 校验 pending → approved (状态机)
Svc_KI->>DB: UPDATE status=approved, reviewer_id, reviewed_at
end
end
%% 阶段3：KB 落库 + Neo4j 写图
rect rgb(232, 245, 233)
Note over Svc_KI,Neo4j: 阶段3：KB 落库 + Neo4j 写图
Svc_KI->>DB: INSERT knowledge_base (title, content, category, tags)
Svc_KI->>DB: UPDATE suggestion status=applied, applied_at
Svc_KI->>Svc_KI: sync_to_neo4j(neo4j_client, suggestion)
rect rgb(232, 234, 246)
Note over Svc_KI,Neo4j: Neo4j 写图步骤
Svc_KI->>Neo4j: merge_issue(issue, category, props) — MERGE 幂等
Neo4j-->>Svc_KI: IssueNode (uuid)
opt 有父 Issue
Svc_KI->>Neo4j: merge_issue(parent_issue, ...)
Neo4j-->>Svc_KI: parent_node
Svc_KI->>Neo4j: create_relation(parent → issue, type, weight)
end
opt 有 Action
Svc_KI->>Neo4j: merge_action(action, props)
Neo4j-->>Svc_KI: ActionNode (uuid)
Svc_KI->>Neo4j: create_relation(issue → action, type, weight=confidence)
end
end
alt 写图成功
Svc_KI->>DB: UPDATE suggestion status=graph_synced, graph_sync_status=synced
Svc_KI->>DB: UPDATE kb graph_sync_status=synced, graph_node_uuid=issue_node.uuid
else 写图失败
Svc_KI->>DB: UPDATE suggestion graph_sync_status=failed
Svc_KI->>DB: UPDATE kb graph_sync_status=failed
end
Svc_KI->>DB: COMMIT
end
ADM->>Svc_KI: 响应 {code:0, data: suggestion (graph_synced)}
```
#### 会话关闭触发点
**文件**：`backend/app/api/conversations.py`，`resolve_conversation` 函数
**关键代码**：
```python
# 会话结单后异步触发知识建议生成
async def _trigger_knowledge_suggestion():
"""异步生成知识建议的后台任务（独立 db session）。"""
from app.database import _get_session_factory
from app.services.knowledge_iteration_service import KnowledgeIterationService
factory = _get_session_factory()
async with factory() as bg_db:
knowledge_service = KnowledgeIterationService()
suggestion = await knowledge_service.generate_knowledge_suggestion(
db=bg_db,
source_type="conversation",
source_data=[str(conversation_id)],
reason=f"会话'{conversation_id}'已结单，自动生成知识迭代建议",
)
if suggestion:
bg_db.add(suggestion)
await bg_db.commit()
# 创建后台任务（不阻塞结单响应）
_asyncio.ensure_future(_trigger_knowledge_suggestion())
```
**设计要点**：
1. **不阻塞结单**：使用 `asyncio.ensure_future` 异步执行，结单响应立即返回
2. **独立 db session**：后台任务使用独立的 `_get_session_factory()` 创建新 session，避免与主请求 session 冲突
3. **失败不影响主流程**：知识建议生成失败时仅记录日志，不影响结单
4. **避免重复**：`_check_existing_suggestion` 检查是否已有 pending 建议
#### Neo4j 写图逻辑（sync_to_neo4j）
```mermaid
flowchart TD
A[approve_suggestion 触发] --> B{suggestion.issue 存在?}
B -->|否| C[return True\n无图字段不视为失败]
B -->|是| D[merge_issue\nMERGE Issue 节点]
D --> E{suggestion.parent_issue 存在?}
E -->|是| F[merge_issue\nMERGE 父 Issue 节点]
F --> G[create_relation\n父Issue → 当前Issue]
E -->|否| H{suggestion.action 存在?}
G --> H
H -->|是| I[merge_action\nMERGE Action 节点]
I --> J[create_relation\nIssue → Action\nweight=confidence]
H -->|否| K[return True]
J --> K
K --> L[写图成功]
style L fill:#c8e6c9
```
**MERGE 幂等写入**：
- Issue 节点按 `name` MERGE（同名不重复创建）
- Action 节点按 `name` MERGE
- 关系通过 `MATCH + CREATE` 创建
#### 部署状态
**生产在线** — 全链路已打通，从会话结单到 Neo4j 写图完整闭环。测试通过率 89/89。
---
## 4. 功能依赖关系图
```mermaid
graph TB
subgraph "H5 员工端功能"
F1[1.分诊交互]
F2[2.置信门控]
F6[6.代答排除]
end
subgraph "坐席端功能"
F3[3.内联审批卡片]
F4[4.拓扑预览]
end
subgraph "管理后台功能"
F5[5.重复检测]
F7[7.知识迭代管理]
F8[8.图谱可视化]
F9[9.合并去重]
end
subgraph "全链路功能"
F10[10.会话关闭→建议→审核→写图]
end
subgraph "基础设施"
NEO4J[Neo4j 图数据库]
DIFY[Dify AI 平台]
PG[(PostgreSQL)]
end
%% 依赖关系
F2 -->|confidence < 0.7 触发| F10
F1 -->|分诊上下文转人工| F10
F6 -->|排除选项影响| F1
F10 -->|生成 KnowledgeSuggestion| F3
F10 -->|生成 KnowledgeSuggestion| F7
F3 -->|展示拓扑| F4
F3 -->|检查重复| F5
F5 -->|发现重复| F9
F7 -->|管理审核| F3
F7 -->|查看图谱| F8
F7 -->|检查重复| F5
F7 -->|合并去重| F9
%% 基础设施依赖
F2 --> DIFY
F10 --> DIFY
F10 --> PG
F3 --> PG
F5 --> NEO4J
F5 --> PG
F7 --> PG
F8 --> NEO4J
F9 --> PG
F10 --> NEO4J
F4 --> NEO4J
%% 样式
style F1 fill:#fff3e0,stroke:#ff9800,stroke-dasharray: 5 5
style F4 fill:#fff3e0,stroke:#ff9800,stroke-dasharray: 5 5
style F6 fill:#fff3e0,stroke:#ff9800,stroke-dasharray: 5 5
style F2 fill:#e8f5e9,stroke:#4caf50
style F3 fill:#e3f2fd,stroke:#2196f3
style F5 fill:#e8f5e9,stroke:#4caf50
style F7 fill:#e8f5e9,stroke:#4caf50
style F8 fill:#e8f5e9,stroke:#4caf50
style F9 fill:#e8f5e9,stroke:#4caf50
style F10 fill:#e8f5e9,stroke:#4caf50
style NEO4J fill:#e8eaf6,stroke:#3f51b5
style DIFY fill:#fce4ec,stroke:#e91e63
style PG fill:#e8eaf6,stroke:#3f51b5
```
**图例**：
- 🟢 绿色边框：生产在线
- 🟠 橙色虚线边框：未实现/仅前端组件
- 🔵 蓝色：基础设施
**核心依赖链**：
```
置信门控 → 会话关闭→建议→审核→写图 → 内联审批卡片 → 重复检测 → 合并去重
↓
拓扑预览
```
---
## 5. 全链路数据流图
### 5.1 通道 A：会话自动生成（全链路闭环）
```mermaid
flowchart TD
Start([员工提问]) --> AI_Reply[AI 回复]
AI_Reply --> ConfCheck{confidence ≥ 0.7?}
ConfCheck -->|是| Normal[正常回复]
ConfCheck -->|否| GateBanner[置信门控横幅<br/>展示转人工入口]
GateBanner --> Transfer{员工选择}
Transfer -->|转人工| WaitingAgent[会话 → waiting_agent]
Transfer -->|继续 AI| Normal
Normal --> Resolved{问题解决?}
Resolved -->|是| Close1[员工关闭]
Resolved -->|否| WaitingAgent
WaitingAgent --> AgentServe[坐席接管]
AgentServe --> Close2[坐席结单]
Close1 --> AsyncGen[异步触发<br/>知识建议生成]
Close2 --> AsyncGen
AsyncGen --> BuildCtx[构建对话上下文<br/>获取消息历史]
BuildCtx --> CallAI[调用 Dify Wingman<br/>生成结构化建议]
CallAI --> ConfGate{confidence ≥ 0.7?}
ConfGate -->|是| CreateSuggestion[创建 KnowledgeSuggestion<br/>status=pending]
ConfGate -->|否| MarkFailed[source_failed=True<br/>标题=生成失败]
MarkFailed --> CreateSuggestion
CreateSuggestion --> NotifyAgent[通知坐席<br/>内联审批卡片]
CreateSuggestion --> NotifyAdmin[通知训练师<br/>管理后台列表]
NotifyAgent --> Review{审核决策}
NotifyAdmin --> Review
Review -->|采纳| Approve[status=approved]
Review -->|驳回| Reject[status=rejected 终态]
Review -->|改写| Rewrite[修改字段<br/>重置 pending]
Review -->|入队| Queue[status=queued<br/>独立队列]
Queue --> QueueReview[队列审批]
QueueReview -->|通过| Approve
QueueReview -->|驳回| Reject
Rewrite --> Review
Approve --> CreateKB[创建 KnowledgeBase 条目<br/>status=applied]
CreateKB --> WriteNeo4j[Neo4j 写图<br/>merge_issue + merge_action]
WriteNeo4j --> SyncCheck{写图成功?}
SyncCheck -->|是| GraphSynced[status=graph_synced<br/>回填 kb.graph_node_uuid]
SyncCheck -->|否| SyncFailed[graph_sync_status=failed<br/>待重试]
GraphSynced --> Done([知识图谱更新完成])
style GateBanner fill:#fff3e0
style AsyncGen fill:#e3f2fd
style CreateSuggestion fill:#e8f5e9
GraphSynced fill:#c8e6c9
style Reject fill:#ffebee
style Done fill:#c8e6c9
```
### 5.2 通道 B：训练师手动录入
```mermaid
flowchart LR
A[训练师点击<br/>手动录入] --> B[填写表单<br/>标题/内容/分类/受众/图字段]
B --> C[提交<br/>source_type=manual<br/>confidence=1.0]
C --> D[创建 KnowledgeSuggestion<br/>status=pending]
D --> E[审核流程<br/>同通道 A]
```
### 5.3 通道 C：RAGFlow 文档 ETL（预留未实现）
```mermaid
flowchart LR
A[RAGFlow 文档上传] --> B[ETL 处理<br/>文档→FAQ]
B --> C[source_type=document_ragflow<br/>audience=engineer_workguide]
C --> D[创建 KnowledgeSuggestion<br/>status=pending]
D --> E[审核流程<br/>同通道 A]
```
### 5.4 三通道汇总
```mermaid
graph TB
subgraph "通道 A：会话自动生成"
A1[会话关闭] --> A2[Dify AI 生成] --> A3[KnowledgeSuggestion]
end
subgraph "通道 B：手动录入"
B1[训练师录入] --> B2[confidence=1.0] --> B3[KnowledgeSuggestion]
end
subgraph "通道 C：RAGFlow（预留）"
C1[文档 ETL] --> C2[自动提取] --> C3[KnowledgeSuggestion]
end
A3 --> S[统一审核队列<br/>status=pending]
B3 --> S
C3 --> S
S --> R{审核}
R -->|采纳| AP[approved → applied → graph_synced]
R -->|驳回| RJ[rejected]
R -->|改写| RW[重置 pending]
R -->|入队| Q[queued → 队列审批]
style S fill:#e3f2fd
style AP fill:#e8f5e9
```
---
## 6. 未实现功能设计
### 6.1 分诊交互 — 前瞻设计
#### 当前状态
前端组件 `TriageCard.vue` 已完成（530 行），包含完整的 UI 交互：步骤进度、选项列表、概率展示、专家模式、折叠/展开、跳过/确认。但后端 API 未实现，Dify 分诊 prompt 未配置。
#### 建议实现方案
**后端新增**：
1. **新增 API 文件**：`backend/app/api/triage.py`
- `POST /api/h5/triage/start` — 发起分诊
- `POST /api/h5/triage/step` — 提交步骤选择
- `POST /api/h5/triage/skip` — 跳过步骤
- `POST /api/h5/triage/transfer` — 转人工
2. **Dify Prompt 设计**：
- 输入：员工问题文本
- 输出：分步选择题数组 `[{question, options: [{label, probability}], total_steps}]`
- 复杂度自适应：简单问题 1-2 步，复杂问题 3-5 步
3. **数据模型**：
- 复用 `Conversation` 表，增加 `triage_steps` JSON 字段存储分诊过程
- 或新建 `triage_sessions` 表
4. **集成点**：
- H5 对话页面在 AI 回复前调用分诊 API
- 分诊完成后将收集的上下文传入 Dify 生成最终回复
#### 预估工作量
| 任务 | 工作量 |
|------|--------|
| 后端 API + 服务 | 2 人日 |
| Dify Prompt 调试 | 3 人日 |
| H5 前端对接 | 1 人日 |
| 测试 | 1 人日 |
| **合计** | **7 人日** |
### 6.2 拓扑预览 — 前瞻设计
#### 当前状态
前端 SVG 缩略图已实现（基于 suggestion 的 issue/parent_issue/action 字段静态渲染），后端 `query_issue_subgraph` 方法已实现但未通过 API 暴露。
#### 建议实现方案
1. **新增 API 端点**：
```python
@router.get("/suggestions/{suggestion_id}/topology")
@require_admin
async def get_suggestion_topology(suggestion_id: str, ...):
# 查询 suggestion 获取 issue 名称
# 调用 neo4j_client.query_issue_subgraph(issue_name, depth=1)
# 返回 {nodes, links}
```
2. **前端增强**：
- SVG 缩略图保留为快速预览
- 点击缩略图弹出 ECharts mini graph modal 展示完整子图
- 子图支持节点点击跳转到图谱可视化页面
3. **降级处理**：
- Neo4j 不可用时回退到当前 SVG 静态渲染
- suggestion 无 issue 字段时不展示拓扑
#### 预估工作量
| 任务 | 工作量 |
|------|--------|
| 后端 API 端点 | 0.5 人日 |
| 前端 ECharts modal | 1 人日 |
| 测试 | 0.5 人日 |
| **合计** | **2 人日** |
### 6.3 代答排除 — 前瞻设计
#### 当前状态
前端 `TriageCard.vue` 中 `setExcludedOptions` / `setRecommendedOption` 方法定义完成，但无后端 API 对接，无 WS 推送机制。
#### 建议实现方案
1. **后端新增**：
- `POST /api/agent/triage/exclude` — 坐席排除选项
- `POST /api/agent/triage/recommend` — 坐席推荐选项
2. **WebSocket 推送**：
- 坐席排除/推荐操作后，通过 WS 实时推送到 H5 员工端
- H5 端接收后调用 `TriageCard.setExcludedOptions()` / `setRecommendedOption()`
3. **Dify Prompt 增强**：
- 将排除的选项作为上下文传入 Dify，影响后续步骤生成
- 避免 AI 在后续步骤中再次推荐已排除的选项
4. **审计日志**：
- 记录坐席排除/推荐操作（操作人、时间、排除的选项、原因）
#### 预估工作量
| 任务 | 工作量 |
|------|--------|
| 后端 API + WS 推送 | 1.5 人日 |
| 坐席端前端对接 | 1 人日 |
| H5 前端对接 | 0.5 人日 |
| 测试 | 1 人日 |
| **合计** | **4 人日** |
---
## 7. 已知问题与后续优化方向
### 7.1 已知问题
| # | 问题 | 影响 | 严重程度 | 当前处理 |
|---|------|------|---------|---------|
| 1 | Neo4j 写图失败后无自动重试 | `graph_sync_status=failed` 的建议停留在 applied 状态，图数据不完整 | P1 | 人工触发重新审批 |
| 2 | `_analyze_conversation_data` 采样限制 20 条 | 分析超过 20 条会话时仅采样前 20 条，可能遗漏 | P2 | 可接受，后续调大采样 |
| 3 | audience 自动标注默认 employee_quick_reply | Conversation 模型无 session_type 字段，无法精确区分员工/工程师会话 | P2 | 保守默认，训练师可手动修改 |
| 4 | 相似度计算为简单前缀匹配 | 无法检测语义相似但文字不同的重复 Issue | P2 | 后续可引入向量相似度 |
| 5 | 会话关闭异步任务无重试机制 | Dify 不可用时建议生成失败，无自动重试 | P2 | source_failed 标记，训练师可手动改写 |
| 6 | 过期状态 expired 无定时任务 | 设计中有 expired 状态（72h 超时），但无定时任务自动触发 | P3 | 待实现定时任务 |
| 7 | `create_relation` 使用 CREATE 而非 MERGE | 重复审批同一建议可能创建重复关系边 | P2 | 后续改为 MERGE |
| 8 | 前端 `createSuggestion` 直接调用 POST /suggestions | API 路由中无 POST /suggestions 创建端点（仅列表 GET） | P1 | 需补充创建 API 或使用其他路径 |
### 7.2 后续优化方向
#### 短期（P0-P1）
1. **Neo4j 写图重试队列**
- 新增定时任务扫描 `graph_sync_status=failed` 的建议
- 自动重试写图，最多 3 次
- 超过重试次数通知管理员
2. **补充手动创建建议 API**
- 前端 `createSuggestion` 调用的 POST /suggestions 端点需补充
- 或确认是否通过其他路由处理
3. **关系边 MERGE 幂等**
- `create_relation` 改用 MERGE 替代 CREATE
- 避免重复审批产生重复关系
#### 中期（P2）
4. **向量相似度去重**
- 引入 embedding 模型计算 Issue 名称的语义相似度
- 替代当前的前缀匹配算法
- 提高重复检测准确率
5. **过期定时任务**
- 实现 72h 超时自动 expired 的定时任务
- 使用 APScheduler 或 Celery beat
6. **分诊交互后端实现**
- 实现分诊 API + Dify Prompt
- 打通 TriageCard 前后端
7. **拓扑预览 API 对接**
- 暴露 `query_issue_subgraph` 为 API
- 前端 ECharts mini graph 展示
#### 长期（P3）
8. **RAGFlow 通道 C 实现**
- 部署 RAGFlow 服务
- 实现文档 ETL → KnowledgeSuggestion 自动生成
- `ragflow_ingestion_enabled` 配置开关已预留
9. **知识图谱推理**
- 基于 Neo4j 图结构进行路径推荐
- 员工提问时推荐相关 Issue→Action 路径
10. **全链路监控看板**
- 建议生成→审核→写图各阶段耗时统计
- 转化漏斗：生成数 → 采纳数 → 写图成功数
- Dify 调用成功率监控
---
## 附录
### A. 数据库迁移
| 迁移版本 | 说明 |
|---------|------|
| 043_knowledge_iteration | 创建 knowledge_suggestions 表 + conversation_annotations 表 |
| 044_automation | 自动化相关表（后续迁移） |
### B. 测试覆盖
| 测试层级 | 测试数 | 通过率 | 报告 |
|---------|--------|--------|------|
| Tier0 基础测试 | 41 | 100% | `docs/06-测试质量/Tier0-测试报告-20260708.md` |
| Tier1 API 测试 | 34 | 100% | 同上 |
| CSV 验证 | 14 | 100% | 同上 |
| P2 可视化测试 | — | — | `docs/06-测试质量/P0串联+P2可视化-测试报告-20260708.md` |
| **合计** | **89** | **100%** | — |
### C. 关键文件索引
| 文件 | 行数 | 说明 |
|------|------|------|
| `backend/app/api/knowledge_iteration.py` | 568 | 12 条 API 路由 |
| `backend/app/api/approval_queue.py` | 208 | 3 条队列 API 路由 |
| `backend/app/services/knowledge_iteration_service.py` | 1197 | 核心服务 |
| `backend/app/services/neo4j_client.py` | 759 | Neo4j 异步客户端 |
| `backend/app/models/knowledge_suggestion.py` | 260 | 数据模型 |
| `backend/app/models/knowledge_base.py` | 143 | 数据模型 |
| `backend/app/models/neo4j_schema.py` | 115 | 图节点 Pydantic 模型 |
| `backend/app/schemas/enums.py` | 159 | 枚举 + 状态机 |
| `backend/app/schemas/knowledge_suggestion.py` | 208 | 请求/响应 Schema |
| `backend/app/config.py` | 469 | 配置项 |
| `backend/app/api/conversations.py` | ~400+ | 会话关闭触发点 |
| `frontend-admin/src/views/KnowledgeIteration.vue` | 982 | 管理后台页面 |
| `frontend-agent/src/components/chat/ApprovalInlineCard.vue` | 695 | 内联审批卡片 |
| `frontend-h5/src/components/TriageCard.vue` | 530 | 分诊卡片 |
| `frontend-h5/src/components/ConfidenceGateBanner.vue` | 332 | 置信门控横幅 |
| `frontend-h5/src/composables/useConfidenceGate.ts` | 181 | 置信门控逻辑 |
---
> **文档结束**
> 本文档基于代码分析生成，已部署功能为回溯文档，未实现功能为前瞻设计。
> 如有疑问请联系架构组。
Reference in New Issue Copy Permalink