Nexus/docs/project/AI-HANDOFF-2026-06-08.md

# Nexus — AI 接续（2026-06-08 · Linux）

> **已由 [AI-HANDOFF-2026-06-09.md](AI-HANDOFF-2026-06-09.md) 取代**（生产 @ `56139a4` 时区交付）。下文保留 Master Backlog 索引。  
> SSOT：`docs/project/nexus-functional-development-guide.md` · 门控 `bash deploy/pre_deploy_check.sh`

---

## 复制提示词（整段给新会话）

```
【Nexus 6.0 接续 · Linux · 2026-06-08】

工作区：$NEXUS_ROOT（本机 ~/桌面/Nexus 或 /opt/nexus）
仓库：http://66.154.115.8:3000/admin/Nexus.git · 分支 main @ a401ea5
生产：https://api.synaglobal.vip · Docker @ /opt/nexus · 端口 8600
SSH：export NEXUS_SSH="azureuser@20.24.218.235"
     export NEXUS_SSH_KEY="/home/r/下载/Telegram Desktop/nz-admin.pem"  # 路径含空格须引号
push：bash scripts/git-push.sh（凭据 deploy/nexus-1panel.secrets.sh，gitignore）
部署：bash deploy/pre_deploy_check.sh && bash deploy/deploy-production.sh

【栈】FastAPI + Async SQLAlchemy + Redis · Vue 3 + Vuetify 4 SPA（15 页）· Vite → web/app/
【铁律】单 Agent · 完美实现 perfect-implementation.mdc · 改代码必 changelog + 部署前 audit · 测试 Agent 做、用户终验

【生产已部署（a401ea5）】
- server_ids 批量上限 2000 + 列表 422 中文完整（a401ea5）
- 设置页 v-form 校验 + 422 中文 + 数值字段 String 保存（632891e / ff143c2）
- 未设路径服务器区：独立面板、行内详情、批量操作与主表齐平、sort-by 排序（85ecd1f）
- 未设路径批量检测选中数修复（05c7aeb）
- 展开详情对比度 + 同步日志仅 1 条（d0526c0）
- 资源恢复 Telegram 联动 CPU/内存/磁盘开关；仪表盘移除服务器列表（fe8b24c/cb49fd9）
- 登录门控/壁纸/IP 校验、页面缓存刷新、server_batch 后台任务、WebSSH ANSI、终端快捷栏等（见 git log 2026-06-08）

【本会话运维记录】
- 批量任务 #20（install-agent）因部署重启僵尸 running；已通过任务 #26 对 #290/#346 重装 Agent 成功
- 用户报「server_ids 最多 50 项s after validation, not 101」→ 已修并部署 a401ea5
- 设置页连接池保存 422「Input should be a valid string」→ 已修并部署 ff143c2/632891e

【2026-06-08 已部署 69068e2】
- server_batch 僵尸回收 + stuck 60s 扫描
- sync_logs 30 天 purge（启动首轮 + 24h）
- 批量安装 Agent：已装且版本 ≥ 主站则跳过
- 验证：`docs/reports/2026-06-08-full-align-deploy-verification.md`

【用户终验待确认】
- 全选 101 台批量操作（install-agent / detect-path）不再 422
- 设置页连接池等数值字段保存
- 未设路径区排序、批量检测选中数、展开对比度、关 CPU 告警无恢复 Telegram
- WebSSH 实连 pwd、Telegram 测试发送、推送预览（勿误推生产）

【优先待办 TOP 10】
1. server_batch 僵尸回收 ☑（69068e2 已部署）
2. sync_logs 30 天自动清理 ☑（69068e2 已部署）
3. Agent 401 停循环 ☑（代码+单测；子机 rollout 见 #7）
4. Agent upgrade 与 install.sh venv 对齐（D-01）
5. ~75 条后端 API 英文 detail 改中文（Pydantic 422 已部分中文化）
6. 更新 AI-HANDOFF + alignment-plan 勾选状态（文档 SSOT）
7. L4 Playwright 全绿 + L5 production-verification-checklist
8. Dashboard 24h 历史趋势图（B-02）
9. 资产管理页 / Sync 配置 UI（C-01/C-02）
10. POSIX-14～18 + 文件管理 FM-L* 生产浏览器验收

【完整 132 条待办】docs/project/AI-HANDOFF-2026-06-08.md §Master Backlog 索引
【对齐计划 31 项】docs/design/plans/2026-06-07-missing-features-alignment-plan.md
【Master 长计划】docs/project/2026-06-01-master-backlog-plan.md

【勿重复做 / 已否决】RBAC、移动端、会话录像、审计 CSV 导出、邮件报告、Redis Cluster、独立文件编辑器
【已风险接受】WebSocket JWT query（ADR-011）、Agent global API_KEY legacy — risk-acceptance-single-operator.md

【工作区】69068e2 已 push/deploy；本地勿提交 web/app/assets/* 构建残留、gate_log.jsonl、.cursor/settings.json
【文档】Handoff 本文 · 功能指南 nexus-functional-development-guide.md · 验收 development-acceptance-standard.md
```

