# EDI 服务技术规范（内部开发版）

> 面向研发与运维。描述模块划分、状态机、数据模型、重试与安全约束。

## 1. 架构

```
买方 EDI 系统
   │ HTTPS(AS2) / SSH(SFTP) / OFTP2
入口层  Caddy / Nginx（TLS 终止、WAF、IP 白名单）
   │
Axum EDI 服务（Rust）
   ├─ AS2 Handler：验签、解密、MDN
   ├─ SFTP Worker：目录轮询、原子写
   ├─ X12 引擎：解析、生成、校验
   ├─ 映射引擎：模板驱动
   └─ 内部 API：对接 ERP
   │
Redis（任务队列、重试）  PostgreSQL（伙伴、模板、报文）  OSS（归档）
```

设计原则：报文翻译与传输解耦；传输可替换；伙伴配置化；服务无状态可横向扩展
（同步 MDN 场景建议单实例或会话粘滞）。

## 2. 技术栈

| 层 | 选型 |
|---|---|
| 服务 | Rust + Axum |
| 队列 | Redis（延迟队列 + 重试） |
| 数据库 | PostgreSQL |
| SFTP | SFTPGo（独立容器） |
| 归档 | 对象存储 OSS |
| 反代 | Caddy / Nginx |
| 密钥 | KMS 托管 AS2 私钥 |

## 3. 报文状态机

```rust
pub enum DocStatus {
    Received,      // 已接收，待解析
    Parsed,        // 解析成功
    ParseFailed,   // 解析失败（记录段与元素错误）
    Queued,        // 出站待发送
    Sent,          // 已发出，等待回执
    AckOk,         // 收到 997 Accept / MDN Success
    AckReject,     // 收到拒绝回执
    AckTimeout,    // 回执超时，重试耗尽
}
```

流转：`Received → Parsed → (业务处理) → Queued → Sent → AckOk / AckReject / AckTimeout`

## 4. 核心表

```sql
CREATE TABLE edi_partner (
  id            BIGSERIAL PRIMARY KEY,
  code          VARCHAR(64) UNIQUE NOT NULL,
  name          VARCHAR(128),
  transport     VARCHAR(16),      -- AS2 / SFTP
  as2_id        VARCHAR(64),
  as2_url       VARCHAR(256),
  peer_cert     TEXT,             -- 对方公钥证书
  our_key_ref   VARCHAR(128),     -- KMS 密钥引用，不存明文
  sftp_host     VARCHAR(128),
  sftp_port     INT,
  dir_in        VARCHAR(256),
  dir_out       VARCHAR(256),
  is_test       BOOLEAN DEFAULT TRUE,
  cert_expire   DATE
);

CREATE TABLE edi_template (
  id            BIGSERIAL PRIMARY KEY,
  partner_id    BIGINT REFERENCES edi_partner(id),
  message_type  VARCHAR(16),      -- 850 / 855 / 856 / 810 / 997
  version       VARCHAR(16),      -- 005010
  mapping       JSONB NOT NULL
);

CREATE TABLE edi_document (
  id            BIGSERIAL PRIMARY KEY,
  partner_id    BIGINT REFERENCES edi_partner(id),
  direction     VARCHAR(8),       -- IN / OUT
  message_type  VARCHAR(16),
  control_no    VARCHAR(64),
  raw_content   TEXT,
  structured    JSONB,
  status        VARCHAR(24),
  error_msg     TEXT,
  oss_key       VARCHAR(256),
  created_at    TIMESTAMPTZ DEFAULT now(),
  updated_at    TIMESTAMPTZ DEFAULT now(),
  UNIQUE (partner_id, control_no)
);

CREATE TABLE edi_ack (
  id            BIGSERIAL PRIMARY KEY,
  document_id   BIGINT REFERENCES edi_document(id),
  ack_type      VARCHAR(16),      -- 997 / MDN
  result        VARCHAR(8),       -- A / R / E
  raw_ack       TEXT,
  oss_key       VARCHAR(256),
  created_at    TIMESTAMPTZ DEFAULT now()
);
```

## 5. 映射模板示例

```json
{
  "partner": "walmart-dropship",
  "message": "850",
  "fields": [
    { "edi": "BEG03", "biz": "order_no", "type": "string", "required": true },
    { "edi": "BEG05", "biz": "order_date", "type": "date", "format": "CCYYMMDD" },
    { "edi": "PO1.LIN03", "biz": "buyer_sku", "type": "string" },
    { "edi": "PO1.LIN02", "biz": "qty", "type": "decimal", "scale": 0 },
    { "edi": "PO1.LIN04", "biz": "uom", "type": "code", "map": { "EA": "PCS" } }
  ]
}
```

## 6. 重试策略

| 项 | 值 |
|---|---|
| 首次重试 | 30 秒 |
| 退避序列 | 30s → 2min → 10min → 30min |
| 最大次数 | 4 |
| 超限处理 | 置 AckTimeout，告警，停止自动重发 |
| 幂等 | 以 partner + control_no 唯一约束防重 |

## 7. 安全约束

1. AS2 私钥仅从 KMS 临时读取，禁止写入代码、镜像、Git。
2. 入站请求记录源 IP、时间、MessageID、伙伴 ID。
3. 内部 API 使用 API Key 鉴权，禁止公网裸奔。
4. 原始报文与回执永久归档，默认保留 7 年。
5. SFTP 仅密钥认证，伙伴目录隔离，禁止跨目录访问。
6. 数据库与 Redis 不暴露公网。

## 8. 监控指标

- 入站报文数、解析失败率
- 出站发送成功率、MDN 成功率、超时数
- 队列积压长度
- 证书剩余天数
- 通道连通性拨测结果

告警渠道：钉钉 / 企业微信机器人 + 邮件。
