# 🏢 Business Blueprint (Crawlful Hub)

> **定位**：Crawlful Hub 业务核心蓝图 - 包含项目目标、技术栈、核心业务模块、功能规格、状态机及行业标杆参考。
> **更新日期**: 2026-03-17

---

## 1. 项目概述 (Project Overview)

**项目名称**: Crawlful Hub (跨境电商增长中台)

**项目愿景**:
成为全球领先的跨境电商智能增长平台
- 🎯 **一站式解决方案**: 从选品到交付的全链路自动化
- 🤖 **AI驱动决策**: 智能定价、智能选品、智能运营
- 🌍 **全球化布局**: 支持多平台、多币种、多语言
- 💰 **利润最大化**: 套利引擎 + 成本优化 + 风险控制

**项目目标**:
- 实现多渠道电商运营管理（TOC/TOB）。
- 提供从商品采集到财务对账的完整业务闭环。
- 提升跨境贸易运营效率与利差套利能力。
- 自动化80%的运营操作，帮助商户平均利润提升30%。

**主要技术栈**:
- **语言**: TypeScript
- **前端框架**: UmiJS 4.x, Ant Design 5.x
- **后端框架**: Node.js 20+
- **数据库**: MySQL 8.0 (cf_ 前缀)
- **缓存**: Redis 6.0

---

## 2. 核心业务闭环 (Core Business Loops)

### 2.1 闭环验收标准 (P0)
- **商品刊登闭环**: ERP 商品 → 平台可售。要求全链路追踪 (traceId)。
- **订单履约闭环**: 平台订单 → 妥投。状态机完整，异常可介入。
- **售后逆向闭环**: 售后请求 → 退款完成。状态流转清晰。
- **资金对账闭环**: platform 结算流水 → 差异关闭。汇率明确，可回溯。
- **合规风控闭环**: 风险信号 → 拦截/复核。审计留痕。

### 2.2 追踪五元组 (Tracking Quintuple)
- `tenantId`: 租户 ID (业务隔离)
- `shopId`: 店铺 ID (平台/店铺隔离)
- `taskId`: 任务 ID (任务/规则触发归档)
- `traceId`: 链路追踪 ID (全链路唯一标识)
- `businessType`: 业务类型 (TOC/TOB)

---

## 3. 核心业务模块 (Core Business Modules)

### 3.1 商品管理 (PIM) & 跨平台套利 (Arbitrage)
- **跨平台套利雷达**: 自动识别 1688 (价格洼地) 与 Amazon/Temu/eBay (价格高地) 的利差。支持视觉寻源与多模态匹配。
- **套利净利引擎**: 统一计算口径 `售价 - 采购 - 平台费 - 物流 - 税费 - 汇率对冲 - 售后损耗 - 广告摊销`。
- **风险门禁**: 
  - B2C: 利润率 < 20% 触发风控预警
  - B2B: 利润率 < 15% 禁止报价
  - ROI < 20% 标记为高风险，< 5% 强制拦截
- **SPU/SKU 管理**: 支持独立站 (Shopify/WooCommerce) 与平台电商的多维度属性映射。
- **刊登任务**: 支持无 API 平台 (TikTok/Temu) 模拟执行与官方 API 刊登。

### 3.2 订单管理 (OMS) & TOB 业务
- **多渠道归集**: 聚合平台订单与独立站 (DTC) 订单。
- **自动审单**: 地址、库存、风险验证规则引擎自动审核。
- **异常处理**: 缺货、地址异常、支付失败进入异常队列，支持人工介入。
- **批量操作**: 审核、发货、标记、打印面单。
- **TOB 报价红线**: B2B 利润率 < 15% 严禁报价，支持大宗贸易的阶梯价设置与询盘转化。
- **分账引擎**: 针对 TOB 业务支持主权级信用池 (Sovereign Credit Pool) 与跨境结算审计。
- **利润核算**: 实时计算单笔订单净利，关联广告支出实现全链路 ROI 溯源。

### 3.3 库存与仓储 (WMS)
- **多仓协同**: 实时同步全球多仓库存，支持独立站与平台库存共享/隔离策略。
- **补货算法**: `(销量预测 * 采购周期 + 安全库存 - 在途)`。支持基于利差热力图的智能补货决策。
- **入/出库流**: ASN 预报、QC 质检、波次拣货。
- **库存老化分析**: 分析周转天数、识别呆滞库存。
- **库存预测与补货**: 基于销售预测与仓库健康度制定采购需求池。

