# Crawlful Hub - AI-Native 电商增长中台中枢 (V20.0 立项说明书)

## 1. 项目愿景与定位 (Vision)
在 AI 与全球化深度融合的背景下，Crawlful Hub 旨在构建一个**以多模态 AI 为内核、容器化采集为基石、数据驱动决策为导向**的电商自动化增长中台。它连接了“全球选品、多维分析、智能创作、自动化分发”的完整闭环，通过 AI 技术实现从“发现利差”到“获取利润”的极速转化。

---

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

### 2.1 智能大脑 (AI-Native Core)
*   **多模态商品理解 (Multi-Modal AI)**：
    *   **深度解析**：集成 GPT-4o 视觉+文本双路解析，自动提取商品核心卖点、技术参数与 SEO 关键词。
    *   **智能创作**：基于多模态理解，自动生成符合目的地市场文化习惯的营销文案与 SEO 标题。
*   **跨境风控审计 (Security Audit)**：
    *   **图像指纹查重**：基于感知哈希 (pHash) 的图像查重引擎，规避搬运风险。
    - **侵权预警 (IP Guard)**：AI 视觉识别品牌 Logo 与敏感词扫描，降低合规风险。

### 2.2 采集与溯源 (Crawler & Sourcing)
*   **容器化沙盒采集 (Sandbox Crawler)**：
    *   **物理隔离**：基于 Docker 的采集进程池，支持 IP 自动调度与资源配额管理，彻底规避封禁风险。
    *   **拟人化模拟**：基于 Playwright 实现动态 Canvas/WebGL 指纹随机化与复杂行为轨迹模拟。
*   **供应链全链路溯源 (Link Tracker)**：
    *   **源头寻址**：基于图像指纹自动关联 1688 源头厂家，识别多级中间商加价。

### 2.3 决策支持 (Decision Hub)
*   **全球利差雷达 (Arbitrage Radar)**：
    *   **ROI 建模**：实时对比 1688、Amazon、Temu 售价，自动计算物流、佣金、税务后的净利润。
*   **库存周转优化 (Inventory Aging)**：
    *   **FIFO 库龄分析**：基于先入先出逻辑追踪库存库龄，自动触发阶梯清仓折扣建议。

---

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

### 3.1 后端技术栈 (Server)
*   **核心框架**：Node.js + Express + TypeScript
*   **性能网关**：Turbo Gateway (基于 Redis 的 L2 缓存与令牌桶限流)
*   **AI 引擎**：OpenAI GPT-4o (Vision + Text)
*   **持久化**：MySQL 8.0 + Knex.js
*   **异步任务**：BullMQ + Redis (用于审计日志与大规模采集调度)
*   **容器化**：Docker (用于 Crawler Sandbox)

### 3.2 协同机制 (Collaboration)
*   **看板驱动 (Source of Truth)**：基于 `COLLABORATION_BOARD.md` 的多 AI 协同开发模式。
*   **契约优先 (Contract-First)**：通过 `shared/types/contracts` 定义跨窗口协作协议。

---

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

### 第一阶段：基础设施与利差建模 (Completed)
- [x] 基于 Node.js + TS 的中台架构搭建。
- [x] 全球价格套利模型与实时汇率同步。
- [x] 跨平台价格比对 (ArbitrageService)。

### 第二阶段：业务闭环与安全加固 (Completed)
- [x] 全球税务合规引擎 (VAT Engine) 与库存周转优化。
- [x] 基于 pHash 的图像指纹服务与审计系统。
- [x] Turbo Gateway 性能网关落地。

### 第三阶段：AI-Native 与多模态演进 (Completed)
- [x] GPT-4o 多模态解析与 SEO 自动化。
- [x] 基于 Docker 的容器化采集沙盒 (Sandbox Crawler)。
- [x] AI 侵权预警 (IP Guard) 深度集成。

### 第四阶段：智能预测与运营自动化 (In Progress)
- [ ] AI 库存预测模型 (Forecaster)。
- [ ] 自动营销挽留系统 (Abandoned Cart Recovery)。
- [ ] 跨平台 API 自动化铺货闭环测试。

---

## 5. 项目核心价值 (Value)
1.  **AI 替代人力**：将繁琐的商品解析与文案改写完全自动化。
2.  **极速套利决策**：分钟级发现全球利差机会，ROI 驱动选品。
3.  **极致稳定性**：通过沙盒技术与性能网关，确保单机环境下的高可用性。

---

## 6. V22.0 增量补充（平台接入中枢与 Win 节点）

### 6.1 混合接入策略
*   已有 API（TK Shop API / BC API）走 **Connector Bus**。
*   无 API 平台走 **No-API Bridge**，采用 `collect -> draft -> review -> publish`。
*   两类链路统一进入 **Publish Orchestrator**。

### 6.2 多商户与隔离
*   Web 登录为主入口，统一签发租户上下文与短期令牌。
*   无 API 执行层采用 Win Node Agent，一店一上下文隔离。

### 6.3 执行层模型
*   推荐结构：`Hub(Control Plane) -> Win Node Agent -> Browser Worker`。
*   节点主动注册、心跳、拉任务并回传回执，保证前后端持续通讯。

### 6.4 术语演进
*   中台前端统一语义：`~~Dashboard~~ -> Console`。