Issue 137 - ShaoClean/Alune GitHub Wiki

Issue #137：仓库数据总览——功能与 UI 设计

目标与确认范围

在现有卡片、列表之外增加“数据总览”，集中展示本机与 SSH 仓库的规模、活跃度、当前工作区状态和来源分布。用户可从数字和图表定位到相关仓库并打开工作区。

2026-09-30，用户明确希望看到各种统计信息和图表，并选择“综合总览：规模、活跃度、状态、来源”。查看修订视觉稿后，用户确认同步。当前以已展示的 01 综合总览 为实现基线，另保留 02 趋势分析、03 全屏大屏 两种布局参考；是否同时产品化不作为已确认的首期承诺。

本页已经替换早期仓库地图方案，旧稿不再作为实现要求。下方历史视觉稿中的数字均为演示数据。2026-10-01 已完成综合总览实现，生产样式以重构后的 UI 为准；真实夹具截图、最终统计口径与证据边界见实现与验收记录。功能尚未合并发布。

2026-10-01 实现更新

  • 六项指标、五类图表与下钻已实现，沿用新版主题变量、Geist、Ant Design 和统一弹窗；不引入 ECharts。
  • 当前 HEAD、提交者时间、完整 UTC 日；clone/worktree 按登记工作区分别计数。最终口径、接口、缓存与限制见验收记录。
  • 已验证真实本机 Git 与临时 SSH、15 组来源/周期、空/未知/失败、浅克隆、焦点回退和 768/1024/1440 明暗布局。500 工作区完整页面采集约 17.2 秒。
  • 历史“抽屉”交互由新版统一明细弹窗承担；备选趋势分析/全屏布局未产品化。
  • 下方勾选仅表示本次 macOS 与 loopback SSH 环境通过，Windows/Linux 原生、屏幕阅读器真机、公网高延迟及生产大历史未运行。

视觉稿与可下载原型

沿用 Alune 月光主题、产品图标和 Ant Design 图标体系。HTML/CSS 视觉稿使用 Apache ECharts 5.6.0 绘制统计图表，数据可交互筛选。

01 综合总览：当前基线

顶部为范围、周期与六项核心指标；主行展示趋势与状态；第二行展示来源、排行和语言；下方列出需要关注的仓库。

综合总览：六项核心指标、趋势、状态、来源、排行和语言图表；演示数据

查看完整页面（含需要关注的仓库表）

02 趋势分析：布局参考

扩大提交趋势和活跃排行，来源、状态和语言作为下一层信息。使用相同指标与统计口径。

趋势分析布局：扩大趋势与排行；演示数据

03 全屏大屏：布局参考

隐藏应用侧栏，默认深色，放大指标与图表，适合持续展示。是否在首期提供专门入口待评估。

全屏大屏：深色统计布局；演示数据

窄窗口与交互附件

下载 ZIP 后解压并打开 index.html；脚本、图表库、主题与图标已包含。可以切换方案、明暗主题、来源、7／30／90 天、查看提示、点击图表或数字进入明细。正式开发前也可用任意静态 HTTP 服务预览。

顶部三方案切换、演示数据标记及底部评审说明属于设计评审工具，不进入生产页面。截图保留评审时原貌；本页顶部记录当前确认状态。刷新和打开工作区在原型中只显示演示反馈，不连接真实 Git 或 SSH。

首期功能范围

入口与基础行为

  • 仓库页右上切换“卡片／列表／数据总览”。保留原默认值，按设备记忆选择，兼容旧偏好。
  • 连接页仍支持卡片／列表；共享视图类型与持久化校验应按页面约束。
  • 切换视图保留共用的来源范围；原列表的搜索／排序应保留各自状态，不能给总览悄悄施加不可见条件。
  • 默认展示当前全部已登记仓库；来源下拉可限定本机或指定 SSH 连接，未解析的连接保留独立兜底身份。

六项核心指标

指标 口径 交互
仓库总数 当前来源范围内已登记仓库数量，附本机与 SSH 数量 查看全部登记仓库
活跃仓库 本期至少一次符合统计范围的提交，按仓库计数；显示占总数比例 查看本期活跃仓库
本期提交 本期提交数量，对比上一等长周期 查看贡献提交的仓库及各自计数
有未提交改动 新鲜有效状态中存在改动的仓库数，附改动文件数量 查看有改动的仓库
待同步仓库 ahead > 0 或 behind > 0 的唯一仓库并集；分别显示待推送、待拉取 查看对应工作区和同步数量
状态待确认 未获取、缓存过期或读取失败的仓库数 查看原因、时间与重试入口

