# 📊 Data & API Specifications (Crawlful Hub)

> **定位**：Crawlful Hub 数据架构与接口规格书 - 包含数据库 Schema、核心业务流程及全量 API 定义。
> **更新日期**: 2026-03-17

---

## 1. 数据库结构 (Data Schema)

### 1.1 命名规范
- **表前缀**: `cf_` (crawlful)
- **字段命名**: snake_case
- **金額字段**: `decimal(10,2)` 或更高精度。
- **物理单位**: 长度 (cm), 重量 (kg), 体积 (m³)。

### 1.2 核心表定义

#### 租户与用户
- `cf_tenant`: 租户 ID、名称、配额、状态。
- `cf_user`: 邮箱、密码哈希、角色 (ADMIN/MANAGER 等)、租户 ID。

#### 店铺与商品
- `cf_shop`: 租户 ID、平台 (AMAZON/TIKTOK 等)、授权 Token。
- `cf_product`: 租户 ID、源平台 ID、标题、描述、JSON 图片列表。
- `cf_product_sku`: SKU 编码、属性 JSON、成本价、零售价、重量/尺寸。

#### 订单与库存
- `cf_inventory`: SKU ID、仓库 ID、总数量、可用/预留数量。
- `cf_order`: 平台订单号、总金额、货币、利润/利润率、状态。
- `cf_order_item`: 订单项、SKU ID、单价、数量。

#### 供应链与财务
- `cf_supplier`: 供应商名称、联系方式、评分、状态。
- `cf_purchase_order`: 采购单号、供应商 ID、总金额、状态。
- `cf_finance_reconciliation`: 对账周期、总销售/利润、差异状态。

---

## 2. 核心业务流程 (Business Processes)

### 2.1 商品采集与刊登 (Collection & Listing)
1. **采集**: 用户输入 URL → Extension 解析 DOM → 发送至 Hub 草稿箱。
2. **刊登**: 选择草稿 → 平台适配器转换字段 → 调用平台 API 发布 → 记录刊登历史。

### 2.2 订单履约与财务 (Fulfillment & Finance)
1. **订单**: 平台 Webhook 推送 → 解析并入库 → 利润审计 (红线校验) → 状态流转。
2. **库存**: 平台同步 → 更新本地库存 → 低于阈值自动触发补货提醒。
3. **对账**: 拉取平台账单 → 自动差异匹配 → 生成报告 → 人工审核异常项。

---

## 3. 全量 API 端点映射 (API Map)

### 3.1 基础管理
- `POST /api/auth/login`: 用户登录。
- `GET /api/users`: 获取用户列表。
- `GET /api/shops`: 获取授权店铺。

### 3.2 商品与库存 (Product & Inventory)
- `GET /api/products`: 获取商品列表。
- `POST /api/products/publish`: 发布商品到平台。
- `GET /api/inventory/aging`: 库存老化分析。
- `GET /api/inventory/forecast`: 库存预测。

### 3.3 订单与支付 (Order & Payment)
- `GET /api/orders`: 获取订单列表。
- `PUT /api/orders/:id/status`: 更新订单状态。
- `POST /api/payments`: 创建支付订单。
- `POST /api/payments/callback`: 处理支付回调。

### 3.4 财务管理 (Finance)
- `GET /api/finance/reconciliation`: 财务对账。

---

## 4. 通用响应与状态码

### 响应格式
```typescript
{
  "success": true,
  "data": { ... },
  "error": "optional error message"
}
```

### 常用状态码
- `200`: 成功 | `401`: 未授权 | `403`: 禁止访问 | `404`: 资源不存在 | `500`: 服务器错误。