# 🛡️ 拉迷家居 · 风险预警审计技能文档

> **版本**: v1.0
> **适用范围**: 拉迷家居企微群聊风险监控系统
> **维护人**: 风控团队

---

## 一、系统概述

### 1.1 背景

拉迷家居在企微运营约 60+ 个业主群，每日产生数百条聊天消息。现有风险预警系统通过「关键词匹配 + AI 审核」双重机制自动检测群聊中的风险内容（投诉、质量、法律纠纷等）。

本技能文档提供一套完整的**事后审计工具**，用于：
- 检验预警系统的覆盖效果
- 发现漏报的潜在风险消息
- 优化关键词库和预警规则
- 生成可视化管理报告

### 1.2 预警系统工作原理

```
消息到达 → 关键词匹配(AC自动机) → 命中? → AI深度分析(DeepSeek) → 有风险? → 创建RiskEvent → 通知负责人
                ↓ 未命中                    ↓ 无风险
              丢弃                        丢弃
```

**关键瓶颈**:
- 关键词命中率直接影响预警覆盖面
- AI 分析是第二道闸门，但只在关键词命中后触发
- 关键词未命中 → 消息对预警系统完全不可见

---

## 二、审计脚本清单

| 脚本 | 文件 | 用途 | 建议频率 | 耗时 |
|------|------|------|----------|------|
| 覆盖审计 | `audit-risk-coverage.ts` | 关键词覆盖率 + 漏报检测 + 可视化 HTML | 每周 | ~30s |
| 深度分析 | `audit-risk-deep-analysis.ts` | 多维度分析 + AI 管理建议 + MD 报告 | 每月 | ~10s |
| 昵称回填 | `backfill-member-nicknames.ts` | 从 Message 表回填 GroupMember 缺失昵称 | 按需 | ~30s |

---

## 三、快速开始

### 3.1 环境要求

```bash
# .env 中需要配置
DEEPSEEK_API_KEY=sk-xxxx      # AI 分析必需（可选，不配则跳过 AI 评审）
QIWE_GUID=B8591A9D-B540-...
```

### 3.2 运行覆盖审计

```bash
cd backend
npx tsx scripts/audit-risk-coverage.ts
```

**输出**: `audit-risk-YYYY-MM-DD.html` — 在浏览器中打开，包含：
- 概览卡片（消息量、预警数、覆盖率）
- 已触发预警列表
- 漏报群列表（含消息样本 + AI 评审结论）
- 未覆盖关键词云
- 管理建议卡片

### 3.3 运行深度分析

```bash
cd backend
npx tsx scripts/audit-risk-deep-analysis.ts
```

**输出**: `audit-risk-deep-YYYY-MM-DD.md` — Markdown 格式，包含：
- 消息活动分布（按天/群/参与者）
- 关键词类别有效性排名
- 漏报原因分类（促销/业务/真实风险）
- AI 管理建议（5 维度）
- 行动项清单（立即/短期/持续）

---

## 四、本期审计结果（2026-06-15 ~ 06-22）

### 4.1 核心数据

| 指标 | 数值 | 评估 |
|------|------|------|
| 文本消息总量 | 1,470 | 日均 184 条 |
| 活跃群数 | 149 | - |
| 参与人数 | 142 | - |
| 风险事件 | **4 条** | 仅覆盖 3 个群 |
| 启用关键词 | 181 个 | - |
| 触发过预警的关键词 | **4 个** | 覆盖率 2.2% 🔴 |
| 完全未触发的关键词 | **176 个** | 占比 97.2% |
| 漏报群 | 21 个 | 高危 3 / 中危 17 / 低危 1 |

### 4.2 已触发的 4 条预警

| 关键词 | 触发群 | 严重度 |
|--------|--------|--------|
| 优惠 | 多个群 | low~medium |
| 投诉 | - | - |
| (其余 2 个) | - | - |

### 4.3 关键词类别有效率

