feat: scaffold headless frontend integration per design doc

.env.local.example

@@ -0,0 +1,7 @@
+# 复制为 .env.local 并按实际环境填写。
+
+# Wagtail 后端 API 地址
+NEXT_PUBLIC_API_URL=http://localhost:8000
+
+# 接收后端发布 Webhook 的密钥（需与后端 REVALIDATE_SECRET 一致）
+REVALIDATE_SECRET=change-me

.gitignore

@@ -32,6 +32,7 @@ yarn-error.log*
 
 # env files (can opt-in for committing if needed)
 .env*
+!.env*.example
 
 # vercel
 .vercel

AGENTS.md

@@ -1,9 +0,0 @@
-<!-- BEGIN:nextjs-agent-rules -->
-
-# This is NOT the Next.js you know
-
-This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
-
-This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
-
-<!-- END:nextjs-agent-rules -->

CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md

app/api/revalidate/route.ts

@@ -0,0 +1,34 @@
+import { revalidateTag } from "next/cache";
+import { NextRequest, NextResponse } from "next/server";
+
+/**
+ * 接收 Wagtail `page_published` signal 发出的发布通知，
+ * 对 fetch 缓存标签做精准失效（详见 documents/设计方案分析与完善版.md §2.7）。
+ *
+ * 后端调用示例（apps/core/signals.py）：
+ *   POST {FRONTEND_REVALIDATE_URL}
+ *   Headers: Authorization: Bearer {REVALIDATE_SECRET}
+ *   Body: { "tags": ["page:1", "/some/url/"] }
+ */
+export async function POST(request: NextRequest) {
+  const authHeader = request.headers.get("authorization");
+  const expected = `Bearer ${process.env.REVALIDATE_SECRET}`;
+
+  if (!process.env.REVALIDATE_SECRET || authHeader !== expected) {
+    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
+  }
+
+  const body = await request.json().catch(() => null);
+  const tags: string[] = body?.tags ?? [];
+
+  if (!Array.isArray(tags) || tags.length === 0) {
+    return NextResponse.json({ error: "No tags provided" }, { status: 400 });
+  }
+
+  for (const tag of tags) {
+    // Next.js 16 要求传入 cache profile；"max" 表示立即使该标签下的缓存完全失效。
+    revalidateTag(tag, "max");
+  }
+
+  return NextResponse.json({ revalidated: tags });
+}

app/blog/[slug]/page.tsx

@@ -0,0 +1,35 @@
+import { notFound } from "next/navigation";
+import type { Metadata } from "next";
+import { getBlogBySlug } from "@/services/blog.service";
+import { BlockRenderer } from "@/blocks/BlockRenderer";
+
+interface BlogDetailPageProps {
+  params: Promise<{ slug: string }>;
+}
+
+export async function generateMetadata({
+  params,
+}: BlogDetailPageProps): Promise<Metadata> {
+  const { slug } = await params;
+  const post = await getBlogBySlug(slug).catch(() => null);
+  return { title: post?.title ?? "文章未找到" };
+}
+
+export default async function BlogDetailPage({ params }: BlogDetailPageProps) {
+  const { slug } = await params;
+  const post = await getBlogBySlug(slug).catch(() => null);
+
+  if (!post) {
+    notFound();
+  }
+
+  return (
+    <article className="mx-auto max-w-3xl px-6 py-24">
+      <h1 className="mb-4 text-4xl font-bold text-slate-900">{post.title}</h1>
+      {post.published_at && (
+        <p className="mb-12 text-sm text-slate-500">{post.published_at}</p>
+      )}
+      <BlockRenderer blocks={post.body} />
+    </article>
+  );
+}

app/blog/page.tsx

@@ -0,0 +1,33 @@
+import Link from "next/link";
+import type { Metadata } from "next";
+import { getBlogList } from "@/services/blog.service";
+
+export const metadata: Metadata = {
+  title: "技术博客",
+};
+
+export default async function BlogListPage() {
+  const posts = await getBlogList().catch(() => []);
+
+  return (
+    <div className="mx-auto max-w-4xl px-6 py-24">
+      <h1 className="mb-12 text-4xl font-bold text-slate-900">技术博客</h1>
+      <ul className="space-y-6">
+        {posts.map((post) => (
+          <li key={post.id} className="border-b border-slate-100 pb-6">
+            <Link
+              href={`/blog/${post.meta.slug}`}
+              className="text-2xl font-semibold text-slate-900 hover:text-primary"
+            >
+              {post.title}
+            </Link>
+            {post.intro && <p className="mt-2 text-slate-600">{post.intro}</p>}
+          </li>
+        ))}
+        {posts.length === 0 && (
+          <p className="text-slate-500">暂无文章，或后端服务未连接。</p>
+        )}
+      </ul>
+    </div>
+  );
+}

app/globals.css

@@ -3,13 +3,18 @@
 :root {
   --background: #ffffff;
   --foreground: #171717;
+  /* 主色调，对应 documents/设计方案分析与完善版.md UI 风格约定 */
+  --color-primary: #2563eb;
+  --color-dark: #0f172a;
 }
 
 @theme inline {
   --color-background: var(--background);
   --color-foreground: var(--foreground);
-  --font-sans: var(--font-geist-sans);
+  --color-primary: var(--color-primary);
-  --font-mono: var(--font-geist-mono);
+  --color-dark: var(--color-dark);
+  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC",
+    "Microsoft YaHei", sans-serif;
 }
 
 @media (prefers-color-scheme: dark) {
@@ -22,5 +27,4 @@
 body {
   background: var(--background);
   color: var(--foreground);
-  font-family: Arial, Helvetica, sans-serif;
 }

app/layout.tsx

@@ -1,29 +1,30 @@
 import type { Metadata } from "next";
-import { Geist, Geist_Mono } from "next/font/google";
 import "./globals.css";
+import Header from "@/components/layout/Header";
+import Footer from "@/components/layout/Footer";
+import ReactQueryProvider from "@/providers/react-query-provider";
 
-const geistSans = Geist({
+// 面向中国大陆用户，避免依赖 next/font/google（构建期需访问 Google 服务器）。
-  variable: "--font-geist-sans",
+// 生产环境建议自托管思源黑体 / HarmonyOS Sans 子集，这里先用系统字体栈占位。
-  subsets: ["latin"],
-});
-
-const geistMono = Geist_Mono({
-  variable: "--font-geist-mono",
-  subsets: ["latin"],
-});
 
 export const metadata: Metadata = {
-  title: "Create Next App",
+  title: {
-  description: "Generated by create next app",
+    default: "企业官网",
+    template: "%s | 企业官网",
+  },
+  description: "企业级 Headless CMS 驱动的现代化官网",
 };
 
 export default function RootLayout({ children }: LayoutProps<"/">) {
   return (
-    <html
+    <html lang="zh-hans" className="h-full antialiased">
-      lang="en"
+      <body className="min-h-full flex flex-col font-sans">
-      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
+        <ReactQueryProvider>
-    >
+          <Header />
-      <body className="min-h-full flex flex-col">{children}</body>
+          <main className="flex-1">{children}</main>
+          <Footer />
+        </ReactQueryProvider>
+      </body>
     </html>
   );
 }

app/page.tsx

@@ -1,69 +1,27 @@
-import Image from "next/image";
+import type { Metadata } from "next";
+import { getHomePage } from "@/services/page.service";
+import { BlockRenderer } from "@/blocks/BlockRenderer";
 
-export default function Home() {
+export const metadata: Metadata = {
-  return (
+  title: "首页",
-    <div className="flex flex-col flex-1 items-center justify-center bg-zinc-50 font-sans dark:bg-black">
+};
-      <main className="flex flex-1 w-full max-w-3xl flex-col items-center justify-between py-32 px-16 bg-white dark:bg-black sm:items-start">
+
-        <Image
+export default async function Home() {
-          className="dark:invert h-5 w-[100px]"
+  const homePage = await getHomePage().catch(() => null);
-          src="/next.svg"
+
-          alt="Next.js logo"
+  if (!homePage) {
-          width={100}
+    return (
-          height={20}
+      <div className="mx-auto max-w-3xl px-6 py-32 text-center">
-          priority
+        <h1 className="mb-4 text-3xl font-semibold text-slate-900">
-        />
+          尚未连接到 Wagtail CMS
-        <div className="flex flex-col items-center gap-6 text-center sm:items-start sm:text-left">
+        </h1>
-          <h1 className="max-w-xs text-3xl font-semibold leading-10 tracking-tight text-black dark:text-zinc-50">
+        <p className="text-slate-600">
-            To get started, edit the{" "}
+          请确认后端服务已启动，并在 <code>.env.local</code> 中配置了{" "}
-            <code className="rounded bg-black/[.06] px-1.5 py-0.5 font-mono text-[0.9em] dark:bg-white/[.08]">
+          <code>NEXT_PUBLIC_API_URL</code>（默认 http://localhost:8000）。
-              page.tsx
+        </p>
-            </code>{" "}
+      </div>
-            file.
+    );
-          </h1>
+  }
-          <p className="max-w-md text-lg leading-8 text-zinc-600 dark:text-zinc-400">
+
-            Looking for a starting point or more instructions? Head over to{" "}
+  return <BlockRenderer blocks={homePage.body} />;
-            <a
-              href="https://vercel.com/templates?framework=next.js&utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-              className="font-medium text-zinc-950 dark:text-zinc-50"
-            >
-              Templates
-            </a>{" "}
-            or the{" "}
-            <a
-              href="https://nextjs.org/learn?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-              className="font-medium text-zinc-950 dark:text-zinc-50"
-            >
-              Learning
-            </a>{" "}
-            center.
-          </p>
-        </div>
-        <div className="flex flex-col gap-4 text-base font-medium sm:flex-row">
-          <a
-            className="flex h-12 w-full items-center justify-center gap-2 rounded-full bg-foreground px-5 text-background transition-colors hover:bg-[#383838] dark:hover:bg-[#ccc] md:w-[158px]"
-            href="https://vercel.com/new?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            <Image
-              className="dark:invert h-[14px] w-4"
-              src="/vercel.svg"
-              alt="Vercel logomark"
-              width={16}
-              height={14}
-            />
-            Deploy Now
-          </a>
-          <a
-            className="flex h-12 w-full items-center justify-center rounded-full border border-solid border-black/[.08] px-5 transition-colors hover:border-transparent hover:bg-black/[.04] dark:border-white/[.145] dark:hover:bg-[#1a1a1a] md:w-[158px]"
-            href="https://nextjs.org/docs?utm_source=create-next-app&utm_medium=appdir-template-tw&utm_campaign=create-next-app"
-            target="_blank"
-            rel="noopener noreferrer"
-          >
-            Documentation
-          </a>
-        </div>
-      </main>
-    </div>
-  );
 }

blocks/BlockRenderer.tsx

@@ -0,0 +1,51 @@
+import type { ComponentType } from "react";
+import Hero from "./hero/Hero";
+import Stats from "./stats/Stats";
+import FeatureGrid from "./feature-grid/FeatureGrid";
+import FAQ from "./faq/FAQ";
+import CTA from "./cta/CTA";
+import LogoCloud from "./logo-cloud/LogoCloud";
+import type { StreamFieldBlock } from "@/types/wagtail";
+
+/**
+ * StreamField type → 组件映射表。
+ * 必须与后端 apps/core/blocks.py 的 COMMON_BLOCKS 保持一致，
+ * 否则新增/重命名 Block 时前后端会出现字段不对齐问题
+ * （详见 documents/设计方案分析与完善版.md §2.6）。
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const components: Record<string, ComponentType<{ value: any }>> = {
+  hero: Hero,
+  stats: Stats,
+  feature_grid: FeatureGrid,
+  faq: FAQ,
+  cta: CTA,
+  logo_cloud: LogoCloud,
+};
+
+export function BlockRenderer({ blocks }: { blocks: StreamFieldBlock[] }) {
+  return (
+    <>
+      {blocks?.map((block) => {
+        if (block.type === "richtext") {
+          return (
+            <div
+              key={block.id}
+              className="prose mx-auto max-w-3xl px-6 py-12"
+              dangerouslySetInnerHTML={{ __html: block.value }}
+            />
+          );
+        }
+
+        const Component = components[block.type];
+        if (!Component) {
+          if (process.env.NODE_ENV === "development") {
+            console.warn(`未找到 Block 类型 "${block.type}" 对应的前端组件`);
+          }
+          return null;
+        }
+        return <Component key={block.id} value={block.value} />;
+      })}
+    </>
+  );
+}

blocks/cta/CTA.tsx

@@ -0,0 +1,23 @@
+import Link from "next/link";
+import type { CTABlockValue } from "@/types/wagtail";
+
+export default function CTA({ value }: { value: CTABlockValue }) {
+  return (
+    <section className="py-32">
+      <div className="mx-auto max-w-6xl px-6">
+        <div className="rounded-[40px] bg-gradient-to-r from-blue-600 to-cyan-500 p-20 text-center text-white">
+          <h2 className="mb-6 text-4xl font-bold">{value.heading}</h2>
+          {value.description && (
+            <p className="mb-10 text-xl text-blue-100">{value.description}</p>
+          )}
+          <Link
+            href={value.button.link}
+            className="inline-block rounded-2xl bg-white px-10 py-4 text-lg font-semibold text-primary"
+          >
+            {value.button.text}
+          </Link>
+        </div>
+      </div>
+    </section>
+  );
+}

blocks/faq/FAQ.tsx

@@ -0,0 +1,23 @@
+import type { FAQBlockValue } from "@/types/wagtail";
+
+export default function FAQ({ value }: { value: FAQBlockValue }) {
+  return (
+    <section className="mx-auto max-w-4xl px-6 py-24">
+      <h2 className="mb-12 text-4xl font-bold text-slate-900">常见问题</h2>
+      <div className="space-y-8">
+        {value.items?.map((item, index) => (
+          <div key={`${item.question}-${index}`}>
+            <h3 className="mb-2 text-xl font-semibold text-slate-900">
+              {item.question}
+            </h3>
+            {/* answer 来自 Wagtail RichTextBlock，后端已做 bleach 白名单清洗 */}
+            <div
+              className="text-slate-600"
+              dangerouslySetInnerHTML={{ __html: item.answer }}
+            />
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}

