# 🏢 Business Blueprint (Crawlful Hub)

> **定位**：Crawlful Hub 高层业务规划文档 - 包含项目目标、技术栈、核心业务模块概述、功能规格、状态机及行业标杆参考。
> **更新日期**: 2026-03-19
>
> **业务闭环详细实现**：请查阅 [Business_ClosedLoops.md](./Business_ClosedLoops.md)

---

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

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

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

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

**术语规范**:
- 业务类型：`TOC`（零售）/ `TOB`（企业）
- 模块简称：PIM（商品管理）、OMS（订单管理）、WMS（库存管理）、FIN（财务管理）

**主要技术栈**:
- **语言**: 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 (价格高地) 的利差。支持视觉寻源与多模态匹配。
- **套利净利引擎**: 统一计算口径 `售价 - 采购 - 平台费 - 物流 - 税费 - 汇率对冲 - 售后损耗 - 广告摊销`。
- **风险门禁**:
  - TOC: 利润率 < 20% 触发风控预警
  - TOB: 利润率 < 15% 禁止报价
  - ROI < 20% 标记为高风险，< 5% 强制拦截
- **SPU/SKU 管理**: 支持独立站 (Shopify/WooCommerce) 与平台电商的多维度属性映射。
- **刊登任务**: 支持无 API 平台 (TikTok/Temu) 模拟执行与官方 API 刊登。
- **多平台商品管理**: 统一管理多平台商品，实现批量操作和跨平台库存同步。

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

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

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

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

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

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

---

## 6. 术语规范参考

本文档遵循 [术语标准化规范](../10_Documents_Global/TERMINOLOGY_STANDARDS.md)，主要术语定义如下：

| 术语 | 说明 |
|-----|------|
| TOC | To Consumer，零售业务 |
| TOB | To Business，企业业务 |
| PIM | 商品管理 (Product Information Management) |
| OMS | 订单管理 (Order Management System) |
| WMS | 库存管理 (Warehouse Management System) |
| FIN | 财务管理 (Financial Management) |
| MKT | 营销管理 (Marketing Management) |

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

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

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

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

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

### 3.13 客户服务与沟通
- **全渠道客户沟通**: 整合多渠道客户沟通，提供智能自动化客服，实现客户精细化管理。
- **智能自动化客服**: AI自动回复常见问题，智能分流与 escalate，个性化回复生成，24/7全天候服务。
- **团队协作管理**: 客服任务分配与管理，内部协作与知识共享，客服绩效监控。
- **客户精细化管理**: 客户画像构建，客户分层与标签，个性化服务策略。
- **跨境沟通适配**: 自动翻译功能，跨文化沟通支持，多语言客服支持。

### 3.14 快速建站与品牌化运营
- **快速建站**: 模板化网站设计，拖拽式页面编辑器，响应式布局适配，多语言支持。
- **品牌化配置**: 品牌标识与视觉设计，品牌故事与内容管理，品牌调性与风格统一。
- **功能集成**: 电商功能集成（商品展示、购物车、支付），营销工具集成（优惠券、促销活动），物流与配送配置，数据分析与报表。
- **品牌推广**: SEO优化，社交媒体集成，内容营销支持，品牌故事传播。

---

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

### 4.1 订单状态机
```
PENDING → PAID → SPLIT → PROCESSING → SHIPPED → COMPLETED → REFUNDED → CANCELLED
```

### 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 系统 | 阶梯价、信用池、询盘管理 |
| **客户服务** | SaleSmartly | 全渠道沟通、智能自动化客服 |

---

## 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)*
