steven_li
2c5205b06e
- 添加MinIO用户文件系统配置选项(BEAVER_MINIO_ROOT_USER等) - 更新外部连接器配置结构，包括BASE_URL和认证令牌设置 - 改进connector provider支持更多类型(official, feishu_bot等) - 实现Mistral模型推理模式支持reasoning_effort参数 - 增强外部连接器策略配置和运行时配置管理 - 添加connector bridge事件验证和安全保护机制 - 优化任务路由逻辑，区分simple_chat和new_task场景 - 更新初始技能工具提示配置，分离authoring admin功能
121 lines
6.6 KiB
Markdown
121 lines
6.6 KiB
Markdown
# 主应用：文件页 UI/UX
|
||
|
||
## 1. 页面定义
|
||
|
||
| 项目 | 内容 |
|
||
| --- | --- |
|
||
| 页面名称 | 文件管理 |
|
||
| 路由 | `/files` |
|
||
| 页面实现 | `app-instance/frontend/app/(app)/files/page.tsx` |
|
||
| 关键组件 | `FilesPage`、`FilePreviewPanel`、`FileIcon`、`ScrollArea` |
|
||
| 核心任务 | 浏览目录、创建文件夹、上传文件、预览文本/Markdown/图片/二进制文件、下载文件、删除文件或目录 |
|
||
| 测试状态 | 已修复并复测通过；本地与 `terminaltest` 生产实例均通过 |
|
||
|
||
## 2. 信息架构与组件层级
|
||
|
||
```text
|
||
AppShell
|
||
└── main.pt-16
|
||
└── /files
|
||
├── Page Header
|
||
│ ├── h1 Files
|
||
│ ├── New folder
|
||
│ ├── Upload
|
||
│ ├── hidden file input
|
||
│ └── Refresh
|
||
├── Breadcrumbs
|
||
│ ├── Files root
|
||
│ └── 当前路径 segments
|
||
├── New directory form
|
||
│ ├── Folder name input
|
||
│ ├── Create
|
||
│ └── Cancel
|
||
└── Content grid
|
||
├── File list panel
|
||
│ ├── Loading state
|
||
│ ├── Error state + Retry
|
||
│ ├── Empty state
|
||
│ └── File / Directory rows
|
||
│ ├── Open / Preview primary button
|
||
│ ├── Download
|
||
│ └── Delete
|
||
└── FilePreviewPanel
|
||
├── Empty preview
|
||
├── Loading preview
|
||
├── Error preview
|
||
├── File metadata
|
||
├── Download
|
||
├── Image preview
|
||
├── Markdown preview
|
||
├── Text preview
|
||
└── Binary fallback
|
||
```
|
||
|
||
## 3. 布局与响应式规则
|
||
|
||
- 页面外层使用 `max-w-7xl`，移动端内边距为 `16px`，桌面端为 `24px`。
|
||
- 内容区默认单列，`lg` 以上改为左侧文件列表、右侧预览双栏。
|
||
- 左侧文件列表和右侧预览都使用 `min-w-0`，避免长文件名、Markdown、代码块撑破页面。
|
||
- 文件行移动端为上下结构：上方文件信息，下方下载/删除操作；`sm` 以上恢复横向布局。
|
||
- 下载/删除在移动端始终可见，桌面端保留 hover 显示。
|
||
- 根目录也允许创建文件夹和上传文件；空态文案与按钮行为一致。
|
||
- 面包屑、文件行主按钮、下载、删除、创建、取消、刷新等主要可点击目标均为 `44px` 以上。
|
||
|
||
## 4. 操作与 UX 逻辑
|
||
|
||
| 操作 | 触发方式 | 状态变化与反馈 | UX 目的 | 当前结果 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 刷新文件列表 | 点击 Refresh | 调用 browse 接口重新加载当前路径 | 获取最新目录状态 | 正常 |
|
||
| 根目录新建文件夹 | 点击 New folder，输入名称，点击 Create | 调用 mkdir，成功后刷新列表 | 空 workspace 也能开始组织文件 | 正常 |
|
||
| 根目录上传文件 | 点击 Upload，选择文件 | 调用 upload，显示进度并刷新列表 | 空 workspace 也能添加文件 | 正常 |
|
||
| 进入目录 | 点击目录主区域 | 调用 browse，更新 breadcrumbs 和列表 | 浏览层级文件 | 正常 |
|
||
| 返回上级或根目录 | 点击 breadcrumbs | 调用 browse 对应路径 | 快速导航 | 正常 |
|
||
| 预览文件 | 点击文件主区域 | 调用 preview，右侧显示内容 | 快速查看文件 | 正常 |
|
||
| 下载文件 | 点击文件行或预览区 Download | 调用 download，浏览器下载 blob | 获取原始文件 | 正常 |
|
||
| 删除文件/目录 | 点击 Delete 并确认 | 调用 delete，成功后从列表移除 | 管理文件空间，防误删 | 正常 |
|
||
| 加载失败 | browse 接口失败 | 显示错误、详情和 Retry | 明确异常恢复路径 | 正常 |
|
||
| 二进制文件预览 | 文件不可预览 | 显示不可直接预览提示 | 避免乱码 | 正常 |
|
||
|
||
## 5. 响应式测试矩阵
|
||
|
||
测试日期：2026-06-04。浏览器：Playwright Chromium。环境：本地 dev server `http://127.0.0.1:3080` 与生产实例 `terminaltest`；API 使用模拟数据，真实浏览器执行点击、上传入口、目录切换、预览、下载、删除确认和截图。
|
||
|
||
| 页面/状态 | 视口 | 横向越界 | 小触控目标 | 关键结论 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 根目录空态 | `390×844` | 无 | 0 | New folder 和 Upload 在根目录可用 |
|
||
| 文件预览 | `390×844` | 无 | 0 | 可进入目录、预览 Markdown、下载、删除 |
|
||
| 加载错误 | `390×844` | 无 | 0 | 错误和 Retry 可见 |
|
||
| 文件预览 | `320×568` | 无 | 0 | 长文件名、操作按钮、Markdown 预览均未撑破页面 |
|
||
| 文件预览 | `390×844` | 无 | 0 | 手机竖屏布局清晰 |
|
||
| 文件预览 | `844×390` 横屏 | 无 | 0 | 横屏无页面级横向滚动 |
|
||
| 文件预览 | `768×1024` | 无 | 0 | 平板布局稳定 |
|
||
| 文件预览 | `1365×900` | 无 | 0 | 桌面双栏布局正常 |
|
||
|
||
### 关键量化证据
|
||
|
||
- 本地文件页 QA 自动化用例 `4 passed`。
|
||
- 部署到 `terminaltest` 后，同一套文件页 QA 自动化用例 `4 passed`。
|
||
- 根目录空态中 `New folder` 和 `Upload` 均为 enabled。
|
||
- 创建文件夹调用 `/api/user-files/mkdir?path=docs`。
|
||
- 下载调用 `/api/user-files/download`。
|
||
- 删除调用 `/api/user-files/delete`，并经过浏览器确认。
|
||
- 实测 `320×568`、`390×844`、`844×390`、`768×1024`、`1365×900` 均无页面级横向越界。
|
||
- 所有实测视口可见小触控目标数为 `0`。
|
||
|
||
## 6. 已修复问题
|
||
|
||
| 等级 | 问题 | 修复 |
|
||
| --- | --- | --- |
|
||
| P1 | 根目录空态提示可上传/新建，但按钮被禁用 | 根目录允许 New folder 和 Upload |
|
||
| P1 | `320px` 下文件列表被 `minmax(360px,440px)` 和长文件名撑破页面 | 默认单列改为 `minmax(0,1fr)`，列表和预览加 `min-w-0` |
|
||
| P1 | 文件行里嵌套下载/删除 role button，移动端不可发现且触控小 | 改为主打开按钮 + 独立下载/删除按钮，移动端始终可见 |
|
||
| P2 | 文件行长文件名与操作按钮互相挤压 | 移动端文件行改为信息在上、操作在下 |
|
||
| P2 | Refresh 是 icon-only 且缺少可访问名称 | 补充 `aria-label/title`，命中区为 `44px` |
|
||
| P2 | 面包屑按钮和文件主按钮触控高度不足 | 固定为 `44px` 以上 |
|
||
| P2 | Markdown/text 预览长内容可能撑破页面 | 预览区增加容器内换行和 preserved long text 规则 |
|
||
|
||
## 7. 剩余观察项
|
||
|
||
- 本轮自动化使用模拟 API 数据覆盖常见文件类型；真实大文件、超大图片、深层目录和上传失败恢复仍需持续观察。
|
||
- 浏览器原生下载行为只验证 download API 被调用，未校验操作系统保存结果。
|