wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-REQ-通用-004-敏感词检测-v1.1.1.md

任务说明书 v1.1.1 — REQ-通用-004 敏感词检测 v1.1.1（鉴权安全补漏）

任务编号: v1.1.1 增量（v1.1 安全补丁 / PATCH 级别） 需求编号: REQ-通用-004 版本: v1.1.1 创建日期: 2026-08-05 作者: 宋献 / Duckula 关联 PRD: docs/01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.1.1.md 关联技术方案: docs/02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.1.1.md 关联测试用例: docs/03-测试文档/03-功能测试用例/TC-通用-004-敏感词检测.md（追加 §10 鉴权章节） 关联缺陷单: docs/03-测试文档/05-缺陷单/BUG-通用-004-敏感词API无鉴权-001.md 关联整改记录: docs/04-运维文档/部署运维/00-文档规范化整改记录.md（#5 整改） 关联源码:

• src/backend/app/api/admin/sensitive_words.py（本次唯一修改文件）
• src/backend/app/api/admin_api.py:50（复用 require_admin 定义）
• src/backend/tests/test_sensitive_words_auth.py（新增鉴权测试 6 条） 基础版本: v1.1（已上线，词库入库 + 后台 UI + 审计日志；实施时漏加鉴权） 前置归档:
• PRD v1.0 → PRD-REQ-通用-004-敏感词检测-v1.0.archive.md
• 技术方案 v1.0 → 技术方案-REQ-通用-004-敏感词检测-v1.0.archive.md
• 任务说明书 v1.1（命名错误）→ 任务说明书-03-v1.1-敏感词词库入库+后台UI.v1.1.archive.md

---

📋 任务概览

项目	内容
任务名	敏感词检测 v1.1.1 — v1.1 安全补漏（13 端点鉴权修复）
目标	给 src/backend/app/api/admin/sensitive_words.py 的 APIRouter 加 dependencies=[Depends(require_admin)]，13 端点全覆盖恢复 admin-only 访问
优先级	🔴 P0-Critical（合规/安全漏洞，详见 BUG-通用-004）
类型	Bug 修复 + 文档规范化（双维度）
估时	30 min（2 行代码 + 6 条测试 + 端到端 curl 验证 + 文档同步）
阻塞项	无（独立部署，与 v1.2 AI 化草案解耦）
风险等级	🟢 低（一行回滚即可，无 DB 迁移）

---

🎯 任务背景

现状（v1.1）

• ✅ v1.1 已上线（2026-07-28）：词库入库 + 后台 UI + 审计日志
• ✅ 13 个 admin 端点落地
• ❌ 13 端点全部裸奔（v1.1 实施漏加 Depends(require_admin)）
• ❌ 技术方案 v1.0 §6.3 已规定 admin 权限但实施未执行
• ❌ TC-通用-004 31 条用例无鉴权维度

目标（v1.1.1）

• ✅ APIRouter 加 dependencies=[Depends(require_admin)]
• ✅ 13 端点全部要求 agent.role == "admin"
• ✅ 非 admin 调用统一 403 + code:1004 无管理权限
• ✅ 新增 6 条鉴权测试用例（TC-通用-004 §10）
• ✅ BUG-通用-004 状态由"待修复"→"已关闭"
• ✅ 整改记录 #5 追加
• ✅ PRD / 技术方案 / 任务说明书 v1.1.1 全部到位

不在本任务范围（明确划清）

• ❌ operator_id 审计字段（列入 v1.1.2 或 v1.2）
• ❌ 正则复杂度限制（列入 v1.1.2）
• ❌ AI 辅助运营（v1.2 草案，独立演进，不阻塞）

---

📥 输入项来源

