wurenzhi
72cd7f6f45
删除不再需要的归档文件和过时的文档模板，包括多个README、安全策略、前端集成蓝图等文件，同时移除了未使用的业务文档和项目结构文件。 优化项目结构，移除冗余文件，保持代码库整洁。主要删除archive/handover目录下的多个文件及doc目录下的部分文档模板。
247 lines
11 KiB
Markdown
247 lines
11 KiB
Markdown
# 🏢 Business Blueprint (Crawlful Hub)
|
||
|
||
> **定位**：Crawlful Hub 业务核心蓝图 - 包含项目目标、技术栈、核心业务模块、功能规格、状态机及行业标杆参考。
|
||
> **更新日期**: 2026-03-17
|
||
|
||
---
|
||
|
||
## 1. 项目概述 (Project Overview)
|
||
|
||
**项目名称**: Crawlful Hub (跨境电商增长中台)
|
||
|
||
**项目目标**:
|
||
- 实现多渠道电商运营管理（TOC/TOB）。
|
||
- 提供从商品采集到财务对账的完整业务闭环。
|
||
- 提升跨境贸易运营效率与利差套利能力。
|
||
|
||
**主要技术栈**:
|
||
- **语言**: 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)*
|