### 3.4 财务管理 (FIN)
- **成本归集**: 采购、头程/尾程物流、佣金、广告。
- **利润实时核算**: 销售收入 - 采购成本 - 物流 - 平台费 - 广告。
- **多币种对账**: ZKP 隐私审计，自动差异匹配。支持 VAT 计提，汇率自动同步。
- **平台费用监控**: 实时监控平台收取的各类佣金、广告投入与退款流水。
- **ROI 看板**: 实时显示业务决策对财务贡献。

### 3.5 营销与广告 (MKT)
- **跨平台投放**: 统一管理 Facebook, Google, TikTok 广告。
- **独立站 DTC 策略**: 针对独立站流量进行全链路归因分析 (Multi-touch Attribution)。
- **动态优化**: 基于 ROAS 自动调整预算，监控盈亏平衡点 (Break-even ROAS)。
- **套利闭环回流**: 从选品建议到真实销量回流，持续迭代套利策略。
- **广告计划看板**: 跨平台广告投放监控与预算动态优化，ROAS 实时监控、自动调价建议、亏损活动预警。

### 3.6 供应链与供应商管理 (SCM)
- **供应商档案**: 信用分级、联系方式、评分管理。
- **采购管理**:
  - 1688 一键代采、实时比价
  - 多供应商询价、MOQ、交期对比
- **补货建议**: `(销量预测 * 采购周期 + 安全库存 - 在途)` 自动生成。
- **供应商产能监控**: 评估供应商交付准时率、质量评分与实时产能状态。

### 3.7 治理与审批中心
- **通用审批中心**: 大额订单、价格变更、退款等敏感操作多级审核。
- **UI 布局**: 待办/已办统计，审批日志，核准/拒绝动作。

### 3.8 合规与证书管理
- **自动化合规**: 订单数据生成 CE、FDA、原产地证等电子证书。
- **信用分级**: 基于配送员履约率、争议率的信用体系。

### 3.9 套利与定价分析 (ARB / Pricing) — TOC + TOB 全链路

#### 核心定位
- 支持 **零售（TOC）** 和 **批发/整柜（TOB）** 套利分析。
- 覆盖 **从生产/采购阶段 → 拿货/整柜阶段 → 零售/平台销售阶段** 的利润分析。
- 提供 **定价推荐、ROI 模拟、利润预测和风险提示**。

#### 核心功能

1. **成本与利润测算**
   - **TOC**：单件商品成本 + 平台费 + 物流 + 广告 → 售价 / ROI / 利润预测
   - **TOB**：整柜成本、批量采购成本、关税、物流 → 单件拆算利润、ROI
   - 支持 **固定成本与浮动成本**组合计算（如汇率、运费波动、关税变化）

2. **定价推荐与模拟**
   - 自动推荐售价区间以满足目标毛利率或 ROI 红线
   - 支持批量调价、不同平台定价差异、整柜与零售拆算定价
   - 可模拟不同库存、销量、物流方式下的利润变化

3. **套利机会发现**
   - **跨平台零售套利**：基于采集价格或手动录入的成本分析价差
   - **跨阶段 TOB 套利**：生产采购成本 vs 平台/批发售价，输出净利和 ROI
   - **跨国家/跨仓套利**：考虑关税、仓储成本、物流方式的最优利润路径

4. **供应链阶段利润分析**
   - **生产阶段**：原材料采购、工厂成本、生产周期成本
   - **拿货阶段**：整柜成本、运输成本、报关费用、税费
   - **零售阶段**：平台费用、广告投入、物流派送、售后成本
   - 支持全链路可视化报表，显示每个环节对利润的贡献

5. **多维度分析报表**
   - **商品维度**：每 SKU/整柜商品成本、售价、ROI、利润预测
   - **阶段维度**：生产 → 拿货 → 零售，每阶段成本、利润占比
   - **平台 / 渠道维度**：各平台毛利率、利润贡献度、风险提示
   - **时间维度**：预测未来收益、库存消耗、套利机会变化