---

## 生产状态

| 项 | 值 |
|----|-----|
| 分支 | `main` @ **`69068e2`** |
| 生产 URL | `https://api.synaglobal.vip` |
| 运行时 | Docker Compose @ `/opt/nexus`（1panel-network） |
| SSH | `azureuser@20.24.218.235`（本机 `Host nexus` 常不可用，用 IP + pem） |
| 最近部署 | 2026-06-08 — server_ids 2000 + 422 中文（`a401ea5`）· `/health` ok · `/app/` 200 |

---

## 2026-06-08 已推送主要变更（摘要）

| Commit | 主题 |
|--------|------|
| `a401ea5` | server_ids 批量上限 2000；列表 too_long 422 纯中文 |
| `632891e` | 设置页 v-form 校验；422 中文；SettingUpdatePayload 数字 coerce |
| `ff143c2` | 设置保存数值字段 String(value) 修 422 |
| `85ecd1f` | 未设路径区表格 `sort-by` 服务端排序 |
| `05c7aeb` | 未设路径批量检测对话框选中数 |
| `d0526c0` | 展开详情对比度；同步日志 limit=1 |
| `fe8b24c` | 资源恢复 Telegram 联动 CPU/内存/磁盘开关 |
| 更早 | 登录门控、pages 自动刷新、server_batch 后台、WebSSH ANSI 等（见 `docs/changelog/2026-06-08-*.md`） |

---

## 本会话未完成（写入日志 · 2026-06-08 对话框结束）

### A. 代码已写未提交

| 模块 | 状态 | 说明 |
|------|------|------|
| server_batch 僵尸回收 | ☐ 未 commit | `recover_orphaned_batch_jobs` + `server_batch_reconcile_loop` 60s；changelog/plan 已有 |
| 若干 verification 报告 | ☐ 未提交 | `docs/reports/2026-06-08-*-verification.md` 多份 |

### B. 已识别待做（未开始或部分）

| # | 项 | 状态 |
|---|-----|------|
| 3 | sync_logs 30 天自动 purge | ☑ |
| 4 | Agent 401 停循环（A-05） | ☑~（待部署+子机升级） |
| 5 | upgrade-agent 与 install.sh 对齐（D-01） | ☐ |
| — | ~75 条后端 API 英文 `detail` 改中文 | ☐ |
| — | ~25 前端英/混排标签 | ☐ |
| 29–31 | L4 Playwright + L5 验收清单 | ☐ |
| 87–95 | 用户浏览器终验（WebSSH/Telegram/推送等） | ~ |

### C. 工作区卫生

- 勿提交：`web/app/assets/*`、`deploy/gate_log.jsonl`、`.cursor/settings.json`
- Handoff 本文已更新至 `a401ea5`；server_batch reconcile 待下一会话收尾

---

## 关键路径

| 用途 | 路径 |
|------|------|
| 后端入口 | `server/main.py` |
| 服务器 API/批量 | `server/api/servers.py` · `server/application/services/server_batch_service.py` |
| 批量回收（未提交） | `server/background/server_batch_reconcile.py` |
| 422 中文 | `server/utils/validation_errors_zh.py` |
| 未设路径前端 | `frontend/src/components/servers/ServerUnsetPathPanel.vue` · `ServersPage.vue` |
| Agent 安装 | `web/agent/install.sh` |
| 门控 | `deploy/pre_deploy_check.sh`（7/7） |
| 部署 | `deploy/deploy-production.sh` |

---

## Master Backlog 索引（132 条 · 2026-06-08 盘点）

> 新会话接某编号时说「做 #N」即可。

### 一、运维可靠性（1–7）

