Nexus Agent
dfb0ea2d8f
修复 ScriptsPage 执行契约（script_id/command、历史过滤、长任务/凭据）及 SchedulesPage 缺失能力（target_path、next_run、push/script、cron/once、sync_mode）；后端补迁移与 schedule_runner 传参。
45 lines
2.0 KiB
Markdown
45 lines
2.0 KiB
Markdown
# 2026-06-07 — 推送调度对齐设计文档
|
||
|
||
## 摘要
|
||
|
||
修复推送调度 SPA 与后端契约断裂：`target_path` 未持久化、`schedule_runner` 未传递目标路径、`next_run` 恒为空；补全调度类型（push/script）、运行模式（cron/once）、同步模式与脚本调度 UI。
|
||
|
||
## 动机
|
||
|
||
- 前端表单有「目标路径」但未提交，DB 无 `target_path` 列，`runNow` 错误默认 `/tmp`
|
||
- 设计文档（附录 E.1）要求 source/target + sync_mode 或 script_id，旧版 SPA 仅支持 cron 推送
|
||
- 表格「下次运行」无 API 计算，用户无法判断调度是否生效
|
||
|
||
## 涉及文件
|
||
|
||
| 层 | 文件 |
|
||
|----|------|
|
||
| 模型 | `server/domain/models/__init__.py` — `PushSchedule.target_path` |
|
||
| 迁移 | `server/infrastructure/database/migrations.py`, `server/api/install.py` |
|
||
| Schema | `server/api/schemas.py` — `ScheduleCreate/Update.target_path` |
|
||
| API | `server/api/settings.py` — `_schedule_to_dict` + `next_run` |
|
||
| Runner | `server/background/schedule_runner.py` — 传 `target_path`、`compute_schedule_next_run` |
|
||
| 前端 | `frontend/src/pages/SchedulesPage.vue`, `frontend/src/types/api.ts` |
|
||
| 测试 | `tests/test_schedule_next_run.py` |
|
||
|
||
## 是否需迁移/重启
|
||
|
||
- **是**：`push_schedules.target_path` 列（启动时 `run_schema_migrations` 自动 ADD）
|
||
- **需重启 API** 以加载新代码；前端需 `vite build` 后部署
|
||
|
||
## 验证方式
|
||
|
||
```bash
|
||
bash scripts/local_verify.sh
|
||
python -m pytest tests/test_schedule_next_run.py tests/test_schedule_runner_once.py -q
|
||
```
|
||
|
||
- 新建 cron 推送调度，填写可选目标路径 → 列表显示 target_path、next_run
|
||
- `runNow` 留空目标路径 → 走各机 `servers.target_path`（与推送页一致）
|
||
- 新建 script 调度 → `schedule_runner` 调 ScriptService
|
||
|
||
## 行为说明
|
||
|
||
- **目标路径留空**：与推送页相同，各服务器使用「服务器管理」中的 `target_path`；未配置则 sync 引擎 fallback `/tmp/sync`
|
||
- **一次性调度**：`fire_at` 到期后 runner 执行一次并 `enabled=false`；失败时 rollback 恢复 enabled
|