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. 通用响应与状态码

响应格式

{
  "success": true,
  "data": { ... },
  "error": "optional error message"
}

常用状态码

• 200: 成功 | 401: 未授权 | 403: 禁止访问 | 404: 资源不存在 | 500: 服务器错误。