# 数据引擎 — 平台与接口配置指南

> 适用版本：HDWL data-engine  
> 阅读对象：实施工程师、运维人员  
> 前置知识：了解 JSON 基本格式即可

---

## 目录

1. [概念说明](#1-概念说明)
2. [平台管理 (api_datasource_platform)](#2-平台管理)
3. [接口管理 (api_interface)](#3-接口管理)
4. [实战：新增一个平台](#4-实战新增一个平台)
5. [常见问题](#5-常见问题)

---

## 1. 概念说明

```
平台 (Platform)  →  对接的第三方系统（如：快手电商、腾讯广告、钉钉）
  └── 接口 (Interface) → 平台提供的具体 API（如：订单列表、商品详情）
        └── 表 (Table) → 数据最终存储的数据库表
```

**举例**：
- **平台** = 快手电商
  - **接口1** = 订单列表 → 数据存入 `kuaishou_order_list` 表
  - **接口2** = 商品列表 → 数据存入 `kuaishou_item_list` 表
  - **接口3** = 售后单列表 → 数据存入 `kuaishou_refund_list` 表

系统会按照配置的**调度周期**，自动拉取每个接口的数据并存入对应的数据库表。

---

## 2. 平台管理

平台配置存储在 `api_datasource_platform` 表中，定义了一个第三方平台的基本信息和认证方式。

### 2.1 基础字段

| 字段 | 类型 | 必填 | 说明 | 示例 |
|------|------|------|------|------|
| `platform_code` | VARCHAR | ✅ | 平台唯一编码，不能重复 | `kuaishou`、`tencent` |
| `platform_name` | VARCHAR | ✅ | 平台显示名称 | `快手电商`、`腾讯广告` |
| `description` | VARCHAR | ❌ | 平台描述 | `快手电商开放平台数据同步` |
| `status` | VARCHAR | ✅ | 状态，`ACTIVE`=启用，`INACTIVE`=停用 | `ACTIVE` |
| `api_base_url` | VARCHAR | ✅ | API 域名，接口地址会拼接在此 URL 后面 | `https://openapi.kwaixiaodian.com` |

### 2.2 认证类型 (auth_type)

| 类型 | 说明 | 适用场景 |
|------|------|----------|
| `TOKEN` | 简单 Token 认证，放在 Header 中 | 内部系统 |
| `API_KEY` | API Key 认证，Token 放在请求参数中 | **快手电商**、钉钉 |
| `OAUTH2` | OAuth 2.0 认证 | 腾讯广告 |
| `SIGN` | 签名认证，使用 appKey + appSecret 签名 | 部分开放平台 |
| `APP_SIGNATURE` | 应用签名认证，基于请求体 MD5 | 钉钉智能薪酬 |

### 2.3 认证配置 (auth_config)

`auth_config` 是一个 **JSON 对象**，根据不同的 `auth_type` 配置不同内容。

#### API_KEY 类型配置（快手电商示例）

```json
{
  "sign_algorithm": "md5",
  "app_key": "ks651333099611149957",
  "app_secret": "JPUXG2CS3I7tqRWbKaLrYQ",
  "sign_secret": "7bc51baab818cf86e121a48d99ff3fe4",
  "token_in_query": true,
  "query_key": "access_token",
  "extra_query_params": {
    "timestamp": "{timestamp_ms}"
  }
}
```

| 字段 | 说明 |
|------|------|
| `sign_algorithm` | 签名算法，可选 `md5`（小写输出）或 `md5_upper`（大写输出）或 `HMAC_SHA256` |
| `app_key` | 平台分配的 AppKey（也叫 AppId、client_id），**快手签名必填** |
| `app_secret` | 平台分配的 AppSecret，用于 OAuth 获取 Token |
| `sign_secret` | 签名专用密钥（**快手特有**），平台分配，在"应用详情"中查看 |
| `token_in_query` | `true`=Token 放在 URL 参数中；`false`=Token 放在 Header 中 |
| `query_key` | Token 的参数名，默认 `access_token` |
| `extra_query_params` | 额外需要拼接的参数，支持 `{timestamp}`（秒）、`{timestamp_ms}`（毫秒）、`{nonce}` 占位符 |

> **快手签名算法**（仅供参考，代码已实现）：
> 1. 所有参数按字母排序，拼接成 `key1=value1&key2=value2&...`
> 2. 末尾追加 `&signSecret=你的signSecret`
> 3. 对整个字符串取 MD5

#### SIGN 类型配置

```json
{
  "sign_algorithm": "md5",
  "app_key": "your_app_key",
  "app_secret": "your_app_secret"
}
```

### 2.4 限流与重试字段

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `rate_limit_per_minute` | INT | 100 | 每分钟最大请求次数，防止触发平台限流 |
| `rate_limit_per_hour` | INT | 3600 | 每小时最大请求次数 |
| `concurrency_limit` | INT | 5 | 并发请求数 |
| `request_timeout_ms` | INT | 30000 | 单次请求超时时间（毫秒） |
| `max_retries` | INT | 3 | 请求失败后的最大重试次数 |
| `retry_delay_ms` | INT | 1000 | 重试间隔（毫秒），每次翻倍 |

### 2.5 Token 与 API Key 字段

| 字段 | 说明 | 快手示例 |
|------|------|----------|
| `token` | 认证 Token / Refresh Token | 快手 OAuth 返回的 `refresh_token` |
| `api_key` | API Key / Access Token | 快手 OAuth 返回的 `access_token` |
| `client_id` | OAuth2 Client ID | 腾讯广告的 client_id |
| `client_secret` | OAuth2 Client Secret | 腾讯广告的 client_secret |

---

## 3. 接口管理

接口配置存储在 `api_interface` 表中，定义了一个平台下每个 API 的请求方式、参数、响应解析规则和存储表结构。

### 3.1 基础字段

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `platform_id` | INT | ✅ | 所属平台的 ID（关联 `api_datasource_platform.id`） |
| `name` | VARCHAR | ✅ | 接口名称，如"订单列表" |
| `code` | VARCHAR | ✅ | 接口编码，唯一标识，如 `order_list` |
| `url` | VARCHAR | ✅ | API 路径，会拼接在平台 `api_base_url` 后面 |
| `method` | VARCHAR | ✅ | HTTP 方法，`GET` 或 `POST` |
| `status` | VARCHAR | ✅ | 状态，`active`=启用，`inactive`=停用 |
| `auth_type` | VARCHAR | ✅ | 认证方式，`inherit`=继承平台配置 |

### 3.2 请求配置 (request_config)

`request_config` 是一个 **JSON 对象**，定义如何构造 API 请求参数。

#### 3.2.1 完整字段说明

```json
{
  "page_param": "cursor",
  "page_size_param": "pageSize",
  "cursor_pagination": true,
  "pagination_mode": "offset",
  "page_size": 50,
  "initial_cursor": "",
  "method": "open.order.cursor.list",
  "version": 1,
  "signMethod": "MD5",
  "time_field": "updateTime",
  "time_field_mode": "range",
  "full_sync_start_time": 1700000000000,
  "queryType": 2,
  "parameters_location": "query",
  "body_wrapper_field": "param",
  "exclude_from_wrapper": ["method", "version", "signMethod"],
  "prefetch": { ... },
  "recursive": { ... },
  "row_inject": ["statisticsMonth"],
  "max_recursive_depth": 20
}
```

#### 3.2.2 分页配置

| 字段 | 说明 | 示例 |
|------|------|------|
| `page_param` | 页码/游标的参数名 | `cursor`、`page`、`offset` |
| `page_size_param` | 每页条数的参数名 | `pageSize`、`page_size` |
| `page_size` | 每页请求条数，覆盖全局配置 | `50` |
| `cursor_pagination` | `true`=游标分页；不配置=普通页码分页 | `true` |
| `pagination_mode` | `offset`=偏移量分页（`offset=(page-1)*size`）；不配置=页码分页 | `offset` |
| `initial_cursor` | 游标分页时的初始游标值，不配则为空字符串 | `""` |

**三种分页模式对比**：

| 模式 | 配置方式 | 适用平台 | 翻页方式 |
|------|----------|----------|----------|
| 游标分页 | `cursor_pagination: true` | 快手、钉钉 | 响应返回 cursor，下次请求带上 |
| 普通分页 | 默认 | 腾讯广告 | 响应返回 totalPages，按页码翻 |
| hasMore 分页 | `has_more_field` 在 response_config | 钉钉 | 响应有 hasMore 字段判断是否有下一页 |

#### 3.2.3 时间过滤配置

用于增量同步——只拉取上次同步之后新增/更新的数据。

| 字段 | 说明 |
|------|------|
| `time_field` | 时间字段名，如 `updateTime`、`createTime` |
| `time_field_mode` | 时间模式：`range`=快手模式(beginTime/endTime)，`filtering`=腾讯模式(filtering 数组) |
| `full_sync_start_time` | 首次全量同步的起始时间戳（**Unix 毫秒**），不配则用全局 `default_lookback_days` |
| `queryType` | 快手专用：`1`=按创建时间查(90天内)，`2`=按更新时间查(240天内) |

> **全局配置** `config.yml` 中 `sync.default_lookback_days` 控制默认回溯天数（默认 89 天）。

#### 3.2.4 业务参数

除了上述系统级字段外，`request_config` 中其他字段都会作为**业务参数**发送给 API。

**快手示例**（`orderViewStatus`、`cpsType`、`sort` 等是业务参数）：
```json
{
  "orderViewStatus": 1,
  "cpsType": 1,
  "sort": 1,
  "pageSize": 50
}
```

#### 3.2.5 body_wrapper_field（快手专用）

快手 API 要求所有业务参数打包成一个 JSON 字符串，放在 `param` 字段中发送。

```json
{
  "body_wrapper_field": "param",
  "exclude_from_wrapper": ["method", "version", "signMethod"]
}
```

**效果**：
- 业务参数 `orderViewStatus=1, pageSize=50, sort=1` → 打包为 `param={"orderViewStatus":1,"pageSize":50,"sort":1}`
- `method`、`version`、`signMethod` 保持在顶层，不被打包

#### 3.2.6 预取配置 (prefetch)

用于需要**先获取实体列表，再逐个查详情**的场景。

```json
{
  "prefetch": {
    "url": "/open/order/cursor/list",
    "method": "GET",
    "response_path": "data.orderList",
    "target_param": "oid",
    "value_field": "oid"
  }
}
```

| 字段 | 说明 |
|------|------|
| `url` | 预取数据的 API 路径 |
| `method` | HTTP 方法 |
| `response_path` | 从响应中提取实体列表的 JSON 路径，如 `data.orderList` |
| `target_param` | 将提取的值传给目标接口时使用的参数名 |
| `value_field` | 从实体中取哪个字段的值，不配则传整个实体对象 |

**工作流程示例**（订单详情）：
1. 先调用 `/open/order/cursor/list` 获取所有订单 ID 列表
2. 对每个订单 ID，调用 `/open/order/detail?oid=xxx` 获取详情
3. 所有详情数据合并存入 `kuaishou_order_detail` 表

#### 3.2.7 递归遍历配置 (recursive)

用于树形结构数据（如钉钉部门树）。

```json
{
  "recursive": {
    "key_field": "dept_id",
    "target_param": "parent_id"
  }
}
```

| 字段 | 说明 |
|------|------|
| `key_field` | 当前节点的 ID 字段名 |
| `target_param` | 传给下级查询的参数名 |
| `max_recursive_depth` | 最大递归深度，默认 20 |

#### 3.2.8 参数位置控制

| 字段 | 说明 |
|------|------|
| `parameters_location` | `query`=参数放 URL 查询字符串；不配=GET 放 URL，POST 放 Body |

#### 3.2.9 字段注入 (row_inject)

如果响应中缺少请求参数中的某些字段，可以用 `row_inject` 注入到每行数据中。

```json
{
  "row_inject": ["statisticsMonth"]
}
```

### 3.3 响应配置 (response_config)

`response_config` 是一个 **JSON 对象**，定义如何解析 API 响应，判断成功/失败，提取数据。

```json
{
  "success_field": "result",
  "success_value": 1,
  "message_field": "error_msg",
  "list_path": "data.orderList",
  "cursor_field": "data.cursor",
  "cursor_end_marker": "nomore",
  "single_record": false,
  "has_more_field": "data.hasMore"
}
```

| 字段 | 说明 | 默认值 |
|------|------|--------|
| `success_field` | 判断成功的字段名 | `code` |
| `success_value` | 成功的值（数字） | `0` |
| `message_field` | 错误消息的字段名 | `message` |
| `list_path` | 数据列表的 JSON 路径，如 `data.orderList` | `data` |
| `cursor_field` | 游标值的 JSON 路径，如 `data.cursor` | 无 |
| `cursor_end_marker` | 游标结束标记，收到此值表示到底 | `nomore` |
| `single_record` | `true`=响应是单条记录(详情接口)，会自动包装成数组 | `false` |
| `has_more_field` | hasMore 分页模式的判断字段路径 | 无 |

#### 成功判断逻辑

```
读取响应的 success_field 字段 → 转成数字 → 和 success_value 比较
相等 = 成功
不相等 = 失败，取 message_field 作为错误消息
```

**快手示例**：`result` 字段值 = `1` 表示成功
**腾讯示例**：`code` 字段值 = `0` 表示成功

#### 数据提取逻辑

```
1. 按 list_path 逐层进入 JSON
2. 最后一段如果是数组 → 直接作为列表
3. 最后一段是对象 → 找对象里的 list/orderList 字段
4. 如果 single_record=true → 将对象包装为单元素数组
5. 每行数据自动展平（子对象字段合并到顶层）
6. 每行附加 raw_data 字段（原始 JSON）
```

### 3.4 表结构定义 (table_definition)

`table_definition` 是 **JSON 对象**，定义目标表的表名、列结构和冲突处理。

```json
{
  "table_name": "kuaishou_order_list",
  "columns": [
    { "name": "oid", "type": "BIGINT", "comment": "订单ID" },
    { "name": "status", "type": "INT", "comment": "订单状态码" },
    { "name": "createTime", "type": "BIGINT", "comment": "创建时间" },
    { "name": "updateTime", "type": "BIGINT", "comment": "更新时间" },
    { "name": "totalFee", "type": "BIGINT", "comment": "总金额(分)" },
    { "name": "buyerNick", "type": "VARCHAR(100)", "comment": "买家昵称" },
    { "name": "itemTitle", "type": "VARCHAR(300)", "comment": "商品标题" }
  ],
  "conflict_keys": ["oid"]
}
```

| 字段 | 说明 |
|------|------|
| `table_name` | 数据库表名，系统会自动创建 |
| `columns` | 列定义数组 |
| `columns[].name` | 列名，**必须与 API 响应中的字段名一致** |
| `columns[].type` | PostgreSQL 数据类型：`BIGINT`、`INT`、`VARCHAR(n)`、`TEXT`、`BOOLEAN`、`JSONB` |
| `columns[].comment` | 列的注释说明 |
| `conflict_keys` | 唯一键，插入时冲突则更新（UPSERT），如 `["oid"]` |

> **自动建表**：系统首次同步时会自动创建表。  
> **自动过滤**：只写入 `columns` 中定义的字段，多余的忽略。  
> **raw_data**：每行会自动附带一个 `raw_data` 字段，保存完整的原始 JSON 响应。

---

## 4. 实战：新增一个平台

以"快手电商"为例，完整步骤：

### 第 1 步：创建平台配置

在 `api_datasource_platform` 表插入一条记录：

```sql
INSERT INTO api_datasource_platform (
  tenant_id, platform_code, platform_name, description, status,
  api_base_url, auth_type, token, api_key, auth_config,
  rate_limit_per_minute, request_timeout_ms, max_retries, retry_delay_ms
) VALUES (
  1,                    -- 租户 ID
  'kuaishou',           -- 平台编码（唯一）
  '快手电商',           -- 名��
  '快手电商开放平台数据同步',
  'ACTIVE',             -- 状态
  'https://openapi.kwaixiaodian.com',  -- API 域名
  'API_KEY',            -- 认证类型
  '你的refresh_token',  -- Token（OAuth 返回）
  '你的access_token',   -- API Key（OAuth 返回）
  '{...}',              -- auth_config（见 2.3 节）
  100, 30000, 3, 1000   -- 限流/超时/重试
);
```

### 第 2 步：创建接口配置

对每个需要同步的 API，在 `api_interface` 表插入一条记录：

```sql
INSERT INTO api_interface (
  tenant_id, platform_id, name, code, url, method, status, auth_type,
  request_config, response_config, table_definition
) VALUES (
  1,
  (SELECT id FROM api_datasource_platform WHERE platform_code='kuaishou'),
  '订单列表',           -- 名称
  'order_list',         -- 编码（唯一）
  '/open/order/cursor/list',  -- API 路径
  'GET',                -- HTTP 方法
  'active',             -- 状态
  'inherit',            -- 认证（继承平台）
  '{...}',              -- request_config（见 3.2 节）
  '{...}',              -- response_config（见 3.3 节）
  '{...}'               -- table_definition（见 3.4 节）
);
```

### 第 3 步：验证

系统启动后会自动：
1. 根据 `table_definition` 创建数据库表
2. 按调度周期拉取数据
3. 写入表中

---

## 5. 常见问题

### Q1：怎么判断数据有没有同步成功？

查看 `sync_tracker` 表，每个接口有一条记录：
- `sync_status` = `success` 表示成功
- `last_sync_time` = 上次同步的时间戳
- 查看 `sync_task_log` 表可以看到每次同步的详细日志

### Q2：怎么修改同步频率？

编辑 `config.yml`：
```yaml
sync:
  sync_interval_minutes: 60   # 改这个，单位分钟
```

### Q3：接口报"签名校验失败"怎么排查？

1. 确认 `app_key`、`app_secret`、`sign_secret` 和快手后台一致
2. 确认 `access_token` 没有过期
3. 确认 `sign_algorithm` 配置正确（快手用 `md5`）
4. 查看日志中的 "签名原文" 和 "签名值"，对比快手官方签名工具的结果

### Q4：想抽取历史数据怎么办？

在接口的 `request_config` 中设置 `full_sync_start_time`（Unix 毫秒时间戳），或修改 `config.yml` 的 `sync.default_lookback_days`。

### Q5：数据重复怎么办？

配置 `table_definition` 中的 `conflict_keys`，系统会用 **UPSERT** 模式（冲突时自动更新，不产生重复数据）。

### Q6：如何停用某个接口？

```sql
UPDATE api_interface SET status = 'inactive' WHERE code = '接口编码';
```

---

> 📅 最后更新：2026-06-16  
> 📝 如有疑问，请联系开发团队

---

## 6. 同步机制说明

### 6.1 同步生命周期

```
第 1 次同步（全量）
  lastSyncTime = 0 → 从 default_lookback_days 天前开始拉取
  时间分片：每 7 天一个分片（如 90 天 ≈ 13 个分片循环）
  完成后：记录 lastSyncTime = 数据中最大的更新时间
                          ↓
第 N 次同步（增量）
  读取 lastSyncTime → beginTime = lastSyncTime
  只拉取上次同步之后新增/更新的数据
  完成后：更新 lastSyncTime
                          ↓
（每隔 sync_interval_minutes 分钟循环一次）
```

### 6.2 配置项

编辑 `config.yml`：

```yaml
sync:
  page_size: 100                  # 每次分页请求条数
  concurrency: 5                  # 同步并发数
  retry_count: 3                  # 最大重试次数
  sync_interval_minutes: 60       # 自动同步间隔（分钟），增量频率
  compensation_interval_seconds: 300  # 失败重试扫描间隔（秒）
  auto_sync_enabled: true         # 是否启用自动同步
  sync_timeout_minutes: 120       # 单次同步超时（分钟）
  default_lookback_days: 89       # 首次全量回溯天数（可按接口覆盖）
  default_tenant_id: 1            # 租户 ID
```

| 配置项 | 说明 | 建议值 |
|--------|------|--------|
| `sync_interval_minutes` | 增量同步频率 | 60（1小时） |
| `default_lookback_days` | 首次全量拉多少天 | 快手限制 90 天内，建议 89 |
| `compensation_interval_seconds` | 失败后多久重试 | 300（5分钟） |
| `auto_sync_enabled` | 是否自动跑 | 生产环境 `true` |

### 6.3 覆盖单个接口的回溯天数

在接口 `request_config` 中加入 `full_sync_start_time`（Unix **毫秒**）

```json
{ "full_sync_start_time": 1769200000000 }
```

### 6.4 查看同步状态

```sql
-- 所有接口的同步状态
SELECT platform_code, interface_code, sync_status, 
       to_timestamp(last_sync_time) AS last_sync_at
FROM sync_tracker ORDER BY platform_code, interface_code;

-- 最近失败记录
SELECT * FROM sync_task_log WHERE status = 'failed' 
ORDER BY start_time DESC LIMIT 20;
```

- `sync_status = 'success'`：上次成功
- `sync_status = 'running'`：正在跑
- `last_sync_time = 0`：还没完成过同步

### 6.5 手动重新全量

把 `last_sync_time` 置 0，下次自动变全量：

```sql
UPDATE sync_tracker SET last_sync_time = 0 
WHERE platform_code = 'kuaishou' AND interface_code = 'order_list';
```

---

> 📅 最后更新：2026-06-16