Add bilingual docs center and replace the guide modal

frontend/components/dashboard/DetailPanel.tsx

@@ -136,8 +136,7 @@ export function DetailPanel() {
   const [heavyContentReady, setHeavyContentReady] = useState(false);
   const isOverlayOpen =
     Boolean(store.futureModalDate) ||
-    store.historyState.isOpen ||
-    store.isGuideOpen;
+    store.historyState.isOpen;
   const isVisible =
     store.isPanelOpen &&
     Boolean(store.selectedCity) &&

frontend/components/dashboard/GuideModal.tsx

@@ -1,105 +0,0 @@
-"use client";
-
-import { useDashboardStore } from "@/hooks/useDashboardStore";
-import { useI18n } from "@/hooks/useI18n";
-
-const GUIDE_CARDS = {
-  "zh-CN": [
-    {
-      body: "Dynamic Ensemble Blending 是系统的核心预测层。它不是对 ECMWF、GFS、ICON、GEM、JMA 等模型的简单平均，而是结合近期样本表现、当前实况与城市偏置后得到的动态加权结果。",
-      title: "DEB 动态融合预测",
-    },
-    {
-      body: "右侧的结算概率分布基于 DEB 预测值与多模型离散度动态计算。μ 代表当前分布中心，会随着模型、实况和时间变化而变化，不是固定结算值。",
-      title: "结算概率引擎",
-    },
-    {
-      body: "结算源按城市市场定义：米兰(LIMC)、华沙(EPWA)、马德里(LEMD)使用机场 METAR；香港市场使用香港天文台(HKO)；台北市场使用交通部中央气象署(CWA)。系统仍会保留 METAR/MGM 作为临近结构参考，并区分观测时间与接收时间。",
-      title: "结算点与主观测源",
-    },
-    {
-      body: "Ankara 不走通用城市逻辑。结算主站以 LTAC / Esenboğa 为准，周边领先信号优先参考 Turkish MGM 站网，其中 Ankara (Bölge/Center) 是重点监控站，不用 Etimesgut 代替。",
-      title: "Ankara 专属增强",
-    },
-    {
-      body: "点击多日预报后的模态框，主要用于分析下一个交易日。6-48 小时趋势以 weather.gov 和 Open-Meteo 为主；0-2 小时临近判断优先看 METAR 与周边站。",
-      title: "未来日期分析",
-    },
-    {
-      body: "历史准确率对账只统计已结算样本。网页端采用近 15 天滚动视图，不把当天尚未结算的样本算入胜率和 MAE。",
-      title: "历史对账规则",
-    },
-  ],
-  "en-US": [
-    {
-      body: "Dynamic Ensemble Blending (DEB) is the core prediction layer. It is not a simple average across ECMWF/GFS/ICON/GEM/JMA, but a dynamically weighted blend adjusted by recent model performance, current observations, and city bias.",
-      title: "DEB Dynamic Fusion",
-    },
-    {
-      body: "Settlement probability distribution is dynamically computed from DEB forecast and model spread. μ is the current distribution center and shifts with model updates, observations, and time.",
-      title: "Settlement Probability Engine",
-    },
-    {
-      body: "Settlement source follows market rule by city: Milan (LIMC), Warsaw (EPWA), and Madrid (LEMD) settle on airport METAR, Hong Kong settles on HKO, and Taipei settles on CWA. METAR/MGM are still kept for intraday structure tracking with observation time vs receipt time separated.",
-      title: "Settlement Source Logic",
-    },
-    {
-      body: "Ankara does not follow the generic city path. LTAC / Esenboğa is the settlement station, with Turkish MGM network for leading signals. Ankara (Bölge/Center) is a key station and is not replaced by Etimesgut.",
-      title: "Ankara-specific Enhancement",
-    },
-    {
-      body: "The multi-day modal focuses on next-session analysis. 6-48h trend mainly relies on weather.gov and Open-Meteo; 0-2h nowcast prioritizes METAR and nearby stations.",
-      title: "Future-date Analysis",
-    },
-    {
-      body: "History reconciliation only uses settled samples. The web dashboard uses a rolling 15-day window and excludes same-day unsettled samples from hit-rate and MAE.",
-      title: "History Rules",
-    },
-  ],
-} as const;
-
-export function GuideModal() {
-  const store = useDashboardStore();
-  const { locale, t } = useI18n();
-
-  if (!store.isGuideOpen) return null;
-
-  return (
-    <div
-      className="modal-overlay"
-      role="dialog"
-      aria-modal="true"
-      aria-labelledby="guide-modal-title"
-      onClick={(event) => {
-        if (event.target === event.currentTarget) {
-          store.closeGuide();
-        }
-      }}
-    >
-      <div className="modal-content large">
-        <div className="modal-header">
-          <h2 id="guide-modal-title">{t("guide.title")}</h2>
-          <button
-            type="button"
-            className="modal-close"
-            aria-label={t("guide.closeAria")}
-            onClick={store.closeGuide}
-          >
-            ×
-          </button>
-        </div>
-        <div className="modal-body">
-          <div className="guide-grid">
-            {GUIDE_CARDS[locale].map((card) => (
-              <div key={card.title} className="guide-card">
-                <h3>{card.title}</h3>
-                <p>{card.body}</p>
-              </div>
-            ))}
-          </div>
-          <div className="guide-footer">{t("guide.footer")}</div>
-        </div>
-      </div>
-    </div>
-  );
-}

frontend/components/dashboard/HeaderBar.tsx

@@ -2,6 +2,7 @@
 
 import { useEffect, useState } from "react";
 import Link from "next/link";
+import { usePathname } from "next/navigation";
 import clsx from "clsx";
 import { LogIn, UserRound } from "lucide-react";
 import { useDashboardStore } from "@/hooks/useDashboardStore";
@@ -14,8 +15,11 @@ import {
 export function HeaderBar() {
   const store = useDashboardStore();
   const { locale, setLocale, t } = useI18n();
+  const pathname = usePathname();
   const [isAuthenticated, setIsAuthenticated] = useState(false);
   const supabaseReady = hasSupabasePublicEnv();
+  const docsHref = "/docs/intro";
+  const docsActive = pathname?.startsWith("/docs");
 
   useEffect(() => {
     let mounted = true;
@@ -78,6 +82,15 @@ export function HeaderBar() {
           </button>
         </div>
 
+        <Link
+          href={docsHref}
+          className={clsx("info-btn", docsActive && "active")}
+          title={t("header.docsAria")}
+          aria-label={t("header.docsAria")}
+        >
+          {t("header.docs")}
+        </Link>
+
         <Link
           href={accountHref}
           className="account-btn"
@@ -88,15 +101,14 @@ export function HeaderBar() {
           <span>{accountLabel}</span>
         </Link>
 
-        <button
-          type="button"
+        <Link
+          href={docsHref}
           className="info-btn"
           title={t("header.infoAria")}
           aria-label={t("header.infoAria")}
-          onClick={store.openGuide}
         >
           {t("header.info")}
-        </button>
+        </Link>
 
         <div className="live-badge" id="liveBadge">
           <span className="pulse-dot" />
@@ -115,4 +127,4 @@ export function HeaderBar() {
       </div>
     </header>
   );
-}
+}

frontend/components/dashboard/MapCanvas.tsx

@@ -21,8 +21,7 @@ export function MapCanvas() {
     selectedDetail: store.selectedDetail,
     suspendMotion:
       Boolean(store.futureModalDate) ||
-      store.historyState.isOpen ||
-      store.isGuideOpen,
+      store.historyState.isOpen,
     isLoadingDetail: store.loadingState.cityDetail,
   });
 

frontend/components/dashboard/PolyWeatherDashboard.tsx

@@ -21,15 +21,6 @@ const MapCanvas = dynamic(
   },
 );
 
-const GuideModal = dynamic(
-  () =>
-    import("@/components/dashboard/GuideModal").then((module) => module.GuideModal),
-  {
-    ssr: false,
-    loading: () => null,
-  },
-);
-
 const HistoryModal = dynamic(
   () =>
     import("@/components/dashboard/HistoryModal").then(
@@ -57,7 +48,6 @@ function DashboardScreen() {
   const { t } = useI18n();
 
   useEffect(() => {
-    void import("@/components/dashboard/GuideModal");
     void import("@/components/dashboard/HistoryModal");
     void import("@/components/dashboard/FutureForecastModal");
   }, []);
@@ -73,10 +63,6 @@ function DashboardScreen() {
         store.closeHistory();
         return;
       }
-      if (store.isGuideOpen) {
-        store.closeGuide();
-        return;
-      }
       if (store.isPanelOpen) {
         store.closePanel();
       }
@@ -100,7 +86,6 @@ function DashboardScreen() {
       <HeaderBar />
       <CitySidebar />
       <DetailPanel />
-      {store.isGuideOpen && <GuideModal />}
       {store.historyState.isOpen && <HistoryModal />}
       {store.futureModalDate && <FutureForecastModal />}
       {showLoading && (

frontend/components/docs/DocsLayout.module.css

@@ -0,0 +1,320 @@
+.docsShell {
+  min-height: 100vh;
+  color: rgba(226, 232, 240, 0.94);
+}
+
+.docsHeader {
+  position: sticky;
+  top: 0;
+  z-index: 40;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 18px 24px;
+  background: rgba(2, 6, 23, 0.82);
+  border-bottom: 1px solid rgba(148, 163, 184, 0.12);
+  backdrop-filter: blur(16px);
+}
+
+.brandWrap {
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+}
+
+.brandLink {
+  color: #67e8f9;
+  font-size: 1.9rem;
+  font-weight: 800;
+  text-decoration: none;
+}
+
+.brandSubtitle {
+  color: rgba(148, 163, 184, 0.88);
+  font-size: 0.95rem;
+}
+
+.headerActions {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+
+.headerButton,
+.headerGhost {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 38px;
+  padding: 0 14px;
+  border-radius: 999px;
+  border: 1px solid rgba(148, 163, 184, 0.18);
+  background: rgba(15, 23, 42, 0.75);
+  color: rgba(226, 232, 240, 0.95);
+  text-decoration: none;
+  font-size: 0.92rem;
+  font-weight: 600;
+}
+
+.headerGhost {
+  background: transparent;
+}
+
+.langSwitch {
+  display: flex;
+  border: 1px solid rgba(148, 163, 184, 0.18);
+  border-radius: 999px;
+  overflow: hidden;
+}
+
+.langButton {
+  min-width: 54px;
+  min-height: 38px;
+  border: 0;
+  background: transparent;
+  color: rgba(148, 163, 184, 0.92);
+  font-weight: 700;
+}
+
+.langButtonActive {
+  background: rgba(34, 211, 238, 0.16);
+  color: #67e8f9;
+}
+
+.docsFrame {
+  display: grid;
+  grid-template-columns: 280px minmax(0, 1fr) 220px;
+  gap: 28px;
+  padding: 24px;
+}
+
+.sidebar {
+  position: sticky;
+  top: 86px;
+  align-self: start;
+  max-height: calc(100vh - 110px);
+  overflow: auto;
+  padding: 20px;
+  border: 1px solid rgba(148, 163, 184, 0.12);
+  border-radius: 20px;
+  background: rgba(15, 23, 42, 0.72);
+}
+
+.sidebarGroup + .sidebarGroup {
+  margin-top: 24px;
+}
+
+.sidebarTitle {
+  margin: 0 0 10px;
+  color: rgba(148, 163, 184, 0.92);
+  font-size: 0.8rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.sidebarLink {
+  display: block;
+  margin-bottom: 6px;
+  padding: 10px 12px;
+  border-radius: 12px;
+  color: rgba(226, 232, 240, 0.88);
+  text-decoration: none;
+  font-size: 0.95rem;
+}
+
+.sidebarLinkActive {
+  background: rgba(34, 211, 238, 0.12);
+  color: #67e8f9;
+}
+
+.content {
+  min-width: 0;
+}
+
+.contentInner {
+  padding: 12px 0 48px;
+}
+
+.pageTitle {
+  margin: 0;
+  font-size: clamp(2.1rem, 4vw, 3.2rem);
+  font-weight: 800;
+  letter-spacing: -0.03em;
+}
+
+.pageDescription {
+  max-width: 820px;
+  margin: 14px 0 0;
+  color: rgba(191, 219, 254, 0.9);
+  font-size: 1.03rem;
+  line-height: 1.75;
+}
+
+.section {
+  margin-top: 40px;
+  scroll-margin-top: 110px;
+}
+
+.sectionTitle {
+  margin: 0 0 16px;
+  font-size: 1.65rem;
+  font-weight: 750;
+}
+
+.paragraph {
+  margin: 0 0 16px;
+  color: rgba(226, 232, 240, 0.94);
+  line-height: 1.9;
+}
+
+.callout {
+  margin: 18px 0;
+  padding: 18px 20px;
+  border: 1px solid rgba(148, 163, 184, 0.16);
+  border-radius: 18px;
+  background: rgba(15, 23, 42, 0.72);
+}
+
+.calloutInfo {
+  border-color: rgba(34, 211, 238, 0.24);
+  background: rgba(8, 47, 73, 0.26);
+}
+
+.calloutWarning {
+  border-color: rgba(251, 191, 36, 0.24);
+  background: rgba(120, 53, 15, 0.2);
+}
+
+.calloutSuccess {
+  border-color: rgba(52, 211, 153, 0.24);
+  background: rgba(6, 78, 59, 0.22);
+}
+
+.calloutTitle {
+  margin: 0 0 8px;
+  font-size: 0.98rem;
+  font-weight: 700;
+}
+
+.calloutText {
+  margin: 0;
+  line-height: 1.8;
+}
+
+.list {
+  margin: 0;
+  padding-left: 20px;
+  color: rgba(226, 232, 240, 0.94);
+  line-height: 1.85;
+}
+
+.list li + li {
+  margin-top: 8px;
+}
+
+.toc {
+  position: sticky;
+  top: 86px;
+  align-self: start;
+  padding: 20px;
+  border: 1px solid rgba(148, 163, 184, 0.12);
+  border-radius: 20px;
+  background: rgba(15, 23, 42, 0.64);
+}
+
+.tocTitle {
+  margin: 0 0 12px;
+  color: rgba(148, 163, 184, 0.92);
+  font-size: 0.82rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.tocLink {
+  display: block;
+  color: rgba(226, 232, 240, 0.86);
+  text-decoration: none;
+  line-height: 1.7;
+  font-size: 0.92rem;
+}
+
+.mobileMenuButton {
+  display: none;
+}
+
+.mobileSidebarBackdrop {
+  display: none;
+}
+
+@media (max-width: 1200px) {
+  .docsFrame {
+    grid-template-columns: 260px minmax(0, 1fr);
+  }
+
+  .toc {
+    display: none;
+  }
+}
+
+@media (max-width: 900px) {
+  .docsHeader {
+    align-items: flex-start;
+    flex-direction: column;
+  }
+
+  .docsFrame {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .mobileMenuButton {
+    display: inline-flex;
+  }
+
+  .sidebar {
+    position: fixed;
+    top: 0;
+    left: 0;
+    z-index: 60;
+    width: min(320px, 88vw);
+    height: 100vh;
+    max-height: none;
+    border-radius: 0 20px 20px 0;
+    transform: translateX(-100%);
+    transition: transform 180ms ease-out;
+  }
+
+  .sidebarOpen {
+    transform: translateX(0);
+  }
+
+  .mobileSidebarBackdrop {
+    position: fixed;
+    inset: 0;
+    z-index: 50;
+    background: rgba(2, 6, 23, 0.52);
+    display: block;
+  }
+}
+
+@media (max-width: 640px) {
+  .docsHeader {
+    padding: 16px;
+  }
+
+  .docsFrame {
+    padding: 16px;
+  }
+
+  .brandWrap {
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 4px;
+  }
+
+  .pageDescription {
+    font-size: 0.98rem;
+  }
+}

frontend/components/docs/DocsScreen.tsx

@@ -0,0 +1,183 @@
+"use client";
+
+import Link from "next/link";
+import { useMemo, useState } from "react";
+import { usePathname } from "next/navigation";
+import clsx from "clsx";
+import styles from "./DocsLayout.module.css";
+import {
+  DocsLocale,
+  DocsPage,
+  DocsPageContent,
+} from "@/content/docs/docs";
+import { DOCS_GROUPS } from "@/content/docs/docs.config";
+import { DOCS_PAGES } from "@/content/docs/docs";
+import { useI18n } from "@/hooks/useI18n";
+
+function DocsHeader() {
+  const { locale, setLocale } = useI18n();
+
+  return (
+    <header className={styles.docsHeader}>
+      <div className={styles.brandWrap}>
+        <Link href="/" className={styles.brandLink}>
+          PolyWeather
+        </Link>
+        <span className={styles.brandSubtitle}>
+          {locale === "zh-CN" ? "产品文档中心" : "Product Documentation"}
+        </span>
+      </div>
+
+      <div className={styles.headerActions}>
+        <Link href="/" className={styles.headerGhost}>
+          {locale === "zh-CN" ? "返回主站" : "Back to App"}
+        </Link>
+        <div className={styles.langSwitch} role="group" aria-label="Language switch">
+          <button
+            type="button"
+            className={clsx(styles.langButton, locale === "zh-CN" && styles.langButtonActive)}
+            onClick={() => setLocale("zh-CN")}
+          >
+            中文
+          </button>
+          <button
+            type="button"
+            className={clsx(styles.langButton, locale === "en-US" && styles.langButtonActive)}
+            onClick={() => setLocale("en-US")}
+          >
+            EN
+          </button>
+        </div>
+      </div>
+    </header>
+  );
+}
+
+function DocsSidebar({
+  currentSlug,
+  locale,
+  open,
+  onClose,
+}: {
+  currentSlug: string;
+  locale: DocsLocale;
+  open: boolean;
+  onClose: () => void;
+}) {
+  return (
+    <>
+      {open && <button type="button" className={styles.mobileSidebarBackdrop} onClick={onClose} aria-label="Close menu" />}
+      <aside className={clsx(styles.sidebar, open && styles.sidebarOpen)}>
+        {DOCS_GROUPS.map((group) => {
+          const pages = DOCS_PAGES.filter((page) => page.group === group.id);
+          return (
+            <div key={group.id} className={styles.sidebarGroup}>
+              <div className={styles.sidebarTitle}>{group.title[locale]}</div>
+              {pages.map((page) => {
+                const title = page.content[locale].title;
+                const href = `/docs/${page.slug}`;
+                return (
+                  <Link
+                    key={page.slug}
+                    href={href}
+                    className={clsx(styles.sidebarLink, currentSlug === page.slug && styles.sidebarLinkActive)}
+                    onClick={onClose}
+                  >
+                    {title}
+                  </Link>
+                );
+              })}
+            </div>
+          );
+        })}
+      </aside>
+    </>
+  );
+}
+
+function DocsToc({ page, locale }: { page: DocsPageContent; locale: DocsLocale }) {
+  return (
+    <aside className={styles.toc}>
+      <div className={styles.tocTitle}>{locale === "zh-CN" ? "本页目录" : "On this page"}</div>
+      {page.sections.map((section) => (
+        <a key={section.id} href={`#${section.id}`} className={styles.tocLink}>
+          {section.title}
+        </a>
+      ))}
+    </aside>
+  );
+}
+
+function BlockRenderer({ block }: { block: DocsPageContent["sections"][number]["blocks"][number] }) {
+  switch (block.type) {
+    case "paragraph":
+      return <p className={styles.paragraph}>{block.text}</p>;
+    case "callout":
+      return (
+        <div className={clsx(styles.callout, block.tone === "warning" && styles.calloutWarning, block.tone === "success" && styles.calloutSuccess, (!block.tone || block.tone === "info") && styles.calloutInfo)}>
+          {block.title ? <div className={styles.calloutTitle}>{block.title}</div> : null}
+          <p className={styles.calloutText}>{block.text}</p>
+        </div>
+      );
+    case "bullets":
+    case "steps":
+      return (
+        <ul className={styles.list}>
+          {block.items.map((item) => (
+            <li key={item}>{item}</li>
+          ))}
+        </ul>
+      );
+    case "image":
+      return (
+        <figure>
+          <img src={block.src} alt={block.alt} />
+          {block.caption ? <figcaption>{block.caption}</figcaption> : null}
+        </figure>
+      );
+    default:
+      return null;
+  }
+}
+
+export function DocsScreen({ page }: { page: DocsPage }) {
+  const pathname = usePathname();
+  const { locale } = useI18n();
+  const [mobileSidebarOpen, setMobileSidebarOpen] = useState(false);
+  const localizedPage = useMemo(() => page.content[locale], [locale, page]);
+  const currentSlug = pathname?.split("/").filter(Boolean).at(-1) || page.slug;
+
+  return (
+    <div className={styles.docsShell}>
+      <DocsHeader />
+      <div className={styles.docsFrame}>
+        <DocsSidebar
+          currentSlug={currentSlug}
+          locale={locale}
+          open={mobileSidebarOpen}
+          onClose={() => setMobileSidebarOpen(false)}
+        />
+
+        <main className={styles.content}>
+          <div className={styles.contentInner}>
+            <button type="button" className={clsx(styles.headerButton, styles.mobileMenuButton)} onClick={() => setMobileSidebarOpen(true)}>
+              {locale === "zh-CN" ? "打开导航" : "Open navigation"}
+            </button>
+            <h1 className={styles.pageTitle}>{localizedPage.title}</h1>
+            <p className={styles.pageDescription}>{localizedPage.description}</p>
+            {localizedPage.sections.map((section) => (
+              <section key={section.id} id={section.id} className={styles.section}>
+                <h2 className={styles.sectionTitle}>{section.title}</h2>
+                {section.blocks.map((block, index) => (
+                  <BlockRenderer key={`${section.id}-${index}`} block={block} />
+                ))}
+              </section>
+            ))}
+          </div>
+        </main>
+
+        <DocsToc page={localizedPage} locale={locale} />
+      </div>
+    </div>
+  );
+}