# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

这是一个基于 WXT 框架的浏览器扩展项目，提供测试工具功能，包括时间戳转换、用户操作录制与回放等。

## 核心命令

### 开发相关

- `npm run dev` - 启动 Chrome 浏览器的开发模式
- `npm run dev:firefox` - 启动 Firefox 浏览器的开发模式
- `npm run build` - 构建 Chrome 浏览器的生产版本
- `npm run build:firefox` - 构建 Firefox 浏览器的生产版本
- `npm run zip` - 打包 Chrome 扩展
- `npm run zip:firefox` - 打包 Firefox 扩展
- `npm run compile` - TypeScript 类型检查（不生成文件）
- `npm run lint` - 运行 ESLint 检查

### 测试相关

- `npm run test` - 运行所有测试（单次执行）
- `npm run test:watch` - 运行测试并监听文件变化
- `npm run test:coverage` - 运行测试并生成覆盖率报告

**运行单个测试文件：**

```bash
npx vitest run components/__tests__/CopyButton.test.tsx
```

**测试技术栈：**

- Vitest - 测试框架
- @testing-library/react - React 组件测试
- @testing-library/user-event v13 - 用户交互模拟（注意：v13 不支持 setup()，使用 fireEvent）
- jsdom - 浏览器环境模拟

### 依赖与准备

- `npm install` - 安装依赖
- `postinstall` 会自动运行 `wxt prepare` 准备开发环境
- `prepare` 钩子会初始化 Husky Git 钩子

## 项目架构

### 技术栈

- **框架**: WXT (Web Extension Toolkit) - 浏览器扩展开发框架
- **前端**: React 19 + TypeScript
- **UI 库**: Material UI (MUI)
- **状态管理**: React Hooks
- **数据库**: Dexie.js (IndexedDB)
- **录制回放**: rrweb
- **路由**: React Router DOM

### 目录结构

```

├── components/ # 可复用 UI 组件
│ ├── CopyButton.tsx # 复制按钮组件
│ ├── DatetimeToTimestamp.tsx # 日期转时间戳组件
│ ├── Navbar.tsx # 导航栏组件
│ ├── RoutePersistence.tsx # 路由持久化组件
│ ├── TimestampExecution.tsx # 时间戳执行组件
│ └── TimestampToDatetime.tsx # 时间戳转日期组件
├── entrypoints/ # 浏览器扩展入口点
│ ├── background.ts # 后台脚本（主进程）
│ ├── content.ts # 内容脚本（注入到页面）
│ ├── offscreen/ # 离屏文档（用于长时间运行任务）
│ ├── popup/ # 扩展弹窗界面
│ │ ├── App.tsx # 弹窗主应用
│ │ ├── main.tsx # 弹窗入口
│ │ └── pages/ # 弹窗页面
│ │ ├── RecordeReplayPage.tsx # 录制回放页面
│ │ ├── TestPage.tsx # 测试页面
│ │ └── TimestampPage.tsx # 时间戳工具页面
│ └── options/ # 选项页面（未列出）
├── assets/ # 静态资源
├── utils/ # 工具函数
│ ├── chromeStorage.ts # Chrome 存储工具
│ ├── dayjs.ts # 日期处理工具
│ ├── messages.tsx # 消息通信工具
│ ├── recordEventsDb.ts # IndexedDB 数据库工具（录制事件存储）
│ ├── recordUtils.tsx # 录制工具函数
│ ├── tabUtils.ts # 标签页工具
│ └── useRecorder.tsx # 录制器 Hook
├── types/ # 类型定义
│ └── storage.d.ts # 存储相关类型
├── public/ # 公共资源
├── package.json # 项目依赖和脚本
├── tsconfig.json # TypeScript 配置
├── wxt.config.ts # WXT 配置
└── web-ext.config.ts # WebExtensions 配置

```

### 核心功能实现

#### 1. 时间戳转换工具

- 位置: `components/` 目录下的时间戳相关组件
- 依赖: dayjs 库进行日期处理
- 功能: 支持日期与时间戳的双向转换，支持多种格式

#### 2. 录制与回放功能

