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
|
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>
|
5 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>
|
5 days ago |
lml
|
1c3a99a8c6
|
feat(hengjian): 对接仓储费 / 尾程费 / 作业费三个计费明细接口
- 新增三个 DTO + HengjianFeeMapper,实现 WarehouseFeeCapable.settlements,
声明 FEE_SETTLEMENT
- 三个接口行结构不同、统一方法只有一个返回类型,因此必须由
FeeQuery.costType 指定查哪一类;不指定即拒绝,不「三个都查再合并」——
合并会让调用方误以为拿到完整账单
- VALUE_ADDED(增值服务费)恒健无对应接口,显式拒绝
- 过滤条件全空时本地拒绝(等于拉全量账单);金额缺失的行跳过而非记 0 元
- 费用类型由接口决定,不靠 settlementName 猜(作业费名形如「退货入库->入库费->…」)
- FeeQuery 补分页(pageCursor / pageSize)与 toBuilder:三个接口都是分页的,
原来返回 List 不带游标,调用方无法翻页
- 只读探针补计费用例(-Dhengjian.probe.feeType=STORAGE|LAST_MILE|OPERATION)
真机确认三个路径均存在(无 token 时返回对应的 Unauthorized 文案)。
验证:mvn test 全量通过,恒健 149 个用例 + 4 个探针跳过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
5 days ago |
chenchuchuan
|
d3633f58ef
|
feat(edayun): 对接仓租明细 / 费用试算 / 库存查询 / 入库单
- 仓租费用明细 POST /webApi/order/cost/v1/selectUserRentDetailList
新增 FeeCapable.storageRents(),按 SKU + 计费日返回仓储费
- 费用试算 POST /webApi/estimate/v1/trial
- 库存查询 POST /webApi/userSkuStock/v1/queryInventory
- 创建 / 编辑自发入库单 POST /webApi/entryInfo/v1/saveEntrySpontaneousOrder
- 查询入库单 SKU 明细 POST /webApi/entryInfo/v1/selectEntrySkuGoodsDetail
- 抽出 EdayunQueryWindows 统一时间窗构造与校验
- 文档补充各接口实测结论与遗留问题(TODO #14-#37)
Co-Authored-By: Claude <noreply@anthropic.com>
|
5 days ago |
lml
|
62a25a9f67
|
feat(hengjian): 对接物流异动单创建 / 查询(trackingChange)
- core 新增能力位 TRACKING_CHANGE、TrackingChangeCapable、TrackingChangeCommand /
TrackingChangeOrder、TrackingChangeHandleType(召回 / 换址 / 在途异常)
- 门面新增 createTrackingChange(写操作,走幂等守卫)与 getTrackingChange
- 恒健新增两个 DTO + HengjianTrackingChangeMapper,实现 createChange / getChange
- 纠正查询路径:文档写 /v1/saleOrder/findOrder,真机 404;
实际是 /v1/trackingChange/findOrder(已写入常量与文档)
- 真机确认 orderNo 必填(文档标「否」);四项必填本地校验,
换址三项缺哪个报哪个
- 异动单受理状态与运单物流状态分两个字段保存(orderStatus / logisticsStatus),
不互相覆盖
- 修正信封:999999 是通用失败码(参数校验失败也回它),只有 message 含授权
字样时才判认证失败,避免参数错误导致宿主白刷凭据
- 探针:查询(只读)+ 创建(写,需一对真实匹配的单号与运单号)
验证:mvn test 全量通过,恒健 129 个用例 + 4 个探针跳过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
1 week ago |
lml
|
a6226a37cc
|
feat(hengjian): 对接订单详情 /v1/saleOrder/findOne 与订单列表 /v1/saleOrder/findByPage
- 新增 HengjianOrderDetailDtos / HengjianOrderListDtos / HengjianOrderMapper,
实现 OutboundCapable.get / query / checkCancel / packages
- 新增 HengjianOrderStatus:8 个 orderStatusEnum 值精确匹配,未识别归 UNKNOWN;
core OutboundStatus 追加 REFUNDED(180)——退款与取消语义不同,合并会分不清是否已发货
- 详情不回 orderId:providerOrderId 保持 null,不编造;列表是唯一回 orderId 的接口
- skuAmount 是行总额落 totalAmount;恒健不回申报单价,declareValue 留空
- 列表:时间/单号二者必填其一(否则本地拒绝)、跨度上限 30 天、rows 截断 100、
状态过滤显式拒绝;游标是页码,末页以仓方 last 为准
- 时间按 UTC 解析(文档声明 utc),不用仓时区
- 包裹从详情 shipmentPackages 提取,按 trackingNo 去重且实际包裹优先
- 取消预判按状态推断,查不到单判 BLOCKED 而不是猜 FREE;cancel 仍未接入
- 只读探针补订单详情 / 订单列表用例
验证:mvn test 全量通过,恒健 99 个用例 + 2 个探针跳过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
fbf2363c06
|
feat(edayun): 对接查询订单费用明细
POST /webApi/order/cost/v1/selectOrderCostInfoList → List<BillingDocument>
与交易明细(accountFlow/list)是两回事:
- 交易明细 = 账户流水,带余额,金额为负表示扣费
- 订单费用 = 按订单拆的报价,带应收/折扣/实付与计费重、分区
三处关键口径:
1. **金额取实付**(realPayPrice = 应收 - 折扣)。应收只是报价,
对账要以实际发生为准。三个金额都保留在 DTO 里。
2. **一个订单展开成多条**。响应是 rows → chargeDetails → feeDetails,
按计费项展开,多条记录 documentNo 相同、靠 feeName 区分。
只有汇总没有 feeDetails 时按汇总记一条。
3. **单号类型要配合**(type: 0 订单号 / 1 平台单号 / 2 追踪号)。
统一模型新增 FeeQueryNoType 枚举与 FeeQuery.noType(),
不支持的类型显式拒绝——静默按别的口径查会让对账金额对不上。
时间窗 ≤3 个月(文档约束),无单号且无时间窗时本地拒绝。
能力接口新增 WarehouseFeeCapable.orderCosts(默认抛不支持),
门面 fees().orderCosts(query)。
顺带补 BillingDocument 里遗漏的 serialNumber() / accountBalance() getter
(上一提交只加了字段没加 getter,测试编译不过)。
测试 12 个。只跑 edayun 模块:93 个全绿;yqn / xincang 未受影响。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
ad41104cc6
|
feat(edayun): 对接查询交易明细(POST /webApi/accountFlow/list)
三条与其它仓不同的口径,都做了针对性处理:
1. **同一单号的同一计费项有多条流水,不能去重**。
文档原文说明这一点,所以每条流水映射成一条 BillingDocument,
靠新增的 serialNumber()(账户流水号)区分。按单号去重会丢账。
2. **金额是 string 且可为负**。billingAmount="-0.500" 是扣费,
正数是充值 / 退费。用 BigDecimal 解析保留符号,不取绝对值。
3. **币种有两个**:accountCurrency(账户币种,优先)与 originalCurrency
(原币)。跨币种账户时两者不同,靠 exchangeRate 换算。
统一模型扩展:
- FeeQuery 新增 settledAfter / settledBefore(计费时间窗,毫秒)。
与已有的 snapshotStartDate(运去哪按仓储费快照查)语义不同,
Javadoc 写明不要互相替代。
- BillingDocument 新增 serialNumber(流水号)与 accountBalance(变动后余额)。
查询约束在本地校验:
- 没给业务单号时时间段必填,且不能超过 180 天
- pageNum / pageSize 必填,当前固定第 1 页 / 每页 200(上限)
- 超过 200 条的翻页待确认(已记 TODO)
计费项分类按 billingCode 关键字推断,认不出归 null 不猜。
测试 10 个。只跑 edayun 模块:81 个全绿。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
lml
|
4aa311feb8
|
feat(warehouse): 新建恒健适配器骨架并接入只读基础资料
- 新增 warehouse-sdk-hengjian 模块,注册 WarehouseProvider.HENGJIAN
- 接入仓库目录、全量物流渠道、按仓物流渠道三个只读接口
- 信封校验覆盖三种真机形态:正常业务信封、HTTP 200 + code=999999、
HTTP 500 + 「未知的账户」;后两者映射为 AuthException
- 能力位只声明 DIRECTORY / LOGISTICS_PRODUCT,未接接口不声明
- 新增只读探针(默认跳过,凭据走系统属性)与接入文档
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
1 week 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 |
lml
|
3e5eb84c29
|
feat(warehouse): 写入模型补齐仓方原始字段,is_sign 不再写死
写入侧此前同样是「模型没有的字段一律不传」,导致调用方无法把仓方支持的参数
传下去。这次按只增不改补齐:
- OutboundCommand 增加 signatureRequired(信仓 is_sign)
下单 mapper 改为:调用方给值按值下发,未给才退回「否」
- WarehouseProduct 增加 productCategory(信仓 product_category)与
imageUrl(product_image 的最终地址)
适配器只发送调用方显式给的值,不做字典猜测
- XincangProductMapper:product_category 按调用方给值下发;
product_image 需要 upload.files 的 OSS 元数据,只有 URL 无法组装,
明确置空并注释说明
字段注释写明对应的仓方原字段与取值含义。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
ead77e0744
|
fix(warehouse): 补齐调用日志覆盖 + 恢复合并丢失的 logisticsProducts
日志这块渠道域和仓域共用同一套 CallObserver / Slf4jCallObserver,
但仓域有一批方法没包 CallSupport.observe,没注入观察者时看不出差别,
一旦注入就是「有的调用有日志、有的没有」,排查时很容易误判。
补齐 6 处:
- createTransfer / createDestruction(两个写操作)
- approveTransfer / deleteTransfer(信仓新加的两个写操作)
- improveInbound / submitInbound(信仓头程的两个写操作)
- processReturn(退货条目处理)
另外 sdk.webhook(...) 之前完全不走观察者:验签失败、解析出几条
都不进日志。现在包进 "warehouse.webhook.parse",失败时能看到异常类型。
顺带修:
- 合并时 WarehouseOperations 丢了 logisticsProducts()(适配器和
LogisticsProductCapable 都在,只是门面入口没了),补回
- WarehouseSdk.Builder.callObserver 的 javadoc 对齐渠道域,写清注入方式
全量 505 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
lml
|
2e5e62594c
|
feat(warehouse): 详情类模型补齐仓方原始字段,并消除一处歧义映射
调用方查完详情只能拿到归一化后的少数几个字段,仓方返回的其余信息(面单链接、
计费重、柜号、托盘数、时间节点等)全被丢弃,只能自己去翻原始报文。
新增字段(全部只增,未改动任何已有字段名与构造签名):
- OutboundOrder:补齐 44 个信仓订单详情字段里的剩余 23 个
含 labelUrl(face_url,面单下载地址)、shopName、skuCount、
zone、dimLength/Width/Height、dimDivisor、weightLbs、billingWeightLbs、
volumeWeightLbs、totalAmount、repairAmount、approvedAt/modifiedAt/
cancelledAt/interceptedAt、providerId、rawStatusName 等
- TransferOrder:补齐 39 个字段 + 新增 TransferLine 明细模型
含 po、deliveryMode/deliveryWay/orderType、labelRequirement、各类贴标标记、
picking/picked/palletized/send/approve 时间节点、shippingId、totalAmount
- InboundOrder:补齐 28 个字段
含 cabinetType/cabinetNo、shipmentType、deliveryRequirements、
四类托盘数、unlade/check/putaway/leave 时间节点、内外箱贴标记
- InboundOrderLine:补 productName/productNameCn/checkedBoxCount/
palletizedQuantity/packingRate/volumeCm
字段注释统一写明「对应哪家仓的哪个原字段」与中文含义;
模型本身不绑定单一仓,其余仓不填即为 null。
消除歧义:
信仓 forecast_detail 的 box_count 是「预报箱数」,而统一模型 packedQuantity
的语义是「装箱时实际装进去的件数」,此前直接映射属语义错位。改为不映射到
packedQuantity,只保留在 checkedBoxCount 与仓方原字段中。
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
|
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
|
258d59b796
|
docs(yqn): 标注平台不回传的字段与待核实的单位
按核实结果把 5 处平台限制写进 Javadoc,避免后来人当成「接漏了」:
- OutboundReceipt.providerOrderId:创建销售订单(API 123)返回的内部数字
id,只能用于列表/关联;查详情(API 128)要用来源单号 outboundRequestNo
- OutboundOrder.orderRef / requestedAt:订单详情不回传,恒为 null,
宿主需自行保存映射
- WarehouseReturn.createdAt:退货计划查询(API 83)无创建时间
- BillingDocument.documentNo / providerSku:结算明细(API 133)响应无这两个
字段,对账靠 saleOrderNo + settledAt + feeName
- TransferOrder.totalWeightKg / totalVolumeCbm:调拨(API 139)文档未标单位,
按 kg / m³ 原样透传;若确认是 lb / in³ 则分别偏大 2.2 / 16.4 倍
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
lml
|
19405c553b
|
feat(xincang): 对接客户仓库与承运商查询
- GET api.get_customer_warehouses → WarehouseDirectoryCapable.warehouses()
- GET api.get_customer_logistics → WarehouseDirectoryCapable.carriers()
core 只新增:
- WarehouseDirectoryCapable(warehouses / carriers)
- WarehouseFacility 模型:仓代码 + 国家 / 省 / 市 / 街道 / 邮编
- WarehouseCapability 追加 DIRECTORY(210)
- WarehouseOperations 增加 warehouses() / carriers(),只读带埋点
未并入 WarehouseRepository:那是宿主维护的 OMS 仓编码 → 账户映射,
这两个接口是仓方返回的可选仓库清单,数据源不同,混用会让宿主分不清信谁。
空 data 返回空列表;只有 rst 缺失(报文结构变化)才抛 ValidationException。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
1 week ago |
lml
|
b360b73df2
|
feat(xincang): 对接头程预报,并修正必填字段静默兜底
四个预报接口(信仓把入库拆成「建空单 → 补明细 → 提交」三步):
- POST forecast.do_forecast → InboundCapable.create,只建单头
- POST forecast.do_improve_forecast → InboundCapable.improve,补明细(整段覆盖)
- POST forecast.done_forecast → InboundCapable.submit,query 与 body 都带单号
- GET forecast.forecast_detail → InboundCapable.get,state 映射到 InboundStatus
core 只新增:InboundCapable 的 default improve / submit、
InboundView 的对应方法(走幂等守卫)、InboundCommand 的预报头字段。
同时修正字段必填性与代码不一致的问题:
- InboundCommand / TransferCommand 上「null 表示不传」的注释与信仓实际必填不符,
改为标注「信仓必填」,不再误导调用方传 null 后再吃运行期异常
- XincangProductMapper:declaredValue 缺失时不再按 0.00 建档(金额影响计费与清关),
改为下发前直接拒绝
- XincangChannelRecommendMapper:仓库代码缺失的报价行直接跳过,
不再编一个 "-" 占位
Co-Authored-By: Claude Code <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>
|
2 weeks 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>
|
2 weeks ago |
lml
|
5b45641e4b
|
feat(xincang): 对接实时库存与库龄列表
- 实时库存 GET api.stocklist:warehouse_code 必填,支持 product_no / page / limit
- 库龄列表 GET api.stockagelist:bill_date 为「起 - 止」单值,支持 key / is_need_fee_rate
core 只新增、不修改:
- InventorySnapshot 追加 productName / pendingOutbound / alertQuantity / volumeCbm
(信仓库存行有、原模型无处承载)
- InventoryCapable 增加 default queryAges(ctx, InventoryAgeQuery),
WarehouseOperations.InventoryView 增加 queryAges
- 新增 InventoryAgeQuery / InventoryAgeRecord:库龄是计费视角数据
(按计费日 × 仓 × SKU × 柜号计费),与库存快照分开建模
信仓实现要点:
- 实时库存只接受单个 warehouse_code;传多个显式拒绝,不静默只查第一个
- syncStrategy = FULL_PULL_DIFF:该接口没有时间增量参数
- 分页游标是字符串化页码,按「本页是否满页」判断下一页(count 不可靠)
- 库龄行缺少计费日期时跳过,不猜日期;时间统一按北京时间解析成 UTC
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
80f8097186
|
docs(yqn): 标注 API 77 实际不可用(拿不到明细行 id,处理方式由仓侧决定并经回调通知)
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks 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>
|
2 weeks ago |
lml
|
bedc6798e1
|
feat(xincang): 对接最优渠道 api.calculate_order_v3
按 SKU + 邮编由仓择优,与既有「运费试算」语义不同,core 新增独立能力:
- WarehouseChannelRecommendCapable.recommend(ctx, query)
- ChannelRecommendQuery:products[sku,qty] + postcode + signatureRequired + warehouseCode
- ChannelRecommendResult:文档两层结构原样保留
optimalPlan(仓 / 渠道 / 总价)+ warehouseQuotes[]
(每仓含 inventoryEnough、库存不足原因、各渠道报价与费用明细)
- WarehouseCapability 追加 CHANNEL_RECOMMEND(200),既有值未动
- 门面入口 fees().recommend(query),只读、不走幂等
信仓实现:
- 请求体 products / postcode / is_sign(是/否),未指定仓时不下发 warehouse_code
- isInventoryEnough 兼容 1/0、true/false、是/否,认不出返回 null
- optimalPlan 为空是合法结果(该城无可用渠道),返回空而非抛异常;
仅 rst 整体缺失才抛 ValidationException
待核对:文档标注 GET + application/json body,但 OkHttp 不支持 GET 带 body
(会直接丢弃),这里按 POST + JSON body 下发,联调时若仓方只认 GET
需换传输实现,改动集中在 XincangConstants.PATH_CHANNEL_RECOMMEND 一处。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
2 weeks 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>
|
2 weeks 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>
|
2 weeks ago |
chenchuchuan
|
9c814851dd
|
docs(warehouse): 标注运去哪不提供入库单创建时间 / API 101 只支持按单号查
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
lml
|
940e205cd7
|
feat(xincang): 对接删除订单与删除转运
- 删除订单 POST api.delete_order:order_no / ckh 二选一,空 body,
按状态分流(待审核→删除、待发货→已取消、拣货/已拣货→已拦截),
统一映射为 CancelResult
- 删除转运 POST fba.delete_fba:必填 order_no,仅待审核可删
取消资格预判:
- 信仓没有独立预判接口,checkCancel 走订单详情按状态推断
- SHIPPED / CANCELLED / INTERCEPTED / DELETED / UNKNOWN → BLOCKED,
其余状态 → FREE
- 查询失败直接抛出,不猜成 FREE,避免下发注定被拒的写请求
- 仓拒绝删除时抛 OutboundCancelBlockedException,与参数错误区分
core 只新增、不修改:
- TransferCapable 增加 default deleteTransfer(ctx, providerTransferNo)
- WarehouseOperations 增加 deleteTransfer,走幂等守卫,
动作键 warehouseCode + providerTransferNo + delete
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
2 weeks ago |
lml
|
47757616e5
|
feat(xincang): 对接订单详情与转运详情
- 订单详情 GET api.get_order:order_no 与 ckh 二选一(outboundRequestNo 走 ckh,
providerOrderId 走 order_no),映射到 OutboundOrder
- 转运详情 GET fba.fba_detail:token + order_no,映射到 TransferOrder
映射要点:
- state 经 XincangOrderStatus / XincangTransferState → core 枚举,未知值归 UNKNOWN
- 订单 order_type=wayfair → LabelMode.PLATFORM_LABEL,其余 WAREHOUSE_LABEL
- 详情只回系统单号 order_no,outboundRequestNo 用它兜底,业务参考号进 orderRef
- products[] 为空时退回 product_sku + sku_count 单值字段
- 时间按北京时间解析成 UTC;空串一律转 null
- errno=0 但 rst 为空抛 ValidationException,不返回"查到了空单"
core 只新增、不修改:
- TransferCapable 增加 default getTransfer(ctx, providerTransferNo)
- WarehouseOperations 增加 getTransfer,带 CallSupport.observe
方法名带 Transfer 后缀:InboundCapable 已有同签名的 get(ctx, String),
两者返回类型不同,同一适配器实现时无法区分(与既有 getReturn 同一手法)。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
2 weeks 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>
|
2 weeks 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 |
lml
|
57590e6d82
|
feat(xincang): 按分层约定补齐信仓平台枚举映射
沿用 a8dfb08 的两层结构(core 底层枚举 + 平台枚举 toCore),补上信仓侧:
新增 xincang.enums:
- XincangOrderStatus 订单 state 0/1/2/3/4/5/6/7/8/10/11/12 → OutboundStatus
- XincangTransferState 转运 state 0~7 → TransferStatus
- XincangForecastStatus 预报 state 0~9 → InboundStatus(信仓预报即头程入库单)
- XincangOrderType order_type common/wayfair,不映射 core:
core 已有 LabelMode 表达同一语义,但信仓按渠道平台判定,不做枚举级归一
core 枚举按「只增不改」处理,避免影响其他仓:
- OutboundStatus 追加 8 个值(code 100~170,rank 9~16)
- TransferStatus 追加 5 个值(code 170~210)
- 既有常量的 code / rank / 方法体一律未动
顺带修两处:
- XincangTransferMapper 补 sourceProvider(XINCANG),符合 a8dfb08 的
「rawStatus 必须与 sourceProvider 成对落库」契约
- rawStatus 改从枚举 rawCode() 取,不再手写 "0"
转运列表与详情的 state 码表不一致(列表少「待贴标」且后续前移),
以更完整的详情码表为准,类注释里写明冲突与调整方式。
Co-Authored-By: Claude Code <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 |
lml
|
ca6d00ba18
|
fix(xincang): 补齐下单与转运缺失的字段
上一版按文档只实现了部分字段,这次对齐到 schema 全量:
一单多件 api.add_order_multiple:
- 补 gzh(trackingNumber)/ face_base64(labelContentBase64)/
shop_name / sfp;order_type=wayfair 时前两者必填,缺失在下单前拦下,
不再等仓返回看不懂的错误
- 移除 remark:该接口 schema 没有这个字段,之前是多发的
新增转运 fba.do_fba:
- 补 4 个单附件(product_label_att / ctn_label_att / express_label_att /
pallet_label_att)、2 个数组附件(other_att / bol_att)、
express_print_copies
- products 明细补 fn_sku / ctn_sku / remark
模型配套:
- OutboundCommand 增加 trackingNumber / labelContentBase64 / shopName / sfp
- TransferCommand 增加 6 个附件字段与快递份数;TransferLine 增加三方 SKU、
箱标 SKU 与备注(保留原两参构造,YQN 不受影响)
- 新增 TransferAttachment 承载 upload.files 返回的附件元数据,
SDK 只搬运、不下载不落盘
字段覆盖已与文档逐项核对:两个接口均无缺、无多。
Co-Authored-By: Claude Code <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 |
lml
|
cde4bac44a
|
feat(xincang): 对接一单多件下单与转运创建 / 审核
- 新增订单一单多件:POST api.add_order_multiple,multipart/form-data,
products 字段是 JSON 字符串;返回 rst.order_no 作为仓侧单号
- 新增转运:POST fba.do_fba,application/json,返回 rst.order_no,
创建后处于待审核
- 转运审核:POST fba.do_approve,无请求体,token 与 order_no 都在 query
仓库域内核的配套扩展(YQN 不受影响,原有测试全绿):
- OutboundCommand 增加 splitOrder,仅声明了 SPLIT 的仓解释
- TransferCommand 增加 po / orderType / deliveryMode / deliveryWay /
otherWarehouseName / labelRequirements / palletRequired / 各类贴标份数
- TransferCapable 增加默认 approve(不支持的仓显式拒绝),
WarehouseOperations.approveTransfer 走幂等守卫,动作键 approve
字段映射的取舍:
- logistics_type 用 carrierCode 承载;ckh 用 outboundRequestNo(要求唯一)
- is_sign 模型无对应字段,固定发「否」
- order_type:Wayfair → wayfair,其余 → common
- 地址超过 32 字符的部分自动拆到 address2
- 字典字段(orderType / deliveryMode / deliveryWay / labelRequirements)
只接受仓方字典原值,SDK 不做归一
- 信仓这版不收申报信息与包裹尺寸,统一模型里的对应字段不发送
- 转运仅支持 TransferType.OUTBOUND(信仓转运 = 仓到平台仓)
|
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 |