# PRD - 敏感词检测 v1.2（AI 辅助运营）

> **需求编号**: REQ-通用-004
> **版本**: v1.2（基于 v1.1 升级）
> **状态**: 草案 v1.0（待评审）
> **作者**: 宋献
> **日期**: 2026-07-28
> **前置版本**: PRD-REQ-通用-004-敏感词检测-v1.0（v0.7.1 上线），v1.1（DB化+后台 UI+审计日志，2026-07-28 上线）
> **关联文档**:
> - 前置 PRD：`01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.0.md`
> - 前置技术方案：`02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.0.md`
> - 关联战略：`01-产品文档/00-产品规划/IT服务台AI化战略路线图-v1.0.md`

---

## 1. 需求描述

### 1.1 背景（v1.1 回顾）

v1.1（2026-07-28 上线）实现了：
- 词库入库（`sensitive_words` / `privacy_patterns`）
- 后台管理 UI（4 Tabs）
- 命中审计日志
- 灰度开关

但 **v1.1 仍然依赖人肉运营**：
- 新敏感词需运营**逐条人工发现并加入**
- 词库命中规则**写死 4 条** + 运营手动扩展
- 绕过场景（如"自己不会百度嘛"加语气词）**无法识别**
- 词库命中率/误判率**无人系统分析**

### 1.2 v1.2 升级动机

**业务压力**：组织正经历 AI 技术冲击，**没有时间从"人肉维护"过渡到"AI 维护"**，敏感词检测 v1.2 必须**直接进入 AI 辅助运营阶段**。

### 1.3 v1.2 目标

| 目标 | 描述 |
|------|------|
| **G1 自动化运营** | 词库发现 / 分类 / 调整由 AI 完成，人工仅最终审核 |
| **G2 绕过场景覆盖** | 引入 AI 语义级检测，**替代 wordfilter** 主路径 |
| **G3 反馈闭环** | 误判自动反馈 → AI 学习 → 自动加白名单 |
| **G4 数据驱动** | 命中率/误判率/绕过模式可量化分析 |

### 1.4 范围

| 范围项 | v1.2 状态 | 说明 |
|--------|----------|------|
| AI 敏感词发现引擎 | ✅ P0 必做 | Dify 工作流：历史 messages + 工单 → LLM 提取 |
| AI 审核工作台 | ✅ P0 必做 | 运营一键 approve / reject |
| AI 误判反馈闭环 | ✅ P0 必做 | 坐席 WARN 后"非命中"反馈 → AI 学习 → 白名单建议 |
| **AI 语义级检测** | ✅ **P0 主路径** | **替代 wordfilter**（用户决策 2026-07-28 确认） |
| AI 自动构造测试用例 | 🟡 P1 | 对抗样本自动生成 |
| AI 智能日报 | 🟡 P1 | 每日违规模式自动分析 |
| AI 自动审批（无人审核） | ❌ P2 不做 | 与 2026-07-08 决策冲突，保留人工最终审核 |
| AI 自动变更 severity | ❌ P2 不做 | 需配套审计，待评审 |

### 1.5 Non-goals

| 不做 | 原因 |
|------|------|
| 完全无人化（AI 全自动） | 决策保留：所有 AI 推荐需人工最终确认 |
| 多语言支持 | 业务尚未确认 |
| 跨租户词库隔离 | 当前单租户架构，无 SaaS 化需求 |
| 组织级 AI 化变革 | 独立任务（见 AI 化路线图），v1.2 仅做工具自身 AI 化 |

---

## 2. 用户故事

### 2.1 运营人员

| 优先级 | 用户故事 |
|--------|----------|
| P0 | 作为运营，我希望看到 AI 自动推荐的新词候选，一键加入词库 |
| P0 | 作为运营，我希望 AI 自动判定分类（profanity/privacy）和 severity，无需我手动选 |
| P0 | 作为运营，我希望 AI 自动分析"非命中"反馈，给出白名单建议 |
| P1 | 作为运营，我希望看到每日违规分析报告（高频词/高频坐席） |
| P1 | 作为运营，我希望 AI 自动生成对抗样本测试，验证词库覆盖率 |

### 2.2 坐席

