# 🛡️ 拉迷家居 · 风险预警审计工具包

> 独立可分发 | 开箱即用 | 适用于 Parse Server + QiWe 企微群聊风控系统

## 快速开始

```bash
# 1. 安装依赖
npm install parse dotenv

# 2. 复制配置模板 → 编辑环境变量
cp .env.example .env

# 3. 运行
npx tsx audit-coverage.ts        # 覆盖审计 → HTML 报告
npx tsx audit-deep-analysis.ts   # 深度分析 → MD 报告
```

---

## 文件说明

| 文件 | 作用 |
|------|------|
| `audit-coverage.ts` | **覆盖审计** — 扫全量消息，检测关键词命中但未预警的「漏报」，AI 逐条评审 |
| `audit-deep-analysis.ts` | **深度分析** — 多维度统计 + 类别有效性排名 + AI 管理建议 |
| `parse-client.ts` | Parse Server 连接初始化（读 `.env` 中的 `PARSE_*` 变量） |
| `.env.example` | 环境变量模板 |
| `README.md` | 本文档 |

### 输出产物

| 脚本 | 输出 | 说明 |
|------|------|------|
| `audit-coverage.ts` | `audit-risk-YYYY-MM-DD.html` | 可视化 HTML，浏览器打开 |
| `audit-deep-analysis.ts` | `audit-deep-YYYY-MM-DD.md` | Markdown 管理报告 |

---

## 环境变量

```bash
# ── Parse Server 连接（必填） ──
PARSE_APP_ID=lami-ai
PARSE_SERVER_URL=https://server.sh-lami.com/parse
PARSE_MASTER_KEY=your-master-key

# ── 企业微信 GUID（必填，用于数据隔离） ──
QIWE_GUID=B8591A9D-B540-44F9-9D74-B2EF5B419EAA

# ── DeepSeek AI（可选，不配则跳过 AI 评审） ──
DEEPSEEK_API_KEY=sk-xxxx
DEEPSEEK_API_URL=https://api.deepseek.com/v1/chat/completions
DEEPSEEK_MODEL=deepseek-chat

# ── 审计时间范围（可选，默认最近 7 天） ──
AUDIT_START=2026-06-15T00:00:00+08:00
AUDIT_END=2026-06-22T23:59:59+08:00
```

---

## 功能对比

| 维度 | audit-coverage.ts | audit-deep-analysis.ts |
|------|-------------------|------------------------|
| 关键词覆盖率 | ✅ | ✅ |
| 漏报群检测 | ✅ + AI 逐条评审 | ✅ + 三分类归因 |
| 可视化报告 | ✅ HTML（浏览器） | ✅ MD（可打印） |
| 消息分布统计 | ❌ | ✅ 按天/群/类型 |
| 类别有效性排名 | ❌ | ✅ |
| AI 管理建议 | ❌（仅评审） | ✅ 5 维度建议 |
| 行动项清单 | ❌ | ✅ 分级行动项 |
| 建议频率 | **每周** | **每月** |
| 耗时 | ~30s | ~10s |

---

## 工作流示意

```
┌─────────────────────────────────────────────────────────┐
│                    每周: audit-coverage.ts               │
│                                                         │
│  Message ──→ 关键词匹配 ──→ 命中? ──→ 已有预警?         │
│     │            │              │           │            │
│     │            │            NO          YES → 跳过     │
│     │            │              │                        │
│     │            │         【漏报】──→ AI 评审           │
│     │            │              │           │            │
│     └────────────┴──────────────┴───────────┘            │
│                         ↓                                │
│                  audit-risk-*.html                        │
└─────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│                 每月: audit-deep-analysis.ts              │
│                                                         │
│  基础统计 + 类别有效性 + 漏报归因 + AI管理建议            │
│                         ↓                                │
│                  audit-deep-*.md                          │
│                         ↓                                │
│              优化关键词库 / 调整规则                      │
└─────────────────────────────────────────────────────────┘
```

---

## 依赖的数据表

本工具假设目标 Parse Server 中存在以下表：

| 表 | 关键字段 | 用途 |
|---|---------|------|
| `Message` | content, senderId, senderName, roomId, msgType, timestamp | 消息内容 |
| `RiskEvent` | groupId, keywords, severity, title, status, createdAt | 已触发预警 |
| `RiskKeyword` | word, category, severity, enabled | 关键词库 |
| `GroupChat` | roomId, roomName, communityName | 群映射 |

---

## 核心指标解释

### 关键词覆盖率
```
触发过预警的关键词数 / 启用关键词总数
```
- < 3% → 🔴 严重冗余，需大规模清理
- 3~8% → 🟡 中等，需分类审核
- > 10% → 🟢 健康

### 类别有效率
```
该类命中消息的关键词数 / 该类总词数
```
- 0% 的类别 → 所有关键词均未启用或过于极端，需重新审核

### 漏报分类
- **促销营销**: 618/双11活动文案 → 误匹配，不需预警
- **正常业务**: 正常设计/安装沟通 → 误匹配，不需预警
- **真实风险**: 质量投诉/纠纷 → 真漏报，需立即处理

---

## 典型使用场景

### 场景 1: 每周风控例会前
```bash
# 设置上周的日期
export AUDIT_START="2026-06-15T00:00:00+08:00"
export AUDIT_END="2026-06-22T23:59:59+08:00"

npx tsx audit-coverage.ts
# 打开 audit-risk-2026-06-15.html 投屏展示
```

### 场景 2: 月度关键词大扫除
```bash
export AUDIT_START="2026-06-01T00:00:00+08:00"
export AUDIT_END="2026-06-30T23:59:59+08:00"

npx tsx audit-deep-analysis.ts
# 根据报告中的"类别有效性"和"未覆盖关键词"
# 淘汰 30 天零命中的词，升级质量类词权重
```

### 场景 3: 618/双11 专项审计
```bash
# 大促前后两周的独立审计
export AUDIT_START="2026-06-01T00:00:00+08:00"
export AUDIT_END="2026-06-22T23:59:59+08:00"
npx tsx audit-coverage.ts
# 检查促销用词是否导致大量误报
```

---

## 部署到其他项目

1. 复制整个 `audit-risk-kit/` 文件夹到目标机器
2. `npm install parse dotenv`
3. `cp .env.example .env` → 编辑 `.env` 填入目标 Parse Server 连接信息
4. 确保目标 Parse Server 中存在上述 4 张表（Message / RiskEvent / RiskKeyword / GroupChat）
5. 运行脚本

> 注意: 表名和字段名必须一致。如果目标项目使用不同的表名或字段名，需要修改脚本中的 `new Parse.Query('...')` 和 `.get('...')` 调用。

---

## 常见问题

**Q: 脚本跑很慢？**
A: AI 评审阶段每个漏报群调一次 DeepSeek，限制最多 20 次。可去掉 `DEEPSEEK_API_KEY` 配置跳过 AI 评审，脚本秒出结果。

**Q: 漏报数量为什么感觉偏多？**
A: 当前漏报基于"关键词命中但未触发预警"。大部分是促销营销词命中，并非真实风险。看 AI 评审列来区分真假漏报。

**Q: 如何新增/删除关键词？**
A: 通过 Parse Dashboard 操作 RiskKeyword 表，系统每 5 分钟自动刷新关键词库。

**Q: 支持非拉迷项目的企微风控吗？**
A: 工具与业务解耦，只要是同样的表结构（Message / RiskKeyword / RiskEvent / GroupChat），直接配置连接即可使用。

---

*拉迷家居 · 风控团队 · v1.0*