Nexus/docs/audit/2026-06-08-script-exec-global-progress-board.md

审计 — 脚本执行全局进度与看板（2026-06-08）

Changelog: docs/changelog/2026-06-08-script-exec-global-progress-board.md、docs/changelog/2026-06-08-script-exec-complete-sound-setting.md

审计范围

模块	文件
异步执行	script_service.py
WS 通知	script_execution_notify.py、websocket.py
长任务回调	script_job_callback.py
Redis 进度	script_execution_store.py
Telegram	telegram/__init__.py、config.py
设置 API	settings.py
前端队列	useScriptExecutionQueue.ts、useWebSocket.ts、App.vue
提示音	scriptCompleteSound.ts、useScriptCompleteSound.ts、SettingsPage.vue
看板页	ScriptRunsPage.vue、router/index.ts
脚本库	ScriptsPage.vue
类型	types/api.ts
单测	test_script_execution_progress_stats.py
构建	web/app/index.html、index-DXg_pn7T.js（Vite 产物，Docker 内亦会 rebuild）
文档	.cursorrules、AGENTS.md、nexus-functional-development-guide.md

安全

项	结论
后台任务 DB 会话	独立 AsyncSessionLocal，请求结束不泄漏
WS 鉴权	复用 /ws/alerts JWT
Telegram	仅汇总 + 看板链接，无失败明细
提示音设置	script_exec_complete_sound 枚举白名单
CUD 审计	execute_started / execute_command 保留

Step 3 规则扫描

H	规则	结论
H1	exec API 不得阻塞至全批次结束	PASS asyncio.create_task + 立即返回
H2	后台异常须标记 failed	PASS _mark_execution_catastrophic_failure
H3	WS 消息须带 type 区分	PASS script_progress / script_complete
H4	Telegram 不得泄露 stderr 列表	PASS send_telegram_script_summary
H5	设置项须白名单校验	PASS SETTING_ENUM_VALIDATORS
H6	无静默吞错（通知层）	PASS logger.warning 记录 notify 失败

Closure

H	判定	依据
H1	PASS	_schedule_background_execution
H2	PASS	script_service._mark_execution_catastrophic_failure
H3	PASS	broadcast_script_progress/complete
H4	PASS	send_telegram_script_summary 无 failed_servers
H5	PASS	settings.py MUTABLE_KEYS + enum
H6	PASS	script_execution_notify.py try/except + warning

Step 8 DoD

• bash scripts/local_verify.sh 通过（test_api 26/26）
• pytest 脚本进度相关 15 条通过
• npm run build 通过
• changelog + 设计文档齐全
• 生产浏览器终验（用户）

测试证据

• tests/test_script_execution_progress_stats.py
• docs/reports/2026-06-08-script-exec-local-verify.md

残留风险（可接受）

• Docker 部署以镜像内 vite build 为准；仓库 web/app/assets 为辅助同步
• 多 worker WS 经 Redis pub/sub（与告警一致）