feat: 初始化船长·HeiXiu 桌面应用项目（错误是svg的问题）

Electron + React 19 + TypeScript + Ant Design 6 + Tailwind CSS 4 【核心架构】 - Electron 主进程（窗口管理、平台检测、图标适配） - Vite 构建链（双产物 dist/ + dist-electron/） - 共享层 shared/（类型、常量、工具函数） - IPC 通信框架 + 安全守卫【主题系统】 - 蓝紫渐变主题（亮色/暗色双模式） - Ant Design ConfigProvider 适配（lightAlgorithm / darkAlgorithm） - Tailwind CSS 4 @theme 指令 + CSS 变量 - 设计令牌三处同步（tokens.ts / globals.css / antd-theme.ts）【导航栏】 - 自定义 H5 导航栏替代系统菜单 - 个人版/企业版双布局 - 未登录拦截 + 事件总线驱动登录弹窗【登录注册】 - Modal 弹层（Portal）+ Tabs 切换 - 登录/注册表单动态字段渲染 - 记住密码 / 自动登录 / 用户协议【更新系统】 - 自定义 API 版本检查（替代 electron-updater generic provider） - 手动下载 + SHA512 校验 + spawn NSIS 安装 - 渲染进程更新状态机 Hook（useUpdater） - 检查更新按钮 + 下载进度展示【构建工具链】 - build.mjs 构建总管（--win/--mac/--linux --personal/--enterprise --build/--clean/--sign/--upload/--publish） - scripts/ 自动化脚本（clean / generate-update-info / upload-oss / publish-release） - electron-builder NSIS 安装器（可选路径、多版本打包） - update-info.json 自动生成（fileSize/sha512/changelog/releaseDate）【代码质量】 - ESLint + TypeScript strict + Prettier - husky + lint-staged（提交前自动检查） - commitlint（规范提交信息） - Playwright E2E + Vitest 单元测试框架 - rollup-plugin-visualizer 打包体积分析【文档】 - README.md（快速开始 + 目录结构 + 命令速查） - UpdateA.md（发布手册：API/签名/发版流程/数据库） - CHANGELOG.md（更新日志） - .env.example（构建环境变量模板）
2026-06-03 15:00:51 +08:00
commit 767bb8b297
95 changed files with 20814 additions and 0 deletions
--- a/src/components/AppProvider.tsx
+++ b/src/components/AppProvider.tsx
@@ -0,0 +1,61 @@
+// ============================================================
+// AppProvider — 应用状态 Provider 组件
+// ============================================================
+
+import { useState, useCallback, useEffect, type ReactNode } from 'react';
+import type { Platform, Edition } from '@shared/types';
+
+import { getPlatform, isDev } from '../utils/platform';
+import { parseEdition } from '@shared/constants/app';
+import { safeIpcOn, safeIpcOff } from '../utils/ipc';
+import { AppContext } from '../contexts/app-context';
+import type { AppContextValue } from '../contexts/app-context';
+
+interface AppProviderProps {
+   children: ReactNode;
+}
+
+export function AppProvider({ children }: AppProviderProps) {
+   const [platform] = useState<Platform>(getPlatform);
+   const [edition] = useState<Edition>(() => {
+      return parseEdition(import.meta.env.VITE_EDITION);
+   });
+   const [isLoggedIn, setIsLoggedIn] = useState(false);
+
+   const login = useCallback(() => {
+      // TODO: 接入真实登录流程
+      setIsLoggedIn(true);
+   }, []);
+
+   const logout = useCallback(() => {
+      // TODO: 清理 token、用户状态等
+      setIsLoggedIn(false);
+   }, []);
+
+   // 监听主进程推送的平台/版本信息
+   useEffect(() => {
+      const handler = (_event: unknown, info: unknown) => {
+         const data = info as { platform?: string; edition?: string } | undefined;
+         if (data) {
+            if (isDev()) {
+               console.log('[AppContext] 主进程平台信息:', data);
+            }
+         }
+      };
+      safeIpcOn('platform-info', handler);
+      return () => {
+         safeIpcOff('platform-info', handler);
+      };
+   }, []);
+
+   const value: AppContextValue = {
+      platform,
+      edition,
+      isLoggedIn,
+      login,
+      logout,
+      isDevMode: isDev(),
+   };
+
+   return <AppContext.Provider value={value}>{children}</AppContext.Provider>;
+}
--- a/src/components/ThemeProvider.tsx
+++ b/src/components/ThemeProvider.tsx
@@ -0,0 +1,72 @@
+// ============================================================
+// ThemeProvider — 主题 Provider 组件
+// ============================================================
+
+import { useState, useEffect, useCallback, type ReactNode } from 'react';
+import { ConfigProvider } from 'antd';
+
+import { getThemeConfig } from '../theme/antd-theme';
+import {
+   ThemeContext,
+   readStoredTheme,
+   writeStoredTheme,
+   applyHtmlTheme,
+   STORAGE_KEY,
+} from '../hooks/use-theme';
+import type { ThemeContextValue } from '../hooks/use-theme';
+
+interface ThemeProviderProps {
+   children: ReactNode;
+}
+
+export function ThemeProvider({ children }: ThemeProviderProps) {
+   const [isDark, setIsDark] = useState<boolean>(readStoredTheme);
+
+   // 挂载时同步
+   useEffect(() => {
+      applyHtmlTheme(isDark);
+   }, []); // eslint-disable-line react-hooks/exhaustive-deps
+
+   const toggleTheme = useCallback(() => {
+      setIsDark((prev) => {
+         const next = !prev;
+         writeStoredTheme(next);
+         applyHtmlTheme(next);
+         return next;
+      });
+   }, []);
+
+   const setLight = useCallback(() => {
+      setIsDark(false);
+      writeStoredTheme(false);
+      applyHtmlTheme(false);
+   }, []);
+
+   const setDark = useCallback(() => {
+      setIsDark(true);
+      writeStoredTheme(true);
+      applyHtmlTheme(true);
+   }, []);
+
+   // 监听系统主题变化（仅用户从未手动切换时跟随）
+   useEffect(() => {
+      const mq = window.matchMedia('(prefers-color-scheme: dark)');
+      const handleChange = (e: MediaQueryListEvent) => {
+         const stored = localStorage.getItem(STORAGE_KEY);
+         if (stored === null) {
+            setIsDark(e.matches);
+            applyHtmlTheme(e.matches);
+         }
+      };
+      mq.addEventListener('change', handleChange);
+      return () => mq.removeEventListener('change', handleChange);
+   }, []);
+
+   const ctx: ThemeContextValue = { isDark, toggleTheme, setLight, setDark };
+
+   return (
+      <ThemeContext.Provider value={ctx}>
+         <ConfigProvider theme={getThemeConfig(isDark)}>{children}</ConfigProvider>
+      </ThemeContext.Provider>
+   );
+}
--- a/src/components/common/LegalTextModal.tsx
+++ b/src/components/common/LegalTextModal.tsx
@@ -0,0 +1,77 @@
+// ============================================================
+// LegalTextModal — 协议/法律文本展示弹窗
+// 从 src/assets/legal/ 加载 .txt 文件，主题适配渲染
+// ============================================================
+
+import { Modal, Typography } from 'antd';
+import { FileTextOutlined } from '@ant-design/icons';
+
+import { useTheme } from '@/hooks/use-theme';
+
+// Vite ?raw 导入：将 .txt 内容作为字符串直接内联
+import serviceAgreement from '@/assets/legal/用户服务协议.txt?raw';
+import pointsAgreement from '@/assets/legal/积分充值服务协议.txt?raw';
+
+const { Paragraph } = Typography;
+
+/** 协议名称 → 文本内容映射 */
+const legalTexts: Record<string, { title: string; content: string }> = {
+   service: { title: '用户服务协议', content: serviceAgreement },
+   points: { title: '积分充值服务协议', content: pointsAgreement },
+};
+
+interface LegalTextModalProps {
+   open: boolean;
+   /** 协议标识：'service' | 'points' */
+   type: 'service' | 'points';
+   onClose: () => void;
+}
+
+export function LegalTextModal({ open, type, onClose }: LegalTextModalProps) {
+   const { isDark } = useTheme();
+   const legal = legalTexts[type];
+
+   if (!legal) return null;
+
+   return (
+      <Modal
+         open={open}
+         onCancel={onClose}
+         footer={null}
+         width={640}
+         centered
+         title={
+            <span className="flex items-center gap-2">
+               <FileTextOutlined />
+               {legal.title}
+            </span>
+         }
+         styles={{
+            body: {
+               maxHeight: '60vh',
+               overflowY: 'auto',
+               padding: '20px 24px',
+               background: isDark ? '#1A1730' : '#FFFFFF',
+               color: isDark ? '#E8E6F0' : '#1E1B4B',
+               fontSize: 14,
+               lineHeight: 2,
+               whiteSpace: 'pre-wrap',
+               wordBreak: 'break-word',
+               fontFamily: 'var(--font-family-base)',
+            },
+         }}
+      >
+         <Paragraph
+            style={{
+               color: isDark ? '#E8E6F0' : '#1E1B4B',
+               fontSize: 14,
+               lineHeight: 2,
+               whiteSpace: 'pre-wrap',
+               margin: 0,
+            }}
+         >
+            {legal.content}
+         </Paragraph>
+      </Modal>
+   );
+}
--- a/src/components/navbar/AnnouncementDrawer.tsx
+++ b/src/components/navbar/AnnouncementDrawer.tsx
@@ -0,0 +1,147 @@
+// ============================================================
+// AnnouncementDrawer — 公告侧拉抽屉（SPA 内部弹出）
+// 数据来源：GET /api/v1/announcements
+// ============================================================
+
+import { useEffect, useState, useCallback } from 'react';
+import { Drawer, List, Typography, Empty, Tag, Spin } from 'antd';
+import { NotificationOutlined } from '@ant-design/icons';
+
+import { fetchAnnouncements, type Announcement } from '@/services/modules';
+
+const { Text, Paragraph } = Typography;
+
+// ---------- 辅助 ----------
+
+/** 公告类型 → Tag 颜色映射 */
+const typeColorMap: Record<string, string> = {
+   system: 'blue',
+   feature: 'purple',
+   activity: 'orange',
+   maintenance: 'red',
+};
+
+/** 公告类型 → 中文标签 */
+const typeLabelMap: Record<string, string> = {
+   system: '系统',
+   feature: '功能',
+   activity: '活动',
+   maintenance: '维护',
+};
+
+/** 格式化日期（YYYY-MM-DD） */
+function formatDate(iso: string): string {
+   try {
+      return new Date(iso).toLocaleDateString('zh-CN', {
+         year: 'numeric',
+         month: '2-digit',
+         day: '2-digit',
+      });
+   } catch {
+      return iso;
+   }
+}
+
+// ---------- 组件 ----------
+
+interface AnnouncementDrawerProps {
+   open: boolean;
+   onClose: () => void;
+}
+
+export function AnnouncementDrawer({ open, onClose }: AnnouncementDrawerProps) {
+   const [list, setList] = useState<Announcement[]>([]);
+   const [loading, setLoading] = useState(false);
+   const [error, setError] = useState<string | null>(null);
+
+   // 打开抽屉时请求公告列表
+   const loadAnnouncements = useCallback(async () => {
+      setLoading(true);
+      setError(null);
+      try {
+         const data = await fetchAnnouncements();
+         // 仅展示有效公告
+         setList(data.filter((item) => item.is_active));
+      } catch (err) {
+         setError((err as Error).message || '加载公告失败');
+         setList([]);
+      } finally {
+         setLoading(false);
+      }
+   }, []);
+
+   useEffect(() => {
+      if (open) {
+         loadAnnouncements();
+      }
+   }, [open, loadAnnouncements]);
+
+   // ---- 渲染 ----
+
+   return (
+      <Drawer
+         title={
+            <span className="flex items-center gap-2">
+               <NotificationOutlined />
+               公告
+            </span>
+         }
+         placement="right"
+         size={380}
+         open={open}
+         onClose={onClose}
+         styles={{ body: { padding: 0 } }}
+      >
+         {loading ? (
+            <div className="flex items-center justify-center h-64">
+               <Spin description="加载中..." />
+            </div>
+         ) : error ? (
+            <div className="flex items-center justify-center h-64">
+               <Empty description={error} />
+            </div>
+         ) : list.length === 0 ? (
+            <div className="flex items-center justify-center h-64">
+               <Empty description="暂无公告" />
+            </div>
+         ) : (
+            <List
+               dataSource={list}
+               renderItem={(item) => (
+                  <List.Item className="px-6! py-4!">
+                     <div className="w-full space-y-2">
+                        {/* 标题 + 类型标签 */}
+                        <div className="flex items-center justify-between gap-2">
+                           <Text strong className="text-sm flex-1" ellipsis>
+                              {item.pinned && '📌 '}
+                              {item.title}
+                           </Text>
+                           <Tag
+                              color={typeColorMap[item.type] || 'default'}
+                              className="m-0! text-xs shrink-0"
+                           >
+                              {typeLabelMap[item.type] || item.type}
+                           </Tag>
+                        </div>
+
+                        {/* 内容 */}
+                        <Paragraph
+                           className="mb-0! text-xs"
+                           type="secondary"
+                           ellipsis={{ rows: 2 }}
+                        >
+                           {item.content}
+                        </Paragraph>
+
+                        {/* 日期 */}
+                        <Text type="secondary" className="text-xs">
+                           {formatDate(item.created_at)}
+                        </Text>
+                     </div>
+                  </List.Item>
+               )}
+            />
+         )}
+      </Drawer>
+   );
+}
--- a/src/components/navbar/NavBar.tsx
+++ b/src/components/navbar/NavBar.tsx
@@ -0,0 +1,135 @@
+// ============================================================
+// NavBar — 自定义顶部导航栏（替代系统菜单）
+//
+// 逻辑：
+//   - 所有导航项默认全部显示（不再按登录状态隐藏）
+//   - 未登录时点击需登录的项 → 弹出提示"请先登录"并触发登录 Modal
+//   - 登录/注册 与 退出登录 仍按登录状态互斥显示
+// ============================================================
+
+import { useState, useCallback, useMemo } from 'react';
+import { App } from 'antd';
+
+import { useAppContext } from '@/contexts/app-context';
+import { useTheme } from '@/hooks/use-theme';
+import { emit, EVENTS } from '@/utils/event-bus.ts';
+import { NavItem } from './NavItem';
+import { AnnouncementDrawer } from './AnnouncementDrawer';
+import { personalLeft, personalRight, enterpriseLeft, enterpriseRight } from './nav-config';
+import type { NavItemConfig } from './types';
+
+const NAVBAR_HEIGHT = 56;
+
+export function NavBar() {
+   const { platform, edition, isLoggedIn, logout } = useAppContext();
+   const { isDark } = useTheme();
+   const { message } = App.useApp();
+
+   const [drawerOpen, setDrawerOpen] = useState(false);
+
+   // 根据版本选择导航项
+   const { leftItems, rightItems } = useMemo(() => {
+      const isEnterprise = edition === 'enterprise';
+      return {
+         leftItems: isEnterprise ? enterpriseLeft : personalLeft,
+         rightItems: isEnterprise ? enterpriseRight : personalRight,
+      };
+   }, [edition]);
+
+   // 过滤规则：
+   //   requireGuest → 仅未登录时可见（登录/注册）
+   //   "退出登录"  → 仅已登录时可见
+   //   其他所有项   → 始终可见，未登录点击时弹"请先登录"
+   const visibleLeft = useMemo(
+      () =>
+         leftItems.filter((item) => {
+            if (item.requireGuest && isLoggedIn) return false;
+            return !(item.key === 'logout' && !isLoggedIn);
+         }),
+      [leftItems, isLoggedIn],
+   );
+   const visibleRight = useMemo(
+      () =>
+         rightItems.filter((item) => {
+            if (item.requireGuest && isLoggedIn) return false;
+            return !(item.key === 'logout' && !isLoggedIn);
+         }),
+      [rightItems, isLoggedIn],
+   );
+
+   // 点击导航项
+   const handleNavClick = useCallback(
+      (item: NavItemConfig) => {
+         // 需要登录但未登录 → 提示并弹出登录 Modal
+         if (item.requireLogin && !isLoggedIn) {
+            message.warning('请先登录');
+            emit(EVENTS.SHOW_LOGIN);
+            return;
+         }
+
+         switch (item.action) {
+            case 'drawer':
+               if (item.key === 'announcements') {
+                  setDrawerOpen(true);
+               }
+               break;
+
+            case 'button':
+               if (item.key === 'logout') {
+                  logout();
+               }
+               break;
+
+            case 'external':
+               if (item.target) {
+                  window.open(item.target, '_blank');
+               }
+               break;
+
+            case 'navigate':
+            case 'spa':
+               if (item.key === 'auth') {
+                  emit(EVENTS.SHOW_LOGIN);
+               } else {
+                  console.log('[NavBar] 导航至:', item.target);
+               }
+               break;
+         }
+      },
+      [isLoggedIn, logout, message],
+   );
+
+   const macPaddingLeft = platform === 'darwin' ? 80 : 12;
+
+   return (
+      <>
+         <div
+            className="navbar-drag-region flex items-center justify-between select-none"
+            style={{
+               height: NAVBAR_HEIGHT,
+               paddingLeft: macPaddingLeft,
+               paddingRight: 12,
+               background: isDark
+                  ? 'linear-gradient(180deg, #1E1B4B 0%, #1A1730 100%)'
+                  : 'linear-gradient(180deg, #FFFFFF 0%, #F5F3FF 100%)',
+               borderBottom: `1px solid ${isDark ? '#2E2A4A' : '#E5E7EB'}`,
+               boxShadow: isDark ? '0 1px 4px rgba(0,0,0,0.3)' : '0 1px 4px rgba(99,102,241,0.06)',
+            }}
+         >
+            <div className="navbar-no-drag flex items-center gap-0.5">
+               {visibleLeft.map((item) => (
+                  <NavItem key={item.key} item={item} onClick={handleNavClick} />
+               ))}
+            </div>
+
+            <div className="navbar-no-drag flex items-center gap-0.5">
+               {visibleRight.map((item) => (
+                  <NavItem key={item.key} item={item} onClick={handleNavClick} />
+               ))}
+            </div>
+         </div>
+
+         <AnnouncementDrawer open={drawerOpen} onClose={() => setDrawerOpen(false)} />
+      </>
+   );
+}
--- a/src/components/navbar/NavItem.tsx
+++ b/src/components/navbar/NavItem.tsx
@@ -0,0 +1,52 @@
+// ============================================================
+// NavItem — 单个导航按钮
+// 布局：图标（SVG）在上，文字在下
+// ============================================================
+
+import { useTheme } from '@/hooks/use-theme.ts';
+import type { NavItemConfig } from './types';
+
+interface NavItemProps {
+   item: NavItemConfig;
+   onClick: (item: NavItemConfig) => void;
+}
+
+export function NavItem({ item, onClick }: NavItemProps) {
+   const { isDark } = useTheme();
+   const isLogout = item.key === 'logout';
+
+   return (
+      <button
+         type="button"
+         onClick={() => onClick(item)}
+         title={item.label}
+         className="navbar-no-drag flex flex-col items-center justify-center gap-0.5 px-3 py-1 rounded-md
+                 transition-all duration-200 cursor-pointer border-0
+                 hover:brightness-95 active:scale-95"
+         style={{
+            background: isLogout ? 'transparent' : 'transparent',
+            minWidth: 56,
+            minHeight: 48,
+         }}
+      >
+         {/* SVG 图标 — 内联渲染，currentColor 继承父元素 color */}
+         {item.iconSrc && (
+            <span
+               className="w-5 h-5 inline-block opacity-80"
+               style={{ color: '#6366F1' }}
+               dangerouslySetInnerHTML={{ __html: item.iconSrc }}
+            />
+         )}
+
+         {/* 文字标签 */}
+         <span
+            className="text-xs leading-tight whitespace-nowrap select-none"
+            style={{
+               color: isLogout ? (isDark ? '#F87171' : '#EF4444') : isDark ? '#E8E6F0' : '#1E1B4B',
+            }}
+         >
+            {item.label}
+         </span>
+      </button>
+   );
+}
--- a/src/components/navbar/index.ts
+++ b/src/components/navbar/index.ts
@@ -0,0 +1,3 @@
+export { NavBar } from './NavBar';
+export { AnnouncementDrawer } from './AnnouncementDrawer';
+export type { NavItemConfig, NavBarConfig, NavAction } from './types';
--- a/src/components/navbar/nav-config.ts
+++ b/src/components/navbar/nav-config.ts
@@ -0,0 +1,198 @@
+// ============================================================
+// 导航栏配置 —— 按版本（个人版 / 企业版）定义导航项
+// 每个导航项的 iconSrc 指向 src/assets/header_actions/ 下的 SVG 图标
+// ============================================================
+
+import type { NavItemConfig } from './types';
+
+// ---------- SVG 图标导入（?raw = 内联渲染，使 currentColor 生效）----------
+import complianceAssetsSvg from '@/assets/header_actions/compliance_assets.svg?raw';
+import announcementsSvg from '@/assets/header_actions/announcements.svg?raw';
+import accountSvg from '@/assets/header_actions/account.svg?raw';
+import membershipSvg from '@/assets/header_actions/membership.svg?raw';
+import rechargeSvg from '@/assets/header_actions/recharge.svg?raw';
+import billingSvg from '@/assets/header_actions/billing.svg?raw';
+import orderDetailsSvg from '@/assets/header_actions/order_details.svg?raw';
+import wechatWorkSvg from '@/assets/header_actions/wechat_work.svg?raw';
+import settingsSvg from '@/assets/header_actions/settings.svg?raw';
+import signOutSvg from '@/assets/header_actions/sign_out.svg?raw';
+import projectManagementSvg from '@/assets/header_actions/project_management.svg?raw';
+
+// ============================================================
+// 个人版导航项
+// ============================================================
+
+/** 个人版 — 左侧 */
+const personalLeft: NavItemConfig[] = [
+   {
+      key: 'compliance-assets',
+      label: '合规素材库',
+      iconSrc: complianceAssetsSvg,
+      action: 'navigate',
+      target: '/compliance-assets',
+      position: 'left',
+   },
+];
+
+/** 个人版 — 右侧（从左至右排列） */
+const personalRight: NavItemConfig[] = [
+   {
+      key: 'announcements',
+      label: '公告',
+      iconSrc: announcementsSvg,
+      action: 'drawer',
+      position: 'right',
+   },
+   {
+      key: 'account',
+      label: '查帐户',
+      iconSrc: accountSvg,
+      action: 'navigate',
+      target: '/account',
+      position: 'right',
+      requireLogin: true,
+   },
+   {
+      key: 'vip-activate',
+      label: '开会员/激活',
+      iconSrc: membershipSvg,
+      action: 'navigate',
+      target: '/vip',
+      position: 'right',
+   },
+   {
+      key: 'recharge-points',
+      label: '充值积分',
+      iconSrc: rechargeSvg,
+      action: 'navigate',
+      target: '/recharge',
+      position: 'right',
+      requireLogin: true,
+   },
+   {
+      key: 'billing-history',
+      label: '消费记录',
+      iconSrc: billingSvg,
+      action: 'navigate',
+      target: '/billing',
+      position: 'right',
+      requireLogin: true,
+   },
+   {
+      key: 'order-details',
+      label: '订单明细',
+      iconSrc: orderDetailsSvg,
+      action: 'navigate',
+      target: '/orders',
+      position: 'right',
+      requireLogin: true,
+   },
+   {
+      key: 'wechat-work',
+      label: '企业微信',
+      iconSrc: wechatWorkSvg,
+      action: 'external',
+      target: 'https://work.weixin.qq.com/',
+      position: 'right',
+   },
+   {
+      key: 'settings',
+      label: '设置',
+      iconSrc: settingsSvg,
+      action: 'navigate',
+      target: '/settings',
+      position: 'right',
+   },
+   {
+      key: 'auth',
+      label: '登录/注册',
+      iconSrc: accountSvg,
+      action: 'navigate',
+      target: '/login',
+      position: 'right',
+      requireGuest: true,
+   },
+   {
+      key: 'logout',
+      label: '退出登录',
+      iconSrc: signOutSvg,
+      action: 'button',
+      position: 'right',
+      requireLogin: true,
+   },
+];
+
+// ============================================================
+// 企业版导航项
+// ============================================================
+
+/** 企业版 — 左侧 */
+const enterpriseLeft: NavItemConfig[] = [
+   {
+      key: 'compliance-assets',
+      label: '合规素材库',
+      iconSrc: complianceAssetsSvg,
+      action: 'navigate',
+      target: '/compliance-assets',
+      position: 'left',
+   },
+   {
+      key: 'project-management',
+      label: '项目管理',
+      iconSrc: projectManagementSvg,
+      action: 'navigate',
+      target: '/projects',
+      position: 'left',
+   },
+];
+
+/** 企业版 — 右侧（从左至右排列） */
+const enterpriseRight: NavItemConfig[] = [
+   {
+      key: 'announcements',
+      label: '公告',
+      iconSrc: announcementsSvg,
+      action: 'drawer',
+      position: 'right',
+   },
+   {
+      key: 'quota-check',
+      label: '查配额',
+      iconSrc: accountSvg,
+      action: 'navigate',
+      target: '/quota',
+      position: 'right',
+      requireLogin: false,
+   },
+   {
+      key: 'settings',
+      label: '设置',
+      iconSrc: settingsSvg,
+      action: 'navigate',
+      target: '/settings',
+      position: 'right',
+   },
+   {
+      key: 'auth',
+      label: '登录/注册',
+      iconSrc: accountSvg,
+      action: 'navigate',
+      target: '/login',
+      position: 'right',
+      requireGuest: true,
+   },
+   {
+      key: 'logout',
+      label: '退出登录',
+      iconSrc: signOutSvg,
+      action: 'button',
+      position: 'right',
+      requireLogin: true,
+   },
+];
+
+// ============================================================
+// 导出
+// ============================================================
+
+export { personalLeft, personalRight, enterpriseLeft, enterpriseRight };
--- a/src/components/navbar/types.ts
+++ b/src/components/navbar/types.ts
@@ -0,0 +1,41 @@
+// ============================================================
+// 导航栏类型定义
+// ============================================================
+
+import type { Edition } from '@shared/types';
+
+/** 导航项的行为类型 */
+export type NavAction =
+   | 'navigate' // 新开窗口
+   | 'spa' // 单页应用内导航（当前窗口）
+   | 'drawer' // 侧拉抽屉（公告等）
+   | 'button' // 纯按钮行为（退出登录）
+   | 'external'; // 外部链接
+
+/** 单个导航项配置 */
+export interface NavItemConfig {
+   /** 唯一标识 */
+   key: string;
+   /** 显示文字 */
+   label: string;
+   /** SVG 图标资源路径（Vite import 后的 URL） */
+   iconSrc?: string;
+   /** 行为类型 */
+   action: NavAction;
+   /** 点击回调 / 路由路径 / 外部 URL（取决于 action） */
+   target?: string;
+   /** 仅在指定版本下显示 */
+   edition?: Edition | Edition[];
+   /** 仅已登录时显示 */
+   requireLogin?: boolean;
+   /** 仅未登录时显示 */
+   requireGuest?: boolean;
+   /** 排列位置 */
+   position: 'left' | 'right';
+}
+
+/** 导航栏配置（按版本分组） */
+export interface NavBarConfig {
+   left: NavItemConfig[];
+   right: NavItemConfig[];
+}