Nexus/docs/project/2026-06-01-master-backlog-plan.md

# Nexus 主待办长计划（文件管理 · POSIX · 部署 · 审计）

| 项 | 内容 |
|----|------|
| 创建日期 | 2026-06-01 |
| 状态 | **活跃** — 新会话接续本文任务 ID |
| 范围 | 2026-06-01 会话内已实现代码的验证/部署/审计 + 全站遗留验收 |
| 关联 SSOT | [development-acceptance-standard.md](./development-acceptance-standard.md) · [AI-HANDOFF-2026-05-23.md](./AI-HANDOFF-2026-05-23.md) |

---

## 如何使用

1. 按 **阶段（Phase）** 顺序执行；阶段内任务可并行标 `∥`。
2. 每完成一项：将 `[ ]` 改为 `[x]`，并在对应 changelog/audit 留痕。
3. 宣称「可部署/可上线」前：至少完成 **Phase D（门控）** + 相关 **Phase C/E** 验证任务。
4. 任务 ID 格式：`{域}-{序号}`，便于 PR/commit 引用（例：`DEP-03`）。

**图例**

| 标记 | 含义 |
|------|------|
| `[x]` | 代码/文档已完成（2026-06-01 会话） |
| `[ ]` | 待做 |
| `🔍` | 需人工/生产环境 |
| `⚠` | 阻塞部署或上线 |

---

## 总览路线图

```mermaid
flowchart LR
  subgraph done [已实现代码]
    A1[POSIX 批次 1-7]
    A2[文件管理 P1-P5]
    A3[二期递归+提示]
  end
  subgraph next [待执行]
    B[Phase A 单测与门控]
    C[Phase B 部署]
    D[Phase C 浏览器与 L1-L4]
    E[Phase D 正式审计 8 步]
    F[Phase E POSIX 批次 13+]
    G[Phase F 全站回归 T1-T5]
    H[Phase G 增强与风险]
  end
  done --> B --> C --> D
  D --> E
  E --> F
  F --> G
  G --> H
```

---

## Phase A — 本地验证与程序门控（未部署前必做）

| ID | 任务 | 状态 | 验收标准 |
|----|------|------|----------|
| A-01 | 跑 POSIX 单测套件 | [x] | 44 passed（含 schema/file 套件） |
| A-02 | 跑文件管理单测套件 | [x] | 同上 |
| A-03 | 跑全量 API 测试（有 `.env`） | [x] | `python tests/test_api.py`（门控方式）；pytest 0 收集（已修复函数名） |
| A-04 | ruff `server/` 零错误 | [x] | |
| A-05 | import 冒烟 | [x] | |
| A-06 | bandit 无 HIGH/MEDIUM | [x] | 门控仅 HIGH；0 HIGH |
| A-07 | 7 门预检脚本 | [x] | 生产 7/7（已删 `server/server/` 遗留目录） |
| A-08 | 合并 changelog（本次主题） | [x] | 见 `docs/changelog/2026-06-01-*.md` 系列（posix / files / phase5 / phase2 / capability） |
| A-09 | 本地集成 smoke | [ ] | `bash scripts/local_integration_smoke.sh` |

**Phase A 完成定义**：A-01～A-07 全 `[x]`（A-09 可选但推荐）。

---

## Phase B — 生产部署（后端 + 前端）

| ID | 任务 | 状态 | 验收标准 |
|----|------|------|----------|
| DEP-01 | `git push origin main` | [x] | d93c518 |
| DEP-02 | 生产 `git fetch && reset --hard origin/main` | [x] | |
| DEP-03 | `supervisorctl restart nexus` | [x] | e704b01 后已 restart |
| DEP-04 | 健康检查 | [x] | `curl` → `ok` |
| DEP-05 | 前端 `deploy/deploy-frontend.sh` | [x] | Windows Node 22 `npm run build` + tar/scp |
| DEP-06 | 浏览器 `/app/` HTTP 200 | [x] | 生产 `curl` → 200 |
| DEP-07 | 记录部署日期到本文 | [x] | 见下表 |

**依赖**：Phase A 的 A-07 通过。  
**路径 SSOT**：`/www/wwwroot/api.synaglobal.vip/` · SSH 别名 `nexus` · 端口 `8600`。

### 部署记录

| 日期 | 操作人 | DEP-01～06 | 备注 |
|------|--------|------------|------|
| 2026-06-01 | AI | 01-06 ✓ | bd6467d 后端 + 前端 FilesPage 等已上线；/app/ 200 |

---

## Phase C — 文件管理功能验收（设计文档 L1～L4）

> 设计：[2026-06-01-files-root-ownership-ui-design.md](../design/specs/2026-06-01-files-root-ownership-ui-design.md) §7  
> 代码状态：Phase 1～5 + 二期 **已实现**；本节全部为 **🔍 生产/浏览器验证**。

### C1 — L1 提权

