Refactor and enhance form recognition, mapping, and UI components (#18)

* docs: 添加组件文档注释和类型导入

refactor: 统一使用 SnackbarOptions 类型
style: 优化导入语句顺序和格式

* refactor: 简化假数据生成器中的faker导入和使用

Co-authored-by: Copilot <copilot@github.com>

* feat(form-recognizer): 增强表单识别功能并优化UI交互

- 新增字段类型偏好设置功能，支持按域名保存字段类型
- 重构FieldList组件，改进字段选择和类型修改体验
- 添加字段定位闪烁功能，便于在页面上快速找到对应字段
- 优化表单填充逻辑，支持单个字段覆盖默认填充模式
- 移除独立的侧边栏页面，统一使用主页面组件
- 改进useStorageState钩子，增加加载状态管理和防抖处理

* refactor: 移除未使用的组件文件

* refactor(页面头部): 提取通用 PageHeader 组件并替换各页面头部实现

重构各页面头部为统一的 PageHeader 组件，提高代码复用性和维护性

* style(组件): 调整自动刷新开关和存储选项网格的样式

优化自动刷新开关的文本内边距，重构存储选项网格的布局结构，调整间距和边框样式

* style(ui): 调整时间戳页面和结果视图的样式

- 为时区选择器添加圆角
- 优化结果视图的布局和对齐方式
- 调整结果项的内边距和文本样式

* ci(workflow): 移除Firefox测试以简化CI流程

仅保留Chrome浏览器的构建步骤，减少CI运行时间和资源消耗

* refactor(qrcode): 重构二维码解析功能并提取为独立模块

* style(页面样式): 统一页面头部图标颜色并优化表单样式

更新各页面头部组件的图标颜色配置，移除冗余的表单标签属性，优化输入框样式和按钮悬停效果

* feat(formMapping): 添加表单映射功能

- 创建 FormMappingPage 页面组件
- 实现表单扫描器 scanner.ts
- 实现高亮器 highlighter.ts
- 更新路由配置 routes.ts
- 更新内容脚本 content.ts
- 更新类型定义 storage.d.ts
- 添加 formMappingPageStyles 样式配置

* feat(表单映射): 添加配置导出功能及状态提示

添加配置导出为JSON文件的功能，包含导出按钮和错误处理。新增Snackbar组件用于显示导出成功和错误状态。优化页面布局结构，将状态提示移至全局容器外。

* feat(表单填充): 新增智能表单填充功能

添加智能表单填充功能，包括：
1. 新增表单填充页面和路由配置
2. 实现模糊匹配引擎和智能注入引擎
3. 添加Mock数据生成器和视觉反馈渲染器
4. 扩展消息接口支持填充操作

* ci: 精简触发CI的工作流分支

移除对develop分支及其变体的触发，仅保留main分支的触发

* test: 更新路由测试以匹配新增的路由数量

* test: 将测试文件中的描述和断言翻译为中文

* test(PageHeader): 添加组件测试用例验证渲染逻辑和样式

* refactor(theme): 重构主题样式并优化仪表盘卡片组件

将页面样式配置集中管理，移除各页面中硬编码的背景色
新增 DashboardCard 组件封装通用卡片逻辑
添加 dashboardCards 配置文件统一管理卡片数据

* refactor(Button): 统一按钮样式并移除重复样式定义

将按钮样式统一封装到 Button 组件中，移除各页面重复的样式定义
更新组件文档说明，提供更清晰的用法示例

* docs: 更新 README 文件中的目录结构说明

添加新组件和配置文件的说明，保持文档与代码同步

* refactor: 优化代码类型声明和UI布局

修复类型声明从any改为never以提高类型安全性
调整TimestampPage页面布局间距
移除DashboardPage中不必要的实时时钟状态
更新ESLint配置以使用推荐配置
添加选项页面打开的错误处理

* refactor(消息通信): 使用 @webext-core/messaging 重构消息处理逻辑

将原有的 chrome.runtime.onMessage 和 chrome.tabs.sendMessage 替换为类型安全的 @webext-core/messaging 实现
添加 ProtocolMap 类型定义确保消息类型安全
更新相关页面和后台脚本使用新的消息通信方式

* fix: 修复依赖项缺失导致的潜在问题

修复 useStorageState 中缺少 defaultValue 依赖的问题
重构 RouterProvider 的初始化逻辑，使用 useCallback 优化性能

* refactor: 重构表单识别和消息处理逻辑

将表单映射UI逻辑提取到独立文件
将消息处理器提取到独立文件
将表单识别页面逻辑提取到自定义hook
优化代码结构和可维护性

* feat(侧边栏): 添加侧边栏状态变化通知功能

- 在消息类型中新增侧边栏状态变化枚举和字段
- 侧边栏打开和关闭时发送状态通知
- 替换轮询检查方式为消息监听机制

* refactor: 优化高亮组件渲染逻辑并添加防抖处理

重构高亮组件渲染逻辑，使用 requestAnimationFrame 进行节流优化
在 useStorageCleaner 中添加防抖处理以避免频繁加载

* refactor: 统一组件导出方式为默认导出

* refactor: 重构样式系统并迁移至 MUI 主题

删除冗余的 CSS 文件，统一使用 MUI 主题管理样式
新增 useActiveTabDomain 和 useSidePanelState 自定义 Hook
优化各入口点的主题集成和布局处理

* docs: 更新项目文档以反映新增功能和技术栈细节

更新 AGENTS.md 文档，详细描述新增的功能模块（存储管理、URL 管理、二维码生成、表单工具套件等）和更新的技术栈信息

* feat: 添加错误边界组件以捕获子组件错误

在 popup、sidepanel 和 options 入口点添加 ErrorBoundary 组件，用于捕获并处理子组件中的 JavaScript 错误。当错误发生时，显示友好的错误界面并提供刷新功能。

* refactor(ui): 使用全局 snackbar 替换本地通知组件

重构表单页面中的通知系统，移除本地 Snackbar 和 Alert 组件，改用全局 GlobalSnackbar 组件统一管理通知
标准化主题配置中的 CSS 属性命名，移除带前缀的样式属性

* refactor(snackbar): 重构全局消息提示为 SnackbarProvider 组件

将原本分散在各页面的 GlobalSnackbar 组件重构为集中管理的 SnackbarProvider，通过 Context 提供统一的消息提示功能。主要变更包括：

1. 创建新的 SnackbarProvider 组件作为全局消息提示容器
2. 提供 useSnackbar hook 供子组件调用
3. 移除各页面中独立的 GlobalSnackbar 实例
4. 在 App 根组件中统一集成 SnackbarProvider
5. 优化消息提示样式和交互行为

* refactor(Snackbar): 重构消息提示组件并优化样式

重构 Snackbar 组件，将状态管理逻辑提取到 GlobalSnackbar 中复用
优化消息提示样式，调整阴影效果和最小尺寸
统一各页面使用 Snackbar 的方式，移除冗余配置

* refactor: 重构路由和功能配置系统

- 将路由配置和仪表盘卡片配置合并为统一的 features 配置
- 重构 RouterProvider 增加数据校验和本地快照功能
- 优化表单字段识别和填充逻辑，提取公共方法
- 更新相关组件和文档以适配新的配置系统
- 删除废弃的 dashboardCards 和 routes 配置文件

providers/RouterProvider.tsx

@@ -1,70 +1,202 @@
-import { createContext, useContext, useState, useEffect, ReactNode } from 'react';
+import { createContext, useContext, useState, useEffect, ReactNode, useCallback } from 'react';
 import type { PageType, StorageSchema } from '@/types/storage';
 import { storageUtil } from '@/utils/chromeStorage';
-import { getDefaultVisibleRoutes, getDefaultPageOrder } from '@/config/routes';
+import {
+  getDefaultVisibleFeatureKeys,
+  getDefaultPageOrder,
+  getAllFeatureKeys,
+} from '@/config/features';
 
+/**
+ * 校验是否为合法的页面类型
+ */
+const isValidPage = (page: unknown): page is PageType => {
+  return typeof page === 'string' && (getAllFeatureKeys() as string[]).includes(page);
+};
+
+/**
+ * 校验页面列表是否合法（所有项都必须是合法的 PageType）
+ */
+const isValidPageList = (pages: unknown): pages is PageType[] => {
+  return Array.isArray(pages) && pages.every(isValidPage);
+};
+
+/**
+ * 路由上下文类型定义
+ */
 interface RouterContextType {
+  /** 当前所在页面 */
   currentPage: PageType;
+  /** 当前可见的页面列表（用于侧边栏/菜单显示） */
   visiblePages: PageType[];
+  /** 页面显示顺序 */
   pageOrder: PageType[];
+  /** 路由数据是否已从存储中加载完成 */
   isLoaded: boolean;
+  /** 导航到指定页面 */
   navigateTo: (page: PageType) => void;
+  /** 仅在本地（当前组件状态）跳转，不影响其他同步端 */
   navigateLocal: (page: PageType) => void;
+  /** 强制同步当前路由到存储 */
   syncNavigation: (page: PageType) => void;
+  /** 返回仪表盘 */
   goBack: () => void;
+  /** 设置可见页面列表 */
   setVisiblePages: (pages: PageType[]) => void;
+  /** 设置页面显示顺序 */
   setPageOrder: (pages: PageType[]) => void;
 }
 
+/**
+ * 创建路由上下文
+ */
 const RouterContext = createContext<RouterContextType | null>(null);
 
+/**
+ * 路由提供者组件参数类型
+ */
 interface RouterProviderProps {
+  /** 子组件 */
   children: ReactNode;
+  /** 默认初始路由，默认为 'dashboard' */
   defaultRoute?: PageType;
+  /** 是否同步路由状态到存储，默认为 true */
   syncRoute?: boolean;
+  /** 存储路由状态的键名，默认为 'app/currentRoute' */
   syncKey?: keyof StorageSchema;
 }
 
+/**
+ * 同步从 localStorage 获取存储快照（用于消除异步加载产生的首屏闪烁）
+ */
+const getSyncSnapshot = <T,>(
+  key: string,
+  defaultValue: T,
+  validator?: (val: unknown) => val is T,
+): T => {
+  try {
+    const val = localStorage.getItem(`snapshot/${key}`);
+    if (!val) return defaultValue;
+    const parsed = JSON.parse(val) as unknown;
+    if (validator) {
+      return validator(parsed) ? parsed : defaultValue;
+    }
+    return (parsed as T) ?? defaultValue;
+  } catch (error) {
+    console.error('解析同步快照失败:', error);
+    return defaultValue;
+  }
+};
+
+/**
+ * 路由提供者组件
+ * 负责管理应用内部的路由状态、页面可见性及排序，并支持与 Chrome Storage 同步
+ */
 export function RouterProvider({
   children,
   defaultRoute = 'dashboard',
   syncRoute = true,
   syncKey = 'app/currentRoute',
 }: RouterProviderProps) {
-  const [currentPage, setCurrentPage] = useState<PageType>(defaultRoute);
-  const [visiblePages, setVisiblePages] = useState<PageType[]>(getDefaultVisibleRoutes());
-  const [pageOrder, setPageOrder] = useState<PageType[]>(getDefaultPageOrder());
+  // 当前页面状态：优先从同步快照加载，并进行合法性校验
+  const [currentPage, setCurrentPage] = useState<PageType>(() =>
+    getSyncSnapshot(syncKey as string, defaultRoute, isValidPage),
+  );
+  // 可见页面列表状态
+  const [visiblePages, setVisiblePages] = useState<PageType[]>(() =>
+    getSyncSnapshot('app/visiblePages', getDefaultVisibleFeatureKeys(), isValidPageList),
+  );
+  // 页面排序状态
+  const [pageOrder, setPageOrder] = useState<PageType[]>(() =>
+    getSyncSnapshot('app/pageOrder', getDefaultPageOrder(), isValidPageList),
+  );
+  // 加载完成标识
   const [isLoaded, setIsLoaded] = useState(false);
+  /**
+   * 从存储中加载初始路由数据
+   */
+  const loadInitialData = useCallback(async () => {
+    try {
+      const savedRoute = await storageUtil.get(syncKey, defaultRoute);
+      const savedVisiblePages = await storageUtil.get(
+        'app/visiblePages',
+        getDefaultVisibleFeatureKeys(),
+      );
+      const savedPageOrder = await storageUtil.get('app/pageOrder', getDefaultPageOrder());
 
+      // 增加数据合法性校验并进行类型收窄
+      if (isValidPage(savedRoute) && syncRoute) {
+        setCurrentPage(savedRoute);
+      }
+      if (isValidPageList(savedVisiblePages)) {
+        setVisiblePages(savedVisiblePages);
+      }
+      if (isValidPageList(savedPageOrder) && savedPageOrder.length > 0) {
+        setPageOrder(savedPageOrder);
+      }
+    } catch (error) {
+      console.error('加载初始路由数据失败:', error);
+    } finally {
+      setIsLoaded(true);
+    }
+  }, [defaultRoute, syncKey, syncRoute]);
+
+  // 组件挂载时加载初始数据
   useEffect(() => {
-    loadInitialData();
-  }, [syncKey]);
+    loadInitialData().catch(console.error);
+  }, [loadInitialData]);
 