#### 业务流示意
```text
生产阶段 / 原材料采购
        │
        ▼
拿货 / 整柜阶段
        │
        ▼
套利分析模块（TOB + TOC）
  ├─ 成本测算（固定/浮动）
  ├─ 定价推荐 & ROI 模拟
  ├─ 跨平台 / 跨阶段套利机会
  └─ 全链路利润分析报表
        │
        ▼
商品刊登 / 调价执行
        │
        ▼
OMS / WMS / 财务 / 营销全链路闭环
```

### 3.10 B2B / TOB 贸易管理
- **报价红线控制**: 利润率低于阈值自动拦截，支持多级审批。
- **阶梯价策略**: 采购数量触发阶梯折扣。
- **信用池**: 基于历史履约记录的结算额度与审计。
- **询盘管理**: 多渠道整合询盘，支持跟进与转化。

### 3.11 产品采集与数据分析
- **多平台采集**: Amazon, eBay, Shopee, 1688 等平台商品信息抓取。
- **数据标准化**: SKU 属性、价格、库存统一格式化。
- **分析支持**: ARB、PIM、营销调价、库存补货预测的数据基础。

### 3.12 物流策略与渠道选择
- **物流模式管理**:
  - 整柜出海 (FCL Shipping)
  - 自有仓出货
  - 第三方仓出货 (3PL)
  - 直发客户 (D2C / Dropship)
- **物流健康状态**: 多渠道实时轨迹遥测、异常节点告警 (48h+ 停留)。

### 3.13 客户管理 (CRM)
- **客户 360 视图**: 订单历史、客诉记录与信用分级。
- **押金与账户管理**: 客户/商家押金管理、账户资产统计。

---

## 4. 关键业务状态机 (State Machines)

### 4.1 订单状态机
```
PULLED → PENDING_REVIEW → CONFIRMED → ALLOCATED → READY_TO_SHIP → SHIPPED → DELIVERED → CLOSED
```

### 4.2 业务审核状态机
```
SUBMITTED (提交) → PENDING_REVIEW (人工审核) → EXECUTED / REJECTED
```

### 4.3 售后状态机
```
REQUESTED → PENDING_REVIEW → APPROVED → RETURN_IN_TRANSIT → QC_INSPECTION → REFUNDED / REJECTED
```

---

## 5. 行业标杆复刻方案 (Benchmarks)

| 业务领域 | 标杆参考 | 核心复刻重点 |
|:------------|:--------------------|:--------------|
| **商品 (PIM)** | 91妙手、店小秘 | 多平台刊登与库存统一 |
| **套利 (ARB)** | 船长BI、Helium 10 | 跨平台寻源与实时利润测算 |
| **订单 (OMS)** | 易仓、积加 | 多源归集与自动化审单 |
| **独立站 (DTC)** | Shopify | 流量归因与多租户隔离 |
| **仓储 (WMS)** | Flexport | 路径规划与多仓协同 |
| **财务 (FIN)** | 出海匠 | 全口径利润审计与回款跟踪 |
| **营销 (MKT)** | 蝉妈妈 | 趋势分析与数据可视化 |
| **供应链 / 采购** | 1688 + 供应商管理工具 | 补货建议、采购比价、供应商信用 |
| **物流模式** | FCL / Own / 3PL / D2C | 全球物流路径、调拨、直发客户 |
| **审批与合规** | 内部审批 & 电子证书 | 敏感操作审核、证书生成 |
| **B2B 贸易管理** | 内部 TOB 系统 | 阶梯价、信用池、询盘管理 |

---

## 6. 项目结构与目录映射 (Directory Map)

```
project
 ├─ .trae/rules/         # 编码与项目特定规则
 ├─ docs/                # 分类文档 (业务、数据、架构、规范、质量)
 ├─ server/src/          # 后端服务 (api, service, repository, domains, workers)
 ├─ extension/src/       # 浏览器插件 (background, content)
 ├─ console/src/         # 前端控制台 (pages, components, services, stores)
```

---

## 7. 实施指南摘要 (Implementation Guides)

### 7.1 TOC 加速架构
- **快速上线**: 提供 Amazon/AliExpress 基础订单同步。
- **ConsumerOrderService**: 专责 TOC 订单流。

### 7.2 非 SaaS 多租户隔离
- **数据独占**: `tenant_id` 逻辑隔离，行级安全校验。
- **资源配额**: 严格限制并发 Worker 与 API 速率。

---

*本蓝图整合了业务功能规格，详细闭环流程请查阅 [Business_ClosedLoops.md](./Business_ClosedLoops.md)*