Nexus/docs/audit/2026-06-01-files-page-row-click.md

# 审计记录：文件管理行点击与自动选服

## 审计信息

- **日期**: 2026-06-01
- **审计人**: Claude (AI)
- **触发原因**: Bug 修复 — `#/files` 无法进入子目录、未选服务器时空列表
- **关联 changelog**: `docs/changelog/2026-06-01-files-page-row-click.md`

## 审计范围（实际改动文件清单）

| 文件 | 行数 | 状态 |
|------|------|------|
| `frontend/src/pages/FilesPage.vue` | 1429 | ☑ 全文已审 |
| `frontend/src/composables/useServerList.ts` | 37 | ☑ 全文已审 |
| `docs/changelog/2026-06-01-files-page-row-click.md` | 25 | ☑ 已审 |

## 变更摘要（审计对象）

1. **Vuetify 4 兼容**：移除无效的 `@click:row` / `@dblclick:row` / `@contextmenu:row`，改用 `:row-props="fileRowProps"` 绑定 `onClick` / `onDblclick` / `onContextmenu`。
2. **自动选服**：`onMounted` 在 `loadServers()` 后调用 `resolveInitialServerId()`（URL → sessionStorage → 第一台），并 `browse()`。
3. **记忆服务器**：`onServerChange` 写入 `sessionStorage` 键 `nexus:files:last_server_id`。
4. **列表加载**：`useServerList` 改用 `http.getList`，兼容数组与 `{ items, total }`。

---

## 审计 8 步结果

### Step 1: 登记 ✅

已登记 3 个文件；变更动机与 changelog 一致。

### Step 2: 全文 Read ✅

- `FilesPage.vue`：template（工具栏、表格、对话框、FileEditorWorkbench）+ script setup 全量通读。
- `useServerList.ts`：全量 37 行。
- 交叉引用：`remotePath.ts`、`fileBrowse.ts`、`api/index.ts`（`getList`）未改，仅核对调用契约。

### Step 3: 规则扫描 H

| ID | 规则 | 扫描位置 | 命中 |
|----|------|----------|------|
| H1 | XSS（未消毒用户输入进 DOM） | `FilesPage.vue` template | 否 — 文件名来自 API，Vue 默认转义 |
| H2 | 凭据泄露 | sessionStorage、路由 query | 否 — 仅存 `server_id` 数字 |
| H3 | IDOR（越权 server_id） | `browse()`、`resolveInitialServerId` | 否 — 后端 JWT + `get_by_id`；前端校验 ID 在列表内（初始化路径） |
| H4 | 路径穿越（`../`） | `openEntry` 符号链接绝对路径 | 否（既有）— `normalizeRemotePath`；穿越依赖 SSH 返回的 link_target，属管理员可信面 |
| H5 | 静默吞错 | `useServerList` catch | 既有模式 — `servers=[]`，页面有空状态提示 |
| H6 | 事件委托冲突（checkbox/按钮误触发行导航） | `fileRowProps` | 已缓解 — `isRowActionTarget` + `closest` |
| H7 | Vuetify API 废弃 | `@click:row` | 已修复 — 改用 `row-props` |
| H8 | 未选服务器调用 API | `browse()` | 否 — 入口 `if (!selectedServer.value) return` |
| H9 | 双击/单击竞态 | 目录行 click + dblclick | 否 — `onRowDblClick` 仅处理 `file` 类型 |
| H10 | sessionStorage 污染 | `FILES_LAST_SERVER_KEY` | 否 — 写入前 `onServerChange` 有值；读取时 `serverList.some` 校验 |
| H11 | 类型安全 | `fileRowProps(data)` | 可接受 — `data.item` 与 `FileEntry` 一致 |
| H12 | 常量声明顺序 | `FILES_LAST_SERVER_KEY` 在 `onServerChange` 之后 | 见 Closure — 运行时无 TDZ 问题，可读性欠佳 |

### Step 4: Closure 表

| H | 判定 | 依据 |
|---|------|------|
| H1 | 通过 | 无 `v-html`；`{{ item.name }}` 等文本插值 |
| H2 | 通过 | `sessionStorage` 仅 `String(serverId)` |
| H3 | 通过 | `resolveInitialServerId` L857-868：`Number.isFinite` + `serverList.some`；API 仍由后端鉴权 |
| H4 | 通过（既有） | 符号链接绝对路径 L751-752 走 `normalizeRemotePath`；后端 `sync_v2.browse_directory` 亦有规范化 |
| H5 | 通过（既有） | `useServerList` L29-30 与多页一致；Files 页 `onMounted` L1363-1365 有 snackbar |
| H6 | 通过 | `isRowActionTarget` L891-894 排除 `.v-selection-control, .v-btn, …` |
| H7 | 通过 | L187 `:row-props="fileRowProps"`；L896-914 实现与 Vuetify 4 `RowPropsFunction` 一致 |
| H8 | 通过 | `browse` L800-801；`navigateToPath` L759-762 |
| H9 | 通过 | `onRowDblClick` L923-926 仅 `isRegularFile` |
| H10 | 通过 | L861-866、L844-845 |
| H11 | 通过 | TypeScript `type-check` 已通过（本地构建前） |
| H12 | 建议 | `FILES_LAST_SERVER_KEY` 宜上移至 `// ── State ──` 区，非功能缺陷 |

