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 |