| 类别 | 总词数 | 命中词 | 命中消息 | 有效率 |
|------|--------|--------|----------|--------|
| 价格讨论 | 22 | 5 | 25 | 23% |
| 质量工艺 | 17 | 8 | 8 | 47% |
| 安装施工 | 12 | 2 | 3 | 17% |
| 负面情绪 | 17 | 1 | 2 | 6% |
| 竞品对比 | 23 | 1 | 1 | 4% |
| 投诉抱怨 | **51** | **0** | **0** | **0%** 🔴 |
| 敏感词 | **25** | **0** | **0** | **0%** 🔴 |
| 法律监管 | **8** | **0** | **0** | **0%** 🔴 |

### 4.4 漏报分类

**类型一：促销营销用词（占比最大 ~80%）**
- 「定金」「订金」「优惠」出现在大量 618 促销广播中
- 同一营销文案在 10+ 个群重复发送
- AI 评审: 正常促销，无真实风险
- **结论: 误报，不需预警**

**类型二：正常业务沟通（~12%）**
- 「色差」用于"告别线上色差"的到店体验邀约
- 「垃圾」用于询问垃圾桶尺寸
- 「宜家」用于游戏互动"宜家对杯"
- **结论: 误报，不需预警**

**类型三：真实质量风险（~8%，需关注）**
- 「脱胶」- 客户在 VIP 服务群反映产品脱胶
- AI 评审: ⚠ 有风险(medium)，安装师傅已提出修补方案
- **结论: 应预警但未预警**

### 4.5 关键发现

1. **关键词库严重冗余**: 181 个词中 176 个从未触发过预警，97% 的词是"沉睡词"
2. **三大类别完全失效**: 投诉抱怨(51词)、敏感词(25词)、法律监管(8词) 合计 84 个关键词零命中
3. **真漏报极少**: 21 个"漏报群"中，仅 2-3 个属于真实风险（脱胶等），其余均为促销营销用词误匹配
4. **盲区存在**: 纯关键词无法识别口语化抱怨（"柜子有缝""板子发黑""味道大"等）

---

## 五、管理建议

### 5.1 关键词库优化（高优先级）

| 操作 | 涉及关键词 | 原因 |
|------|-----------|------|
| 🔴 移除/降级 | 定金、订金、优惠、折扣、打折、砍价 | 大量 618 促销误匹配，非真实风险 |
| 🔴 移除/降级 | 色差、垃圾、宜家 | 正常业务语境高频出现 |
| 🟡 保留升级 | 脱胶、开裂、变形、发霉、装错 | 质量类词命中即应预警 |
| 🟡 保留观察 | 投诉、维权、退款、甲醛、超标 | 核心敏感词，虽本期未命中但须保留 |
| 🟢 新增 | 柜子有缝、板子发黑、味道大、掉皮 | 补充口语化投诉表达 |

**目标**: 将关键词库从 181 精简至 60-80 个高质量词，覆盖率从 2.2% 提升至 10%+

### 5.2 预警规则优化

1. **质量类关键词独立规则**: "脱胶/开裂/变形/发霉/装错/尺寸不对" → 命中即报，不经过 AI 二次确认
2. **聚合升级规则**: 同一群 1 小时内命中 ≥3 个不同中低危关键词 → 自动升级为高危预警
3. **频次监控**: 连续 3 天命中但 AI 判定无风险的关键词 → 标记为疑似误报，人工审核

### 5.3 盲区补充

| 盲区类型 | 示例 | 检测方案 |
|----------|------|----------|
| 口语化投诉 | "柜子有缝""板子黑了一块" | 补充口语化关键词或正则变体 |
| 情绪爆发 | 连发 5+ 条消息、大量感叹号 | 统计消息密度和标点密度 |
| 图片/语音 | 客户发损坏照片 | 标注图片+文字交叉检测（需 OCR） |
| 群内@负责人 | @店长 + 投诉内容 | 检测 @模式 + 负面词组合 |

### 5.4 流程优化

1. **三级响应机制**:
   - 高危预警 → 15 分钟内客服主管介入
   - 中危预警 → 30 分钟内区域经理跟进
   - 低危预警 → 2 小时内门店负责人确认

2. **闭环证据**: 预警关闭前需提供解决证据（维修照片、客户确认截图），防止"已读不回"

3. **误报标记**: 确认为误报的事件必须在关闭原因中注明，作为优化关键词的输入

### 5.5 定期审计节奏

