wurenzhi
136c2fa579
- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
89 lines
3.0 KiB
Markdown
89 lines
3.0 KiB
Markdown
# 📊 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`: 服务器错误。
|