# Crawlful Extension - 跨境自动化执行终端 (V20.0 立项说明书)

## 1. 项目愿景与定位 (Vision)
Crawlful Extension 是增长中台的“触角”与“执行终端”。它深度嵌入浏览器，通过**规则驱动的 UI 注入、跨站数据同步与自动化执行内核**，将中台的 AI 决策转化为具体的业务操作。V20.0 引入了 **WebAR 预览**与 **E2E 自动化自愈**技术，进一步提升了前端运营的确定性与体验。

---

## 2. 核心架构与功能模块 (Modules)

### 2.1 自动化执行内核 (Automation Core)
*   **万能注入引擎 (JsonInjector)**：
    *   **零代码适配**：通过 JSON Schema 定义不同平台的 HTML 选择器（标题、价格、SKU、图片），实现无需发布插件即可适配新平台。
    *   **自动表单填充**：一键将 Hub 中台的标准化商品数据填充至 Temu、TikTok、Shopee 等发布端后台。
*   **同行店铺一键采集 (Store Cloner)**：
    *   **批量队列同步**：在竞品店铺列表页一键抓取所有 SKU 元数据，并推送到中台采集队列。

### 2.2 数据同步枢纽 (Sync Hub)
*   **跨站状态感知**：实时在采集页面显示商品是否已采集、已发布或库存状态。
*   **离线数据缓存 (Dexie.js)**：利用 IndexedDB 实现大规模采集数据的本地缓存与断点续传。

### 2.3 交互增强 (UX Optimization)
*   **WebAR 预览 (AR预览注入)**：在特定品类（如饰品、眼镜）详情页自动注入 AR 试戴按钮，提升转化率。
*   **零偏移骨架屏 (ZLS 2.0)**：解决插件注入导致的页面布局抖动问题，提供无感的原生化加载体验。

### 2.4 稳定性保障 (Reliability)
*   **E2E Shadow Test (自动化测试网关)**：在背景页周期性运行针对核心平台的注入检测脚本，一旦选择器失效，自动向 Hub 报错并通知 AI 修复。

---

## 3. 技术架构设计 (V20.0 Stack)

### 3.1 前端技术栈 (Extension)
*   **构建工具**：Vite 5 + CRXJS (Manifest V3)
*   **核心框架**：React 18 + TypeScript
*   **样式库**：Tailwind CSS 3 + Shadcn UI
*   **状态管理**：Zustand / Pinia (跨页面状态同步)
*   **数据存储**：Dexie.js (IndexedDB)

### 3.2 协同机制
*   **API 客户端 (SyncService)**：封装标准化的 Hub 通信协议，支持采集任务的实时下发与状态回传。

---

## 4. 实施路线图 (Roadmap)

### 第一阶段：框架搭建与注入内核 (Completed)
- [x] 基于 Vite + React 的插件 V3 架构搭建。
- [x] `BaseInjector` 抽象类与 `TemuInjector` 实现。
- [x] Client/Server 通信协议定义。

### 第二阶段：同步增强与体验优化 (Completed)
- [x] `Sync Hub` 跨站数据同步中枢。
- [x] `JsonInjector` 零代码规则解析。
- [x] `Store Cloner` 批量采集逻辑。

### 第三阶段：AI 交互与自动化增强 (In Progress)
- [ ] `AR预览注入 (WebAR)` 功能上线。
- [ ] `E2E Shadow Test` 自动化自愈脚本。
- [x] `ImageEditor` 插件端素材工坊集成。

---

## 5. 项目核心价值 (Value)
1.  **运营效率提升**：将原本数十分钟的人工搬货流程缩短至秒级自动化填充。
2.  **极速平台适配**：通过 JsonInjector 实现对全球电商站点的分钟级适配能力。
3.  **确定性交付**：通过自动化测试网关确保注入逻辑的持续有效性。

---

## 6. V22.0 增量补充（轻插件策略）

### 6.1 角色重定义
*   插件由“重执行终端”演进为“轻量传感器”：
    *   保留：页面识别、采集触发、状态展示；
    *   下沉：图像处理、复杂 AI 逻辑、发布编排至 Hub/Node。

### 6.2 登录与授权
*   统一采用 Web 端登录（Console 主入口）。
*   插件通过短期 Plugin Token 静默授权，避免二次登录。

### 6.3 与 Win 节点协同
*   插件负责采集与触发；
*   Win Node Agent 负责无 API 平台执行；
*   Hub 统一负责编排、审计与回执。

### 6.4 术语演进
*   `~~Dashboard~~ -> Console`，避免中台语义偏差。