# 任务说明书 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：源码级（编译层证据）

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

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

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

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

```bash
# 容器内 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）

- [x] PRD v1.1.1 已新建并归档 v1.0
- [x] 技术方案 v1.1.1 已新建并归档 v1.0
- [x] 任务说明书 v1.1.1 已新建（旧名 v1.1 已归档）
- [x] 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)]`，无显式豁免不得省略