仓库总数是登记数量；当前状态有效覆盖率是新鲜有效状态数／登记数。采集过程中不能将尚未获取的状态计为零改动。

改动文件数量须按仓库和路径去重，同一文件同时已暂存和未暂存不能重复计数。ahead／behind 相对本地已获取的远端跟踪引用，不表示托管服务器的实时状态。无上游应显示“未设置上游”，不能解释为已同步。

五类图表

图表 表达内容 点选下钻
提交趋势 每日提交数量，折线／面积；上期对应日用虚线；日均、峰值及有提交天数 对应日期有提交的仓库
工作区状态 干净／有改动／未知的互斥环图，数量和比例；显示状态覆盖率 对应状态仓库
来源分布 各本机／SSH 来源仓库数量，按上述状态堆叠 点击段同时限定来源和状态
活跃仓库排行 本期提交次数 Top 5，显示对总提交的贡献比例 目标仓库详情
主要语言分布 每个仓库按主要语言归类计一次，以数量条形图展示 对应语言仓库

语言图统计的是仓库数，不能解释为代码行数、工作量或人员贡献。未知语言、未采集和分析失败需要明确分类，不能丢弃后仍声称全量覆盖。

筛选与时间

  • 来源筛选影响全部指标、图表、下钻与关注表。
  • 近 7／30／90 天只影响活跃、提交、历史对比、趋势和排行；状态、来源与语言仍为当前快照。
  • 统计图、指标、排行、汇总与明细必须使用同一范围和一致的去重策略。
  • 本期与上期采用相邻且不重叠的等长区间；明确包含当前日期与时间边界。上期为 0 时显示“上期无提交”或“新增”，不显示无穷比率。
  • 分母为 0 时显示可理解的空态，不使用 NaN；历史缺失、尚未采集与实际零提交必须可区分。

关注表与明细

下方“需要关注的仓库”列出有改动、待推拉及状态未知的仓库，跨类别去重。展示名称、来源、分支、工作区状态、同步状态与操作。支持全部、有改动、待同步、未知／异常切换和查看全部。

点选图表或指标打开新版统一明细弹窗；标题与说明明确当前筛选口径，显示完整来源、路径、分支、状态新鲜度及错误原因，并提供打开正确工作区、刷新／重试。明细返回时保留看板筛选。窄窗口使用可滚动的统一弹窗。

首期不包含自动 fetch／pull／push、跨仓库批量写入、人员绩效评分、仓库依赖图或主机拓扑。

UI 与可访问性规格

  • 桌面默认保留现有导航，内容按“标题与操作 → 范围／周期 → 六项数字 → 图表 → 关注表”排列。
  • 数字使用清楚的层级和等宽数字特性；次级文字承担统计范围、单位和更新时间，不用装饰性图表填充空间。
  • 主色用于正常统计系列；琥珀色表达改动，灰色表达未知。关键状态同时显示文字、数量或图标，不能只依赖颜色。
  • 趋势本期为实线，上期为虚线；提示中明确日期和对比含义。当前状态图不会随周期选择变成历史状态图。
  • 图表单位、坐标、图例和样本覆盖范围可见；缺失区间不能通过平滑曲线伪造连续数据。
  • 复用 theme.css 的背景、表面、文字、边框、主色、状态色、圆角与动效变量。支持浅色、深色与减少动态效果。
  • 1440 px 等宽屏保持多图表布局；1024／768 px 按可用宽度重排指标及图表。表格可内部横向滚动，页面无整体横向溢出。
  • 对图表提供可键盘访问的指标／图例／数据表替代入口及必要文字描述；纯 Canvas 点击不能是唯一入口。弹窗支持 Esc、焦点圈定及关闭后恢复到触发项。

原设计的数据能力与工程建议（2026-09-30）

已有数据可复用

仓库登记、来源归属、状态 phase/data/updatedAt/stale、分支与变更文件、ahead/behind、工作区打开动作、视图偏好与主题。

现有状态队列总并发上限 3、后台上限 2，缓存 60 秒（调研基线）。新的聚合方案需要继续尊重状态缓存、去重和资源边界；最终限制以实现时基线为准。