#	输入项	路径	用途
1	关联 PRD	docs/01-产品文档/00-产品规划/PRD-REQ-通用-004-敏感词检测-v1.1.1.md	需求来源（PATCH 级别）
2	关联技术方案	docs/02-技术文档/技术架构/技术方案-REQ-通用-004-敏感词检测-v1.1.1.md	实现细节（含根因定位 + 修复方案）
3	关联缺陷单	docs/03-测试文档/05-缺陷单/BUG-通用-004-敏感词API无鉴权-001.md	触发任务，复现步骤 + 修复方案
4	关联整改记录	docs/04-运维文档/部署运维/00-文档规范化整改记录.md	#5 整改索引
5	关联测试用例	docs/03-测试文档/03-功能测试用例/TC-通用-004-敏感词检测.md	加 §10 鉴权章节
6	需了解的现有代码	src/backend/app/api/admin/sensitive_words.py	本次唯一修改文件
7	需了解的现有代码	src/backend/app/api/admin_api.py:50-66	require_admin 函数定义（复用，不重写）
8	需了解的现有代码	src/backend/app/api/admin_roles.py 等 6 个文件	同类已加鉴权实现（对照参考）
9	命名规范	docs/00-产品开发流程与文档管理规范.md v1.9 § 11	文档命名 + 版本对齐铁律

---

📤 输出成果要求

A. 代码改动（必交）

#	文件	变更
A1	src/backend/app/api/admin/sensitive_words.py	顶部 imports 新增 from app.api.admin_api import require_admin
A2	src/backend/app/api/admin/sensitive_words.py	L44 APIRouter 加 dependencies=[Depends(require_admin)]
A3	src/backend/tests/test_sensitive_words_auth.py	新增 6 条鉴权测试

B. 文档改动（必交）

#	文档	状态
B1	PRD-REQ-通用-004-敏感词检测-v1.1.1.md	✅ 已新建
B2	技术方案-REQ-通用-004-敏感词检测-v1.1.1.md	✅ 已新建
B3	任务说明书-REQ-通用-004-敏感词检测-v1.1.1.md	✅ 本文件
B4	PRD-REQ-通用-004-敏感词检测-v1.0.md	✅ 已归档为 .v1.0.archive.md
B5	技术方案-REQ-通用-004-敏感词检测-v1.0.md	✅ 已归档为 .v1.0.archive.md
B6	任务说明书-03-v1.1-敏感词词库入库+后台UI.md	✅ 已归档为 .v1.1.archive.md（修正命名违规）
B7	TC-通用-004-敏感词检测.md	⏳ 加 §10 鉴权章节（6 用例）
B8	BUG-通用-004-敏感词API无鉴权-001.md	✅ 已新建
B9	00-文档规范化整改记录.md	⏳ 追加 #5 整改记录

C. 部署产物（必交）

#	项	状态
C1	后端镜像重启（docker compose restart backend）	待执行
C2	容器内端到端 curl 验证三组证据（无 token / agent / admin）	待执行
C3	源码 grep 验证（grep require_admin sensitive_words.py）	待执行
C4	pytest 6 条新用例全通过	待执行

---

🔧 验证方式

验证 1：源码级（编译层证据）

grep -n "require_admin" src/backend/app/api/admin/sensitive_words.py
# 预期：至少 2 行（1 处 import + 1 处 dependencies 引用）

验证 2：自动化测试（单元层证据）

cd src/backend
pytest tests/test_sensitive_words_auth.py -v
# 预期：6 条用例全部通过

验证 3：容器内端到端（部署层证据，按 deploy-troubleshoot 铁律）

# 容器内 grep 验证（容器 ≠ 源码 ≠ 宿主残留目录，必须在容器核对）
docker compose exec backend grep -n "require_admin" app/api/admin/sensitive_words.py

# 普通坐席 token 调用 13 端点 → 全部 403
TOKEN_AGENT="<普通坐席 token>"
for path in /api/admin/sensitive-words /api/admin/sensitive-words/test /api/admin/sensitive-words/reload /api/admin/privacy-patterns /api/admin/moderation-logs /api/admin/moderation-logs/stats /api/admin/moderation-config; do
    echo "GET $path:"
    curl -sS -X GET "http://localhost:8000$path" \
      -H "Authorization: Bearer $TOKEN_AGENT" -w "\nHTTP %{http_code}\n"
