LinkPort/docs/todo.md

UI 实现状态与待验收事项

更新时间：2026-09-20。

本文维护实现状态和仍需完成的验收。按“全部实现”的要求，UI-001 至 UI-011 已完成代码接入，并新增后端和前端回归用例；不是仅登记计划。复选框代表对应实现已落地，不代表浏览器和真实协议服务验收完成。使用方式见 工作区交互 与 连接编辑器，视觉来源见 DBX 风格界面。

实施顺序与前置验收

• UI-000｜待完成：生产构建与运行态验收。 Go 1.25.0 全部后端测试、vet、前端类型检查已通过；Vite/esbuild 与 Playwright worker 均受 spawn EPERM 阻塞。仍需构建前端和新嵌入程序，将 LINKPORT_E2E_BINARY 指向新程序，在隔离数据库/空闲端口运行全套测试，检查全部页面、四类编辑器、登录/退出、主题及 320/390/768/1920px 截图。测试发现与纯逻辑断言不能替代此验收。
• 优先补齐连接配置：独立 URL 参数编辑（UI-007）→ 未解析 URL 与测试/保存的一致性（UI-008）。先明确协议支持和参数生效链路，不交付只有输入框、实际连接不生效的功能。
• 工作区第一阶段：全局资源搜索 → 树形资源导航 → 表格列设置。
• 后续阶段：统一操作菜单、首页快捷入口、连接标识与测试反馈；高级参数须先确认后端语义，多标签工作区须先完成状态与生命周期设计，再分别实施。
• 每项完成后更新状态、相关功能文档、change-rationale.md 和实际验证结果；未执行的测试或截图验收不得标记通过。

待实现清单

编号	优先级	功能	状态
UI-001	高	全局资源搜索	代码完成；待浏览器验收
UI-002	高	树形资源导航	代码完成；待浏览器验收
UI-003	高	表格列设置	代码及布局合并断言通过；待浏览器验收
UI-004	中	多标签工作区	生命周期设计及代码完成；待浏览器验收
UI-005	中	统一操作菜单	代码完成；待浏览器验收
UI-006	中	首页最近资源与快捷入口	代码完成；待浏览器验收
UI-007	高，优先补齐	独立 URL 参数编辑与实际生效	代码、解析断言及协议 fixture 通过；待浏览器验收
UI-008	高	URL 输入、表单、测试与保存一致性	代码及 API 回归通过；待浏览器验收
UI-009	高	连接高级参数 UI 与协议支持	能力矩阵、代码及 fixture 通过；待浏览器验收
UI-010	中	连接颜色、备注与展示控制	代码、保存/备份/同步回归通过；待浏览器验收
UI-011	中	连接测试内联状态与诊断复制	代码完成；待浏览器验收

连接配置 UI 差异核对

以下依据 DBX 的 apps/desktop/src/components/connection/ConnectionDialog.vue 和 linkport 当前源码核对；完整 URL 导入、独立 URL 参数和高级连接配置是不同功能。

项目	linkport 当前状态	待补范围
完整连接 URL 导入	提供待解析/已填入/错误状态，测试及保存前统一应用；解析后清空原始 URL	浏览器验证同时存在待处理输入和错误重试，见 UI-008
独立 URL 参数输入	已新增独立输入、原子校验、结构化字段映射和回读，不存任意原始字符串	浏览器验证字段联动、保存重开，见 UI-007
协议参数扩展	MySQL charset、PostgreSQL application_name 已贯通握手/启动参数，未知项仍拒绝	已验证本地 fixture，不代表真实数据库兼容性验收，见 UI-007
连接、查询、空闲超时及保活	已有单位/范围/默认值控件：网络超时、PG 查询超时、Mongo 空闲超时、非 K8s TCP 保活	不支持的选项禁用，能力矩阵见 UI-009 与连接文档
连接颜色和备注	目标/网关各自保存颜色、备注和显示开关；列表、树、最近资源显示	保存、备份恢复和同步测试通过；待主题/小屏验收，见 UI-010
连接测试	保留原草稿测试和详细结果，新增内联摘要、过期提示和白名单诊断复制	待浏览器生命周期与剪贴板验收，见 UI-011
TLS/SSL、代理、账号页签	已有基础配置和资产引用，不是整页缺失	复用现有能力；新增参数须与现有字段一致，不降低 TLS 校验要求

