simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c9c70422f658d5e00e1a6d0c36f2f08a222eaae9
wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-REQ-通用-004-敏感词检测-v1.1.1.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

238 lines
11 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.
# 任务说明书 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)]`，无显式豁免不得省略
Reference in New Issue View Git Blame Copy Permalink