simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6c60fb81db7a01a19bc8b85cbab64dcb25ec62d0
wecom_it_smart_desk/docs/01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.2-AI辅助.md
T
Simon facc04aa65 chore: docs 结构整改 + compose 双目录对齐（合并重建提交） 
本提交为 .git 对象库损坏后的重建提交，内容等价于原先三个本地提交
（5e2fd4c2 / 57a53c98 / 5d7e1873）的累积结果，未做任何额外改动。

一、docs 结构整改（整改 #14）
根因：重构时新结构为 untracked 文件，执行 git stash（未带 -u）未纳入，
随后 git reset 拉回 HEAD 旧 tracked 树，导致旧树复活、新旧两棵目录
树并存于 docs/，共 791 文件、双分类体系冲突。

修复动作：
- b2 同名异主题文件改名迁移保全 9 个
- C 类 39 个孤立文件按主题正确归类
- A/B1 类 222 个重复文件删除（新结构已有内容副本）
- 9 个旧独有空目录删除
- 270 处内部引用按 verified 映射改写
- 整改记录 #14 登记于 04-运维文档/部署运维

结果：docs 791 → 569 文件，顶层仅规范 8 类 + 治理文件，单树恢复。
残留：约 20 处指向从未存在文件的陈旧死链，归入独立文档卫生任务。

二、compose 双目录对齐（消除踩坑 A）
- docker-compose.yml：nginx 前端挂载全部由根目录 frontend-*/dist
  改为 src/frontend-*/dist（h5 / agent / admin / terminal）
- docker-compose.dev.yml：dev 服务 build context 与卷同步改 src/
- 效果：本地 docker compose up 不再把根目录 stale dist 挂回，
  与线上一致，分叉隐患消除（已 docker compose config 校验通过）

防复发铁律：
- 重构须提交；仓库修复须 git stash -u 或先 commit
- 新结构须 git add 并提交，避免再次 untracked 复活
- H5 改动只动 src/frontend-h5/，禁改根目录遗留 frontend-*/
2026-08-07 22:31:32 +08:00

419 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 辅助运营为定位**
Reference in New Issue View Git Blame Copy Permalink