DDI 接入规范

1. 文档目的

接收端只负责原始字节的可靠保全和交付元数据登记，不解析 Excel、CSV 或其他业务文件的列，也不修改文件内容。业务字段、查询条件和导出行数由发送端负责记录。

2. 接口定义

项目	规范
方法	`POST`
地址	`https://<接收端域名>/api/v1/ingest`
请求体	单个文件的原始二进制字节流
发送端鉴权	不需要管理员令牌；令牌只用于管理员网页和下载接口
中文编码	HTTP 元数据使用 UTF-8；中文头值使用 `encodeURIComponent`

一次请求只代表一个文件。一次业务采集有多个文件时，为每个文件分别发送请求，并让它们共享同一个 X-DDI-Batch-ID。

3. 请求头

Header	要求	内容
`Content-Type`	应传	文件 MIME 类型；未知时使用 `application/octet-stream`
`Content-Length`	应传	原始请求体字节数，必须与本地文件大小一致
`X-DDI-Source`	应传	发送端或适配器名称
`X-DDI-Company`	应传	商业全称，中文先 URL 编码
`X-DDI-Batch-ID`	应传	本次采集唯一标识，同批文件保持一致
`X-DDI-Filename`	应传	原始文件名，中文先 URL 编码
`X-DDI-Data-Type`	应传	纯销、购进、配送、库存等业务类型
`X-DDI-Sent-At`	可选	发送端 ISO 8601 时间，用于日志排查

4. 成功响应

成功返回 201 Created 和 JSON：

{
  "id": "服务器生成的文件标识",
  "receivedAt": "2026-09-07T05:33:02.123Z",
  "byteSize": 184320,
  "chunkCount": 1,
  "storage": "d1-chunks"
}

发送端至少记录 HTTP 状态、id、receivedAt、文件名、字节数和本地 SHA-256。

5. 错误处理与重试

状态	处理动作
`201`	文件已完整写入，结束本文件发送
`400`	修正空请求体或无效参数后再发送，不要盲目重试
`413`	拆分文件或联系管理员确认服务限制
`502/503`	保留本地文件，按 5 秒、15 秒、45 秒最多重试 3 次
网络超时	不要删除本地文件，先核对后台是否已经存在

接收端当前按请求生成独立文件，不保证跨请求幂等。补发文件应使用新批次，并在发送端日志中记录补发原因。

6. PowerShell 示例

$file = Get-Item '.\纯销_20260907.csv'
$headers = @{
  'Content-Type' = 'text/csv; charset=utf-8'
  'Content-Length' = [string]$file.Length
  'X-DDI-Source' = 'SHYBYF DDI'
  'X-DDI-Company' = [uri]::EscapeDataString('洛阳宝神鹿大药房有限公司')
  'X-DDI-Batch-ID' = 'LUOYANG-20260907-001'
  'X-DDI-Filename' = [uri]::EscapeDataString($file.Name)
  'X-DDI-Data-Type' = [uri]::EscapeDataString('纯销')
}
Invoke-RestMethod -Method Post -Uri 'https://your-domain.example/api/v1/ingest' -Headers $headers -InFile $file.FullName

7. 接入验收清单

文件上传前能读取本地文件大小和 SHA-256。
请求体是原始二进制，不是 JSON、Base64 或表单包装。
同一采集轮次的所有文件共享一个 X-DDI-Batch-ID。
只有 HTTP 201 才写入“已送达”。
后台可以看到文件数量、文件名、大小和批次。
下载单文件和整批 ZIP 后，SHA-256 与发送端原文件一致。

8. 安全说明

管理员令牌只配置在接收端环境变量 ADMIN_API_TOKEN，不要写入发送端脚本、URL、Git 仓库或截图。正式环境必须通过 HTTPS 访问。

← 返回 DDI 接收端