hoelee-blog/docs/consultant-review-2026-10-27-posts-and-casestudies-plan.md

博客升级执行计划：/posts/ 归档重构与 Case Studies 作品集化

记录时间：2026-10-27
归档状态：已锁定，待下个会话/回合指令开工
顾问裁定依据：

1. 第一轮：《关于 Hoelee Enterprise 技术博客的整体评审与升级建议》
2. 第二轮：《关于 Case Studies Banner 尺寸与 Posts 筛选交互的补充裁定》

---

一、核心决策与交互规范（Decision Register）

1. /categories/case-studies/ 作品集化

• Hero 架构：桌面端采用左右分栏紧凑 Hero（左侧文本 + 右侧视觉）。文字必须使用语义化 HTML，严禁将标题或文字烧入图片；移动端自然堆叠。
• Banner 视觉规格：
  • 比例约 21:9 至 3:1（内容区 900px 下，目标显示高度控制在 240–300px，避免占用过多首屏空间）。
  • 圆角：8–12px，克制。
  • 视觉意象：展示 3 台生产宿主（Unraid / Synology / VPS）、Docker、Prometheus 监控、网络链路与自动化流向；配色遵循暗调终端灰绿 + 暖铜低饱和点缀。
• 案例排序与内容组织：
  • 弃用单纯时间倒序，顶部优先展示 3–4 篇旗舰案例（生产基础设施规模、本地 AI 工作流、端到端自动化）。
  • 卡片突出解决的痛点与量化成果指标（如 3 Hosts · 162 Containers）。
• 行动入口（Affordance）：
  • 卡片保持整卡可点，摘要末尾增加小型文字链接 Read case study → / 阅读案例复盘 →。

2. /posts/ 全部文章归档页

• 结构模型：
  • 顶部：实时搜索栏 + 分类与热门标签过滤条。
  • 中部（Featured 精选区）：展示 2–3 篇旗舰精选文章卡片（16:9 WebP 封面、简短摘要、阅读时间、核心标签）。
  • 下部（完整归档）：紧凑年份与月份条目列表，供高效快速扫读。
• 交互联动机制（顾问裁定）：
  • 默认态：展示 Featured 精选卡片 + 默认全量归档列表。
  • 触发筛选态：一旦用户在搜索框输入首个有效字符，或点击选中任意 Category/Tag 芯片，Featured 精选区执行平滑收起（高度收起 + 150–200ms 过渡，兼容 prefers-reduced-motion），把全量视口空间让给检索结果。
  • 恢复态：用户清空输入且清除 Tag 筛选时，精选区重新展开。
  • 状态反馈：列表上方常驻显式筛选状态（当前过滤条件、命中篇数、一键 Clear filters 按钮）。
  • 全局覆盖：搜索算法对全量文章进行匹配，精选文章在收起状态下依然能在结果列表中被命中展示。

3. 全局组件体验优化

• src/components/PostList.astro 通用卡片组件补全轻量行动链接（Read article → / Read case study →）。
• 严格保证中英双语（EN / ZH）同等体验与无死角本地化。
• 保证 375px/390px 移动端无横向滚动溢出。

---

二、工单拆解与实施路线图

工单 1：/posts/ 混合列表与动态联动（P0）

• 目标文件：
  • src/pages/posts/index.astro
  • src/pages/zh/posts/index.astro
  • src/components/Archive.astro
• 实施内容：
  1. 在 Archive.astro 或 posts/index.astro 中定义 featuredPosts 选取逻辑（复用首页验证过的 3 篇经典系统级案例）。
  2. 实现 Featured 响应式栅格卡片（16:9 WebP 缩略图、标题、阅读时长、摘要、行动链接）。
  3. 改造 Archive.astro 的客户端脚本：
     • 增加 #archive-featured 容器引用与折叠状态类 .is-collapsed。
     • 监听 input 输入与 Tag/Category 按钮点击，计算 isFiltering = Boolean(query || activeTag || activeCat)。
     • 当 isFiltering === true 时，平滑收起 #archive-featured；重置为 false 时恢复。
     • 增加 #archive-filter-status 状态栏（显示匹配数量与“清除筛选”按钮）。
  4. 完善 CSS 过渡动画与 @media (prefers-reduced-motion: reduce) 降级支持。

工单 2：/categories/case-studies/ 紧凑 Hero 与作品集重构（P0）

• 目标文件：
  • src/pages/categories/[category].astro
  • src/pages/zh/categories/[category].astro
  • src/components/CategoryArt.astro
  • src/components/PostList.astro
• 实施内容：
  1. 为 case-studies 类别定制专用 Hero 结构：
     • 桌面端 CSS Grid / Flex 两栏布局（左侧 H1 + 定位介绍，右侧 21:9 / 3:1 扁平架构视觉）。
     • 移动端单栏自然堆叠。
  2. 视觉资产准备：
     • 为 case-studies 制作或导出具备 3 宿主 + Docker + Prometheus 拓扑辨识度的横幅素材（落地于 /images/categories/case-studies-banner.webp）。
     • 在 CategoryArt.astro 或分类页直接引入响应式 <picture> 标签。
  3. 列表项调整：
     • case-studies 分类下的文章加入排序权重（旗舰案例前置）。
     • 卡片增加解决问题、量化结果指标（利用已有的 featuredMetrics 数据源或 frontmatter 扩展）。
  4. 增加卡片右下角 Read case study → / 阅读案例复盘 → 引导文字。

