|
|
|
|
# 易达云(EDAYUN)接入
|
|
|
|
|
|
|
|
|
|
## 当前状态:骨架
|
|
|
|
|
|
|
|
|
|
| 项 | 状态 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 模块 | ✅ `warehouse-sdk-edayun` 已建、已注册 |
|
|
|
|
|
| 适配器 / 工厂 | ✅ 类型就绪,能力位为空 |
|
|
|
|
|
| 获取 token | ✅ 已对接(`POST /oauth/token`) |
|
|
|
|
|
| 业务接口 | ⬜ 等文档 |
|
|
|
|
|
| 回调 | ⬜ 等文档 |
|
|
|
|
|
| 真机验证 | ⬜ 等测试环境 |
|
|
|
|
|
|
|
|
|
|
**骨架阶段的行为**:任何业务调用都会抛
|
|
|
|
|
`WarehouseUnsupportedCapabilityException`——这是有意为之,不返回空集合。
|
|
|
|
|
|
|
|
|
|
## 鉴权(已确认部分)
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
① POST /oauth/token
|
|
|
|
|
body: { "client_id": "OMS授权用户名", "client_secret": "密码" }
|
|
|
|
|
无业务请求头
|
|
|
|
|
→ 返回 token
|
|
|
|
|
|
|
|
|
|
② 业务请求头
|
|
|
|
|
token 来自 ①
|
|
|
|
|
appKey 测试: 7289ded35b198243883151876eaf3213
|
|
|
|
|
timestamp 毫秒,5 分钟内有效
|
|
|
|
|
sign MD5(body + "." + appSecret),测试环境可传 openApiAdminSecret 免签
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**凭据映射**(复用 `ChannelSecret`):
|
|
|
|
|
|
|
|
|
|
| 易达云 | ChannelSecret |
|
|
|
|
|
|---|---|
|
|
|
|
|
| appKey(请求头) | `appKey()` |
|
|
|
|
|
| appSecret(签名用) | `appSecret()` |
|
|
|
|
|
| client_id(换 token) | `clientId()` |
|
|
|
|
|
| client_secret(换 token) | `clientSecret()` |
|
|
|
|
|
|
|
|
|
|
**代码位置**:
|
|
|
|
|
|
|
|
|
|
| 类 | 职责 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| `auth/EdayunTokenClient` | 换 token,兼容三种响应形态,按 code 区分可重试 |
|
|
|
|
|
| `http/EdayunRequestFactory` | 构造 token 请求与业务请求;`sign()` 算 MD5 |
|
|
|
|
|
| `adapter/EdayunAdapter.token(ctx)` | 走 `TokenManager` 缓存(按 `appKey + clientId` 维度) |
|
|
|
|
|
|
|
|
|
|
**三处待联调确认**:
|
|
|
|
|
|
|
|
|
|
1. **响应体结构**——文档只给了 `code` 取值(200/500/503/504),**没给 body 字段**。
|
|
|
|
|
现在兼容 `data.access_token` / `data.expiry` / 顶层 `token` 三种形态,真机确认后删多余分支。
|
|
|
|
|
2. **token 有效期**——文档未写。`data.expires_in` 优先,其次 `data.expiry`,
|
|
|
|
|
都没有按 2 小时兜底(`DEFAULT_TOKEN_TTL_SECONDS`)。
|
|
|
|
|
3. **是否有 refresh**——文档没提。当前按「过期重新登录」处理。
|
|
|
|
|
|
|
|
|
|
## 待确认(问易达云)
|
|
|
|
|
|
|
|
|
|
| # | 要确认 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 1 | **业务接口文档**(含回调) |
|
|
|
|
|
| 2 | **测试环境**:域名、OMS 授权账号、测试仓、测试 SKU |
|
|
|
|
|
| 3 | token 响应的**实际 body 结构**与**有效期** |
|
|
|
|
|
| 4 | **限流**:每秒许可数、单日配额 |
|
|
|
|
|
| 5 | **能否在 PR 环境走写操作**(建单 / 取消 / 销毁),决定探针设计 |
|
|
|
|
|
| 6 | **回调**:验签算法、时间戳单位、响应体格式、是否按路径区分 |
|
|
|
|
|
| 7 | **费用口径**:是否有费用类型码(运去哪只有中文名) |
|
|
|
|
|
| 8 | **库存同步**:支持按时间增量还是只能全量 |
|
|
|
|
|
|
|
|
|
|
## 骨架已定的部分
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
warehouse-sdk-edayun/
|
|
|
|
|
├── pom.xml
|
|
|
|
|
└── src/main/java/common/ecommerce/edayun/
|
|
|
|
|
├── EdayunConstants.java 端点 / 路径 / 限流(带 TODO 占位)
|
|
|
|
|
├── adapter/
|
|
|
|
|
│ ├── EdayunAdapter.java 能力位为空,未实现能力不声明
|
|
|
|
|
│ └── EdayunAdapterFactory.java
|
|
|
|
|
├── dto/package-info.java 一个接口一个文件
|
|
|
|
|
├── enums/package-info.java 平台枚举约定
|
|
|
|
|
├── http/package-info.java 信封校验约定
|
|
|
|
|
└── webhook/package-info.java 回调约定
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**测试**:`EdayunAdapterTest`(5 个)验证类型接对、能力位为空、
|
|
|
|
|
未实现能力显式拒绝、注册后可解析、能力查询不触发真实 API。
|
|
|
|
|
|
|
|
|
|
## 接下来怎么推进
|
|
|
|
|
|
|
|
|
|
按 [onboarding-checklist.md](../onboarding-checklist.md):
|
|
|
|
|
|
|
|
|
|
1. 拿到文档后补 `EdayunConstants` 的路径常量
|
|
|
|
|
2. 按接口逐个补 `dto/` + `adapter/XxxMapper` + `enums/`(阶段 2 的 6 步)
|
|
|
|
|
3. 写只读探针 → 真机验证 → 全链路探针
|
|
|
|
|
4. 补回调实现
|
|
|
|
|
5. 更新本文档
|
|
|
|
|
|
|
|
|
|
## 已知的坑(从运去哪/信仓带来的经验)
|
|
|
|
|
|
|
|
|
|
| 坑 | 应对 |
|
|
|
|
|
|---|---|
|
|
|
|
|
| 文档参数名可能带 `query.` 前缀而实际不带 | 真机验证时必须核对 |
|
|
|
|
|
| 有些接口没有 `code` 只有 `status` | 信封校验要兼容两种 |
|
|
|
|
|
| 文档示例常是自动生成的占位符 | 不看示例值,看真机返回 |
|
|
|
|
|
| 单位可能未标注 | 真机验证量级(kg vs lb 差 2.2 倍) |
|
|
|
|
|
| 状态码可能依赖上下文(单据类型) | `(type, status)` 一起带出去 |
|