1. 先实测数据源，再谈架构#

规格里列了 7 个源，写码之前我先把每个都 curl 了一遍，拿到真实返回格式，这一步直接决定了解析层怎么写：

Epic 那个接口有个细节：elements 里混着当前免费和下周预告，要看 promotions.promotionalOffers[].promotionalOffers[] 里有没有 discountPercentage === 0 且 startDate <= now < endDate 的 offer；链接 slug 按 productSlug || urlSlug || catalogNs.mappings[0].pageSlug 优先级取。实测返回里还真有一条 slug 是内部 hash 的（「浮游世界」），链接能用但不是可读名，属于可接受的边缘情况。

2. 技术选型#

💡 通俗理解：整个后端就是一个「报刊订阅员」——每 2 小时去 7 个报刊亭转一圈（Promise.allSettled 并发，哪家关门也不影响别家），新报纸登记入册（url UNIQUE 去重 + is_new 标记），超过 7 天的旧报纸直接扔掉。

3. 后端实现#

1
items(id, source, title, url UNIQUE, summary, category,
2
      published_at, expires_at, first_seen_at,
3
      is_new, claimed, favorited)
4
source_status(source PK, ran_at, ok, item_count, error)

1
for (const raw of r.value) {
2
  const item = { expires_at: null, source: name, ...raw };
3
  if (isOlderThan7d(item)) continue;
4
  item.category = raw.category ?? classify(raw.title);
5
  upsertItem(db, item);
6
  kept++;
7
}
8
recordSourceStatus(db, name, true, kept, null);

4. 前端实现#

Vite + React 19 + Tailwind v4，npx shadcn init 之后加了 button/badge/card/input/switch 五个组件，页面拆成 StatsBar（统计条+刷新按钮）、FilterChips（搜索框+来源/类别 chips+只看新增开关）、DealCard（优惠卡片）三块，状态都在 App.tsx 里用 useState 管，没引数据请求库。

规格里几个点的落地方式：

• chips：shadcn 没有现成 chip，用 Button 的 variant 切换——选中 default（黑底白字）、未选 outline（白底描边），就是规格要的 Toggle 观感。
• 「我的收藏」：当作前端伪类别，筛 favorited === 1，不用后端配合。
• 已领沉底：排序 claimed ASC, is_new DESC, published DESC，卡片 opacity-60 + 标题划线。
• 临期标红：expires_at 距今 <48h 用 destructive Badge，否则普通 outline。
• 失败如实显示：source_status 里 ok=false 的源在统计条下用红色小字逐行列「XX 未能抓取（错误原因）」。

5. 验证#

5.2 端到端#

起服务后首轮：GET /api/status 返回 7/7 成功、119 条在架。点「立即刷新」触发第二轮，新增 11 条真实新帖→共 130 条，「本轮新增 11」计数正确——这正是按 URL 去重 + is_new 翻转想要的效果。

Playwright 开 390px 视口逐项过：类别筛选（点「游戏」剩 5 条）、标题搜索（「浮游」命中 1 条）、PATCH 已领/收藏后卡片置灰划线沉底、Epic 卡片挂「11月13日到期」标签。

6. 踩坑记录#

这次没有大 bug，几个小坑记一下：

1. shadcn CLI 参数变了：shadcn@4.23 里 -b 已经从「base color」变成了「组件库基座」（radix/base/aria），按老习惯敲 -b zinc 直接报 Invalid option。最后用 init -y -t vite -b radix -p nova 非交互跑通，preset 也得显式给，否则会卡在交互选项里。
2. TypeScript 7 移除了 baseUrl：脚手架给的是 typescript@~7.0.2，tsc -b 报 Option 'baseUrl' has been removed。现在 paths 直接相对 tsconfig 所在目录解析，删掉 baseUrl 即可。
3. 测试暴露的健壮性问题：fake 抓取器返回的条目没带 source 字段，入库直接 NOT NULL constraint failed。修的方式不是在每个抓取器里补，而是 round.js 入库前默认 source: name——抓取器忘了填也兜得住。
4. 改 index.html 记得重建：dev 验证时发现页面标题还是 web，因为 Express 托管的是 web/dist，改源文件后要重新 vite build。

7. 总结#

• 从零到可用一轮跑完：7 源实测 → 选型 → 后端 → 前端 → 验证，全部规格点落地
• 实测数据：首轮 119 条、二轮 +11、7/7 源正常、单测 5/5、Playwright 交互逐项过
• 已知边界：Epic hash slug 链接不可读、NodeSeek 全站噪声归「其他」、Jina 免费档限流（2h 一次远低于限额）
• 遗留：本机没有 Docker，multi-stage Dockerfile 写了但没实际构建过，上 VPS 前需要验一次