| ID | 任务 | 状态 | 步骤 / 预期 |
|----|------|------|-------------|
| FM-L1-01 | deploy + `nexus-files.sudoers` | [ ] 🔍 | 目标机安装 `docs/deploy/nexus-files-sudoers.example`；`sudo -n true` 成功 |
| FM-L1-02 | 写/保存/压缩/chmod 成功 | [ ] 🔍 | 审计含 `elevated: true`（若走了 sudo） |
| FM-L1-03 | SSH 用户 root | [ ] 🔍 | 不触发多余 sudo；功能正常 |
| FM-L1-04 | 无 sudo 非 root | [ ] 🔍 | 失败提示含免密 sudo / 文档路径，非「SSH 连接失败」 |
| FM-L1-05 | 顶栏不可读提示 | [ ] 🔍 | 选 deploy 服务器见提示条；读 root 属主文件后提示更新 |
| FM-L1-06 | `files-capability` API | [ ] 🔍 | `GET /api/servers/{id}/files-capability` 与 UI 检测一致 |
| FM-L1-07 | 服务器 `files_elevation` 三档 | [ ] 🔍 | off / auto_sudo / always_sudo 行为符合预期 |

### C2 — L2 展示

| ID | 任务 | 状态 | 预期 |
|----|------|------|------|
| FM-L2-01 | 归属列 www/root | [ ] 🔍 | chip 正确 |
| FM-L2-02 | tooltip 完整权限 | [ ] 🔍 | 悬停见 `drwx… · 755 · www` |
| FM-L2-03 | 无默认宽「权限」列 | [ ] 🔍 | 主表不挤占 |
| FM-L2-04 | 不可读行锁图标 | [ ] 🔍 | `mdi-shield-lock` 与 ls 一致 |
| FM-L2-05 | 修改时间为 long-iso | [ ] 🔍 | 形如 `2026-06-01 12:00:00`，排序合理 |

### C3 — L3 修改权限

| ID | 任务 | 状态 | 预期 |
|----|------|------|------|
| FM-L3-01 | 预设 644/755 一键 | [ ] 🔍 | |
| FM-L3-02 | chown www 后刷新 | [ ] 🔍 | 列表归属更新 |
| FM-L3-03 | 非法 mode/owner | [ ] 🔍 | 前端拦截 + API 400 |
| FM-L3-04 | 目录递归 chmod | [ ] 🔍 | 勾选 → confirm → 子项权限变化；`/` 等被拒绝 |
| FM-L3-05 | 权限对话框检测按钮 | [ ] 🔍 | 与顶栏 capability 一致 |

### C4 — L4 回归

