ShadowsocksX-NG/docs/design/home-target-card.md

首页活动目标卡片

本文件记录 2026-10-14 确认的需求。当前实现以代码为准。

呈现与交互

• 卡片位于首页左栏、代理模式卡片上方。
• 头部显示活动目标名称、完整目录路径和「定位当前」。
• 工具栏提供「全部／收藏」和「测试全部」。
• 全部视图保留目录层级。收藏按已有顺序平铺，组不展开。
• 目录区最高 360 点，超出后内部滚动。底部操作区独立于内部滚动区。
• 行只显示名称，不额外显示连接地址或端口。悬停显示完整路径。
• 单击只选择。分组箭头只展开或收起。双击不激活。
• 浏览选择使用系统语义选中色。活动目标使用闪电标记，活动组只标记自身。
• 底部显示所选名称与路径。组显示可激活配置数和已知无效配置的跳过数。
• 没有选择、当前项已激活、本地激活条件不满足时，禁用激活并说明原因。
• 测试结果不参与激活资格判断。
• 激活期间显示「激活中…」，冻结当前卡片，页面导航保留，已有测试继续。
• 沿用现有激活语义，活动标记跟随活动目标。部署成功不作为标记更新条件。
• 不新增激活错误提示，沿用首页其他卡片的现有提示。
• 首页只提供查看、测试和激活，不增加管理、搜索和目录行键盘导航。

测试结果与范围

• 两页共享 ServerConnectivity、ConnectivityCell 与测试按钮行为，不新增缓存或调度器。
• 未测试显示「—」，悬停显示「尚未测试」。两页统一此规则。
• 服务器显示最近一次结果。组显示「最快 128 ms」，悬停显示服务器名称和测试时间。
• 组有结果但没有成功结果时显示「—」，悬停显示「无成功结果」。
• 测试时显示小型进度指示，保留此前结果。
• 沿用五分钟与网络变化失效规则。过期结果使用次要颜色，悬停注明「已过期」。
• 沿用现有组汇总规则：优先新鲜成功；仅有过期成功时显示过期最快值；每台服务器只取最近一次结果。
• 底部测试选择的服务器或组内全部后代服务器。
• 全部视图的批次覆盖全目录。收藏视图的批次覆盖收藏节点及全部后代。
• 批次按点击时的目标去重，不受折叠影响，沿用任务复用、冷却与进度。
• 只手动触发测试。测试期间仍可浏览、选择和激活。
• 不按延迟排序或切换目标，保持目录及收藏顺序。

浏览状态

• 主工作区为唯一窗口。窗口持有首页浏览 Module，切页保留状态。
• 首页独立持久化视图模式和展开分组；浏览选择只存于窗口会话。
• 无持久化记录时所有组收起。
• 本窗口首次进入首页时选择并定位当前目标。必要时切换全部、展开祖先。
• 之后仅「定位当前」主动定位。定位产生的模式和展开状态也落盘。
• 收起所选项的祖先组时选择该组。
• 切换视图后选择不可见时清空。目录更新时清理失效节点状态。
• 空目录与空收藏分别说明，并引导前往服务器页添加或收藏。
• 复用现有目录与激活 Interface，不修改领域 Interface。

验证 seam

• 首页浏览 Module 的 Interface：首次进入、定位、选择、折叠、切换视图、目录更新和测试范围。
• 既有 ServerConnectivity Interface：继续由现有测试验证调度、失效及汇总语义。