chenchuchuan
|
cbc02361d7
|
fix(inventory): line_name 是项目名称,不映射到商品名
确认运去哪与恒健库存响应里的 line_name / lineName 是「项目名称」
(用于仓方分账 / 路由),不是商品名。
- 运去哪:撤掉上一提交里 line_name → productName 的映射
- 恒健:撤掉 lineName → productName(快照 + 变动流水两处)
- 测试:恒健 movementsMapAllFields 改为断言 productName 为 null
结果:这两家的 InventorySnapshot.productName 恒为 null,只在响应里
能拿到项目名,但不属于商品信息。
Co-Authored-By: Claude <noreply@anthropic.com>
|
13 hours ago |
chenchuchuan
|
17097a764f
|
feat(inventory): 库存快照补 barcode / productNameCn,运去哪补品名映射
实际核对四家仓的库存响应后补齐:
1. InventorySnapshot 新增两个字段
- barcode:条码(UPC/EAN/GTIN),仓方原值
- productNameCn:中文品名,仓方原值
两者都可能为 null,各仓支持度不同。
2. 各仓映射补齐
- 易达云:row.barcode → barcode(原本丢弃)
- 信仓:chn_name → productName + productNameCn(原本只进 productName)
- 运去哪:line_name → productName(原本拿到了却没写进快照,一直是 null)
- 恒健:lineName 已映射到 productName,无变化
productNameCn 只填明确是中文的字段(信仓 chn_name);运去哪 / 恒健的
line_name / lineName 语言由仓方决定,不猜,只填 productName。
Co-Authored-By: Claude <noreply@anthropic.com>
|
14 hours ago |
chenchuchuan
|
799ac981c7
|
refactor: WarehouseAccount 用 accountId 取代 credentialRef
原 credentialRef 只是个"密钥引用名",和仓编码是两套标识,理解成本高。
改为:
- 新增 accountId 作账户主键,同时作为 SecretProvider 的取密钥键
- 删除 credentialRef
- accountId 不填时默认等于 warehouseCode,简单场景少写一个字段
对外调用不变:sdk.warehouses(warehouseCode) 仍传仓编码。
SecretProvider.get(accountId) 拿密钥。
同一仓未来挂多个 provider 时,warehouseCode 会有多条记录,但 accountId
仍然唯一,密钥 / 限流 / 水位线按它隔离。
Co-Authored-By: Claude <noreply@anthropic.com>
|
18 hours ago |
chenchuchuan
|
a6bfba6fa9
|
fix: 同步引擎查询窗口与水位线对齐,库存增量字段显式拒绝
1. SyncEngine 的查询窗口补上上界
原来 fetch(from, cursor) 只传起点,水位线却推进到 to。窗口内尚未入账的
数据会被永久跳过。改为 PageFetcher(from, to, cursor),查询与推进都限定在
[from, to)。同时补 syncProducts。
2. 新增首次全量建底 API
增量同步要求先有水位线,但此前没有任何方法能建底,只能手工 advance。
新增 bootstrapSalesOrders / bootstrapProducts:分页拉全量 → 落库 →
成功后播种水位线;已有水位线时拒绝执行,避免把线上水位线回退。
3. 库存 updatedAfter 四家仓统一显式拒绝
恒健原本就拒绝;运去哪 / 易达云 / 信仓此前静默忽略该字段,调用方以为
是按增量拉、实际拿到全量,容易误用。现统一抛 ValidationException,
与各仓 inventorySyncStrategy()=FULL_PULL_DIFF 保持一致。
补 4 个同步测试:窗口上界、无水位线、to 早于起点、建底与重复建底拒绝。
Co-Authored-By: Claude <noreply@anthropic.com>
|
19 hours ago |
chenchuchuan
|
dc4db1c208
|
refactor: 连接配置收敛到 SecretProvider,调用点只传身份
调用方不再每次构造 ChannelConnection 传地址和密钥,改为:
- 账户只保留业务字段(warehouseCode / provider / providerWarehouseId / credentialRef)
- 密钥与地址由 SecretProvider 按 credentialRef 统一提供
- 门面新增免连接重载:sdk.warehouses(code)、sdk.salesOrders(key) 等
主要改动:
- ChannelSecret 承接 endpointBaseUrl / auxEndpointBaseUrl,与密钥一起配置
- WarehouseAccount 删除 timeZone / endpointBaseUrl / auxEndpointBaseUrl
- ChannelAccount 增加 endpointBaseUrl
- PlatformAdapter / WarehouseAdapter 新增 defaultEndpointBaseUrl(),适配器提供内置默认地址
(运去哪 / 信仓 / 恒健 / 领星取生产地址;易达云生产地址未定,返回 null)
- WarehouseConnection 不再无条件覆盖凭据里的地址,凭据已有地址时优先采用
- 两个门面的 Builder 新增 secretProvider(...),未注入时仍可用带连接的老入口
- 旧签名(带 connection)全部保留,向后兼容
适配器内部未改动:它们只消费 ctx.secret() / ctx.endpointBaseUrl(),
来源由调用方传入改为门面装配。
Co-Authored-By: Claude <noreply@anthropic.com>
|
20 hours ago |
chenchuchuan
|
4d2f8a0fc4
|
docs: 源码集成版去掉前两章,直接从「配置」开始
源码已经随交付提供,怎么拷、要引哪些库不需要再写在文档里。
删除「一、源码怎么集成」「二、必须引入的第三方库」,章节整体前移:
一、配置(原三)
二、快速上手(原四)
三、我要做的事能不能做(原五)
四、按任务 4.1~4.8(原 6.x)
五、贯穿全局的规则(原七)
六、出错了怎么办(原八)
依赖信息压缩成开头一行:jackson 2.13.5 / slf4j-api 1.7.36 / okhttp 4.12.0。
全部锚点已同步重编号并逐个核对,无失效链接。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 days ago |
chenchuchuan
|
76a1a810b5
|
docs: 拆成两份使用说明——jar 引入版 / 源码集成版
之前的「源码集成版」只覆盖了一种交付形态。按实际需要拆成两份,
共享的配置与业务章节保持一致,只替换集成方式:
SDK使用说明-Jar引入.md
- 一、集成方式:引哪些 jar(核心 warehouse-sdk-core + 按需适配器)、
Maven / Gradle 写法、建议开启 sources 下载、jar 自带的传递依赖
- 二、配置 / 三、快速上手 / 四~七 与源码版一致
SDK使用说明-源码集成.md
- 一、源码怎么集成:必拷 6 个目录(已核对仓库域不引用 channel 包)、
两种投放方式(合并 src/main/java 或独立模块)、测试代码可选项
- 二、必须引入的第三方库:只有 jackson / slf4j / okhttp,不需要 Lombok
- 三、配置 / 四、快速上手 / 五~八 与 jar 版一致
两版的业务章节(任务、全局规则、异常)内容完全相同,只是编号后移:
jar 版 四~七,源码版 五~八。锚点同步改过。
删除原来的 SDK操作手册.md(已被这两份取代)。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 days ago |
chenchuchuan
|
52a064707b
|
docs: 操作手册改为「源码集成版」
对方面对我们全量源码,不走 Maven 坐标,所以重写:
一、源码怎么集成(新增)
- 源码结构图与「必拷/不用拷」清单
- 关键事实:仓库域主代码完全不引用 channel 包(已 grep 核对),
所以只需拷 6 个目录
- 两种放法:合并进 src/main/java(包名不变,不用改 import)/ Gradle 多模块
- 测试代码可选:sdk-testkit 的 FakeDirectAdapter 引用了 channel 包,
只想测仓库域时只拷 5 个类即可
二、必须引入的第三方库(新增)
- 全量 grep import 核对后:只有 jackson / slf4j-api / okhttp 三个
- 明确「不需要 Lombok」(仓库域零使用,只有 lingxing 用了)
- 给了 Gradle 与 Maven 两种写法
- OkHttp 4.x 是 Kotlin 写的,需要 kotlin-stdlib;给两个规避方案
- 附 HttpTransport 自定义实现说明(不想引 OkHttp 时)
三~七 保持上一版的任务组织:
5 分钟上手 / 能不能做 / 8 个任务 / 全局规则 / 异常处理
只把「引入依赖」的 Maven 坐标换成了源码说明。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 days ago |
chenchuchuan
|
a7fedbe5b1
|
docs: 操作手册改为「业务开发版」,按任务组织
原来那版是按 SDK 结构写的(创建/入参出参/能力),业务开发要先读三章
才能寄一个快递。重写为面向使用方:
一、5 分钟上手
- 引入依赖 → 实现两个 SPI(含可参考的实现)→ 组装 SDK → 拿到仓视图
- 1.4 用「查仓库清单」做连通性自检,附失败对照表
二、我要做的事能不能做
- 一张 21 行的「业务动作 × 四个仓」矩阵,先看能不能做
三、按任务(8 节,每节统一结构:代码 → 拿到什么 → ⚠️ 坑)
- 发货 / 轨迹 / 取消 / 退货 / 库存 / 商品 / 对账 / 打单
四、贯穿全局的规则
- 单位、SKU 口径、分页、金额——写一次,各任务复用
五、出错了怎么办
- 五类异常 + 重试判定 + 常见报错对照 + 幂等键表
附录:日志格式、枚举速查、更深文档去哪看
相对上一版的取舍:
- 砍掉架构分层、WarehouseContext 组装、扩展新仓等维护者视角内容
- 快速开始给完整可运行代码,任务章节给片段 + 前置说明
- IdempotencyStore 的示例改成与真实 SPI 一致(四种 Claim 结果),
并把示意方法名标注清楚,避免被当成可直接编译的代码
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 days ago |
chenchuchuan
|
b6e3f05091
|
docs: 新增三方仓 SDK 操作手册
按「1. SDK 怎么创建、2. 入参怎么传出参怎么取、3. 各能力怎么调用」三段组织:
一、创建
- 依赖坐标、JDK 1.8
- 宿主必须实现的 SPI:WarehouseRepository / WarehouseAccount /
IdempotencyStore / CallObserver / TokenStore
- 构建门面(含 4 个仓工厂的构造参数、build 失败条件、单例要求)
- 连接信息与各仓凭据字段
- 取仓视图、查能力位
二、入参/出参
- 通用约定:cm/g/Instant/Money,以及 SKU 口径(建档下发的那串)
- Page<T> 翻页模板(游标已屏蔽各仓页码起点差异)
- OutboundCommand / OutboundLine / ShipTo 逐字段说明 + 必填/选填
- InventoryQuery / InboundCommand / ReturnCommand / ReturnQuery /
FeeQuery / FeeEstimateQuery / WarehouseProduct / ProductQuery
- 出参速查表(18 个模型的关键 getter)
三、能力调用
- 视图结构 + 23 行能力矩阵(四个仓逐项打勾)
- 商品 / 出库 / 库存 / 入库 / 退货 / 费用 / 基础资料 / 单据打印 /
调拨销毁异动 的调用示例
四、异常层级(ChannelException -> WarehouseException)、取值、重试判定、幂等键表
五、常见坑速查(SKU 口径、易达云反向布尔、地址州名、面单 URL、-1 语义等)
写的过程中核对并修正了几处:
- OutboundQuery.status 收的是仓侧原始字符串,不是统一枚举
- 能力矩阵按各适配器 EnumSet.of 实际声明提取,不是按接口实现推断
- 补上此前漏掉的 recommend / classifyAddress
- 箱唛两接口语义相反(printBarcode=箱唛、newPrintCaseMark=SKU 标)
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 days ago |
lml
|
492743b34e
|
fix(hengjian): 计费的「未结算」哨兵日期 1997-01-01 转 null
重测计费接口时发现真问题:未结算的账单行把 settlementAt / bookAt
填成 1997-01-01 00:00:00 而不是 null。直接落库会让对账以为
1997 年结过一笔。
- HengjianFeeMapper 新增 settledAt():哨兵日期转 null;
仓储费 / 尾程费 / 作业费三个接口统一走它
- 尾程费与作业费原先的 firstNonBlank(settlementAt, chargeAt) 回落
一并去掉——chargeAt 是计费发生时间,不是结算时间,回落会让
「未结算」看起来像「已结算」
顺带更正之前的结论:ES 抖动无法复现。同一参数连打 20 次全部成功,
rows 5/10/20/50/100 也都成功,说明当时是仓方一次性抖动,不是稳定
故障。重试逻辑保留(成本极低、只读无副作用),但文档改为如实记录。
新增结算哨兵测试。mvn test 全量通过。
|
2 days ago |
lml
|
28e4b98975
|
test(hengjian): 地址识别改用已知答案的地址做正例
上一轮用普通地址测出 UNKNOWN 时无法判断是接口问题还是地址库覆盖问题。
换成两个已知答案的地址验证:
Google HQ (1600 Amphitheatre Pkwy, Mountain View, CA 94043) = BUSINESS
Apple HQ (1 Infinite Loop, Cupertino, CA 95014) = BUSINESS
结论:接口与映射都正常,「UNKNOWN」是恒健地址库没覆盖到该地址,
不是 bug。探针保留一个 UNKNOWN 样例并注明原因,避免下次误判。
另外确认 country 必须是两字母 ISO 码,给 USA 回 400。
同时修正计费接口的故障描述:不是某一个接口挂,三个
(仓储费 / 尾程费 / 作业费)都会间歇性回 Elasticsearch scroll 异常,
同参数重试有时成功。
|
2 days ago |
lml
|
72982e2806
|
test(hengjian): 只读探针补全全部查询接口,并用真机结果修 5 处映射
探针从 7 个用例扩到 21 个,覆盖全部已接入的查询接口(商品 / 库存 /
入库 / 调拨 / 退货 / 销毁 / 试算 / 地址 / 计费 / 目录)。
真机跑通 14 个接口,暴露并修掉这些问题:
- 运费试算必须给「发运仓库」或「发运邮编」其一,否则 400。发运仓的
字段名是 warehouseCode,shipWarehouseCode / orgWarehouseCode /
shipFromWarehouseCode 都不认(逐个试过)。core 的 FeeEstimateQuery
补 shipFromWarehouseCode,适配器用账户仓兜底
- 试算的 shipper* 给了不完整会报「发货人信息不完整」,所以要么只给
warehouseCode,要么给全五项
- 商品查询 length 真机确实有(文档响应表漏了),之前的兜底没触发
- 商品 nameEn 空值返回字符串 "null" 而不是 JSON null,trimToNull 一并当空
- 商品 cost 可为 0.0,是合法成本,原先当「没给」丢掉;且误塞进了
declaredValue(语义是申报价值),改为 cost
- isInsuranceRate 是费率不是金额,不再塞进 insuranceFee(Money 是金额语义)
- 响应有文档没写的 productStatus,保留原值到 rawStatus
另记录一条仓方故障:chargingSettlement 的 STORAGE 类型在测试环境返回
code=999999 + Elasticsearch scroll 异常,是恒健侧 ES 故障,我方报文正确。
销毁查询路径仍 404,探针标注未覆盖。token 只从 -Dhengjian.probe.token 读,
不入库。
mvn test 全量通过。
|
3 days ago |
lml
|
8d04306169
|
refactor(hengjian): 退货查询收进 ReturnQuery,消除绕开操作日志的适配器入口
HengjianAdapter.queryReturnsAdvanced 是门面上没有对应入口的 public 方法,
宿主强转适配器直接调用时会绕过 CallSupport.observe,操作日志漏记。
做法不是给它补日志,而是把它表达的能力收进统一模型:
- ReturnQuery 增加 rawStatuses / queryDataType / queryTypeValue+queryValue
* rawStatuses:统一枚举有损。恒健 RETURNING 对应仓方 20(待处理)
和 35(处理中),归一层表达不了,要给原值时只能传码
* 与 statuses 互斥,两套码表同时给会互相覆盖,构造期就拒绝
- 恒健 queryReturns 支持全部维度,并显式拒绝它没有的(SKU 过滤、
多状态、单号与 tracking 同时给、时间窗只给一半)
- 删除 queryReturnsAdvanced;适配器不再有绕开门面的 public 方法
验证:mvn test 全量通过。审计脚本确认门面除 outbound()(返回视图对象)
外零漏点,恒健不再有绕过日志的入口。
|
3 days ago |
lml
|
590162eefc
|
merge: 合入远端商品查询,统一改用 ProductInfo
手动合并的检查结论:编译与测试都过,但语义上两边各做了一套,
恒健 / 信仓还在产出 WarehouseProduct(建档入参),与远端的
ProductInfo(查询结果)重复。按远端方案统一。
- ProductInfo 作为唯一的商品查询结果模型:补恒健 / 信仓特有的
实测尺寸、申报价值、保价、保质期、体积、状态原值等字段
- WarehouseProduct 回退到远端版本:去掉为「查询结果复用建档入参」
加的 allowUnknownDimensions / providerProductId / measured* 等
- 恒健 / 信仓 mapper 改为产出 ProductInfo,适配器方法名对齐为 query()
顺带修两个操作日志漏点(都是门面方法没走 CallSupport.observe):
- OutboundOutbounds.create:写操作只记了幂等层的 writes.create,
没有门面级记录,日志里看不到「下发」这个动作
- 退货 create / cancel、入库 create、入库 bols、inventorySyncStrategy
并把恒健两个绕开日志的适配器方法收进门面:
- queryReturnHandles -> WarehouseReturnCapable.queryHandles
返回统一模型 ReturnHandle(新增),不再暴露仓方 DTO
- queryReturnsAdvanced 保留在适配器(统一模型无对应维度),
文档里标注「不走门面日志」
新增 WarehouseCallObserverTest(7 个用例)覆盖:
成功 / 失败 / 只读 / 一次调用一条 / 未注入 observer / observer 抛异常
不影响业务 / params 不含密钥。门面 45 -> 51 个 operation 全部有记录。
mvn test 全量通过。
|
3 days ago |
lml
|
aac75d5904
|
feat: 信仓 / 恒健全接商品查询
core 新增 ProductQuery(SKU 过滤 + 分页)与
WarehouseProductCapable.queryProducts(default 拒绝,两家覆盖),
门面加 queryProducts。WarehouseProduct 补查询结果才有的字段
(仓侧 id / 仓方实测尺寸 / 创建更新时间 / 状态原值 / 体积),
并加 allowUnknownDimensions 开关:查询结果允许尺寸重量为 0
表示「仓方未给」,建档仍必须为正数——不伪造 0.01 之类的假值。
恒健 /v2/product/queryPage:
- 文档把 pageSize / pageNum 的说明写反(pageSize 写「页码」),
按响应里的含义实现:pageSize=每页条数、pageNum=页码;请求侧是 STRING
- 响应 data 是分页对象而非数组,按 total 判断是否还有下一页
- 文档漏了 length(只有 width/height/itemLength),映射时优先 length、
缺失退回 itemLength
- measurement* 存到仓方实测字段,与申报尺寸分开
信仓 api.productlist:
- 字段表按 Apifox「OMS接口文档V2」全量映射(token/state/page/limit 四项必填)
- 固定 state=1 查正式产品:临时产品是建档中间态,混进业务列表会让人
以为能下单;建档查重仍走 state=0
- key 是单值:传多个 SKU 时拒绝,不静默只取第一个
- 厘米与英寸两套尺寸都给,直接用厘米那套,避免二次换算舍入
- 数值全是字符串,空串转 null 不转 0;按 rst.count 判断下一页
- PRODUCTION_BASE_URL 确定为 https://oms.xincang-tech.com/oms(去掉末尾斜杠)
验证:mvn test 全量通过(恒健 +11、信仓 +10)。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
chenchuchuan
|
635fc09883
|
Merge branch 'master' of http://124.222.6.97:3000/chencc/common-ecommerce
|
3 days ago |
chenchuchuan
|
5bbfb33261
|
docs: 写清 SKU 口径——建档下发的那串,之后全程用它
核心结论(代码注释 + 文档都补上):
- 建档时 skuOf() = providerSku 优先,为空才回退 omsSku
易达云写到 skuCode 字段、运去哪写到 sku 字段
- 仓方一旦落库,之后 查商品 / 下单 / 查库存 都必须传同一串
- 所以「仓侧 SKU」不一定等于 OMS SKU:
给了 providerSku(如 AP0000X9US0010601)则两者不同;没给则同名
- SDK 不做 OMS→仓侧转换(映射表在宿主手里,静默转换会静默查空)
补注释的位置:
- WarehouseProduct.providerSku 字段与 getter
- ProductQuery.providerSkus / InventoryQuery.providerSkus
- YqnProductMapper.skuOf / EdayunProductMapper.skuOf(含真机证据说明)
- 两个适配器的商品查询方法 javadoc
- YqnOutboundMapper / EdayunOrderMapper 的出库行 SKU 赋值处
Co-Authored-By: Claude <noreply@anthropic.com>
|
3 days ago |
chenchuchuan
|
b5e94c1157
|
feat: 运去哪 / 易达云 商品查询接口
统一模型新增:
- ProductQuery:providerSkus(仓侧 SKU)/ barcode / 创建时间窗 / 分页,
单次上限 100 个 SKU
- ProductInfo:查询结果(仓侧 SKU、条码、尺寸重量、装箱、状态、创建时间)
- WarehouseProductCapable.query(...) 默认抛不支持;门面 queryProducts(ProductQuery)
运去哪(API 113 /v1/product/findPage):
- **页码从 0 开始**(文档原文),游标即页码、不做 ±1 换算
- 单页上限 100、skuList 上限 100
- 该接口没有条码 / 时间窗过滤,传了本地拒绝
- 翻页优先 last,其次 number+1 < totalPages,最后按满页兜底
- cost 没有 currency 时不成 Money(避免丢单位)
易达云(/webApi/skuInfo/v1/listProductPage):
- skuCode 是逗号拼接的单个字符串,一次最多 50 个,超了本地拒绝
- 页码从 1 开始、单页上限 200
- 尺寸取**实际值**,缺失才回落 forecast*(真机 ybtest:实际 55 vs 预报 10,差 5 倍)
- 「查询无数据」按空页处理,不抛异常(与轨迹接口同口径)
- 查询条件全空时仓方默认查最近一个月,本地不补默认值
真机验证(2026-11-17):
- 易达云:不带时间窗 total=52244;skuCode=ybtest 命中 1 行;
30 天窗口 + 2021 年建的 SKU → 「查询无数据」;10 年窗口正常命中
- 运去哪:未提供 x-api-key,只做了离线单测
SKU 口径已确认并写入文档:两边都传仓侧 SKU(建档下发的 providerSku,
为空时才是 omsSku),SDK 不做 OMS→仓侧转换。
Co-Authored-By: Claude <noreply@anthropic.com>
|
3 days ago |
chenchuchuan
|
efc248c27d
|
docs: 同步 CR 修复后的文档
- README:queryReturns 已实现(之前写的是「没有列表接口」);
BarcodePaperSize -> CaseMarkPaperSize
- TODO:#38 标记已解决;#65 枚举名修正
- architecture:能力位 26 -> 27,WAREHOUSE_DIRECTORY -> DIRECTORY,
补 CASE_MARK_PRINT 一行
Co-Authored-By: Claude <noreply@anthropic.com>
|
3 days ago |
chenchuchuan
|
7629a52ab8
|
fix(edayun): 修 CR 发现的三个真 bug 与若干语义问题
Critical:
1. EdayunRmaListMapper 静默丢弃调用方的仓库过滤——账户绑了数字仓 id 时,
传入不同的 warehouseCode 会被忽略,结果反而变宽。改为冲突时本地拒绝。
2. EdayunTrackMapper 把 track.receiver(收件人)映射到 signedBy(签收人),
导致每个在途包裹都被判成已签收。易达云响应没有签收人字段,改为不填。
3. 退货详情 / 列表用 warehouseName(美西1仓)当 warehouseCode,宿主拿它
equals / 回传查询会全线失效。改为只用仓编码,缺失直接回退 OMS 仓编码。
Important:
4. EdayunReturnMapper 静默丢弃 returnReason / estimatedReceiveDate /
lineName——三个字段易达云都不支持,改为本地拒绝并说明原因。
5. WarehouseDirectoryCapable.carrierDirectory 默认实现把 carriers() 的码
包装成假的两层结构(carrierId == nameEn == FEDEX-G),改成默认抛不支持。
6. EdayunAdapter.printSkuLabel 改包级可见:SKU_LABEL 未声明,门面够不到,
留 public 会让调用方误以为能用。
7. products(warehouseCode) 之前完全忽略入参;改为显式优先,且必须数字。
8. 删掉 EdayunCarrierTest.warehousesAreUnsupported——它断言的是相反行为,
能过只是因为没注册路由。
9. EdayunAdapter 类注释还写着「已实现:商品建档、创建出库单」。
Minor:EdayunAdapterFactory 重复 import、CaseMarkPrintCapable javadoc 写的
BARCODE_PRINT 不存在、TODO.md 表格分隔行丢失、EdayunInventoryTest 合并残留
换行错乱。
新增回归用例:仓库过滤冲突 / 一致、三个不支持字段被拒。
验证:全仓 mvn test 通过;易达云 304 个用例全绿。
Co-Authored-By: Claude <noreply@anthropic.com>
|
3 days ago |
lml
|
93e85bfeb7
|
feat(hengjian): 对接入库箱标生成 /v2/inbound/boxLabelGenerate
真机确认必填五项:inboundPlanOrderNo / type / pageSize / isIndexNo /
isOriginCountry(空 body 时仓方一次性列出全部缺失项);paperType 与
fileNamingType 选填。
- 响应无 data:只有 code/message,不回任务号也不回文件,文件要去
入库计划详情的 packingLabelUrl 取。所以 LabelPrintTask.taskNo 恒为
null,不代表调用失败
- 份数口径不同:twoCopies → type 1 一式一份 / 2 一式两份,是份数码
不是布尔
- 恒健没有 sizeType / downloadMode 口径,改用 paperType(1 A4 /
2 10×10);labelsPerPage 直接映射 pageSize
- isIndexNo / isOriginCountry 仓方标必填,统一模型是 null-able:
null 时本地拒绝而不是猜——猜「是」每箱多印一行,猜「否」漏印
- core LabelPrintTask.taskNo 改为可空;BoxLabelCommand 补
showIndexNo / showOriginCountry / paperTypeCode / fileNamingType
顺带修正一处笔误:AddressClassificationCapable 的 @param city
被改成「必」,恢复为「必填」。
验证:mvn test 全量通过,恒健 340 个用例(+11)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
lml
|
b634ff2e93
|
feat(hengjian): 对接销毁计划创建 / 查询(路径待真机确认)
⚠ 这两个路径在测试环境真机返回 404 No handler found(2026-11-17),
文档路径及 26 个变体全试过;同环境其它接口正常响应,不是网络问题。
代码按文档实现,路径常量加了显式警告,联调时只需改一处。
- 创建:hopeDestroyData 字段名照抄(Data 不是 Date);orderNo 不传
(文档标必填但示例没有,仓方自生成);响应无 data,不回仓单号也不回状态
- 查询:请求体是裸数组;data 也是数组且查不到的单号不返回;
按来源单号查(示例里数组的值正是响应里的 sourceNo),也兼容仓方计划单号
- 新增 HengjianDestructionStatus:7 个状态值精确匹配;core 没有销毁状态
枚举,保留仓方码 + 中文名,不硬造跨仓枚举
- core DestructionCommand 补 lineName,DestructionOrder 补
lineName / hopeDestroyDate / createdAt
验证:mvn test 全量通过,恒健 329 个用例(+16)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
lml
|
1325314957
|
fix(hengjian): 异动单查询补齐未映射字段,并修正 changeRequestNo 语义
服务端字段原先只映射了一部分,排障要看的几组被丢掉了:
- 来源三维各存各的:sourceId / sourceNo / sourceOrderType,
orderNo 取 sourceNo(我们下发的单号落在那里),upstreamNo 不再合并进来
——合并就分不清哪一层出的问题
- 收件人对照:originalRecipient* / newRecipient* 三项都保留,
换址场景要能看到「原 → 新」
- carrierIsAcceptance 补齐并加 carrierAccepted():恒健是 1 否 / 2 是,
不是 0/1;缺失或非法值返回 null(未知),不猜
- trackingLabel 补齐并加 recalling()(1 召回中)
- errorStatus 与 errorMessage 分开保留:码用于判断、文本用于展示
- customerRemark / acceptanceRemark 两个字段不合并
修正 changeRequestNo 语义:查询响应里仓方不回 OMS 申请号,
原先把它填成仓单号,会让调用方误以为两者相等。现改为查询结果为 null,
创建结果仍填(那才是真的 OMS 单号)。字段改为允许 null。
验证:mvn test 全量通过,恒健 313 个用例(+8)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
lml
|
757b058697
|
feat(hengjian): 对接订单上传附件 /v1/saleOrder/createAttachment
- 新增 HengjianOrderAttachmentDtos,在 OutboundCapable 上加
uploadAttachments()(default 拒绝),恒健覆盖
- 门面新增 outbound().attachment(ref, list):写操作走幂等守卫,
业务键是「单号 + 附件名 + attachment」——同附件重传幂等、
不同附件各自一次(只用单号做键会让第二次附件被判成重复)
- 请求平铺;type 在这个接口是 INTEGER 0~6(创建订单那边标 STRING,
两页不一致),认不出即拒绝,不猜
- 给了 contentBase64 时忽略 url 并剥掉 data: 前缀(仓方语义)
- 真机无 token 时直接 403、不做参数校验,必填项按文档实现:
orderNo + 非空列表,每行 name/type 必填、url 与 file 二选一
- 响应无 data,只有 code/message
验证:mvn test 全量通过,恒健 305 个用例(+12)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
chenchuchuan
|
8dabf9fb1b
|
test(edayun): 补 SDK 装配链路冒烟(离线,按业务场景)
从门面 WarehouseSdk 走一遍,覆盖:
- 装配:能力位全量断言(12 个已声明 + 3 个必须为假)、工厂能建出适配器
- 场景 1 主数据:仓库 / 承运商 / 物流产品(-998 已跳过)
- 场景 2 发货:试算 → 建单 → 查单 → 面单 → 取消前校验 → 取消,
外加建单幂等(同一 outboundRequestNo 只打一次仓方)
- 场景 3 库存:safeStock 缺失映射为 -1
- 场景 4 退货:建单 → 详情 → 列表 → 取消
- 场景 5 单据 / 轨迹 / 打印:BOL、节点与运单级轨迹(上网/妥投时间)、
箱唛、入库单
- 未实现能力(调拨 / 退货检验后处理)必须抛,不返回空
不联网:用 RecordingTransport + 真实报文样本。适配器直接注册(传输层可替换),
另用一例单独验证工厂路径能 build 出适配器。
验证:9 个用例全绿;全仓 mvn test 通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
3 days ago |
chenchuchuan
|
97be2aebe9
|
docs(edayun): SKU 标接口不是未启用,是仓方内部报错
路径 /webApi/entryInfo/v1/newPrintCaseMark 确认存在——缺 pageSize 报
「纸张不能为空」、缺 madeInChina 报「产地标签不能为空」、缺 entryCode 报
「入库单号不能为空」。之前写错成 newPrintCaseMarkContentType 才会报
「接口不存在或未启用」。
参数补全后一律「内部服务器错误」,换 6 种 pageSize / madeInChina 0-1 /
separation / 箱序号区间 / skuCode / caseCodeList / 不存在的 entryCode
都是同一个错误,判断是仓方内部异常,不是我们的参数问题。
Co-Authored-By: Claude <noreply@anthropic.com>
|
3 days ago |
chenchuchuan
|
5dce79ea32
|
fix(edayun): 修正 SKU 标端点路径(去掉 ContentType 后缀)
正确路径是 /webApi/entryInfo/v1/newPrintCaseMark,之前按文档写成了
newPrintCaseMarkContentType,PR 环境一直报「接口不存在或未启用」,
被误判成「真机未启用」。
改路径后重测:接口存在且能过参数校验(缺 pageSize 报「纸张不能为空」、
缺 madeInChina 报「产地标签不能为空」),但补全后一律「内部服务器错误」,
试过 6 种 pageSize、madeInChina 0/1、separation、箱序号区间、skuCode、
caseCodeList、甚至不存在的 entryCode,返回都一样——说明是仓方内部异常,
不是我们的参数问题。因此仍然只有单测覆盖,TODO #68 保留。
Co-Authored-By: Claude <noreply@anthropic.com>
|
3 days ago |
chenchuchuan
|
c8f471352b
|
Merge branch 'master' of common-ecommerce
冲突处理:
- WarehouseCapability:远端新增 ADDRESS_CLASSIFICATION(260),本地的
CASE_MARK_PRINT 顺延到 270(码值只增不改,不复用)
- WarehouseOperations:两边新增的 import 都保留,去掉重复
适配远端新增后的编译错误:
- WarehouseReturnCapable.queryReturns 签名从 String cursor 改成 ReturnQuery
是本地改动,远端的 yqn / hengjian 实现还按老签名。yqn 只是抛不支持,
改签名即可;hengjian 把 ReturnQuery 的 cursor 转给 queryReturnsAdvanced,
并对其不支持的维度(时间窗 / 单号 / SKU / 状态)显式拒绝——静默忽略会
让调用方以为筛过了。
验证:全量 mvn test 通过(293 个用例,4 个探针跳过)。
Co-Authored-By: Claude <noreply@anthropic.com>
|
3 days ago |
lml
|
5169fb3107
|
feat(hengjian): 对接退货详情 / 列表 / 处理单列表 / 填写处理方式
四个接口真机均确认存在,但都不做参数校验(thirdParty 那两个回 403,
handlePage / handlingMethod 回 500+999999),必填项按文档实现。
- 请求形态两套:thirdParty 两个是双层包裹 params,handlePage 与
handlingMethod 是平铺;发错形态仓方当成空请求
- 详情:SKU 明细落 lines,换标明细 changeSku 落 newSku;
待处理 / 已处理列表不塞进 lines(那是 SKU 维度)
- sourceType 两页文档顺序相反(创建页 1 无来源、详情页 1 销售),
适配器不解释,原值保留在 type()
- 列表:page/size 文档标 string 转字符串下发;状态过滤是单值,多给即拒绝;
仓库 code 收逗号拼接;RETURNING 对应 20 或 35,无法唯一映射返回 null
- 处理单列表:过滤条件全是数组;返回仓方处理行(无对应统一模型);
时间戳是 ISO 带时区,解析转换后使用
- 处理方式:四项定位(returnPlanNo+returnNo+erpSku+tracking)不用行 id;
两级处理方式;继续拍照必须给 photosQuantity
- core ReturnProcessCommand:lineId 改 Long 可空、disposition 改可空
(与 primaryHandlingMethod 至少给一个)、补 6 个字段;运去哪缺 lineId 时
在适配器里显式拒绝,已加守卫
验证:mvn test 全量通过,恒健 293 个用例(+18)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
chenchuchuan
|
f66720f6be
|
feat(edayun): 对接仓库清单(权限内 / 全量激活)
两个接口用途不同,不要混用:
- POST /webApi/warehouse/listWarehouseHasPerm → warehouses(ctx)
当前客户有权限的仓(实测 69 条,跳过 -999 后 68)
- POST /webApi/warehouse/listActive → activeWarehouses(ctx, inbound)
平台全量激活仓(118 条),**含当前客户没授权的**
有权限的 68 个仓里有 50 个不在 listActive 结果里,所以给客户选仓必须用前者。
-999 是「智能分仓」哨兵值(divideWarehouse),不是真实仓,映射时跳过——
和物流产品接口的 -998 是同一套路。
listActive 的 warehouseOperationType:0 尾程 111 条 / 1 头程 7 条 /
不传 118 条(文档说必填,实测不传也通)。
统一模型口径:warehouseCode 放仓编码(USLA),数字 id 进 providerWarehouseId。
listActive 比 listWarehouseHasPerm 多 30 个字段(容量 / 营业时间 / 负责人邮箱等),
DTO 只声明统一模型用得上的十几个,其余由 Jackson 忽略。
顺带把之前 warehouses() 的显式拒绝换成真实实现,DIRECTORY 能力位从此完整。
Co-Authored-By: Claude <noreply@anthropic.com>
|
3 days ago |
chenchuchuan
|
17ef1c574a
|
feat(edayun): 对接客户自有物流服务(承运商)清单
POST /webApi/carrier/v1/listCarrierByWarehouse → List<WarehouseCarrier>
返回两层:承运商(carrierId / 名称中英文)→ 物流服务(logisticId / 名称)。
自提单下单时 carrierName 可以填承运商名,也可以用某个物流服务的名字。
统一模型新增 WarehouseCarrier;能力挂在
WarehouseDirectoryCapable.carrierDirectory(门面 carrierDirectory())。
原有的 carriers()(List<String>,只有码)保留不动——carrierDirectory 的
默认实现会把码包装成无名条目,能给出结构的仓覆盖它。
ownLogisticList 文档写成对象、真机返回数组,DTO 按 List 收。
真机(2026-11-16):仓 2 返回 11 个承运商(FedEx 下 12 个物流服务);
不传仓 22 个;countryCode=US 10 个。
顺带:易达云没有仓库列表接口,warehouses() 显式抛不支持,
不返回空列表——空列表和「没有仓」调用方分不清。DIRECTORY 能力位
目前只覆盖承运商这一半。
Co-Authored-By: Claude <noreply@anthropic.com>
|
3 days ago |
chenchuchuan
|
b675dd67e0
|
refactor(edayun): 修正 printBarcode / newPrintCaseMark 的语义归属
仓方确认两个端点名与实际打印的东西是反的:
- /webApi/skuInfo/v2/printBarcode → 实际是箱唛(外箱标)
- /webApi/entryInfo/v1/newPrintCaseMark* → 实际是 SKU 标
代码按实际语义命名(端点不变):
- printCaseMarks(...) + CaseMarkPrintCommand / CaseMarkPaperSize / CASE_MARK_PRINT
- printSkuLabel(...) + EdayunSkuLabelDtos / EdayunSkuLabelMapper / EdayunSkuLabelPaper
纸张尺寸真机实测(MediaBox)发现文档标称有错:
pageSize=2 文档说 6×4cm,实测 100×150mm
pageSize=3 文档说 A4, 实测 60×40mm
枚举按实测尺寸命名,码值原样保留。
其余三个尺寸与文档一致:0→70×30、1→100×60。
Co-Authored-By: Claude <noreply@anthropic.com>
|
3 days ago |
lml
|
4bcd8d54d9
|
feat(hengjian): 对接退货计划创建 /v1/saleReturn/thirdParty/saveReturnPlan
- 新增 HengjianReturnPlanCreateDtos + HengjianReturnMapper,实现
WarehouseReturnCapable.create,声明 RETURN
- 请求是双层包裹:业务字段全在 params 下(与其它接口不同)
- 该接口无 token 时直接 403、不做参数校验,必填项按文档字段表实现并在
本地拒绝(orgWarehouseCode / returnSkuArr / 每行四项),待真机带 token 验证
- tracking 挂在行上而统一模型是命令级:行级优先、否则退回命令级
- treatmentMethodForAppearanceDamage 文档标 integer、示例给 "2",按字符串下发
- 响应只回头级信息,不回明细行——保持空列表不凭空造
- 新增 HengjianReturnPlanStatus:8 个值精确匹配,20 待处理与 35 处理中不合并;
并注明 handlingStatus(5/10/15/20)是另一套码表
- core ReturnCommand 补 7 个字段、ReturnCommandLine 补 3 个字段并加两个
Builder 重载;其它仓不读,行为不变
验证:mvn test 全量通过,恒健 275 个用例(+16)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
lml
|
94b69a021d
|
feat(hengjian): 对接调拨计划创建 / 查询 / 取消
三个接口真机均确认存在:create 的参数校验可逐步推进、cancel 缺 sourceNo 回
"Required String parameter 'sourceNo' is not present"、findByPage 无参数回 403。
- 创建:真机确认必填 outOrgWarehouseCode / inOrgWarehouseCode /
estimateOutboundTime / estimateInboundTime;文档另标的 projectUnicode /
transportationType / inventoryType / isLabel / receiveStore / shipTo* 真机不校验,
按选填实现
- details[].qty 文档标 STRING:按字符串下发;查询响应是数字,两个 DTO 各声明
- 统一模型是 LocalDate,恒健要 yyyy-MM-dd HH:mm:ss:补当天 00:00:00 不编造时刻
- inOrgWarehouseCode=Other 表示外部仓库,映射 TransferType.OUTBOUND
- 响应 data 是字符串单号,拿不到即报错;创建不回状态,status 保持 UNKNOWN
- 查询:分页四件套必填、rows 上限 100 拒绝不截断;过滤参数都是单值,多给只取首个
- 取消走 GET + query,落在 deleteTransfer;仓方拒绝原样抛业务异常
- 新增 HengjianTransferStatus:13 个值精确匹配,100 取消中与 110 已取消不合并
- core 补 TransferQuery 模型 + TransferCapable.queryTransfers + 门面,
TransferCommand 补 5 字段、TransferOrder 补 projectCode/attachments
验证:mvn test 全量通过,恒健 259 个用例(+21)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
4 days ago |
chenchuchuan
|
fed2c0d4fc
|
feat(edayun): 对接打印箱唛(真机未启用)
POST /webApi/entryInfo/v1/newPrintCaseMarkContentType → WarehouseLabel
与入库箱标(inbound().printBoxLabel)的区别:那个是运去哪风格的异步任务
(只回任务号),易达云这个同步返回 PDF 地址。
纸张码值不连续:100×100=4、100×150=2、A4=5。统一枚举 LabelSizeType 原来
只有 100×100 / 100×150 / 104×98,这次补 A4(运去哪不支持 A4,不影响它)。
统一模型的 BoxLabelCommand 没有「选哪些箱」,所以默认整单打印;
部分箱用 printCaseMarks 的 CaseSelection 重载(系统箱号 / SKU /
箱序号区间 / 客户箱号区间四选一,全空本地拒)。
madeInChina 与 separation 是易达云特有语义、统一模型没有对应概念,默认关——
猜「打」会让每箱多一行。
真机(2026-11-16):该接口在 PR 环境报「接口不存在或未启用」;
去掉 ContentType 后缀的 newPrintCaseMark 能过参数校验(缺 pageSize 报
「纸张不能为空」、缺 madeInChina 报「产地标签不能为空」),但补全后一律
「内部服务器错误」。所以映射是按文档写的,只有单测覆盖,见 TODO #68。
Co-Authored-By: Claude <noreply@anthropic.com>
|
4 days ago |
chenchuchuan
|
5124ff85d1
|
docs(edayun): 补退货 / BOL / 物流产品 / 轨迹 / 条码的实测结论
README 新增五节,每节都包含「真机验证」小节与实际返回:
- 退货四接口:状态码表(来自列表文档)、时间窗是字符串、checkList 优先、
data=false 是仓方拒绝、详情三处文档类型不符
- BOL:与入库 BOL 的区别、11=已妥投、PR 无数据
- 物流产品:-998 是哨兵值、applicableBusiness 只能固定 1、各口径条数
- 物流轨迹:请求体是纯数组、「未匹配到轨迹」不是错误、上网/妥投时间口径
- 条码打印:与入库贴标的区别、本地提前挡的两条、四种纸张
库存一节补了真机结论:pageSize 静默截断到 500、页码越界重复返回最后一页、
safeStock 大量为 null、数字字段全是字符串。
TODO 从 37 条增到 67 条,主要新增:退货状态码表 / 行 id 缺失、BOL 状态码表、
物流产品码表与哨兵值、轨迹 eventStatus、条码 OSS 链接有效期。
Co-Authored-By: Claude <noreply@anthropic.com>
|
4 days ago |
chenchuchuan
|
d8b3bdec55
|
feat(edayun): 对接商品条码打印
POST /webApi/skuInfo/v2/printBarcode → WarehouseLabel
与入库 SKU 贴标(inbound().printSkuLabel)不是一回事:
- 那个绑定入库计划单、14 种小纸尺寸、异步返回任务号
- 这个按任意 SKU 打、4 档纸张、同步返回 PDF 地址
纸张集合完全不重叠,所以新建 BarcodePaperSize 而不是复用 SkuLabelSizeType。
新增 core 层 BarcodePrintCapable / BarcodePrintCommand / BarcodePaperSize,
能力位 BARCODE_PRINT,门面 printBarcodes(cmd)。
本地提前挡两条(仓方对这两条的返回都是「内部服务器错误」,看不出原因):
- SKU 数 > 50(仓方提示「最多打印50个SKU」)
- 份数 <= 0
isPrintSkuName 只在 true 时下发,false 交给仓方默认。
真机(2026-11-16):ybtest + A4 拿到真实 PDF;四种纸张尺寸都 code=200。
其余实测校验:缺 productInfos →「产品信息不能为空」、缺 pageSize →
「纸张尺寸不能为空」、pageSize 非法 / num=0 →「内部服务器错误」、
SKU 不存在 →「sku=XXX信息不存在」。
Co-Authored-By: Claude <noreply@anthropic.com>
|
4 days ago |
lml
|
8f7d703f2f
|
feat(hengjian): 对接入库计划详情 /v1/inbound/getInboundPlanInfo 与列表 getInboundPlanPage
- 两个接口回的对象字段完全一致,共用一份 DTO 与映射
- 详情:真机确认 orderNo 必填;单号既可是仓方计划单号也可是来源单号;
data 为空返回 null
- 列表:状态过滤转数字码,认不出的状态拒绝不猜;时间区间是单值字符串
"yyyy-MM-dd ~ yyyy-MM-dd";页大小上限 200 超限拒绝
- 新增 HengjianInboundStatus:计划单码表 0/5/6/8/10/15/20/25/70/100,
同时认数字串与中文名;收货单的 0/70/90 是另一套码表,不混用
- core 新增 InboundQuery(仓/状态/单号/三种时间窗/库存类型/shipmentId)
与 InboundCapable.queryInbounds() + 门面 queryInbounds();
InboundCapable.query(cursor) 共用同一实现
- 数量三层 plan/packed/received 直接搬运不重算;可售/不可售分开映射,
缺失时按可售兜底但总数一致
- 收货单 inboundOrderList 落成 INBOUNDED 阶段批次,库存类型保持 null
验证:mvn test 全量通过,恒健 238 个用例(+18)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
4 days ago |
chenchuchuan
|
6ba1cb408a
|
feat(edayun): 对接物流轨迹查询
POST /webApi/track/getTrackInfoList → List<TrackEvent> / TrackingInfo
请求体是纯字符串数组 [1Z111,1Z222],没有包装对象——文档把字段名留空了,
示例 [{"": [...]}] 是自动生成的占位,真机只有纯数组能通。
「未匹配到轨迹」按空结果处理:仓方回 code=500,但对调用方来说和
「运单刚生成、还没揽收」是同一件事,抛异常会让宿主无法区分真失败与还没轨迹。
track 返回空列表,trackShipment 返回 null;其它 500 仍抛。
TrackingInfo 新增 firstOnlineAt / deliveredAt:文档说「主要关注上网时间跟妥投时间」,
这两个是带时区的字符串(GMT-04:00),而节点时间是毫秒,同一响应里口径混杂。
字符串按 timeZone 解析,解析失败留 null;认不出时区按 UTC,不猜成仓所在时区。
真机(2026-11-16):文档示例单号、出库单里的真实跟踪号、账户流水里的 20 个单号
全部「未匹配到轨迹」,PR 环境没有可查到的轨迹,映射只有单测覆盖。
Co-Authored-By: Claude <noreply@anthropic.com>
|
4 days ago |
chenchuchuan
|
3c7ff77488
|
feat(edayun): 对接物流产品清单
POST /webApi/order/listByLogisticProductHasPerm → List<LogisticsProduct>
复用已有的 LogisticsProductCapable.products(),能力位 LOGISTICS_PRODUCT。
关键点:productId = -998 是「使用分物流规则」的哨兵值,不是真实产品,
映射时跳过——否则宿主的渠道清单里会多一个查不到的 id。
applicableBusiness 固定 1(店铺订单):统一模型不区分业务类型。
文档说 warehouseId 必填,实测不传会返回全账号的产品(162 条 vs 仓 2 的 36 条),
所以只在 providerWarehouseId 是数字时才下发。
统一模型只有编码 / 名称 / 是否跨国三个字段;易达云不回跨国标记,恒 false。
承运商类型、派单方式、面单获取方式、增值服务选项都只在 DTO 里。
真机(2026-11-16,仓 2):店铺订单 36 条、平台仓订单 23 条、退货单 35 条;
不传业务类型 37 条(含 -998);不传仓 162 条。-998 每次都出现,确认是哨兵值。
Co-Authored-By: Claude <noreply@anthropic.com>
|
4 days ago |
chenchuchuan
|
59aec58ffa
|
feat(edayun): 对接 BOL 查询(平台仓订单)
POST /webApi/fbaOrder/v1/getOrderBolList → List<BolDocument>
与入库 BOL 不是一回事:
- inbound().bols() 是头程入库计划单的文件地址(List<String>)
- 本接口针对平台仓 / 店铺订单,带提货状态、约定/实际提货量与 POD 签收凭证
方法名用 orderBols 而不是 bols:InboundCapable 已有同参数、返回值不同的方法,
同一适配器实现两者时擦除后无法区分。
新增 core 层 BolCapable + BolDocument,门面 orderBols(providerOrderNo),
能力位 BOL。
状态码表只有 11=已妥投 是文档确认的,其余按 statusName 中文名兜底,
认不出归 UNKNOWN 并把原值留在 rawStatus。
真机(2026-11-16):FBA473182144 返回 code=200 但 bolList=null,
PR 环境没有 BOL 数据,映射目前只有单测覆盖。
Co-Authored-By: Claude <noreply@anthropic.com>
|
4 days ago |
chenchuchuan
|
9e06b5873e
|
feat(edayun): 对接退货单创建 / 详情 / 取消 / 列表
四个接口:
- 创建退货单 POST /webApi/rma/info/v1/saveAndPublish(只支持 returnType=2 自行退回,
另三种要退货人地址或亚马逊单号,标准模型没有)
- 退货单详情 POST /webApi/rma/info/v1/getOrderDetail
- 取消退货单 POST /webApi/rma/info/v1/cancel
- 退货单列表 POST /webApi/rma/info/v1/selectRmaInfoList
统一模型侧:
- WarehouseReturnCapable.cancel 从 void 改成 boolean(返回值要能表达「仓方拒绝」),
目前只有易达云实现,改动安全
- queryReturns 签名从 (ctx, cursor) 改成 (ctx, ReturnQuery),
新增 ReturnQuery + ReturnQueryNoType(退货单号 / 出库单号 / 平台订单号)
- 门面 returns().query(ReturnQuery) / returns().cancel(providerReturnNo),
cancel 走幂等守卫
关键口径:
- 创建响应 data 就是仓侧 RMA 单号(运去哪只回 code/message)
- 取消响应 data 是布尔;code=200 + data=false 是仓方拒绝,抛异常而不是静默返回 false
- 列表时间是字符串 yyyy-MM-dd HH:mm:ss,按仓方时区解释,不是毫秒
- 列表只认单个 status,多状态本地拒绝并提示拆查询
- 详情明细优先 checkList(仓实际收到),没有才回落 skuList(买家预报)
- 状态码表来自列表文档:-1/0/1/2/3/4/5/6/7,之前只能按中文名猜
真机(2026-11-16,仓 2):列表返回 10 条 RMA,状态分布 -1/0/1/3/4/5/6 全部对上码表;
详情实测三处与文档不符——skuList.skuNum 文档标 string 实际 number、
valueAddedServices 标 number 实际字符串、picUrls 标 string 实际 JSON 数组,
DTO 已按真机类型调。创建 / 取消是写操作,未在真机执行。
Co-Authored-By: Claude <noreply@anthropic.com>
|
4 days ago |
chenchuchuan
|
8b3fa466af
|
fix(edayun): 库存 safeStock 缺失记 -1、出库单补保价映射
库存查询真机实测(500 行采样):
- safeStock 有 430 行为 null,原实现映射成 0,与「安全库存真的是 0」无法区分。
统一模型的约定是「仓方未给时为 -1」,改成 -1 并补两个用例。
- 其余数字字段虽然文档标 number,真机全是字符串("15499"),DTO 用 Integer
由 Jackson 自动转换,无需改动。
创建出库单:
- 文档的 addService 支持 is_insurance,标准模型有 OutboundLine.insuredAmount。
任意商品行带保价即整单下发 is_insurance(addService 是订单级开关,
易达云没有行级保价)。
顺带把 EdayunAdapterTest 的能力位断言改成「只断言恒有 / 恒无的能力」,
避免每加一个接口都要改它。
测试:EdayunInventoryTest +2、EdayunOrderTest +3。
Co-Authored-By: Claude <noreply@anthropic.com>
|
4 days ago |
lml
|
70ae09d7c8
|
feat(hengjian): 对接入库计划创建 /v1/inbound/createInboundPlan
- 新增 HengjianInboundCreateDtos + HengjianInboundMapper,实现
InboundCapable.create,声明 INBOUND
- 真机确认必填 orderNo / warehouseCode / inventoryType / productItems;
文档标必填的 currency 真机不校验,按选填实现
- 响应不回仓单号(只有 code/message),providerInboundId 保持 null,
不拿来源单号顶替
- 柜型按恒健的四个独立字段映射(20GP/40GP/40HQ/45HQ + 各自箱号);
认不出的柜型直接拒绝,静默丢弃等于少报柜数
- 装箱信息映射 cartonItems(尺寸 cm / 重量 g),空则不传
- 入库查询 / 分页未接,显式抛异常而非返回 null
- core InboundCommand 补 6 个恒健协议字段(documentStatus / purchaseOrderNos /
actualShipDate / goodsType / shippingCompanyName / containers),
其它仓不读,行为不变
验证:mvn test 全量通过,恒健 220 个用例(+17)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
4 days ago |
lml
|
d126757e80
|
feat(hengjian): 对接库存查询 / 批量分页 / 库存变动流水
三个接口真机均确认存在(无 token 时返回各自的 Unauthorized 文案,
与 404 对照组可区分)。
按 SKU 查 /v1/inventory/getInventory、批量分页 /v2/inventory/get_inventory_by_page
- 恒健有两个库存接口且能力不同,统一模型只有一个 query(),按条件分流:
给 providerSkus 走按 SKU(不分页),只给 warehouseCodes 走分页
- 两个都给 → 拒绝(恒健无此接口);都不给 → 拒绝(不退化成整仓全量);
给 updatedAfter / inventoryType / includeZeroStock → 拒绝(不支持)
- 分页接口 rows 上限 500(文档明写),超过拒绝不截断
- 字段名两套:字段表写 snake_case、示例写 camelCase,DTO 用 @JsonAlias 同时接住
- data 形状两套:对象(含 content)与数组,用 JsonNode 判形状后分流
- updatedAt 缺失时报错而非填 EPOCH——快照时间是对账对齐依据
- syncStrategy = FULL_PULL_DIFF:两个接口都没有增量入参
库存变动流水 /v1/inventory/task/query
- 真机确认 skus / beginDateTime / endDateTime 必填,缺项回 MethodArgumentNotValidException
- 日期跨度按「含首尾」口径算:10-01~10-30 合法(30 天),10-01~10-31 非法
- rows 上限 100(文档明写)
- 新增 core 模型 InventoryMovement / InventoryMovementQuery / queryMovements()
- changeQty 按原值保留不转符号;单据类型与变动方向保留仓方原文不归一
- 单行缺 sku / createTime 时跳过该行而非整页失败
验证:mvn test 全量通过,恒健 203 个用例(+23)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
4 days ago |
lml
|
73892d6052
|
feat(hengjian): 对接运费测算与地址属性识别
两个接口都在 /v2/api/shipping 下,真机均确认可用(无 token 时的
参数校验响应与 404 对照组可区分)。
运费测算 /v2/api/shipping/calculate
- 真机确认必填项是包裹四项 + 两个单位 + 收货方五项;文档标必填的
shipper* 系列实际可不传
- 单位 cm/g 与统一模型一致,不换算
- 包裹尺寸在恒健是 INTEGER,厘米值四舍五入(截断会让报价偏低)
- totalRate 取 conversionTotalRate(折算价 / 客户实付),
不取 originalTotalRate(承运商牌价)
- 恒健不按仓返回,统一结果只有一个实例,仓编码用账户仓填充
地址属性 /v2/api/shipping/addressClassification
- 新增能力位 ADDRESS_CLASSIFICATION + AddressClassificationCapable
+ core 枚举 AddressType(BUSINESS/RESIDENTIAL/MIXED/UNKNOWN)
- 真机确认 street1/zip/city/state/country 五项必填,本地先挡
- 认不出归 UNKNOWN 不猜;MIXED 在 residential() 里按住宅计
- 文档域名写的是 open-api.thebizark.com(别家),真机确认本仓域名可用
顺带修 core 缺陷:FeeEstimateQuery.logisticsServiceCode 原为构造期必填,
而恒健允许不传(由仓报全部渠道)。改为选填,并新增 hasLogisticsServiceCode();
运去哪要求必填,改为在它的 mapper 里校验,不影响既有行为。
验证:mvn test 全量通过,恒健 180 个用例(+14)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
4 days ago |
lml
|
a4c38a4408
|
feat(warehouse): 补齐文档有而模型缺的入参,恒健已接接口全部可传
对照恒健接口文档逐个核对后,发现上一轮只修了「有字段但不生效」,
还有一批「模型里压根没字段、调用方传不进来」。这次补齐:
OutboundCommand(下单,5 项 + 附件列表)
- paidAt / pickupTime / directFulfillment / thirdPartyAccount / warehouseRemark
- warehouseRemark 与 remark 是两个字段:前者给仓作业看(恒健 warehouseRemark),
后者是客户备注(customerRemark),不能合并
- attachments: List<WarehouseAttachment>,支持 URL 与 base64 的通用附件,
与平台面单快捷入口 labelContentBase64 并存
- WarehouseAttachment 补 contentBase64(下发用;查询回来恒为 null)
OutboundQuery(列表查询,5 个维度)
- channel / channelAccount / poNo / providerOrderIds / updatedAfter+updatedBefore
- updatedAfter/Before 是独立的更新时间窗,与创建时间窗 after/before 分开——
增量同步按更新时间更准
WarehouseProduct(商品建档,2 项)
- imageUrls:产品测量图(复核长宽高),不是商品主图 imageUrl
- specialOuterPackaging:特殊外包装布尔开关,不是 packageStyle 三选一
二者原先被判为「语义不同不能顶替」直接丢弃,现在各有独立字段
恒健侧同步映射,并对不完整的附件(缺 name/type/url+base64)本地拒绝。
验证:mvn test 全量通过,恒健 166 个用例(+9)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
4 days ago |
lml
|
53c296c12f
|
fix(warehouse): 排序/分页/仓过滤改为可配,停止静默吞参数与静默截断
审计恒健已接接口时发现的四类问题,一并修正:
1) sort 被写死成 desc。文档里 sidx「可写死 id」、sort 明确是 asc/desc 两值,
而 OutboundQuery 根本没有排序字段,调用方无处表达。
→ core 新增 SortDirection 与 OutboundQuery.sortField / sortDirection;
恒健未指定时用文档默认(sidx=id、sort=desc),指定则透传。
2) 静默吞参数:orderRef / providerSku / noType 传了不生效也不报错。
→ 三者均改为显式拒绝(与同方法里 statuses 的处理一致)。
3) 静默截断:rows 超 100、计费 size 超 200 被悄悄改小,
调用方按自己的 pageSize 判末页会误判「还有下一页」,导致漏账。
→ 改为超限直接报错。rows=100 是文档明写上限;size=200 是我编的保守值,
已在注释标注待真机确认。
4) 计费仓过滤写死账户仓。恒健接口参数本就是复数 orgWarehouseCodes,
写死会让调用方无法表达「全部仓」或「其中几个仓」。
→ FeeQuery 新增 warehouseCodes(与 InventoryQuery 同口径),
非空用调用方的,空才退回账户仓。
验证:mvn test 全量通过,恒健 157 个用例(+8)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
4 days ago |
lml
|
456834ea2c
|
Merge remote-tracking branch 'origin/master'
|
4 days ago |