simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6be361fb63783520f5dcfd7cce386ac9b5523d4f
wecom_it_smart_desk/docs/07-项目管理/任务说明书/任务说明书-133-voice_asr-auth加固.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

7.4 KiB
Raw Blame History

任务说明书 133 — voice_asr.py POST /asr auth 加固（P0 安全巡检）

任务编号: 133 版本: v1.0 创建日期: 2026-08-03 完成日期: 2026-08-03 负责人: Duckula 优先级: 🔴 P0（安全巡检发现，连续 2 次标记） 类型: 安全加固（后端 + 测试 + 文档同步） 状态: ✅ 已完成（含 E2E 验证）

📋 任务概览

项目 内容
任务名 voice_asr.py POST /asr auth 加固
触发 P0 安全巡检：src/backend/app/api/voice_asr.py POST /asr 上传端点无 auth 依赖，连续 2 次标记
风险 🔴 高 — 任意用户可上传文件消耗存储或上传恶意文件；H5 端 PC/Mac 企微用户为真实生产调用方，未鉴权直接对外暴露
目标 加 Depends(get_current_user) + 大小上限 + Content-Type 白名单 + 审计日志
关联技术方案 docs/02-技术文档/技术架构/技术方案-REQ-AI-003-语音转文字-v1.1.md §10
关联源码 src/backend/app/api/voice_asr.py + src/backend/tests/test_voice_asr.py
估时 实际 ~1.5 h（含 403/404 部署排查 + 文档同步 + 部署）

🎯 任务背景

现状（巡检发现）

  • ✅ 已上线：src/backend/app/api/voice_asr.py 提供 POST /voice/asr 百度 ASR 端点
  • 🔴 无 auth 依赖：任意已登录用户均可调用，恶意用户可消耗百度 ASR 配额
  • 🔴 无大小限制：可上传任意大小文件导致 worker 阻塞（--workers 1）
  • 🔴 无 Content-Type 校验：恶意 payload 可直达百度 ASR
  • 🟡 无审计日志：无法追溯是谁在什么时间调了几次

调用方（修复前未识别清楚）

  • ❌ 曾被误判为"孤儿接口"——实际 H5 端 PC/Mac 企微用户每日调用此端点
  • ✅ H5 端采用"双策略自动切换"（手机企微 JS-SDK / PC/Mac 端企微 百度 ASR）
  • ✅ 详见技术方案 v1.1 §10.1

📥 输入项来源

# 输入项 路径 用途
1 关联技术方案 docs/02-技术文档/技术架构/技术方案-REQ-AI-003-语音转文字-v1.0.md → v1.1 §10 修复依据
2 关联源码（修复前） src/backend/app/api/voice_asr.py 当前实现
3 H5 端调用链 src/frontend-h5/src/components/chat/InputBar.vue:246-265 + src/frontend-h5/src/composables/useAudioRecorder.ts + src/frontend-h5/src/api/voice.ts 调用方验证
4 apiClient 拦截器 src/frontend-h5/src/api/index.ts:38-44 加 auth 兼容性确认
5 统一认证依赖 src/backend/app/dependencies/__init__.py (get_current_user) 复用现有依赖

📤 输出成果要求

代码改动（必须）

# 文件 改动
1 src/backend/app/api/voice_asr.py 加 Depends(get_current_user) 注入 current_user: UserInfo
2 src/backend/app/api/voice_asr.py 加 MAX_AUDIO_SIZE = 10 * 1024 * 1024 常量 + 大小校验
3 src/backend/app/api/voice_asr.py 加 ALLOWED_AUDIO_CONTENT_TYPES 白名单常量 + Content-Type 校验
4 src/backend/app/api/voice_asr.py 所有日志加 current_user.employee_id 审计字段

测试改动（必须）

# 文件 改动
5 src/backend/tests/test_voice_asr.py 加 from app.dependencies import UserInfo + _make_mock_user() helper
6 src/backend/tests/test_voice_asr.py 批量替换 13 处 transcribe_audio(mock_audio) → transcribe_audio(mock_audio, _make_mock_user())
7 src/backend/tests/test_voice_asr.py _make_mock_audio() 加 content_type="audio/pcm" 兼容白名单

文档同步（必须，避免下次同类误判）

