hoelee
4e64bfc9ae
Deploy / build (push) Successful in 33s
Review pass on the 041471d delivery, measured rather than eyeballed.
/posts/ on a phone put its first archive row 2.36 screens down (featured block
1235 px + 435 px of controls = row at 1996 px at 390x844), so a reader who came
to browse had to scroll past three stacked 16:9 cards. Below 700 px the cards are
now horizontal — thumb 38 %, excerpt dropped, title clamped to three lines — and
the block header carries `All 91 posts ↓` into #archive-list (with scroll-margin
for the sticky header), which doubles as the bypass-block affordance. Block
1235 → 523 px, card 392 → 153 px, first row 1996 → 1309 px.
Two new small-text colours measured under WCAG AA (.feat-min 3.04:1,
.archive-status 3.67:1 at ~12 px) move to --muted → 5.78:1 and 6.99:1. The
featured heading went with them; pre-existing --faint dates (3.67:1) were left
alone rather than restyling 91 rows.
/categories/ still showed the old Gemini case-studies.webp while the category
page had the new topology banner — one category, two art languages. The tile now
uses case-studies-banner-1200.webp (14 KB) letterboxed on #0b1613: a 16:9 centre
crop sliced the outer host panels in half, the letterbox was measured seamless.
`6min read` was emitted without its space (template-literal fix → `6 min read`,
`6 分钟`, verified in dist/). Both /posts/ ledes stopped claiming the page is
purely newest-first.
probe-layout: 72/72 viewport checks, collapse still 425→0→425 (1280) and
523→0→523 (390) in EN and ZH.
138 lines
10 KiB
Markdown
138 lines
10 KiB
Markdown
# 博客升级执行计划：/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 篇资源齐备 |
|
||
|
||
验收命令：
|
||
|
||
```bash
|
||
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。
|