1023 lines
32 KiB
Markdown
1023 lines
32 KiB
Markdown
|
# 技术方案 - H5 智能推荐重构
|
|||
|
|
|
|||
|
|
> **REQ 编号**: REQ-用户-006
|
|||
|
|
> **版本**: v1.0
|
|||
|
|
> **日期**: 2026-07-28
|
|||
|
|
> **作者**: 宋献 (Simon) + Duckula
|
|||
|
|
> **依赖 PRD**: `docs/01-产品文档/05-用户端H5/PRD-REQ-用户-006-智能推荐重构-v1.0-Frozen.md`（**§4.7 已冻结，必须遵守**）
|
|||
|
|
> **依赖代码**:
|
|||
|
|
> - `src/backend/app/services/asset_recommend_service.py`（现有 L1/L2/L3 实现）
|
|||
|
|
> - `src/backend/app/config/assets.yaml`（现有 L1 关键词 + L3 角色配置）
|
|||
|
|
> - `src/backend/app/tasks/h5_ai_task.py`（现有 _step_persist / _step_assets）
|
|||
|
|
> - `src/backend/app/services/ws_manager.py`（双 WS 通道：dynamic_recommend + asset_recommend）
|
|||
|
|
> - `src/frontend-h5/src/components/assistant/DynamicRecommend.vue`（前端右侧栏组件）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、现状分析
|
|||
|
|
|
|||
|
|
### 1.1 现有实现（4 条触发源混跑）
|
|||
|
|
|
|||
|
|
| 来源 | 代码位置 | WS 通道 | 触发时机 | 现状问题 |
|
|||
|
|
|------|---------|---------|---------|---------|
|
|||
|
|
| **A：Dify action** | `h5_ai_task.py::_step_persist` line 595 | `dynamic_recommend` WS | T0 同步 | v2.3 审批类只推左边 |
|
|||
|
|
| **B：L1 关键词** | `_push_asset_recommends` → `asset_service.match_keywords()` | `asset_recommend` WS | T1 异步 | `if keyword in message_lower` 太硬，无语义 |
|
|||
|
|
| **C：L2 画像** | `_push_asset_recommends` → `asset_service.match_profile_triggers()` | `asset_recommend` WS | T1 异步 | 画像 API 拿不到时全部 if 跳过 |
|
|||
|
|
| **D：L3 角色** | `_push_asset_recommends` → `asset_service.get_by_role()` | `asset_recommend` WS | T1 异步 | 英文 key vs 中文 position，永远不命中 |
|
|||
|
|
|
|||
|
|
### 1.2 关键问题（5 类，与 PRD §1 对齐）
|
|||
|
|
|
|||
|
|
1. L1 关键词匹配太硬 → 易误命中（"邮箱配置"也命中"邮箱"）
|
|||
|
|
2. L2 画像依赖外部 API → 拿不到时空 L2
|
|||
|
|
3. L3 角色推荐不工作 → 中文/英文 key 不匹配
|
|||
|
|
4. 双轨运行（A/B/C/D 各跑各的）→ 无去重、无排序
|
|||
|
|
5. v2.3 审批类不出现在右侧 → 进度无法跨会话回看
|
|||
|
|
|
|||
|
|
### 1.3 与 PRD §4.7 决策对照
|
|||
|
|
|
|||
|
|
PRD §4.7 已冻结 5 个决策，技术方案必须全部落地：
|
|||
|
|
- ① 冷启动 A → §7 客户端状态机（无则隐）
|
|||
|
|
- ② 多源合并 B → §6 合并算法
|
|||
|
|
- ③ 触发失败降级 B → §8 降级链路
|
|||
|
|
- ④ 话题切换检测 B → §9 检测算法
|
|||
|
|
- ⑤ 跨会话持久化 B → §10 localStorage 方案
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、目标与范围
|
|||
|
|
|
|||
|
|
### 2.1 改造目标
|
|||
|
|
|
|||
|
|
| 目标 | 衡量标准 |
|
|||
|
|
|------|---------|
|
|||
|
|
| 4 类触发源全部可观测 | 后端日志 / 前端埋点可追踪每条推荐的来源 ID |
|
|||
|
|
| 多源合并生效 | 同 recommend_id 不重复；右侧栏 ≤3 张 |
|
|||
|
|
| 冷启动符合"无则隐" | 进会话 5s 内右侧栏无任何卡片 |
|
|||
|
|
| 跨会话持久化生效 | L2/L3/T2 推荐在 localStorage 可见 |
|
|||
|
|
| 审批进度回流 | 来源 D（用户发起的审批）状态变化时回流右侧栏 |
|
|||
|
|
|
|||
|
|
### 2.2 改造范围
|
|||
|
|
|
|||
|
|
**In-scope**：
|
|||
|
|
- 后端 `asset_recommend_service.py` 重构（L1/L2/L3 三层 + 中文角色匹配）
|
|||
|
|
- 后端新增 `recommend_progress` 表 + 订阅 API（T2 事件触发）
|
|||
|
|
- 后端新增 WS type `recommend_update`（审批状态回流）
|
|||
|
|
- 前端 `DynamicRecommend.vue` 重构（FIFO + 4 类卡片 + 上限 3 张）
|
|||
|
|
- 前端 `RightPanel.vue` 适配（无标题 + 持久化展示）
|
|||
|
|
- 前端新增 `recommendStore.ts`（Pinia 状态机管理）
|
|||
|
|
|
|||
|
|
**Out-of-scope**：
|
|||
|
|
- 智能推荐算法升级（语义匹配/向量召回）→ v1.4+ 单独做
|
|||
|
|
- 坐席端 AI 辅助 → 不在本次范围
|
|||
|
|
- 多模态推荐 → PRD-REQ-AI-003 单独做
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、架构设计
|
|||
|
|
|
|||
|
|
### 3.1 整体架构图
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
graph TB
|
|||
|
|
subgraph "前端 H5"
|
|||
|
|
UI[RightPanel.vue<br/>右侧栏 UI]
|
|||
|
|
DR[DynamicRecommend.vue<br/>推荐卡片渲染]
|
|||
|
|
RS[recommendStore.ts<br/>Pinia 状态机]
|
|||
|
|
LS[(localStorage<br/>持久化)]
|
|||
|
|
end
|
|||
|
|
|
|||
|
|
subgraph "后端"
|
|||
|
|
WS[ws_manager.py<br/>WebSocket 管理]
|
|||
|
|
T1[h5_ai_task.py<br/>_step_persist T0]
|
|||
|
|
T2[h5_ai_task.py<br/>_step_assets T1]
|
|||
|
|
T3[recommend_event_listener.py<br/>T2 webhook/轮询]
|
|||
|
|
AS[asset_recommend_service.py<br/>4 类触发源核心]
|
|||
|
|
AR[assets.yaml<br/>L1+L3 配置]
|
|||
|
|
EP[employee_profile_service.py<br/>L2 画像]
|
|||
|
|
DB[(PostgreSQL<br/>recommend_progress)]
|
|||
|
|
end
|
|||
|
|
|
|||
|
|
subgraph "外部"
|
|||
|
|
DIFY[Dify 主推理<br/>itdesk_main]
|
|||
|
|
WECOM[企微审批<br/>webhook]
|
|||
|
|
HUORONG[火绒 API<br/>L2 画像源]
|
|||
|
|
end
|
|||
|
|
|
|||
|
|
DIFY -- "action" --> T1
|
|||
|
|
T1 -- "T0 WS" --> WS
|
|||
|
|
T1 -- "触发 _step_assets" --> T2
|
|||
|
|
EP -- "查画像" --> HUORONG
|
|||
|
|
T2 -- "调 service" --> AS
|
|||
|
|
AS -- "查 L1" --> AR
|
|||
|
|
AS -- "查 L2" --> EP
|
|||
|
|
AS -- "查 L3" --> AR
|
|||
|
|
T2 -- "T1 WS" --> WS
|
|||
|
|
WECOM -- "审批状态" --> T3
|
|||
|
|
T3 -- "写库" --> DB
|
|||
|
|
T3 -- "T2 WS" --> WS
|
|||
|
|
WS -- "broadcast" --> UI
|
|||
|
|
UI --> RS
|
|||
|
|
RS --> DR
|
|||
|
|
RS -- "读/写" --> LS
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 时序图：员工发起"VPN 申请"全链路
|
|||
|
|
|
|||
|
|
```mermaid
|
|||
|
|
sequenceDiagram
|
|||
|
|
participant E as 员工
|
|||
|
|
participant H5 as H5 前端
|
|||
|
|
participant BE as 后端
|
|||
|
|
participant D as Dify
|
|||
|
|
participant AS as Asset Service
|
|||
|
|
participant W as 企微审批
|
|||
|
|
participant LS as localStorage
|
|||
|
|
|
|||
|
|
E->>H5: 发送"我要申请 VPN"
|
|||
|
|
H5->>BE: WS 消息
|
|||
|
|
BE->>D: 调用主推理
|
|||
|
|
D-->>BE: {text, action.approval_type=vpn_access}
|
|||
|
|
Note over BE: T0 同步：action 非空且非审批类<br/>但 v2.3 后审批类只推左边
|
|||
|
|
BE->>H5: WS ai_reply (含文字 + 操作步骤气泡)
|
|||
|
|
BE->>BE: _step_persist 完成
|
|||
|
|
BE->>BE: 触发 _step_assets (T1 异步)
|
|||
|
|
BE->>AS: match_keywords("我要申请 VPN")
|
|||
|
|
AS-->>BE: [vpn 关键词命中]
|
|||
|
|
BE->>AS: match_profile_triggers(profile)
|
|||
|
|
AS-->>BE: [L2 画像检测]
|
|||
|
|
BE->>AS: get_by_role(profile.position)
|
|||
|
|
AS-->>BE: [L3 角色匹配]
|
|||
|
|
BE->>BE: §6 多源合并（去重+排序+上限3张）
|
|||
|
|
BE->>H5: WS asset_recommend
|
|||
|
|
H5->>LS: 持久化非对话级推荐
|
|||
|
|
H5-->>E: 右侧栏显示 L1 VPN 卡 + L2 提醒（如有）+ L3 资源（如有）
|
|||
|
|
|
|||
|
|
E->>H5: 点击"申请 VPN"
|
|||
|
|
H5->>W: 跳转企微审批表单
|
|||
|
|
W-->>H5: 审批状态变化
|
|||
|
|
W-->>BE: webhook 通知
|
|||
|
|
BE->>BE: _step_persist + recommend_progress 写库
|
|||
|
|
BE->>H5: WS recommend_update (type=progress)
|
|||
|
|
H5->>LS: 更新持久化条目
|
|||
|
|
H5-->>E: 右侧栏顶部插入审批进度卡
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.3 数据流图
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
[用户消息] → [Dify 主推理] → [action 字段]
|
|||
|
|
↓
|
|||
|
|
[_step_persist (T0 同步)]
|
|||
|
|
↓
|
|||
|
|
┌──────┴──────┐
|
|||
|
|
↓ ↓
|
|||
|
|
[ai_reply WS] [dynamic_recommend WS] ← 仅 action 非空且非审批
|
|||
|
|
↓ ↓
|
|||
|
|
[气泡渲染] [右侧栏渲染]
|
|||
|
|
↓
|
|||
|
|
[_step_assets (T1 异步)]
|
|||
|
|
↓
|
|||
|
|
[AssetRecommendService.process_dify_intent]
|
|||
|
|
↓
|
|||
|
|
┌──────┼──────┬──────┐
|
|||
|
|
↓ ↓ ↓ ↓
|
|||
|
|
L1 L2 L3 dedup
|
|||
|
|
↓ ↓ ↓ ↓
|
|||
|
|
[assets.yaml] [profile] [role] [排序+上限3]
|
|||
|
|
↓
|
|||
|
|
[asset_recommend WS (单个包)]
|
|||
|
|
↓
|
|||
|
|
[前端 recommendStore]
|
|||
|
|
↓
|
|||
|
|
[Pinia state + localStorage]
|
|||
|
|
↓
|
|||
|
|
[DynamicRecommend.vue FIFO 渲染]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、4 类触发源的技术实现
|
|||
|
|
|
|||
|
|
### 4.1 来源 A：Dify action（T0 同步）
|
|||
|
|
|
|||
|
|
**代码位置**：`h5_ai_task.py::_step_persist` line 592-650
|
|||
|
|
|
|||
|
|
**改动点**：保持 v2.3 现状（审批类只推左边），仅优化非审批类的来源标记
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
# v1.0 修改建议：在 recommend_data 中加 source: "dify_action"
|
|||
|
|
recommend_data = {
|
|||
|
|
...
|
|||
|
|
"source": "dify_action", # 新增：标识来源 A
|
|||
|
|
"trigger_timing": "T0", # 新增：标识触发时机
|
|||
|
|
"layer": "A", # 新增：与 L1/L2/L3 同维度
|
|||
|
|
...
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**前端处理**：`DynamicRecommend.vue` 接收时按 `source` 字段分流到不同渲染分支
|
|||
|
|
|
|||
|
|
### 4.2 来源 B：L1 关键词匹配（T1 异步）
|
|||
|
|
|
|||
|
|
**代码位置**：`asset_recommend_service.py::match_keywords` line 170-189
|
|||
|
|
|
|||
|
|
**核心问题**：`if keyword in message_lower` 太硬
|
|||
|
|
|
|||
|
|
**改造方案 v1.0（最小改动）**：
|
|||
|
|
|
|||
|
|
| 改造项 | 实现方式 | 优先级 |
|
|||
|
|
|--------|---------|--------|
|
|||
|
|
| 4.2.1 **中文分词**（推荐） | 引入 `jieba` 库，对用户消息分词后再匹配 | P1（v1.2 考虑） |
|
|||
|
|
| 4.2.2 **同义词表**（推荐） | `assets.yaml` 新增 `synonyms` 字段 | P1（v1.2 考虑） |
|
|||
|
|
| 4.2.3 **最小改动**（v1.0 必做） | 保持 substring 匹配，但增加"词频权重" | P0 |
|
|||
|
|
|
|||
|
|
**v1.0 实现（最小改动版）**：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
def match_keywords(self, message: str) -> List[RecommendCard]:
|
|||
|
|
"""v1.0 改造：增加词频权重 + 消息长度归一化"""
|
|||
|
|
cards = []
|
|||
|
|
message_lower = message.lower()
|
|||
|
|
msg_len = len(message_lower)
|
|||
|
|
|
|||
|
|
for keyword, asset in self.keyword_assets.items():
|
|||
|
|
# 词频权重：出现越多权重越高（最多 1.0）
|
|||
|
|
occurrences = message_lower.count(keyword)
|
|||
|
|
if occurrences == 0:
|
|||
|
|
continue
|
|||
|
|
|
|||
|
|
# 长度归一化：短消息中关键词占比高 → 权重加成
|
|||
|
|
weight = min(1.0, occurrences * (len(keyword) / max(msg_len, 1)) * 10)
|
|||
|
|
|
|||
|
|
card = self._build_card_from_asset(keyword, asset, source='keyword_assets')
|
|||
|
|
card.confidence = weight # 置信度反映匹配强度
|
|||
|
|
cards.append(card)
|
|||
|
|
|
|||
|
|
return cards
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**配置文件扩展**（`assets.yaml`）：
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
# v1.0 新增：同义词表（可选）
|
|||
|
|
synonyms:
|
|||
|
|
"vpn": ["虚拟专用网络", "远程办公", "内网穿透", "aTrust"]
|
|||
|
|
"邮箱": ["outlook", "邮件", "mail", "企业邮箱"]
|
|||
|
|
"密码": ["pwd", "口令", "登录密码"]
|
|||
|
|
|
|||
|
|
# v1.0 新增：单关键词排除规则（防止误命中）
|
|||
|
|
exclude_keywords:
|
|||
|
|
- "邮箱" # 当消息同时包含"收件箱"时排除
|
|||
|
|
- "电脑" # 当消息仅含"电脑"不命中，需配合"笔记本"/"硬件"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4.3 来源 C：L2 画像触发（T1 异步）
|
|||
|
|
|
|||
|
|
**代码位置**：`asset_recommend_service.py::match_profile_triggers` line 261-366
|
|||
|
|
|
|||
|
|
**核心问题**：画像 API 拿不到时全部 if 跳过
|
|||
|
|
|
|||
|
|
**改造方案 v1.0**：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
def match_profile_triggers(self, profile: Dict) -> List[RecommendCard]:
|
|||
|
|
"""v1.0 改造：画像 API 拿不到时降级到 DB 设备登记表"""
|
|||
|
|
cards = []
|
|||
|
|
|
|||
|
|
# v1.0 新增：画像为空时的降级
|
|||
|
|
if not profile or not profile.get('huorong_version'):
|
|||
|
|
# 降级方案：从 DB 设备登记表查最近一次上报
|
|||
|
|
cached_profile = self._get_cached_profile_from_db(profile.get('employee_id'))
|
|||
|
|
if cached_profile:
|
|||
|
|
profile = cached_profile
|
|||
|
|
|
|||
|
|
if not profile:
|
|||
|
|
return cards # 实在拿不到就返回空（C → D 降级）
|
|||
|
|
|
|||
|
|
# 原 5 个 if 触发逻辑保持不变
|
|||
|
|
...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**新增降级函数**：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
def _get_cached_profile_from_db(self, employee_id: str) -> Optional[Dict]:
|
|||
|
|
"""从 DB 设备登记表查最近一次画像缓存"""
|
|||
|
|
# 查 device_registry 表，按 updated_at DESC 取最新一条
|
|||
|
|
# 映射字段到 profile dict
|
|||
|
|
...
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 4.4 来源 D：L3 角色匹配（T1 异步）
|
|||
|
|
|
|||
|
|
**代码位置**：`asset_recommend_service.py::get_by_role` line 191-216
|
|||
|
|
|
|||
|
|
**核心问题**：英文 key vs 中文 position 永远不命中
|
|||
|
|
|
|||
|
|
**改造方案 v1.0**：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
def get_by_role(self, role: str) -> List[RecommendCard]:
|
|||
|
|
"""v1.0 改造：中文岗位子串匹配 + role_assets 新增中文 key"""
|
|||
|
|
cards = []
|
|||
|
|
|
|||
|
|
# v1.0 改造 1：精确匹配（保持原逻辑）
|
|||
|
|
if role in self.role_assets:
|
|||
|
|
asset = self.role_assets[role]
|
|||
|
|
cards.append(self._build_card_from_asset(role, asset, source='role_assets'))
|
|||
|
|
return cards
|
|||
|
|
|
|||
|
|
# v1.0 改造 2：子串匹配（中英文混合场景）
|
|||
|
|
for role_key, asset in self.role_assets.items():
|
|||
|
|
# 双向子串匹配：position 包含 key 或 key 包含 position
|
|||
|
|
if role_key in role or role in role_key:
|
|||
|
|
card = self._build_card_from_asset(role_key, asset, source='role_assets')
|
|||
|
|
card.confidence = 0.7 # 子串匹配置信度低
|
|||
|
|
cards.append(card)
|
|||
|
|
continue
|
|||
|
|
|
|||
|
|
# v1.0 改造 3：别名匹配（基于配置文件的 aliases）
|
|||
|
|
if self._match_role_alias(role, role_key):
|
|||
|
|
card = self._build_card_from_asset(role_key, asset, source='role_assets')
|
|||
|
|
card.confidence = 0.85
|
|||
|
|
cards.append(card)
|
|||
|
|
|
|||
|
|
return cards
|
|||
|
|
|
|||
|
|
def _match_role_alias(self, position: str, role_key: str) -> bool:
|
|||
|
|
"""基于角色别名表匹配"""
|
|||
|
|
aliases = self.role_aliases.get(role_key, [])
|
|||
|
|
return position in aliases or any(alias in position for alias in aliases)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**配置文件扩展**（`assets.yaml`）：
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
# v1.0 新增：中文角色 key（与英文并存）
|
|||
|
|
role_assets:
|
|||
|
|
# 英文 key（保持兼容）
|
|||
|
|
developer:
|
|||
|
|
title: "开发者资源"
|
|||
|
|
...
|
|||
|
|
|
|||
|
|
# v1.0 新增：中文 key（实际生产用）
|
|||
|
|
开发:
|
|||
|
|
alias_of: "developer"
|
|||
|
|
开发工程师:
|
|||
|
|
alias_of: "developer"
|
|||
|
|
程序员:
|
|||
|
|
alias_of: "developer"
|
|||
|
|
|
|||
|
|
财务:
|
|||
|
|
alias_of: "finance"
|
|||
|
|
财务人员:
|
|||
|
|
alias_of: "finance"
|
|||
|
|
会计:
|
|||
|
|
alias_of: "finance"
|
|||
|
|
|
|||
|
|
管理员:
|
|||
|
|
alias_of: "manager"
|
|||
|
|
管理层:
|
|||
|
|
alias_of: "manager"
|
|||
|
|
|
|||
|
|
新员工:
|
|||
|
|
alias_of: "new_employee"
|
|||
|
|
应届生:
|
|||
|
|
alias_of: "new_employee"
|
|||
|
|
|
|||
|
|
# v1.0 新增：角色别名映射（更精细的匹配）
|
|||
|
|
role_aliases:
|
|||
|
|
developer:
|
|||
|
|
- "研发"
|
|||
|
|
- "技术"
|
|||
|
|
- "前端"
|
|||
|
|
- "后端"
|
|||
|
|
- "测试"
|
|||
|
|
- "运维"
|
|||
|
|
- "DBA"
|
|||
|
|
finance:
|
|||
|
|
- "财务"
|
|||
|
|
- "会计"
|
|||
|
|
- "出纳"
|
|||
|
|
- "审计"
|
|||
|
|
manager:
|
|||
|
|
- "主管"
|
|||
|
|
- "经理"
|
|||
|
|
- "总监"
|
|||
|
|
- "VP"
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、3 种触发时机实现
|
|||
|
|
|
|||
|
|
### 5.1 T0 同步触发（Dify action 与气泡同帧）
|
|||
|
|
|
|||
|
|
**代码位置**：`h5_ai_task.py::_step_persist`
|
|||
|
|
|
|||
|
|
**改动点**：保持现有逻辑，仅在 WS 数据包中加 `trigger_timing: "T0"` 标记
|
|||
|
|
|
|||
|
|
### 5.2 T1 异步触发（AI 回复后独立步骤）
|
|||
|
|
|
|||
|
|
**代码位置**：`h5_ai_task.py::_step_assets`
|
|||
|
|
|
|||
|
|
**改动点**：
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
async def _step_assets(db, employee_id, content, result):
|
|||
|
|
"""v1.0 改造：T1 异步触发，支持超时和失败降级"""
|
|||
|
|
try:
|
|||
|
|
# v1.0 新增：3s 超时（避免阻塞主流程）
|
|||
|
|
async with asyncio.timeout(3.0):
|
|||
|
|
asset_service = get_asset_recommend_service()
|
|||
|
|
profile_service = get_employee_profile_service()
|
|||
|
|
|
|||
|
|
l1_recs = asset_service.match_keywords(content)
|
|||
|
|
|
|||
|
|
# L2 + L3 降级逻辑（与 §4.7.5 决策 ③ 对齐）
|
|||
|
|
profile = None
|
|||
|
|
try:
|
|||
|
|
profile = await asyncio.wait_for(
|
|||
|
|
profile_service.get_profile(employee_id),
|
|||
|
|
timeout=1.0
|
|||
|
|
)
|
|||
|
|
except (asyncio.TimeoutError, Exception) as e:
|
|||
|
|
logger.warning(f"[AssetRecommend] 画像获取失败/超时（C → D 降级）: {e}")
|
|||
|
|
|
|||
|
|
l2_recs = asset_service.match_profile_triggers(profile or {})
|
|||
|
|
|
|||
|
|
# 全部失败兜底（D 失败 → §4.7.4 空状态）
|
|||
|
|
if not profile:
|
|||
|
|
role = None
|
|||
|
|
else:
|
|||
|
|
role = profile.position or ''
|
|||
|
|
|
|||
|
|
l3_recs = asset_service.get_by_role(role or '')
|
|||
|
|
|
|||
|
|
# §6 多源合并
|
|||
|
|
all_recs = asset_service.merge_recommends(
|
|||
|
|
l1_recs, l2_recs, l3_recs,
|
|||
|
|
max_count=3
|
|||
|
|
)
|
|||
|
|
|
|||
|
|
# 推送 WS
|
|||
|
|
ws_msg = asset_service.build_ws_message(all_recs)
|
|||
|
|
await ws_manager.broadcast_to_employees([employee_id], ws_msg)
|
|||
|
|
|
|||
|
|
except asyncio.TimeoutError:
|
|||
|
|
logger.warning("[AssetRecommend] T1 异步触发超时（>3s），放弃本轮推荐")
|
|||
|
|
except Exception as e:
|
|||
|
|
logger.error(f"[AssetRecommend] T1 失败: {e}", exc_info=True)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5.3 T2 事件触发（审批状态变化驱动）
|
|||
|
|
|
|||
|
|
**新增模块**：`app/services/recommend_progress_service.py`
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
class RecommendProgressService:
|
|||
|
|
"""v1.0 新增：审批进度回流服务"""
|
|||
|
|
|
|||
|
|
async def handle_approval_webhook(self, approval_id: str, status: str):
|
|||
|
|
"""处理企微审批 webhook"""
|
|||
|
|
progress = RecommendProgress(
|
|||
|
|
employee_id=self._get_employee_id(approval_id),
|
|||
|
|
approval_id=approval_id,
|
|||
|
|
approval_type=self._get_approval_type(approval_id),
|
|||
|
|
status=status,
|
|||
|
|
updated_at=datetime.utcnow()
|
|||
|
|
)
|
|||
|
|
self.db.add(progress)
|
|||
|
|
self.db.commit()
|
|||
|
|
|
|||
|
|
# T2 推送：recommend_update WS
|
|||
|
|
ws_data = {
|
|||
|
|
"type": "recommend_update",
|
|||
|
|
"data": {
|
|||
|
|
"recommend_id": f"progress_{approval_id}",
|
|||
|
|
"source": "approval_progress",
|
|||
|
|
"approval_type": progress.approval_type,
|
|||
|
|
"status": status,
|
|||
|
|
"updated_at": progress.updated_at.isoformat(),
|
|||
|
|
"ttl_days": 7, # 完结后 7 天清除
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
await ws_manager.broadcast_to_employees([progress.employee_id], ws_data)
|
|||
|
|
|
|||
|
|
async def poll_pending_approvals(self):
|
|||
|
|
"""v1.0 新增：60s 轮询兜底（防止 webhook 丢失）"""
|
|||
|
|
while True:
|
|||
|
|
await asyncio.sleep(60)
|
|||
|
|
# 查最近 1 小时状态变化的审批
|
|||
|
|
recent = self.db.query(RecommendProgress).filter(
|
|||
|
|
RecommendProgress.updated_at > datetime.utcnow() - timedelta(hours=1)
|
|||
|
|
).all()
|
|||
|
|
for p in recent:
|
|||
|
|
current_status = await self._fetch_remote_status(p.approval_id)
|
|||
|
|
if current_status != p.status:
|
|||
|
|
await self.handle_approval_webhook(p.approval_id, current_status)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**WebSocket 协议扩展**：
|
|||
|
|
|
|||
|
|
| type | 来源 | 推送时机 | 用途 |
|
|||
|
|
|------|------|---------|------|
|
|||
|
|
| `dynamic_recommend` | A | T0 同步 | Dify action 卡片 |
|
|||
|
|
| `asset_recommend` | B/C/D | T1 异步 | 关键词/画像/角色推荐 |
|
|||
|
|
| `recommend_update` | T2 事件 | webhook + 轮询 | 审批进度回流（v1.0 新增） |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 六、多源合并规则实现
|
|||
|
|
|
|||
|
|
### 6.1 去重算法
|
|||
|
|
|
|||
|
|
**代码位置**：`asset_recommend_service.py` 新增 `merge_recommends` 方法
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
def merge_recommends(
|
|||
|
|
self,
|
|||
|
|
*rec_lists: List[RecommendCard],
|
|||
|
|
max_count: int = 3
|
|||
|
|
) -> List[RecommendCard]:
|
|||
|
|
"""v1.0 新增：多源合并（PRD §4.7.3 决策 ②）"""
|
|||
|
|
|
|||
|
|
# Step 1: 合并所有来源
|
|||
|
|
all_recs = []
|
|||
|
|
for recs in rec_lists:
|
|||
|
|
all_recs.extend(recs)
|
|||
|
|
|
|||
|
|
# Step 2: 按 card_key 去重（同卡片保留 confidence 最高的）
|
|||
|
|
dedup_map: Dict[str, RecommendCard] = {}
|
|||
|
|
for rec in all_recs:
|
|||
|
|
key = rec.id # 推荐用稳定 ID；fallback 到 title
|
|||
|
|
if key not in dedup_map or rec.confidence > dedup_map[key].confidence:
|
|||
|
|
dedup_map[key] = rec
|
|||
|
|
|
|||
|
|
deduped = list(dedup_map.values())
|
|||
|
|
|
|||
|
|
# Step 3: 按 layer 排序（L1 > L2 > L3，layer 内按 confidence DESC）
|
|||
|
|
layer_priority = {"L1": 1, "L2": 2, "L3": 3, "A": 0} # A 优先级最高
|
|||
|
|
deduped.sort(key=lambda r: (
|
|||
|
|
layer_priority.get(r.layer, 99),
|
|||
|
|
-r.confidence if r.confidence else 0
|
|||
|
|
))
|
|||
|
|
|
|||
|
|
# Step 4: 截断到上限
|
|||
|
|
return deduped[:max_count]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 6.2 排序算法
|
|||
|
|
|
|||
|
|
按 `layer` 字段优先级 + `confidence` 字段排序（同 layer 内按 confidence DESC）
|
|||
|
|
|
|||
|
|
### 6.3 上限控制
|
|||
|
|
|
|||
|
|
`max_count=3`（PRD §4.7.3 上限规则）
|
|||
|
|
|
|||
|
|
### 6.4 同源抑制（30 分钟窗口）
|
|||
|
|
|
|||
|
|
**代码位置**：`asset_recommend_service.py` 新增 `_same_source_suppress` 方法
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
def _same_source_suppress(
|
|||
|
|
self,
|
|||
|
|
employee_id: str,
|
|||
|
|
keyword: str,
|
|||
|
|
suppress_window_minutes: int = 30
|
|||
|
|
) -> bool:
|
|||
|
|
"""v1.0 新增：同源抑制（PRD §4.7.3 同源抑制规则）"""
|
|||
|
|
|
|||
|
|
cache_key = f"suppress:{employee_id}:{keyword}"
|
|||
|
|
cached = self.redis.get(cache_key)
|
|||
|
|
|
|||
|
|
if cached:
|
|||
|
|
return True # 在抑制窗口内，跳过
|
|||
|
|
|
|||
|
|
# 设置抑制窗口
|
|||
|
|
self.redis.setex(cache_key, suppress_window_minutes * 60, "1")
|
|||
|
|
return False
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 七、冷启动策略实现（PRD §4.7.4 决策 ① A）
|
|||
|
|
|
|||
|
|
### 7.1 客户端状态机
|
|||
|
|
|
|||
|
|
**新增 Pinia store**：`src/frontend-h5/src/stores/recommendStore.ts`
|
|||
|
|
|
|||
|
|
```typescript
|
|||
|
|
import { defineStore } from 'pinia'
|
|||
|
|
import { ref, computed } from 'vue'
|
|||
|
|
|
|||
|
|
export interface RecommendCard {
|
|||
|
|
id: string
|
|||
|
|
layer: string // 'A' | 'L1' | 'L2' | 'L3' | 'progress'
|
|||
|
|
source: string
|
|||
|
|
title: string
|
|||
|
|
description?: string
|
|||
|
|
icon?: string
|
|||
|
|
items?: any[]
|
|||
|
|
action_url?: string
|
|||
|
|
action_label?: string
|
|||
|
|
confidence?: number
|
|||
|
|
created_at: string // ISO 8601
|
|||
|
|
ttl_days?: number // 跨会话持久化 TTL
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export const useRecommendStore = defineStore('recommend', () => {
|
|||
|
|
const cards = ref<RecommendCard[]>([])
|
|||
|
|
const lastUpdate = ref<string>('')
|
|||
|
|
|
|||
|
|
// 状态机
|
|||
|
|
const state = ref<'empty' | 'cold_start' | 'populated' | 'overflow'>('empty')
|
|||
|
|
|
|||
|
|
// 计算属性
|
|||
|
|
const visibleCards = computed(() => {
|
|||
|
|
// PRD §4.7.4 决策 ① A：冷启动时右侧栏空（不显示任何卡片）
|
|||
|
|
if (state.value === 'cold_start' || state.value === 'empty') {
|
|||
|
|
return []
|
|||
|
|
}
|
|||
|
|
return cards.value.slice(0, 3) // §4.7.3 上限 3 张
|
|||
|
|
})
|
|||
|
|
|
|||
|
|
const hasContent = computed(() => visibleCards.value.length > 0)
|
|||
|
|
|
|||
|
|
// Actions
|
|||
|
|
function pushCards(newCards: RecommendCard[]) {
|
|||
|
|
if (newCards.length === 0) {
|
|||
|
|
state.value = state.value === 'empty' ? 'empty' : 'cold_start'
|
|||
|
|
return
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// FIFO：新卡片插入最上方
|
|||
|
|
cards.value = [...newCards, ...cards.value].slice(0, 10) // 本地缓存上限 10
|
|||
|
|
state.value = 'populated'
|
|||
|
|
lastUpdate.value = new Date().toISOString()
|
|||
|
|
persistToLocalStorage()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function updateProgress(recommendId: string, updates: Partial<RecommendCard>) {
|
|||
|
|
const idx = cards.value.findIndex(c => c.id === recommendId)
|
|||
|
|
if (idx === -1) {
|
|||
|
|
// 进度卡不存在 → 插入新卡到顶部
|
|||
|
|
cards.value.unshift({
|
|||
|
|
id: recommendId,
|
|||
|
|
layer: 'progress',
|
|||
|
|
source: 'approval_progress',
|
|||
|
|
...updates,
|
|||
|
|
created_at: new Date().toISOString()
|
|||
|
|
} as RecommendCard)
|
|||
|
|
} else {
|
|||
|
|
cards.value[idx] = { ...cards.value[idx], ...updates }
|
|||
|
|
}
|
|||
|
|
state.value = 'populated'
|
|||
|
|
persistToLocalStorage()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function clearByLayer(layers: string[]) {
|
|||
|
|
cards.value = cards.value.filter(c => !layers.includes(c.layer))
|
|||
|
|
if (cards.value.length === 0) {
|
|||
|
|
state.value = 'empty'
|
|||
|
|
}
|
|||
|
|
persistToLocalStorage()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function clearAll() {
|
|||
|
|
cards.value = []
|
|||
|
|
state.value = 'empty'
|
|||
|
|
persistToLocalStorage()
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 持久化（PRD §4.7.7 决策 ⑤）
|
|||
|
|
function persistToLocalStorage() {
|
|||
|
|
const persistable = cards.value.filter(c =>
|
|||
|
|
['L2', 'L3', 'progress'].includes(c.layer)
|
|||
|
|
)
|
|||
|
|
localStorage.setItem(
|
|||
|
|
`recommend_cards_${getEmployeeId()}`,
|
|||
|
|
JSON.stringify(persistable)
|
|||
|
|
)
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
function loadFromLocalStorage() {
|
|||
|
|
const cached = localStorage.getItem(`recommend_cards_${getEmployeeId()}`)
|
|||
|
|
if (cached) {
|
|||
|
|
try {
|
|||
|
|
cards.value = JSON.parse(cached)
|
|||
|
|
state.value = cards.value.length > 0 ? 'populated' : 'empty'
|
|||
|
|
} catch (e) {
|
|||
|
|
console.warn('Failed to load recommend cards from localStorage', e)
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
return {
|
|||
|
|
cards,
|
|||
|
|
state,
|
|||
|
|
visibleCards,
|
|||
|
|
hasContent,
|
|||
|
|
lastUpdate,
|
|||
|
|
pushCards,
|
|||
|
|
updateProgress,
|
|||
|
|
clearByLayer,
|
|||
|
|
clearAll,
|
|||
|
|
loadFromLocalStorage
|
|||
|
|
}
|
|||
|
|
})
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 7.2 "无则隐" 原则（前端落地）
|
|||
|
|
|
|||
|
|
**DynamicRecommend.vue 改造**：
|
|||
|
|
|
|||
|
|
```vue
|
|||
|
|
<template>
|
|||
|
|
<div v-if="recommendStore.hasContent" class="dynamic-recommend">
|
|||
|
|
<!-- PRD §4.5 UI 规范：无标题 -->
|
|||
|
|
<div
|
|||
|
|
v-for="card in recommendStore.visibleCards"
|
|||
|
|
:key="card.id"
|
|||
|
|
class="recommend-card"
|
|||
|
|
:class="`recommend-card--${card.layer.toLowerCase()}`"
|
|||
|
|
>
|
|||
|
|
<!-- 卡片内容根据 type 渲染 -->
|
|||
|
|
<component
|
|||
|
|
:is="getCardComponent(card)"
|
|||
|
|
:card="card"
|
|||
|
|
@dismiss="handleDismiss(card)"
|
|||
|
|
/>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<!-- PRD §4.7.4 决策 ① A：冷启动空状态不显示任何内容 -->
|
|||
|
|
</template>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 八、触发失败降级实现（PRD §4.7.5 决策 ③ B）
|
|||
|
|
|
|||
|
|
### 8.1 降级链路图
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
[A 失败] → [B + C + D] （Dify action 空 → 走关键词/画像/角色）
|
|||
|
|
[B 失败] → [C + D] （关键词无匹配 → 走画像/角色）
|
|||
|
|
[C 失败] → [D] （画像拿不到 → 走角色）★ 关键降级
|
|||
|
|
[D 失败] → [] （角色无匹配 → 空）★ 关键
|
|||
|
|
[全部失败] → [] （按 §4.7.4 走空状态）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 8.2 实现（已在 §4.3 / §4.4 / §5.2 给出代码）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 九、话题切换检测实现（PRD §4.7.6 决策 ④ B）
|
|||
|
|
|
|||
|
|
### 9.1 Jaccard 相似度算法
|
|||
|
|
|
|||
|
|
**新增工具**：`src/backend/app/services/topic_detector.py`
|
|||
|
|
|
|||
|
|
```python
|
|||
|
|
def jaccard_similarity(set1: set, set2: set) -> float:
|
|||
|
|
"""Jaccard 相似度"""
|
|||
|
|
if not set1 and not set2:
|
|||
|
|
return 1.0 # 两个空集合相似度为 1
|
|||
|
|
intersection = set1 & set2
|
|||
|
|
union = set1 | set2
|
|||
|
|
return len(intersection) / len(union) if union else 0.0
|
|||
|
|
|
|||
|
|
def detect_topic_change(recent_messages: List[str], current_message: str, threshold: float = 0.3) -> bool:
|
|||
|
|
"""检测话题切换（PRD §4.7.6）"""
|
|||
|
|
current_keywords = extract_keywords(current_message)
|
|||
|
|
recent_keywords = set()
|
|||
|
|
for msg in recent_messages[-3:]: # 最近 3 条
|
|||
|
|
recent_keywords |= extract_keywords(msg)
|
|||
|
|
|
|||
|
|
similarity = jaccard_similarity(current_keywords, recent_keywords)
|
|||
|
|
return similarity < threshold
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 9.2 意图突变检测
|
|||
|
|
|
|||
|
|
由 Dify 返回的 `intent_type` 与上一条不同时触发清空（已在 `match_profile_triggers` 中处理）
|
|||
|
|
|
|||
|
|
### 9.3 会话分隔
|
|||
|
|
|
|||
|
|
用户点"结束会话"或新建会话时清空所有跨会话推荐
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十、跨会话持久化实现（PRD §4.7.7 决策 ⑤ B）
|
|||
|
|
|
|||
|
|
### 10.1 客户端 localStorage 方案
|
|||
|
|
|
|||
|
|
已在 §7.1 `recommendStore.ts::persistToLocalStorage` 实现
|
|||
|
|
|
|||
|
|
### 10.2 5 类推荐的差异化持久化
|
|||
|
|
|
|||
|
|
| 推荐类型 | 持久化 | 存储位置 | 过期规则 |
|
|||
|
|
|---------|--------|---------|---------|
|
|||
|
|
| L1 / A | ❌ 不持久 | 仅 Pinia state | 话题切换即清 |
|
|||
|
|
| L2 | ✅ 持久 30 天 | localStorage | 30 天后清 / 画像更新时清 |
|
|||
|
|
| L3 | ✅ 持久 | localStorage | 角色变更时清 |
|
|||
|
|
| 审批进度（T2） | ✅ 持久直到完结 | localStorage | 审批结束/已读时清 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十一、数据模型
|
|||
|
|
|
|||
|
|
### 11.1 新增 `recommend_progress` 表（审批进度）
|
|||
|
|
|
|||
|
|
```sql
|
|||
|
|
CREATE TABLE recommend_progress (
|
|||
|
|
id SERIAL PRIMARY KEY,
|
|||
|
|
recommend_id VARCHAR(64) UNIQUE NOT NULL, -- rec_{approval_id}
|
|||
|
|
employee_id VARCHAR(64) NOT NULL,
|
|||
|
|
approval_id VARCHAR(64) NOT NULL,
|
|||
|
|
approval_type VARCHAR(50) NOT NULL,
|
|||
|
|
status VARCHAR(50) NOT NULL, -- pending/approved/rejected/completed
|
|||
|
|
created_at TIMESTAMP DEFAULT NOW(),
|
|||
|
|
updated_at TIMESTAMP DEFAULT NOW(),
|
|||
|
|
ttl_days INT DEFAULT 7, -- 完结后 N 天清除
|
|||
|
|
INDEX idx_employee (employee_id),
|
|||
|
|
INDEX idx_approval (approval_id)
|
|||
|
|
);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 11.2 新增 `recommend_event` 表（埋点）
|
|||
|
|
|
|||
|
|
```sql
|
|||
|
|
CREATE TABLE recommend_event (
|
|||
|
|
id BIGSERIAL PRIMARY KEY,
|
|||
|
|
employee_id VARCHAR(64) NOT NULL,
|
|||
|
|
recommend_id VARCHAR(64),
|
|||
|
|
layer VARCHAR(10), -- A/L1/L2/L3/progress
|
|||
|
|
source VARCHAR(50),
|
|||
|
|
event_type VARCHAR(20) NOT NULL, -- shown/clicked/dismissed/used
|
|||
|
|
conversation_id VARCHAR(64),
|
|||
|
|
created_at TIMESTAMP DEFAULT NOW(),
|
|||
|
|
INDEX idx_employee_event (employee_id, event_type),
|
|||
|
|
INDEX idx_time (created_at)
|
|||
|
|
);
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 11.3 Alembic 迁移
|
|||
|
|
|
|||
|
|
新增 `alembic/versions/{revision}_add_recommend_progress.py`（按项目惯例生成）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十二、接口设计
|
|||
|
|
|
|||
|
|
### 12.1 WebSocket 协议扩展
|
|||
|
|
|
|||
|
|
| type | 来源 | 触发时机 | 数据结构 |
|
|||
|
|
|------|------|---------|---------|
|
|||
|
|
| `dynamic_recommend` | A | T0 | `{source, trigger_timing, layer: "A", recommend_id, card_type, title, ...}` |
|
|||
|
|
| `asset_recommend` | B/C/D | T1 | `{recommends: [{layer, source, title, confidence, ...}], layered: true}` |
|
|||
|
|
| `recommend_update` | T2 | 事件 | `{recommend_id, source: "approval_progress", status, updated_at, ttl_days}` |
|
|||
|
|
|
|||
|
|
### 12.2 新增 REST API
|
|||
|
|
|
|||
|
|
| 方法 | 路径 | 用途 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| GET | `/api/recommend/progress/{approval_id}` | 查审批进度（前端轮询兜底） |
|
|||
|
|
| POST | `/api/recommend/feedback` | 用户"不相关"反馈（v1.2 接入） |
|
|||
|
|
| POST | `/api/webhook/wecom-approval` | 企微审批 webhook 接收 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十三、前端改造
|
|||
|
|
|
|||
|
|
### 13.1 DynamicRecommend.vue 重构
|
|||
|
|
|
|||
|
|
详见 §7.2 模板代码
|
|||
|
|
|
|||
|
|
### 13.2 RightPanel.vue 适配
|
|||
|
|
|
|||
|
|
**改造点**：
|
|||
|
|
- 移除"智能推荐"标题（PRD §4.5 UI 规范：无标题）
|
|||
|
|
- 引用 `useRecommendStore()` 替代本地状态
|
|||
|
|
- 监听 store.state 决定是否显示区块
|
|||
|
|
|
|||
|
|
### 13.3 状态机 store
|
|||
|
|
|
|||
|
|
详见 §7.1
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十四、性能与可用性
|
|||
|
|
|
|||
|
|
### 14.1 性能指标
|
|||
|
|
|
|||
|
|
| 指标 | 目标 | 测量 |
|
|||
|
|
|------|------|------|
|
|||
|
|
| T1 异步触发响应时间 | < 3s | 后端日志 |
|
|||
|
|
| 右侧栏渲染时间 | < 200ms | 浏览器 Performance |
|
|||
|
|
| WS 推送零延迟（T0） | 0ms | 网络抓包 |
|
|||
|
|
| localStorage 读写 | < 10ms | 浏览器 Performance |
|
|||
|
|
|
|||
|
|
### 14.2 WS 断连降级
|
|||
|
|
|
|||
|
|
WS 断连时，store 保持现有 cards（不重置），重连后增量同步
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十五、风险与降级
|
|||
|
|
|
|||
|
|
| 风险 | 等级 | 降级策略 |
|
|||
|
|
|------|------|---------|
|
|||
|
|
| Dify action 频繁失败 | 高 | A 来源降级为 B/C/D（不影响主对话） |
|
|||
|
|
| 画像 API 不可用 | 中 | C 来源降级为 D（用缓存画像兜底） |
|
|||
|
|
| WS 断连 | 中 | localStorage 保持现有卡片，重连后增量 |
|
|||
|
|
| localStorage 配额超限 | 低 | 仅保留 L2/L3/progress，LRU 淘汰 |
|
|||
|
|
| 审批 webhook 丢失 | 中 | 60s 轮询兜底 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十六、部署与灰度
|
|||
|
|
|
|||
|
|
### 16.1 部署顺序
|
|||
|
|
|
|||
|
|
1. **后端**：`asset_recommend_service.py` + `recommend_progress_service.py` + 新增表 + Alembic 迁移
|
|||
|
|
2. **前端 H5**：`recommendStore.ts` + `DynamicRecommend.vue` 重构 + `RightPanel.vue` 适配
|
|||
|
|
3. **nginx**：无改动
|
|||
|
|
4. **DB 迁移**：`alembic upgrade head`（蓝绿环境）
|
|||
|
|
5. **验收**：端到端 + 数据埋点
|
|||
|
|
|
|||
|
|
### 16.2 灰度策略
|
|||
|
|
|
|||
|
|
| 阶段 | 范围 | 持续时间 | 验证指标 |
|
|||
|
|
|------|------|---------|---------|
|
|||
|
|
| 1% 灰度 | 10 人 | 1 天 | 无 P0/P1 错误 |
|
|||
|
|
| 10% 灰度 | 100 人 | 2 天 | 点击率 > 5% |
|
|||
|
|
| 50% 灰度 | 500 人 | 3 天 | 点击率 > 10% |
|
|||
|
|
| 100% 全量 | 全部员工 | - | 点击率 > 15% |
|
|||
|
|
|
|||
|
|
### 16.3 回滚预案
|
|||
|
|
|
|||
|
|
**触发条件**：
|
|||
|
|
- P0/P1 错误率 > 5%
|
|||
|
|
- 推荐卡片渲染失败 > 2%
|
|||
|
|
- WS 推送延迟 > 5s
|
|||
|
|
|
|||
|
|
**回滚操作**：
|
|||
|
|
- 后端：`docker compose restart backend`（保留 DB 数据）
|
|||
|
|
- 前端：`docker restart wecom_it_nginx`
|
|||
|
|
- DB：`alembic downgrade -1`（删除 recommend_progress + recommend_event 表）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十七、测试策略
|
|||
|
|
|
|||
|
|
### 17.1 单元测试
|
|||
|
|
|
|||
|
|
| 模块 | 测试用例数 | 覆盖目标 |
|
|||
|
|
|------|----------|---------|
|
|||
|
|
| `asset_recommend_service.py` | 30+ | L1/L2/L3 匹配 + 合并 + 降级 |
|
|||
|
|
| `recommend_progress_service.py` | 10+ | 审批进度回流 + 轮询 |
|
|||
|
|
| `topic_detector.py` | 15+ | Jaccard 相似度 + 阈值边界 |
|
|||
|
|
|
|||
|
|
### 17.2 集成测试
|
|||
|
|
|
|||
|
|
- WS 协议全链路（A + B + C + D + T2）
|
|||
|
|
- 多源合并（4 类来源同帧推送）
|
|||
|
|
- 持久化（localStorage 跨会话）
|
|||
|
|
|
|||
|
|
### 17.3 E2E 测试（agent-browser）
|
|||
|
|
|
|||
|
|
- 员工发"VPN 申请" → 右侧栏出 VPN 卡 + 进度回流
|
|||
|
|
- 员工切换话题 → 旧 L1 推荐清空
|
|||
|
|
- 用户关闭浏览器再打开 → L2/L3/progress 持久卡片仍在
|
|||
|
|
|
|||
|
|
### 17.4 A/B 测试
|
|||
|
|
|
|||
|
|
- 灰度期间对比新旧两版的点击率、自助解决率
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十八、关联文档
|
|||
|
|
|
|||
|
|
- **PRD（冻结）**：`docs/01-产品文档/05-用户端H5/PRD-REQ-用户-006-智能推荐重构-v1.0-Frozen.md`
|
|||
|
|
- **改造实施计划**：`docs/02-技术文档/实现配置/AI对话链路全栈改造实施计划-v1.0.md`
|
|||
|
|
- **H5 用户端实现概览**：`docs/02-技术文档/前端改造/设计-H5用户端实现概览-v1.0.md`
|
|||
|
|
- **右侧栏动态推送评估**：`docs/02-技术文档/前端改造/前端设计-H5右侧栏动态推送-v1.0.md`
|
|||
|
|
- **AI 回复来源标识 PRD**：`docs/01-产品文档/03-AI服务/PRD-REQ-AI-004-AI回复来源标识-v1.0.md`
|
|||
|
|
- **代码**：
|
|||
|
|
- `src/backend/app/services/asset_recommend_service.py`
|
|||
|
|
- `src/backend/app/services/recommend_progress_service.py`（v1.0 新增）
|
|||
|
|
- `src/backend/app/services/topic_detector.py`（v1.0 新增）
|
|||
|
|
- `src/backend/app/config/assets.yaml`
|
|||
|
|
- `src/backend/app/tasks/h5_ai_task.py`
|
|||
|
|
- `src/frontend-h5/src/stores/recommendStore.ts`（v1.0 新增）
|
|||
|
|
- `src/frontend-h5/src/components/assistant/DynamicRecommend.vue`
|
|||
|
|
- `src/frontend-h5/src/components/assistant/RightPanel.vue`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 十九、变更日志
|
|||
|
|
|
|||
|
|
| 版本 | 日期 | 变更内容 | 作者 |
|
|||
|
|
|------|------|---------|------|
|
|||
|
|
| v1.0 | 2026-07-28 19:20 | 初版：基于 PRD §4.7 冻结决策，给出 4 类触发源 + 3 种时机 + 多源合并 + 冷启动 + 降级 + 话题切换 + 持久化 的技术实现 | Duckula + 宋献 |
|