# 文件 改动
8 docs/02-技术文档/技术架构/技术方案-REQ-AI-003-语音转文字-v1.0.md v1.0 → v1.1 + 头部变更记录 + §10 增量更新（7 个子节）
9 docs/05-运营文档/02-用户手册/手册-坐席端.md v1.0 → v1.1 + §5.4 修正错误描述（PC 端百度 ASR → 三环境矩阵）
10 docs/04-运维文档/运维指南/配置清单与环境变量.md BAIDU_ASR_* 加调用方说明 + 加 auth 验证命令
11 docs/00-产品开发流程与文档管理规范.md v1.12 → v1.13 + 新增 §16 增量更新章节治理（6 个子节）

🔧 验证方式

1. 单元测试（开发环境）

cd src/backend && python -m pytest tests/test_voice_asr.py -v
# 期望：16/16 PASS

2. 部署前静态检查

python -m py_compile src/backend/app/api/voice_asr.py
python -m py_compile src/backend/tests/test_voice_asr.py

3. 部署后服务端验证（容器内）

# 无 Token → 应拒绝（HTTP 403 FastAPI HTTPBearer 默认 / 401 get_current_user）
docker exec wecom_it_backend curl -X POST http://127.0.0.1:8000/voice/asr \
  -H "Content-Type: application/json" -d '{}'
# 期望：403 + {"detail":"Not authenticated"}

# 带错误 Token → 应返回 401
docker exec wecom_it_backend curl -X POST http://127.0.0.1:8000/voice/asr \
  -H "Authorization: Bearer fake-token" \
  -H "Content-Type: application/octet-stream" --data-binary "test"
# 期望：401

4. 端到端验证（用户实测）

  • ✅ 电脑端（PC Chrome/Edge 坐席工作台）→ Web Speech API 正常
  • ✅ 手机端（企微 WebView H5）→ 企微 JS-SDK 正常
  • ✅ 员工端（H5 PC/Mac 企微 WebView）→ 前端录音 + /voice/asr + 百度 ASR 正常
  • ✅ 坐席端（PC Chrome/Edge）→ Web Speech API 正常

✅ 完成标准

# 标准 状态
1 voice_asr.py 加 Depends(get_current_user) ✅
2 MAX_AUDIO_SIZE = 10MB 校验生效 ✅
3 ALLOWED_AUDIO_CONTENT_TYPES 白名单校验生效 ✅
4 日志含 current_user.employee_id ✅
5 测试 16/16 PASS ✅
6 技术方案 v1.0 → v1.1（+§10） ✅
7 运营手册 §5.4 修正 ✅
8 配置清单 BAIDU_ASR_* 调用方说明 ✅
9 规范 v1.12 → v1.13（+§16） ✅
10 jumpserver-V2 部署 + 健康检查 ✅
11 四端用户实测 E2E 通过 ✅

全部完成 ✅

📊 关键指标

指标 值
代码改动文件 2（voice_asr.py + test_voice_asr.py）
文档同步文件 4（技术方案 + 运营手册 + 配置清单 + 规范）
测试用例 16（全部 PASS）
部署耗时 ~12 min（含 403/404 排查）
E2E 验证 4 端全部通过
经验沉淀 MEMORY 4 条新铁律
规范新增章节 §16（6 个子节）

🔗 关联文档

  • 技术方案：docs/02-技术文档/技术架构/技术方案-REQ-AI-003-语音转文字-v1.1.md（v1.0 已升级，§10 增量更新）
  • 规范 v1.13：docs/00-产品开发流程与文档管理规范.md §16（增量更新治理）
  • daily log：docs/.workbuddy/memory/2026-08-03.md
  • 项目 MEMORY：docs/.workbuddy/memory/MEMORY.md（新增 4 条铁律）

⚠️ 后续治理（不影响本次闭环）

  1. 编号 REQ-AI-003 冲突：技术方案编号与产品 PRD-REQ-AI-003-多模态视觉理解 同号冲突 → 下次 AI 模块迭代时统一治理为 REQ-AI-009
  2. HTTPBearer 403 vs 401 统一：是否改为 401 取决于项目偏好；建议作为独立改进项
  3. 生产环境 E2E 录屏：建议录一段语音识别全流程作为回归测试素材

文档结束

Reference in New Issue View Git Blame Copy Permalink