参数编辑、超时和元数据已同步扩展模型、API、运行时及配置回读；使用已有加密配置，无 SQLite 表结构迁移。支持的 URL 参数、超时默认值和协议边界见 连接配置页签与 URL。

本轮实际验证

• GOTOOLCHAIN=go1.25.0，GOFLAGS=-p=1 限制并发，临时目录/Go 缓存放工作区 tmp：go test ./... -count=1 -timeout=120s 全部通过，go vet ./... 通过。
• 锁定依赖下 vue-tsc --noEmit 和 git diff --check 通过；7 项新增前端纯逻辑测试函数在单进程执行通过，覆盖参数/草稿/列布局/搜索脱敏/标签唯一性。
• Playwright 成功发现全套 88 项用例，但 worker 被 spawn EPERM 阻止；Vite 在启动 esbuild 时出现同类错误。没有声称生产构建、浏览器断言或截图已通过。
• 协议验证全部为隔离的本地 fixture；未连接真实 MySQL/MongoDB/SSH 测试服务，未修改工作区 data，未替换或启动用户实际服务。

事项说明

UI-001：全局资源搜索

• 增加统一搜索入口，按名称、地址和项目查找目标、网关、代理及资产，区分资源类型与所属项目/环境，支持直接进入详情或编辑。
• 支持键盘打开、方向键选择、Enter 确认和 Escape 关闭，提供手机可点击入口、空结果及加载失败反馈。
• 复用与边界：在现有菜单搜索和资源导航能力上扩展，不搜索解密后的密码、密钥或文件正文。明确当前项目/环境搜索范围，跨范围跳转时同步筛选状态，并经过未保存确认。
• 验收：同名资源可区分；键盘和触屏均可操作；切换范围、删除资源及异步迟到响应不会打开错误资源；搜索结果不泄露敏感字段。
• DBX 参考：apps/desktop/src/composables/useQuickOpen.ts、apps/desktop/src/components/quick-open/QuickOpenDialog.vue。

UI-002：树形资源导航

• 按“项目 → 环境 → 资源类型”组织资源，提供折叠、状态标记、定位当前资源和清晰的未分组入口。
• 桌面支持调整侧栏宽度；手机保留轻量入口，避免多层树占满工作区。
• 复用与边界：沿用现有项目、环境和资源 ID，不创建平行的分组数据体系；资源计数、树中选择与现有页面筛选保持一致。仅持久化非敏感的展开状态和布局偏好。
• 验收：资源新增、重命名、移动范围和删除后树及时更新；搜索定位可展开祖先节点；长名称、空分组及低高度窗口可用；不丢失现有菜单入口。
• DBX 参考：apps/desktop/src/components/layout/AppSidebar.vue、apps/desktop/src/components/sidebar。

UI-003：表格列设置

• 为网关、连接/命令审计和资产列表增加列显隐、拖动排序、宽度调整及恢复默认。
• 按表格稳定标识保存非敏感布局偏好，新增或移除字段后能够合并旧偏好并恢复可用布局。
• 复用与边界：保留现有列表筛选和分页；关键标识、选择列及操作列的可隐藏规则需要明确。窄屏继续采用现有卡片或表格内部滚动，不强制套用桌面列宽。
• 验收：刷新后偏好保留；异常列宽受到限制；键盘或按钮能够完成拖动的等效操作；默认布局可恢复；空数据和长文本下不产生页面级横向溢出。
• DBX 参考：apps/desktop/src/components/grid/DataGridColumnLayoutPopover.vue、apps/desktop/src/composables/useDataGridColumnLayout.ts。

UI-004：多标签工作区

