wurenzhi/makemd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 添加货币和汇率管理功能

Browse Source 
refactor: 重构前端路由和登录逻辑

docs: 更新业务闭环、任务和架构文档

style: 调整代码格式和文件结构

chore: 更新依赖项和配置文件
This commit is contained in:
wurenzhi
2026-03-19 19:08:15 +08:00
parent 8de9ea0aaa
commit eafa1bbe94
203 changed files with 20240 additions and 39580 deletions
Download Patch File Download Diff File Expand all files Collapse all files

573
docs/04_Plugin/01_Plugin_Design.md Normal file
View File

@@ -0,0 +1,573 @@
# Plugin Design (Crawlful Hub)
> **定位**：Crawlful Hub 浏览器插件架构设计文档 - 包含技术栈、目录结构、核心功能及开发规范。
> **更新日期**: 2026-03-18
> **最高优先级参考**: [Business_ClosedLoops.md](../00_Business/Business_ClosedLoops.md)
---
## 1. 技术栈 (Tech Stack)
| 层级 | 技术 | 版本 | 用途 |
|------|------|------|------|
| **Framework** | WebExtensions API | MV3 | 浏览器扩展标准 |
| **Language** | TypeScript | 5.x | 开发语言 |
| **Build Tool** | Vite | 5.x | 构建工具 |
| **Bundler** | Rollup | 4.x | 代码打包 |
| **UI** | React + Tailwind | 18.x + 3.x | 弹窗/选项页 UI |
| **Testing** | Vitest | 1.x | 单元测试 |
---
## 2. 目录结构 (Directory Structure)
```
extension/
│
├─ manifest.json # 扩展清单 (MV3)
│
├─ src/
│ │
│ ├─ background/ # Service Worker (后台脚本)
│ │ ├─ index.ts # 入口
│ │ ├─ handlers/
│ │ │ ├─ messageHandler.ts # 消息处理
│ │ │ ├─ alarmHandler.ts # 定时任务
│ │ │ └─ commandHandler.ts # 快捷键处理
│ │ └─ services/
│ │ ├─ crawlerService.ts # 网页采集服务（无API平台）
│ │ ├─ syncService.ts # 同步服务
│ │ └─ authService.ts # 认证服务
│ │
│ ├─ content/ # 内容脚本 (注入页面)
│ │ ├─ index.ts # 入口
│ │ ├─ crawlers/ # 采集器
│ │ │ ├─ amazonCrawler.ts
│ │ │ ├─ ebayCrawler.ts
│ │ │ ├─ shopifyCrawler.ts
│ │ │ └─ aliexpressCrawler.ts
│ │ ├─ automation/ # 自动化操作
│ │ │ ├─ listingAutomation.ts
│ │ │ ├─ orderAutomation.ts
│ │ │ └─ adAutomation.ts
│ │ └─ utils/
│ │ ├─ domUtils.ts
│ │ ├─ selectorUtils.ts
│ │ └─ eventUtils.ts
│ │
│ ├─ popup/ # 弹窗页面
│ │ ├─ index.tsx
│ │ ├─ components/
│ │ │ ├─ QuickActions.tsx
│ │ │ ├─ StatusPanel.tsx
│ │ │ └─ RecentTasks.tsx
│ │ └─ hooks/
│ │ └─ useBackground.ts
│ │
│ ├─ options/ # 选项页面
│ │ ├─ index.tsx
│ │ ├─ components/
│ │ │ ├─ GeneralSettings.tsx
│ │ │ ├─ PlatformSettings.tsx
│ │ │ ├─ AccountSettings.tsx
│ │ │ └─ AdvancedSettings.tsx
│ │ └─ stores/
│ │ └─ settingsStore.ts
│ │
│ ├─ shared/ # 共享资源
│ │ ├─ types/
│ │ │ ├─ messaging.ts # 消息类型定义
│ │ │ ├─ crawler.ts # 采集类型
│ │ │ └─ platform.ts # 平台类型
│ │ ├─ constants/
│ │ │ ├─ platforms.ts # 平台常量
│ │ │ └─ selectors.ts # 选择器常量
│ │ └─ utils/
│ │ ├─ logger.ts
│ │ ├─ storage.ts
│ │ └─ crypto.ts
│ │
│ └─ injected/ # 注入脚本 (隔离环境)
│ ├─ index.ts
│ └─ services/
│ └─ bridgeService.ts
│
├─ assets/ # 静态资源
│ ├─ icons/
│ │ ├─ icon-16.png
│ │ ├─ icon-32.png
│ │ ├─ icon-48.png
│ │ └─ icon-128.png
│ └─ styles/
│ └─ global.css
│
├─ _locales/ # 国际化
│ ├─ en/
│ │ └─ messages.json
│ └─ zh_CN/
│ └─ messages.json
│
└─ dist/ # 构建输出
```
---
## 3. 架构设计 (Architecture)
### 3.1 核心组件关系
```
┌─────────────────────────────────────────────────────────────┐
│ Browser Extension │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Popup │ │ Options │ │ Content │ │
│ │ (UI) │◄───►│ (Settings) │◄───►│ (Page) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ └────────────────────┼────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ Service Worker │ │
│ │ (Background) │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Crawler │ │ Sync │ │ Auth │ │
│ │ Engine │ │ Engine │ │ Engine │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 3.2 通信机制
#### 消息类型 (Messaging Types)
```typescript
// src/shared/types/messaging.ts
export enum MessageType {
// 采集相关
CRAWL_PRODUCT = 'CRAWL_PRODUCT',
CRAWL_ORDER = 'CRAWL_ORDER',
CRAWL_COMPLETE = 'CRAWL_COMPLETE',
// 自动化相关
AUTO_LISTING = 'AUTO_LISTING',
AUTO_ORDER = 'AUTO_ORDER',
AUTO_AD = 'AUTO_AD',
// 同步相关
SYNC_DATA = 'SYNC_DATA',
SYNC_STATUS = 'SYNC_STATUS',
// 认证相关
AUTH_LOGIN = 'AUTH_LOGIN',
AUTH_LOGOUT = 'AUTH_LOGOUT',
AUTH_REFRESH = 'AUTH_REFRESH',
// 设置相关
GET_SETTINGS = 'GET_SETTINGS',
SET_SETTINGS = 'SET_SETTINGS',
// 任务相关
TASK_STATUS = 'TASK_STATUS',
TASK_RESULT = 'TASK_RESULT',
}
export interface MessagePayload {
type: MessageType;
data?: any;
error?: string;
traceId?: string;
}
```
#### 通信流程
```
Content Script ──► Background Service Worker ──► Backend API
│ │
│◄─────────────────────┘
│
Popup/Options ◄─── Chrome Storage
```
---
## 4. 核心功能模块
### 4.1 数据采集模块 (Crawler)
**功能定位**
- 从各电商平台采集商品、订单数据
- **仅处理无API平台**：TikTok Shop, Temu, 部分1688页面等
- **有API平台由后端处理**：Amazon MWS, eBay API, Shopee Open API
- 支持沙箱模式（测试环境）
**采集策略矩阵**
| 平台 | 类型 | 采集方式 | 登录要求 | 反爬策略 |
|------|------|----------|----------|----------|
| Amazon | 有API | ❌ 后端处理 | OAuth | API限流 |
| eBay | 有API | ❌ 后端处理 | OAuth | API限流 |
| Shopee | 有API | ❌ 后端处理 | OAuth | API限流 |
| TikTok Shop | 无API | ✅ 插件采集 | 需登录 | 指纹隔离+代理IP |
| Temu | 无API | ✅ 插件采集 | 需登录 | 指纹隔离+代理IP |
| 1688(部分) | 无API | ✅ 插件采集 | 可选 | 频率控制 |
**⚠️ 重要约束**
- **后端严禁直接爬取**（IP封禁风险、法律合规问题）
- 所有网页级采集必须通过插件在用户浏览器端执行
- 插件必须实现店铺隔离（一店一IP一指纹）
**采集器实现**
```typescript
// src/content/crawlers/amazonCrawler.ts
export class AmazonCrawler {
private selectors = {
title: '#productTitle',
price: '.a-price-whole, .a-offscreen',
images: '#landingImage, .a-dynamic-image',
description: '#feature-bullets, #productDescription',
reviews: '#acrCustomerReviewText',
};
async crawlProduct(): Promise<ProductData> {
const title = this.extractText(this.selectors.title);
const price = this.extractPrice(this.selectors.price);
const images = this.extractImages(this.selectors.images);
const description = this.extractText(this.selectors.description);
return {
platform: 'AMAZON',
title,
price,
images,
description,
url: window.location.href,
crawledAt: new Date().toISOString(),
};
}
private extractText(selector: string): string {
const element = document.querySelector(selector);
return element?.textContent?.trim() || '';
}
private extractPrice(selector: string): number {
const element = document.querySelector(selector);
const text = element?.textContent?.replace(/[^\d.]/g, '') || '0';
return parseFloat(text);
}
private extractImages(selector: string): string[] {
const elements = document.querySelectorAll(selector);
return Array.from(elements)
.map(el => el.getAttribute('src') || el.getAttribute('data-src'))
.filter(Boolean) as string[];
}
}
```
**采集流程**
```
1. 用户点击采集按钮 / 定时任务触发
2. Content Script 注入采集器
3. 采集器解析 DOM 提取数据
4. 数据发送至 Background
5. Background 发送至后端 API
6. 返回采集结果
```
### 4.2 自动化操作模块 (Automation)
**功能定位**
- 自动刊登商品
- 自动处理订单
- 自动投放广告
**自动化实现**
```typescript
// src/content/automation/listingAutomation.ts
export class ListingAutomation {
async autoListing(productData: ProductData, platform: string): Promise<boolean> {
switch (platform) {
case 'AMAZON':
return this.listOnAmazon(productData);
case 'EBAY':
return this.listOnEbay(productData);
case 'SHOPIFY':
return this.listOnShopify(productData);
default:
throw new Error(`Unsupported platform: ${platform}`);
}
}
private async listOnAmazon(product: ProductData): Promise<boolean> {
// 1. 导航到刊登页面
await this.navigateTo('/inventory/add');
// 2. 填写商品信息
await this.fillInput('#title', product.title);
await this.fillInput('#price', product.price.toString());
await this.fillTextarea('#description', product.description);
// 3. 上传图片
for (const imageUrl of product.images) {
await this.uploadImage(imageUrl);
}
// 4. 提交刊登
await this.click('#submit-button');
// 5. 等待结果
return this.waitForSuccess();
}
private async navigateTo(path: string): Promise<void> {
window.location.href = `https://sellercentral.amazon.com${path}`;
await this.waitForElement('#title', 10000);
}
private async fillInput(selector: string, value: string): Promise<void> {
const input = document.querySelector(selector) as HTMLInputElement;
if (input) {
input.value = value;
input.dispatchEvent(new Event('input', { bubbles: true }));
}
}
private async waitForElement(selector: string, timeout: number): Promise<void> {
return new Promise((resolve, reject) => {
const startTime = Date.now();
const check = () => {
if (document.querySelector(selector)) {
resolve();
} else if (Date.now() - startTime > timeout) {
reject(new Error('Timeout waiting for element'));
} else {
setTimeout(check, 100);
}
};
check();
});
}
}
```
### 4.3 数据同步模块 (Sync)
**功能定位**
- 定时同步订单数据
- 同步库存状态
- 同步广告数据
**同步配置**
```typescript
// src/background/services/syncService.ts
export class SyncService {
private syncIntervals: Record<string, number> = {
orders: 5 * 60 * 1000, // 5分钟
inventory: 10 * 60 * 1000, // 10分钟
ads: 30 * 60 * 1000, // 30分钟
};
async startSync(): Promise<void> {
// 创建定时任务
chrome.alarms.create('syncOrders', { periodInMinutes: 5 });
chrome.alarms.create('syncInventory', { periodInMinutes: 10 });
chrome.alarms.create('syncAds', { periodInMinutes: 30 });
}
async handleAlarm(alarmName: string): Promise<void> {
switch (alarmName) {
case 'syncOrders':
await this.syncOrders();
break;
case 'syncInventory':
await this.syncInventory();
break;
case 'syncAds':
await this.syncAds();
break;
}
}
private async syncOrders(): Promise<void> {
const platforms = await this.getEnabledPlatforms();
for (const platform of platforms) {
try {
const orders = await this.crawlOrders(platform);
await this.sendToBackend('/api/v1/orders/sync', orders);
} catch (error) {
console.error(`Failed to sync orders for ${platform}:`, error);
}
}
}
}
```
---
## 5. 安全与隐私
### 5.1 数据存储
```typescript
// src/shared/utils/storage.ts
export class SecureStorage {
// 存储敏感数据（加密）
static async setSecure(key: string, value: string): Promise<void> {
const encrypted = await this.encrypt(value);
await chrome.storage.local.set({ [key]: encrypted });
}
// 读取敏感数据（解密）
static async getSecure(key: string): Promise<string | null> {
const result = await chrome.storage.local.get(key);
if (result[key]) {
return this.decrypt(result[key]);
}
return null;
}
// 存储普通数据
static async set(key: string, value: any): Promise<void> {
await chrome.storage.local.set({ [key]: value });
}
// 读取普通数据
static async get(key: string): Promise<any> {
const result = await chrome.storage.local.get(key);
return result[key];
}
private static async encrypt(text: string): Promise<string> {
// 使用 Chrome 的加密 API
// 实际实现需要更复杂的加密逻辑
return btoa(text);
}
private static async decrypt(encrypted: string): Promise<string> {
return atob(encrypted);
}
}
```
### 5.2 权限控制
```json
// manifest.json
{
"manifest_version": 3,
"name": "Crawlful Hub",
"version": "1.0.0",
"permissions": [
"storage",
"alarms",
"activeTab",
"scripting"
],
"host_permissions": [
"https://sellercentral.amazon.com/*",
"https://www.ebay.com/*",
"https://*.myshopify.com/*",
"https://*.tiktok.com/*"
],
"background": {
"service_worker": "src/background/index.ts"
},
"content_scripts": [
{
"matches": [
"https://sellercentral.amazon.com/*",
"https://www.ebay.com/*"
],
"js": ["src/content/index.ts"]
}
],
"action": {
"default_popup": "src/popup/index.html"
},
"options_page": "src/options/index.html"
}
```
---
## 6. 开发规范
### 6.1 代码规范
- 使用 TypeScript 严格模式
- 使用函数式组件 + Hooks
- 避免使用 `any` 类型
- 所有消息类型必须在 `messaging.ts` 中定义
### 6.2 测试规范
```typescript
// __tests__/crawler.test.ts
import { AmazonCrawler } from '../src/content/crawlers/amazonCrawler';
describe('AmazonCrawler', () => {
let crawler: AmazonCrawler;
beforeEach(() => {
crawler = new AmazonCrawler();
});
test('should extract product title', async () => {
// Mock DOM
document.body.innerHTML = `
<span id="productTitle">Test Product</span>
`;
const product = await crawler.crawlProduct();
expect(product.title).toBe('Test Product');
});
});
```
### 6.3 构建与发布
```bash
# 开发模式
npm run dev
# 生产构建
npm run build
# 打包扩展
npm run package
# 运行测试
npm run test
```
---
## 7. 相关文档
- [DOM Interaction](./DOM_Interaction.md)
- [Automation Scripts](./Automation_Scripts.md)
- [Backend Design](../02_Backend/Backend_Design.md)
- [Business ClosedLoops](../00_Business/Business_ClosedLoops.md)
---
*本文档基于业务闭环设计，最后更新: 2026-03-18*