61 lines
3.2 KiB
Markdown
61 lines
3.2 KiB
Markdown
|
# 2026-05-29 推送页面迭代 Round 2 — 5 项功能
|
|||
|
|
|
|||
|
|
## 变更摘要
|
|||
|
|
1. F1: 失败自动重试 — 推送失败自动创建重试任务，行内"🔄 重试"按钮
|
|||
|
|
2. F2: 服务器在线状态标识 — 服务器列表显示🟢/🔴在线状态
|
|||
|
|
3. F3: 推送完成 Telegram 通知 — 推送完成/部分失败发 Telegram 消息含详情
|
|||
|
|
4. F4: 文件内容预览 — 文件管理器点击文件名预览内容
|
|||
|
|
5. F5: 同步模式详细说明 — 每种模式下方显示说明文字
|
|||
|
|
|
|||
|
|
## 动机
|
|||
|
|
推送页面 Round 1 完成后，实际使用中发现：推送失败需手动切页重试、无法识别服务器在线状态、推送完成无即时通知、文件管理器无法预览内容、同步模式含义不明确。
|
|||
|
|
|
|||
|
|
## 涉及文件
|
|||
|
|
|
|||
|
|
### 后端
|
|||
|
|
- `server/application/services/sync_engine_v2.py` — 推送失败自动创建 PushRetryJob + Telegram 通知
|
|||
|
|
- `_sync_one()`: 失败时创建 PushRetryJob，记录 retry_job_id
|
|||
|
|
- `sync_files()`: 完成后调用 `send_telegram_sync_complete()`
|
|||
|
|
- 返回 dict 新增 `retry_job_ids`
|
|||
|
|
- `server/api/websocket.py` — `broadcast_sync_progress()` 新增 `retry_job_id` 参数
|
|||
|
|
- `server/infrastructure/telegram/__init__.py` — 新增 `send_telegram_sync_complete()` 函数
|
|||
|
|
- 参数: completed, failed, total, source_path, operator, failed_servers, duration_seconds
|
|||
|
|
- 全部成功🟢/部分失败🟡/全部失败🔴 不同消息格式
|
|||
|
|
- `server/api/sync_v2.py` — 新增 `POST /api/sync/local-file-preview` 端点
|
|||
|
|
- 安全: `os.path.realpath()` + `startswith("/tmp/nexus_upload_")` 校验
|
|||
|
|
- 限制: 仅文件 + 最多 4KB + base64 编码 + encoding_hint
|
|||
|
|
- 审计日志
|
|||
|
|
- `server/api/schemas.py` — 新增 `LocalFilePreview` 模型
|
|||
|
|
|
|||
|
|
### 前端
|
|||
|
|
- `web/app/push.html` — 全面改造
|
|||
|
|
- F1: WS 消息处理 `updateProgressFromWS()` 失败行显示"🔄 重试"按钮 + `retryServer()` 函数
|
|||
|
|
- F1: HTTP 响应 `updateProgressFromResult()` 同样显示重试按钮 + `_retryJobMap` 映射
|
|||
|
|
- F2: `filterServers()` 服务器选项加🟢/🔴在线状态标识
|
|||
|
|
- F4: `renderFileManager()` 文件名可点击 + `previewLocalFile()` 预览函数 + 模态框
|
|||
|
|
- F5: 同步模式下方 `<div id="syncModeDesc">` 说明文字 + `onSyncModeChange()` 更新
|
|||
|
|
|
|||
|
|
### 设计/技术文档
|
|||
|
|
- `docs/design/specs/2026-05-29-push-round2-design.md` — 设计文档
|
|||
|
|
- `docs/design/plans/2026-05-29-push-round2.md` — 技术文档
|
|||
|
|
|
|||
|
|
## 安全影响
|
|||
|
|
- F1 (重试): 利用已有 `/api/retries/{id}/retry` 端点，JWT 认证 + 审计日志
|
|||
|
|
- F3 (Telegram): `source_path` 经 `sanitize_external_message()` 脱敏
|
|||
|
|
- F4 (预览): `os.path.realpath()` + `startswith("/tmp/nexus_upload_")` 双重校验 + 4KB 限制
|
|||
|
|
- 所有新端点需 JWT 认证 + 审计日志
|
|||
|
|
|
|||
|
|
## 需要迁移/重启
|
|||
|
|
- 是：后端 Python 需重启（supervisorctl restart nexus）
|
|||
|
|
- 否：无数据库 schema 迁移
|
|||
|
|
|
|||
|
|
## 验证方式
|
|||
|
|
1. F5: 切换同步模式 → 下方说明文字正确更新
|
|||
|
|
2. F2: 服务器列表 → 在线🟢、离线🔴标识
|
|||
|
|
3. F1: 推送失败 → 行内"🔄 重试"按钮 → 点击重试
|
|||
|
|
4. F3: 推送完成 → Telegram 收到通知含详情
|
|||
|
|
5. F4: 上传 ZIP → 点击文件名 → 弹出预览框
|
|||
|
|
|
|||
|
|
## 进度条
|
|||
|
|
☑实现 ☐WSL验证 ☐审计8步 ☐部署 ☐健康检查 ☐浏览器验证 ☐changelog
|