# Crawlful Hub

> 全自动化跨境电商运营平台 | AI驱动 | 多平台集成

---

## 项目简介

Crawlful Hub 是一个全自动化的跨境电商运营平台，集成了商品管理、订单处理、物流策略、广告营销、B2B贸易等核心功能，通过 AI 技术实现智能决策和自动化运营。

### 核心特性

- � **多平台统一管理** - 支持 TikTok、Shopee、Shopify、Amazon 等 12+ 平台
- 🤖 **AI 智能决策** - 自动调价、智能选品、广告优化
- 📊 **全链路追踪** - 五元组追踪体系，确保数据一致性
- 🔐 **企业级安全** - RBAC 权限模型，租户隔离

---

## 快速导航

| 文档类型 | 路径 | 说明 |
|---------|------|------|
| 📋 **任务中心** | [TASKS/](docs/TASKS/_index.md) | P0/P1/P2 任务列表与进度 |
| 📐 **架构设计** | [ARCH/](docs/ARCH/_index.md) | 系统架构、领域模型、服务地图 |
| 📖 **规则规范** | [RULES/](docs/RULES/_index.md) | 数据库、API、安全、TypeScript 规范 |
| 🔧 **服务文档** | [SERVICES/](docs/SERVICES/_index.md) | 各业务服务设计文档 |
| 🔗 **业务闭环** | [LOOPS/](docs/LOOPS/_index.md) | 商品、订单、营销等闭环文档 |
| 📚 **API 文档** | [API_Documentations/](docs/API_Documentations/) | 各平台 API 集成文档 |

---

## 核心功能

### 1. 商品管理 (PIM)
- 商品刊登与映射
- 库存同步与管理
- 商品健康度监控
- AI 智能定价

### 2. 订单管理 (OMS)
- 多平台订单集中管理
- 订单履约与异常处理
- 批量订单处理
- 自动化发货

### 3. 营销管理 (MKT)
- 广告计划创建与管理
- 投放效果分析
- ROI 优化
- GMV Max 自动化

### 4. 财务管理 (FIN)
- 多平台对账
- 利润计算与分析
- 成本核算
- 风控预警

### 5. B2B 贸易
- 企业报价管理
- 批量订单处理
- 合同管理
- 利润红线控制

### 6. 售后逆向
- 退货申请处理
- 退款流程管理
- 客户服务

### 7. 合规与证书
- 证书管理与过期提醒
- 合规检查
- 平台资质管理

---

## 项目架构

### 技术栈

| 层级 | 技术 |
|------|------|
| **前端** | React 18, TypeScript, UmiJS 4, Tailwind CSS, Ant Design |
| **后端** | Node.js 18+, Express, TypeScript |
| **数据库** | MySQL 8.0 (阿里云 RDS) |
| **缓存** | Redis 6.0 |
| **队列** | BullMQ |
| **自动化** | Playwright |
| **AI** | 多 AI 服务集成 |

### 模块结构

```
makemd/
├── dashboard/          # 前端管理控制台
├── server/             # 后端服务
├── node-agent/         # 节点代理 (Playwright 自动化)
├── scripts/            # 脚本工具
├── docs/               # 项目文档
│   ├── TASKS/          # 任务中心
│   ├── ARCH/           # 架构设计
│   ├── RULES/          # 规则规范
│   ├── SERVICES/       # 服务文档
│   ├── LOOPS/          # 业务闭环
│   └── API_Documentations/  # API 文档
└── .trae/              # AI 协作配置
```

---

## 快速开始

### 环境要求

- Node.js 16+
- MySQL 8.0+
- Redis 6.0+

### 安装依赖

```bash
# 后端依赖
cd server && npm install

# 前端依赖
cd ../dashboard && npm install

# Node Agent 依赖
cd ../node-agent && npm install
```

### 数据库初始化

```bash
mysql -u root -p < scripts/db-init.sql
```

### 启动服务

```bash
# 后端服务
cd server && npm run dev

# 前端服务
cd dashboard && npm run dev

# Node Agent
cd node-agent && npm run dev
```

---

## 开发规范

### 代码规范

- 遵循 TypeScript 最佳实践
- 使用 ESLint 进行代码检查
- 提交前运行 `npm run check` 进行类型检查
- 所有业务逻辑必须在 Service 层实现

### 提交规范

- 提交信息使用中文描述
- 提交前确保代码通过测试
- 大型功能提交前创建分支

### 核心约束

```typescript
// 数据库
表前缀: 'cf_'           // cf_product, cf_order
金额类型: decimal(10,2)  // 禁止 float/double

// 业务类型
TOC: 零售/C端
TOB: 企业/B端
// 禁止使用 B2C/B2B

// 利润红线
TOB利润率 < 15%: 禁止报价
TOC利润率 < 20%: 触发风控预警
```

---

## 文档索引

### 规则文档

| 文档 | 说明 |
|------|------|
| [术语标准](docs/RULES/TERMINOLOGY.md) | 标准术语、命名规范 |
| [数据库规则](docs/RULES/database.md) | 表命名、字段类型 |
| [API 规则](docs/RULES/api.md) | 路由、权限、响应格式 |
| [安全规则](docs/RULES/security.md) | RBAC、数据隔离 |
| [TypeScript 规则](docs/RULES/typescript.md) | 类型定义、编译 |
| [业务规则](docs/RULES/business.md) | 利润红线、决策流程 |
| [协作规则](docs/RULES/collaboration.md) | AI 协作、任务领取 |

### 架构文档

| 文档 | 说明 |
|------|------|
| [系统架构](docs/ARCH/system.md) | 整体架构设计 |
| [领域模型](docs/ARCH/domain.md) | 核心领域设计 |
| [服务地图](docs/ARCH/backend.md) | 服务依赖关系 |
| [状态机](docs/ARCHIVE/01_Architecture/06_State_Machine.md) | 状态流转定义 |

---

## 许可证

MIT License