blocks/feature-grid/FeatureGrid.tsx

@@ -0,0 +1,26 @@
+import type { FeatureGridBlockValue } from "@/types/wagtail";
+
+export default function FeatureGrid({ value }: { value: FeatureGridBlockValue }) {
+  return (
+    <section className="bg-slate-50 py-24">
+      <div className="mx-auto max-w-7xl px-6">
+        {value.heading && (
+          <h2 className="mb-16 text-4xl font-bold text-slate-900">{value.heading}</h2>
+        )}
+        <div className="grid gap-8 lg:grid-cols-3">
+          {value.items?.map((item, index) => (
+            <div
+              key={`${item.title}-${index}`}
+              className="rounded-3xl bg-white p-8 shadow-sm"
+            >
+              <h3 className="mb-3 text-2xl font-semibold text-slate-900">
+                {item.title}
+              </h3>
+              <p className="text-slate-600">{item.description}</p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}

blocks/hero/Hero.tsx

@@ -0,0 +1,30 @@
+import Link from "next/link";
+import type { HeroBlockValue } from "@/types/wagtail";
+
+export default function Hero({ value }: { value: HeroBlockValue }) {
+  return (
+    <section className="relative overflow-hidden bg-gradient-to-b from-slate-50 to-white py-32">
+      <div className="mx-auto flex max-w-5xl flex-col items-center px-6 text-center">
+        <h1 className="mb-6 text-5xl font-bold leading-tight text-slate-900">
+          {value.title}
+        </h1>
+        {value.subtitle && (
+          <p className="mb-10 max-w-2xl text-lg leading-8 text-slate-600">
+            {value.subtitle}
+          </p>
+        )}
+        <div className="flex gap-4">
+          {value.buttons?.map((button, index) => (
+            <Link
+              key={`${button.link}-${index}`}
+              href={button.link}
+              className="rounded-2xl bg-primary px-8 py-4 text-white"
+            >
+              {button.text}
+            </Link>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}

blocks/logo-cloud/LogoCloud.tsx

@@ -0,0 +1,28 @@
+import Image from "next/image";
+import type { LogoCloudBlockValue } from "@/types/wagtail";
+
+export default function LogoCloud({ value }: { value: LogoCloudBlockValue }) {
+  return (
+    <section className="py-20">
+      <div className="mx-auto max-w-6xl px-6 text-center">
+        {value.heading && (
+          <h3 className="mb-10 text-lg font-semibold text-slate-500">
+            {value.heading}
+          </h3>
+        )}
+        <div className="flex flex-wrap items-center justify-center gap-10 grayscale">
+          {value.logos?.map((logo, index) => (
+            <Image
+              key={`${logo.url}-${index}`}
+              src={logo.url}
+              alt={logo.title}
+              width={120}
+              height={40}
+              className="h-10 w-auto object-contain"
+            />
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}

blocks/stats/Stats.tsx

@@ -0,0 +1,19 @@
+import type { StatsBlockValue } from "@/types/wagtail";
+
+export default function Stats({ value }: { value: StatsBlockValue }) {
+  return (
+    <section className="py-20">
+      <div className="mx-auto grid max-w-6xl grid-cols-2 gap-8 px-6 lg:grid-cols-4">
+        {value.items?.map((item, index) => (
+          <div
+            key={`${item.label}-${index}`}
+            className="rounded-3xl border border-slate-100 bg-white p-10 text-center shadow-sm"
+          >
+            <div className="mb-3 text-5xl font-bold text-primary">{item.value}</div>
+            <div className="text-slate-600">{item.label}</div>
+          </div>
+        ))}
+      </div>
+    </section>
+  );
+}

components/layout/Footer.tsx

@@ -0,0 +1,24 @@
+export default function Footer() {
+  return (
+    <footer className="mt-auto border-t border-slate-100 bg-slate-950 py-10 text-slate-400">
+      <div className="mx-auto max-w-7xl px-6 text-center text-sm">
+        <p>&copy; {new Date().getFullYear()} 企业官网. All rights reserved.</p>
+        {/*
+          合规要求：中国大陆网站需展示 ICP 备案号并链接至工信部备案查询。
+          详见 documents/设计方案分析与完善版.md §2.15。
+          实际备案号需在完成 ICP 备案后替换。
+        */}
+        <p className="mt-2">
+          <a
+            href="https://beian.miit.gov.cn/"
+            target="_blank"
+            rel="noreferrer"
+            className="hover:text-white"
+          >
+            沪ICP备XXXXXXXX号-1
+          </a>
+        </p>
+      </div>
+    </footer>
+  );
+}

components/layout/Header.tsx

@@ -0,0 +1,25 @@
+import Link from "next/link";
+
+const navItems = [
+  { title: "首页", href: "/" },
+  { title: "博客", href: "/blog" },
+];
+
+export default function Header() {
+  return (
+    <header className="sticky top-0 z-50 border-b border-slate-100 bg-white/80 backdrop-blur">
+      <div className="mx-auto flex h-16 max-w-7xl items-center justify-between px-6">
+        <Link href="/" className="text-xl font-bold text-primary">
+          企业官网
+        </Link>
+        <nav className="flex gap-8">
+          {navItems.map((item) => (
+            <Link key={item.href} href={item.href} className="text-slate-700">
+              {item.title}
+            </Link>
+          ))}
+        </nav>
+      </div>
+    </header>
+  );
+}

next.config.ts

@@ -1,7 +1,14 @@
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
-  /* config options here */
+  images: {
+    // Wagtail 后端媒体地址（开发环境 + 生产环境国内 OSS/CDN 域名）。
+    // 详见 documents/设计方案分析与完善版.md §2.3。
+    remotePatterns: [
+      { protocol: "http", hostname: "localhost" },
+      { protocol: "https", hostname: "**" },
+    ],
+  },
 };
 
 export default nextConfig;

package-lock.json

@@ -8,9 +8,13 @@
       "name": "frontend",
       "version": "0.1.0",
       "dependencies": {
+        "@tanstack/react-query": "^5.101.4",
+        "clsx": "^2.1.1",
+        "lucide-react": "^1.28.0",
         "next": "16.3.0",
         "react": "19.2.8",
-        "react-dom": "19.2.8"
+        "react-dom": "19.2.8",
+        "zustand": "^5.0.14"
       },
       "devDependencies": {
         "@tailwindcss/postcss": "^4",
@@ -277,30 +281,6 @@
         "node": ">=6.9.0"
       }
     },
-    "node_modules/@emnapi/core": {
-      "version": "1.10.0",
-      "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.10.0.tgz",
-      "integrity": "sha512-yq6OkJ4p82CAfPl0u9mQebQHKPJkY7WrIuk205cTYnYe+k2Z8YBh11FrbRG/H6ihirqcacOgl2BIO8oyMQLeXw==",
-      "dev": true,
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "@emnapi/wasi-threads": "1.2.1",
-        "tslib": "^2.4.0"
-      }
-    },
-    "node_modules/@emnapi/runtime": {
-      "version": "1.11.3",
-      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.3.tgz",
-      "integrity": "sha512-Xz4Tpyki7XyrpbUK1jR1AhdAdaXyhhY4lZ3neLodmhpuWfy2PAQN5B46sAiU4liOXGLkHypn/qU+jvfWSCYYLA==",
-      "license": "MIT",
-      "optional": true,
-      "peer": true,
-      "dependencies": {
-        "tslib": "^2.4.0"
-      }
-    },
     "node_modules/@emnapi/wasi-threads": {
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
@@ -1607,6 +1587,32 @@
         "tailwindcss": "4.3.3"
       }
     },
+    "node_modules/@tanstack/query-core": {
+      "version": "5.101.4",
+      "resolved": "https://registry.npmjs.org/@tanstack/query-core/-/query-core-5.101.4.tgz",
+      "integrity": "sha512-gNwcvOJcRbLWPOLG/2OBm+zM+Yv+MKsXKEOWC57USuZDEsI71hEErQsiEGx5wX9rzWWkfwM0fVSPoiIFSsxfiw==",
+      "license": "MIT",
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      }
+    },
+    "node_modules/@tanstack/react-query": {
+      "version": "5.101.4",
+      "resolved": "https://registry.npmjs.org/@tanstack/react-query/-/react-query-5.101.4.tgz",
+      "integrity": "sha512-yRg2pfOCxIs4ZJW3XYYHU/WgtD04FHSnfHlpRT7h7pR77hwkdRG4wxbKe4aq6P0RvXUTBSQpQeadS1SUYUe+KA==",
+      "license": "MIT",
+      "dependencies": {
+        "@tanstack/query-core": "5.101.4"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/tannerlinsley"
+      },
+      "peerDependencies": {
+        "react": "^18 || ^19"
+      }
+    },
     "node_modules/@tybys/wasm-util": {
       "version": "0.10.3",
       "resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.3.tgz",
@@ -1653,7 +1659,7 @@
       "version": "19.2.18",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.18.tgz",
       "integrity": "sha512-AnzbBERsrLKtk2XSfTbYRLjQPdy116Sty4q+T+Bp3IC4l6jNBvreVPAHmpq9qhXQM7CXZPjLVmGMw9sy+hxQ3w==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT",
       "peer": true,
       "dependencies": {
@@ -2758,6 +2764,15 @@
       "integrity": "sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==",
       "license": "MIT"
     },
+    "node_modules/clsx": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/clsx/-/clsx-2.1.1.tgz",
+      "integrity": "sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/color-convert": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
@@ -2811,7 +2826,7 @@
       "version": "3.2.3",
       "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.2.3.tgz",
       "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
-      "dev": true,
+      "devOptional": true,
       "license": "MIT"
     },
     "node_modules/damerau-levenshtein": {
@@ -3416,6 +3431,7 @@
       "integrity": "sha512-whOE1HFo/qJDyX4SnXzP4N6zOWn79WhnCUY/iDR0mPfQZO8wcYE4JClzI2oZrhBnnMUCBCHZhO6VQyoBU95mZA==",
       "dev": true,
       "license": "MIT",
+      "peer": true,
       "dependencies": {
         "@rtsao/scc": "^1.1.0",
         "array-includes": "^3.1.9",
@@ -5049,6 +5065,15 @@
         "yallist": "^3.0.2"
       }
     },
+    "node_modules/lucide-react": {
+      "version": "1.28.0",
+      "resolved": "https://registry.npmjs.org/lucide-react/-/lucide-react-1.28.0.tgz",
+      "integrity": "sha512-fARAFJULsGuDDydjp6+6blekG/sBIM29TerzLjc9bQUKAcEfrSc4ZQKb25KRz4OMKd87cZTb5dgq0w/T6KufVg==",
+      "license": "ISC",
+      "peerDependencies": {
+        "react": "^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+      }
+    },
     "node_modules/magic-string": {
       "version": "0.30.21",
       "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz",
@@ -6789,6 +6814,35 @@
       "peerDependencies": {
         "zod": "^3.25.0 || ^4.0.0"
       }
+    },
+    "node_modules/zustand": {
+      "version": "5.0.14",
+      "resolved": "https://registry.npmjs.org/zustand/-/zustand-5.0.14.tgz",
+      "integrity": "sha512-/8tAspM5LMPr28b3fwLYrtdj77ECpfZviaP75CMTnwO8ISyaE4GDIG/9rDDYq/cH9D2Xw2A2RXglLInmVBQB/g==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=12.20.0"
+      },
+      "peerDependencies": {
+        "@types/react": ">=18.0.0",
+        "immer": ">=9.0.6",
+        "react": ">=18.0.0",
+        "use-sync-external-store": ">=1.2.0"
+      },
+      "peerDependenciesMeta": {
+        "@types/react": {
+          "optional": true
+        },
+        "immer": {
+          "optional": true
+        },
+        "react": {
+          "optional": true
+        },
+        "use-sync-external-store": {
+          "optional": true
+        }
+      }
     }
   }
 }

package.json

@@ -9,9 +9,13 @@
     "lint": "eslint"
   },
   "dependencies": {
+    "@tanstack/react-query": "^5.101.4",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.28.0",
     "next": "16.3.0",
     "react": "19.2.8",
-    "react-dom": "19.2.8"
+    "react-dom": "19.2.8",
+    "zustand": "^5.0.14"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4",

providers/react-query-provider.tsx

@@ -0,0 +1,15 @@
+"use client";
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { useState } from "react";
+
+export default function ReactQueryProvider({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  const [queryClient] = useState(() => new QueryClient());
+  return (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+}

services/api-client.ts

@@ -0,0 +1,38 @@
+/**
+ * Wagtail API v2 请求客户端。
+ * 详见 documents/设计方案分析与完善版.md §2.7 Headless API 设计规范。
+ */
+
+const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:8000";
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+interface FetchOptions {
+  /** ISR 重新验证秒数，默认 60s。传 0 表示不缓存（用于预览）。 */
+  revalidate?: number;
+  /** 关联的缓存标签，供 revalidateTag 精准失效使用。 */
+  tags?: string[];
+}
+
+export async function fetchAPI<T>(
+  path: string,
+  { revalidate = 60, tags }: FetchOptions = {},
+): Promise<T> {
+  const res = await fetch(`${API_BASE_URL}${path}`, {
+    next: { revalidate, tags },
+  });
+
+  if (!res.ok) {
+    throw new ApiError(`API request failed: ${path}`, res.status);
+  }
+
+  return res.json() as Promise<T>;
+}

services/blog.service.ts

@@ -0,0 +1,28 @@
+import { fetchAPI } from "./api-client";
+import type {
+  BlogPageDetail,
+  BlogPageSummary,
+  WagtailListResponse,
+} from "@/types/wagtail";
+
+/**
+ * 获取博客列表（按发布时间倒序）。
+ */
+export async function getBlogList(): Promise<BlogPageSummary[]> {
+  const res = await fetchAPI<WagtailListResponse<BlogPageSummary>>(
+    "/api/v2/pages/?type=blog.BlogPage&fields=intro,published_at&order=-published_at",
+    { tags: ["blog-list"] },
+  );
+  return res.items;
+}
+
+/**
+ * 根据 slug 获取博客详情。
+ */
+export async function getBlogBySlug(slug: string): Promise<BlogPageDetail | null> {
+  const res = await fetchAPI<WagtailListResponse<BlogPageDetail>>(
+    `/api/v2/pages/?type=blog.BlogPage&slug=${encodeURIComponent(slug)}&fields=body,intro,published_at&limit=1`,
+    { tags: [`blog:${slug}`] },
+  );
+  return res.items[0] ?? null;
+}

services/page.service.ts

@@ -0,0 +1,13 @@
+import { fetchAPI } from "./api-client";
+import type { HomePageDetail, WagtailListResponse } from "@/types/wagtail";
+
+/**
+ * 获取首页内容（取页面树中第一条 home.HomePage）。
+ */
+export async function getHomePage(): Promise<HomePageDetail | null> {
+  const res = await fetchAPI<WagtailListResponse<HomePageDetail>>(
+    "/api/v2/pages/?type=home.HomePage&fields=body,seo_title_override,seo_description_override&limit=1",
+    { tags: ["home-page"] },
+  );
+  return res.items[0] ?? null;
+}

stores/app.store.ts

@@ -0,0 +1,11 @@
+import { create } from "zustand";
+
+interface AppState {
+  theme: "light" | "dark";
+  setTheme: (theme: "light" | "dark") => void;
+}
+
+export const useAppStore = create<AppState>((set) => ({
+  theme: "light",
+  setTheme: (theme) => set({ theme }),
+}));

types/wagtail.ts

@@ -0,0 +1,100 @@
+/**
+ * Wagtail API v2 通用类型定义。
+ * 对应后端 apps/core/blocks.py 中的 StreamField Block 结构，
+ * 前后端字段需保持一致（详见 documents/设计方案分析与完善版.md §2.6）。
+ */
+
+export interface WagtailMeta {
+  type: string;
+  detail_url: string;
+  html_url: string | null;
+  slug: string;
+  first_published_at: string | null;
+}
+
+export interface WagtailPageSummary {
+  id: number;
+  meta: WagtailMeta;
+  title: string;
+}
+
+export interface WagtailListResponse<T> {
+  meta: { total_count: number };
+  items: T[];
+}
+
+export interface CTAButtonValue {
+  text: string;
+  link: string;
+}
+
+export interface StatItemValue {
+  value: string;
+  label: string;
+}
+
+export interface FeatureItemValue {
+  icon?: string;
+  title: string;
+  description: string;
+}
+
+export interface FAQItemValue {
+  question: string;
+  answer: string; // richtext HTML
+}
+
+export interface HeroBlockValue {
+  title: string;
+  subtitle?: string;
+  background_image?: { url: string; title: string } | null;
+  buttons: CTAButtonValue[];
+}
+
+export interface StatsBlockValue {
+  items: StatItemValue[];
+}
+
+export interface FeatureGridBlockValue {
+  heading?: string;
+  items: FeatureItemValue[];
+}
+
+export interface FAQBlockValue {
+  items: FAQItemValue[];
+}
+
+export interface CTABlockValue {
+  heading: string;
+  description?: string;
+  button: CTAButtonValue;
+}
+
+export interface LogoCloudBlockValue {
+  heading?: string;
+  logos: { url: string; title: string }[];
+}
+
+export type StreamFieldBlock =
+  | { id: string; type: "hero"; value: HeroBlockValue }
+  | { id: string; type: "stats"; value: StatsBlockValue }
+  | { id: string; type: "feature_grid"; value: FeatureGridBlockValue }
+  | { id: string; type: "faq"; value: FAQBlockValue }
+  | { id: string; type: "cta"; value: CTABlockValue }
+  | { id: string; type: "logo_cloud"; value: LogoCloudBlockValue }
+  | { id: string; type: "richtext"; value: string };
+
+export interface HomePageDetail extends WagtailPageSummary {
+  body: StreamFieldBlock[];
+  seo_title_override?: string;
+  seo_description_override?: string;
+}
+
+export interface BlogPageSummary extends WagtailPageSummary {
+  intro?: string;
+  published_at?: string;
+}
+
+export interface BlogPageDetail extends BlogPageSummary {
+  body: StreamFieldBlock[];
+}