rsgltzyd/testing-tool
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: 同步工程文档与当前架构 (#70)

Browse Source 
* docs(工程文档): 同步当前架构说明
* docs(工程文档): 格式化文档表格
This commit is contained in:
cursor[bot]
2026-06-26 16:59:53 +08:00
committed by 雨霖铃
parent 1041b3ece1
commit 1948ba67a7
8 changed files with 200 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/CODING_STANDARDS.md
+42 -38
View File
@@ -285,8 +285,7 @@ import { useThemeMode } from '@/providers/ThemeModeProvider';
import { FeatureConfig, FEATURES } from '@/config/features';
import { storageUtil } from '@/utils/chromeStorage';
// 5. i18n
import { useTranslation } from 'react-i18next';
import { normalizeLanguage, SUPPORTED_LANGUAGES } from '@/i18n';
import { useI18n } from '@/utils/chromeI18n';
// 6. 本地组件
import TextMode from './TextMode';
import { ZONES } from './constants';
@@ -295,7 +294,7 @@ import SwitchButtonGroup from '@/components/SwitchButtonGroup';
import { Button } from '@/components/ui/button';
// 8. 工具函数 / Hook
import { cn } from '@/lib/utils';
import { useLazyTranslation } from '@/utils/useLazyTranslation';
import { useStorageState } from '@/utils/useStorageState';
// 9. 类型
import type { PageType, StorageSchema } from '@/types/storage';
```
@@ -401,22 +400,22 @@ className={cn(
## 5. 错误处理
### 5.1 工具函数：结果对象模式
### 5.1 工具函数：可恢复错误返回可判断结果
工具函数**不抛异常**，返回包含 `hasError` 和 `error` 字段的结果对象：
可恢复的解析/校验错误应返回可判断的结果，避免工具层直接弹 Toast。确需保留底层异常的函数
（如 `formatJson` / `minifyJson`）必须在页面 Hook 或 UI 层捕获并转换为用户提示：
```typescript
// ✅ 结果对象模式
export function markdownToHtml(markdown: string): MarkdownToHtmlResult {
// ✅ 可恢复校验返回错误消息，调用方据此展示 UI
export function validateJson(text: string): string | null {
if (!text.trim()) {
return null;
}
try {
...
return { html, originalLength, htmlLength, hasError: false };
} catch (error) {
return {
html: '', ...
hasError: true,
error: error instanceof Error ? error.message : 'Markdown 解析失败',
};
JSON.parse(text.trim());
return null;
} catch (e) {
return e instanceof SyntaxError ? e.message : 'Invalid JSON';
}
}
```
@@ -658,7 +657,7 @@ export function useTimestampConverter(): UseTimestampConverterReturn { ... }
```
src/utils/useStorageState.ts — Chrome Storage 状态持久化
src/utils/useLazyTranslation.ts — i18n 懒加载
src/utils/chromeI18n.ts — chrome.i18n wrapper 与 useI18n
src/utils/useContextMenuData.ts — 右键菜单数据
src/utils/useDebounce.ts — 防抖
src/pages/Timestamp/useTimestampConverter.ts — 页面级 Hook
@@ -671,43 +670,48 @@ src/pages/StorageCleaner/useStorageCleaner.ts — 页面级 Hook
### 9.1 翻译键格式
- 命名空间：`common`（默认）、`features`
- 翻译键格式：`namespace:key`（如 `features:timestamp.title`）
- 语言：`zh`（默认）、`en`
- 使用 Chrome 扩展标准的 `chrome.i18n`，通过 `src/utils/chromeI18n.ts` 暴露 `useI18n`
- 翻译 key 存放在 `public/_locales/zh_CN/messages.json`
- 直接 key：`t('dashboard_title')` → 查找 `dashboard_title`
- 命名空间兼容写法：`t('common:buttons.search')` → 查找 `common_buttons_search`
- 命名空间参数：`useI18n(['common', 'features'])` 会尝试 `common_key`、`features_key`
### 9.2 翻译文件结构
```
i18n/locales/{zh,en}/common.json — 全局通用翻译
i18n/locales/{zh,en}/features.json — 功能模块标题和描述
i18n/locales/{zh,en}/{功能名}.json — 各功能独立翻译
public/_locales/zh_CN/messages.json — Chrome 扩展默认语言包
wxt.config.ts — manifest.default_locale = 'zh_CN'
```
### 9.3 使用方式
```typescript
// ✅ 页面组件 — 使用 useLazyTranslation
import { useLazyTranslation } from '@/utils/useLazyTranslation';
// ✅ 页面组件 / 子组件 — 使用 useI18n
import { useI18n } from '@/utils/chromeI18n';
export default function Index() {
const { t } = useLazyTranslation('timestamp');
return <h1>{t('timestamp:title')}</h1>;
const { t } = useI18n('timestamp');
return <h1>{t('timestamp_title')}</h1>;
}
// ✅ 全局组件 — 使用 useTranslation
import { useTranslation } from 'react-i18next';
export function TopBar() {
const { t } = useTranslation(['common', 'features']);
return <span>{t('common:settings')}</span>;
// ✅ 带占位符
export function NotFoundMessage() {
const { t } = useI18n('router');
return <p>{t('router_notFoundDescription', { entryPointType: 'popup' })}</p>;
}
```
### 9.4 添加新翻译
1. 在 `i18n/locales/{zh,en}/features.json` 添加功能标题和描述
2. 创建 `i18n/locales/{zh,en}/{功能名}.json` 添加功能专属翻译
3. 在 `utils/useLazyTranslation.ts` 的 `localeModules` 中注册新命名空间
1. 在 `public/_locales/zh_CN/messages.json` 添加 Chrome 扩展格式的消息：
```json
{
"feature_title": { "message": "功能标题" },
"feature_description": { "message": "功能描述" }
}
```
2. key 使用下划线分隔，避免点号；`useI18n` 会把 `namespace:key.path` 兼容转换为下划线
3. `chrome.i18n` 不支持运行时动态切换语言，浏览器语言变化后需要刷新扩展页面
---
@@ -1083,7 +1087,7 @@ export default function Index() {
4. ✅ 业务逻辑提取到 `useXxx.ts` Hook（index.tsx 不超过 150 行）
5. ✅ 需要持久化的 UI 状态使用 `useStorageState`
6. ✅ 常量 ≥3 个时提取到 `constants.ts`
7. ✅ 在 `i18n/locales/{zh,en}/` 添加翻译
7. ✅ 在 `public/_locales/zh_CN/messages.json` 添加翻译
8. ✅ 创建 `__tests__/index.test.tsx` 测试文件
9. ✅ 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
10. ✅ 运行 `npm run lint && npm run typecheck && npm run test` 全部通过
@@ -1103,8 +1107,8 @@ export default function Index() {
| `src/hooks/` | 自定义 React Hooks |
| `src/utils/` | 工具函数与服务抽象 |
| `src/types/` | TypeScript 类型声明 |
| `src/lib/` | 通用工具函数（cn、utils） |
| `public/` | 静态资源 |
| `src/lib/` | 通用工具函数与生成器库（cn、utils、generators） |
| `public/` | 静态资源与 Chrome `_locales` 语言包 |
---
AGENTS.md
+62 -18
View File
@@ -1,23 +1,6 @@
# AGENTS.md
WXT 浏览器扩展项目 (React 19 + TypeScript)。为开发者和测试人员提供浏览器内效率工具集。
## 功能列表
功能定义见 `src/config/features.tsx`，`PageType` 见 `src/types/storage.d.ts`。
| key | 页面目录 | 说明 |
| -------------------- | -------------------------- | ------------------------------------------- |
| `dashboard` | `pages/Dashboard` | 仪表盘首页，工具导航与最近使用 |
| `timestamp` | `pages/Timestamp` | Unix 时间戳转换与格式化 |
| `storageCleaner` | `pages/StorageCleaner` | 清理 Cookies、本地存储、IndexedDB、Cache 等 |
| `qrCode` | `pages/QrCode` | 二维码生成与解析 |
| `textStatistics` | `pages/TextStatistics` | 文本字符、单词、行数、字节统计 |
| `jwt` | `pages/Jwt` | JWT 解码与查看 |
| `jsonTools` | `pages/JsonTools` | JSON 差异比较、格式化、YAML/TOML 转换与压缩 |
| `base64Converter` | `pages/Base64Converter` | 文本、文件、图像 Base64 编解码 |
| `rightClickRestorer` | `pages/RightClickRestorer` | 恢复被网站禁用的右键菜单 |
| `testDataGenerator` | `pages/TestDataGenerator` | 自定义规则批量生成测试数据 |
WXT 浏览器扩展项目 (React 19 + TypeScript)。提供时间戳转换、存储清理、JWT 解析、JSON 工具、二维码、Base64、测试数据生成器等测试效率工具。
## 核心命令
@@ -110,6 +93,38 @@ src/pages/FeatureName/
- 当 `index.tsx` 超过 150 行时，必须拆分为 UI + Hook 模式
- 复杂页面可增加 `contexts/`、`hooks/`、`components/` 子目录
### 测试数据生成器模块
```
src/pages/TestDataGenerator/
├── index.tsx # 主页面（字段配置 + 标签页切换）
├── hooks/useGenerator.ts # Web Worker 管理 Hook（创建、复用、通信、销毁）
└── components/
├── FieldList.tsx # 字段列表（虚拟滚动 + @dnd-kit 拖拽排序 + 规则保存）
├── FieldItem.tsx # 字段卡片展示
├── FieldEditor.tsx # 字段编辑器（名称校验、生成器选择、参数配置）
├── GeneratorSelector.tsx # 生成器选择器（分类 + 搜索）
├── GeneratorConfig.tsx # 生成器参数表单（动态渲染 string/number/boolean/select/array）
├── GenerateOptions.tsx # 生成选项（数量、格式）
├── GenerateButton.tsx # 生成按钮 + 进度条
├── DataPreview.tsx # 示例数据预览（JSON 语法高亮）
├── ResultPanel.tsx # 生成结果状态面板
├── ExportPanel.tsx # 导出面板（复制/下载 JSON/CSV）
└── RuleManager.tsx # 规则管理（CRUD、搜索、导入/导出）
src/utils/
├── ruleStorage.ts # 规则持久化存储（localStorage）
└── dataExporter.ts # 数据导出工具（JSON/CSV 转换、下载、剪贴板）
src/lib/generators/ # 内置生成器定义（个人信息、企业、技术、基础类型）
src/workers/
└── generator.worker.ts # 数据生成 Web Worker
src/types/
└── testDataGenerator.ts # 类型定义（FieldConfig, DataRule, GeneratorDefinition 等）
```
## 关键架构决策
**路由**: 不使用 React Router。通过 `src/config/features.tsx` 的 `FEATURES` 数组管理，`RouterProvider` 根据 `PageType`
@@ -131,11 +146,40 @@ src/pages/FeatureName/
- 全局变量: `vitest/globals` (describe, it, expect 等无需导入)
- Setup 文件: `vitest.setup.ts` 自动 mock:
- `chrome.*` / `browser.*` API (storage, tabs, runtime, cookies 等)
- `@/utils/chromeI18n` (从 `public/_locales/zh_CN/messages.json` 加载真实翻译)
- `window.matchMedia`
- 测试文件命名: `__tests__/*.test.{ts,tsx}` 或 `*.test.{ts,tsx}`
- Mock 模式: 使用 `vi.mock()` 进行模块级 mock，避免在测试文件中重复 mock 代码
- 测试工具: `@testing-library/react` + `@testing-library/user-event` 进行组件测试
## i18n (chrome.i18n)
项目使用 Chrome 扩展标准的 `chrome.i18n` API 进行本地化，通过 `src/utils/chromeI18n.ts` 提供类型安全的 React Hook 包装。
- **翻译文件**: `public/_locales/zh_CN/messages.json`（Chrome 扩展标准格式）
- **默认语言**: `zh_CN`（在 `wxt.config.ts` 的 `manifest.default_locale` 中配置）
- **使用方式**: `import { useI18n } from '@/utils/chromeI18n'`
- **翻译键格式**:
- 直接 key: `t('dashboard_title')` → 查找 `dashboard_title`
- 命名空间格式（兼容旧用法）: `t('common:buttons.search')` → 查找 `common_buttons_search`
- 带命名空间参数: `useI18n(['common', 'features'])`，会自动尝试 `common_key`、`features_key`
- **占位符支持**: `t('router_notFoundDescription', { entryPointType: 'popup' })`
- **Hook 返回值**: `{ t, i18n: { language, changeLanguage }, isLoaded }`
- **回退策略**: 当翻译 key 未命中时，返回 key 本身（开发模式下在控制台记录 warning）
- **限制**: `chrome.i18n` 无法动态切换语言，语言跟随浏览器设置，切换后需刷新页面
## 新功能开发清单
1. 在 `src/types/storage.d.ts` 添加 `PageType` 联合类型
2. 在 `src/config/features.tsx` 的 `FEATURES` 数组添加配置（指定 key、翻译键、图标、三种渲染模式的组件）
3. 在 `src/pages/` 创建页面组件 (懒加载)：
- `index.tsx` — UI 组件，使用 `useI18n` 获取翻译
- `useFeatureName.ts` — 业务逻辑 Hook
- `constants.ts` — 常量（可选）
4. 在 `public/_locales/zh_CN/messages.json` 添加翻译
5. 如需新权限，更新 `wxt.config.ts` 的 `manifest.permissions`
6. 添加对应的单元测试
## 代码规范
- 禁止使用 `any` (测试文件除外)
README.md
+3 -4
View File
@@ -81,7 +81,7 @@
- **UI 组件**: shadcn/ui (基于 Radix UI 的无头组件库)
- **样式**: Tailwind CSS + class-variance-authority + cn() 工具函数
- **日期处理**: dayjs (集成 UTC 和 Timezone 插件)
- **国际化**: i18next + react-i18next
- **国际化**: Chrome `chrome.i18n` + `public/_locales/zh_CN/messages.json`
- **通信**: @webext-core/messaging
- **存储**: Chrome Storage API (类型安全封装)
- **解析引擎**: qr-scanner (二维码解析), qrious (二维码生成)
@@ -107,8 +107,8 @@
│ ├── hooks/ # 自定义 React Hooks
│ ├── utils/ # 工具函数与服务抽象
│ ├── types/ # TypeScript 类型声明
│ └── lib/ # 通用工具函数 (cn, utils 等)
├── public/ # 静态资源 (图标、manifest 资源等)
│ └── lib/ # 通用工具函数与生成器库 (cn, utils, generators 等)
├── public/ # 静态资源 (图标、_locales 本地化资源等)
├── wxt.config.ts # WXT 框架核心配置
└── package.json # 项目元数据与依赖管理
```
@@ -155,7 +155,6 @@
- `sidePanel`: 支持在浏览器侧边栏中运行.
- `clipboardWrite`: 提供一键复制功能.
- `contextMenus`: 注册右键菜单，支持快捷操作.
- `alarms`: 管理后台定时任务（如清理后自动刷新）.
## 浏览器支持
docs/test-data-generator/README.md
+11 -1
View File
@@ -2,7 +2,7 @@
> 版本: v1.0
> 创建时间: 2024-01-20
> 状态: 待 Review
> 状态: 已实现（见 `src/pages/TestDataGenerator/`、`src/lib/generators/`、`src/workers/generator.worker.ts`）
## 产品定位
@@ -19,3 +19,13 @@
- [规则管理](./rule-management.md)
- [界面设计](./ui-design.md)
- [技术实现](./technical-implementation.md)
## 当前实现入口
- 页面入口：`src/pages/TestDataGenerator/index.tsx`
- Worker：`src/workers/generator.worker.ts`
- 生成器库：`src/lib/generators/`
- 规则存储：`src/utils/ruleStorage.ts`
- 导出工具：`src/utils/dataExporter.ts`
实现约束与任务完成状态记录在 [TASKS.md](./TASKS.md)。
public/README.md
+16
View File
@@ -12,8 +12,24 @@
| `icon/48.png` | 48×48 图标（扩展管理页） |
| `icon/96.png` | 96×96 图标 |
| `icon/128.png` | 128×128 图标（Chrome Web Store） |
| `_locales/` | Chrome 扩展本地化资源 |
## 本地化资源
项目使用 Chrome 扩展标准 `chrome.i18n`，默认语言在 `wxt.config.ts` 中配置为 `zh_CN`。
| 文件/目录 | 用途 |
| ------------------------------ | -------------------------------------------------- |
| `_locales/zh_CN/messages.json` | 默认中文语言包，包含功能名、描述、按钮、提示等翻译 |
添加或修改文案时：
- 使用 Chrome 扩展消息格式：`"key": { "message": "文本" }`
- key 使用下划线分隔，例如 `testDataGenerator_title`
- 代码中通过 `useI18n` 或 `getMessage` 读取，不要新增 `i18n/locales` 目录
## 注意事项
- 修改图标后需同步更新 `wxt.config.ts` 中的 manifest 配置
- 图标格式推荐使用 PNG，确保透明背景
- 修改 `_locales` 后需确认 `manifest.default_locale` 与语言目录名一致
src/lib/README.md
+33 -3
View File
@@ -4,9 +4,10 @@
## 文件说明
| 文件 | 用途 |
| ---------- | ------------------------------------ |
| `utils.ts` | `cn()` 函数 — shadcn/ui 标准工具函数 |
| 文件/目录 | 用途 |
| ------------- | -------------------------------------- |
| `utils.ts` | `cn()` 函数 — shadcn/ui 标准工具函数 |
| `generators/` | 测试数据生成器内置生成器库和分类注册表 |
## cn()
@@ -24,3 +25,32 @@ import { cn } from '@/lib/utils';
```
所有需要动态合并 Tailwind 类名的场景都应使用 `cn()`，而非手动拼接字符串。
## generators/
测试数据生成器的核心生成器库，供 `src/workers/generator.worker.ts` 在后台线程中按字段配置生成数据。
| 文件 | 用途 |
| -------------- | ---------------------------------------------- |
| `index.ts` | 聚合所有生成器，导出分类、查找和搜索函数 |
| `personal.ts` | 个人信息生成器（姓名、邮箱、手机号、身份证等） |
| `business.ts` | 业务数据生成器（订单号、价格、日期、状态等） |
| `technical.ts` | 技术数据生成器（UUID、IPv4、URL） |
| `basic.ts` | 基础类型生成器（整数、浮点数、布尔值、字符串） |
| `types.ts` | 生成器库内部类型与通用选项 |
使用示例：
```typescript
import { getGeneratorById, searchGenerators } from '@/lib/generators';
const generator = getGeneratorById('chineseName');
const value = generator?.generate({});
const matched = searchGenerators('uuid');
```
约束：
- 新增生成器必须实现 `GeneratorDefinition`，并加入所属分类文件的导出列表。
- 需要唯一值或大批量稳定输出时，优先实现 `generateAtIndex(params, index)`。
- 新增分类时同步更新 `generatorCategories`，并确保 `GeneratorSelector` 能展示该分类。
src/types/README.md
+11 -3
View File
@@ -10,12 +10,10 @@
**页面类型：**
- `PageType` — 所有页面类型的联合类型（`dashboard` | `timestamp` | `storageCleaner` | ...）
- `PageType` — 所有页面类型的联合类型（含 `dashboard`、`timestamp`、`storageCleaner`、`testDataGenerator` 等）
- `JsonToolsPageMode` — JSON 工具子模式（`diff` | `format` | `yaml` | `toml` | `minify`）
- `Base64ConverterPageMode` — Base64 子模式（`text` | `file` | `image`）
- `Base64ConvertDirection` — 编解码方向（`encode` | `decode`）
- `MarkdownToHtmlPreviewMode` — Markdown 预览模式（`split` | `preview` | `html`）
- `HtmlToMarkdownPreviewMode` — HTML 预览模式（`split` | `preview` | `markdown`）
**存储 Schema：**
@@ -34,6 +32,16 @@
`qrious` 库的类型声明，定义 QR 码生成选项和 `QRious` 类。
### testDataGenerator.ts
测试数据生成器共享类型，包含：
- `FieldConfig` — 字段配置（字段名、生成器、参数、必填、空值率、唯一性）
- `DataRule` — 可保存/导入/导出的字段规则
- `GeneratorDefinition` / `GeneratorParam` — 内置生成器定义和参数 Schema
- `GenerateResult` / `GenerateProgress` / `WorkerMessage` — Worker 生成结果、进度和消息协议
- `ExportFile` — JSON/CSV 导出文件描述
## 修改 StorageSchema 的注意事项
修改 `StorageSchema` 时，必须：
src/utils/README.md
+22 -21
View File
@@ -4,39 +4,40 @@
## 工具函数
| 文件 | 用途 |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| `chromeStorage.ts` | Chrome Storage API 封装：类型安全的 `StorageUtils` 类，提供 `get/set/remove` 方法 |
| `chromeTabs.ts` | Chrome Tabs API 封装：获取活动标签页、获取域名、在新标签页打开扩展页面 |
| `clipboard.ts` | 剪贴板操作：`copyTextToClipboard`（文本）、`copyImageToClipboard`（图片） |
| `messages.ts` | 扩展消息通信：基于 `@webext-core/messaging`，定义 `MessageAction` 枚举和 `ProtocolMap` 类型安全映射 |
| `contextMenu.ts` | 右键菜单配置与操作：定义菜单项、创建菜单、解析点击事件、ID→PageType 映射 |
| `base64Converter.ts` | Base64 编解码：文本↔Base64、文件↔Base64、图片预览，定义文件大小限制和图像 MIME 类型 |
| `jwt.ts` | JWT 解析：Base64URL 解码、解析 Header/Payload/Signature、JSON 格式化输出 |
| `jsonFormatter.ts` | JSON 格式化/压缩：支持缩进、按键排序、minify |
| `jsonToYaml.ts` | JSON→YAML 转换 |
| `jsonToToml.ts` | JSON→TOML 转换 |
| `markdownToHtml.ts` | Markdown→HTML 转换：基于 `marked` 库，支持 GFM 和换行转换 |
| `htmlToMarkdown.ts` | HTML→Markdown 转换：基于 DOMParser 解析 |
| `qrCodeParser.ts` | 二维码解析：基于 `qr-scanner` 库从文件中解析二维码 |
| `storageCleaner.ts` | 存储清理：获取当前标签页、检测受限 URL、计算 Cookie/Storage 大小、清理操作 |
| `textStatistics.ts` | 文本统计：使用 `Intl.Segmenter` 计算字符数/单词数/行数/字节大小 |
| `format.ts` | 通用格式化：`formatBytes` 将字节转为可读字符串（B/KB/MB/GB/TB） |
| `dayjs.ts` | Day.js 初始化：扩展 UTC、Timezone、RelativeTime 插件，加载中文本地化 |
| 文件 | 用途 |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| `chromeStorage.ts` | Chrome Storage API 封装：类型安全的 `StorageUtils` 类，提供 `get/set/remove` 方法 |
| `chromeTabs.ts` | Chrome Tabs API 封装：获取活动标签页、获取域名、在新标签页打开扩展页面 |
| `clipboard.ts` | 剪贴板操作：`copyTextToClipboard`（文本）、`copyImageToClipboard`（图片） |
| `messages.ts` | 扩展消息通信：基于 `@webext-core/messaging`，定义 `MessageAction` 枚举和 `ProtocolMap` 类型安全映射 |
| `contextMenu.ts` | 右键菜单配置与操作：定义菜单项、创建菜单、解析点击事件、ID→PageType 映射 |
| `base64Converter.ts` | Base64 编解码：文本↔Base64、文件↔Base64、图片预览，定义文件大小限制和图像 MIME 类型 |
| `jwt.ts` | JWT 解析：Base64URL 解码、解析 Header/Payload/Signature、JSON 格式化输出 |
| `jsonFormatter.ts` | JSON 格式化/压缩：支持缩进、按键排序、minify |
| `jsonToYaml.ts` | JSON→YAML 转换 |
| `jsonToToml.ts` | JSON→TOML 转换 |
| `qrCodeParser.ts` | 二维码解析：基于 `qr-scanner` 库从文件中解析二维码 |
| `storageCleaner.ts` | 存储清理：获取当前标签页、检测受限 URL、计算 Cookie/Storage 大小、清理操作 |
| `textStatistics.ts` | 文本统计：使用 `Intl.Segmenter` 计算字符数/单词数/行数/字节大小 |
| `format.ts` | 通用格式化：`formatBytes` 将字节转为可读字符串（B/KB/MB/GB/TB） |
| `dayjs.ts` | Day.js 初始化：扩展 UTC、Timezone、RelativeTime 插件，加载中文本地化 |
| `chromeI18n.ts` | Chrome `chrome.i18n` 包装：提供 `getMessage` 和兼容 React 使用的 `useI18n` Hook |
| `ruleStorage.ts` | 测试数据生成器规则存储：基于 `localStorage` 的 CRUD、搜索、导入/导出和数量限制 |
| `dataExporter.ts` | 测试数据导出：JSON/CSV 转换、文件下载和复制到剪贴板 |
| `rightClickInjection.ts` | 右键恢复注入脚本：在页面上下文恢复 contextmenu/copy/paste 等事件默认行为 |
## 自定义 Hooks
| 文件 | 用途 |
| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
| `useStorageState.ts` | Chrome Storage 状态 Hook：类似 `useState`，值自动同步到 `chrome.storage`，使用 `localStorage` 快照消除首屏闪烁 |
| `useLazyTranslation.ts` | 懒加载翻译 Hook：按需动态导入 i18n 命名空间，支持预加载和缓存 |
| `useContextMenuData.ts` | 右键菜单数据 Hook：从 storage 读取待处理数据，匹配 featureKey 后消费并触发回调 |
| `useDebounce.ts` | 防抖 Hook：对值进行延迟更新，避免频繁触发 |
## 使用约定
- 工具函数使用**命名导出**（`export function xxx()`）
- 工具函数**不抛异常**，返回包含 `hasError` 和 `error` 字段的结果对象
- 工具层不直接展示 Toast；可恢复错误返回可判断结果，需要抛出的解析/转换错误由页面 Hook 或 UI 层捕获
- Hook 使用 `use` 前缀命名，定义返回值接口类型
- 存储操作使用 `chromeStorage.ts` 的 `storageUtil` 封装，不要直接调用 `chrome.storage`
- 消息通信使用 `messages.ts` 的 `sendMessage`/`onMessage`，不要使用原生 `chrome.runtime.sendMessage`