BIGboss248/nextjs-wordpress

Next.js 页面与路由开发 (nextjs-page-dev)

专门用于创建生产就绪的 Next.js App Router 页面的工作流，支持异步路由参数、本地化翻译字典、动态元数据、类型安全的 JSON-LD 结构化数据（schema-dts）以及静态预渲染。

[!TIP] 模块化资产与深入指南：

• 流式与 UI 边界：references/streaming-and-boundaries.md
• 页面约定与生命周期：references/page-conventions-and-lifecycle.md
• SEO 与结构化数据指南：references/seo-structured-data-guide.md
• 可复用模板：resources/templates/
• 验证脚本：scripts/verify-page.ps1（Windows）/ scripts/verify-page.sh（Linux）

---

架构规则与标准

1. 规划上下文与路由注册

• 读取 docs/project.json 以解析 supported_languages、dictionaries_dir（默认为 "messages"）和 new_component_dir。
• 所有导航 URL 必须引用来自 @/lib/routes 或 @/i18n/navigation 的 ROUTES。
• 目标页面路径层级：app/[locale]/<route-path>/page.tsx（如果非本地化，则为 app/<route-path>/page.tsx）。

2. 零硬编码与字典填充

• 无硬编码内容： 页面标题、标题、描述和静态标签在写入 JSX 之前，必须添加到所有 supported_languages 的 messages/[locale].json 文件中。
• RSC 翻译： 在服务器组件中使用 await getTranslations('<namespace>') 读取翻译。

3. SEO、元数据与 JSON-LD

• 动态元数据： 导出 generateMetadata({ params, searchParams }: Props)，提供动态的 title、description 和规范 URL（alternates: { canonical: ... }）。
• 结构化数据： 使用 schema-dts（WithContext<T>）注入类型化的 JSON-LD，包装在 <script type="application/ld+json"> 中，并将 < 字符转义为 \u003c。
• 有关模式，请参考 references/seo-structured-data-guide.md。

4. 静态预渲染 (generateStaticParams)

• 如果页面嵌套在 [locale] 动态段（或其他动态段）下，且 supported_languages 包含多个语言环境，则导出 generateStaticParams() 返回所有支持的语言环境的 { locale }。

5. 即时导航与细粒度 Suspense 下沉

• 细粒度加载状态：将 <Suspense> 下推到特定的动态子组件，以使静态/缓存部分（头部、英雄区、缓存产品信息）立即提升到静态壳和应用壳中。
• 选择退出：如果某个段本质上是动态的且不需要即时反馈，则配置 export const instant = false。
• 有关流式模式，请参考 references/streaming-and-boundaries.md。

---

工作流步骤

• 步骤 0：实现计划生成与批准关卡

  • 读取 docs/project.json 和 lib/routes.ts 中的目标路由定义。
  • 制定页面元数据、JSON-LD 模式类型、翻译命名空间和组件布局。
  • 如果正在创建主要新页面，则向用户提供简洁的实现计划。

• 步骤 1：填充翻译字典

  • 在所有语言环境的文件（messages/en.json、messages/fa.json 等）中，为页面标题、元描述和页面正文内容添加专用的页面命名空间。

• 步骤 2：创建配套骨架屏 (loading.tsx)

  • 如果页面流式传输内容或获取数据，则根据 loading.tsx.template 部署 loading.tsx。

• 步骤 3：实现页面组件 (page.tsx)

  • 根据 page.tsx.template 部署并自定义：
    1. 定义异步 props 接口（params: Promise<{ locale: string, ... }>、searchParams）。
    2. 导出 generateMetadata()，解析动态标题和规范链接。
    3. 为本地化/动态路由导出 generateStaticParams()。
    4. 实现页面 RSC，从 <new_component_dir>/<page-name>/ 组合章节组件。
    5. 渲染 <JsonLd> 结构化数据组件。

• 步骤 4：验证与健全性检查

  • 运行页面验证脚本：
    • Windows（PowerShell）：

      pwsh .agents/skills/nextjs-page-dev/scripts/verify-page.ps1 -RoutePath <route_dir>
      

    • Linux / macOS（Bash）：

      bash .agents/skills/nextjs-page-dev/scripts/verify-page.sh <route_dir>
      

  • 确保没有 TypeScript 或字典缺失错误。

• 步骤 5：实现计划检查清单同步

  • 在 docs/plan/05-pages-and-components.md 中勾选已完成的页面基础设施项（page.tsx、loading.tsx、error.tsx、generateMetadata、JSON-LD Schema、generateStaticParams()）。
  • 如果该页面的所有子组件检查清单和页面基础设施任务都已完成，则勾选父级页面项（- [x]）。