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>
|
1 day 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>
|
2 days 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>
|
2 days 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>
|
2 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>
|
4 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>
|
4 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>
|
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>
|
5 days ago |
lml
|
fa9bfd71ba
|
refactor(warehouse): 必填校验从模型下沉到各仓适配器
统一模型此前把运去哪的协议要求(packingType、两个预计日期、调拨出库必须给
shipTo)写进了构造期校验,接第二家仓时会被第一家的约束卡住:信仓既没有
packingType 字段、转运也只有发货日期并用仓库名代替地址,调用方却必须给这些
无意义的值才能构造命令。
改成按仓校验:
- WarehouseProduct:packingType 不再是构造期必填(-1 表示未给)
运去哪的必填校验移到 YqnProductMapper
- TransferCommand:预计到仓日期与 shipTo 不再是构造期必填
运去哪的必填校验移到 YqnTransferMapper
保留跨仓共识的一致性校验(给了两个日期才比较先后)
- 信仓侧无需改动:它的必填项(deliveryMode / deliveryWay / palletRequired /
预报头字段)本来就在适配器里校验
对运去哪调用方的影响:缺少这些字段仍然报错,只是从构造期的
IllegalArgumentException 变成调用时的 IllegalArgumentException(mapper 抛出),
错误信息里带仓方字段名,更明确。
顺带修探针里因模型放宽才暴露的问题:
- 写探针不再给 omsSku 硬编码 "1"、不再给转运编造 PROBE-SKU / PROBE-DEST / 假地址,
缺 sku 或 destWarehouse 时直接跳过
- 转运探针不再传 estimateInboundDate / shipTo(信仓不收,也能验证模型已放宽)
- 基座里的 requireProperty 与凭据默认值恢复为「空值 + 必须由 -D 传入」
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
30758c7acb
|
fix(yqn): 结算明细单号口径 + 测试跟随真机行为
结算明细(costs/detail)的 saleOrderNo 要的是<b>数字单号</b>,即创建出库单
返回的 providerOrderId(实测 200171697),不是我们下发的来源单号。真机用
PROBE-xxx-OUT 去查会被适配器拦下。
- FeeQuery.saleOrderNo 的 Javadoc 写清口径,并说明传非数字会被拒绝
- 适配器报错信息补上出处(providerOrderId returned by saleOrder/create)
- 探针的结算明细改为读 -Dyqn.probe.saleOrderNo,不再复用出库单号
真机验证:用 200171697 查询返回 0 条(该单刚创建,还没产生费用),
接口本身通。
测试跟随真机行为更新:
- 物流产品:URL 参数名从 query.warehouseCode 改为 warehouseCode
- 仓库目录:成功 status 从 1 改为 200
全量 488 个测试通过(yqn 163 个)。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
0b8d687984
|
fix(yqn): 运费试算的信封兼容 + 全链路探针(真机验证)
真机验证发现 运费试算(POST /v1/saleOrder/calculate)与仓库目录一样,
响应没有 code 字段,只有 status=200 / message=success。原来走 execute()
(强制要求业务码 200),把成功当失败了。
把「容忍式信封」抽成通用实现:
- requireEnvelopeTolerant:有 code 按 200 校验,没有则看 status==200
(实测成功是 200,不是文档示例的 1)
- executeTolerant:非 2xx 仍交给 YqnEnvelope 分类,2xx 才走容忍判定
- 运费试算改用 executeTolerant
新增 YqnFullFlowProbeTest(15 步,按 @Order 串链路):
出库创建 → 详情 → 取消;库存;试算;结算明细;入库创建 → 查询 →
箱标 → SKU 标;调拨;退货;销毁;商品建档。
默认跳过,需 -Dyqn.probe.all=true + token,仅限 PR 环境。
真机结论:
- 出库全链路通(创建 / 详情 / 取消),且 UNSHIPPED 正确映射为 SUBMITTED
- 调拨 totalWeight=1000.0(1 件 500g)→ 单位确认是 kg,不是 lb
- 入库创建 → 查询通,能拿到计划单号
- 箱标 / SKU 标:仓方内部接口 Read timed out(他们那边的问题,非我们的报文)
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
05063853d1
|
fix(yqn): 真机联调发现三处参数名/成功码错误
用 pr 环境(RF_NY_US)跑只读探针,三处与文档不符:
1. 库存查询(get_inventory_by_page):参数名不该带 query. 前缀。
实测 400 "Required List parameter 'warehouseCodes' is not present",
说明仓方按扁平参数名取:warehouseCodes / inventoryType / rows / page。
之前照文档写的 query.warehouseCodes 被忽略。
2. 物流产品(getCarrierGroupList):同上,应为 warehouseCode 而非
query.warehouseCode,实测 400 "Required String parameter
'warehouseCode' is not present"。
3. 仓库目录(warehouse/findAll):实测 status=200 / message=success 才是
成功,不是文档示例里的 status=1。原来按 1 判定,把成功响应当失败。
另外给 YqnEnvelope 的 4xx 错误补上响应体:之前只报 http 400,看不到
仓方给的 message,排查全靠猜。
修完三个只读接口全部跑通:库存 2 条、仓库 1 个、物流产品 100 个。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
38db00cd4d
|
test(yqn): 新增只读联调探针 YqnReadOnlyProbeTest
运去哪之前只有单元测试(RecordingTransport 打桩),没有真机验证。补一个
只读探针,默认跳过,需显式开启:
mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \
-Dyqn.probe=true -Dyqn.probe.token=<x-api-key> \
-Dyqn.probe.providerWarehouseId=RF_NY_US \
-Dtest=YqnReadOnlyProbeTest test
覆盖 7 个查询接口:
- GET /v1/warehouse/findAll 仓库目录(不依赖单号)
- GET /v2/sysCarrierGroup/getCarrierGroupList 物流产品(验 GET+query 参数)
- GET /v2/inventory/get_inventory_by_page 库存(验分页与下划线字段名)
- POST /v1/warehouse/operation/costs/detail 结算明细(需 saleOrderNo)
- POST /v1/saleOrder/findOne 出库详情(需 outboundOrderNo)
- POST /v1/inbound/getInboundPlanInfo 入库计划(需 inboundOrderNo)
- POST /v3/saleReturn/getInboundPlanInfo 退货计划(需 returnOrderNo)
- GET api/v2/orderShipment/track/{no} 轨迹(需 trackingNo)
**不碰任何写接口**:下单 / 建入库 / 建调拨 / 建退货 / 销毁都会真实创建单据,
没有测试环境,一律不跑(遵守 feedback-no-live-write-tests)。
安全:
- 凭据只走系统属性,不入库
- 输出打印 token 掩码(前 4 + 后 2),不打印完整 token
- 只打印字段摘要,不打印完整报文(可能含 PII)
异常只打印不抛出,一次跑完便于对照真实报文。全量 162 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
7fd5bb43df
|
refactor(warehouse): OutboundQuery.providerOrderId → outboundRequestNo
原名有误导:这个字段装的从来不是仓内部 id,而是我们下发的来源单号
(outboundRequestNo)。运去哪创建订单(API 123)返回的 data.orderId 是
内部数字 id,只能用于列表/关联,不能作为详情查询(API 128 findOne)的入参。
改名后语义与 OutboundOrder.providerOrderId(真正的仓侧 id)明确区分。
调用方需同步改:query(OutboundQuery.builder().outboundRequestNo(...))。
全量 486 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
a267d67bac
|
feat(yqn): 批量补齐「仓方有、模型没有」的字段
按「仓方给了就加,并标注来源字段」补齐四类:
1. 创建入库计划(API 97)请求侧 11 个字段,之前完全没下发:
lineCode / shipmentId / referenceId / attachInfoItems / transportType /
deliveryType / goodsSize / tmsNos / carrier / socFlag / palletFlag。
其中 attachInfoItems 意味着之前入库单无法随单传附件(面单/装箱单/BOL)。
tmsNos 运去哪是逗号分割的字符串,出参用 List 承接。
2. 查询入库计划(API 101)响应侧 10 个字段:
lineName / shipmentId / referenceId / shipmentNo / goodsType /
actualShipDate / cartonTotalWeight / cartonTotalVolume / 四种柜型数量与柜号。
柜型新增 InboundOrder.ContainerInfo(GP20/GP40/HQ40/HQ45 + 数量 + 柜号 +
仓方原值),只对给了值的柜型产对象。
3. 商品(API 115)11 个字段:
expirationControl / expirationDate / packedQty / packedLength/Width/Height/
Weight / isInsuranceFlag / isInsuranceRate / snMgmtMode / lotControl。
顺带修海关币种:之前把申报额无脑贴成 USD,非美元会被静默算错;
现在非 USD 直接拒绝,由调用方换算。
4. 物流轨迹(API 189):
parcel 实重实尺(oz/inch 统一换算成 g/cm 后落模型,宿主不用各仓换算)
+ carrierDetail 的承诺送达日期 / 始发地 / 目的地。
另把 WarehouseReturn.Attachment 合并为通用 WarehouseAttachment,
与出库/入库附件统一。
新增 YqnExtraFieldsTest(9 个)。全量 486 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
9b6f1bf7c6
|
feat(yqn): 补齐订单详情的附件 / SN / 行金额等字段
订单详情(POST /v1/saleOrder/findOne)仓方一直给了这些字段,模型没接、
mapper 没读。按「仓方有、我们没有就加,并标注来源字段」补齐:
新增通用模型:
- WarehouseAttachment:单据附件(name / type / url / packageNo)。acc
type 保留仓方原值,不做跨仓归一(装箱单与发货计划归一会混)
- SerialNumber:序列号(snCode / lineNo / providerProductId /
deliverOrderItemId),售后追溯与召回靠它
OutboundOrder 新增(均标注运去哪来源字段):
- attachments ← enclosure[]
—— 之前 PackageResult.labelRef 恒为 null 的根因就是这里没映射
- serialNumbers ← orderSnInfo[].snList[]
- signatureRequired ← isSignature(null 表示仓方未给,不是「否」)
- insured ← isInsure
- thirdPartyAccount ← thirdPartyAccount
OutboundLine 新增:
- totalAmount ← skuAmount(行总金额,与请求侧的单价×数量对称)
- insuredAmount ← insureAmount
- platformOrderItemIds ← ordList[].skuOrdList[](按 SKU 关联)
- batchNos ← batchInfo(计划与出库批次按 key=value 去重)
PackageResult 新增:
- cost ← shipmentPackages[].cost
仓储层 WarehouseReturn.Attachment 与新的 WarehouseAttachment 结构重复,
下一轮合并。
新增 YqnOrderDetailExtrasTest(8 个)。全量 477 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
208b549c96
|
feat(yqn): 接入销售退货计划查询,退货链路闭环
新增 API 83(POST /v3/saleReturn/getInboundPlanInfo)。这个接口补上了
退货链路的关键缺口:saleReturnOrderItems[].id 就是退货条目处理(API 77)
要求的明细行 id,之前没有任何途径能拿到。
链路现在是:
创建退货(API 81)
→ 退货入库完成回调(API 142,通知处理结果)
→ 退货计划查询(API 83,拿明细行 id)
→ 退货条目处理(API 77,按行设置处理方式)
模型变更:
- WarehouseReturn.status 从 String 改为 ReturnStatus 枚举(新增底层枚举:
草稿/待审核/审核拒绝/退货中/待收货/已完成/已关闭/UNKNOWN);仓方原值仍在
rawStatus。运去哪的状态是中文文本,按完整值精确匹配,未知归 UNKNOWN
- WarehouseReturn 补头级字段:actualReceivedAt / inspectedQuantity /
relatedProcessNo / lineName / attachments
- ReturnLine 补:lineId(API 77 操作键)、inventoryType、processedQuantity、
suggestedDisposition、newSku、pictureUrls、remark
顺带修正 toCreated:status 之前硬编码字符串 "SUBMITTED",现在为 UNKNOWN
——创建接口不回状态,真实状态要查 API 83 才知道。
新增 YqnReturnQueryTest(9 个):头级字段、明细行 id、行明细、附件、
状态枚举全量映射、未知状态、空 data、空单号拒绝。
全量 421 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
1805bbdf94
|
fix(yqn): 入库批次区分计划/上架;退货回调补批次字段
入库查询(getInboundPlanInfo):
仓方分两段给批次——planBatchItems 是预报装箱、inboundBatchItems 是实际
上架。原来合并进同一个列表且不标来源,同一 SKU/箱会出现两条数量不同的
记录(计划 60 / 实收 58),宿主无法判断哪条是计划、短少核对失真。
InboundOrderBatch 增加 Phase 枚举(PLANNED / INBOUNDED)。
退货入库回调(API 142):
items[].batchParamNo(批次号)与 batchParam(批次属性)之前完全丢弃,
退回货品的批次/效期无法回填库存。ReturnLinePayload 增加 batchNo 与
batchParams。换标上架场景仓方不传 batchParam,为空列表属正常。
测试:入库批次阶段断言、退货回调批次字段断言。
全量 412 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
732d77cac0
|
fix(yqn): 时区改由调用方传入;申报额按行总额下发
时区(影响所有时间字段):
原来 zoneOf 硬编码 Asia/Shanghai,运去哪仓在美国,所有本地时间被整体
平移 13–16 小时。改成:
- WarehouseConnection 增加可选 zoneId,由 OMS 显式传入
(账户时区不一定有,且同一 provider 多仓可能跨时区,SDK 不做地理推断)
- 未指定时按 UTC 解释,不再猜成北京时间
- WarehouseContext.zone() 暴露给适配器;各 mapper 的 DEFAULT_ZONE 统一改 UTC
- 下发时间(latestShipDate / estimatedDeliveryTime)也按该时区格式化,
原来按上海格式化,仓按所在地解释会跨日
申报金额:
运去哪 createSaleOrder 的 skuAmount 是「当前 SKU 总金额」,我们原来只传
单价、没乘数量,整单申报额少算 quantity 倍。改为 单价 × 数量。
OutboundLine.declareValue 的 Javadoc 明确「语义是单价」。
测试:
- YqnAdapterTest 默认时区断言从 UTC+8 改为 UTC
- 新增 usesConnectionZoneWhenProvided:纽约仓 09:00 → 14:00Z
全量 411 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
de11a900af
|
fix(yqn): 修 P0 状态误判 + 三处回调数据丢失 + 结算/库存口径
全链路审计(18 个接口逐字段比对)后的第一批修复。
P0:
- YqnOutboundStatus 用 contains("SHIP") 匹配,UNSHIPPED(未发货)被判成
SHIPPED(已交运)。下游会认为货已发出,checkCancel 直接 BLOCKED。
改为按 API 128 的文档枚举精确匹配(canceled/shipped/picked/approved/
assigned/unshipped/pending),未收录值归 UNKNOWN。测试固化 UNSHIPPED
不再命中。
P1(回调数据丢失):
- API 154 业务单据变动:orderNoStatus / orderNoStatusDesc 完全没带出去,
只剩「有变化」通知。WarehouseCallback 增加 rawStatus 字段,与
rawEventType 里的单据类型一起解释(同一个 5 在四套码表下含义不同)
- API 142 退货入库:processMode=3(不良品上架)与 5(良品上架)都映射
RESTOCK,不良品被报成良品。core 新增 RESTOCK_UNSELLABLE(50)
- API 150 库存变动:opLabel 缺失或未知时默认判出库,入库流水可能被反向
扣减。InventoryPayload.inbound 改为 Boolean,未知返回 null
P1(口径):
- API 133 结算:settlementType 为 null 时被当作「实际结算」,正踩
Javadoc 警告的反向风险。改为「只有 1 才是实际,其余一律按预估」
- API 107 库存:warehouseCode 回退用的是仓方编码,与出库/入库单的 OMS
编码口径不一致;asOfUtc 缺省时用 Instant.now() 而非注入的 clock
全量 410 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
0e539ce12a
|
feat(yqn): API 81 补 lineName;确认 code 为字符串形态
两处按文档对齐:
1. lineName(项目名称,非必填)之前没有标准字段,直接丢弃。
ReturnCommand 增加 lineName(),YqnReturnMapper 下发。仓方按项目分账 /
路由时缺这个字段会走默认项目,属于静默偏差。
2. API 81 的响应 code 是 **string**("200"),多数接口是数字 200。
现有 YqnEnvelope 用 stringAt 读再转整数,两种形态本来就能识别——
但此前没有测试锁定这个行为,改严格数字解析会把退货创建打挂。
新增 YqnEnvelopeTest(11 个)覆盖:
数字码 / 字符串码 / 带空白字符串码 / 数字失败码 / 字符串失败码 /
缺码 / 非数字码 / 空 body / 401 / 429 / 503
全量 406 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
80f8097186
|
docs(yqn): 标注 API 77 实际不可用(拿不到明细行 id,处理方式由仓侧决定并经回调通知)
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
1f5e6334c6
|
feat(yqn): 补全 API 101 入库计划响应 + 补测试
按你提供的完整文档核对出入参,补齐之前缺的部分:
API 101 响应侧(之前只映射了 22/40 个字段):
- 头级三层数量 planQty / packedQty / receivedQty → InboundOrder 新增
plannedQuantity / packedQuantity / receivedQuantity。之前只有行级,
头-行交叉校验(短少 / 溢装定位)做不了
- batchInfo(计划批次 + 上架批次)→ 新增 InboundOrderBatch,含箱唛号与
库存类型。注意与下发的 InboundBatch 不是一回事:那个是请求侧、
这个是回查侧
- boxInfo(每箱装了哪些 SKU、计划量与上架量)→ 新增 InboundOrderBox
- packingLabelUrl → 原样带出,Javadoc 注明仓方称将改为异步箱标任务
createdAt 确认运去哪不提供(文档无该字段),维持 null 并已标注。
测试补充:
- YqnInboundPlanTest(9 个):完整响应逐字段断言、可选段缺失、未知状态
归 UNKNOWN、按单号查、空单号拒绝
- WarehouseWebhookSdkTest(9 个)+ FakeWebhookAdapter:门面 sdk.webhook
按 provider 分派、不依赖仓账户、验签失败不进 parse、未注册 provider、
无 WEBHOOK 能力、解析结果透传
顺带修:sdk.webhook 传 null secret 时 WarehouseConnection 构造抛 NPE,
改为给空凭据,是否可用由适配器验签决定。
全量 395 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
56e3406f7c
|
feat(yqn): 补齐另外三个回调:单据变动 / 退货入库完成 / 库存变动
四个回调共用同一套验签(appKey|timestamp|rawBody 的 HMAC-SHA256),
但报文结构不同。运去哪不按路径区分回调,因此在适配器里按报文特征分派:
含 processMode → 退货入库完成(142);含 opType → 库存变动(150);
含 orderNoType → 业务单据变动(154);否则按面单购买成功(149)。
出参改造:
- 新增 WarehouseEventType 底层枚举(LABEL_PURCHASED / ORDER_STATUS_CHANGED /
RETURN_INBOUND_COMPLETED / INVENTORY_CHANGED / UNKNOWN),调用方按它分派;
eventType 从 String 改为枚举,仓方原值另存 rawEventType
- 新增 InventoryPayload:库存推送是增量流水,quantity 恒为正、方向由
inbound 布尔表达,避免调用方按符号猜测;providerOperationType 保留仓方
单据类型码(100 销售出库等)
两处容易出错的地方已在实现里注明:
- API 154 的 orderNoStatus 含义随 orderNoType 变化(入库计划 / 调拨 /
销售出库 / 退货认领四套码表),所以 rawEventType 里带上类型,不单独解释状态
- API 142 的 processMode 与 API 81 的预约处理方式码值集合不同,映射到
ReturnProcessDisposition 时只用 142 的码表(2 销毁 / 3 不良品上架 /
4 换标上架 / 5 良品上架);3 与 5 都归 RESTOCK,因为底层枚举没有区分良品与否
API 142 的回调里 items 没有明细行 id,所以 lineId 仍为 null——API 77
(退货条目处理)的操作键依然拿不到,这条链路还没闭环。
新增 YqnCallbackParsersTest(9 个)。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
4eb15bd91a
|
feat(warehouse): 回调链路 —— 按 provider 的 SDK 入口 + HMAC 验签 + 统一出参
回调是仓方主动推送,SDK 不监听端口:OMS 暴露 HTTP(如 /user/callback/yqn),
取到 headers 与原始 body 后交给 SDK,SDK 只做「验签 + 解析」。
三处新增:
1. 入口 WarehouseSdk.webhook(provider, secret, headers, rawBody, nowMillis)
原来只能 warehouses(warehouseCode, conn).parseWebhook(...),但回调进来时
只有 provider、没有 warehouseCode。新入口按 provider 分派,不查账户。
2. 出参 WarehouseCallback
原 WarehouseEvent 只有 5 个字段,装不下退货的明细行 id / 处理方式,
也装不下入库实收量。改为「公共头 + 按业务分型载荷」:outbound / returns /
inbound 三个可空字段,按 eventType 取用;rawBody 原样保留供回溯。
提供指纹方法供宿主去重(报文无事件 id 时使用)。
3. 验签能力 WebhookSignatures
HMAC-SHA256 + Base64、恒定时间比较(避免时间差泄漏签名前缀)、
时间戳窗口校验、大小写不敏感的取头。
运去哪面单回调(API 149)实现:
signature = Base64(HmacSHA256(appSecret, appKey|timestamp|rawBody))
头:X-AppKey / X-Timestamp / X-Signature
时间戳单位文档未写明,按位数兼容秒与毫秒(<=10 位按秒),联调后收紧。
新增 YqnLabelCallbackParserTest(10 个):验签通过 / 篡改 body / 错误密钥 /
缺头 / 时间窗过期 / 头名大小写 / X-AppKey 回退 / 载荷解析 / 指纹 / 时间戳单位。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
3d17a27c3f
|
refactor(yqn): 把 YqnDtos 按接口拆成独立文件
原来 1174 行的单个 YqnDtos 装了 63 个内部类,18 个接口的报文混在一起,
改一个接口要在上千行里翻找,共用结构(BatchAttr 之类)也会被误当成
「跨接口共享类型」。
拆成 18 个文件,一个接口一个:
YqnCreateOrderDtos / YqnOrderDetailDtos / YqnCancelOrderDtos / YqnProductDtos /
YqnFeeDetailDtos / YqnInventoryDtos / YqnCreateInboundDtos / YqnInboundPlanDtos /
YqnTransferDtos / YqnCreateSaleReturnDtos / YqnReturnProcessDtos /
YqnFeeEstimateDtos / YqnTrackingDtos / YqnDestroyPlanDtos / YqnBoxLabelDtos /
YqnSkuLabelDtos / YqnLogisticsProductDtos / YqnWarehouseDtos
拆分原则:
- 每个文件只放该接口的请求 / 响应与内嵌子结构
- 跨接口重复的结构**各自复制一份**(如 BatchAttr 在入库与调拨里各有一份),
避免因共用而被迫一起改
- 保留每个类的 @JsonInclude(NON_NULL):它决定空字段是否出现在报文里,
拆分时漏掉会让请求多出 null 字段(测试已验证并修复)
顺带修一处:TransferMapper 引用的是入库的 BatchAttr,拆分后类型不兼容,
改为使用调拨自己的 BatchAttr。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
9c814851dd
|
docs(warehouse): 标注运去哪不提供入库单创建时间 / API 101 只支持按单号查
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
4184b5aeaa
|
fix(yqn): 修复出库链路四处参数丢失 / 语义错误
逐字段审计「标准出入参 ↔ 运去哪出入参」后发现的问题,只修能明确判定为
bug 的,不涉及模型结构调整:
1. 平台面单文件从未下发
OutboundCommand.labelContentBase64 无任何映射,attachInfoItems 整类
从未被构造。结果是 labelMode=PLATFORM_LABEL 校验通过、面单一个字节
都没发,仓没有面单可打。现在映射为 attachInfoItems(type=0 面单),
去掉 data URI 头、从 MIME 取 fileType;单包裹时带 packageNo。
同时加了「PLATFORM_LABEL 必须给面单内容」的校验,只声明模式不给文件
会直接拒绝,不再静默失败。
2. 声明了 SPLIT 但没有对应字段
运去哪下单接口没有拆单字段,splitOrder 无法下发,却声明了
WarehouseCapability.SPLIT。撤掉该能力位,避免调用方以为能控制拆单。
3. 出库查询把 orderRef 当来源单号
query() 用 firstNonBlank(providerOrderId, orderRef),而 API 128 只按
来源单号查;orderRef 是平台单号,传进去查不到或查错单。现在只接受
providerOrderId,并在报错里说明原因。
4. 回查路径上 OutboundOrder 三个字段恒空
providerOrderId 在 API 128 里没有(只有 API 123 创建时返回),
labelMode 与 requestedAt 也不回传。labelMode 之前直接走构造器默认值
WAREHOUSE_LABEL,会把平台面单订单报成仓面单。改为由调用方显式传入
(get/query 传 null 时按仓自有面单兜底),并给 PackageResult 补
carrierCode(包裹级承运商 code,之前只映射了名称)。
5. 顺带补上现成落点没赋值的两个字段
shopName → channelAccount、sfp → isPrime(1/2),之前 DTO 有字段
却从不 set,多店铺与 SFP 场景静默失效。
文档补充:
- InventoryCapable.query / OutboundQuery.orderRef 标注「并非所有仓支持,
过滤可能不生效」,按 SKU 过滤目前在 YQN 侧完全未实现
新增 YqnOutboundPayloadTest(9 个)覆盖面单附件、data URI、两种面单模式、
店铺/SFP、查询语义、SPLIT 撤销。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
08b982d8a6
|
fix(yqn): 调拨单补齐响应字段并修掉 sourceNo 缺失导致创建失败
API 139 的创建响应有 80 多个字段,之前只取了 9 个,调拨失败时
errorCode / errorReason 直接丢失——status 只告诉你「已驳回」或
「取消异常」,具体原因查不到。补上:
- errorCode / errorReason + hasError() 便捷判断
- orgWarehouseTitle / inOrgWarehouseTitle(调出/调入仓名称)
- carrierCode / totalWeight / totalVolume
- TransferOrder 新增字段全部加 Javadoc 说明「缺失时为 null」
顺带修一个真实 bug:响应不回填 sourceNo 时,toOrder 直接把 null 传给
TransferOrder.transferRequestNo,构造期抛 IllegalArgumentException。
sourceNo 同时是幂等键,不能为空——改为回落到请求侧的 transferRequestNo。
新增 YqnTransferTest 覆盖:出库调拨带 shipTo、响应字段映射、
异常字段、未知状态归 UNKNOWN、type 取自请求侧。
单元体积单位运去哪未标明,按 kg / m³ 命名但不做换算,Javadoc 注明。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
a64352225a
|
feat(yqn): 按 API 134 对接仓库目录查询
新能力 WAREHOUSE_DIRECTORY:同步仓方名下可用仓的基础档案,
为库存 / 订单 / 调拨等接口提供合法的 warehouseCode 来源。
- WarehouseInfo:仓 code / 名称 / 国家州城市 / 地址 / 邮编 / 联系人 / 电话 / 邮箱
与 spi.WarehouseAccount 分开:那个是宿主接入配置(含凭证引用),
这个是仓方主数据。两者靠 warehouseCode 对上
- WarehouseDirectoryCapable.warehouses(ctx),门面 sdk.warehouses(...).warehouses()
- 只读主数据,不走幂等;空清单按「无可用仓」返回空列表,不当错误
**信封不同,单独处理**:这个接口的响应文档只有 status / message / data,
没有 code,而 YqnEnvelope 要求业务码存在且为 200——直接复用会把成功响应
判成失败。改为:有 code 时按 200 校验,没有则退回看 status==1。
两个分支都有测试覆盖。
PII 提示写进模型 Javadoc:联系人 / 电话 / 邮箱需按宿主安全策略处理。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
b67caf0c46
|
feat(yqn): 按 API 135 对接物流产品(承运商渠道)清单查询
新能力 LOGISTICS_PRODUCT:下单 / 试算前校验渠道可用性用。
- LogisticsProduct:产品 code / 名称 / 是否跨国 + 来源仓与 provider
- LogisticsProductCapable.products(ctx, warehouseCode),门面
sdk.warehouses(...).logisticsProducts(warehouseCode)。默认实现抛不支持,
信仓无此接口不受影响
- 只读主数据,不走幂等;空清单按「该仓无可用渠道」返回空列表,不当错误
两处按既有约定处理:
- 文档把 query.warehouseCode 写在「Body 参数」里但方法是 GET,与库存接口
(API 107)同样按 query 参数下发
- warehouseCode 显式指定优先,其次账户配置;两者都没有时拒绝,
不发空值请求
crossCountry 缺失时按「非跨国」处理,不猜成跨国。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
c3716f6160
|
feat(yqn): 按 API 100 对接打印入库计划单 SKU 标
补齐上一提交预留的 SKU_LABEL 能力位。
- SkuLabelCommand:仓侧单号 + 来源单号 + 导出方式 + 尺寸 + 原产地 + 四个显示开关
- SkuLabelSizeType:14 种小尺寸(40×30 … 100×100),映射为运去哪
labelSizeType 1..14。**不复用箱标的 LabelSizeType**:箱标只有 3 种尺寸
(100×100 / 100×150 / 104×98),SKU 标是 14 种,两者取值集合几乎不重叠,
合一个枚举会让「每页数量联动」那套约束套用到 SKU 标上
- YqnSkuLabelMapper 复用 YqnBoxLabelMapper 的 downloadMode 语义(1 压缩包 / 2 PDF)
- InboundCapable.printSkuLabel 默认抛不支持;门面 inbound().printSkuLabel(cmd)
沿用文档给出的默认值:中文默认不显示,二维码与 ERP_SKU 默认显示。
原产地上送前统一大写,空白按「不打印」处理并省略该字段。
同样是异步任务:只返回 taskNo,label() 恒为 null。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
948ff1a96d
|
feat(yqn): 按 API 99 对接打印入库计划单箱标
新增 BOX_LABEL 能力位与 SKU_LABEL(后者预留,本期未接)。
- BoxLabelCommand:仓侧单号 + 来源单号 + 导出方式 + 尺寸 + 每页数量 + 两份 +
展示客户码
- LabelDownloadMode(压缩包 / 单个 PDF)、LabelSizeType(100×100 / 100×150 /
104×98)、LabelsPerPage(1 / 6)三个底层枚举,仓方码值由 YqnBoxLabelMapper 映射
- LabelPrintTask:只有任务编号,label() 恒为 null——仓方异步生成文件,
下载地址要另外查任务中心。Javadoc 写清「本调用拿不到文件」
- InboundCapable.printBoxLabel 默认抛不支持;门面为 inbound().printBoxLabel(cmd)
尺寸与每页数量有联动约束(每页 1 个 → 100×100/100×150;每页 6 个 → 104×98),
在 BoxLabelCommand 构造期校验,不等仓方拒绝。这条规则的错误此前只会表现为
仓方业务报错,排查成本高。
不走幂等守卫:重复调用只是再生成一份文件,不改业务状态。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
9b8f1222b4
|
feat(yqn): 按 API 88 对接创建销毁计划
销毁能力此前只有接口和端点常量,没有任何实现。补齐:
- DestructionCommand:单号 / 仓 / 库存类型 / 期望销毁日期 / 商品行 / 附件
- AttachmentType 底层枚举(面单 / 装箱单 / 提单 / 其他),仓方码由
YqnDestructionMapper 映射为 0/1/2/3
- DestructionCapable.create 改收命令对象;门面改为经幂等守卫,
幂等键 warehouseCode + destructionNo + create(销毁会减库存,重复下发等于报废两次)
三处接口特性和其它接口不同:
- 路径与旧常量不一致:/destroyplan/DestructionPlanCreate → 文档给出的
/v1/destroyPlan/createDestroyPlan
- 期望日期字段名是 hopeDestroyData(Data 不是 Date),照原样发
- 响应只有 destroyPlanOrderNo,没有状态。所以新建单据的 status/rawStatus
留空,Javadoc 明确写了「创建成功 ≠ 已执行销毁」
另修一处签名冲突:DestructionCapable.get(ctx, String) 与 OutboundCapable.get
擦除后同签名,改为 getDestruction。查询接口仓方未提供,显式抛不支持。
顺带修正上一提交的轨迹成功码判定:该文档示例是自动生成的占位符
(message:"example"),code=1 不可靠,且同站其它接口都是 200。
改为两者都接受,标注待联调核对;测试相应改成兼容 1/200、拒绝 500。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
d2d2f04a45
|
feat(yqn): 按 API 189 对接运单物流轨迹
新增 TrackEvent 之外的运单级模型 TrackingInfo(最新状态 / 承运商 / 签收人 /
预计妥投 / 公开轨迹页),events() 与既有 track() 返回一致。
TrackingCapable 增加 trackShipment(),门面同步暴露。
两处接口特性与仓接口不同,单独处理:
- 主机不同:轨迹在 pr-ship-api.yqn.com,仓接口在 pr-hwc-open-api.yqn.com。
WarehouseConnection 增加可选 auxEndpointBaseUrl,调用方显式传入;
没传时抛 WarehouseUnsupportedCapabilityException,不静默退回主基址
(否则轨迹请求会打到仓接口上,拿到的是看不懂的业务错误)
- 成功码不同:文档响应示例是 code=1,不是仓接口的 200。走独立的
YqnConstants.TRACK_SUCCESS_CODE 判定,不复用 YqnEnvelope
状态值保持运去哪原话,不做跨仓归一——承运商的节点状态词汇差异大,
「派送失败 / 退回中」这类区分归一会丢信息。
JacksonJsonCodec 补 intAt(json, pointer, missing):nodeAt + 类型判断,
避免适配器自己持有 ObjectMapper。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
06961c6781
|
feat(yqn): 按 API 121 对接订单测算(运费试算)
新能力,与既有结算明细(API 133 / FEE_SETTLEMENT)是两条路径:
后者查已发生的账单,这个在发货前按包裹 + 地址 + 渠道询价。
- FeeEstimateQuery:cm / g 为单位,适配器负责换算成仓方单位,
调用方不用按仓猜单位;isResidential 用 Boolean 三态,null 表示不传
- FeeEstimateResult:按仓库维度返回,一个仓下多个渠道报价,
每个渠道一笔总价 + 若干细分成本项
- WarehouseFeeEstimateCapable.estimate(ctx, query),入口
sdk.warehouses(...).fees().estimate(query),校验 FEE_ESTIMATE 能力位
logisticsServiceCode 有 29 个固定取值,建 YqnLogisticsService 枚举放 yqn 模块
(不映射到 core——各仓渠道划分口径不同,强行归一会失真);查询类仍接受字符串,
文档未收录的新渠道可直接透传。
报价仅供参考,实际费用以 BillingDocument 结算为准,已在 Javadoc 标注。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
a8dfb08e69
|
refactor(warehouse): 枚举下沉 core + 平台枚举分层映射
枚举原来散在各模型内部(OutboundStatus 嵌在 OutboundOrder 里、DealMethod 嵌在
ReturnCommand 里),且直接带仓方的数字码,导致 core 知道运去哪的协议值。改成两层:
- 底层枚举(warehouse-sdk-core/enums):只含 SDK 自编稳定 code + 中文名,
不认识任何仓的码值。code 从 10 起按 10 递增、只追加不重排,落库用。
- 平台枚举(warehouse-sdk-yqn/enums):带仓方原始码,toCore() 映射到底层。
运去哪出库状态是自由文本(无码表),按关键字收敛;其余按文档码表 1:1。
Mapper 里 9 个散落的 switch 全部删除,改为一行 of(raw).toCore()。
顺带修两处会误导下游的问题:
- OutboundStatus 缺 UNKNOWN,认不出的状态被兜底成 SUBMITTED(已下发)。
补 UNKNOWN(0, rank=-1),认不出归它;对应测试断言一并修正,
新增 unknownStatusIsNotGuessed 覆盖 null / 空串 / 未知值。
- InboundOrder / TransferOrder / WarehouseReturn / BillingDocument 缺
sourceProvider,rawStatus 无法解释(同一数字在不同仓含义不同)。补上字段,
运去哪的 Mapper 全部标注 YQN。
落库契约写进 WarehouseSink:rawStatus 必须与 sourceProvider 成对保存,
它是映射调整后唯一能重跑、修正历史数据的依据。
删除 WarehouseEnum 接口——在该规模下各枚举自带 code()/label()/ofCode() 足够,
不引入额外抽象。合并 ReturnDisposition 到 ReturnProcessDisposition(后者加
UNKNOWN),退货只保留「预约预报」与「检验后决定」两套语义。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
eb98688c4b
|
feat(yqn): 按 API 81 / 77 对接创建销售退货与退货条目处理
- 路径 /salereturn/SalesReturnCreate → /v3/saleReturn/createSaleReturnPlan
- 路径 /salereturn/SaleReturnAddProcessMode → /v3/saleReturn/addProcessMode
两套「处理方式」不能混用,各建各的枚举:
- ReturnCommand.DealMethod(预约预报):0 客户自提 / 1 拍照确认 /
2 销毁 / 5 仓库确认
- ReturnProcessCommand.Disposition(检验后决定):0 客户自提 / 2 销毁 /
3 上架良品 / 4 换标上架
码值完全不同,共用一套会静默错处理。
接口层面的两个硬约束:
- API 81 响应只有 code/message,没有单号。providerReturnId 只能是 null,
按仓单号回查这条路走不通,只能用来源单号;已在 Javadoc 里写明
- API 77 按明细行 id 操作,所以幂等键是
warehouseCode + providerReturnNo + lineId + process,
而不是整单——一张退货单的多行可以分别上架/销毁
另外修了一处会导致编译失败的设计冲突:InboundCapable 与
WarehouseReturnCapable 原本都有 get(ctx, String) / query(ctx, String),
同一适配器实现两者时泛型擦除后签名冲突。退货侧改名为
getReturn / queryReturns。
ReturnView.setDisposition 换成 process(ReturnProcessCommand):
原方法只有整单 + 枚举,装不下「哪一行 + 换标新 SKU」。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
1d3ebce5ab
|
feat(yqn): 按 API 139 对接创建调拨单
上门 8 个接口都是单仓内动作,这个是第一个跨仓写操作:会同时改两个仓的库存。
- 路径 /transferoutboundplan/TransferOutboundPlanCreate →
/v2/transferOutboundPlan/create
- 新增 TRANSFER 能力位与 TransferCapable:直接建独立能力接口,不塞进
InventoryCapable.adjust —— 调拨是跨仓单据,不是单仓库存调整
- 门面 createTransfer() 强制经幂等守卫,幂等键
warehouseCode + transferRequestNo + create
新增模型:
- TransferCommand:调出/调入仓、两种运输类型、期望出入库日期、
FBA shipmentId/removeOrderId、收货地址、增值服务、标签、批次
- TransferOrder:双号 + 归一化状态
- TransferType / TransferStatus:运去哪的 0/1/2/3 与 16 个状态码各自映射,
未知归 UNKNOWN
三条本地校验:
- 期望入库日期不能早于期望出库日期
- 调拨出库类型必须给收货地址;仓到仓由仓自己处理
- inventoryType 只接受 0/1
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
29d41da00f
|
feat(yqn): 按 API 101 对接查询入库计划
- 路径 /inbound/InboundPlanQuery → /v1/inbound/getInboundPlanInfo
- 入参只有 orderNo,入库单号与来源单号都能传
- 补齐 create 之后空着的能力:get() 返回完整详情,query() 按单号查一条
入库单模型按响应重写:
- 新增 InboundStatus 枚举,把运去哪的 0/5/6/8/10/16/17/20/25/70/100
归一化;未知码归 UNKNOWN,不猜
- InboundOrder 补 estimatedArrivalAt / actualArrivalAt / shipper 四项 /
totalWeightKg / totalVolumeCbm / inventoryType / lines
- 新增 InboundOrderLine:计划 / 装箱 / 实收 / 可售 / 不可售五个数量分开存,
并给 quantityMatchesPlan() 供对账判断短少与溢装
两点保守处理:
- createdAt 留 null:响应里只有 estimateArrive / actualArrive /
firstReception,没有下单时间
- 状态码按精确匹配,不做包含判断:运去哪的码是整数枚举,模糊匹配会把
6(审核拒回) 误判成 16(收货中)
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
eea3161634
|
feat(yqn): 按 API 97 对接创建入库计划单
- 路径 /inbound/inboundCreate → /v1/inbound/createInboundPlan
- 响应回 data.inboundPlanOrderNo(字符串),直接作 providerInboundId
入库模型按文档重写,补齐此前缺的维度:
- InboundCommand 补 inventoryType(必填) / factoryBatchNo / currency /
三个日期 / 原产地 / 发货方四项 / 集装箱号 / 装箱 / 批次
- InboundLine 的 boxNo 换成 cost(采购成本影响仓侧库存成本)
- 新增 InboundCarton(箱规 + sid 归并物理箱)、InboundBatch(批次属性
开放式 key/value,各仓支持的 key 不同,不做枚举)
两条本地校验:
- 集装箱号必须是 4 位大写字母 + 7 位数字,传错仓侧直接拒
- expectArriveDate 不能早于 estimateArriveDate
两个显式放弃:
- logisticsType 固定 0:文档写明运去哪头程只支持 web 端,openapi 不开放
- 入库单查询未接:文档只给了创建接口,get/query 抛
UnsupportedCapability,不返回空页
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
2472cba6f0
|
feat(yqn): 按 API 107 对接批量库存查询
- 路径 /inventory/BatchQueryInventory → /v2/inventory/get_inventory_by_page
- 方法是 GET,但文档把参数写在 Body 里;按重复 query 参数下发
(query.warehouseCodes=a&query.warehouseCodes=b),待联调核对
- 响应是 Spring Data 分页结构,翻页以 data.last 为准
- 该接口的 code 是字符串,其它接口是数字;信封按数值解析,两种都能过
库存模型补齐 API 107 的维度:
- InventorySnapshot 补 inventoryType(可售/不可售) / parentSku / saleType /
standardQuantity / 箱套四个库存字段
- InventoryQuery 补 warehouseCodes / inventoryType
两条防护:
- warehouseCodes 必填;没给时用账户配置的仓,都没有直接拒绝,
空列表会把整个租户的库存都拉下来
- inventory_current 文档标为 string,按 BigDecimal 解析,脏值归 0
同步策略固定 FULL_PULL_DIFF:运去哪没有按时间增量查的接口。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
d0649fed38
|
feat(yqn): 按 API 133 对接结算明细,费用查询改用 FeeQuery
API 133 是「一个接口按条件查四种费用」,不是 Spec §6.2 设想的
settlements/orderCosts/rentDetails/accountFlows 四个方法:
- 路径 /fee/SettlementDetails → /v1/warehouse/operation/costs/detail
- 入参:saleOrderNo / billingTransNo / costType / sku / externalOrderNo /
snapshotStartDate / snapshotEndDate,全部可选
所以 WarehouseFeeCapable 收敛为单个 settlements(ctx, FeeQuery),删掉
orderCosts / rentDetails / accountFlows / estimate:文档里没有对应接口,
留着就是四个永远抛 Unsupported 的空壳。
新增 FeeQuery / WarehouseFeeType,映射层做三条文档约束:
- 空条件直接拒绝,避免无条件下拉全量
- 按日期查只支持仓储费,且区间不超过 30 天
- saleOrderNo 在运去哪是数字,非数字直接拒绝(传错类型仓侧静默查不到)
BillingDocument 按响应重写:补 feeName / feeType / settledAt / estimated /
saleOrderNo;estimated 由 settlementType 决定(1 实际 / 2 预估),
对账时必须把预估和实际分开,否则会把预估值当已发生成本。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
f144e26827
|
feat(yqn): 按 API 122 对接取消销售订单
- 路径 /saleorder/OrderCancel → /v1/saleOrder/cancel
- 入参只有 orderNo,没有 acceptCharge / cancelReason
- 响应只有 statusCode/status/code/message,没有 data
运去哪没有取消费概念,也没有取消预判。因此:
- cancel() 只发 orderNo,acceptCharge 在此仓不生效(字段保留给易达云那类
有收费取消的仓)
- 仓拒绝取消(已拣货/已出库)时业务码非 200,统一映射为
OutboundCancelBlockedException,而不是笼统的 PlatformBusinessException
- 删掉 toEligibility(),它依赖的 cancelType 字段在文档里不存在
CancelCommand 的注释同步说明 acceptCharge 只对有收费取消的仓有效。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
ac8a164982
|
feat(yqn): 按 API 128 对接订单详情
- 路径 /saleorder/FindOrderInfor → /v1/saleOrder/findOne
- 响应只有 code/message/data,没有 statusCode/status
- data 里没有顶层 carrier / trackingNo:运单在 shipmentPackages
按 API 128 改统一模型:
- OutboundOrder 补 lines / shipTo / exceptionCode / estimatedShippingFee /
paidAt / carrierCode / currency
- PackageResult 补 carrierServiceCode / erpSku / shippedQuantity
三个语义坑的处理:
- 运去哪没有订单列表接口,query() 只支持按单号查;不给单号直接拒绝,
避免被当成增量同步用
- shipmentPackages 里 packageFlag=1 是面单信息行,会与实际包裹同 trackingNo
重复出现,按 trackingNo 去重且实际包裹优先
- errorCode=unexception 视为无异常,避免带异常标记的空串流进业务
ShipTo 的必填校验从模型挪到适配器:「哪些字段必填」是仓方协议,
查询回来的详情本来就可能缺字段。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
89ed0101f9
|
feat(yqn): 按 API 123 对接创建销售订单
文档把出库下单的契约定死了,替换掉此前按命名习惯猜的字段:
- 路径 /saleorder/OrderCreate → /v1/saleOrder/create
- 响应只有 data.orderId(仓内部数字 id),没有字符串单号;
幂等结果引用改存这个 id
- 必填扩到 10 项:来源单号、完整收件地址、联系人电话、销售平台、商品行
OutboundCommand 补 API 123 需要的维度:
- salesPlatform 改必填,类型用渠道域的 Platform 枚举,由适配器映射到
仓方平台码。仓按平台做路由与面单归属,不给就猜错,所以宁可构造期失败
- 新增 carrierCode / shipServiceLevel / latestShipDate /
estimatedDeliveryTime / currency / packages
- ShipTo 补 addressLine3(运去哪要求地址最多三行)
新增 OutboundPackageSpec:多包裹拆单,尺寸 cm、重量 g、含包裹内 SKU 与
打包耗材编码。不传则由仓按默认规则打包。
未接的部分保持原样:FindOrderInfor / OrderCancel 仍是旧假设,
取消预判与包裹查询等查询类接口等文档再对齐。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
067d815888
|
feat(yqn): 接入商品创建/编辑(API 115 /v1/product/save)
按官方文档落三条此前只能靠猜的契约:
- 鉴权头确认是 x-api-key(原来猜的 token)
- 响应信封确认是 statusCode/status/code/message,code=200 成功;
空响应体或缺失 code 不再当作成功处理
- 商品路径确认是 /v1/product/save
新增 YqnProductMapper:统一 WarehouseProduct → SaveProductRequest。
customs 按“国家 + HS + 申报价值”整组下发,币种固定 USD;
没给全时整个 customs 不发。WarehouseProduct 在构造期就挡住半组字段。
WarehouseProduct 按 API 115 的必填项重写:packingType / 长宽高 / 重量 / SN
改为必填,单位写进字段名(cm、g),避免适配器之间靠注释约定换算。
出库相关的字段仍待打样核对(Spec §8.6 第 2/5/9 项)。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
ec3e7b330c
|
feat(warehouse): 新增仓库域 SDK 内核与运去哪 P1 出库闭环
按 Spec W0《三方仓域 SDK 设计》落地 W1 + W2。
warehouse-sdk-core:
- 与 ChannelSdk 平级的 WarehouseSdk 门面,两个域互不依赖,只在 sdk-common
上共享幂等 / 水位线 / 审计 / HTTP
- 主键是 OMS 下发的 warehouseCode,出库单双号
outboundRequestNo(SDK 生成)+ providerOrderId(仓生成)
- 17 个能力位、9 个能力接口;未实现的能力显式抛
WarehouseUnsupportedCapabilityException,不静默返回空
- 取消三态 FREE / CHARGED / BLOCKED;收费取消必须显式 acceptCharge,
否则抛 OutboundCancelChargeRequiredException —— 资金动作不默认放行
- 出库创建强制经 IdempotencyGuard,幂等键
warehouseCode + outboundRequestNo + action;没注入幂等存储直接失败,
调用方无法绕过
- 领域模型不可变 + Builder;收件人 PII 的 toString 只输出国家与城市
warehouse-sdk-testkit:
- InMemory 仓仓库 / 落库 / 回调去重 / 未匹配回调留档
- FakeWarehouseAdapter 覆盖出库、收费取消、可重试失败路径
warehouse-sdk-yqn(运去哪 P1):
- 组织级固定 token 放请求头,不走 TokenManager(Spec §7.1)
- 出库 create / get / query / checkCancel / cancel / packages
- 面单模式为 PLATFORM_LABEL 且账户未声明 PLATFORM_LABEL_DELIVERY 时拒绝,
不静默降级为仓自有面单
- 默认 2 req/s/仓令牌桶(三家仓均未公开限流值)
待打样核对(Spec §8.6 第 1/2/5 项):token 头名与有效期、出库是否支持
外部单号、取消收费判定字段。这些全部集中在 YqnConstants / YqnDtos /
YqnEnvelope,核实后只改这三处。
测试:238 个,0 失败(7 个跳过的是需要真实凭据的联调探针)。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |