node-resource-utils 0.0.0-stage → 1.1.7

package/resources/src/components/docs/DocsChrome.tsx

@@ -0,0 +1,259 @@
+'use client';
+
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+import { useEffect, useState, type ReactNode } from 'react';
+import { Drawer } from 'antd';
+import {
+  AppstoreOutlined,
+  MenuOutlined,
+  ReadOutlined,
+} from '@ant-design/icons';
+import {
+  docHref,
+  type DocNav,
+  type DocNavGroup,
+  type DocNavPage,
+  type DocsStats,
+} from '@/lib/docs-shared';
+import DocsSearchProvider, { DocsSearchLauncher } from './DocsSearch';
+
+/**
+ * 文档站外壳：顶栏 + 左侧目录 + 内容区。
+ *
+ * 和后台管理外壳刻意分开：
+ *   - 文档是「阅读场景」，不需要业务菜单、收藏、徽标
+ *   - 独立的全宽版式能把正文与右侧目录都放在舒适的位置
+ *   - 从后台进入文档站后，顶栏保留「返回系统」，形成清晰的来去路径
+ *
+ * 移动端把左侧目录收进 Drawer；桌面端保持常驻并 sticky，
+ * 长文档向下滚动时目录始终可见。
+ */
+
+function NavPage({
+  page,
+  active,
+  onNavigate,
+}: {
+  page: DocNavPage;
+  active: boolean;
+  onNavigate?: () => void;
+}) {
+  return (
+    <Link
+      href={docHref(page.slug)}
+      onClick={onNavigate}
+      className={`wb-docs-nav-page ${active ? 'is-active' : ''}`}
+    >
+      <span className="wb-docs-nav-page-text">{page.title}</span>
+    </Link>
+  );
+}
+
+function groupHasActive(group: DocNavGroup, activeSlug: string): boolean {
+  if (group.pages.some((page) => page.slug === activeSlug)) return true;
+  return group.groups.some((child) => groupHasActive(child, activeSlug));
+}
+
+function NavGroup({
+  group,
+  activeSlug,
+  depth = 0,
+  onNavigate,
+}: {
+  group: DocNavGroup;
+  activeSlug: string;
+  depth?: number;
+  onNavigate?: () => void;
+}) {
+  const hasActive = groupHasActive(group, activeSlug);
+  const first = group.pages[0];
+
+  return (
+    <div className={`wb-docs-nav-group ${depth > 0 ? 'is-nested' : ''}`}>
+      {first ? (
+        <Link
+          href={docHref(first.slug)}
+          onClick={onNavigate}
+          className={`wb-docs-nav-group-title ${hasActive ? 'has-active' : ''}`}
+        >
+          {group.title}
+        </Link>
+      ) : (
+        <div className={`wb-docs-nav-group-title ${hasActive ? 'has-active' : ''}`}>
+          {group.title}
+        </div>
+      )}
+      {group.pages.map((page) => (
+        <NavPage
+          key={page.slug}
+          page={page}
+          active={page.slug === activeSlug}
+          onNavigate={onNavigate}
+        />
+      ))}
+      {group.groups.map((child) => (
+        <NavGroup
+          key={child.key}
+          group={child}
+          activeSlug={activeSlug}
+          depth={depth + 1}
+          onNavigate={onNavigate}
+        />
+      ))}
+    </div>
+  );
+}
+
+function DocsNav({
+  nav,
+  activeSlug,
+  stats,
+  onNavigate,
+}: {
+  nav: DocNav;
+  activeSlug: string;
+  stats: DocsStats;
+  onNavigate?: () => void;
+}) {
+  return (
+    <nav className="wb-docs-nav" aria-label="文档目录">
+      <Link
+        href="/docs"
+        onClick={onNavigate}
+        className={`wb-docs-nav-home ${activeSlug === '' ? 'is-active' : ''}`}
+      >
+        <ReadOutlined />
+        <span>文档首页</span>
+      </Link>
+
+      <div className="wb-docs-nav-scroll">
+        {nav.sections.map((section) =>
+          section.type === 'page' ? (
+            <NavPage
+              key={section.slug}
+              page={section}
+              active={section.slug === activeSlug}
+              onNavigate={onNavigate}
+            />
+          ) : (
+            <NavGroup
+              key={section.key}
+              group={section}
+              activeSlug={activeSlug}
+              onNavigate={onNavigate}
+            />
+          )
+        )}
+      </div>
+
+      <div className="wb-docs-nav-foot">
+        {stats.pageCount} 篇文档
+        {stats.updatedAt ? ` · 更新于 ${stats.updatedAt}` : ''}
+      </div>
+    </nav>
+  );
+}
+
+export default function DocsChrome({
+  appName,
+  nav,
+  stats,
+  userName,
+  children,
+}: {
+  appName: string;
+  nav: DocNav;
+  stats: DocsStats;
+  userName: string;
+  children: ReactNode;
+}) {
+  const pathname = usePathname();
+  const [drawerOpen, setDrawerOpen] = useState(false);
+
+  // URL 里的中文/空格会被编码，而导航数据里是原始 slug；两边先统一解码再比较，
+  // 否则中文文件名（通用底座允许）会导致当前项不高亮。
+  const activeSlug =
+    pathname === '/docs'
+      ? ''
+      : pathname
+          .replace(/^\/docs\/?/, '')
+          .replace(/\/+$/, '')
+          .split('/')
+          .map((part) => {
+            try {
+              return decodeURIComponent(part);
+            } catch {
+              return part;
+            }
+          })
+          .join('/');
+
+  // 文档站正文走 window 滚动；切换页面后回到顶部，移动端顺便收起目录
+  useEffect(() => {
+    setDrawerOpen(false);
+    window.scrollTo({ top: 0, behavior: 'auto' });
+  }, [pathname]);
+
+  return (
+    <DocsSearchProvider nav={nav}>
+      <div className="wb-docs">
+        <header className="wb-docs-header">
+          <div className="wb-docs-header-inner">
+            <button
+              type="button"
+              className="wb-docs-menu-btn"
+              aria-label="打开文档目录"
+              onClick={() => setDrawerOpen(true)}
+            >
+              <MenuOutlined />
+            </button>
+
+            <Link href="/docs" className="wb-docs-brand">
+              <span className="wb-docs-brand-logo">{appName.slice(0, 1)}</span>
+              <span className="wb-docs-brand-name">{appName}</span>
+              <span className="wb-docs-brand-divider" />
+              <span className="wb-docs-brand-badge">帮助中心</span>
+            </Link>
+
+            <div className="wb-docs-header-search">
+              <DocsSearchLauncher />
+            </div>
+
+            <div className="wb-docs-header-actions">
+              <span className="wb-docs-user">{userName}</span>
+              <Link href="/dashboard" className="wb-docs-return">
+                <AppstoreOutlined />
+                <span>返回系统</span>
+              </Link>
+            </div>
+          </div>
+        </header>
+
+        <div className="wb-docs-body">
+          <aside className="wb-docs-sidebar">
+            <DocsNav nav={nav} activeSlug={activeSlug} stats={stats} />
+          </aside>
+          <main className="wb-docs-main">{children}</main>
+        </div>
+
+        <Drawer
+          open={drawerOpen}
+          onClose={() => setDrawerOpen(false)}
+          placement="left"
+          size={300}
+          title="帮助中心"
+          className="wb-docs-drawer"
+          styles={{ body: { padding: '8px' } }}
+        >
+          <DocsNav
+            nav={nav}
+            activeSlug={activeSlug}
+            stats={stats}
+            onNavigate={() => setDrawerOpen(false)}
+          />
+        </Drawer>
+      </div>
+    </DocsSearchProvider>
+  );
+}

package/resources/src/components/docs/DocsHome.tsx

@@ -0,0 +1,209 @@
+'use client';
+
+import Link from 'next/link';
+import {
+  ArrowRightOutlined,
+  BookOutlined,
+  CompassOutlined,
+  MessageOutlined,
+} from '@ant-design/icons';
+import { iconOf } from '@/components/admin/menu-icons';
+import type { SearchEntry } from '@/lib/menu-service';
+import {
+  docHref,
+  type DocNav,
+  type DocNavGroup,
+  type DocNavPage,
+  type DocsStats,
+} from '@/lib/docs-shared';
+import { DocsSearchLauncher } from './DocsSearch';
+
+const TONES = 5;
+
+/** 文档首页：搜索入口 + 快速开始 + 分类卡片 + 系统功能速查 */
+export default function DocsHome({
+  appName,
+  nav,
+  stats,
+  features,
+}: {
+  appName: string;
+  nav: DocNav;
+  stats: DocsStats;
+  features: SearchEntry[];
+}) {
+  const rootPages = nav.sections.filter(
+    (section): section is ({ type: 'page' } & DocNavPage) => section.type === 'page'
+  );
+  const groups = nav.sections.filter(
+    (section): section is ({ type: 'group' } & DocNavGroup) => section.type === 'group'
+  );
+
+  // 功能速查由菜单树自动生成：新增业务模块只要登记了菜单，
+  // 这里就会自动出现，不需要再改文档站代码。
+  const featureGroups = new Map<string, SearchEntry[]>();
+  for (const entry of features) {
+    // 目录节点会指向第一个子页面，和它自己的子项重复；功能速查只列具体页面
+    if (entry.path === '/docs' || entry.type === 'dir') continue;
+    const key = entry.trail.split(' / ')[0] || '常用入口';
+    const list = featureGroups.get(key) ?? [];
+    if (list.length < 6) list.push(entry);
+    featureGroups.set(key, list);
+  }
+
+  const empty = stats.pageCount === 0 && groups.length === 0;
+
+  return (
+    <div className="wb-docs-home">
+      <section className="wb-docs-hero">
+        <div className="wb-docs-hero-kicker">
+          <BookOutlined />
+          {appName} · 帮助中心
+        </div>
+        <h1 className="wb-docs-hero-title">系统使用手册</h1>
+        <p className="wb-docs-hero-sub">
+          从账号登录到数据导出，把每一项功能、每一个常见问题按主题整理清楚。
+          找不到答案时，可以直接从顶栏搜索，或前往问题反馈。
+        </p>
+
+        <DocsSearchLauncher variant="hero" />
+
+        <div className="wb-docs-hero-stats">
+          <span>
+            <strong>{stats.pageCount}</strong> 篇文档
+          </span>
+          <span className="wb-docs-hero-dot" />
+          <span>
+            <strong>{stats.groupCount}</strong> 个分类
+          </span>
+          {stats.updatedAt && (
+            <>
+              <span className="wb-docs-hero-dot" />
+              <span>最近更新 {stats.updatedAt}</span>
+            </>
+          )}
+        </div>
+      </section>
+
+      {empty && (
+        <section className="wb-docs-empty">
+          <h2>文档正在建设中</h2>
+          <p>
+            在项目的 <code>content/docs</code> 目录新增 Markdown 文件，刷新后会自动生成文档页与侧边目录。
+          </p>
+        </section>
+      )}
+
+      {rootPages.length > 0 && (
+        <section className="wb-docs-section">
+          <div className="wb-docs-section-head">
+            <h2>快速入口</h2>
+            <span>第一次使用，从这里开始</span>
+          </div>
+          <div className="wb-docs-quick-grid">
+            {rootPages.map((page) => (
+              <Link key={page.slug} href={docHref(page.slug)} className="wb-docs-quick-card">
+                <span className="wb-docs-quick-icon">
+                  <CompassOutlined />
+                </span>
+                <span className="wb-docs-quick-main">
+                  <span className="wb-docs-quick-title">{page.title}</span>
+                  <span className="wb-docs-quick-desc">{page.description || '查看文档'}</span>
+                </span>
+                <ArrowRightOutlined className="wb-docs-quick-arrow" />
+              </Link>
+            ))}
+          </div>
+        </section>
+      )}
+
+      {groups.length > 0 && (
+        <section className="wb-docs-section">
+          <div className="wb-docs-section-head">
+            <h2>按主题浏览</h2>
+            <span>{stats.groupCount} 个分类</span>
+          </div>
+          <div className="wb-docs-group-grid">
+            {groups.map((group, index) => (
+              <article key={group.key} className={`wb-docs-group-card tone-${index % TONES}`}>
+                <div className="wb-docs-group-card-head">
+                  <span className="wb-docs-group-badge">{group.title.slice(0, 1)}</span>
+                  <div>
+                    <h3 className="wb-docs-group-title">{group.title}</h3>
+                    <span className="wb-docs-group-count">{group.count} 篇文档</span>
+                  </div>
+                </div>
+
+                {group.description && (
+                  <p className="wb-docs-group-desc">{group.description}</p>
+                )}
+
+                <div className="wb-docs-group-links">
+                  {group.pages.slice(0, 4).map((page) => (
+                    <Link key={page.slug} href={docHref(page.slug)} className="wb-docs-group-link">
+                      <span>{page.title}</span>
+                      <ArrowRightOutlined />
+                    </Link>
+                  ))}
+                  {group.groups.map((child) => (
+                    <Link
+                      key={child.key}
+                      href={child.pages[0] ? docHref(child.pages[0].slug) : '/docs'}
+                      className="wb-docs-group-link"
+                    >
+                      <span>{child.title}</span>
+                      <ArrowRightOutlined />
+                    </Link>
+                  ))}
+                </div>
+
+                {group.pages[0] && (
+                  <Link href={docHref(group.pages[0].slug)} className="wb-docs-group-enter">
+                    进入分类 <ArrowRightOutlined />
+                  </Link>
+                )}
+              </article>
+            ))}
+          </div>
+        </section>
+      )}
+
+      {featureGroups.size > 0 && (
+        <section className="wb-docs-section wb-docs-feature-section">
+          <div className="wb-docs-section-head">
+            <h2>功能速查</h2>
+            <span>与系统菜单同步，新模块自动出现</span>
+          </div>
+          <div className="wb-docs-feature-grid">
+            {[...featureGroups.entries()].map(([title, entries]) => (
+              <div key={title} className="wb-docs-feature-card">
+                <div className="wb-docs-feature-title">{title}</div>
+                <div className="wb-docs-feature-links">
+                  {entries.map((entry) => (
+                    <Link key={entry.id} href={entry.path} className="wb-docs-feature-link">
+                      <span className="wb-docs-feature-icon">{iconOf(entry.icon)}</span>
+                      <span className="wb-docs-feature-name">{entry.name}</span>
+                    </Link>
+                  ))}
+                </div>
+              </div>
+            ))}
+          </div>
+        </section>
+      )}
+
+      <section className="wb-docs-cta">
+        <span className="wb-docs-cta-icon">
+          <MessageOutlined />
+        </span>
+        <div className="wb-docs-cta-main">
+          <h2>文档没有覆盖到你的问题？</h2>
+          <p>把使用中遇到的异常、建议或数据问题提交给管理员，处理进度可以在反馈页跟踪。</p>
+        </div>
+        <Link href="/feedback" className="wb-docs-cta-btn">
+          前往问题反馈 <ArrowRightOutlined />
+        </Link>
+      </section>
+    </div>
+  );
+}