# 2026-05-30 — 全站 ruff 清零

## 日期
2026-05-30

## 变更摘要
全站 ruff 代码质量扫描从 77 个错误清零到 0，同时修复 3 个实际 bug。

## 动机
全站巡检发现 server/ 目录有 77 个 ruff 错误，其中 6 个 F821（未定义变量）会导致运行时 NameError。

## 涉及文件（21 个）

| 文件 | 变更类型 | 说明 |
|------|----------|------|
| server/api/install.py | bug fix | site_url 变量在定义前使用 → 移到函数开头；移除未使用 hashlib 导入 |
| server/api/sync_v2.py | bug fix | 缺少 `import os` 导致对比功能 NameError |
| server/application/services/script_jobs.py | bug fix | `${LOG}` 在 f-string 中触发 Python 变量查找 → 改为普通字符串 |
| server/api/auth.py | 质量 | 移除未使用 ip_address 变量 |
| server/api/scripts.py | 质量 | 移除未使用导入 |
| server/api/settings.py | 质量 | 5 个 B904 raise from 修复 |
| server/api/websocket.py | 质量 | S110 noqa |
| server/api/webssh.py | 质量 | 10 个 S110 noqa (SSH 清理) |
| server/application/services/auth_service.py | 质量 | S105 noqa (Redis key prefix) |
| server/application/services/sync_engine_v2.py | 质量 | 移除未使用导入 |
| server/background/heartbeat_flush.py | 质量 | 移除未使用导入 |
| server/background/schedule_runner.py | 质量 | F541 f-string 修正 |
| server/background/script_execution_flush.py | 质量 | B023 循环变量绑定修复 |
| server/background/self_monitor.py | 质量 | F541 f-string 修正 |
| server/domain/models/__init__.py | 质量 | 移除 4 个未使用导入 |
| server/domain/repositories/__init__.py | 质量 | 移除未使用 Dict 导入 |
| server/infrastructure/database/admin_repo.py | 质量 | 移除未使用 List 导入 |
| server/infrastructure/database/migrations.py | 质量 | 移除未使用导入 |
| server/infrastructure/redis/client.py | 质量 | B904 raise from |
| server/infrastructure/ssh/asyncssh_pool.py | 质量 | S110 noqa + B007 变量重命名 |
| server/infrastructure/subscription_parser.py | 质量 | S110 noqa |

## 关键 Bug 修复

### 1. install.py site_url NameError
- **问题**: `site_url` 在第 472 行使用但第 499 行才定义 → 安装向导初始化数据库会崩溃
- **修复**: 将 `site_url` 计算移到函数开头（redis_url 之后）

### 2. sync_v2.py os 未导入
- **问题**: 对比功能（文件 diff）使用 `os.path` 但未导入 `os`
- **修复**: 在函数内添加 `import os`

### 3. script_jobs.py f-string 陷阱
- **问题**: `f'echo $! > "${LOG}.pid"'` 中 `${LOG}` 被 Python 解释为变量查找
- **修复**: 改为普通字符串 `'echo $! > "${LOG}.pid"'`

## 是否需迁移
否

## 是否需重启
是 — 已部署

## 验证方式
- ruff: ✅ All checks passed (77 → 0)
- bandit: ✅ 0 HIGH, 15 MEDIUM (B108+B104 低风险)
- import: ✅
- 健康检查: ✅ ok

## Commit
32feb1b