2026-10-24 23:20:20 +08:00
parent dd7612bc74
commit e555610037
15 changed files with 1154 additions and 16 deletions
@@ -0,0 +1,33 @@
+# ADR-0005：页面内目录浏览器
+
+- 状态：已接受（取代早期"后端弹出系统对话框"方案）
+- 日期：2026-10-24
+
+## 背景
+
+任务的工作目录必须是绝对 Windows 路径。浏览器的文件选择控件出于安全限制只暴露文件名或伪造路径，拿不到用户所选目录的真实绝对路径。
+
+最初尝试由后端调用 `IFileOpenDialog` 弹出系统文件夹对话框，但代价明显：需要新增 `windows` crate；对话框属于后端进程而不属于浏览器窗口，可能被浏览器挡住；接口会长时间挂起；自动化测试无法覆盖。对于一个本机 Web 应用，这些都不划算。
+
+## 决策
+
+1. 在页面内实现目录浏览器：`DirectoryPickerDialog` 弹窗，盘符 → 逐级进入 → 「使用此目录」。
+2. 后端只提供只读列表接口 `GET /api/v1/system/directories?path=<绝对路径>`，路径为空时返回盘符。
+3. 响应包含 `path`（当前目录）、`parent`（上一级，盘符根为 null）、`entries`（仅子文件夹，按名称排序）、`truncated`（超过 500 项）。
+4. 弹窗顶部保留可编辑的路径输入框，支持直接粘贴绝对路径后回车跳转；「上一级」「盘符」用于层级导航。
+5. 选中结果通过 `setValue` 回填输入框并触发虚拟环境重新探测；输入框始终可编辑，二者不互斥。
+6. 列表接口是只读的，与任务列表一样免令牌；不存在的路径返回 `400 DIRECTORY_NOT_FOUND`，相对路径返回 `400 DIRECTORY_PATH_INVALID`，无权限返回 `400 DIRECTORY_UNREADABLE`。
+
+## 原因
+
+- 纯前端就能完成交互，不依赖桌面会话，Windows 服务模式下同样可用。
+- 不引入新依赖，也不需要 COM 线程管理。
+- 弹窗属于页面本身，不会被浏览器遮挡，焦点和键盘行为可控。
+- 可以被 Vitest 和 Playwright 完整覆盖。
+
+## 边界
+
+- 只列文件夹，不列文件；隐藏目录（如 `.venv`）会正常显示，便于选择虚拟环境目录。
+- 目录读取失败时停留在原目录并提示原因，不做静默降级。
+- 单个目录最多返回 500 个子文件夹，超出时提示截断。
+- 列表接口只做只读列举；真正执行脚本时仍需任务配置中的绝对路径通过后端校验。