u-desk/docs/02-架构设计/功能决策记录.md

功能决策记录

日常开发中对各功能做的细节取舍（功能粒度，补架构决策之下的实现层）。聚焦「为什么这么定」。 创建：2026-06-12 | 维护：随开发追加

来源：历史会话挖掘 + 当前会话。覆盖 u-desk 0.3.x → 0.4.x（fs-only-v3）开发期。

---

启动 / 关闭速度

ServiceStartup 非关键路径并行化

• 决策：SQLite + ConfigAPI 前置同步，PdfAPI/FileSystemService/CleanupExpiredCache/CleanupSiteCacheDirs 移入 goroutine 并行。
• 原因/取舍：前置依赖必须先就绪；非关键子系统串行会阻塞 Wails 窗口加载前端，并行后首屏不受拖累。
• 状态：✅ 已落地（app.go ServiceStartup）

审计日志懒初始化 ensureReady

• 决策：审计日志从启动全量初始化改为首条写入时才 ensureReady（开文件 + 起 flush 协程）。
• 原因/取舍：原 NewAuditLogger 启动即建目录/开文件/起协程拖慢启动。懒初始化零启动开销；用 mutex+initialized 标志替代 sync.Once，因 sync.Once 消费后不再执行、初始化失败后后续 Log 静默丢失。
• 状态：✅ 已落地（audit_log.go）

回收站 metadata 延迟加载

• 决策：回收站 metadata.json 从启动加载改为首次访问时 ensureLoaded。
• 原因/取舍：用户可能整个会话不用回收站；延迟加载减启动 IO 和内存。
• 状态：✅ 已落地（recycle_bin.go）

startFileServer 同步启动

• 决策：startFileServer 从 go a.startFileServer() 改为同步调用。
• 原因/取舍：该函数只注册 HTTP handler 不阻塞；异步启动反而有 handler 未注册完成时前端已请求的竞态。
• 状态：✅ 已落地（app_filesystem.go）

loadFromDB 延迟 500ms 自动连接

• 决策：loadFromDB 中系统信息采集 + 自动连接包进 setTimeout(500)。
• 原因/取舍：远程 profile 自动连接并发网络 IO 阻塞首屏；延迟 500ms 让空壳 UI 先渲染。代价：首屏 500ms 内远程不可用，且与 session restore 存在同 profile 双连接竞争（见连接管理域）。
• 状态：✅ 已落地（connection-manager.ts）

session restore 延迟到 rAF

• 决策：会话恢复（路径/连接）延迟到 requestAnimationFrame。
• 原因/取舍：onMounted 恢复阻塞 Vue 首帧渲染；rAF 让首帧先绘制再恢复。
• 状态：✅ 已落地（index.vue onMounted）

Markdown / highlight.js 动态懒加载

• 决策：marked + highlight.js 从静态 import 改为按需动态 import。
• 原因/取舍：两库 ~200KB+，全量导入阻塞首屏；文件预览是按需功能不应拖慢所有用户。代价：首次开 MD 有原文闪烁。
• 状态：✅ 已落地（markedExtensions.ts）

启动后 3s 延迟静默检查更新

• 决策：启动后 setTimeout(3000) 静默检查更新。
• 原因/取舍：启动即发网络请求增加首屏时间；延迟 3s 让 UI 先渲染，静默不弹窗。
• 状态：✅ 已落地（App.vue）

ServiceShutdown errgroup 并行 + 5s 总超时

• 决策：关闭用 errgroup 并行关 4 个子系统，共享 5s 总超时。
• 原因/取舍：原串行关闭耗时叠加；并行后总耗时取最慢子系统，5s 兜底防无限挂起。
• 状态：✅ 已落地（app.go ServiceShutdown）

热键轮询递增间隔

• 决策：热键轮询从固定 200ms 改为 50→100→200ms 递增。
• 原因/取舍：首检快 150ms（50ms 捕获），后续逐步放宽降 CPU。
• 状态：✅ 已落地（app.go）

---

文件删除 / 回收站

回收站优先策略

• 决策：删除文件时先尝试移入回收站，移动失败才永久删除。
• 原因/取舍：旧逻辑「先永久删除再移回收站」——文件已删，移回收站必然失败，回收站形同虚设。改为先移后删保证误删可恢复。永久删除仅在跨卷/权限失败时降级兜底。
• 状态：✅ 已落地（filesystem/service.go）

isInRecycleBin 用 HasPrefix

• 决策：判断路径是否在回收站内用 strings.HasPrefix 而非切片前缀比较。
• 原因/取舍：旧 cleanPath[:len(cleanBinPath)] 当 len(cleanPath) < len(cleanBinPath) 时切片越界 panic。HasPrefix 自带长度判断。
• 状态：✅ 已落地

回收站 entries 并发安全

• 决策：RecycleBin.entries 加 sync.Mutex，ListEntries 返回副本。
• 原因/取舍：autoCleanup 后台协程与用户操作并发读写 entries 存在竞争；返回副本避免外部遍历被 cleanup 修改 panic。
• 状态：✅ 已落地（recycle_bin.go）

随机字符串加索引偏移

• 决策：generateRandomString 每个字符对 nanoseed 加索引 i 偏移再取模。
• 原因/取舍：同一次调用内多字符同纳秒生成、seed 相同导致全串重复字符。加索引打破局部相同。非密码学随机，简单偏移足够。
• 状态：✅ 已落地（recycle_bin.go）

IsFileLocked 去 O_CREAT

• 决策：IsFileLocked 去掉 O_CREAT 改纯只读探测。
• 原因/取舍：O_CREAT 检查锁时会意外创建空文件——目标已删时被「复活」成 0 字节误导。纯探测不应有写入语义。
• 状态：✅ 已落地（file_lock.go）

---

远程 HTML 站点预览

确定性站点缓存目录

