Files

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

14 KiB

Raw Blame History

任务说明书 03 — 敏感词检测 v1.1（词库入库 + 后台 UI）

任务编号: v1.1 增量（关联任务 #81 延后项）版本: v1.1 创建日期: 2026-07-28 作者: 宋献 关联 PRD: docs/01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.0.md 关联技术方案: docs/02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.0.md 关联测试用例: docs/03-测试文档/03-功能测试用例/TC-通用-004-敏感词检测.md 关联数据迁移: src/backend/alembic/versions/056_add_moderation_tables.py 关联源码: src/backend/app/services/content_moderation_service.py 基础版本: v0.7.1（已上线，命中即 WARN，词库写死 4 条）

📋 任务概览

项目	内容
任务名	敏感词检测 v1.1 — 词库入库 + 后台 UI
目标	把 v0.7.1 写死的 4 条基础词和 4 类隐私正则，迁移到 PostgreSQL 数据库，并开发管理后台 UI，让运营可自主增删改查、可热加载、可配置命中动作
优先级	🟠 P1（v0.7.1 已上线，WARN 策略可接受，v1.1 是优化）
类型	功能开发（数据库 + 后端 + 前端）
估时	1 人天（数据库 0.2d + 后端 0.4d + 前端 0.3d + 部署 0.1d）
阻塞项	无（#81 延后项已部分解决，剩余 UI 部分 v1.1 完成）
风险等级	🟡 中（DB 切换需双轨降级，避免业务中断）

🎯 任务背景

现状（v0.7.1）

✅ 已上线：内容审核服务（content_moderation_service.py）
⚠️ 写死 4 条敏感词：运营无法调整
⚠️ 写死 4 类隐私正则：无法扩展
⚠️ 命中动作固定 WARN：决策保留（v1.0 不升级 BLOCK）
⚠️ 后台 UI 缺失：运营改词必须改代码
⚠️ 无审计日志：合规追溯缺失
⚠️ TC-202 P0 延后项"中文+号码"已修复验证（(?<!\d)/(?!\d) 数字边界 + 调整检测顺序）
⚠️ 真实 bug 已修复：身份证前 17 位误判为 bank_card（先识别 phone/id_card，再在剩余文本识别 bank_card）

目标（v1.1）

✅ 词库入库（sensitive_words 表 + 4 词初始化）
✅ 隐私正则入库（privacy_patterns 表 + 4 正则初始化）
✅ 启动时从 DB 加载词库到内存（双轨：DB 为空 → 降级写死 4 词）
✅ 12 个管理 API（CRUD + 测试 + 审计 + 配置）
✅ 4 个管理 UI 子页（词库/正则/配置/审计）
✅ 命中审计日志（moderation_logs 表）
✅ 保留 v0.7.1 WARN 决策（不升级 BLOCK）

📥 输入项来源

#	输入项	路径	用途
1	关联 PRD	`docs/01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.0.md`	需求来源
2	关联技术方案	`docs/02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.0.md`	实现细节
3	关联测试用例	`docs/03-测试文档/03-功能测试用例/TC-通用-004-敏感词检测.md`	31 用例验收
4	v0.7.1 已上线服务源码	`src/backend/app/services/content_moderation_service.py`	当前实现基线
5	现有 pytest 15 用例	`src/backend/tests/test_content_moderation.py`	不破回归
6	看板验真测试报告 ⑤节	`docs/03-测试文档/04-版本测试报告/看板验真-测试报告-20260707.md`	历史基线
7	快速回复规则后台管理架构	`docs/01-产品文档/00-产品规划/PRD-REQ-通用-002-快速回复规则后台管理-v1.2.md`	后台 UI 架构参考
8	知识库迭代 §4 代答排除规则	`docs/02-技术文档/技术架构/技术方案-REQ-知识-001-知识库迭代-v1.0.md`	关键词匹配机制参考
9	Alembic 055 迁移（最新）	`src/backend/alembic/versions/055_add_quick_rules.py`	迁移模板
10	Init SQL 模板	`src/backend/scripts/init_quick_rules.sql`	应急数据脚本模板

📤 输出成果要求

1. 数据库（0.2d）

#	交付物	路径	说明
1.1	Alembic 056 迁移	`src/backend/alembic/versions/056_add_moderation_tables.py`	3 表 + 索引 + 序列 + 初始数据（4 词 + 4 正则）
1.2	Init SQL 应急脚本	`src/backend/scripts/init_moderation.sql`	Alembic 失败时手动执行（已写好，验证用）
1.3	4 模型类	`src/backend/app/models/sensitive_word.py` `src/backend/app/models/privacy_pattern.py` `src/backend/app/models/moderation_log.py`	SQLAlchemy ORM 模型
1.4	`__init__.py` 注册	`src/backend/app/models/__init__.py`	必须在 __init__.py 注册，否则 Alembic 检测不到（参考 055 教训）

2. 后端服务（0.4d）

