search-syntax-pro/.claude/specs/需求文档实现/02-system-architecture.md

SSP智能搜索插件 - 系统架构设计

架构概览

基于您的技术决策，系统架构采用现代化技术栈和Chrome扩展最佳实践：

核心技术栈:

• 语言: TypeScript 5.x
• 构建工具: Vite 5.x + 热重载开发环境
• UI框架: 轻量级方案（考虑 Preact/Mithril）
• 样式: SCSS + CSS Modules 或 Tailwind CSS
• 状态管理: 基于Chrome Storage的轻量级状态管理

Chrome扩展架构:

• Manifest V3: 使用最新标准
• Service Worker: 替代背景页面
• Content Scripts: 页面内容注入
• Popup/Options: 扩展界面组件

系统架构图

┌─────────────────────────────────────────────────────────┐
│                Chrome Extension                         │
├─────────────────────────────────────────────────────────┤
│  UI Layer (380-420px width)                            │
│  ├── Popup UI (主界面)                                  │
│  │   ├── SearchForm Component                          │
│  │   ├── SyntaxOptions Component                       │
│  │   ├── QueryPreview Component                       │
│  │   └── HistoryPanel Component                       │
│  ├── Options Page (设置页面)                           │
│  └── Side Panel (侧边栏)                               │
├─────────────────────────────────────────────────────────┤
│  Business Logic Layer                                  │
│  ├── SearchQueryService                                │
│  ├── SyntaxValidator                                   │
│  ├── HistoryManager                                    │
│  └── SettingsManager                                   │
├─────────────────────────────────────────────────────────┤
│  Search Engine Adapters                                │
│  ├── BaiduAdapter                                      │
│  ├── GoogleAdapter                                     │
│  ├── BingAdapter                                       │
│  └── AdapterFactory                                    │
├─────────────────────────────────────────────────────────┤
│  Data Access Layer                                     │
│  ├── ChromeStorageService                              │
│  ├── LocalizationService                               │
│  ├── DataPortability (导入导出)                        │
│  └── ConfigurationService                              │
└─────────────────────────────────────────────────────────┘

详细组件设计

1. UI层架构

Popup界面 (380-420px宽度)

// 主界面组件结构
interface PopupComponents {
  searchForm: SearchForm;        // 关键词输入和引擎选择
  syntaxOptions: SyntaxOptions;  // 可视化语法选择器
  queryPreview: QueryPreview;    // 查询预览和操作按钮
  historyPanel: HistoryPanel;    // 历史记录管理
}

interface SearchForm {
  keywordInput: HTMLInputElement;
  engineSelector: SelectElement;
  searchButton: ButtonElement;
}

设置页面架构

interface OptionsPage {
  generalSettings: GeneralSettings;
  dataManagement: DataManagement;
  importExport: ImportExportSection;
  aboutSection: AboutSection;
}

2. 业务逻辑层

核心服务设计

class SearchQueryService {
  buildQuery(params: SearchParams): string;
  validateQuery(query: string): ValidationResult;
  suggestCompletions(partial: string): string[];
}

class SyntaxValidator {
  validateSiteSyntax(site: string): boolean;
  validateFileType(type: string): boolean;
  checkConflicts(syntaxes: SyntaxType[]): ConflictResult;
}

class HistoryManager {
  addToHistory(query: SearchQuery): void;
  getHistory(limit: number): SearchQuery[];
  clearHistory(): void;
}

3. 数据存储架构

Chrome Storage配置

interface StorageConfig {
  // 历史记录保存30天
  history: {
    key: 'search_history';
    expiration: 30 * 24 * 60 * 60 * 1000; // 30天
    maxSize: 1000; // 最多保存1000条记录
  };
  
  // 用户设置（永久保存）
  settings: {
    key: 'user_settings';
    persistent: true;
  };
  
  // 缓存数据（24小时）
  cache: {
    key: 'app_cache';
    expiration: 24 * 60 * 60 * 1000;
  };
}

数据模型定义

interface SearchHistory {
  id: string;
  keyword: string;
  engine: SearchEngine;
  syntax: SyntaxOptions;
  timestamp: number;
}

interface UserSettings {
  defaultEngine: 'baidu' | 'google' | 'bing';
  language: 'zh-CN' | 'en-US';
  enableHistory: boolean;
  theme: 'light' | 'dark' | 'auto';
}

interface SyntaxOptions {
  site?: string;
  fileType?: string;
  dateRange?: DateRange;
  exactMatch?: string;
}

4. 搜索引擎适配器

统一接口设计

interface SearchEngineAdapter {
  buildQuery(params: SearchParams): string;
  validateSyntax(syntax: SyntaxType): boolean;
  getSupportedSyntax(): SyntaxType[];
  getBaseUrl(): string;
}

// 百度适配器实现
class BaiduAdapter implements SearchEngineAdapter {
  buildQuery(params: SearchParams): string {
    let query = params.keyword;
    if (params.site) query += ` site:${params.site}`;
    if (params.fileType) query += ` filetype:${params.fileType}`;
    return `https://www.baidu.com/s?wd=${encodeURIComponent(query)}`;
  }
}

5. 数据导入导出

导入导出接口

interface ExportData {
  version: string;
  timestamp: number;
  data: {
    history: SearchHistory[];
    settings: UserSettings;
  };
}

class DataPortability {
  async exportToJSON(): Promise<Blob>;
  async importFromJSON(file: File): Promise<ImportResult>;
  validateImportData(data: any): boolean;
  backupToCloud(): Promise<void>;
  restoreFromCloud(): Promise<void>;
}

6. 国际化支持

多语言配置

interface I18nConfig {
  supported: ['zh-CN', 'en-US'];
  default: 'zh-CN';
  fallback: 'en-US';
  
  messages: {
    'zh-CN': ChineseMessages;
    'en-US': EnglishMessages;
  };
}

class I18nManager {
  private currentLocale: string;
  private messages: ExtensionMessages;
  
  t(key: string, substitutions?: string[]): string;
  detectLocale(): string;
  loadMessages(locale: string): Promise<void>;
}

7. 开发环境配置

Vite配置

// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      input: {
        popup: 'src/popup/index.html',
        options: 'src/options/index.html',
        background: 'src/background/index.ts',
        content: 'src/content/index.ts'
      }
    },
    outDir: 'dist',
    target: 'chrome89' // 支持Chrome和Edge
  },
  
  plugins: [
    chromeExtension(),
    typescript(),
    hmr({ overlay: false })
  ],
  
  define: {
    __IS_DEV__: process.env.NODE_ENV === 'development'
  }
});

8. 浏览器兼容性

目标浏览器支持

const browserSupport = {
  chrome: {
    minVersion: "89",
    status: "primary"
  },
  edge: {
    minVersion: "89", 
    status: "primary"
  },
  firefox: {
    minVersion: "109",
    status: "secondary",
    planned: true
  }
};

9. Chrome Web Store发布准备

Manifest配置

{
  "manifest_version": 3,
  "name": "__MSG_app_name__",
  "version": "1.0.0",
  "description": "__MSG_app_description__",
  "default_locale": "en",
  
  "permissions": [
    "storage",
    "activeTab",
    "scripting"
  ],
  
  "host_permissions": [
    "<all_urls>"
  ],
  
  "background": {
    "service_worker": "background.js"
  },
  
  "action": {
    "default_popup": "popup.html",
    "default_title": "__MSG_app_name__"
  },
  
  "options_page": "options.html"
}

技术决策总结

已确认的技术选型

1. 构建工具: TypeScript + Vite + 热重载
2. UI方案: 轻量级框架 + CSS预处理器 + CSS框架
3. 浏览器支持: Chrome/Edge主要，Firefox后续
4. 数据存储: 本地存储，30天历史，支持导入导出
5. 国际化: 中英文静态支持

性能要求

• 插件启动时间: < 200ms
• 查询生成响应: < 100ms
• 内存占用: < 50MB
• 历史记录: 最多1000条，30天自动清理

安全策略

• 权限最小化原则
• 本地数据存储，不上传用户数据
• 支持一键清除所有数据
• 符合Chrome Web Store安全标准

---

Document Version: 1.0 Date: 2025-11-06 Author: 冷火凉烟 (System Architect) Quality Score: 92/100