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>
|
4 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>
|
4 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>
|
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
|
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>
|
4 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 |
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 |
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>
|
5 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>
|
5 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
|
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 |
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
|
5fe33db101
|
feat(hengjian): 对接订单取消 /v1/saleOrder/cancel
- 新增 HengjianCancelOrderDtos,实现 OutboundCapable.cancel
- 恒健要求 orderId + orderNo 双键必填,统一模型允许只给一个:
缺哪个先用列表接口补(详情不回 orderId),补不到则本地拒绝,
不发必然被仓方拒的取消请求
- 列表补回的结果逐条精确比对单号 / id 才用,避免近似结果取消错单
- orderId 用 Long(文档标 INTEGER,九位 id 用 int 会静默错单)
- 仓方拒绝取消抛 OutboundCancelBlockedException;认证失败不包装成不可取消
- checkCancel 把 UNKNOWN 也判 BLOCKED,认不出的状态不凭猜下写请求
- 移除已无调用方的 unsupportedOutbound 辅助方法
- 写探针补取消与取消预判用例(需 -Dhengjian.probe.cancelOrderNo)
验证:mvn test 全量通过,恒健 109 个用例 + 2 个探针跳过。
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 |
lml
|
586d9c5eb8
|
feat(hengjian): 对接创建销售发货单 /v1/saleOrder/create
- 新增 HengjianCreateOrderDtos + HengjianOutboundMapper,实现 OutboundCapable.create,
声明 OUTBOUND 与 PLATFORM_LABEL_DELIVERY 能力位
- 时间按 UTC 的 yyyy-MM-dd HH:mm:ss 输出(文档明确 utc),不用仓时区——
那个时区是给仓方回传的无时区本地时间用的,方向相反
- skuAmount 取「行总额」:有 totalAmount 直接用,否则申报单价 × 数量
- isSignature 挂在行上且必填:取命令的布尔值套到每一行,成人 / 间接签收
统一映射成直接签收(1),比静默降成 0 安全
- attachInfoItems 必填:无附件发空数组;平台面单剥掉 data: 前缀后进 file
- 必填字段(地址六项 / 城市 / createdAt / 产品行)本地拒绝,不发无效请求
- 响应只回 data.orderId,拿不到即报错——取消接口同时要 orderId 与 orderNo
- 查询 / 取消 / 包裹仍显式拒绝,不返回 null;写探针增加建单用例
- 文档补建单口径与两页文档不一致处
验证:mvn test 全量通过,恒健 74 个用例 + 2 个探针跳过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
1 week ago |
lml
|
fc1753165d
|
feat(hengjian): 对接商品创建 / 编辑 /v1/product/save
- 新增 HengjianProductSaveDtos + HengjianProductMapper,声明 PRODUCT 能力位
- 保存语义:同 SKU 再调即更新,不区分 create/update;响应无 data,
status 固定 SAVED、rawStatus 取仓方 message,不编 ADDED/UPDATED
- 恒健必填项(nameEn / description / packingType / 外箱四项 / packedQty)
在本地拒绝,缺项一个请求都不发
- 三组尺寸(产品 / 单品 / 外箱)各归各位,不做回退填充
- 不发送恒健没有语义对应的字段:imageUrl(恒健是测量图)、packageStyle、
SN / 批次 / HS / 原产国 / 链接 / 客退 / 品类
- 新增写探针(默认跳过,另需 -Dhengjian.probe.write=true)验证保存幂等
- 文档补商品保存的字段口径与本地校验清单
验证:mvn test 全量通过,恒健 48 个用例 + 2 个探针跳过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
1 week ago |
lml
|
c5d9c768a9
|
refactor(xincang): 按接口拆分 DTO,XincangDtos 拆成 16 个文件
XincangDtos 单文件 1601 行、40 个内嵌类、覆盖 14 个接口,超出
onboarding-checklist「一个接口一个文件」的约定。按接口切成 16 个文件,
最大的 XincangForecastDetailDtos 约 220 行。
- Attachment 归到 XincangUploadDtos(upload.files 返回的对象,转运 /
商品原样回传),跨文件引用用 XincangUploadDtos.Attachment 限定
- UploadResponse / UploadData 保留(此前无调用方,按约定留作已定义未接入)
- 字段、@JsonProperty、@JsonInclude / @JsonIgnoreProperties 原样搬移,
序列化行为不变
- 4 处 mapper 的 javadoc 引用改为新类名;README 的 dto 目录说明同步
验证:mvn test 全量通过(信仓 118 个用例 + 3 个探针跳过)。
Co-Authored-By: Claude Code <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 |
chenchuchuan
|
5b4c22db41
|
docs: README 补调用日志(审计)一节
新增 3.6,写清「宿主怎么配置才有日志」:
- 最省事:builder().callObserver(new Slf4jCallObserver(ZoneId.of(...)))
两个门面(ChannelSdk / WarehouseSdk)用法一致
- 不注入 = NOOP,不产生任何日志
- 时区不传则取 systemDefault,容器里通常是 UTC,建议显式指定
- SDK 只依赖 slf4j-api,实现由宿主提供;没绑定时日志被静默丢弃,
需注意控制台那条 NOP 警告
- 成功(INFO)/ 失败(WARN)的实际输出样式与逐字段说明
- 落库 / MQ / 监控:实现 CallObserver 的三条约束(不抛异常、要快、
params 不含敏感信息)
- 覆盖范围:全部门面方法,含写操作与回调
- 部分成功用 observeSummary + ResultMapper 区分
顺带更新包结构里 audit 的类清单。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
a4cfd6cbfe
|
docs: 新增 docs-warehouse/ 三方仓文档
四篇:
- README.md 索引
- architecture.md 分层、枚举分层、能力矩阵、幂等、SPI、设计约定
- callback.md 回调链路、出参模型、验签、宿主要做什么、四个注意点
- notes.md 通用注意事项(写操作/状态/时区/单位/字段口径/测试)
- yqn/README.md 运去哪接入汇总:19 个接口、业务流程、真机联调结论、
平台限制、字段口径、两套码表、单位、探针用法
运去哪这篇记录了真机验证的结果,包括 4 处文档与实际不符
(库存/物流产品的参数名、仓库目录的成功码、运费试算无 code 字段)。
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
|
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 |
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>
|
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 |
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>
|
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 |
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>
|
1 week 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>
|
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 |
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 |
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 |
lml
|
8078e72de9
|
feat(xincang): 对接商品新增 / 更新(api.add_product / api.update_product)
信仓没有 upsert 接口,createOrUpdate 按「先查临时产品,有则更新、无则新增」实现:
- GET api.productlist?state=0 按 SKU 查临时产品,结果再按 product_no 精确比对,
防止 key 模糊匹配把相似 SKU 误判为已存在
- 命中走 api.update_product(只对临时产品有效),否则 api.add_product
- 写接口 token 同时放 query(文档通用约定)与请求体(产品接口 schema 要求)
- WarehouseProduct 的 cm / g 按常量换算成信仓的 inch / lbs,保留 4 位小数;
金额取 declaredValue 并固定 USD,非美元直接拒绝,避免静默按美元记错价
- bar_code 缺失时退回 SKU;packing_rate 固定 1(必填项);
包装方式 / SN / 海关等信仓未定义的字段不发送
- 适配器改为实现 WarehouseProductCapable,能力位声明 PRODUCT
未接入 api.pub_product:建档结果仍是临时产品(state=0),上架正式产品另行接入。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
2 weeks ago |
lml
|
c6241dddc7
|
feat(xincang): 新增信仓三方仓模块与登录换 token
- GET /api.login?appkey=&secret= 换取客户级 token,token 放 query 参数,
不是 Authorization 头
- token_expire_time 按北京时间 yyyy-MM-dd HH:mm:ss 解析为 UTC expiresAt;
字段缺失按文档 2 小时兜底,格式非法直接失败
- TokenManager 按 appkey 缓存(同客户多仓共用一个 token),提前 10 分钟续期;
信仓无 refresh 接口,到期即重新登录
- XincangEnvelope 统一校验顶层 errno 与 rst.code,HTTP 401/403/429/5xx 照常分类,
trace_id 落到 platformRequestId
- 本期不声明任何 WarehouseCapability,业务能力后续逐个接入
- 附登录只读探针,默认跳过,凭据走 -Dxincang.probe.*
待核对:生产基址(文档只给测试地址)与限流值(文档未公开,暂按 2 req/s)。
Co-Authored-By: Claude Code <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 |
chenchuchuan
|
65e5460e0d
|
refactor(http): 删除从未被实现的 Signer 接口
签名参数往往要在构造 HttpRequest 之前算出来(领星要把业务参数、
access_token、app_key、timestamp 一起签名后拼进 query),事后补头的
sign(HttpRequest, ChannelSecret) 表达不了这种时序;签名落点也不统一
(query / header / body 内嵌 / 整包 hash)。实际实现都是静态工具类,
如 LingxingSigner。
README / GUIDE 中「实现 Signer」的接入指引同步改为写静态工具类。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
86843c4b5a
|
docs(readme): 包结构改为按当前代码目录展开
- 「一、包职责」改为「一、包结构」,按 shared / channel / http / lingxing
实际包与类逐目录列出,lingxing 下展开到子平台(含各自 dto/product/order/shop)
- testkit 归到 shared.testkit 下展示,与实际包名一致
- GUIDE / 操作手册 中指向 README 的说法同步
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
8bca2bff73
|
refactor: 模块更名 shared/channel,README 补架构图
- common → shared(跨域共享层),core → channel(渠道域),
包名同步为 common.ecommerce.shared.* / common.ecommerce.channel.*
- GUIDE / 操作手册 的 Maven 坐标随之更新
- README 增加架构图:分层依赖、模块依赖、一次查询的调用链;
包职责表与 lingxing 适配器结构对齐当前实现
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |
chenchuchuan
|
aaeb0c23f5
|
refactor: 拆出 common 模块,渠道域与仓库域共享基础设施
把与渠道域无关的基础设施从 core 上提到 common 模块(包名
common.ecommerce.shared.*),为三方仓域复用同一套 SPI 与管道做准备。
不改变任何行为,只做搬迁、改包名与 import。
迁移内容(36 个类 + 3 个测试):
- audit CallObserver / CallOutcome / CallRecord / Slf4jCallObserver
- error 8 个异常(AuthException … ValidationException)
- idempotency IdempotencyGuard / WriteAudit / WriteResult / WriteScope
- spi AccessToken / ChannelSecret / TokenStore / LockProvider /
SecretProvider / SyncCursorStore / Idempotency* 共 10 个
- sync SyncSpec / SyncResult(SyncEngine 留在 core,它依赖订单模型)
- model Platform / ChannelProvider / Capability / FulfillmentMode
- support Money / Page / PlatformTime / CanonicalKeys
模块依赖调整为:
core / http / testkit → common
lingxing → core + http + common
http 不再依赖 core,仓库域可直接复用传输层与令牌管理。
验证:全量 84 个测试通过(common 33 / core 29 / http 13 / testkit 29 /
lingxing 84 含 13 个默认跳过的探针)。
Co-Authored-By: Claude <noreply@anthropic.com>
|
2 weeks ago |