#	交付物	路径	说明
2.1	重构内容审核服务	`src/backend/app/services/content_moderation_service.py`	双轨加载：DB 有数据 → 加载 DB；DB 空 → 降级写死 4 词。保留 v0.7.1 修复（数字边界 + 顺序调整）
2.2	敏感词管理服务	`src/backend/app/services/admin/sensitive_word_service.py`（新）	增删改查 + 批量导入 + 命中测试
2.3	隐私正则管理服务	`src/backend/app/services/admin/privacy_pattern_service.py`（新）	增删改查 + 正则测试器
2.4	审计日志查询服务	`src/backend/app/services/admin/moderation_log_service.py`（新）	分页查询 + 搜索过滤
2.5	命中动作配置服务	`src/backend/app/services/admin/moderation_config_service.py`（新）	GET/PUT 全局配置（v1.1 保留 WARN 不升级）
2.6	4 路由文件	`src/backend/app/api/admin/sensitive_words.py` `src/backend/app/api/admin/privacy_patterns.py` `src/backend/app/api/admin/moderation_logs.py` `src/backend/app/api/admin/moderation_config.py`	共 12 端点
2.7	main.py lifespan 钩子	`src/backend/app/main.py`	启动时调用 `load_moderation_words()` 加载 DB 词库
2.8	pytest 15 用例	`src/backend/tests/test_content_moderation.py`	已补：TC-202~207，15/15 通过（含 P0 延后项修复）

3. 前端 UI（0.3d）

#	交付物	路径	说明
3.1	API 封装	`src/frontend-admin/src/api/sensitiveWord.ts`	12 端点 + TypeScript 类型
3.2	词库管理页	`src/frontend-admin/src/views/admin/SensitiveWords.vue`	表格 + 增删改查 + 命中测试输入框
3.3	隐私正则页	`src/frontend-admin/src/views/admin/PrivacyPatterns.vue`	表格 + 正则测试器（实时匹配）
3.4	命中配置页	`src/frontend-admin/src/views/admin/ModerationConfig.vue`	severity 1-3 档可视化配置（v1.1 锁 WARN）
3.5	审计日志页	`src/frontend-admin/src/views/admin/ModerationLogs.vue`	分页 + 搜索（按 agent_id/action/时间）
3.6	路由注册	`src/frontend-admin/src/router/index.ts`	4 路由 + sidebar 菜单项
3.7	样式	复用快速回复规则后台卡片样式	避免重复设计

4. 部署与文档（0.1d）

#	交付物	路径	说明
4.1	部署 SOP	`docs/04-运维文档/部署运维/部署SOP-敏感词v1.1.md`	AST 校验 + jumpserver-V2 + alembic upgrade + restart + 验证
4.2	本任务说明书	`docs/07-项目管理/任务说明书/任务说明书-03-v1.1-敏感词词库入库+后台UI.md`	当前文档
4.3	任务 #81 状态更新	`docs/07-项目管理/任务说明书/IT智能服务台-项目管理主文档.md`	标 #81 部分完成（中文+号码修复 + bank_card 修复），v1.1 子任务完成

✅ 验证方式

单元测试

cd src/backend
pytest tests/test_content_moderation.py -v
# 期望：15 passed

数据库迁移验证

# 1. 升级迁移
alembic upgrade head
# 期望：无错误

# 2. 验证表创建
psql -d wecom_it_db -c "\dt sensitive_words"
psql -d wecom_it_db -c "\dt privacy_patterns"
psql -d wecom_it_db -c "\dt moderation_logs"
# 期望：3 表都存在

# 3. 验证初始数据
psql -d wecom_it_db -c "SELECT word, category, severity FROM sensitive_words WHERE is_active = TRUE"
# 期望：4 行（投诉我/你爱找谁找谁/自己不会百度吗/这点小事）

psql -d wecom_it_db -c "SELECT name, pattern FROM privacy_patterns WHERE is_active = TRUE"
# 期望：4 行（phone/id_card/bank_card/personal_email）

端到端测试（jumpserver-V2 部署后）

坐席端发消息命中 WARN（端到端必做）
- Mock 登录坐席
- 发送"自己不会百度吗"
- 期望：返回 WARN + matched_words 含该词
后台 UI CRUD（4 子页各做一次）
- 词库管理：增 → 查 → 改 → 删
- 隐私正则：增（带正则测试器）→ 查 → 改 → 删
- 命中配置：GET / PUT（验证仍锁 WARN）
- 审计日志：分页 + 搜索
降级兜底测试（关键）
- 临时清空 sensitive_words 表（UPDATE sensitive_words SET is_active = FALSE）
- 重启后端
- 期望：服务仍能审核（降级为写死 4 词）

灰度监控（上线后 24h）

指标	阈值	告警方式
词库加载日志	"Loaded N sensitive words from DB" 出现	应用日志（grep）
降级告警	"No sensitive words in DB, fallback to hardcoded" 不应出现	应用日志（告警）
命中率	0.5% < 命中率 < 5%（正常区间）	Prometheus（v1.1 加）
接口 P99	< 100ms	应用日志
异常率	< 0.1%	Prometheus

🎯 完成标准

必达项