| 优先级 | 用户故事 |
|--------|----------|
| P0 | 作为坐席，我希望 AI 能识别"自己不会百度嘛"等绕过的语气（不被精确匹配绕过） |
| P0 | 作为坐席，我希望误报时一键标记"非命中"，系统记住我的反馈 |
| P0 | 作为坐席，我希望继续保留最终发送权（不被 AI 强制阻断） |

### 2.3 管理员

| 优先级 | 用户故事 |
|--------|----------|
| P1 | 作为管理员，我希望所有 AI 推荐/审核记录可追溯 |
| P1 | 作为管理员，我希望 AI 引擎可灰度启用（如先 1 个部门试运行） |
| P2 | 作为管理员，我希望 AI 引擎可关闭，回到 v1.1 模式 |

---

## 3. 功能需求

### 3.1 AI 敏感词发现引擎（P0）

| 字段 | 规格 |
|------|------|
| 输入数据 | 1) 历史 messages（最近 30 天）<br>2) 工单投诉内容<br>3) 审计日志（被 WARN 的文本）<br>4) 运营白名单（已知非敏感词） |
| AI 处理 | Dify 工作流：<br>① 数据采样（按时间+部门）<br>② LLM 推理（提取风险词 + 判定分类 + 判定 severity）<br>③ 去重（与现有词库 diff）<br>④ 输出"待审核"队列 |
| 触发时机 | 每日凌晨 03:00 自动跑（cron）<br>运营可手动触发（按钮） |
| 输出 | `ai_pending_words` 表（待审核队列） |
| 数据量 | 30 天 messages 约 1 万条，LLM 处理 ≈ 30 秒 |

### 3.2 AI 审核工作台（P0）

| 字段 | 规格 |
|------|------|
| 位置 | `/sensitive-words` 管理后台 → 新增 Tab"AI 推荐" |
| 展示 | 待审核词列表：word / category / severity / AI 置信度 / 来源 / 推荐时间 |
| 操作 | 1) approve → 写入 `sensitive_words` 表<br>2) reject → 标记"已拒绝"，不再推荐<br>3) 编辑 → 修改 word/category/severity 后 approve |
| 批量 | 支持批量 approve（多选） |
| 审计 | 所有操作写 `ai_word_review_logs` 表 |

### 3.3 AI 误判反馈闭环（P0）

| 字段 | 规格 |
|------|------|
| 坐席侧 | WARN 提示条增加"非命中"按钮 |
| 后端 | 接收反馈 → 写入 `false_positive_feedback` 表（text / agent_id / timestamp） |
| AI 处理 | 每日分析"非命中"反馈：<br>① 提取频繁被标记的词/短语<br>② LLM 判定"确为误报" → 自动加白名单<br>③ LLM 判定"需复审" → 入 AI 审核队列 |
| 白名单存储 | 新增 `whitelist` 表（phrase / category / source / created_at） |
| 检测逻辑 | 审核时：先查白名单 → 命中则直接 PASS |

### 3.4 AI 语义级检测（P0 主路径）

| 字段 | 规格 |
|------|------|
| **替代目标** | **替代 wordfilter** 作为主检测引擎 |
| 实现方式 | Dify LLM 调用（GPT-4o-mini 或国产模型） |
| 输入 | 坐席消息文本 |
| 输出 | `{action, category, matched_concepts, confidence, suggestion}` |
| 响应时间 | < 2s（P95） |
| 成本 | ¥0.001 / 次（GPT-4o-mini）<br>按日均 1 千条消息 ≈ ¥1/天 |
| 降级策略 | Dify 不可用时 → 降级为 wordfilter（v1.1 引擎）<br>降级日志：ERROR + 计数 |
| 决策动作 | 仍维持 WARN（2026-07-08 决策保留） |
| 旁路 | wordfilter 仍作为快速预筛（命中则直接 WARN，不调 AI）<br>未命中 → 调 AI 语义 |

### 3.5 AI 自动构造测试用例（P1）

| 字段 | 规格 |
|------|------|
| 触发 | CI 流水线 / 运营手动 |
| 生成 | LLM 自动生成 100 条对抗样本（语气词 / 同义词 / 拼音化） |
| 跑测 | 自动跑 pytest 报告 |
| 输出 | 覆盖率报告：词库覆盖 / AI 语义覆盖 / 遗漏点 |