- 位置: `utils/useRecorder.tsx` (核心录制逻辑)、`utils/recordUtils.tsx` (工具函数)
- 依赖: rrweb 库
- 存储: IndexedDB (Dexie.js) - `utils/recordEventsDb.ts`
- 特点: 支持分块存储录制事件，优化性能

**录制架构流程：**

1. **开始录制** (`popup:start` → `background.ts` → `content.ts`)
   - Popup 发送开始录制消息
   - Background 生成 sessionId，初始化 IndexedDB 会话
   - Content Script 启动 rrweb 录制器

2. **事件存储** (`content:save-track-events`)
   - rrweb 捕获事件后通过消息发送给 Background
   - Background 使用 IndexedDB 分块存储（每块 100 个事件）

3. **停止录制** (`popup:stop`)
   - Background 从 IndexedDB 流式读取所有事件
   - 生成回放 HTML 文件并下载
   - 保留录制历史（不删除 IndexedDB 数据）

4. **状态管理**
   - 录制状态存储在 `chrome.storage.local` (recorder_state)
   - 支持 Tab 切换检测和 Tab 关闭自动停止

#### 3. 通信系统

- 位置: `utils/messages.tsx`
- 机制: 使用 `@webext-core/messaging` 库实现
- 通信通道: 后台脚本 ↔ 内容脚本 ↔ 弹窗 ↔ 离屏文档

**核心消息类型：**

- `popup:start` / `popup:stop` - Popup 控制录制
- `popup:started` / `popup:stopped` - 状态变化通知
- `popup:check-status` - 查询录制状态
- `content:start-recording` / `content:stop-recording` - 控制 Content Script
- `content:save-track-events` - 保存录制事件
- `popup:get-sessions` / `popup:delete-session` - 录制会话管理

#### 4. 数据存储

- Chrome Storage API: `utils/chromeStorage.ts` (用于配置等小数据)
- IndexedDB: `utils/recordEventsDb.ts` (用于存储大量录制事件)

**IndexedDB 数据结构：**

- **sessions** 表: 录制会话元数据
  - `id`: sessionId (string)
  - `startTime`: 录制开始时间 (number)
  - `tabId`: 录制的标签页 ID (number)
  - `chunkCount`: 数据块数量 (number)
  - `totalEvents`: 总事件数 (number)

- **events** 表: 事件数据块
  - `id`: 自增 ID (number)
  - `sessionId`: 关联的会话 ID
  - `chunkIndex`: 块索引 (number)
  - `events`: rrweb 事件数组 (unknown[])
  - `timestamp`: 时间戳 (number)
  - CHUNK_SIZE: 100 个事件/块

### 关键配置文件

#### wxt.config.ts

- 配置 WXT 框架参数
- 启用 React 模块
- 配置浏览器扩展权限
- Vite 构建配置（使用 Terser 压缩，强制 ASCII 编码）

#### manifest 权限

```typescript
permissions: [
  'storage',           // 存储权限
  'unlimitedStorage',  // 无限制存储
  'clipboardWrite',    // 剪贴板写入
  'activeTab',         // 当前标签页
  'scripting',         // 脚本注入
  'tabs',              // 标签页管理
  'offscreen',         // 离屏文档
  'downloads',         // 下载管理
  'debugger',          // 调试器
],
host_permissions: ['<all_urls>']  // 访问所有网站
```

## 开发注意事项

### 扩展入口点

- **后台脚本**: `entrypoints/background.ts` - 处理扩展生命周期和后台任务
- **内容脚本**: `entrypoints/content.ts` - 注入到网页中，处理 DOM 交互
- **弹窗**: `entrypoints/popup/main.tsx` - 用户点击扩展图标时显示
- **离屏文档**: `entrypoints/offscreen/main.tsx` - 处理长时间运行的任务（如录制）

### 浏览器兼容性

- 支持 Chrome 和 Firefox 浏览器
- 使用 WXT 框架抽象浏览器差异

### 代码质量

- 使用 ESLint 进行代码检查
- Husky 用于 Git 钩子管理
- Lint-staged 确保暂存文件符合规范