---
inclusion: manual
---

# OfferPie Chrome Extension 项目结构说明

## 1️⃣ 项目整体层次
```
offferpie_google_extension/
│
├─ package.json                   # 依赖 + manifest 权限配置
├─ tsconfig.json                  # TypeScript 配置（继承 Plasmo 模板）
├─ .prettierrc.cjs                # 代码格式化配置
│
├─ assets/                        # 静态资源（图标等）
│   ├─ icon.png
│   └─ icon1.png
│
└─ src/                           # 源码主目录
    ├─ config.ts                  # **环境配置**（多环境切换：dev/prod）
    ├─ constants.ts               # **全局常量**（消息类型、存储 Key、缓存时间等）
    │
    ├─ background/                # **Background Service Worker**
    │   └─ index.ts               # 后台服务（监听图标点击、处理 Cookie 读取消息、安装事件）
    │
    ├─ contents/                  # **Content Scripts**（注入到目标网页的脚本）
    │   └─ sidebar.tsx            # 侧边栏入口（Shadow DOM 样式隔离，监听消息控制显隐）
    │
    ├─ components/                # **UI 组件**
    │   ├─ SidebarPanel.tsx       # 侧边栏面板组件
    │   └─ SidebarPanel.scss      # 侧边栏样式
    │
    ├─ api/                       # **接口层**（REST API 请求封装）
    │   ├─ request.ts             # 通用请求方法（自动带 Token、统一错误处理、支持路径/query/body 参数）
    │   ├─ dataApi.ts             # Java 后端接口（业务 CRUD）
    │   └─ aiApi.ts               # Python AI 后端接口（AI 能力）
    │
    ├─ utils/                     # **工具层**（无业务依赖的通用工具）
    │   ├─ cookie.ts              # Cookie 读取（通过消息中转 Background 获取）
    │   ├─ storage.ts             # Chrome Storage 封装（chrome.storage.local 读写删）
    │   └─ auth.ts                # 登录状态检查（带缓存，全局共享）
    │
    └─ lib/                       # **业务逻辑层**（具体业务功能实现）
        ├─ autofill.ts            # 自动填表逻辑
        ├─ dom.ts                 # DOM 操作工具
        ├─ formMatcher.ts         # 表单匹配器
        ├─ pickerDetector.ts      # 选择器检测
        ├─ pickerFill.ts          # 选择器填充
        ├─ datePicker.ts          # 日期选择器处理
        ├─ resumeDataHelper.ts    # 简历数据辅助
        ├─ resumeUpload.ts        # 简历上传
        ├─ constants.ts           # 业务常量
        └─ types.ts               # 业务类型定义
```

## 2️⃣ 各层模块职责
| 层级 | 主要职责 | 关键文件 |
|------|----------|----------|
| **config** | 环境配置管理，支持 dev/prod 切换 | `config.ts`（dataBaseApi、aiBaseApi、cookieSourceUrl） |
| **constants** | 全局常量定义 | `constants.ts`（MSG_TYPES、STORAGE_KEYS、LOGIN_CHECK_INTERVAL） |
| **background** | 后台事件处理：图标点击、Cookie 读取中转、安装事件 | `background/index.ts` |
| **contents** | 注入目标网页的脚本，负责 UI 渲染和页面交互 | `contents/sidebar.tsx`（侧边栏面板注入） |
| **components** | 可复用 React UI 组件 | `SidebarPanel.tsx` |
| **api** | 接口请求封装，自动携带 Token，统一错误处理 | `request.ts`（通用封装）、`dataApi.ts`（Java 端）、`aiApi.ts`（Python 端） |
| **utils** | 无业务依赖的通用工具 | `cookie.ts`（Cookie 获取）、`storage.ts`（持久化存储）、`auth.ts`（登录检查） |
| **lib** | 具体业务功能实现（自动填表、DOM 操作、简历处理等） | `autofill.ts`、`formMatcher.ts`、`resumeUpload.ts` 等 |

## 3️⃣ 技术栈
| 类别 | 技术选型 | 说明 |
|------|----------|------|
| **扩展框架** | Plasmo 0.90 | Chrome MV3 扩展开发框架，约定式文件结构 |
| **UI 框架** | React 19 | 组件化 UI 开发 |
| **UI 组件库** | Arco Design (web-react) | 字节跳动 React 组件库 |
| **语言** | TypeScript 5.8 | 类型安全 |
| **样式** | SCSS | 组件样式，通过 Shadow DOM 隔离 |

## 4️⃣ Plasmo 框架约定
| 文件/目录 | 框架行为 |
|-----------|----------|
| `src/background/index.ts` | 自动注册为 Background Service Worker |
| `src/contents/*.tsx` | 自动注册为 Content Script（带 UI，Shadow DOM 隔离） |
| `src/contents/*.ts` | 自动注册为 Content Script（纯逻辑，无 UI） |
| `popup.tsx`（未使用） | 点击图标弹出的小窗口 |
| `options.tsx`（未使用） | 扩展设置页 |
| `sidepanel.tsx`（未使用） | 浏览器侧边栏面板 |
| `package.json → manifest` | 自动合并生成 manifest.json |

## 5️⃣ 通信架构
```
Content Script（页面内）
    │
    │  chrome.runtime.sendMessage
    │  ← GET_TOKEN / GET_COOKIES →
    ▼
Background Service Worker（后台）
    │
    │  chrome.cookies.get / getAll
    ▼
Chrome Cookie Store（公司网站域名下的 Cookie）
```

- Content Script 不直接读 Cookie，统一通过 Background 中转
- Background 按需唤醒，处理完消息后自动休眠
- Token 从公司网站 Cookie 中获取，复用页面登录状态

## 6️⃣ 鉴权机制
- **Token 来源**：通过 `chrome.cookies.get` 从公司网站域名（cookieSourceUrl）读取名为 `Token` 的 Cookie
- **请求携带**：`api/request.ts` 每次请求前自动获取 Token，塞入请求头 `Token` 字段
- **登录检查**：`utils/auth.ts` 提供 `ensureLogin()` 方法，调用后端 `checkLogin` 接口验证 Token 有效性
- **缓存策略**：登录检查结果缓存到 `chrome.storage.local`，5 分钟内全局不重复请求；失败立即清缓存

## 7️⃣ 与后端的关系
| 后端 | 基础地址 | 用途 |
|------|----------|------|
| **Java 端**（back-end） | `http://localhost:8080/api` | 业务 CRUD：用户、简历、岗位、投递等 |
| **Python AI 端**（offerpie_python_ai） | `http://localhost:8000` | AI 能力：智能分析、简历解析、对话等 |

- 两个后端共享同一套 Token 鉴权体系
- 插件通过读取公司网站 Cookie 复用登录状态，无需单独登录

## 8️⃣ Manifest 权限
| 权限 | 用途 |
|------|------|
| `activeTab` | 访问当前活动标签页 |
| `storage` | 使用 chrome.storage.local 持久化数据 |
| `tabs` | 操作标签页（发送消息等） |
| `cookies` | 读取公司网站域名下的 Cookie（获取 Token） |
| `host_permissions: <all_urls>` | Content Script 注入所有页面 + 跨域请求 |

## 9️⃣ 构建与运行
- **安装依赖**：`npm install`
- **开发模式**：`npm run dev`（热更新，产物在 `build/chrome-mv3-dev`）
- **生产构建**：`npm run build`（产物在 `build/chrome-mv3-prod`）
- **打包发布**：`npm run package`（生成 zip）
- **加载到 Chrome**：`chrome://extensions` → 开发者模式 → 加载已解压的扩展程序 → 选择 build 目录