# files.php 迭代 — 代码审查跟进项

> ⚠️ **已归档** — 2026-05-22
> 本文档审查的 PHP 文件 (api_proxy.php, files.php, webfm.php) 已被 Tailwind CSS v4 + Alpine.js 前端替代。
> 相关功能已迁移到: web/app/files.html + server/api/sync_v2.py
> 保留本文档供历史参考。

**审查日期**: 2026-05-19  
**审查范围**: `web/api_proxy.php`, `web/files.php`  
**审查结论**: 零 [必须修复] 项，可合入主干

---

## 建议修改 (4 项) — 下次迭代顺手改

### #1 api_proxy.php 重复鉴权加注释

**位置**: `web/api_proxy.php:22`  
**当前代码**:
```php
// Auth check: return 401 JSON for unauthenticated API requests
if (empty($_SESSION['logged_in'])) {
```

**改动**: 加一行说明这是兜底检查（auth.php 已处理主路径）
```php
// 兜底：auth.php 已校验 AJAX 请求，此处防止 auth.php 未拦截的边缘情况
if (empty($_SESSION['logged_in'])) {
```

**工时**: 1min

---

### #2 删除未使用的 `fm.uploadRaw`

**位置**: `web/files.php:208-210`  
**当前代码**:
```javascript
fm.uploadRaw=function(action,fd){
    return fetch(API+'?action='+action,{method:'POST',headers:{'X-Requested-With':'XMLHttpRequest'},body:fd});
};
```

**改动**: 删除这 3 行。上传已用 XHR 直接处理，此函数未被任何代码调用。

**工时**: 1min

---

### #3 toast 元素残留清理

**位置**: `web/files.php:213-214` (`fm.load` 函数开头)  
**问题**: 用户在上传完成前离开页面（点面包屑导航等），上传 toast 不会自动移除。

**改动**: 在 `fm.load` 开头加一行清理：
```javascript
fm.load=async function(path){
    // 清理残留的上传 toast
    document.querySelectorAll('div[style*="z-index:9999"]').forEach(function(el){el.remove();});
    state.path=path||state.path;
    // ...
```

**工时**: 5min

---

### #4 ACE 本地化

**位置**: `web/files.php:189`  
**原方案**: CDN 引入 cdnjs  
**决策**: 改为本地文件 `web/ace/ace.js` (444KB)，不依赖外部 CDN  
**状态**: ✅ 已实施  
**附带好处**: CDN fallback 提示无需再做（本地文件始终可用）

---

## 仅供参考 (2 项) — 不改也行

### #5 `done` 闭包变量加注释

**位置**: `web/files.php:363`  
**说明**: `done` 在单线程事件循环中不会有竞态，但要让维护者明白。加一行注释即可：
```javascript
let total=files.length, done=0, errors=[];
// done 在所有 XHR 回调中共享，JS 单线程保证无竞态
```

### #6 CORS origin 精确匹配

**位置**: `web/api_proxy.php:13`  
**说明**: `strpos($origin, $serverHost)` 在子域名场景可能误判。当前影响极低（同源策略 + 鉴权已有保护），如有跨子域需求时再改用 `parse_url` 精确比较。

---

## 待确认 (1 项) — 已决策

### #7 `restart_nexus` 端点 — ✅ 保留

**位置**: `web/api_proxy.php:227-229`  
**决策人**: 用户 — 2026-05-19  
**决策**: **保留**（已恢复）  
**依据**: 运维管理后台场景下，Web 重启是合理需求；鉴权已到位

---

---

## WebFM 集成审查 (2026-05-19)

### #8 未登录 `<meta refresh>` → PHP header — [必须修复]

**位置**: `web/webfm.php:1076`
**建议**: PHP header 跳转，避免加载整个 `<head>` 后再跳转

### #9 safePath 标准已确立 — ✅

**结论**: api_proxy.php 的做法是对的——不存在时返回原始路径 `$p`，父目录 `realpath` 兜底。已写入设计标准 §4。

### #10 logout 跳转 login.php — [建议修改]

**位置**: `web/webfm.php:357`
**现状**: `session_destroy()` 后跳回 `$self` (webfm.php)，多跳一次才到 login.php

---

## 执行计划

| 项 | 类型 | 工时 | 执行 |
|----|------|------|------|
| #1-#4 | 下次迭代一并改 | 12min | 工程部 |
| #8 | 改 meta→header | 1min | 工程部 |
| #10 | logout 跳转 | 1min | 工程部 |
| #5-#6 | 不改也能合 | — | — |
| #7 | 等产品决策 | — | 产品部 |
