makemd/docs/02_Backend/API_Specs/Data_API_Specs.md

# 📊 Data & API Specifications (Crawlful Hub)

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

---

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

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

### 1.2 数据库安全约束
- **⚠️ 严禁**: 代码中执行 `DROP`, `TRUNCATE` 等破坏性操作
- **幂等性**: 所有建表语句必须使用 `db.schema.hasTable` 前置校验
- **JSON 处理**: images/skus/attributes 入库前序列化，出库解析
- **唯一约束**: `cf_product` 表必须保证 (platform, productId) 唯一

### 1.3 核心表定义

#### 1.3.1 租户与用户

**cf_tenant** (租户表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | 租户ID |
| name | string | 租户名称 |
| quota | json | 配额配置 |
| status | string | 状态 |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

**cf_user** (用户表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | 用户ID |
| email | string | 邮箱 |
| password_hash | string | 密码哈希 |
| role | enum | ADMIN/MANAGER/OPERATOR/FINANCE/SOURCING/LOGISTICS/ANALYST |
| tenant_id | string(FK) | 租户ID |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

#### 1.3.2 店铺与商品

**cf_shop** (店铺表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | 店铺ID |
| tenant_id | string(FK) | 租户ID |
| platform | enum | AMAZON/EBAY/SHOPEE/TIKTOK/TEMU/1688 |
| platform_shop_id | string | 平台店铺ID |
| name | string | 店铺名称 |
| auth_token | encrypted | 授权Token(加密存储) |
| status | string | 状态 |
| **trace_id** | string | 链路追踪ID |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

**cf_product** (商品主表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | 商品ID |
| tenant_id | string(FK) | 租户ID |
| shop_id | string(FK) | 店铺ID |
| platform | enum | 平台类型 |
| platform_product_id | string | 平台商品ID |
| title | string | 商品标题 |
| description | text | 商品描述 |
| images | json | 图片列表(JSON数组) |
| category | string | 类目 |
| status | string | 状态 |
| **trace_id** | string | 链路追踪ID |
| **business_type** | enum | TOC/TOB |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |
| **唯一约束**: (platform, platform_product_id) |

**cf_product_sku** (SKU变体表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | SKU ID |
| tenant_id | string(FK) | 租户ID |
| shop_id | string(FK) | 店铺ID |
| product_id | string(FK) | 商品ID |
| sku_code | string | SKU编码 |
| attributes | json | 属性JSON(颜色/尺寸等) |
| cost_price | decimal(10,2) | 成本价 |
| retail_price | decimal(10,2) | 零售价 |
| weight_kg | decimal(8,3) | 重量(kg) |
| length_cm | decimal(8,2) | 长度(cm) |
| width_cm | decimal(8,2) | 宽度(cm) |
| height_cm | decimal(8,2) | 高度(cm) |
| **trace_id** | string | 链路追踪ID |
| **business_type** | enum | TOC/TOB |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

#### 1.3.3 订单与库存

**cf_inventory** (库存表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | 库存ID |
| tenant_id | string(FK) | 租户ID |
| shop_id | string(FK) | 店铺ID |
| sku_id | string(FK) | SKU ID |
| warehouse_id | string | 仓库ID |
| total_qty | int | 总数量 |
| available_qty | int | 可用数量 |
| reserved_qty | int | 预留数量 |
| **trace_id** | string | 链路追踪ID |
| **business_type** | enum | TOC/TOB |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

**cf_consumer_orders** (C端订单表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | 订单ID |
| tenant_id | string(FK) | 租户ID |
| shop_id | string(FK) | 店铺ID |
| platform | enum | 平台类型 |
| platform_order_id | string | 平台订单号 |
| total_amount | decimal(10,2) | 总金额 |
| currency | string | 币种 |
| profit | decimal(10,2) | 利润 |
| profit_margin | decimal(5,2) | 利润率(%) |
| status | string | 订单状态 |
| **trace_id** | string | 链路追踪ID |
| **task_id** | string | 任务ID |
| **business_type** | enum | TOC/TOB |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

**cf_order_item** (订单项表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | 订单项ID |
| order_id | string(FK) | 订单ID |
| sku_id | string(FK) | SKU ID |
| unit_price | decimal(10,2) | 单价 |
| quantity | int | 数量 |
| created_at | datetime | 创建时间 |

#### 1.3.4 供应链与财务

**cf_supplier** (供应商表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | 供应商ID |
| tenant_id | string(FK) | 租户ID |
| name | string | 供应商名称 |
| contact | json | 联系方式 |
| rating | decimal(3,2) | 评分 |
| status | string | 状态 |
| **trace_id** | string | 链路追踪ID |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

**cf_purchase_order** (采购订单表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | 采购单号 |
| tenant_id | string(FK) | 租户ID |
| supplier_id | string(FK) | 供应商ID |
| total_amount | decimal(10,2) | 总金额 |
| status | string | 状态 |
| **trace_id** | string | 链路追踪ID |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

**cf_finance_reconciliation** (财务对账表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | 对账ID |
| tenant_id | string(FK) | 租户ID |
| shop_id | string(FK) | 店铺ID |
| period | string | 对账周期 |
| total_sales | decimal(12,2) | 总销售额 |
| total_profit | decimal(12,2) | 总利润 |
| variance_status | string | 差异状态 |
| **trace_id** | string | 链路追踪ID |
| created_at | datetime | 创建时间 |
| updated_at | datetime | 更新时间 |

#### 1.3.5 审计日志

**cf_audit_log** (审计日志表)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | string(PK) | 日志ID |
| tenant_id | string | 租户ID |
| shop_id | string | 店铺ID |
| task_id | string | 任务ID |
| trace_id | string | 链路追踪ID |
| business_type | enum | TOC/TOB |
| action | string | 操作类型 |
| entity_type | string | 实体类型 |
| entity_id | string | 实体ID |
| old_values | json | 旧值 |
| new_values | json | 新值 |
| user_id | string | 操作用户ID |
| ip_address | string | IP地址 |
| created_at | datetime | 创建时间 |

### 1.4 五元组追踪字段说明

所有业务表必须包含以下追踪字段：

| 字段 | 类型 | 说明 | 必填 |
|------|------|------|------|
| tenant_id | string | 租户ID - 业务隔离 | ✅ |
| shop_id | string | 店铺ID - 平台/店铺隔离 | ✅ (店铺相关表) |
| task_id | string | 任务ID - 任务追踪 | ✅ (异步任务) |
| trace_id | string | 链路追踪ID - 全链路唯一 | ✅ |
| business_type | enum | TOC/TOB | ✅ |

---

## 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`: 服务器错误。