| 频率 | 动作 | 负责 |
|------|------|------|
| 每日 | 查看风控大屏 pending 事件 | 值班客服 |
| 每周一 | 运行覆盖审计脚本，对比上周 | 风控专员 |
| 每月初 | 运行深度分析，输出月度报告 | 风控负责人 |
| 每月底 | 关键词大扫除（淘汰零命中词） | 风控 + 运营 |

**核心 KPI**:
- 关键词覆盖率 > 10%（当前 2.2%）
- 误报率 < 30%
- 预警响应时间 < 30 分钟
- 漏报群 < 5 个/月（含高危 0 个）

---

## 六、代码架构说明

### 6.1 audit-risk-coverage.ts

```
数据查询 (fetchAllData)
  ├── Message (msgType=0,2,13,29)
  ├── RiskEvent
  ├── RiskKeyword (enabled=true)
  └── GroupChat (roomId→roomName 映射)
      ↓
覆盖分析 (analyzeCoverage)
  ├── 按群分组消息
  ├── 关键词匹配 (matchKeywordsInMessages)
  ├── 漏报检测 (对比 alertedRoomIds / alertedKeywords)
  └── 按严重度排序输出
      ↓
AI 评审 (aiReviewMissedAlert)
  └── 高危/中危漏报 → DeepSeek 二次判定
      ↓
HTML 报告 (generateHTML)
  └── 可视化报告 + 管理建议卡片
```

### 6.2 audit-risk-deep-analysis.ts

```
数据查询 (fetchData) + 基础统计 (basicStats)
  ├── 按天/按群/按发送者分布
  └── 活跃群 TOP 15
      ↓
关键词匹配分析 (matchAnalysis)
  ├── 全量关键词命中次数
  ├── 各类别有效率排行
  └── 命中消息列表
      ↓
漏报分析 (missedVsAlerted)
  ├── 逐群对比命中词 vs 已预警词
  ├── 漏报群分类（高危/中危/低危）
  └── 真正未覆盖关键词
      ↓
AI 管理建议 (aiSummaryReport)
  └── 5 维度管理建议（关键词/规则/盲区/流程/审计）
      ↓
MD 报告生成
```

### 6.3 关键依赖

```typescript
import Parse from '../src/db/parse-client.js';  // Parse Server SDK
// AI: DeepSeek API (/v1/chat/completions)
// 模型: deepseek-chat, temperature=0.2~0.4
```

---

## 七、附录

### A. 相关文件索引

| 文件 | 说明 |
|------|------|
| `audit-risk-coverage.ts` | 覆盖审计脚本 |
| `audit-risk-deep-analysis.ts` | 深度分析脚本 |
| `backfill-member-nicknames.ts` | 昵称回填脚本 |
| `audit-risk-2026-06-15-22.html` | 本期 HTML 报告 |
| `audit-risk-2026-06-15-22.md` | 本期 MD 报告(简版) |
| `audit-risk-deep-2026-06-15-22.md` | 本期深度 MD 报告 |
| `../src/services/message-analyzer.service.ts` | 线上分析引擎 |
| `../src/services/compliance-check.service.ts` | 合规检查 + AC 自动机 |
| `../src/services/ai-analysis.service.ts` | DeepSeek AI 分析 |
| `../src/services/risk-event.service.ts` | 风险事件 CRUD |

### B. 常见问题

**Q: 脚本跑很慢？**
A: AI 评审阶段每个漏报群调一次 DeepSeek，限制最多 20 次。取消 AI 可不配 DEEPSEEK_API_KEY。

**Q: 漏报数量为什么和实际感觉不一致？**
A: 当前漏报检测基于"关键词命中但未触发预警"。关键词没命中的消息不在检测范围内（盲区）。

**Q: 如何新增关键词？**
A: RiskKeyword 表手动添加，或通过前端「关键词管理」页面操作。系统每 5 分钟自动刷新 AC 自动机。

**Q: 如何查看实时预警？**
A: 前端风控大屏 `http://localhost:4041/risk-control/dashboard`，或预警弹窗（每 30s 轮询）。

---

*技能文档由风控团队维护，每次重大变更后更新版本号。*