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

@@ -0,0 +1,42 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+!.env*.example
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

README.md

@@ -1,2 +1,36 @@
-# wagtailcms-frontend
+This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
 
+## Getting Started
+
+First, run the development server:
+
+```bash
+npm run dev
+# or
+yarn dev
+# or
+pnpm dev
+# or
+bun dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+
+You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+
+This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+
+## Learn More
+
+To learn more about Next.js, take a look at the following resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+
+You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+
+## Deploy on Vercel
+
+The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+
+Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.

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

@@ -0,0 +1,30 @@
+@import "tailwindcss";
+
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+  /* 主色调，对应 documents/设计方案分析与完善版.md UI 风格约定 */
+  --color-primary: #2563eb;
+  --color-dark: #0f172a;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-primary: var(--color-primary);
+  --color-dark: var(--color-dark);
+  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC",
+    "Microsoft YaHei", sans-serif;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+  }
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+}

app/layout.tsx

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

app/page.tsx

@@ -0,0 +1,27 @@
+import type { Metadata } from "next";
+import { getHomePage } from "@/services/page.service";
+import { BlockRenderer } from "@/blocks/BlockRenderer";
+
+export const metadata: Metadata = {
+  title: "首页",
+};
+
+export default async function Home() {
+  const homePage = await getHomePage().catch(() => null);
+
+  if (!homePage) {
+    return (
+      <div className="mx-auto max-w-3xl px-6 py-32 text-center">
+        <h1 className="mb-4 text-3xl font-semibold text-slate-900">
+          尚未连接到 Wagtail CMS
+        </h1>
+        <p className="text-slate-600">
+          请确认后端服务已启动，并在 <code>.env.local</code> 中配置了{" "}
+          <code>NEXT_PUBLIC_API_URL</code>（默认 http://localhost:8000）。
+        </p>
+      </div>
+    );
+  }
+
+  return <BlockRenderer blocks={homePage.body} />;
+}

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>
+  );
+}

eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

next.config.ts

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

package.json

@@ -0,0 +1,30 @@
+{
+  "name": "frontend",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "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",
+    "zustand": "^5.0.14"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.3.0",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

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>
+  );
+}

public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

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 }),
+}));

tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}

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[];
+}