# SFTP 对接实施手册

> 适用于中小买方、测试环境，以及部分国内工厂的供应链协同。
> SFTP 没有传输层回执，业务回执完全依赖 997 文件。

## 1. 目录约定

```
/[PARTNER_CODE]/in/       买方上传给我方的报文
/[PARTNER_CODE]/out/      我方生成、买方拉取的报文
/[PARTNER_CODE]/ack/      997 回执文件
/[PARTNER_CODE]/archive/  已处理文件归档（避免重复消费）
```

- 每个伙伴独立根目录，禁止跨目录访问。
- 目录权限：伙伴账号只读写自己的目录，不能列其他伙伴。

## 2. 认证与账号

- 仅允许 SSH 公钥认证，关闭密码登录。
- 每人/每伙伴独立密钥，禁止共用。
- 建议限制来源 IP（能拿到买方出口 IP 时必做）。
- 服务端指纹提前提供给买方，避免首次连接信任问题。

```bash
# 生成密钥对（发给买方的是公钥）
ssh-keygen -t ed25519 -C "partner-walmart" -f ~/.ssh/walmart_ed25519 -N ""

# 手工连通测试
sftp -i ~/.ssh/walmart_ed25519 -P 22 partner@edi.example.com
```

## 3. 文件命名

统一规则，便于排查与去重：

```
{报文类型}_{YYYYMMDD}_{序号}.txt
850_20261116_00001.txt
856_20261116_00001.txt
997_20261116_00001.txt
```

若买方有自己的命名规范（多数有），以买方为准并记录在本手册末尾。

## 4. 写入与读取的原子性

**这是最容易出问题的地方。**

上传方：
1. 先写 `xxx.txt.tmp`
2. 写完并 flush 后 `rename` 为 `xxx.txt`
3. 绝不直接创建目标文件名后慢慢写

接收方：
1. 只处理不带 `.tmp` 后缀的文件
2. 处理前检查文件大小在短时间内是否稳定（可选）
3. 处理成功后移动到 `archive/`

## 5. 轮询与消费

| 项 | 建议值 |
|---|---|
| 轮询间隔 | 30 秒 |
| 单次批量 | 50 个文件 |
| 失败重试 | 3 次，间隔 1 / 5 / 15 分钟 |
| 归档保留 | 90 天，之后转对象存储 |
| 幂等键 | 文件名 + 控制号 |

## 6. 回执

- 收到报文并处理完成后，立即在 `ack/` 生成对应 997。
- 997 文件名与原报文对应，便于买方匹配。
- 买方拉取 997 视为业务签收；长时间未拉取需人工提醒。

## 7. 常见问题

| 现象 | 排查方向 |
|---|---|
| 连接被拒 | 公钥未配置、账号权限、来源 IP 限制 |
| 上传成功但对方读不到 | 直接写了目标文件名，对方读到半截文件 |
| 重复建单 | 未归档、未做幂等校验 |
| 中文乱码 | 文件含非 ASCII，X12 要求 ASCII |
| 文件被覆盖 | 命名序号重复，需加时间戳或控制号 |

## 8. 安全

- 禁 root 登录，SFTP 使用独立系统账号或容器内虚拟账号。
- 关闭端口转发与 shell 登录（SFTP-only）。
- 定期审计登录日志与文件操作日志。
- 密钥泄露时立即吊销并换新，同步通知买方。

## 9. 上线检查

- [ ] 双方密钥互换并连通
- [ ] 三个目录权限与归属正确
- [ ] 原子写约定已与买方确认
- [ ] 文件命名规则确认并记录
- [ ] 997 生成与归档路径验证
- [ ] 轮询与归档策略已配置
- [ ] 来源 IP 白名单已生效