done
# 预期：全部 HTTP 403 + code:1004

# admin token 调用 13 端点 → 全部 200
TOKEN_ADMIN="<admin token>"
# 同上循环，预期全部 HTTP 200

验证 4：业务层回归（不破坏既有功能）

• 坐席发送消息触发审核流程 → 仍 WARN
• admin 词库管理 UI → 仍可增删改查
• TC-通用-004 既有 23/31 通过用例不变

---

✅ 完成标准

必达项（P0-Critical）

• PRD v1.1.1 已新建并归档 v1.0
• 技术方案 v1.1.1 已新建并归档 v1.0
• 任务说明书 v1.1.1 已新建（旧名 v1.1 已归档）
• BUG-通用-004-001 缺陷单已新建
• 源码 2 行变更落地（sensitive_words.py）
• pytest 6 条鉴权用例全通过
• 容器内端到端 curl 三组证据齐全
• TC-通用-004 §10 鉴权章节已追加
• 整改记录 #5 已追加
• BUG-通用-004 状态变更为"已关闭"
• commit message 含 [BUG-通用-004]

回归项（P1）

• 13 端点 admin 调用仍返回 200
• 坐席发送消息审核流程不变
• TC-通用-004 既有 23 通过用例不变

文档铁律合规（按 spec §11 强制）

• PRD 文件名 = 内容版本号 = v1.1.1
• 技术方案文件名 = 内容版本号 = v1.1.1
• 任务说明书文件名 = 内容版本号 = v1.1.1
• 三件套版本号对齐（v1.1.1）
• 子任务归档规范（旧 v1.1 改 .v1.1.archive.md）

---

📅 任务分解（WBS）

#	任务	耗时	状态
1	创建 BUG-通用-004-001 缺陷单	5 min	✅ 完成
2	创建 PRD v1.1.1 + 归档 v1.0	10 min	✅ 完成
3	创建技术方案 v1.1.1 + 归档 v1.0	10 min	✅ 完成
4	归档任务说明书 v1.1 + 新建 v1.1.1	5 min	✅ 完成
5	TC-通用-004 加 §10 鉴权章节（6 用例）	10 min	⏳ 待执行
6	改 sensitive_words.py（2 行）	2 min	⏳ 待执行
7	新增 test_sensitive_words_auth.py（6 条）	10 min	⏳ 待执行
8	pytest 6 条新用例全通过	2 min	⏳ 待执行
9	容器内端到端 curl 验证（3 组证据）	10 min	⏳ 待执行
10	整改记录追加 #5	3 min	⏳ 待执行
11	BUG-通用-004 状态变更 + commit	3 min	⏳ 待执行
总计		~70 min	4/11 完成

---

🔄 关联与依赖

关联项	关系	备注
v1.2 AI 化草案	独立	不互相阻塞，可任意顺序部署
v1.1.2（operator_id 审计）	后续	同一漏洞面但不同维度，列入下次迭代
整改记录 #5	本任务产出	同步推进
BUG-通用-004	本任务触发	完成后关闭

---

📝 变更日志

版本	日期	变更	变更人
v1.1.1	2026-08-05	首次创建（PATCH 级别鉴权补漏）	宋献 / Duckula

---

关键决策：

• 本任务按 spec.md §3.1 PATCH 级别定义（修复性调整）
• 命名按 spec.md §4.1 任务说明书正则 ^任务说明书-.*\.md$，修正 v1.1 旧命名（任务说明书-03-...）为新规范命名（任务说明书-REQ-通用-004-...）
• 旧名归档按 spec.md §11.5 铁律 4（.v{X}.archive.md 后缀）
• 本任务独立部署，不阻塞 v1.2 AI 化草案
• 强制规范沉淀（写入 MEMORY 候选）：任何 APIRouter(prefix="/admin", ...) 必须声明 dependencies=[Depends(require_admin)]，无显式豁免不得省略