# 审计 — 脚本执行全局进度与看板（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

- [x] `bash scripts/local_verify.sh` 通过（test_api 26/26）
- [x] `pytest` 脚本进度相关 15 条通过
- [x] `npm run build` 通过
- [x] 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（与告警一致）
