# 首页、分类与详情模板 / Home, section & detail patterns

ID: page-patterns
Version: 1.2.1

按用户意图选择最小必要结构：发现内容、直接浏览、定向查找或理解用法。

Choose the smallest useful structure for discovery, browsing, targeted search, or understanding a resource.

## Anatomy
- 首页：主推与补充 → 最近更新 → 目录 → 入门入口。
  Home: lead and supporting picks → recent updates → sections → starter guides.
- 分类：标题与简介 → 数量 → 最新列表 → 继续展开。
  Category: title and description → count → newest entries → progressive reveal.
- 详情：用途 → 来源与日期 → 用法与限制 → 相关资源。
  Detail: purpose → source and dates → usage and limits → related resources.
- 搜索：查询与筛选 → 结果数量 → 结果 / 空状态。
  Search: query and filters → count → results or empty state.

## Parameters
- home.featured: 1 lead + creative rail
  仅为首页主推与创意轨分配强层级。
  Reserve strong editorial hierarchy for the homepage lead and creative rail.
- category.order: updatedAt desc / key asc
  按已有更新日期排序，相同日期保持稳定顺序。
  Sort by existing update date, then stable key for ties.
- detail.evidence: source + context
  区分来源核对、作者声称与操作实测。
  Distinguish source checks, author claims, and hands-on testing.

## Rules
- 内容量与用户目标决定是否需要筛选；分类首页不默认继承搜索页复杂度。
  Content volume and user intent determine filtering; categories do not inherit search complexity by default.
- 首页精选优先看质量与具体用途，不用最新日期代替推荐理由。
  Select editorial picks by usefulness, not by treating recency as a recommendation.
- 不要在示例里伪造用户量、效果提升、评分或核验时间。
  Do not fabricate user counts, performance gains, ratings, or verification dates.
- 复用现有详情 URL、收藏键和静态阅读能力。
  Preserve existing detail URLs, saved keys, and static reading.

## States
- 内容充足 / Enough content: 保持精选与最新条目的角色区分，渐进展示长列表。
  Separate editorial and recent roles; progressively reveal long lists.
- 内容稀少 / Sparse content: 使用直接列表，不填充无内容的大模块。
  Use a direct list without large empty modules.
- 定向查找 / Targeted search: 进入独立搜索页，URL 保留条件便于分享。
  Use the dedicated search page with shareable URL state.

## Do / Avoid
- Do: 三个真正值得看的推荐，比十个没有理由的占位模块更有用。 / Three justified picks are more useful than ten unexplained placeholder modules.
- Avoid: 照搬电商价格、优惠券和促销倒计时到 AI 资源目录。 / Copy prices, coupons, or promotional countdowns into an AI resource directory.

## Code mapping
- src/components/HomeShell.astro: 编辑精选首页 / Editorial homepage
- src/pages/[section].astro: 分类页 / Category page
- src/pages/search.astro: 独立搜索页 / Dedicated search page

## Dependencies
resource-cards, navigation, feedback, layout

## Acceptance
- 首屏直接回答“这里有什么、下一步做什么”。
  The viewport answers what is here and what to do next.
- 每个模块都有真实内容来源与明确目的。
  Each module has a real content source and purpose.
- 页面稀疏、空结果和长列表都有合理结构。
  Sparse, empty-result, and long-list pages have appropriate structures.

## Implementation example
```
import DirectoryListing from "../components/DirectoryListing.astro";

<h1><Loc zh="学习与工作流" en="Learning & workflows" /></h1>
<p><Loc zh="从教程开始实践。" en="Start with a practical guide." /></p>
<DirectoryListing section="learn" />
```

## Reference
Method reference: https://tmall-design.com/#case/feed
Rules, parameters, examples, and branding in this file are specific to AI UP LAB.