### 3.6 AI 智能日报（P1）

| 字段 | 规格 |
|------|------|
| 触发 | 每日 08:00 自动生成 |
| 内容 | 1) 命中总数（按 action / category 分布）<br>2) 高频违规坐席（Top 10）<br>3) 高频违规部门（按部门聚合）<br>4) 命中时段分布（小时级热力图）<br>5) AI 语义命中 vs wordfilter 命中（覆盖率对比）<br>6) 误报率（"非命中"反馈占比） |
| 推送 | 管理员企微消息卡片 |
| 存储 | `daily_reports` 表（30 天滚动） |

---

## 4. 数据需求

### 4.1 新增表

#### `ai_pending_words`（AI 推荐词队列）
```sql
CREATE TABLE ai_pending_words (
    id              SERIAL PRIMARY KEY,
    word            VARCHAR(100) NOT NULL,
    category        VARCHAR(50) NOT NULL,
    severity        SMALLINT NOT NULL,
    confidence      DECIMAL(3,2) NOT NULL,    -- 0.00~1.00
    source          VARCHAR(50) NOT NULL,      -- message_sample / complaint / audit_log
    sample_text     TEXT,                      -- 原始样本（前 200 字）
    status          VARCHAR(20) DEFAULT 'pending', -- pending / approved / rejected
    reviewed_by     INTEGER REFERENCES users(id),
    reviewed_at     TIMESTAMP,
    created_at      TIMESTAMP DEFAULT NOW(),
    UNIQUE(word, status)
);
CREATE INDEX idx_pending_status ON ai_pending_words(status, created_at);
```

#### `false_positive_feedback`（误判反馈）
```sql
CREATE TABLE false_positive_feedback (
    id              BIGSERIAL PRIMARY KEY,
    agent_id        INTEGER NOT NULL REFERENCES agents(id),
    original_text   TEXT NOT NULL,
    matched_word    VARCHAR(100),
    category        VARCHAR(50),
    created_at      TIMESTAMP DEFAULT NOW()
);
CREATE INDEX idx_fp_agent ON false_positive_feedback(agent_id, created_at);
```

#### `whitelist`（白名单）
```sql
CREATE TABLE whitelist (
    id              SERIAL PRIMARY KEY,
    phrase          VARCHAR(200) NOT NULL UNIQUE,
    category        VARCHAR(50),
    source          VARCHAR(50),                -- ai_auto / manual / fp_feedback
    created_at      TIMESTAMP DEFAULT NOW(),
    expires_at      TIMESTAMP                   -- 可选：临时白名单
);
```

#### `ai_word_review_logs`（AI 推荐审核记录）
```sql
CREATE TABLE ai_word_review_logs (
    id              BIGSERIAL PRIMARY KEY,
    pending_id      INTEGER REFERENCES ai_pending_words(id),
    reviewer_id     INTEGER REFERENCES users(id),
    action          VARCHAR(20) NOT NULL,       -- approve / reject / edit
    original_word   VARCHAR(100),
    final_word      VARCHAR(100),
    notes           TEXT,
    created_at      TIMESTAMP DEFAULT NOW()
);
```

#### `daily_reports`（每日报告）
```sql
CREATE TABLE daily_reports (
    id              SERIAL PRIMARY KEY,
    report_date     DATE UNIQUE NOT NULL,
    payload         JSONB NOT NULL,
    created_at      TIMESTAMP DEFAULT NOW()
);
```

### 4.2 `sensitive_words` 表扩展

```sql
-- 新增字段
ALTER TABLE sensitive_words ADD COLUMN source VARCHAR(50) DEFAULT 'manual';
-- source 取值: manual / ai_recommend / imported / migrated_from_v07

ALTER TABLE sensitive_words ADD COLUMN confidence DECIMAL(3,2);
-- 仅 ai_recommend 来源的词有置信度
```

### 4.3 Alembic 迁移

- 新建：`alembic/versions/057_add_ai_moderation_tables.py`

---

## 5. 接口需求

### 5.1 新增后端 API（11 端点）