• 决策：远程 HTML 预览用 common.SiteCacheDir（SHA-256 哈希 transport+connID+path+size+modTime）生成确定性路径，命中直接返回；SFTP 与 OSS 统一。
• 原因/取舍：旧 OSS 方案每次 os.MkdirTemp 全量重下，二次打开仍慢。确定性哈希让同文件二次打开命中缓存，size+modTime 进哈希源文件变动自动失效。取舍：路径可预测（非随机名），去重收益远大于此。
• 状态：✅ 已落地（common/utils.go + ossdrv/sftp DownloadSiteForPreview）

资源下载范围演进

• 决策：全量下载 → 仅补充已发现资源所在目录 → supplementDir 限制 50 文件 / 单文件 5MB。
• 原因/取舍：用户指出「网站可能 100G」全量不可行；改为只补充资源所在目录（webpack chunk 等）。最终加 50 文件 + 5MB 上限防失控，SFTP/OSS 统一。
• 状态：✅ 已落地（sftp/service.go、ossdrv/service.go）

OSS 补充分页

• 决策：OSS supplementDir 列目录循环翻页（IsTruncated + NextMarker），取完或达上限止。
• 原因/取舍：旧 MaxKeys:200 单次调用，目录超 200 文件直接截断漏下载。分页保完整 + 上限防失控。
• 状态：✅ 已落地（ossdrv/service.go）

资源下载并发策略

• 决策：相对路径资源 8 并发、绝对路径资源串行。
• 原因/取舍：绝对路径 siteRoot 嗅探是共享状态需顺序探测；相对路径无依赖可并行。20 资源从 20×RTT 降到 ~3 轮；8 并发信号量防连接数爆炸。
• 状态：✅ 已落地（sftp/ossdrv DownloadSiteForPreview）

绝对路径 siteRoot 向上嗅探

• 决策：绝对路径 /assets/js/main.js 的根含义通过从 HTML 所在目录逐级向上尝试下载直到桶根来确定，非简单去 /。
• 原因/取舍：不同 HTML 的 / 可能指向不同根（多站点共存）；简单相对 HTML 目录在嵌套场景出错（pages/about.html 引 /assets/ 应到桶根而非 pages/assets）。
• 状态：✅ 已落地（ossdrv resolveAbsoluteResourcePath）

siteRoot 不跨 HTML 共享

• 决策：每个 HTML 独立嗅探 siteRoot，不跨调用共享。
• 原因/取舍：同桶多个不同网站的 / 可能指不同根；共享会跨站污染。
• 状态：✅ 已落地

路径重写：正则 → JS setter 拦截

• 决策：用 JS 拦截脚本覆盖 HTMLScriptElement.src 等 setter 重写绝对路径，替代 locationPathRegex 正则替换。
• 原因/取舍：正则替换 location.pathname 在 inline JS 字符串内破坏引号致 SyntaxError；正则无法处理 webpack 动态 import() chunk。setter 拦截覆盖静态 + 动态两种。
• 状态：✅ 已落地（asset_handler.go injectPathInterceptor）

拦截脚本 base 用 baseDir

• 决策：拦截脚本 base 直接用 HTML 文件所在目录，不用 findSiteRootDir 嗅探的网站根。
• 原因/取舍：SFTP 场景 findSiteRootDir 返回临时目录根，实际网站根在子目录；用 baseDir 与 transformHtmlResourcePaths 解析一致避免层级错位。
• 状态：✅ 已落地（asset_handler.go/sftp/service.go）

CSS MIME 按扩展名显式设置

• 决策：文件服务器按扩展名设 Content-Type（CSS → text/css），不依赖 http.DetectContentType。
• 原因/取舍：DetectContentType 对 CSS 返回 text/plain，浏览器 strict MIME checking 拒绝应用样式。
• 状态：✅ 已落地（asset_handler.go）

资源探测用 try-download

• 决策：用 try-download 探测资源存在性，而非先 GetFileInfo/Exists。
• 原因/取舍：七牛 GetFileInfo 可能走签名域名返回 EOF，接口无 Exists；直接尝试下载更稳妥，失败即跳过。
• 状态：✅ 已落地（ossdrv tryDownloadResource）

OSS HTML 预览路由：/proxy → /localfs

• 决策：OSS 的 HTML 预览从 /proxy/html-preview（远程代理路由）改为先下载到临时目录再用 /localfs/html-preview。
• 原因/取舍：本地文件服务器只注册了 /localfs/html-preview，/proxy/ 仅在 agent server；OSS 路径不是本地 FS 路径，代理路由无法处理。
• 状态：✅ 已落地（useFilePreview.ts htmlPreviewUrl）

仅 HTML 类型走整站流程

• 决策：仅 HTML 预览走独立整站下载流程，其他类型（图片/视频/音频）走 resolveWithTransport() 单文件。
• 原因/取舍：其他类型已通过 downloadForPreview+buildLocalUrl 走 /localfs/；只有 HTML 需下载关联资源。
• 状态：✅ 已落地（useFilePreview.ts）

HTML 资源正则收窄 + srcset 补全

• 决策：htmlResRegex 中 data 收窄为 data-src|data-url；新增 srcset 正则独立提取；排除 <a href> 导航链接和非资源扩展名。
• 原因/取舍：旧 data= 误匹配 data-id 等无关属性产生无效拉取；srcset 是响应式图片标准属性旧逻辑完全遗漏；<a href> 导航链接不应下载。
• 状态：✅ 已落地（common/utils.go、site_resource.go）

资源提取逻辑 DRY 统一

• 决策：OSS 和 SFTP 的 extractResources/shouldSkipResource 重复代码统一到 filesystem/site_resource.go。
• 原因/取舍：两 service 各复制一份相同逻辑违反 DRY；统一净减 114 行。
• 状态：✅ 已落地

---

七牛 OSS

域名分类：临时域名优先