• 先明确标签的稳定标识、重复打开规则、组件缓存、轮询暂停及关闭后的资源释放，再支持同时打开目标配置、网关详情和审计。
• 切换标签保留筛选和滚动位置，支持固定标签、关闭其他标签及关闭含未保存修改的标签时确认。
• 复用与边界：复用现有未保存变更保护，不把密码、私钥、解密内容或表单草稿写入浏览器持久存储。标签关闭只关闭视图，不隐式停止实际网关；不活动标签避免重复轮询。
• 验收：切换和关闭标签不串用资源状态；资源删除或范围变化后不保留可误操作的旧视图；关闭其他标签逐项保护未保存修改；手机有可访问的标签切换方式。
• DBX 参考：apps/desktop/src/components/layout/AppTabBar.vue、apps/desktop/src/components/layout/EditorGroupTabBar.vue。

UI-005：统一操作菜单

• 将编辑、复制配置、连接示例、查看审计及适用的启停操作整合为统一“更多”菜单，桌面补充右键入口。
• 统一禁用条件、危险操作样式、确认交互和键盘操作；手机保留可点击按钮，不依赖右键。
• 复用与边界：所有入口调用现有业务操作与校验，不复制一套启停或删除逻辑。复制配置沿用现有脱敏规则，不因新增快捷菜单绕过敏感信息查看要求。
• 验收：菜单和原按钮的行为、禁用状态及确认条件一致；资源状态变化后不执行过期操作；菜单靠近窗口边缘时仍可见，触屏和键盘可用。
• DBX 参考：apps/desktop/src/components/ui/CustomContextMenu.vue。

UI-006：首页最近资源与快捷入口

• 在现有运行概览中增加最近访问资源、常用操作和异常网关入口，不另建重复仪表盘。
• 提供新建目标、创建网关、导入配置等适用入口；点击最近资源或异常项可定位对应页面。
• 复用与边界：复用已有统计、监控状态和启动检查能力；最近记录仅保存必要的资源 ID、类型及访问时间，不保存凭据或解密内容。项目/环境筛选与实际资源删除同步生效。
• 验收：没有历史记录时提供明确引导；失效资源可清理；切换范围不展示错误资源；异常状态与原监控页面一致；手机布局保持紧凑。
• DBX 参考：apps/desktop/src/components/layout/WelcomeScreen.vue。

UI-007：独立 URL 参数编辑与实际生效

• 在目标连接配置中提供独立“URL 参数”输入区，支持 key=value&... 表达及按协议展示的示例、说明与错误定位；可辅以键值行编辑，但不要求用户先拼接完整连接 URL。
• 定义各协议支持的参数、类型、默认值和作用范围。DBX 的 charset=utf8mb4 等示例需逐项评估后端支持；当前未实现的参数应明确拒绝，不能静默丢弃或只保存不生效。
• 协调 URL 参数与数据库、TLS、认证来源、集群等已有表单字段。规定同义参数、重复项和冲突值的处理方式，采用一致的数据来源，避免两个输入区互相覆盖。
• 贯通 URL 导入、草稿测试、保存、重新编辑、目标运行时配置、配置备份及多端同步；敏感参数按现有凭据规则处理，不写入浏览器偏好或未脱敏日志。
• 复用与边界：扩展现有 ConnectionURLImport.vue、connectionURL.ts 和 MongoDB 专用解析器，不以无约束字符串透传绕过协议校验或 TLS 安全要求。只读策略等网关配置不能因 URL 参数被绕过。
• 验收：编码字符、空值、重复参数、同义参数、协议切换和冲突均有测试；未支持参数报错后不部分修改表单；草稿测试与保存后的实际连接使用同一组有效参数；重开、备份恢复和同步不会丢失配置或泄漏秘密。协议验证必须说明真实服务或 fixture 边界。
• DBX 参考：apps/desktop/src/components/connection/ConnectionDialog.vue 中 supportsGenericUrlParams、form.url_params 及协议专用 URL 参数输入区。

UI-008：URL 输入、表单、测试与保存一致性

