feat: 初始化项目结构并添加核心功能模块
- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
This commit is contained in:
115
docs11/01-business-core/business-blueprint.md
Normal file
115
docs11/01-business-core/business-blueprint.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# 🏢 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 Modules)
|
||||
|
||||
### 2.1 闭环总览 ⭐⭐⭐
|
||||
|
||||
#### 闭环验收标准 (P0)
|
||||
- **商品刊登闭环**: ERP 商品 → 平台可售。要求全链路追踪 (traceId)。
|
||||
- **订单履约闭环**: 平台订单 → 妥投。状态机完整，异常可介入。
|
||||
- **售后逆向闭环**: 售后请求 → 退款完成。状态流转清晰。
|
||||
- **资金对账闭环**: platform 结算流水 → 差异关闭。汇率明确，可回溯。
|
||||
- **合规风控闭环**: 风险信号 → 拦截/复核。审计留痕。
|
||||
|
||||
#### 追踪四元组 (Tracking Quad)
|
||||
- `tenantId`: 租户 ID (业务隔离)
|
||||
- `shopId`: 店铺 ID (平台/店铺隔离)
|
||||
- `taskId`: 任务 ID (任务/规则触发归档)
|
||||
- `traceId`: 链路追踪 ID (全链路唯一标识)
|
||||
|
||||
### 2.2 模块功能详述
|
||||
|
||||
#### 1. 商品管理 (PIM) & 跨平台套利 (Arbitrage)
|
||||
- **跨平台套利雷达**: 自动识别 1688 (价格洼地) 与 Amazon/Temu/eBay (价格高地) 的利差。支持视觉寻源与多模态匹配。
|
||||
- **套利净利引擎**: 统一计算口径 `售价 - 采购 - 平台费 - 物流 - 税费 - 汇率对冲 - 售后损耗 - 广告摊销`。
|
||||
- **风险门禁**: B2C 利润率 < 20% 触发预警，利润率 < 15% 或 ROI < 20% 标记为高风险，< 5% 强制拦截。
|
||||
- **SPU/SKU 管理**: 支持独立站 (Shopify/WooCommerce) 与平台电商的多维度属性映射。
|
||||
- **刊登任务**: 支持无 API 平台 (TikTok/Temu) 模拟执行与官方 API 刊登。
|
||||
|
||||
#### 2. 订单管理 (OMS) & TOB 业务
|
||||
- **多渠道归集**: 聚合平台订单与独立站 (DTC) 订单。
|
||||
- **TOB 报价红线**: B2B 利润率 < 15% 严禁报价，支持大宗贸易的阶梯价设置与询盘转化。
|
||||
- **分账引擎**: 针对 TOB 业务支持主权级信用池 (Sovereign Credit Pool) 与跨境结算审计。
|
||||
- **利润核算**: 实时计算单笔订单净利，关联广告支出实现全链路 ROI 溯源。
|
||||
|
||||
#### 3. 库存与仓储 (WMS)
|
||||
- **多仓协同**: 实时同步全球多仓库存，支持独立站与平台库存共享/隔离策略。
|
||||
- **补货算法**: `(销量预测 * 采购周期 + 安全库存 - 在途)`。支持基于利差热力图的智能补货决策。
|
||||
- **入/出库流**: ASN 预报、QC 质检、波次拣货。
|
||||
|
||||
#### 4. 财务与结算
|
||||
- **成本归集**: 采购、头程/尾程物流、佣金、广告。
|
||||
- **多币种对账**: ZKP 隐私审计，自动差异匹配。
|
||||
- **汇率避险**: 联动多币种汇率避险接口，锁定汇率风险，记录汇兑损益。
|
||||
|
||||
#### 5. 营销与广告 (MKT)
|
||||
- **跨平台投放**: 统一管理 Facebook, Google, TikTok 广告。
|
||||
- **独立站 DTC 策略**: 针对独立站流量进行全链路归因分析 (Multi-touch Attribution)。
|
||||
- **动态优化**: 基于 ROAS 自动调整预算，监控盈亏平衡点 (Break-even ROAS)。
|
||||
- **套利闭环回流**: 从选品建议到真实销量回流，持续迭代套利策略。
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键业务状态机 (State Machines)
|
||||
|
||||
### 3.1 订单状态机
|
||||
- `PULLED` → `PENDING_REVIEW` → `CONFIRMED` → `ALLOCATED` → `READY_TO_SHIP` → `SHIPPED` → `DELIVERED` → `CLOSED`
|
||||
|
||||
### 3.2 业务审核状态机
|
||||
- `SUBMITTED` (提交) → `PENDING_REVIEW` (人工审核) → `EXECUTED` / `REJECTED`
|
||||
|
||||
---
|
||||
|
||||
## 4. 行业标杆复刻方案 (Benchmarks)
|
||||
|
||||
- **ERP 系统**: 像素级还原易仓、店小秘核心逻辑。
|
||||
- **TikTok 运营**: 实现 91 妙手同级的无 API 履约与采集能力。
|
||||
- **数据分析**: 船长 BI 级的数据归集与可视化看板。
|
||||
|
||||
---
|
||||
|
||||
## 5. 项目结构与目录映射 (Directory Map)
|
||||
|
||||
```
|
||||
project
|
||||
├─ .trae/rules/ # 编码与项目特定规则
|
||||
├─ docs/ # 分类文档 (业务、数据、架构、规范、质量)
|
||||
├─ server/src/ # 后端服务 (api, service, repository, domains, workers)
|
||||
├─ extension/src/ # 浏览器插件 (background, content)
|
||||
├─ console/src/ # 前端控制台 (pages, components, services, stores)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 实施指南摘要 (Implementation Guides)
|
||||
|
||||
### 6.1 TOC 加速架构
|
||||
- **快速上线**: 提供 Amazon/AliExpress 基础订单同步。
|
||||
- **ConsumerOrderService**: 专责 TOC 订单流。
|
||||
|
||||
### 6.2 非 SaaS 多租户隔离
|
||||
- **数据独占**: `tenant_id` 逻辑隔离，行级安全校验。
|
||||
- **资源配额**: 严格限制并发 Worker 与 API 速率。
|
||||
77
docs11/01-business-core/业务9.md
Normal file
77
docs11/01-business-core/业务9.md
Normal file
@@ -0,0 +1,77 @@
|
||||
|
||||
---
|
||||
|
||||
## 9. 套利与定价分析 (ARB / Pricing) — TOC + TOB + 汇率支持
|
||||
|
||||
### 核心定位
|
||||
|
||||
* **零售（TOC） + 批发/整柜（TOB）套利分析**
|
||||
* 覆盖 **生产 → 拿货 → 平台销售**全链路
|
||||
* 支持 **定价推荐、ROI 模拟、利润预测、汇率自动换算**
|
||||
* 支持跨国、跨仓、多币种利润计算
|
||||
|
||||
### 核心功能
|
||||
|
||||
1. **成本与利润测算**
|
||||
|
||||
* 支持 **固定成本与浮动成本**组合（采购、生产、物流、平台费、广告、关税等）
|
||||
* **汇率换算**：自动获取实时汇率，将外币成本/售价换算成目标结算币种
|
||||
* 输出每 SKU 或整柜商品 **售价/ROI/签收利润**
|
||||
|
||||
2. **定价推荐与模拟**
|
||||
|
||||
* 自动推荐售价区间以满足目标毛利率或 ROI 红线
|
||||
* 支持多币种定价、不同平台价格差异
|
||||
* 可以模拟不同库存、销量、物流方式和汇率波动下的利润
|
||||
|
||||
3. **套利机会发现**
|
||||
|
||||
* **跨平台零售套利**：采集价格或手动录入成本分析价差
|
||||
* **跨阶段 TOB 套利**：生产采购成本 vs 批发/整柜售价
|
||||
* **跨国家 / 跨仓套利**：结合汇率、关税、仓储成本、物流费用计算净利润
|
||||
|
||||
4. **供应链阶段利润分析**
|
||||
|
||||
* **生产阶段**：原材料采购、工厂成本、生产周期成本
|
||||
* **拿货阶段**：整柜成本、运输成本、报关费用、税费（多币种换算）
|
||||
* **零售阶段**：平台费用、广告投入、物流派送、售后成本
|
||||
|
||||
5. **多维度分析报表**
|
||||
|
||||
* 商品维度、阶段维度、平台 / 渠道维度、时间维度
|
||||
* 汇率敏感性分析：利润随汇率变化的浮动曲线
|
||||
|
||||
---
|
||||
|
||||
### 业务流示意（文字版）
|
||||
|
||||
```text
|
||||
生产阶段 / 原材料采购（支持多币种）
|
||||
│
|
||||
▼
|
||||
拿货 / 整柜阶段（FCL/TOB）
|
||||
│
|
||||
▼
|
||||
套利分析模块（TOB + TOC + 汇率换算）
|
||||
├─ 成本测算（固定/浮动/汇率调整）
|
||||
├─ 定价推荐 & ROI 模拟
|
||||
├─ 跨平台 / 跨阶段套利机会
|
||||
└─ 汇率敏感性分析 & 全链路利润报表
|
||||
│
|
||||
▼
|
||||
商品刊登 / 调价执行（多平台 / 多币种）
|
||||
│
|
||||
▼
|
||||
OMS / WMS / 财务 / 营销全链路闭环
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
💡 **特点说明**
|
||||
|
||||
* 汇率处理贯穿 **TOB 和 TOC 全链路**
|
||||
* 支持多币种采购、整柜成本、平台销售价格统一计算
|
||||
* 可进行 **利润随汇率波动的敏感性分析**，为定价策略提供数据支持
|
||||
* 套利模块成为全链路利润智能分析引擎，同时支撑 **零售、批发、整柜、跨国贸易**
|
||||
|
||||
---
|
||||
Reference in New Issue
Block a user