• 决策：下载域名解析临时域名优先（按后缀 *.qiniudns.com/*.clouddn.com/*.qbox.me 分类），自定义域名降级。
• 原因/取舍：用户桶绑定的自定义域名不可达导致 EOF；临时域名更稳定。后缀 + 前缀双重匹配防误判。
• 状态：✅ 已落地（qiniu/client.go resolveDownloadDomain）

域名探测策略演进：TCP → HTTP HEAD → 移除

• 决策：域名可达性探测从 TCP 连接 → HTTP HEAD → 最终移除，改用签名 URL 直接下载。
• 原因/取舍：TCP 探测端口开放但 HTTP 返回 EOF 无法发现；HTTP HEAD 对 5xx 无法区分真假可用；签名 URL 可绕防盗链，探测逻辑不再需要。
• 状态：✅ 已落地（qiniu/client.go，probeDomain 已删）

签名 URL 绕防盗链

• 决策：Download 内部改用签名 URL 而非裸 HTTP GET；签名格式从 URL\ndeadline 修正为 URL?e=deadline。
• 原因/取舍：裸 GET 遇 CDN 防盗链（478）被拒；签名 URL 绕过防盗链；参照 kodo-browser 始终用签名 URL。
• 状态：✅ 已落地（qiniu/client.go GetSignedURL/Download）

region 从域名提取

• 决策：从 API 返回的临时域名提取真实 region（detectRegionFromDomains），不依赖用户配置的 config.Region。
• 原因/取舍：用户填的 Region 可能错误（填 z0 实际 as0），构造的降级域名不存在（502）；从 u-res-as0.qiniudns.com 提取才准确。
• 状态：✅ 已落地

跨账号桶返回错误

• 决策：resolveDownloadDomain 在 API 返回空域名列表时直接返回错误，不伪造 <bucket>-<region>.qiniudns.com。
• 原因/取舍：跨账号桶 GetBucketDomains 返回空，伪造域名不存在致 403；代码无法修跨账号问题。
• 状态：✅ 已落地

阿里云不适用此逻辑

• 决策：阿里云 OSS 不加域名探测/降级/签名 URL 逻辑。
• 原因/取舍：阿里云下载 URL 直接 <bucket>.<region>.aliyuncs.com，endpoint 固定官方域名始终可达；用户要求不影响阿里云正确访问。
• 状态：✅ 已落地

---

阿里云 OSS

手动签名不用官方 SDK

• 决策：采用手动签名，不引入阿里云官方 SDK。
• 原因/取舍：项目已有手动签名实现，避免重量级 SDK 依赖；需自行处理 base64（StdEncoding→URLEncoding）、URL 编码（PathEscape + QueryEscape）。
• 状态：✅ 已落地（oss/aliyun/client.go）

endpoint 信任用户配置

• 决策：endpoint 直接传用户配置值，信任用户配置，不自动清空/覆盖。
• 原因/取舍：旧代码 region 非空时清空 endpoint 让 NewClient 从 region 派生，破坏 VPC/自定义域名场景；改为信任配置，NewClient 在 endpoint 空时才从 region 派生（已有此逻辑）。
• 状态：✅ 已落地（ossdrv/service.go）

region 全量缓存 + 探测

• 决策：Connect() 时立即缓存所有桶 region 到 bucketRegions，未命中时主动 ListBuckets 探测。
• 原因/取舍：app 重启后直接跳上次浏览的桶时缓存无数据，客户端用默认 hangzhou 创建致跨 region 访问失败。
• 状态：✅ 已落地（oss/aliyun/）

缓存 key：GetFileInfo 失败直接报错

• 决策：DownloadToTemp 中 GetFileInfo 失败时直接返回错误，不静默降级用空 modTime。
• 原因/取舍：原失败时用空 modTime 继续生成 key，失败/成功状态产生不同 key 永远命中不了缓存；确定报错让调用方明确处理。
• 状态：✅ 已落地（ossdrv/service.go DownloadToTemp）

Last-Modified 解析填入 FileInfo

• 决策：解析阿里云 HEAD 响应的 Last-Modified 头填入 FileInfo（原 _ = 丢弃）。
• 原因/取舍：丢弃致 LastModified 永远零值，缓存 key 用零值格式化后不稳定（失败/成功 key 不同），永远命中不了已有缓存。
• 状态：✅ 已落地（oss/aliyun/client.go GetFileInfo）

---

缓存管理

预览缓存：前端 LRU Map → 后端 SQLite 24h

• 决策：预览缓存从前端 LRU Map（上限 50）迁移到后端 SQLite，键 (transport, connID, remotePath, fileSize, modTime)，24h TTL。
• 原因/取舍：前端 JS Map 重启即丢失且无过期；后端 SQLite 重启后仍有效，size+modTime 进键源文件变动自动失效。
• 状态：✅ 已落地（storage/download_cache.go）

站点缓存清理时机：启动 + 关闭

• 决策：站点预览缓存在启动和关闭时各清理一次 24h 过期目录，不引入后台定时器。
• 原因/取舍：站点缓存用户驱动低频，不需常驻 goroutine 轮询；启停各清一次覆盖典型生命周期。同时清遗留旧随机目录 udesk-site-*。
• 状态：✅ 已落地（download_cache.go CleanupSiteCacheDirs + app.go）

内容类型检测缓存 200 条满清空

• 决策：contentDetectCache 加 200 条上限，满时整体 clear()（非逐条 LRU）。
• 原因/取舍：无上限会内存泄漏；选「满即清空」非真 LRU——文件类型检测重复命中率低、清空成本低、实现简单。
• 状态：✅ 已落地（useFilePreview.ts）

面包屑目录缓存 200 条

• 决策：面包屑悬停子目录列表用 Map<path, result> 缓存，限 200 条。
• 原因/取舍：悬停需频繁查询，缓存避免重复网络请求；只缓存目录（悬停只展示可导航子目录）。
• 状态：✅ 已落地（PathBreadcrumb.vue dirCache）

CodeEditor 滚动位置缓存

• 决策：滚动位置 LRU 最多 5 份，每份 3min 过期。
• 原因/取舍：文件切换保留编辑位置提升体验；5 份对应最近 5 文件，3min 过期避免长期占内存。
• 状态：✅ 已落地（CodeEditor.vue）

---

错误处理策略

GetFileInfo 错误：吞掉 → slog.Warn

• 决策：Go 后端 6 处 infoMap, _ := GetFileInfo(...) 改为 slog.Warn 可追踪。
• 原因/取舍：吞错误致前端收到零值数据（name/path/size 全零）既不可用又不可调试。
• 状态：✅ 已落地（sftp/ossdrv）

前端 useFileOperations 去 catch 纯代理

• 决策：useFileOperations 删除全部 try-catch 改为纯代理。
• 原因/取舍：原 catch → onError → throw 三重处理致同一错误弹两次消息；改为边界层统一处理，中间层不吞异常。
• 状态：✅ 已落地（useFileOperations.ts）

系统 API 边界层合理兜底（回滚）

• 决策：system.ts 4 个系统信息 API（CPU/内存/磁盘/环境变量）先删空 catch 后又加回轻量 try { ... } catch { return {} }。
• 原因/取舍：先按确定性编程删空 catch，但审查发现系统信息属边界展示层——获取失败不应崩 UI，返回 {} 是合理降级。与中间层「不吞异常」原则不同，这是边界层合理兜底。
• 状态：✅ 已落地（api/system.ts）

目录加载失败提示

• 决策：loadDirectory(dir).catch(() => {}) 静默吞改为 Message.error 提示。
• 原因/取舍：fire-and-forget 静默吞错时加载失败用户不知列表为何没更新，无从排障；用户感知优先。
• 状态：✅ 已落地（index.vue）

系统信息部分成功降级

• 决策：GetLocalSystemInfo 三项采集全部失败才返回 error，部分成功仍返回已得数据。
• 原因/取舍：单项失败不应让整个接口不可用（降级优于全失败）；全失败才说明采集机制本身有问题。
• 状态：✅ 已落地（app_system.go）

OSS 重命名单文件失败不中断

• 决策：批量重命名中单文件删除失败不中断整批，记录并返回最后一个错误。
• 原因/取舍：单文件失败中断整批时已删无法回滚、未删无法继续体验更差；ossdrv 未引 slog 故用 fmt.Errorf 累积。
• 状态：✅ 已落地（ossdrv/service.go）

---

连接管理

_activeId 提前设置 + 失败回退

• 决策：_activeId 在 buildAndPool() 之前设置，失败时回退旧值。
• 原因/取舍：原在 buildAndPool 之后设，setState('connected') 回调读到旧 activeProfile 致 transport 类型判断错误。提前设置引入新问题：失败时卡在失败 ID 上 Sidebar 无法重试 → 保存旧值失败恢复。
• 状态：✅ 已落地（connection-manager.ts connect）

_lastActiveId 去重提前执行

• 决策：_lastActiveId 去重检查在 _suppressAutoNav 之前执行。
• 原因/取舍：原更新在 suppressAutoNav 检查之后，抑制时回调 return 致 _lastActiveId 不更新；抑制后 updateProfile 异步 notifyChange 触发回调时 _lastActiveId 过期误触发导航到 / 覆盖正确路径。
• 状态：✅ 已落地（index.vue onStateChange）

连接池复用前 isAlive 探测

• 决策：connect() 复用池中连接前先调 transport.isAlive()，失效则清理重建。
• 原因/取舍：原见池中有就返回「已连接」，僵尸连接点击时直接返回已连接实际已断；复用前探测识别并移除失效连接。
• 状态：✅ 已落地（connection-manager.ts）

isAlive 做成可选方法

• 决策：FsTransport 接口新增可选 isAlive?(): Promise<boolean>，SFTP 用 SftpGetFileInfo('/')、OSS 用 OssListDir('') 探测。
• 原因/取舍：用轻量只读操作作心跳而非重连，失败 catch 返回 false；可选方法（?）保持对其他实现的向后兼容。
• 状态：✅ 已落地（transport.ts + 各 transport 实现）

远程 rootPath 始终返回 /

• 决策：远程连接的 rootPath 始终返回 /，忽略 localStorage 残留的 Windows 路径。
• 原因/取舍：原对远程用 filePath 前 4 段算 rootPath 过滤非目录后为空，悬停子目录列表空；远程根目录就是 /。远程模式若沿用本地缓存路径致导航失败。
• 状态：✅ 已落地（ConnectionIndicator.vue）

连接失败中止打开文件

• 决策：handleOpenFavorite 连接失败时 return 中止，不用错误 transport 继续打开。
• 原因/取舍：原失败后继续导航用错误 transport（local）加载远程路径，OSS 文件被当本地处理（路径变 C:\Users\...）。
• 状态：✅ 已落地（index.vue handleOpenFavorite）

loadFileContent await updatePreviewUrl

• 决策：loadFileContent 中 updatePreviewUrl 改为 await。
• 原因/取舍：OSS/SFTP 预览 URL 依赖异步下载到临时文件，不等待会竞态；本地文本不必要但无害，统一 await 简化逻辑。
• 状态：✅ 已落地（index.vue）

字段映射 snakeToCamel

• 决策：前端 loadFromDB() 用 snakeToCamel() 转换 Go 返回的 snake_case JSON。
• 原因/取舍：Go JSON 用 snake_case（access_key），前端 TS 期望 camelCase（accessKey）；直接 ...p 展开不转换致 profile.secretKey 为 undefined，OSS 认证失败——收藏图片打不开的根因。
• 状态：✅ 已落地（connection-manager.ts）

LoadConnectionProfiles 用 json.Marshal

• 决策：LoadConnectionProfiles 用 json.Marshal/Unmarshal 替代手动 map[string]interface{} 字段转换。
• 原因/取舍：手动 map 每字段 float64() 断言，新增字段必漏；JSON 自动处理类型转换，Go struct 到前端 camelCase 全链路映射更可靠。
• 状态：✅ 已落地（app.go）

watchFile 仅本地生效

• 决策：watchFile/unwatchFile 仅本地模式生效，远程连接静默跳过。
• 原因/取舍：远程 FS 无 inotify/ReadDirectoryChangesW 机制，强行监听增加复杂度和网络开销。
• 状态：✅ 已落地（app.go + index.vue）

onStateChange 职责拆分（未实施）

• 决策：onStateChange 回调应拆分为「只管连接状态通知，导航权归 UI 层」。
• 原因/取舍：当前回调同时承担状态跟踪 + 自动导航，_suppressAutoNav 全局标志脆弱，任何异步竞争都绕过它（updateProfile 的 notifyChange 异步触发是典型）。长期方案：连接管理器不管导航、导航权在 UI 显式调用、updateProfile 不触发 notifyChange。当前用 _lastActiveId 去重 + 提前更新作临时修复。
• 状态：📐 设计未实施（临时修复已落地）

---

SFTP

SSH keepalive 30s

• 决策：为每个 SSH 连接起独立 goroutine，每 30s 发送 keepalive@openssh.com。
• 原因/取舍：原无 keepalive，长时间空闲后 NAT/防火墙丢连接 SFTP 变「僵尸」；30s 防连接被杀。
• 状态：✅ 已落地（sftp/client.go）

临时文件去掉 CreateTemp

• 决策：去掉 CreateTemp + 二次 Create，直接拼路径。
• 原因/取舍：原创建两次临时文件（先 CreateTemp 再 Create），多余 IO 增加失败点；直接拼路径减少一次系统调用与竞态窗口。
• 状态：✅ 已落地（sftp/service.go）

parseProcMeminfo 统一单位

• 决策：parseProcMeminfo 统一先按 kB 运算、最后转 bytes。
• 原因/取舍：原 kB/bytes 混用易中间步骤算错；统一单位运算只在出口转换减少混淆。
• 状态：✅ 已落地（sftp/service.go）

---

文件预览 / 编辑

文件读写大小上限

• 决策：本地读写上限 10MB，SFTP 对齐 10MB；预览模式放宽 50MB。
• 原因/取舍：编辑模式整文件加载到内存，10MB 平衡可用性和内存安全；预览可流式/只读，50MB 覆盖绝大多数视频/图片/音频。SFTP 与本地一致避免行为不一致。
• 状态：✅ 已落地（filesystem/service.go、sftp/service.go）

大文件预检 BIG_FILE

• 决策：预览文件超 BIG_FILE（1MB）阈值时不读取内容，显示提示 return。
• 原因/取舍：基于目录列表 size 预检，避免读大文件致编辑器/前端卡死；阈值常量化便于统一调整。
• 状态：✅ 已落地（FileEditorPanel.vue、constants.ts）

clearContent 重置 isBinaryFile

• 决策：clearContent() 必须重置 isBinaryFile = false（之前只清 fileContent/originalContent）。
• 原因/取舍：模板 v-if 链以 isBinaryFile 为第一分支；上一个是二进制、切换到图片/视频时 clearContent 不清该标志会永久命中二进制分支、阻断所有图片/视频预览（cascade 失效根因）。
• 状态：✅ 已落地（useFileEdit.ts）

二进制/媒体用 isMediaPreviewable 判定

• 决策：用 isMediaPreviewable(filename) 显式判断，替代 originalContent.value === undefined。
• 原因/取舍：originalContent === undefined 在首次加载未完成时也 undefined，靠它区分「非文本」语义模糊不可靠。
• 状态：✅ 已落地（index.vue）

非文本文件变更 _t 强制刷新

• 决策：非文本文件（图片/视频）变更后用 URL 追加 _t=timestamp 强制刷新。
• 原因/取舍：方案简洁不侵入文件服务器 URL 生成；只在真正变化时追加，首次走浏览器缓存、tab 切换从缓存恢复原 URL 不产生额外请求。
• 状态：✅ 已落地（index.vue handleFileChanged）

_t 用真实 mtime 而非 Date.now

• 决策：_t 参数从 Date.now() 改为文件实际 mtime（os.Stat ModTime）。
• 原因/取舍：同文件多次保存同内容时 Date.now() 让 mtime 不变但时间戳变；真实 mtime 正确反映修改时刻，且一次 os.Stat 同时完成存在性判断 + 取 mtime。事件 payload 从 string 演进为 {path, mtime} map，前端兼容新旧格式。
• 状态：✅ 已落地（filewatch/watcher.go + index.vue）

草稿恢复脏标记（取舍未决）

• 决策：加载草稿后不同步 originalContent，致文件打开即显示「脏」标记。
• 原因/取舍：草稿残留（localStorage 24h）在 loadFile 后覆盖 fileContent，originalContent 已设为原始内容，二者不同触发脏标记。设计意图恢复未保存编辑（预期），但「一打开就脏」让人困惑。取舍：保草稿恢复 vs 视觉干净——暂未改。
• 状态：❓ 未决

单文件 Tab 显示 + 空状态

• 决策：预览 Tab 栏显示条件从 length > 1 改为 > 0（单文件也显示可关闭）；无预览显示 logo + 「U-Desk / 文件管理器」空状态。
• 原因/取舍：支持「关闭所有预览回到空状态」；空状态低透明度居中不抢焦点。
• 状态：✅ 已落地（FileEditorPanel.vue）

AsyncCodeEditor 重试上限 2 次

• 决策：defineAsyncComponent 的 onError 限重试 2 次。
• 原因/取舍：Vue3 加载/渲染失败后进入永久死亡状态不自动重试；无限 retry() 在网络持续故障时无限重试。策略演进：无限重试 → 上限 2 次。
• 状态：✅ 已落地（FileEditorPanel.vue）

BGM 播放失败跳过不删

• 决策：播放失败自动跳下一首，不删除曲目。
• 原因/取舍：网络文件可能临时不可用（SFTP 断连、OSS 签名过期），删曲目会永久丢失播放列表；跳过保留重试机会。
• 状态：✅ 已落地（BgmBar.vue）

---

文件监听

300ms 防抖

• 决策：fsnotify 文件变化事件后端 300ms 防抖后再 EmitEvent("file-changed")。
• 原因/取舍：编辑器连续保存（VS Code）短时间多次触发 fsnotify；防抖合并多次事件为一次避免前端反复刷新。
• 状态：✅ 已落地（filewatch/watcher.go）

仅监听当前预览单文件 + 脏数据保护

• 决策：仅监听当前正在预览的单个文件；用户有未保存修改时跳过自动刷新。
• 原因/取舍：用户选「自动刷新 + 通知」+「仅当前预览文件」（拒绝「同时监听目录」开销大）；跳过脏数据刷新防丢失未保存编辑。
• 状态：✅ 已落地（index.vue handleFileChanged）

防抖回调捕获局部 emit 变量

• 决策：防抖回调里把 w.emitEvent 先捕获到局部变量 emit 再调用。
• 原因/取舍：debounceTimer 回调在独立 goroutine 执行，直接访问 w.emitEvent 不持锁，与 Close() 并发会 nil pointer panic；捕获局部变量即无需持锁。
• 状态：✅ 已落地（watcher.go）

监听目录而非单文件

• 决策：监听文件所在目录而非文件本身。
• 原因/取舍：部分系统（某些 Linux）不支持直接监听单文件；监听目录兼容性更好，配合防抖过滤目标文件。
• 状态：✅ 已落地（watcher.go）

---

自动更新

os.Exit → Quit 释放 mutex

• 决策：os.Exit(0) 改为 application.Get().Quit() 优雅退出。
• 原因/取舍：Wails v3 启用 SingleInstance 单实例锁；旧流程 bat 先 start 新进程再 os.Exit，新实例启动时旧进程未完全退出，SingleInstance 检测冲突拒绝。Quit 释放 mutex，bat 轮询等旧 PID 退出后再启新实例。
• 状态：✅ 已落地（update.go restartApplication + main.go）

.new 延迟替换

• 决策：运行中 exe 用 .new 延迟替换（安装阶段只复制到 .new，重启阶段 bat 替换）。
• 原因/取舍：Windows 不允许覆盖正在运行的 exe；旧 os.Rename 失败后静默 return nil 实际没替换。改为安装复制 .new、重启 bat 先杀进程再 move、启动 ReplacePendingFile() 兜底。
• 状态：✅ 已落地（update.go）

bat 启动方式

• 决策：bat 用 exec.Command("cmd", "/C", batFile) + SysProcAttr{HideWindow: true}，不经 cmd /C start。
• 原因/取舍：-H windowsgui 模式下 cmd /C start 启动的 bat 可能被 Windows 安全策略拦截；直接 exec.Command + CREATE_NO_WINDOW 避免弹窗且不触发拦截。
• 状态：✅ 已落地（update.go）

bat 写失败降级重启

• 决策：bat 写入失败时降级为 os.Exit(0) + 直接 exec.Command("cmd", "/C", "start", "", execPath).Start()。
• 原因/取舍：bat 依赖临时目录可写，权限不足/磁盘满则无法完成标准流程；降级牺牲 .new 替换但保证能退出并尝试重启。
• 状态：✅ 已落地（update.go fallbackRestart）

check_url 空值才用默认

• 决策：check_url 仅在为空时用默认值，不覆盖已存在的旧 URL。
• 原因/取舍：尊重用户已配置值 vs 自动修正旧失效 URL（如 img.1216.top）——可能导致旧用户无法检测更新。迁移逻辑暂未加。
• 状态：🚧 待实测（当前配置已修，迁移逻辑未加）

更新检查 URL 配置化

• 决策：检查更新 URL 从硬编码改为读 update_config.json，空值 fallback 默认。
• 原因/取舍：硬编码无法按部署环境切换；完全无默认值会致配置缺失时检查失效，故保留 fallback。
• 状态：✅ 已落地（app.go、update_config.go）

---

代码结构 / DRY

三套 FileItem 类型统一

• 决策：三套 FileItem 定义统一为 types/file-system.ts 的一个，删除 api/types.ts 的 File interface。
• 原因/取舍：原 transport.ts 用 is_dir/mod_time（蛇形）、file-system.ts 用 isDir/modified_time（驼峰）、api/types.ts 用 isDir/modified（又不同），加两套 transformFile 易错；统一为驼峰，transport 层做一次蛇→驼峰转换。
• 状态：✅ 已落地（types/file-system.ts、api/transport.ts、api/types.ts）

CopyFile 失败清理 + 权限保留

• 决策：common.CopyFile 加失败清理（os.Remove dst）+ 保留源文件权限（os.Chmod）。
• 原因/取舍：从 download_cache/recycle_bin/update 三处提取共享 CopyFile 时，原各处有失败清理和权限保留，合并不能丢；recycle_bin 依赖文件权限不变。
• 状态：✅ 已落地（common/utils.go）

全局单例死代码删除

• 决策：删除 globalLogger/globalRecycleBin/LogOperation/LogError/GetGlobalLogger/GetStackTrace 等全局单例，而非加 sync.Once 保护。
• 原因/取舍：这些只有声明和 getter 从未初始化或调用，属死代码；直接删比加保护更干净。
• 状态：✅ 已落地（logger.go、recycle_bin.go）

App 拆分粒度：11 文件不再动

• 决策：11 个 app_*.go 按功能域拆分，不再进一步合并或细分。
• 原因/取舍：命名清晰符合 Go 多文件包惯例；继续拆分或合并都增加认知负担，「保持现状」是当前最佳点。
• 状态：✅ 已落地（决定不动）

Windows 专用代码 build tag 隔离

• 决策：registry/w32 等 Windows 专用包函数移到 app_windows.go，跨平台函数留 app.go。
• 原因/取舍：Windows 专用包直接 import 致跨平台编译失败；build tag 文件拆分而非运行时 GOOS 判断，是 Go 惯例且零运行时开销。
• 状态：✅ 已落地（app.go/app_windows.go）

watchFile 接口统一

• 决策：watchFile/unwatchFile 统一走 FsTransport 接口。
• 原因/取舍：原各 transport 各自实现接口不统一；收敛后共用同一套签名和调用模式。
• 状态：✅ 已落地（transport.ts + 4 个 transport 实现）

旧版遗留清理

• 决策：删除 3 个旧版零引用 composable JS 文件（~1000 行）+ Wails v2 遗留 wailsjs 绑定。
• 原因/取舍：旧版 JS/wailsjs 文件无 import 引用属历史遗留，留着混淆开发。
• 状态：✅ 已落地（composables/*.js、wailsjs/wailsjs/）

---

窗口外观

DWMWA_COLOR_NONE 抑制白边

• 决策：用 DWMWA_COLOR_NONE（0xFFFFFFFE）作四主题状态 BorderColour，移除 DisableFramelessWindowDecorations。
• 原因/取舍：白边根因是 ExtendFrameIntoClientArea 保留 DWM 框架、暗色模式未告知 DWM 用暗色渲染；试过 #2D2D2D、移除 CustomTheme、DisableFramelessWindowDecorations:true 均无效；DWMWA_COLOR_NONE 是 Win11 官方抑制边框 API。Win10 不支持降级无装饰（取舍：牺牲 Win10 Aero 阴影/圆角换 Win11 干净边缘）。
• 状态：✅ 已落地（main.go）

背景色固定 #2D2D2D

• 决策：窗口 BackgroundColour 固定 #2D2D2D（暗色安全）。
• 原因/取舍：此色仅 CSS 未渲染前的加载瞬间可见；暗色模式不露白边，亮色模式被前端 CSS 覆盖；不随主题切换避免 Go 端复杂度。
• 状态：✅ 已落地（main.go）

---

UI 交互

设置面板 Teleport to body

• 决策：弹出面板从 sidebar 内 position: absolute 改为 <Teleport to="body"> + position: fixed。
• 原因/取舍：旧方案被 overflow: hidden 容器裁切，设置按钮/更多菜单弹出被截断；Teleport 彻底解决 z-index 和 overflow:hidden 裁剪。
• 状态：✅ 已落地（Sidebar.vue）

服务器区块 max-height: none

• 决策：服务器区块 max-height: none 不限高；收藏夹区块保留 max-height 折叠动画。
• 原因/取舍：max-height: 500px 在服务器列表 >15 行时裁剪；服务器区块在 flex-shrink: 0 内高度由内容决定即可。折叠动画只适合可变高度区块。
• 状态：✅ 已落地（Sidebar.vue）

收藏夹默认折叠

• 决策：收藏夹侧栏 favCollapsed 初始值改 true（默认收起）。
• 原因/取舍：保持界面简洁，用户按需展开。
• 状态：✅ 已落地

折叠动画 max-height:0

• 决策：折叠动画从 grid-template-rows: 0fr 改为 max-height: 0 + overflow: hidden。
• 原因/取舍：0fr 方案折叠后仍有残留高度；帮助区块不再 margin-top: auto，依赖收藏区块 flex-grow 自然推到底。
• 状态：✅ 已落地（Sidebar.vue）

toggleSettings 用 closest

• 决策：toggleSettings 用 closest('.settings-btn') 替代 e.currentTarget。
• 原因/取舍：Vue 3 内联事件 e.currentTarget 有 null 风险（Vue 内部包装），原 || e.target 兜底有类型安全隐患（e.target 可能是子文本节点）；closest 向上查找更可靠。
• 状态：✅ 已落地（Sidebar.vue）

面包屑下拉过滤 + 200 + 缓存

• 决策：面包屑下拉只获取目录（跳过文件），slice(0, 200) 限制，Map<path, result> 跨导航缓存。
• 原因/取舍：/tmp 等大目录返回过多卡顿；用户只能导航到目录，过滤文件减 payload；200 上限防极端，Map 缓存避免悬停同路径重复请求。
• 状态：✅ 已落地（PathBreadcrumb.vue）

拖拽 iframe 遮罩

• 决策：resize 拖拽时 mousedown 即激活全屏遮罩，并缓存容器尺寸。
• 原因/取舍：iframe（PDF/图片预览）捕获鼠标事件致拖拽中断；每帧 getBoundingClientRect() 强制回流；遮罩从 rAF 回调改 mousedown 立即触发，避免鼠标未移动时遮罩不出现。
• 状态：✅ 已落地（resize.ts）

系统信息 15s 自动刷新

• 决策：系统信息面板 setInterval 每 15s 刷新。
• 原因/取舍：固定周期足够反映服务器状态变化且不致过大开销。
• 状态：✅ 已落地（连接管理器 refreshTimer）

F11 预览全屏：OS 级 → 窗口内全屏 [2026-06-13]

• 决策：文件预览区 F11 全屏从浏览器 Fullscreen API（OS 级，占整个屏幕）改为 CSS class 驱动的窗口内全屏（position: fixed; inset: 0），只盖 u-desk 应用窗口视口。
• 原因/取舍：OS 全屏独占整个显示器、遮任务栏、退出后窗口尺寸/位置可能错乱，对桌面文件管理器过重；窗口内全屏只占应用视口，保留任务栏与多窗口切换，符合「应用内聚焦预览」预期。代价：失去浏览器原生 ESC 退出 → 自行补 ESC 监听退出 + F11 再按切换。实现：isFullscreen ref 驱动 .is-fullscreen class，移除 requestFullscreen/exitFullscreen/fullscreenchange 监听器及 panelRef，:fullscreen 选择器全部改 .is-fullscreen。
• 状态：✅ 已落地（FileEditorPanel.vue，wails3 build 通过 2026-06-13）

---

快捷键 / 热键

RegisterGlobalHotkey 单 defer Unlock

• 决策：合并为单一 defer mu.Unlock()，消除锁间隙竞态。
• 原因/取舍：原 nil 检查和赋值不在同一把锁内（Lock→检查→Unlock→注册→Lock→赋值→Unlock），两 goroutine 可同时通过 nil 检查致重复注册。
• 状态：✅ 已落地（app.go RegisterGlobalHotkey）

盘符快捷键先回本地

• 决策：Ctrl+Shift+C~H 盘符快捷键切换前先回本地 transport。
• 原因/取舍：远程模式下按盘符快捷键会报错（C:~H: 盘符操作不适用远程 transport）；先切回本地再执行盘符切换。
• 状态：✅ 已落地（index.vue）

---

DevTools

build tag 控制

• 决策：用 Go build tag（!production/production）控制 DevTools 开关。
• 原因/取舍：wails dev 和 wails3 build 默认都带 devtools tag 致生产包弹 Inspector；曾考虑运行时 Env.Info().Debug 判断但 Run() 前不可用；build tag 编译期控制零运行时开销更可靠。
• 状态：✅ 已落地（devtools.go/devtools_prod.go）

---

桌面应用体验

UniqueID 反向域名

• 决策：UniqueID 用 top.1216.udesk，不用 com.1216.top.udesk。
• 原因/取舍：用户域名 1216.top，按反向域名规范应为 top.1216.udesk；com. 开头系统层面也能工作但用户明确要求严格反向域名规范。
• 状态：✅ 已落地（main.go SingleInstance）

全局禁用浏览器右键菜单

• 决策：App.vue onMounted 添加 contextmenu 事件拦截，全局禁用浏览器默认右键菜单。
• 原因/取舍：桌面应用露浏览器默认右键菜单破坏原生体验；CSS --default-contextmenu: hide 在 WebView2 不一定生效，JS preventDefault 更可靠。
• 状态：✅ 已落地（App.vue）

---

版本 / 依赖

Wails 暂缓升级

• 决策：暂不升级（停留 alpha.80，最新 alpha.86）。
• 原因/取舍：升级主要带来 Windows 托盘 GDI 内存泄漏修复、WebView2 焦点空指针修复，但对本项目影响不大；而改进清单依赖的原生对话框/窗口事件 API 新版仍未提供，升级收益不足以抵消回归风险。
• 状态：🚧 待实测（暂缓非永久否决）

---

文档 / 流程

CHANGELOG 用户视角

• 决策：CHANGELOG.md 只写用户能感知的变化，不写内部实现细节。
• 原因/取舍：CHANGELOG 面向用户非开发者；内部重构（结构化日志、并发安全、依赖升级）只作概括条目，详细技术改动放 CHANGELOG.internal.md；新功能不应归入「修复」。
• 状态：✅ 已落地

调试工具验证后统一清理

• 决策：调试日志和临时测试工具在功能验证通过后再统一清理，不随修复合并。
• 原因/取舍：OSS 连接问题未完全验证前用户要求「先不清理」；调试日志帮助定位了 updateProfile 异步 notifyChange 误触发导航的 bug。最终验证后统一清理 cmd 调试工具、DebugLog 绑定、前端调试日志。
• 状态：✅ 已落地

---

已知上游依赖问题

Chromium 149 中文 IME 标点按两次丢失 [2026-06-13]

• 决策：确认是 Chromium 149 上游 bug，不在应用层修；等 Chrome/Edge 151 推送更新 WebView2 Runtime 解，或临时切 IME 英文标点绕过。
• 原因/取舍：症状——中文输入法下编辑器（CodeMirror）直接打全角标点（。，；：）每隔一次丢失，需按两次。排查已排除：u-desk 全局快捷键（index.vue handleKeyDown / FileEditorPanel onKeyDown 全部需 Ctrl/Meta/Alt/Shift 或功能键，裸标点不命中不拦截）、CodeMirror 配置（6.41.1，无 closeBrigits/无标点 keymap 绑定）、watch modelValue 回写（字符串相等不重派发）。CodeMirror 作者 marijn 用裸 <div contenteditable> 也在 Chrome 149 stable 复现，提 Chromium #521205128 → 纯内核 bug，非本项目代码。应用层无法修：丢失的那次按键在 Chromium 内部被吞，不触发任何 JS 事件（无 keydown/beforeinput/compositionend），拦不到。不在 CodeMirror 加 inputHandler/keydown hack：作者本人只提 issue 未给 workaround，硬 hack 引新问题。当前环境：WebView2 Runtime = Edge = 149.0.4022.62（Chromium 149，2026-06-02 stable），通道覆盖未设（stable 正常）。根因（2026-06-12 上游确认）：Chromium 的 TSFTextStore 在 IME 活动时仍跑 autocorrect 检测，吞掉标点；修复 CL 7917332（Pranav Modi/MS）标题 "Skip autocorrect detection when IME is active in TSFTextStore"。
• 状态：🚧 上游已修复待发布（2026-06-12 在 Chrome 151.0.7888.0 / Win11 验证有效，已加 verified 标签；接受现状不应用层修）
• 📋 待办：修复落 Chrome 151（非 150）。等 Edge/WebView2 Runtime 升到 151 stable（Chrome 150 stable ~2026-06-29，151 stable 约 2026-07 下旬；急用可装 Edge Beta 151 提前验）→ 更新后回归验证编辑器中文标点。参考 CodeMirror 论坛 #9741。

---

维护说明

本文档为初始整理，覆盖 7 个历史会话 + 当前会话，共 ~90 条去重决策。

压缩信号：当前 ~19 功能域、超 300 行。后续触发以下任一条件时压缩：

• 老 Sprint 决策超 3 个 → 归档到 功能决策记录-归档.md
• 某功能域 > 10 条 → 单独拆文件
• 已稳定决策合并精简，只留结论 + 关键原因

更新优先于新增：决策点已存在就改原条，演进用 → 串联，不留重复版本。