pytest 15/15 通过（含 TC-202 中文+号码 P0 延后项）
Alembic 056 迁移成功（3 表 + 4 词 + 4 正则初始数据）
启动时从 DB 加载词库（Loaded 4 sensitive words from DB 日志）
DB 清空时降级为写死 4 词（业务不中断）
12 端点可访问（4 路由文件 + admin 权限校验）
4 前端子页可访问（路由 + sidebar 菜单）
命中动作仍锁 WARN（v0.7.1 决策保留，不升级 BLOCK）
审计日志写入 moderation_logs 表
上线后 24h 监控无 ERROR 日志

决策保留项（不达标但已接受）

命中动作可配置（v1.1 锁 WARN，v1.2 再考虑可配置化）
词库热加载（v1.1 仅启动加载，改词需重启；v1.2 加 60s 热加载）
词库导入导出（v1.1 仅手动增删；v1.2 加 CSV 导入）

跨任务铁律

修改 .py 后 AST 静态校验（防语法错误导致容器启动失败）
通过 jumpserver-V2 部署（不用 elFinder/base64 老通道）
本地 Windows 路径（D:\资料\...）和 ASCII 路径（D:\dev\wecom）两边都改
三处同步铁律：config.py 字段 + docker-compose.yml 注入 + .env.example 模板

⚠️ 风险与降级

风险	等级	降级措施
DB 切换导致服务挂掉	🟠 高	双轨加载：DB 加载失败/为空 → 自动降级写死 4 词（与 v0.7.1 行为一致）
Alembic 056 迁移失败	🟡 中	Init SQL 应急脚本（`scripts/init_moderation.sql`），手动执行
运营误删所有词	🟡 中	双轨降级：DB 词库为空时仍可用
正则改坏导致误报	🟡 中	UI 提供"正则测试器"，保存前必须看到命中结果
审计日志爆炸增长	🟢 低	30 天后归档（v1.2 加）
前端改路由导致 404	🟡 中	部署前本地 build 验证（`npm run build`）+ curl `/itadmin/sensitive-words` 200
多路径同步遗漏	🟠 高	部署前 diff 中文路径和 ASCII 路径，必须两边都改（工作记忆铁律）

回滚方案

# 1. 回滚 Alembic 迁移
alembic downgrade -1
# 删除 sensitive_words / privacy_patterns / moderation_logs 3 表

# 2. 代码回滚
docker restart wecom_it_backend  # v0.7.1 代码（已挂载卷，无需重建）
# content_moderation_service.py 双轨加载逻辑会检测到表不存在，降级写死 4 词

# 3. 前端回滚
# 用 dist-*.zip 旧版（保留至少 2 个）

📅 实施时间表（建议）

时段	工作	产出
Day 1 AM	数据库（056 迁移 + 4 模型 + init 注册）	3 表 + 4 词 + 4 正则
Day 1 PM	后端服务（重构 + 4 service + 4 路由）	12 端点 + 双轨加载
Day 2 AM	前端 UI（4 子页 + 路由 + API）	4 页面可访问
Day 2 PM	部署 + 验收（AST + jumpserver-V2 + E2E）	生产上线
Day 3	24h 监控 + 收尾	任务关闭

📎 关联文档

文档	位置
关联 PRD	`docs/01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.0.md`
关联技术方案	`docs/02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.0.md`
关联测试用例	`docs/03-测试文档/03-功能测试用例/TC-通用-004-敏感词检测.md`
看板验真测试报告	`docs/03-测试文档/04-版本测试报告/看板验真-测试报告-20260707.md`
快速回复规则 PRD（架构参考）	`docs/01-产品文档/00-产品规划/PRD-REQ-通用-002-快速回复规则后台管理-v1.2.md`
知识库迭代 §4（关键词匹配参考）	`docs/02-技术文档/技术架构/技术方案-REQ-知识-001-知识库迭代-v1.0.md`
当前服务源码	`src/backend/app/services/content_moderation_service.py`
当前测试源码	`src/backend/tests/test_content_moderation.py`
任务 #81（基础）	`docs/07-项目管理/任务说明书/任务说明书-01-新开发任务.md` §任务 6
项目管理主文档	`docs/07-项目管理/任务说明书/IT智能服务台-项目管理主文档.md`

🔄 变更日志

版本	日期	变更	变更人
v1.1	2026-07-28	首次创建：词库入库 + 后台 UI 任务说明书	宋献

14 KiB Raw Blame History Unescape Escape

任务说明书 03 — 敏感词检测 v1.1（词库入库 + 后台 UI）

📋 任务概览

🎯 任务背景

现状（v0.7.1）

目标（v1.1）

📥 输入项来源

📤 输出成果要求

1. 数据库（0.2d）

2. 后端服务（0.4d）

3. 前端 UI（0.3d）

4. 部署与文档（0.1d）

✅ 验证方式

单元测试

数据库迁移验证

端到端测试（jumpserver-V2 部署后）

灰度监控（上线后 24h）

🎯 完成标准

必达项

决策保留项（不达标但已接受）

跨任务铁律

⚠️ 风险与降级

回滚方案

📅 实施时间表（建议）

📎 关联文档

🔄 变更日志

14 KiB

Raw Blame History