需要新增的数据

  1. 活动聚合：跨仓库提交摘要、周期序列、上一等长周期与排行。
  2. 语言识别：主要语言、采集覆盖率、未知／失败原因及缓存。
  3. 统一聚合摘要：来源、状态、活动与语言的统计版本、时间、范围、覆盖数和部分失败信息。

拟将渲染与采集分开：页面消费摘要，后台按预算采集并增量更新；点击后再加载必要明细。避免每个图表独立重复请求 Git、拉取完整 diff 或扫描文件内容。

控制 SSH 并发、超时、扫描文件数及体积，支持取消、缓存和单来源失败隔离。不能为了显示全量数字在进入页面时无界执行全量远程探测。尚未采集项明确为未知，并提供有范围说明的手动刷新。

提交历史范围、作者时间／提交时间、时区、浅克隆覆盖、多个 clone／worktree 共享历史去重以及语言检测排除规则，需要在实现前落入接口设计和测试。视觉稿按当前分支演示，不代表这些细节全部最终确定。

代码线索

可新增独立总览组件、纯统计派生函数和后台聚合接口。ECharts 已用于视觉稿；正式库选型仍需验证许可证、包体、可访问性与性能，视觉确认不强制具体依赖。

验收标准

  • 卡片／列表／数据总览切换及偏好恢复正确，旧配置兼容，连接页与原视图无回归。
  • 六项核心指标与五类图表数据一致，来源、周期、范围、去重与比例规则可追溯。
  • 同期日期边界及零分母正确，当前快照不随周期切换伪造成历史状态。
  • 状态分类互斥且总和等于登记数；待同步并集去重；无上游、未知、旧缓存及失败无误报。
  • 图表／指标下钻与交集筛选准确，关注表与明细能打开正确仓库。
  • 空列表、无活动、未采集、无匹配、部分失败、浅克隆和远端超时均有明确反馈。
  • 提交及语言统计口径有文档、针对性测试及真实 Git 夹具验证。
  • 缓存、并发、错误隔离、刷新及取消符合资源约束，不隐式同步或修改仓库。
  • 明暗主题、减少动态效果、键盘与语义化替代入口、弹窗焦点及窄屏布局验收通过。
  • 对 0／1／20／100／500 仓库完成真实采集、渲染与本机／SSH 回归记录。

验证记录与证据边界

视觉稿使用同一份可重复计算的 48 仓库演示数据：24 本机、12 开发、8 预发布、4 构建；近 30 天提交 427 次，上期 349 次，21 个活跃仓库。工作区状态为 32 干净、11 有改动、5 未知；待推送 7、待拉取 6，其中 3 个重叠，去重后待同步 10。

日期 场景 结果
2026-09-30 HTML/CSS＋ECharts 浏览器视觉稿；五张图表、指标、明细 已渲染并截图检查
2026-09-30 排行点击、来源筛选、7 天联动、零结果、异常入口、表格筛选、主题与布局 演示交互验证通过
2026-09-30 5 个来源范围（含全部）× 7／30／90 天 15 组演示数据校验通过：每日和提交总数一致，状态与语言汇总等于范围内仓库数，待同步并集正确；见 JSON 附件
2026-09-30 1600 px 桌面／完整页面与 768 px 窄窗口 截图已检查，768 px 无页面整体横向溢出
2026-09-30 历史状态 真正的状态、提交、语言采集；大规模性能；跨平台应用；完整无障碍 当时未运行：产品尚未实现，不能以演示验证代替
2026-10-01 真实数据实现、macOS 浏览器、loopback SSH、0/1/20/100/500 规模 实现与验收记录；跨平台原生与生产边界另列，未视为通过

实现时使用临时本机／SSH 仓库和受控提交历史验证日期、分支、clone/worktree、浅克隆、改动状态和语言识别，记录真实命令、系统和结果。较长验收可另建 Issue-137-Validation。

风险、未决事项与回退

  • 历史和语言统计的采集成本、缓存失效、部分覆盖与去重规则是主要工程风险。
  • 基础状态与新增活动／语言能力可以分阶段交付；未接入的图表必须显示“尚未采集／暂不可用”，不得用随机数据占位。完整验收仍要求本页的六项指标和五类图表。
  • 02／03 布局是否进入首期及是否提供全屏入口待实现评估。
  • 本功能不改变磁盘仓库；若总览需回退，可关闭入口并将失效视图偏好安全回退到卡片，保留原有两种视图。

关联资料