1. server_batch 僵尸任务回收（例 #20） ☑~ **（本地已实现，待部署）**  
2. server_batch 启动 stuck 扫描 ☑~ **（同上）**  
3. sync_logs 30 天自动 purge ☑  
4. Agent 401 停循环（A-05） ☑~  
5. upgrade-agent 与 install.sh 对齐（D-01） ☐  
6. 生产复核 `push_schedules.target_path` 列（A-02） ~  
7. 各子机同步 agent.py（A-05 依赖） ☐  

### 二、对齐计划 A 部署点验（8–12）

8. A-01 持续部署 ☑ · 9. A-02 ~ · 10. A-03 脚本库点验 ~ · 11. A-04 调度点验 ~ · 12. A-05 同 #4  

### 三、14 页缺口 B（13–19）

13. B-01 Commands 推送日志 Tab ☑~ · 14. B-02 Dashboard 24h 趋势 ☐ · 15. B-03 Files 树形侧栏 ☐  
16. B-04 CSV 模板 ☑~ · 17. B-05 SSOT 扩写 ☑ · 18. B-06 Settings Agent 指引 ☐ · 19. WebSSH 重连生产验证 ~  

### 四、API 无 UI C（20–23）

20. C-01 资产管理页 ☐ · 21. C-02 Sync 配置 UI ☐ · 22. C-03 Sync 批量命令 ☐ · 23. C-04 Sync SFTP ☐  

### 五、产品 D（24–28）

24. D-01 同 #5 · 25. D-02 宝塔监控 ☐ · 26. D-03 mTLS ☐ · 27. D-04 搜索增强 ☐ · 28. D-05 凭据轮询 E2E ☐  

### 六、验收 E（29–50）

29. E-01 local_verify 401 ☐ · 30. E-02 Playwright 15 绿 ☐ · 31. E-03 L5 清单 ☐  
32–35. E-04～E-07 心跳/WS/守护/install E2E ☐ · 36. E-08 ☑ · 37–41. POSIX-14～18 ☐  
42–46. ENH-01～04/08 ☐ · 47–50. 文档 SSOT E-19～22（#47/#50 部分 ☑）  

### 七、Master FM/T（51–81）

51. A-09 local_integration_smoke ☐ · 52. Phase C 浏览器 L1–L4 ☐ · 53–74. FM-L1～L4 文件管理生产验收 ☐  
75–77. ENH-05～07 文档回写 ☐ · 78. T-04 Telegram ☐ · 79. T-06 同 #31 · 80. T-07 WebSSH ~ · 81. T-08 CSV ☑  

### 八、Handoff 可选（82–86）

82. 全选筛选结果 ☑ · 83. 失败分组 ☑ · 84. 失败导出 CSV ☐ · 85. 归档旧 handoff ☐ · 86. 其它表 sort 扫尾 ☐  

### 九、用户终验（87–95）

87–90. WebSSH/推送/Telegram/kill 自愈 ☐ · 91–95. 近期功能浏览器终验 ~  

### 十、L5 清单（96–125）

96–125. `production-verification-checklist.md` 逐项 ☐（#122 /health ☑）  

### 十一、仓库卫生（126–132）

126–132. handoff/alignment 过期、verification 未提交、assets 残留、gate_log、.cursor ☐  

### 十二、不做 / 风险接受（133–137）

133–135. 已否决功能 · 136–137. ADR-011 / global API_KEY 风险接受  

---

## 常用命令

```bash
cd ~/桌面/Nexus   # 或 $NEXUS_ROOT
docker compose up -d mysql redis
bash scripts/start-dev.sh          # API :8600
bash scripts/local_verify.sh
cd frontend && npm run dev         # :3000/app/

bash deploy/pre_deploy_check.sh
bash scripts/git-push.sh
export NEXUS_SSH="azureuser@20.24.218.235"
export NEXUS_SSH_KEY="/home/r/下载/Telegram Desktop/nz-admin.pem"
bash deploy/deploy-production.sh
```

---

## 铁律

- 单 Agent；禁止虚拟部门
- 完美实现：设计→技术文档→代码→测试→changelog→（批准）部署
- 测试 Agent 执行；用户只做终验（`docs/reports/2026-06-01-final-acceptance-checklist.md`）

---

## 变更记录

| 日期 | 变更 |
|------|------|
| 2026-06-08 初版 | 3f995a7 摘要 |
| 2026-06-08 中 | 更新至 85ecd1f；132 条 Master Backlog |
| 2026-06-08 末 | 更新至 a401ea5；记录 server_ids/设置 422 修复；server_batch reconcile 未提交待办 |