docs: files.html 全面迭代 changelog

2026-05-30 23:36:49 +08:00
parent 14131f98f0
commit ac38442383
1 changed files with 101 additions and 0 deletions
@@ -0,0 +1,101 @@
+# Changelog — files.html + sync_v2.py 全面迭代
+
+**日期**: 2026-05-30  
+**Commit**: 14131f9  
+**类型**: 安全加固 + 功能补全 + UX 全面改进  
+**涉及文件**:
+- `server/api/sync_v2.py` — 符号链接解析 + 新增 3 个端点
+- `server/api/schemas.py` — 新增 FileDownload/FileRead/FileWrite schema
+- `web/app/files.html` — 前端全面重写
+
+## 后端变更 (sync_v2.py)
+
+### P2-1/P3-2: 符号链接解析
+- `ls -la` 解析逻辑新增 `is_link` 字段（检测 `l` 权限）
+- 符号链接文件名 `name -> target` 分离为 `name` + `link_target`
+- 响应新增 `is_link` 和 `link_target` 字段
+
+### P2-7: 新增 `/api/sync/download` 端点
+- 通过 SFTP 流式下载远程文件
+- 使用 `StreamingResponse` + 64KB chunk 避免内存膨胀
+- 审计日志记录
+
+### P2-8: 新增 `/api/sync/read-file` + `/write-file` 端点
+- `read-file`: `stat` 检查大小 → `cat` 读取内容，限制 1MB
+- `write-file`: base64 编码内容避免 shell 注入，`echo | base64 -d | tee` 写入
+- 两个端点均有审计日志
+
+## 前端全面重写 (files.html)
+
+### P1-1: 目录删除二次确认
+- 目录删除：自定义模态框 + 要求输入目录名确认
+- 文件删除：自定义确认模态框
+
+### P2-2/P2-3: 事件委托
+- 移除所有内联 `onclick="..."` 字符串拼接
+- 改用 `data-action` + `data-path` + `data-name` 属性
+- 统一事件委托 `fileListEl.addEventListener('click', ...)`
+- 彻底消除 XSS 向量
+
+### P2-4: 上传进度条
+- `XMLHttpRequest.upload.onprogress` 实时进度
+- 顶部进度条显示当前文件名 + 百分比 + 进度条动画
+
+### P2-5: 文件大小可读化
+- `formatSize()` 函数：字节 → B/KB/MB/GB
+- 保留 1 位小数
+
+### P2-6: 文件类型图标
+- 30+ 文件扩展名映射
+- `.py`→🐍 `.jpg`→🖼️ `.tar.gz`→📦 `.log`→📊 `.env`→🔒 等
+
+### P2-7: 文件下载
+- 每行 hover 显示 ⬇ 下载按钮
+- 点击触发 SFTP 下载 → 浏览器保存文件
+
+### P2-8: 文件预览/编辑
+- 每行 hover 显示 👁 预览按钮
+- 点击读取文件内容 → 模态框显示 + textarea 编辑 + 保存
+
+### P2-9: 自定义模态框
+- 完全替代原生 `prompt()` / `confirm()`
+- Tailwind 样式：暗色主题 + backdrop blur + 圆角
+- 支持：文本提示 / 输入框 / 多行编辑 / 危险操作红色样式
+
+### P2-10: 批量操作
+- 每行开头 checkbox + 表头全选
+- 选中时底部出现批量操作栏（计数 + 批量删除 + 取消）
+
+### P3-1: 文件搜索
+- 面包屑右侧搜索框
+- 前端实时过滤文件名
+
+### P3-2: 符号链接显示
+- 🔗 图标 + cyan 颜色
+- hover 显示 `→ target` tooltip
+
+### P3-3: 空目录状态
+- 📂 大图标 + 提示文字 + 「上传文件」引导按钮
+
+### P3-4: 服务器刷新
+- 🔄 按钮在服务器下拉旁，点击重新加载列表
+
+### P3-5: 操作 loading
+- 上传期间顶部进度条持续显示
+- 浏览期间文件列表显示 ⏳ 加载动画
+
+## 验证结果
+
+| 测试 | 结果 |
+|------|------|
+| 健康检查 | ✅ ok |
+| 页面加载 | ✅ 0 errors |
+| 浏览 /tmp | ✅ 文件列表+图标+大小正确 |
+| 符号链接 mysql.sock | ✅ 🔗 图标 |
+| 面包屑 | ✅ /tmp 路径 |
+| 搜索框 | ✅ 存在 |
+| 全选 checkbox | ✅ 存在 |
+| 操作按钮 | ✅ 👁 ⬏ ✏ 🗑 |
+
+## 是否需迁移/重启
+- 需要重启后端服务（新增 3 个 API 端点）