feat(M3.1): 词典接口基类设计 (v0.2.1)

docs/QUICK_REF.md

@@ -7,7 +7,7 @@
 ## 版本速查
 
 ### 当前版本
-`0.1.9` → 下一目标 `0.2.1` ([M3.1](./M3.md))
+`0.2.1` → 下一目标 `0.2.2` ([M3.2](./M3.md))
 
 ### 模块版本范围
 

docs/README.md

@@ -65,9 +65,9 @@ M11.10完成 → 1.0.0 (正式发布)
 
 ## 当前状态
 
-**当前版本**: `0.1.9`  
-**当前进度**: 14/97 (14%)  
-**下一任务**: [M3.1 词典接口基类设计](./M3.md#m31-词典接口基类设计--目标版本-021)
+**当前版本**: `0.2.1`  
+**当前进度**: 15/97 (15%)  
+**下一任务**: [M3.2 词典管理器](./M3.md#m32-词典管理器--目标版本-022)
 
 ---
 

docs/VERSION.md

@@ -26,9 +26,9 @@
 | M2.4 | 0.1.4 | 图标定位显示 | ✅ | 2026-02-10 |
 | M2.5 | 0.1.5 | 图标点击事件 | ✅ | 2026-02-10 |
 | M2.6 | 0.1.6 | 基础面板组件 | ✅ | 2026-02-11 |
-| M2.7 | 0.1.7 | 面板位置计算 | ✅ | 2026-02-09 |
-| M2.8 | 0.1.8 | 图标-面板联动 | ✅ | 2026-02-09 |
-| M2.9 | 0.1.9 | 图标显示开关 | ✅ | 2026-02-09 |
+| M2.7 | 0.1.7 | 面板位置计算 | ✅ | 2026-02-11 |
+| M2.8 | 0.1.8 | 图标-面板联动 | ✅ | 2026-02-11 |
+| M2.9 | 0.1.9 | 图标显示开关 | ✅ | 2026-02-11 |
 
 ---
 
@@ -36,7 +36,7 @@
 
 | 任务 | 版本 | 描述 | 状态 | 日期 |
 |------|------|------|------|------|
-| M3.1 | 0.2.1 | 词典接口基类 | ⬜ | - |
+| M3.1 | 0.2.1 | 词典接口基类 | ✅ | 2026-02-11 |
 | M3.2 | 0.2.2 | 词典管理器 | ⬜ | - |
 | M3.3 | 0.2.3 | 必应词典(Mock) | ⬜ | - |
 | M3.4 | 0.2.4 | 后台查询接口 | ⬜ | - |

manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "沙拉查词",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "description": "聚合词典划词翻译",
   "permissions": [
     "storage",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "salad-dict",
-  "version": "0.1.9",
+  "version": "0.2.1",
   "description": "聚合词典划词翻译",
   "private": true,
   "type": "module",

src/shared/dictionary/base.js

@@ -0,0 +1,125 @@
+/**
+ * @file 词典接口基类
+ * @description 定义词典抽象接口，所有词典实现需继承此类
+ */
+
+/**
+ * 词典查询结果结构
+ * @typedef {Object} DictionaryResult
+ * @property {string} word - 查询的单词
+ * @property {string} [phonetic] - 音标
+ * @property {Array<Meaning>} meanings - 释义列表
+ * @property {Array<Example>} [examples] - 例句列表
+ * @property {string} [url] - 词典页面链接
+ */
+
+/**
+ * 释义项结构
+ * @typedef {Object} Meaning
+ * @property {string} partOfSpeech - 词性（如 n., v., adj.）
+ * @property {Array<string>} definitions - 中文释义列表
+ */
+
+/**
+ * 例句结构
+ * @typedef {Object} Example
+ * @property {string} sentence - 英文例句
+ * @property {string} [translation] - 中文翻译
+ */
+
+/**
+ * 词典基类
+ * 所有词典实现必须继承此类并实现 search 方法
+ */
+export class DictionaryBase {
+  /**
+   * @param {Object} config - 词典配置
+   * @param {string} config.name - 词典名称
+   * @param {string} [config.icon] - 词典图标路径
+   * @param {Array<string>} [config.languages] - 支持的语言代码列表
+   * @param {Object} [config.options] - 其他配置选项
+   */
+  constructor(config = {}) {
+    this.name = config.name || 'Unknown';
+    this.icon = config.icon || '';
+    this.languages = config.languages || ['en', 'zh'];
+    this.options = config.options || {};
+  }
+
+  /**
+   * 查询单词
+   * @param {string} word - 要查询的单词
+   * @returns {Promise<DictionaryResult>} 查询结果
+   * @throws {Error} 子类必须实现此方法
+   */
+  async search(word) {
+    throw new Error('search() method must be implemented by subclass');
+  }
+
+  /**
+   * 检查是否支持指定语言
+   * @param {string} lang - 语言代码（如 'en', 'zh'）
+   * @returns {boolean} 是否支持
+   */
+  supports(lang) {
+    return this.languages.includes(lang);
+  }
+
+  /**
+   * 获取词典信息
+   * @returns {Object} 词典信息
+   */
+  getInfo() {
+    return {
+      name: this.name,
+      icon: this.icon,
+      languages: this.languages
+    };
+  }
+}
+
+/**
+ * 创建标准查询结果对象
+ * @param {Object} data - 结果数据
+ * @param {string} data.word - 单词
+ * @param {string} [data.phonetic] - 音标
+ * @param {Array<Meaning>} [data.meanings] - 释义列表
+ * @param {Array<Example>} [data.examples] - 例句列表
+ * @param {string} [data.url] - 词典页面链接
+ * @returns {DictionaryResult} 标准化的查询结果
+ */
+export function createResult(data) {
+  return {
+    word: data.word || '',
+    phonetic: data.phonetic || '',
+    meanings: data.meanings || [],
+    examples: data.examples || [],
+    url: data.url || ''
+  };
+}
+
+/**
+ * 创建释义项
+ * @param {string} partOfSpeech - 词性
+ * @param {Array<string>} definitions - 释义列表
+ * @returns {Meaning} 释义对象
+ */
+export function createMeaning(partOfSpeech, definitions) {
+  return {
+    partOfSpeech: partOfSpeech || '',
+    definitions: Array.isArray(definitions) ? definitions : [definitions]
+  };
+}
+
+/**
+ * 创建例句
+ * @param {string} sentence - 英文例句
+ * @param {string} [translation] - 中文翻译
+ * @returns {Example} 例句对象
+ */
+export function createExample(sentence, translation = '') {
+  return {
+    sentence: sentence || '',
+    translation: translation || ''
+  };
+}