diff --git a/docs/changelog/2026-06-07-alignment-backlog-plan.md b/docs/changelog/2026-06-07-alignment-backlog-plan.md new file mode 100644 index 00000000..d52902ea --- /dev/null +++ b/docs/changelog/2026-06-07-alignment-backlog-plan.md @@ -0,0 +1,23 @@ +# Changelog — 缺失功能对齐计划 + +**日期**：2026-06-07 + +## 摘要 + +新增 `docs/design/plans/2026-06-07-missing-features-alignment-plan.md`，将相对功能 SSOT 的缺口、待部署项、API 无 UI、产品 backlog 与验收工程债共 **31 项**逐项编号（A～E），含优先级、验收标准与推荐排期。 + +## 动机 + +用户要求计划任务清单；避免与 `dfb0ea2` 已修复项（脚本库/调度）及已实现误报（WebSSH 自动重连、CSV 导入、文件预览）重复排期。 + +## 涉及文件 + +- `docs/design/plans/2026-06-07-missing-features-alignment-plan.md`（新建） + +## 迁移 / 重启 + +无 + +## 验证 + +打开计划文档，按 ID 勾选进度总表。 diff --git a/docs/changelog/2026-06-07-alignment-plan-phase1.md b/docs/changelog/2026-06-07-alignment-plan-phase1.md new file mode 100644 index 00000000..4b53cd75 --- /dev/null +++ b/docs/changelog/2026-06-07-alignment-plan-phase1.md @@ -0,0 +1,33 @@ +# Changelog — 对齐计划 Phase 1（B-01/B-04/B-05 + 文档） + +**日期**：2026-06-07 + +## 摘要 + +按 `docs/design/plans/2026-06-07-missing-features-alignment-plan.md` 实施首批 P1 项：Commands 推送日志第三视图、CSV 导入静态模板、功能指南 §12.6/12.8/12.10 与附录 E.1 扩写；`acceptance_catalog` 与 E2E 用例同步。 + +## 动机 + +计划 Week 1 优先项；旧版 `commands.html` 三视图在 SPA 缺推送日志；导入对话框链接的模板文件不存在。 + +## 涉及文件 + +- `frontend/src/pages/CommandsPage.vue` — 推送日志视图 + status/sync_mode/trigger 筛选 +- `web/app/servers_import_template.csv` — 静态模板（与 `GET /servers/import/template` 列一致） +- `frontend/src/pages/ServersPage.vue` — 模板说明 +- `docs/project/nexus-functional-development-guide.md` — §12.6/12.8/12.10 +- `docs/project/nexus-functional-development-guide-appendix.md` — E.1 +- `tests/acceptance_catalog.py` +- `frontend/e2e/full-acceptance.spec.mjs` + +## 迁移 / 重启 + +- 仅前端静态 + 文档；`vite build` 后部署 `web/app/` + +## 验证 + +```bash +cd frontend && npx vite build +# Commands #/commands → 推送日志视图 → 筛选器可见、表格加载 +# Servers 导入对话框 → 下载模板 CSV 200 +``` diff --git a/docs/design/plans/2026-06-07-missing-features-alignment-plan.md b/docs/design/plans/2026-06-07-missing-features-alignment-plan.md new file mode 100644 index 00000000..3480dbdf --- /dev/null +++ b/docs/design/plans/2026-06-07-missing-features-alignment-plan.md @@ -0,0 +1,197 @@ +# Nexus 6.0 — 缺失功能对齐计划（Backlog） + +**日期**：2026-06-07 +**基线**：`docs/project/nexus-functional-development-guide.md` §12 + 附录 E/J · `dfb0ea2`（脚本库+调度已 push） +**对照审计**：`docs/reports/2026-06-06-frontend-14p-contract-audit.md` +**用途**：逐项排期、勾选验收；**禁止**与已完成项重复实现。 + +--- + +## 0. 总览 + +| 类别 | 项数 | 说明 | +|------|------|------| +| **A 待部署/生产验证** | 4 | 代码已在 Gitea，生产未生效或未点验 | +| **B 14 页 SPA 能力缺口** | 6 | 相对功能 SSOT / 旧版 HTML 仍缺 UI 或细节 | +| **C 后端有 API、前端无页** | 4 | Sync/Assets 等 API 已存在 | +| **D 产品增强（P1/P2/可选）** | 5 | 非 14 页核心，但 backlog 仍列 | +| **E 验收与工程债** | 12 | L4/L5、POSIX、ENH、文档 SSOT | +| **合计可排期项** | **31** | 不含「已否决」功能 | + +**14 页 API 路径层**：2026-06-06 审计 **PASS**（端点存在 ≠ 能力完整）。 + +**已否决（不做，勿排期）**：RBAC、移动端、会话录像、审计 CSV 导出、邮件报告、Redis Cluster、独立文件编辑器模块。 + +--- + +## A. 待部署与生产验证（优先） + +> 代码已合入 `main@dfb0ea2`，**不算功能缺失**，但必须上线后才算对齐完成。 + +| ID | 任务 | 优先级 | 状态 | 涉及 | 验收标准 | +|----|------|--------|------|------|----------| +| A-01 | **生产部署** `dfb0ea2`（API + 前端静态） | P0 | ☐ | `deploy/deploy-production.sh` | 生产 `git pull` 后 API 重启；`web/app/` 同步；`/health` 200 | +| A-02 | **DB 迁移** `push_schedules.target_path` | P0 | ☐ | `migrations.py` 启动时 DDL | 生产 `SHOW COLUMNS FROM push_schedules LIKE 'target_path'` 有列 | +| A-03 | **脚本库**生产点验 | P0 | ☐ | ScriptsPage + `/scripts/exec` | 新建 ops 脚本 → 选机执行 → 状态条 #id；历史按 script_id 过滤；长任务/凭据可用 | +| A-04 | **推送调度**生产点验 | P0 | ☐ | SchedulesPage + `schedule_runner` | 新建 cron 推送：target_path 可选、next_run 有值、runNow 留空目标走各机配置；script 调度 runNow 走 `/scripts/exec` | +| A-05 | **边端 Agent** 401 停循环 | P1 | ☐ | `web/agent/agent.py` | 错误 key 心跳 401 后子机 agent 不再无限重试（需各机同步 agent 文件） | + +**依赖**：A-01 → A-02 → A-03/A-04 可并行点验。 + +--- + +## B. 十四页 SPA — 相对设计 SSOT 的能力缺口 + +| ID | 页面 | 缺失能力 | 优先级 | 状态 | 设计依据 | 验收标准 | +|----|------|----------|--------|------|----------|----------| +| B-01 | **Commands** `/commands` | **推送日志视图**（第三 Tab：rsync 历史、状态/模式/触发源过滤） | P1 | ☐ | 旧版 `commands.html` 三视图；现 SPA 仅命令+会话 | 第三视图可调 `GET /servers/logs` 或 sync_logs 分页 API；筛选与 Push 历史一致 | +| B-02 | **Dashboard** `/` | **历史趋势图**（CPU/内存/磁盘时序，非仅 Redis 实时） | P2 | ☐ | `nexus-full-site-features.md` §23 | 至少 24h 折线图；数据来自 MySQL 历史或现有 heartbeat 落库 | +| B-03 | **Files** `/files` | **树形侧栏**目录导航 | P3 | ☐ | 归档 §12 文件管理「未实现：树形侧栏」 | 左树右表；与 browse API 联动 | +| B-04 | **Servers** `/servers` | **CSV 导入模板**静态文件缺失 | P2 | ☐ | UI 链到 `/app/servers_import_template.csv` 但仓库无此文件 | 提供模板 CSV + 文档列说明；导入 E2E 一条 | +| B-05 | **Schedules** `/schedules` | **设计文档 §12.8 扩写**（push/script、cron/once 已代码实现） | P2 | ☐ | 功能指南仍只写一行「Cron 调度推送」 | 更新 SSOT 与附录 E.1 字段表；避免下轮误判缺失 | +| B-06 | **Settings** `/settings` | **子机 Agent 批量同步入口**（若运维需要一键提示） | P3 | ☐ | 边端 A-05 依赖人工 scp | 文档或设置页展示 agent 升级/同步命令（非必须新 API） | + +**说明（勿重复做）**： + +- **WebSSH 断线自动重连**：`useTerminalSessions.ts` 已实现指数退避重连 → 归档 §23 过时，仅需 **生产验证**，不新开 B 项。 +- **CSV 批量导入**：`ServersPage` + `POST /servers/import` **已实现** → 仅 B-04 补模板。 +- **文件内容预览**：`FilesDialogs.vue` preview **已实现** → 不列入缺口。 +- **脚本库 / 调度**：B 类无缺口；归 **A-03/A-04 部署验证**。 + +--- + +## C. 后端 API 已有、前端无独立页面 + +| ID | API 模块 | 端点（示例） | 缺失 UI | 优先级 | 状态 | 验收标准 | +|----|----------|--------------|---------|--------|------|----------| +| C-01 | **资产管理** | `GET/POST/PUT/DELETE /api/assets/platforms` | 无 `#/assets` 页；Platform/Node 仅在服务器表单下拉只读 | P2 | ☐ | 独立页或 Settings 子 Tab：Platform/Node CRUD + 审计 | +| C-02 | **Sync 配置推送** | `POST /api/sync/config`、`/config/rollback` | 无配置批量下发 UI | P2 | ☐ | 选服务器 + key/value 或文件；回滚一次操作 | +| C-03 | **Sync 批量命令** | `POST /api/sync/commands` | 无独立页（脚本库部分覆盖） | P3 | ☐ | 与 Scripts 边界写清：临时命令 vs 入库脚本 | +| C-04 | **Sync SFTP** | `POST /api/sync/sftp` | 文件页 upload 走 `/sync/upload`，SFTP 专用流未暴露 | P3 | ☐ | 文档明确等价路径或补 UI | + +--- + +## D. 产品 Backlog（非 14 页核心） + +| ID | 功能 | 优先级 | 状态 | 说明 | 验收标准 | +|----|------|--------|------|------|----------| +| D-01 | **Agent upgrade 与 install.sh venv 对齐** | P1 | ☐ | `upgrade-agent` API 已有；需与 `web/agent/install.sh` 路径/venv 一致 | 升级后 agent 版本与中心一致；install 脚本 idempotent | +| D-02 | **宝塔 API 监控集成** | 可选 | ☐ | 可选增强 | 设计文档 + 配置项 + 只读指标 | +| D-03 | **Agent mTLS** | 可选 | ☐ | 安全增强 | ADR + 双端证书轮换方案 | +| D-04 | **全局搜索**增强 | P3 | ☐ | `App.vue` 已有 `/search/` | 结果分组、键盘导航、schedules 新字段展示 | +| D-05 | **E2E：凭据轮询** | P2 | ☐ | 审计报告 §5 建议 | add-by-ip 失败 → pending → 重试/删除 Playwright | + +--- + +## E. 验收、审计与文档工程债 + +### E.1 测试与验收（Phase F / L4–L5） + +| ID | 任务 | 优先级 | 状态 | 命令/文档 | +|----|------|--------|------|-----------| +| E-01 | 修复本地 `local_verify.sh` 登录 401 环境 | P1 | ☐ | `.env` + `seed_local_admin.py` | +| E-02 | L4 Playwright 15 用例全绿 | P1 | ☐ | `frontend/e2e/full-acceptance.spec.mjs` | +| E-03 | L5 生产验收清单勾选 | P1 | ☐ | `production-verification-checklist.md` | +| E-04 | T-01 心跳 Redis 写入 | P2 | ☐ | Agent 60s → `heartbeat:{id}` | +| E-05 | T-02 WebSocket 告警 + Telegram | P2 | ☐ | 浏览器 WS + 消息 | +| E-06 | T-03 三层守护杀进程重启 | P2 | ☐ | Supervisor 恢复 | +| E-07 | T-05 install 向导五步 | P2 | ☐ | 干净环境 E2E | +| E-08 | `acceptance_catalog` 增 add-by-ip / schedules 字段 | P3 | ☐ | `tests/acceptance_catalog.py` | + +### E.2 POSIX 审计批次（Phase E） + +| ID | 任务 | 状态 | +|----|------|------| +| E-09 | POSIX-14 `unix_ls.py` 边界用例 | ☐ | +| E-10 | POSIX-15 前端 `remotePath.ts` 扫尾 | ☐ | +| E-11 | POSIX-16 `sync_engine_v2` rsync 目标回归 | ☐ | +| E-12 | POSIX-17 生产 Win 开发 + Linux SSH 目标回归 | ☐ | +| E-13 | POSIX-18 `nexus-posix-paths.mdc` + 可选 CI | ☐ | + +### E.3 增强项（Phase G） + +| ID | 任务 | 优先级 | 状态 | +|----|------|--------|------| +| E-14 | ENH-01 危险路径 chmod 二次确认 | P2 | ☐ | +| E-15 | ENH-02 `find -maxdepth` 替代大范围 chmod -R | P3 | ☐ | +| E-16 | ENH-03 预加载失败聚合提示 | P3 | ☐ | +| E-17 | ENH-04 `NEXUS_FILES_ELEVATION_DEFAULT` env | P3 | ☐ | +| E-18 | ENH-08 文件列表「权限」列默认隐藏 + 列设置 | P3 | ☐ | + +### E.4 文档 SSOT 漂移（避免误判「缺失」） + +| ID | 任务 | 优先级 | 状态 | +|----|------|--------|------| +| E-19 | 更新 `AI-HANDOFF-2026-06-03.md` 指针与 commit | P1 | ☐ | +| E-20 | 修正 `nexus-full-site-features.md` §23（重连/CSV/预览已实现） | P1 | ☐ | +| E-21 | 更新 `status.md`（Vue SPA 非 Alpine） | P2 | ☐ | +| E-22 | 扩写功能指南 §12.8 Schedules、§12.6 Scripts 能力表 | P2 | ☐ | + +--- + +## 1. 推荐执行顺序 + +``` +Week 0（立即） + A-01 → A-02 → A-03 + A-04 + A-05 + +Week 1（P1 能力） + B-01 Commands 推送日志视图 + B-04 CSV 模板 + D-01 Agent upgrade 对齐 + E-01 E-02 E-03 + +Week 2+（P2/P3） + B-02 Dashboard 趋势 + C-01 资产管理页 + C-02 配置推送 UI + E-09～E-13 POSIX + D-02～D-05 按需 +``` + +--- + +## 2. 单项 DoD（通用） + +每项关闭须满足： + +1. 有 `docs/design/specs/` 或本计划 ID 引用（中改以上） +2. 实现 + `bash scripts/local_verify.sh` 或针对性 pytest +3. `docs/changelog/YYYY-MM-DD-*.md` +4. 生产点验（A/B/C/D 类）或 E2E（E-02） +5. 更新功能指南 / 本表状态 ☐→☑ + +--- + +## 3. 进度总表 + +``` +A 部署验证 [ ] 0/5 +B 14页缺口 [ ] 0/6 +C API无UI [ ] 0/4 +D 产品backlog [ ] 0/5 +E 工程债 [ ] 0/22 +───────────────────── +合计 [ ] 0/31（不含已否决） +``` + +--- + +## 4. 相关文档 + +| 文档 | 路径 | +|------|------| +| 功能 SSOT | `docs/project/nexus-functional-development-guide.md` | +| 14 页契约审计 | `docs/reports/2026-06-06-frontend-14p-contract-audit.md` | +| Master backlog | `docs/project/2026-06-01-master-backlog-plan.md` | +| 脚本库修复 changelog | `docs/changelog/2026-06-07-scripts-spa-perfect-implementation.md` | +| 调度修复 changelog | `docs/changelog/2026-06-07-schedules-perfect-implementation.md` | +| 验收标准 | `docs/project/development-acceptance-standard.md` | + +--- + +## 变更记录 + +| 日期 | 变更 | +|------|------| +| 2026-06-07 | 初版：31 项可排期 backlog；标注 dfb0ea2 待部署；剔除已实现误报（自动重连、CSV 导入、文件预览） | diff --git a/docs/project/nexus-functional-development-guide-appendix.md b/docs/project/nexus-functional-development-guide-appendix.md index c09c81c7..e1825052 100644 --- a/docs/project/nexus-functional-development-guide-appendix.md +++ b/docs/project/nexus-functional-development-guide-appendix.md @@ -253,12 +253,14 @@ useTerminalSettings → localStorage 主题/字体（非敏感） | 方法 | 路径 | 说明 | |------|------|------| -| GET | `/` | 列表 | -| POST | `/` | 创建（cron + server_ids + source/target + sync_mode 或 script_id） | -| PUT | `/{id}` | 更新 | +| GET | `/` | 列表（含 `next_run`、`target_path`、`schedule_type`、`run_mode`） | +| POST | `/` | 创建 push：`source_path`、`target_path?`、`sync_mode`、`cron_expr`/`fire_at`；script：`script_id`/`script_content` | +| PUT | `/{id}` | 更新（allowlist 含 `target_path`） | | DELETE | `/{id}` | 删除 | -后台 `schedule_runner` 每分钟扫描 `enabled=1` 且 cron 到期项 → 调 SyncEngine 或 ScriptService。 +`PushSchedule.target_path` 留空时 runner / `runNow` 与各机 `servers.target_path` 一致。 + +后台 `schedule_runner` 每分钟扫描 `enabled=1` 且到期项 → SyncEngineV2 或 ScriptService。 ### E.2 重试 `/api/retries` diff --git a/docs/project/nexus-functional-development-guide.md b/docs/project/nexus-functional-development-guide.md index 0a544eac..a2431985 100644 --- a/docs/project/nexus-functional-development-guide.md +++ b/docs/project/nexus-functional-development-guide.md @@ -586,11 +586,14 @@ main.ts → App.vue（侧栏/搜索）→ router-view | 功能 | API | |------|-----| -| 脚本 CRUD | `/scripts/` | -| Monaco 编辑 | content 字段 | -| 执行 | `POST /scripts/exec` + 轮询 executions | -| 临时命令 | quick exec 面板 | -| 停止 | `POST /scripts/executions/{id}/stop` | +| 脚本 CRUD | `GET/POST/PUT/DELETE /scripts/`（分类 ops/deploy/check/cleanup） | +| Monaco 编辑 | `ScriptContentEditor` · `content` 字段 | +| 库内执行 | `POST /scripts/exec`（`script_id` 或 `command` 二选一） | +| 临时命令 | 页内 quick exec 面板 | +| 长任务 / DB 凭据 | `long_task`、`credential_id`；`GET /scripts/exec-config` | +| 执行状态 | 10s 轮询 `GET /scripts/executions/{id}` | +| 历史 | `GET /scripts/executions?script_id=` | +| 停止 / 重试 / 卡住 | `POST .../stop`、`.../retry`、`.../mark-stuck` | ### 12.7 CredentialsPage `/credentials` @@ -606,7 +609,15 @@ main.ts → App.vue（侧栏/搜索）→ router-view ### 12.8 SchedulesPage `/schedules` -Cron 调度推送；`runNow` → `POST /sync/files`；cron 前端正则校验。 +| 功能 | API / 行为 | +|------|------------| +| 类型 | `schedule_type`: `push`（rsync）或 `script`（ScriptService） | +| 运行模式 | `run_mode`: `cron`（5 字段 cron_expr）或 `once`（fire_at） | +| 推送字段 | `source_path`（必填）、`target_path`（可选，留空走各机配置）、`sync_mode` | +| 脚本字段 | `script_id` 或 `script_content`、`exec_timeout`、`long_task` | +| 列表 | `next_run` API 计算；`GET /schedules/` | +| 立即执行 | push → `POST /sync/files`；script → `POST /scripts/exec` | +| 后台 | `schedule_runner` 60s 扫描到期项 | ### 12.9 RetriesPage `/retries` @@ -614,7 +625,11 @@ Cron 调度推送；`runNow` → `POST /sync/files`；cron 前端正则校验。 ### 12.10 CommandsPage `/commands` -命令视图 / 会话视图；`GET /assets/command-logs|ssh-sessions`。 +| 视图 | API | 筛选 | +|------|-----|------| +| 命令视图 | `GET /assets/command-logs` | server_id | +| 会话视图 | `GET /assets/ssh-sessions` | server_id | +| 推送日志 | `GET /servers/logs` | server_id、status、sync_mode、trigger_type | ### 12.11 AlertsPage `/alerts` diff --git a/frontend/e2e/full-acceptance.spec.mjs b/frontend/e2e/full-acceptance.spec.mjs index 0c504a38..17868d18 100644 --- a/frontend/e2e/full-acceptance.spec.mjs +++ b/frontend/e2e/full-acceptance.spec.mjs @@ -108,11 +108,14 @@ test('10 retries list', async ({ page }) => { await expect(page.getByText(/重试|队列/).first()).toBeVisible({ timeout: 20000 }) }) -test('11 commands: command and session views', async ({ page }) => { +test('11 commands: command, session and push log views', async ({ page }) => { await login(page) await nav(page, '/commands') await expect(page.getByText('命令日志')).toBeVisible({ timeout: 20000 }) await page.locator('.v-card-title .v-select').first().click() + await page.locator('.v-overlay-container').getByText('推送日志').click() + await expect(page.locator('table').first()).toBeVisible() + await page.locator('.v-card-title .v-select').first().click() await page.locator('.v-overlay-container').getByText('会话视图').click() await expect(page.locator('table').first()).toBeVisible() }) diff --git a/frontend/src/pages/CommandsPage.vue b/frontend/src/pages/CommandsPage.vue index 17958835..309c2355 100644 --- a/frontend/src/pages/CommandsPage.vue +++ b/frontend/src/pages/CommandsPage.vue @@ -1,19 +1,61 @@