> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kleep.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SFTP 数据结构

## 1. 简介

本文档描述了在您的专用空间配置完成后，如何在我们的 SFTP 环境中组织您的数据文件——**商品**、**订单**、**退货**及相关数据。

如果您运营多个商店或拥有多个环境（生产、预生产等），请为每个环境创建单独的子文件夹（也可以是不同品牌、不同国家等）。

### 目录结构示例

```
/root_space
    /shop_fr
    /shop_en
    /shop_it
```

***

## 2. 数据传输时间表

数据文件理想情况下应在以下时间段内**每日**传输：

* **凌晨 02:00**
* **凌晨 05:00**

此时间段可确保最佳的处理和数据摄入效果。

***

## 3. 文件组织标准

在每个商店目录中，请创建以下文件夹：

* `products`
* `orders`
* `returns`
* `return_reasons`（可选）
* `misc`（可选）

**说明：**

* `return_reasons` 文件夹用于存放包含额外退货数据（如顾客提供的退货原因）的导出文件。这些导出为可选项。
* `misc` 文件夹可存放杂项文件。如需使用此文件夹，请事先与我们讨论层级结构，以确保兼容性。

每个导出文件应放置在对应文件夹中，并使用带时间戳的文件名进行**零日期标记**。

### 文件名格式示例

```
products_2025-01-15T02-00-00.csv
```

***

## 4. 导出内容要求

每种数据集类型的预期字段、格式和约束的详细规范，请参阅 **数据传输：模板** 文档。

**商品目录导出的关键要求：**

* 导出**所有商品变体**，包括缺货商品
* 包含**最后修改日期**字段，用于增量处理
* 维护完整的变体信息，以支持正确的尺码分析
* 可选择添加停用标志，以控制 Kleep 的显示

请参阅模板以获取全面的字段定义和示例。

***

## 5. 处理跨导出文件的重复数据

记录合理地出现在多个每日导出文件中是正常的。例如，某个退货记录可能在不同文件中多次出现。

我们的摄入系统会自动处理去重，并仅处理每条记录的**最新版本**。

***

## 6. 数据格式规范

所有导出文件应以 **CSV** 格式提供。

不建议使用 Excel 文件（`.xlsx`），因为它们会引入格式不一致问题，并可能使自动化摄入工作流程变得复杂。

* **日期时间：** 使用 ISO 8601 格式：`YYYY-MM-DDTHH:MM:SSZ`，示例：`2025-01-15T14:30:00Z`
* **编码：** 所有文本字段使用 UTF-8 编码，在 CSV 中正确转义特殊字符
* **布尔值：** 使用 `true`/`false`（小写）或 `True`/`False`
* **小数值：** 使用句点（`.`）作为小数分隔符。示例：`129.99` 而非 `129,99`
* **空值：** CSV 中缺失的可选文本字段使用空字符串，JSON 中使用 null

### 文件命名规范

***

如 SFTP 数据结构文档中所述，请使用以下格式：

```
{data_type}_{timestamp}.csv
```

示例：

* `products_2025-01-15T02-00-00.csv`
* `orders_2025-01-15T02-00-00.csv`
* `returns_2025-01-15T02-00-00.csv`

***

## 7. 导出历史数据

如果您需要提供**历史数据**（即不属于每日导出的数据），您可以导出所有数据类型最多**一年的历史记录**，包括：

* **商品**
* **订单**
* **退货**

历史数据集可以**通过 SFTP** 传输，或者如果更方便，也可以**通过另一种商定的方式**传输。

# 完整 SFTP 结构示例

```
/root_space
    /shop_fr
        /products
            products_2025-01-15T02-00-00.csv
            products_2025-01-16T02-00-00.csv
        /orders
            orders_2025-01-15T02-00-00.csv
            orders_2025-01-16T02-00-00.csv
        /returns
            returns_2025-01-15T02-00-00.csv
            returns_2025-01-16T02-00-00.csv
        /return_reasons
            return_reasons_2025-01-15T02-00-00.csv  (optional)
        /misc
            (optional, please discuss hierarchy with us)

    /shop_en
        /products
        /orders
        /returns
        /return_reasons
        /misc

    /shop_it
        /products
        /orders
        /returns
        /return_reasons
        /misc

```

***