+  // 当 currentPage 改变时，如果开启了同步，则持久化到存储和本地快照
   useEffect(() => {
     if (isLoaded && syncRoute) {
-      storageUtil.set(syncKey, currentPage as any);
+      storageUtil.set(syncKey, currentPage as PageType).catch(console.error);
+      localStorage.setItem(`snapshot/${syncKey}`, JSON.stringify(currentPage));
     }
   }, [currentPage, isLoaded, syncRoute, syncKey]);
 
-  // Listen for storage changes if sync is enabled
+  // 持久化可见页面列表
+  useEffect(() => {
+    if (isLoaded) {
+      storageUtil.set('app/visiblePages', visiblePages).catch(console.error);
+      localStorage.setItem('snapshot/app/visiblePages', JSON.stringify(visiblePages));
+    }
+  }, [visiblePages, isLoaded]);
+
+  // 持久化页面排序
+  useEffect(() => {
+    if (isLoaded) {
+      storageUtil.set('app/pageOrder', pageOrder).catch(console.error);
+      localStorage.setItem('snapshot/app/pageOrder', JSON.stringify(pageOrder));
+    }
+  }, [pageOrder, isLoaded]);
+
+  /**
+   * 监听存储变化，以便在多个入口（如 Popup 和 Options）之间同步路由和设置
+   */
   useEffect(() => {
     if (!syncRoute) return;
 
     const handleStorageChange = (changes: { [key: string]: chrome.storage.StorageChange }) => {
-      // 同步路由
+      // 同步当前路由
       if (syncRoute && changes[syncKey as string]) {
         const newRoute = changes[syncKey as string].newValue as PageType;
-        if (newRoute && newRoute !== currentPage) {
+        if (newRoute && newRoute !== currentPage && isValidPage(newRoute)) {
           setCurrentPage(newRoute);
         }
       }
       // 同步可见页面列表
       if (changes['app/visiblePages']) {
-        setVisiblePages(changes['app/visiblePages'].newValue as PageType[]);
+        const newPages = changes['app/visiblePages'].newValue;
+        if (isValidPageList(newPages)) {
+          setVisiblePages(newPages);
+        }
       }
       // 同步页面排序
       if (changes['app/pageOrder']) {
-        setPageOrder(changes['app/pageOrder'].newValue as PageType[]);
+        const newOrder = changes['app/pageOrder'].newValue;
+        if (isValidPageList(newOrder)) {
+          setPageOrder(newOrder);
+        }
       }
     };
 
@@ -72,42 +204,30 @@ export function RouterProvider({
     return () => chrome.storage.onChanged.removeListener(handleStorageChange);
   }, [syncRoute, currentPage, syncKey]);
 
-  const loadInitialData = async () => {
-    try {
-      const [savedRoute, savedVisiblePages, savedPageOrder] = await Promise.all([
-        storageUtil.get(syncKey, defaultRoute),
-        storageUtil.get('app/visiblePages', getDefaultVisibleRoutes()),
-        storageUtil.get('app/pageOrder', getDefaultPageOrder()),
-      ]);
-
-      if (savedRoute && syncRoute) {
-        setCurrentPage(savedRoute as PageType);
-      }
-      if (savedVisiblePages) {
-        setVisiblePages(savedVisiblePages);
-      }
-      if (savedPageOrder && savedPageOrder.length > 0) {
-        setPageOrder(savedPageOrder);
-      }
-    } catch (error) {
-      console.error('Failed to load initial routing data:', error);
-    } finally {
-      setIsLoaded(true);
-    }
-  };
-
+  /**
+   * 跳转到指定页面
+   */
   const navigateTo = (page: PageType) => {
     setCurrentPage(page);
   };
 
+  /**
+   * 仅在本地跳转，不触发自动同步（通常由 handleStorageChange 内部调用）
+   */
   const navigateLocal = (page: PageType) => {
     setCurrentPage(page);
   };
 
+  /**
+   * 手动同步导航状态到存储
+   */
   const syncNavigation = (page: PageType) => {
-    storageUtil.set(syncKey, page as any);
+    storageUtil.set(syncKey, page as StorageSchema[typeof syncKey]).catch(console.error);
   };
 
+  /**
+   * 返回主仪表盘
+   */
   const goBack = () => {
     setCurrentPage('dashboard');
   };
@@ -132,6 +252,10 @@ export function RouterProvider({
   );
 }
 
+/**
+ * 自定义 Hook：获取路由上下文
+ * @throws {Error} 如果在 RouterProvider 之外使用则抛出异常
+ */
 export function useRouter() {
   const context = useContext(RouterContext);
   if (!context) {