工单 3：全站列表组件与多语言对齐（P1）

• 目标文件：
  • src/components/PostList.astro
  • src/styles/global.css
• 实施内容：
  1. PostList.astro 全面增加可点击的小型文字链接：
     • 普通分类：Read article → / 阅读文章 →
     • Case Studies：Read case study → / 阅读案例复盘 →
  2. 校验中英双语标签字典 categoryLabel，确保无未翻译的英文字段泄漏到 /zh/ 页面。
  3. 确保列表卡片在移动端下的行间距与点击区域（Touch Target ≥ 44px）符合无障碍规范。

工单 4：端到端验收与发布（P0）

• 验收流程：
  1. 本地执行 npm run build，确保 Astro 构建零错误。
  2. 运行 node scripts/check-assets.mjs，确保静态资源引证有效。
  3. 使用 Headless 探测工具或 Playwright 脚本验证 1920px 与 375px 视口下的视觉呈现与水平溢出（scrollWidth === clientWidth）。
  4. 提交 Git 并推送到 Gitea（git.hoelee.com）与 GitHub 镜像。

---

交付记录 — 2026-10-27

按上文四个工单全部落地，构建、资源校验、视口溢出探测均通过。逐项对照：

工单	状态	落地位置	偏差 / 说明
1 · /posts/ 混合归档（EN/ZH）	✅	src/components/Archive.astro、src/lib/featured.ts、src/pages/posts/index.astro、src/pages/zh/posts/index.astro、src/pages/index.astro	旗舰集合用固定 slug（3 张归档 / 4 张首页），不用「最新 N 篇」；不做分页，仍是全量渲染 + 客户端过滤，Ctrl+F 与零请求都保住；筛选时旗舰块折叠为 inert + 高度 0，状态行从 All 91 posts 变为 Showing 27 of 91 posts
2 · case-studies 作品集版式	✅	src/components/PortfolioHero.astro、src/lib/portfolio.ts、src/components/PostList.astro、src/styles/global.css、src/pages/{,zh/}categories/[category].astro	banner 从 3:1 改为 21:9（2400×1029），因为 3:1 在 240–300px 展示高度下纵向空间不足；连线由「三根曲线穿面板」改为共享铜总线；纯几何、无烘焙文字、seeded 确定性，重跑不产生 diff。指标 pill 只取正文出现过的数字（容器数 / VRAM / cron）
3 · 列表组件与多语言对齐	✅	src/components/PostList.astro、src/components/Archive.astro、src/styles/global.css	动作链接为中英双语且不进 Tab 序（每卡一个键盘停留点）；Archive.astro 行尾与分类 chip 原本泄漏英文 slug，已统一走 categoryLabel()；移动端标题链接 min-height: 44px。标签 chip 仍是导航链接（跳 /tags/x/），不改为页内过滤——这是先前锁定的决策，保留
4 · 端到端验收与发布	✅	scripts/probe-layout.mjs（新增）	9 个页面 × 8 个视口（1920/1280/960/768/430/390/375/320）共 72/72 通过，scrollWidth == clientWidth；折叠行为在 EN/ZH × 1280/390 实测；check-assets.mjs 182 篇资源齐备

验收命令：

npm run build && node scripts/check-assets.mjs
python -m http.server 4321 --directory dist &
chrome --headless=new --remote-debugging-port=9333 about:blank &
node scripts/probe-layout.mjs          # 退出码 1 = 有横向溢出或折叠失效

截图评审期间另修的三处（不在原工单内，属于同类体验缺陷）：两条 chip 条带原本无标签且视觉同构 （devops 出现两次：分类 30 / 话题 6）→ 加 Category / Topic 标签、≤700px 时标签上移； 列表卡片标签数封顶 4 个 + +N，修复卡片元信息行高不一致；导航补 aria-current="page" （此前四个栏目链接在任何页面都没有当前位置提示）。

---

复审修复 — 2026-10-27（第二轮）

独立复核实测发现四处遗漏，已修并重新量过（详见 project-state.md §4e-bis）：

#	问题	实测（前 → 后）	改法
P1	移动端 /posts/ 首条归档行在 2.36 屏之外	精选块 1235→523px，卡片 392→153px，首行 1996→1309px（1.55 屏）	≤700px 精选卡改左图右文、隐藏摘要、标题 3 行截断；块头加 All 91 posts ↓（含 scroll-margin-top）
P2	两处新增小字不达 WCAG AA	.feat-min 3.04→5.78；.archive-status 3.67→6.99（AA 需 4.5:1）	--faint → --muted（仅新增元素；既有 91 行日期未动，避免整页重排）
P3	同一分类两套视觉	/categories/ 瓦片原用旧 case-studies.webp	改用 case-studies-banner-1200.webp（14KB）+ object-fit:contain on #0b1613 信箱式留边（16:9 居中裁切会切掉两侧主机面板，已实测）
P4	6min read 缺空格	6min read → 6 min read / 6 分钟	改为模板字符串（同款写法在文章页正常，此处在嵌套 span 内被吞掉）

另：/posts/、/zh/posts/ 导语不再声称"全部按时间倒序"。验收：probe-layout 72/72，折叠在 EN/ZH × 1280/390 仍为 425→0→425 / 523→0→523。