| 接口 | 方法 | 说明 | 权限 |
|------|------|------|------|
| `/api/admin/ai-pending-words` | GET | 列表查询 | admin |
| `/api/admin/ai-pending-words/{id}/approve` | POST | 审核通过 | admin |
| `/api/admin/ai-pending-words/{id}/reject` | POST | 审核拒绝 | admin |
| `/api/admin/ai-pending-words/batch-approve` | POST | 批量通过 | admin |
| `/api/admin/ai-pending-words/trigger` | POST | 手动触发 AI 发现 | admin |
| `/api/admin/false-positive-feedback` | POST | 坐席提交反馈 | agent |
| `/api/admin/false-positive-feedback` | GET | 查询反馈 | admin |
| `/api/admin/whitelist` | GET/POST/PUT/DELETE | 白名单 CRUD | admin |
| `/api/admin/whitelist/auto-suggest` | POST | AI 基于反馈生成建议 | admin |
| `/api/admin/daily-reports/latest` | GET | 最新日报 | admin |
| `/api/admin/daily-reports/{date}` | GET | 指定日期日报 | admin |

### 5.2 改造现有 API

| 接口 | 变更 |
|------|------|
| `POST /admin/sensitive-words/test` | 增加 AI 语义模式（`mode=ai`） |
| `GET /admin/moderation-config` | 增加 `ai_engine_enabled` 字段 |
| `PUT /admin/moderation-config` | 增加 AI 引擎开关 |

### 5.3 Dify 工作流（3 个）

| 工作流 | 用途 |
|--------|------|
| `sensitive_word_discovery` | 输入 messages → 输出风险词列表 |
| `false_positive_analyzer` | 输入 fp_feedback → 输出白名单建议 |
| `daily_report_generator` | 输入审计日志 + 命中数据 → 输出日报 |

### 5.4 配置项（v1.2 新增）

```python
# config.py
AI_MODERATION_ENABLED = False  # 总开关
AI_DISCOVERY_CRON_HOUR = 3     # 每日 AI 发现执行时间
AI_DAILY_REPORT_HOUR = 8       # 日报推送时间
DIFY_DISCOVERY_APP_ID = "..."  # 复用现有 Dify app
DIFY_API_KEY = "..."           # 从 .env 读
WHITELIST_ENABLED = True        # 白名单开关
```

**配置同步铁律**：新增 6 个配置项时需同步：
1. `config.py` 字段
2. `docker-compose.yml` 的 `backend.environment`
3. `.env.example` 模板

---

## 6. 数据隐私合规（重要）

### 6.1 LLM 输入数据合规

| 数据类型 | 合规要求 |
|----------|----------|
| 历史 messages | 喂 LLM 前**脱敏**：移除手机号/身份证/邮箱/姓名 |
| 工单投诉内容 | 同样脱敏 |
| 审计日志 | 已脱敏（v1.1 仅存 text_excerpt 100 字） |

### 6.2 脱敏规则

```python
# content_moderation_service.py 新增 _sanitize_for_ai()
def _sanitize_for_ai(text: str) -> str:
    """喂 AI 前脱敏"""
    text = re.sub(r'(?<!\d)1[3-9]\d{9}(?!\d)', '[PHONE]', text)
    text = re.sub(r'(?<!\d)\d{17}[\dXx](?!\d)', '[ID_CARD]', text)
    text = re.sub(r'(?<!\d)\d{16,19}(?!\d)', '[BANK]', text)
    text = re.sub(r'[\w.-]+@[\w.-]+\.[\w]+', '[EMAIL]', text)
    text = re.sub(r'[\u4e00-\u9fa5]{2,4}(?=先生|女士|老师|经理|总)', '[NAME]', text)
    return text
```

### 6.3 合规审计

| 审计项 | 实施 |
|--------|------|
| LLM 调用日志 | `ai_llm_calls` 表：app_id / 输入 hash / 输出 / 延迟 / 成本 |
| 数据脱敏校验 | 单元测试：确保喂 LLM 前已脱敏 |
| 运营 review 记录 | 所有 AI 推荐审核写入 `ai_word_review_logs` |
| 错误监控 | Sentry / 日志告警：Dify API 失败率 > 5% |

---

## 7. 风险与降级