**附带观察（非本次引入，不记 FINDING）**：

- `watch(route.query.server_id)` L1378-1390 未校验 `serverList`，非法 `?server_id=abc` 可能得到 `NaN`（原逻辑已存在）。建议在后续小改中与 `resolveInitialServerId` 对齐。

### Step 5: 入口表

| 入口类型 | 位置 | 说明 |
|----------|------|------|
| 用户点击 | `fileRowProps.onClick/onDblclick/onContextmenu` | 行级导航/编辑/菜单 |
| 用户选择 | `v-select` `selectedServer` | 切换服务器 → `onServerChange` |
| 路由 query | `server_id`, `path` | `onMounted` / `watch` / `syncRouteQuery` |
| sessionStorage | `nexus:files:last_server_id` | 恢复上次服务器 |
| HTTP GET | `/servers/` | `useServerList.loadServers` |
| HTTP POST | `/sync/browse` 等 | 既有文件操作（未改契约） |

### Step 6: 输入 → Sink

```
[URL server_id / sessionStorage / 默认第一台]
  → resolveInitialServerId (校验 ∈ serverList)
  → selectedServer
  → browse() → POST /sync/browse { server_id, path }
  → 后端 JWT + ServerRepository + SSH ls

[行点击 item.name]
  → openEntry → joinRemotePath + normalizeRemotePath
  → browse()（同上）

[行点击 非目录]
  → onRowClick 无操作（仅目录/符号链接）

[双击文件]
  → editFile → readRemoteFileContent → FileEditorWorkbench
```

**控制措施**：路径片段经 `joinRemotePath`/`validatePathSegment`；服务器 ID 初始化路径白名单校验；API 鉴权在后端。

### Step 7: 归类

```
FilesPage.vue           1429行  12H  0 FINDING
useServerList.ts            37行   1H  0 FINDING
changelog                    25行   0H  0 FINDING
────────────────────────────────────────────
总计                      13H   0 FINDING
```

### Step 8: DoD ✅

| 维度 | 项 | 结果 |
|------|-----|------|
| 安全 | 无新增 XSS/IDOR/凭据泄露 | ✅ |
| 逻辑 | 目录单击可进入；无 server 时自动选服并 browse | ✅ |
| 逻辑 | 复选框/操作列不误触发目录进入 | ✅ |
| 性能 | `row-props` 每行创建闭包（与 Vuetify 常规用法一致） | ✅ |
| 质量 | TS type-check | ✅（实现时已通过） |
| 质量 | `FILES_LAST_SERVER_KEY` 声明位置 | ⚠️ 建议上移（不阻断） |
| 文档 | changelog ≥10 行 | ✅ |
| 部署 | 生产 tar 需在 WSL/Git Bash 重跑；prune 路径为仓库根 `deploy/prune_frontend_assets.py` | ⚠️ 运维注意 |

---

## FINDING 列表

无（0 FINDING）。

---

## 审查 4 维度（摘要）

### 安全（12 项抽样）

- JWT 请求经既有 `http` 客户端 ✅
- 不在前端存储 SSH 密码 ✅
- `server_id` 仅数字、列表内校验（初始化） ✅
- 行事件不执行 `eval`/动态 HTML ✅

### 逻辑（8 项）

- 根因：Vuetify 4 无 `click:row` → 已用 `row-props` 修复 ✅
- 根因：无 query 不 browse → 已自动选服 ✅
- 空服务器列表提示 ✅
- 符号链接相对路径不盲目 navigate ✅

### 性能（5 项）

- `displayedFiles` 仍为 computed 过滤，未增加额外请求 ✅
- `preloadDirectoryFiles` 行为未改 ✅

### 质量（5 项）

- 注释说明 Vuetify 4 变更原因 ✅
- `useServerList` 与 `SchedulesPage`/`RetriesPage` 列表解析策略统一 ✅
- 常量位置可优化（H12 建议）⚠️

---

## 结论

☑ **审计通过，0 FINDING，可合并/可部署**

**部署前提醒**（非代码缺陷）：

1. Windows `tar` 对 `-C web/app` 可能失败，请用 WSL 或 `deploy/deploy-frontend.sh` 打包上传。
2. 生产 prune：`cd /www/wwwroot/api.synaglobal.vip && python3 deploy/prune_frontend_assets.py`
3. 浏览器验证 `#/files` 后建议 **Ctrl+F5** 强刷。

**可选后续小改**（不阻断）：

- 将 `FILES_LAST_SERVER_KEY` 移至 state 区顶部。
- `watch(route.query.server_id)` 增加与 `resolveInitialServerId` 相同的列表校验。