M4 详细设计：首页组件化表达与阅读路径设计

这份详细设计文档用于描述 M4 的核心设计选择：在保持“生成优先”的前提下，如何用最少的自定义组件把首页、模块页和专题页做得更适合阅读。

设计目标

M4 的目标不是再引入新的数据源，而是重新组织现有数据的展示方式。

本轮设计要同时满足四点：

• 保持生成脚本为主入口
• 组件数量尽量少
• 首页信息密度提升，但不失控
• 模块页与专题页既有推荐入口，也保留完整列表

一、组件边界设计

1.1 组件地图

本轮仅引入 3 个 Vue 组件，边界如下：

• SiteStatGrid.vue：负责展示站点统计数据
• SiteDataGrid.vue：负责展示通用卡片列表，如模块卡片、专题卡片、最近更新卡片、推荐入口卡片
• SiteReadingPaths.vue：负责展示按步骤组织的专题阅读路径

1.2 组件职责约束

这些组件只负责“展示”，不负责数据获取。

数据仍然统一由 scripts/generate-vitepress.mjs 计算并直接写入 Markdown 页面或主题配置中。这样可以避免：

• 组件在客户端重复计算数据
• 页面和主题之间出现双重数据源
• VitePress 页面逐步演化成难维护的半前端应用

二、首页信息架构设计

2.1 首页结构

首页按下面顺序组织：

1. Hero
2. 站点概览统计
3. 快速开始模块卡片
4. 重点专题卡片
5. 最近更新卡片
6. 建议阅读路径
7. 搜索与发布说明
8. 相关链接

2.2 统计数据来源

首页统计卡片展示：

• 模块数
• 专题数
• Markdown 总量
• 最近更新日期

这些数据都由生成脚本在构建时直接计算。

2.3 最近更新数据来源

“最近更新”必须基于原始 Markdown 文件的 mtime，而不是 docs-site 生成文件的时间戳。

因此设计上新增一个“原始文件递归采集”流程：

• 遍历仓库顶层学习模块
• 读取 Markdown 标题
• 读取文件修改时间
• 生成排序后的最近更新列表

三、模块页与专题页设计

3.1 模块页设计

模块页保留三层信息：

• 模块基础信息
• 推荐入口卡片
• 最近更新卡片
• 完整文档列表

这样既保留总览索引价值，也提升了“优先读什么”的可见度。

3.2 专题页设计

专题页结构调整为：

• 覆盖模块卡片
• 推荐阅读卡片
• 建议阅读路径

阅读路径按照“专题下模块顺序 -> 模块重点入口”的方式构建，先让读者知道入口，再引导深入阅读。

四、主题与生成协作设计

4.1 主题增强方式

继续使用自动生成的 .vitepress/theme，但在其中注册全局组件，让 Markdown 页面可以直接写：

• <SiteStatGrid />
• <SiteDataGrid />
• <SiteReadingPaths />

4.2 样式策略

样式层遵循两个原则：

• 不做重型主题改造
• 只为卡片展示和阅读路径提供足够的视觉分层

重点使用：

• 卡片边框与阴影
• 响应式网格布局
• 移动端下的单列退化

五、自测设计

本轮至少执行下面几类验证：

5.1 构建验证

• npm run docs:sync
• npm run build

5.2 页面验证

• 首页是否展示统计卡片、最近更新和阅读路径
• 内容导航/ 是否能正常展示卡片入口
• 某个模块页是否出现最近更新区
• 某个专题页是否展示阅读路径组件

5.3 预览验证

• npm run preview
• 访问首页、内容导航页、专题导航页和某个专题页，确认 HTTP 200

六、变更边界

本轮不做：

• 登录态、个性化推荐
• 评论和互动组件
• 外部搜索服务
• 页面级实时数据获取
• 手工编排单篇文章内容

M4 仍然是“生成驱动”的文档站增强，而不是向复杂前端应用转型。