| 风险 | 等级 | 降级措施 |
|------|------|----------|
| Dify API 不可用 | 🟡 中 | 自动降级为 wordfilter（v1.1 引擎） |
| AI 推荐质量低 | 🟡 中 | 置信度 < 0.7 不入"待审核"队列 |
| 脱敏不彻底泄露隐私 | 🟠 高 | 脱敏失败时**不调 LLM**，直接降级 wordfilter |
| AI 误判高（绕过场景也误报） | 🟡 中 | 人工 review 必须；自动阈值兜底 |
| 审计日志爆炸 | 🟢 低 | 7 天前的旧 fp_feedback 自动清理 |
| AI 引擎与决策冲突 | 🟡 中 | **保留人工最终审核**（决策保留 2026-07-08） |

---

## 8. 验收标准

### 8.1 必达项（v1.2 P0）

- [ ] AI 发现引擎每天 03:00 自动跑，生成 ≥ 1 个推荐词（基于历史数据）
- [ ] AI 审核工作台：运营可一键 approve / reject / 批量 approve
- [ ] AI 误判反馈闭环：坐席"非命中"按钮 → 24h 内 AI 自动分析
- [ ] **AI 语义级检测作为主路径**：Dify 不可用时降级 wordfilter
- [ ] AI 语义覆盖"自己不会百度嘛"等语气绕过场景
- [ ] 数据脱敏：喂 LLM 前已移除 PII
- [ ] 所有 AI 推荐均经人工最终确认
- [ ] 命中动作仍为 WARN（决策保留）
- [ ] 白名单生效：白名单词命中 WARN 时直接 PASS
- [ ] 灰度开关：`AI_MODERATION_ENABLED=false` 时回到 v1.1 行为

### 8.2 非必达（v1.2 P1 / P2）

- [ ] AI 自动构造测试用例（P1）
- [ ] AI 智能日报推送（P1）
- [ ] AI 自动审批（不做）
- [ ] AI 自动变更 severity（不做）

---

## 9. 实施路线

| 阶段 | 内容 | 工作量 |
|------|------|--------|
| **D1** | Dify 工作流（3 个）开发 + 测试 | 2 天 |
| **D2** | 后端：5 新表 + 11 API + 现有 API 扩展 | 2 天 |
| **D3** | 前端：AI 审核工作台 + 误报反馈按钮 + 白名单 UI | 2 天 |
| **D4** | AI 语义级检测集成 + 降级逻辑 | 1 天 |
| **D5** | 数据脱敏 + 合规审计 | 0.5 天 |
| **D6** | 部署 + 灰度发布（先 1 个坐席试运行 24h） | 1 天 |
| **总计** | | **8.5 天** |

---

## 10. 关联文档

| 文档 | 位置 | 关联点 |
|------|------|--------|
| 前置 PRD v1.0 | `01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.0.md` | 基础功能 |
| 前置技术方案 v1.0 | `02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.0.md` | 实现参考 |
| 前置测试用例 | `03-测试文档/03-功能测试用例/TC-通用-004-敏感词检测.md` | 测试基线 |
| **关联战略** | `01-产品文档/00-产品规划/IT服务台AI化战略路线图-v1.0.md` | **v1.2 是战略落地的第一个抓手** |
| Dify 应用清单 | `02-技术文档/实现配置/dify_dsl/` | 新增 3 工作流 |
| 看板验真测试报告 | `03-测试文档/04-版本测试报告/看板验真-测试报告-20260707.md` | 历史基线 |

---

## 11. 变更日志

| 版本 | 日期 | 变更 | 变更人 |
|------|------|------|--------|
| v1.0 | 2026-07-28 | 首次整理：v0.7.1 上线内容回溯为正式 PRD | 宋献 |
| v1.1 | 2026-07-28 | DB化 + 后台 UI + 审计日志 + 灰度开关 | 宋献 |
| **v1.2 草案 v1.0** | **2026-07-28** | **AI 辅助运营：AI 语义级检测纳入 P0 替代 wordfilter** | **宋献** |

---

> **关键决策记录**：
> - 2026-07-08：命中动作固定 WARN（v1.0 决策）
> - 2026-07-28：v1.1 上线（DB化）
> - **2026-07-28：v1.2 启动，AI 语义级检测作为主路径，AI 辅助运营为定位**