• 明确标示完整 URL 的“未解析 / 已应用 / 错误”状态；当 URL 尚未解析时点击测试或保存，应统一解析或提示先应用，不能让用户误以为新 URL 已经参与操作。
• 定义 URL 解析后继续修改主机、端口、账号或独立 URL 参数的优先级；切换页签、关闭编辑器及失败重试不无声丢弃未处理输入。
• 复用与边界：现有手动“解析并填入配置”和账号选择继续可用；复用表单校验、凭据保留规则及未保存确认。原始 URL 可能含密码，不因新增编辑状态而持久保存明文，也不自动触发连接请求。
• 验收：粘贴 URL 后直接测试/保存有明确且一致的结果；解析失败阻止误用旧配置；多账号写入对象正确；切换页签和返回编辑不串用旧输入；错误信息保持脱敏。
• DBX 参考：apps/desktop/src/components/connection/ConnectionDialog.vue 中 hasPendingConnectionUrlInput、ensureConnectionHostResolvedFromUrl 和 formValueForSubmit。

UI-009：连接高级参数 UI 与协议支持

• 为适用协议设计连接超时、查询超时、空闲超时及保活间隔的控件，显示单位、范围、默认值，以及“使用默认 / 当前目标覆盖”的来源；没有全局配置能力时不展示虚假的全局设置。
• 先区分拨号、认证、查询与长连接各阶段的语义，列出每种协议支持和不支持的项。DBX 的空闲超时等字段有协议条件，不能对所有协议一律展示。
• 贯通目标模型、草稿测试、运行配置、导入导出和同步；明确参数修改对新连接与已有会话的影响。
• 复用与边界：不把客户端数据库管理工具的会话策略直接套到多协议网关。后端无法兑现的设置必须隐藏或明确禁用，不能只增加 UI；不将整个连接读超时冒充查询超时。
• 验收：默认行为兼容旧配置；边界值、继承/覆盖和禁用状态有校验；参数确实作用于声明的阶段，不误伤长查询、订阅、SSH 或 SFTP 会话；各协议分别记录实际验证范围。
• DBX 参考：apps/desktop/src/components/connection/ConnectionDialog.vue 中连接/查询超时、idle_timeout_secs 与 keepalive_interval_secs 控件。

UI-010：连接颜色、备注与展示控制

• 为目标/网关提供可选颜色标识和备注，并定义列表、详情、未来资源树或标签页中的显示规则；允许关闭备注展示。
• 支持预设颜色和清除标识，限制备注长度；只有确认有必要时才增加自定义色，避免增加配置复杂度。
• 复用与边界：文件资产已有备注，不重复建设；连接色只用于识别，不替代运行状态或告警色。连接元数据如需持久化，应覆盖备份与同步，并明确旧配置默认值。
• 验收：长备注、小屏和深浅主题下可读；颜色以外仍有名称等辨识信息；清除、保存、重开和备份恢复一致；不将资产备注误写到目标或网关。
• DBX 参考：apps/desktop/src/components/connection/ConnectionDialog.vue 中 form.color、form.note 和备注侧栏展示开关。

UI-011：连接测试内联状态与诊断复制

• 在连接编辑器固定操作区展示测试中、成功或失败的简要状态，并保留已有详细结果入口；可显示已经获得的耗时与失败阶段。
• 提供脱敏诊断复制，修改测试相关配置或切换账号后标记上次结果已过期，不把旧成功状态当作当前配置已验证。
• 复用与边界：不重新实现连接测试接口，沿用 TargetDraftTest.vue 的草稿快照、账号选择、凭据保留和 SSH 指纹确认。诊断复制不得包含密码、私钥、原始含密 URL 或资产正文。
• 验收：测试期间按钮状态正确；关闭编辑器后迟到结果不污染其他目标；修改配置后状态失效；键盘和读屏能够获得结果反馈；手机底部状态不挤掉测试、取消与保存按钮。
• DBX 参考：apps/desktop/src/components/connection/ConnectionDialog.vue 底部 testResult、copyTestResult 和测试按钮。

实施边界

• DBX 参考路径均相对于本地 C:\work\github\dbx；参考交互模式，不直接搬入其业务状态或依赖链。
• 已有连接测试、未保存确认、列表筛选记忆、项目/环境筛选和批量操作优先复用，不重复建设。
• 暂不纳入完整 SQL 编辑器、Tauri 桌面多窗口及 DBX 数据库业务模块。
• 展示和导航增强不预设数据库迁移；URL 参数、高级设置和连接元数据必须先确认后端及存储支持。需要调整接口、运行语义或持久化结构时，应单独记录兼容方案与验证，且不得使用真实目标数据进行烟雾测试。