系统文件夹与缩略图：前后端统一模型与实现笔记

1.1 针对系统文件夹本身的写入限制

整体目标：系统文件夹本身是“只读结构”，不能被当成普通目录乱写。

1. 上传文件：不能上传到系统文件夹

   文件：core/internal/api/server.go:290-299

   • uploadFile 中：
     • 从表单获取 path，默认 /
     • 如果 isSystemFolderPath(path)：
       • 返回 400 {"error": "system folder cannot be modified"}

2. 创建文件夹：不能在系统文件夹下建子目录

   文件：core/internal/api/server.go:636-642

   • createFolder 中：
     • 请求里的 req.Path 为空则归一化为 /
     • isSystemFolderPath(req.Path) 为真时：
       • 返回 400 {"error": "system folder cannot be modified"}

3. 移动文件 / 文件夹：目标路径不能是系统文件夹，源不能是系统文件夹本身

   文件：core/internal/api/server.go:736-763（moveFiles）

   • 约束：
     • req.TargetPath 为空则归一化为 /
     • 若 isSystemFolderPath(req.TargetPath)：
       • 返回 400 {"error": "system folder cannot be modified"}
     • 遍历 req.FileIDs，对每个源文件：
       • 如果 file.IsDir && file.IsSystemFolder：
         • 返回 400 {"error": "system folder cannot be modified"}
       • 其它目录正常处理（包括级联更新子路径）

4. 复制文件 / 文件夹：同样禁止目标是系统文件夹，禁止复制系统文件夹本身

   文件：core/internal/api/server.go:840-870（copyFiles）

   • 约束与 moveFiles 对齐：
     • 目标路径是系统文件夹 → 拒绝
     • 源是 IsDir && IsSystemFolder → 拒绝

5. 删除文件 / 文件夹：禁止删除系统文件夹

   文件：core/internal/api/server.go:526-590（deleteFile）

   • 读取元数据后，如果：
     • file.IsDir && file.IsSystemFolder：
       • 返回 400 {"error": "system folder cannot be modified"}
       • 不删元数据、不删 S3 对象

结论：

• 系统文件夹本身（例如“缩略图”）：
  • 不能作为上传 / 新建文件夹的目标路径
  • 不能被 moveFiles、copyFiles、deleteFile 当作普通目录和文件夹处理
• 这是“第一层防护”：保护系统目录结构不被破坏

2.1 基础缩略图 API（已有）

路由注册：core/internal/api/server.go:195-200

• POST /api/v1/thumbnails/:id → uploadThumbnail
  • 用于客户端自动生成缩略图后上传，不面向手动上传。
  • 行为：
    • 读取表单字段 file
    • 用 fileID+"#thumb" 派生加密 key
    • 加密写入 thumbs/{fileID}.enc
• GET /api/v1/thumbnails/:id → downloadThumbnail
  • 读取 thumbs/{id}.enc，解密成 JPEG 返回。
• DELETE /api/v1/thumbnails/:id → deleteThumbnail
  • 删除 thumbs/{id}.enc
• GET /api/v1/thumbnails → listThumbnails
  • 列出 thumbs/ 下所有对象，返回：
    • ID（去掉 .enc 后的 id）
    • Size
    • Time（最近修改时间）

这些接口只作用于缩略图对象，不修改任何源文件对象 files/*。

2.2 新增：导出缩略图为普通文件（复制 / 移动略缩图）

需求：

• 略缩图视图中的“文件”（虚拟条目）应当支持：
  • 复制出来 → 变成一个真正的小图文件
  • 移动出来 → 变成一个真正的小图文件，同时删除对应略缩图
• 严格保证：操作只基于略缩图对象本身，不对源文件做任何改动

type ExportThumbnailRequest struct {
	TargetPath     string `json:"targetPath"`
	Name           string `json:"name"`
	DeleteOriginal bool   `json:"deleteOriginal"`
}

3.1 AppState 中的缩略图虚拟目录

文件：client/lib/core/state/app_state.dart:1000-1070, 2066-2085

• 路径常量：

  • _thumbsPath = "/缩略图/"

• 当前目录下文件：

  • currentFiles：
    • 当 _currentPath == _thumbsPath 时：
      • 返回 _thumbFiles 的排序版本（虚拟文件列表）
    • 否则：返回普通 _files 过滤结果

• 刷新缩略图列表：

  文件：app_state.dart:2066-2085

  Future<void> refreshThumbnails() async {
    if (_isOffline) return;
    final res = await api.listThumbnails();
    ...
    _thumbFiles = res.data!.map((t) {
      final metaIndex = _files.indexWhere((f) => f.id == t.id);
      final name = metaIndex >= 0 ? _files[metaIndex].name : t.id;
      return FileMetadata(
        id: t.id,
        name: name,
        path: _thumbsPath,
        size: t.size,
        encryptedSize: 0,
        isDir: false,
        mimeType: 'image/jpeg',
        createdAt: now,
        updatedAt: t.time,
      );
    }).toList();
    notifyListeners();
  }

• 这里的 _thumbFiles 就是“虚拟的略缩图文件”，对应后端 listThumbnails 的返回。

3.2 前端 API 封装：导出缩略图

文件：client/lib/core/api/api_client.dart:271-305

已有接口：

• listThumbnails
• getThumbnail
• uploadThumbnail（客户端自动生成略缩图后上传用）
• deleteThumbnail

新增接口：

Future<ApiResult<FileMetadata>> exportThumbnail({
  required String fileId,
  required String targetPath,
  required String name,
  bool deleteOriginal = false,
})

• 对应后端 POST /api/v1/thumbnails/:id/export
• 请求体包含 targetPath / name / deleteOriginal
• 返回值是后端生成的新普通文件的 FileMetadata

3.3 系统文件夹本身的 UI 保护

文件：client/lib/ui/files_page.dart

几个核心约束：

1. 多选时不包含系统文件夹

   • “全选”只选非系统文件夹：

     files_page.dart:359-371

     final ids =
         state.currentFiles.where((f) => !f.isSystemFolder).map(
               (f) => f.id,
             );

   • “反选”同样基于非系统文件夹：

     files_page.dart:373-384

     final allIds = state.currentFiles
         .where((f) => !f.isSystemFolder)
         .map((f) => f.id)
         .toSet();

2. 系统文件夹不参与长按选中

   files_page.dart:1060-1065

   • 列表视图长按：
     • 若 file.isSystemFolder，直接返回，不进入 _selectionMode

   files_page.dart:2116-2121

   • 网格视图：
     • 选择模式下点击系统文件夹无效
     • 长按系统文件夹无效

3. 系统文件夹不出现在“选择目标目录”列表中

   files_page.dart:1211-1219

   final dirs =
       state.files.where((f) => f.isDir && !f.isSystemFolder).toList();

   • 复制 / 移动时，目标目录对话框不会列出“缩略图”等系统文件夹。

4. 系统文件夹没有“重命名 / 删除”按钮

   底部操作单 _FileActionSheet：

   files_page.dart:1870-1902

   • 只有在 !file.isSystemFolder 时才显示“删除”
   • 只有在 !file.isSystemFolder && !isThumbFolder 时才显示“重命名”

   这样根目录的“缩略图”文件夹视图中，只会展示安全操作（比如详情），没有破坏性入口。

3.4 略缩图视图中对“文件本身”的操作

重点是 /缩略图/ 路径下的行为。