| ID | 任务 | 状态 | 预期 |
|----|------|------|------|
| FM-L4-01 | 文件树 / 编辑器 | [ ] 🔍 | 打开保存无回归 |
| FM-L4-02 | 剪贴板复制/粘贴/移动 | [ ] 🔍 | |
| FM-L4-03 | 上传 / 下载 | [ ] 🔍 | |
| FM-L4-04 | 压缩 / 解压 | [ ] 🔍 | |
| FM-L4-05 | Windows 开发机 + Linux 目标路径 | [ ] 🔍 | 路径无 `\` 进入远程命令 |

**Phase C 完成定义**：C1～C4 全部 `[x]`。

---

## Phase D — 正式审计（8 步 · 部署门控）

> 模板：`docs/audit/TEMPLATE.md` · 规则：`.cursor/rules/audit-line-review.mdc`  
> 现状：POSIX 分批审查 ✅；files-phase5 简表 ✅；**下列为改动的完整 8 步审计（待补）**。

| ID | 审计主题 | 状态 | 输出文件 |
|----|----------|------|----------|
| AUD-01 | 文件管理 Phase 1～3（remote_shell / browse / chmod UI） | [x] | 合并在 master-execution-audit |
| AUD-02 | files-capability + files_elevation（批次 10） | [x] | 同上 |
| AUD-03 | Phase 5 加固（long-iso / read-file / remote_write） | [x] | files-phase5.md + master-execution |
| AUD-04 | 二期递归 chmod + 不可读提示（批次 12） | [x] | 同上 |
| AUD-05 | Schema 路径校验 P2（schema_path_validators） | [x] | posix-path-full-audit |
| AUD-06 | 部署前 Review 门：审计含**实际改动文件清单** | [ ] | 已修 gate 选最新 audit；待重跑 |

**每份审计必须含**：Step3 规则扫描 · Closure 全表 · 入口表 · 输入→Sink · DoD · 0 FINDING 或已修 FINDING（`文件:行号`）。

---

## Phase E — POSIX 路径审计（延续）

> 总览：[posix-path-full-audit.md](../audit/2026-06-01-posix-path-full-audit.md)  
> 分批记录：[posix-path-batch-review.md](../audit/2026-06-01-posix-path-batch-review.md)

| ID | 任务 | 状态 | 说明 |
|----|------|------|------|
| POSIX-13 | 批次 13：`remote_shell` + `files_capability` + `files_chmod_policy` | [x] | master-execution-audit §批次 POSIX-13 |
| POSIX-14 | 批次 14：`unix_ls.py` 解析边界（空格文件名、异常行） | [ ] | 对照 `test_file_permissions.py` 补案例 |
| POSIX-15 | 批次 15：前端 `remotePath.ts` 全页面扫尾 | [ ] | `rg` 无裸 `+` 路径拼接 |
| POSIX-16 | 批次 16：`sync_engine_v2` rsync 目标再回归 | [ ] | `user@host:path` 形态 |
| POSIX-17 | 生产回归：Windows 主机开发 + Linux SSH 目标 | [ ] 🔍 | full-audit DoD 最后一项 |
| POSIX-18 | 规则固化：`.cursor/rules/nexus-posix-paths.mdc` 与 CI 可选检查 | [ ] | 如在 CI 加 `rg` 门禁 |

---

## Phase F — 全站遗留测试（CLAUDE / HANDOFF）

| ID | 任务 | 状态 | 说明 |
|----|------|------|------|
| T-01 | 心跳 Redis 写入验证 | [ ] 🔍 | Agent 60s → `heartbeat:{id}` |
| T-02 | WebSocket 连接与告警推送 | [ ] 🔍 | 浏览器 + Telegram |
| T-03 | 三层守护（杀 Python → Supervisor 重启） | [ ] 🔍 | |
| T-04 | Telegram 推送 | [ ] 🔍 | |
| T-05 | install.html 五步安装向导 | [ ] 🔍 | |
| T-06 | L5 生产验收清单 | [ ] | `production-verification-checklist.md` |
| T-07 | WebSSH 断线重连（HANDOFF P1） | [ ] | 独立设计与实现 |
| T-08 | 服务器 CSV 批量导入（HANDOFF P1） | [ ] | |

---

## Phase G — 增强与已知风险（未实现 / 低优先级）

| ID | 任务 | 优先级 | 说明 |
|----|------|--------|------|
| ENH-01 | 危险路径 chmod 二次确认（`/etc`、`/usr` 下单文件） | P2 | 设计 §8 风险表 |
| ENH-02 | `find -maxdepth` 替代大范围 `chmod -R`（可选） | P3 | 降低误操作面 |
| ENH-03 | 预加载失败聚合提示（非静默） | P3 | `filePreload.ts` 现静默 catch |
| ENH-04 | `NEXUS_FILES_ELEVATION_DEFAULT` 全局 env 默认 | P3 | plans 二期提及 |
| ENH-05 | 设计文档 §7 勾选同步到本文 | P1 | FM-L* 完成后回写 spec |
| ENH-06 | 更新 `AI-HANDOFF` 指针到本文 | P1 | 避免多 SSOT 分叉 |
| ENH-07 | `CLAUDE.md` 实现表：文件管理条目标为已完成 | P2 | 与代码一致 |
| ENH-08 | 可选列「权限」默认隐藏 + 列设置 | P3 | L2-03 细化 |

---

## 已完成代码清单（勿重复实现）

| 主题 | 批次/阶段 | 关键路径 |
|------|-----------|----------|
| POSIX SSOT + sync_v2 规范化 | 批次 1～7 | `server/utils/posix_paths.py` |
| Schema 路径 P2 | P2 | `schema_path_validators.py` |
| remote_shell + sudo 回退 | Phase 1 | `remote_shell.py` |
| browse owner/group/mode_octal | Phase 2 | `sync_v2.py` |
| FilePermissionDialog + chown | Phase 3 | 前端组件 |
| files-capability + files_elevation | 批次 10 / Phase 4 | `servers.py` |
| long-iso / read-file 提权 / write elevation | 批次 11 / Phase 5 | `unix_ls.py` |
| 递归 chmod + 不可读顶栏/锁图标 | 批次 12 / 二期 | `files_chmod_policy.py` |

---

## 进度总表（给用户一眼看跳步）

```
代码实现     [x]  POSIX 1-7 + 文件管理 P1-P5 + 二期
本地单测门控 [x]  Phase A（A-07 生产待重跑）
正式审计 8 步 [x]  Phase D（合订 master-execution-audit）
生产部署     [x]  Phase B
浏览器 L1-L4 [ ]  Phase C
POSIX 13-18  [~]  Phase E（13 完成；14-18 待做）
全站 T1-T8   [ ]  Phase F
增强 ENH     [ ]  Phase G（按需）
```

**当前建议下一项**：`A-01` → `A-07` → `DEP-01`～`DEP-06` → `FM-L1-01` 起。

---

## 文档索引

| 类型 | 路径 |
|------|------|
| 文件管理设计 | `docs/design/specs/2026-06-01-files-root-ownership-ui-design.md` |
| 文件管理计划 | `docs/design/plans/2026-06-01-files-root-ownership-ui.md` |
| 二期计划 | `docs/design/plans/2026-06-01-files-phase2-recursive-read-hint.md` |
| POSIX 全审计 | `docs/audit/2026-06-01-posix-path-full-audit.md` |
| POSIX 分批 | `docs/audit/2026-06-01-posix-path-batch-review.md` |
| Changelog 目录 | `docs/changelog/2026-06-01-*.md` |
| sudoers 示例 | `docs/deploy/nexus-files-sudoers.example` |

---

## 变更记录

| 日期 | 变更 |
|------|------|
| 2026-06-01 | 初版：合并 POSIX 分批、文件管理 Phase/二期、部署门控、审计、全站 T 项 |