lml
|
492743b34e
|
fix(hengjian): 计费的「未结算」哨兵日期 1997-01-01 转 null
重测计费接口时发现真问题:未结算的账单行把 settlementAt / bookAt
填成 1997-01-01 00:00:00 而不是 null。直接落库会让对账以为
1997 年结过一笔。
- HengjianFeeMapper 新增 settledAt():哨兵日期转 null;
仓储费 / 尾程费 / 作业费三个接口统一走它
- 尾程费与作业费原先的 firstNonBlank(settlementAt, chargeAt) 回落
一并去掉——chargeAt 是计费发生时间,不是结算时间,回落会让
「未结算」看起来像「已结算」
顺带更正之前的结论:ES 抖动无法复现。同一参数连打 20 次全部成功,
rows 5/10/20/50/100 也都成功,说明当时是仓方一次性抖动,不是稳定
故障。重试逻辑保留(成本极低、只读无副作用),但文档改为如实记录。
新增结算哨兵测试。mvn test 全量通过。
|
3 days ago |
lml
|
28e4b98975
|
test(hengjian): 地址识别改用已知答案的地址做正例
上一轮用普通地址测出 UNKNOWN 时无法判断是接口问题还是地址库覆盖问题。
换成两个已知答案的地址验证:
Google HQ (1600 Amphitheatre Pkwy, Mountain View, CA 94043) = BUSINESS
Apple HQ (1 Infinite Loop, Cupertino, CA 95014) = BUSINESS
结论:接口与映射都正常,「UNKNOWN」是恒健地址库没覆盖到该地址,
不是 bug。探针保留一个 UNKNOWN 样例并注明原因,避免下次误判。
另外确认 country 必须是两字母 ISO 码,给 USA 回 400。
同时修正计费接口的故障描述:不是某一个接口挂,三个
(仓储费 / 尾程费 / 作业费)都会间歇性回 Elasticsearch scroll 异常,
同参数重试有时成功。
|
3 days ago |
lml
|
72982e2806
|
test(hengjian): 只读探针补全全部查询接口,并用真机结果修 5 处映射
探针从 7 个用例扩到 21 个,覆盖全部已接入的查询接口(商品 / 库存 /
入库 / 调拨 / 退货 / 销毁 / 试算 / 地址 / 计费 / 目录)。
真机跑通 14 个接口,暴露并修掉这些问题:
- 运费试算必须给「发运仓库」或「发运邮编」其一,否则 400。发运仓的
字段名是 warehouseCode,shipWarehouseCode / orgWarehouseCode /
shipFromWarehouseCode 都不认(逐个试过)。core 的 FeeEstimateQuery
补 shipFromWarehouseCode,适配器用账户仓兜底
- 试算的 shipper* 给了不完整会报「发货人信息不完整」,所以要么只给
warehouseCode,要么给全五项
- 商品查询 length 真机确实有(文档响应表漏了),之前的兜底没触发
- 商品 nameEn 空值返回字符串 "null" 而不是 JSON null,trimToNull 一并当空
- 商品 cost 可为 0.0,是合法成本,原先当「没给」丢掉;且误塞进了
declaredValue(语义是申报价值),改为 cost
- isInsuranceRate 是费率不是金额,不再塞进 insuranceFee(Money 是金额语义)
- 响应有文档没写的 productStatus,保留原值到 rawStatus
另记录一条仓方故障:chargingSettlement 的 STORAGE 类型在测试环境返回
code=999999 + Elasticsearch scroll 异常,是恒健侧 ES 故障,我方报文正确。
销毁查询路径仍 404,探针标注未覆盖。token 只从 -Dhengjian.probe.token 读,
不入库。
mvn test 全量通过。
|
3 days ago |
lml
|
8d04306169
|
refactor(hengjian): 退货查询收进 ReturnQuery,消除绕开操作日志的适配器入口
HengjianAdapter.queryReturnsAdvanced 是门面上没有对应入口的 public 方法,
宿主强转适配器直接调用时会绕过 CallSupport.observe,操作日志漏记。
做法不是给它补日志,而是把它表达的能力收进统一模型:
- ReturnQuery 增加 rawStatuses / queryDataType / queryTypeValue+queryValue
* rawStatuses:统一枚举有损。恒健 RETURNING 对应仓方 20(待处理)
和 35(处理中),归一层表达不了,要给原值时只能传码
* 与 statuses 互斥,两套码表同时给会互相覆盖,构造期就拒绝
- 恒健 queryReturns 支持全部维度,并显式拒绝它没有的(SKU 过滤、
多状态、单号与 tracking 同时给、时间窗只给一半)
- 删除 queryReturnsAdvanced;适配器不再有绕开门面的 public 方法
验证:mvn test 全量通过。审计脚本确认门面除 outbound()(返回视图对象)
外零漏点,恒健不再有绕过日志的入口。
|
3 days ago |
lml
|
aac75d5904
|
feat: 信仓 / 恒健全接商品查询
core 新增 ProductQuery(SKU 过滤 + 分页)与
WarehouseProductCapable.queryProducts(default 拒绝,两家覆盖),
门面加 queryProducts。WarehouseProduct 补查询结果才有的字段
(仓侧 id / 仓方实测尺寸 / 创建更新时间 / 状态原值 / 体积),
并加 allowUnknownDimensions 开关:查询结果允许尺寸重量为 0
表示「仓方未给」,建档仍必须为正数——不伪造 0.01 之类的假值。
恒健 /v2/product/queryPage:
- 文档把 pageSize / pageNum 的说明写反(pageSize 写「页码」),
按响应里的含义实现:pageSize=每页条数、pageNum=页码;请求侧是 STRING
- 响应 data 是分页对象而非数组,按 total 判断是否还有下一页
- 文档漏了 length(只有 width/height/itemLength),映射时优先 length、
缺失退回 itemLength
- measurement* 存到仓方实测字段,与申报尺寸分开
信仓 api.productlist:
- 字段表按 Apifox「OMS接口文档V2」全量映射(token/state/page/limit 四项必填)
- 固定 state=1 查正式产品:临时产品是建档中间态,混进业务列表会让人
以为能下单;建档查重仍走 state=0
- key 是单值:传多个 SKU 时拒绝,不静默只取第一个
- 厘米与英寸两套尺寸都给,直接用厘米那套,避免二次换算舍入
- 数值全是字符串,空串转 null 不转 0;按 rst.count 判断下一页
- PRODUCTION_BASE_URL 确定为 https://oms.xincang-tech.com/oms(去掉末尾斜杠)
验证:mvn test 全量通过(恒健 +11、信仓 +10)。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
lml
|
93e85bfeb7
|
feat(hengjian): 对接入库箱标生成 /v2/inbound/boxLabelGenerate
真机确认必填五项:inboundPlanOrderNo / type / pageSize / isIndexNo /
isOriginCountry(空 body 时仓方一次性列出全部缺失项);paperType 与
fileNamingType 选填。
- 响应无 data:只有 code/message,不回任务号也不回文件,文件要去
入库计划详情的 packingLabelUrl 取。所以 LabelPrintTask.taskNo 恒为
null,不代表调用失败
- 份数口径不同:twoCopies → type 1 一式一份 / 2 一式两份,是份数码
不是布尔
- 恒健没有 sizeType / downloadMode 口径,改用 paperType(1 A4 /
2 10×10);labelsPerPage 直接映射 pageSize
- isIndexNo / isOriginCountry 仓方标必填,统一模型是 null-able:
null 时本地拒绝而不是猜——猜「是」每箱多印一行,猜「否」漏印
- core LabelPrintTask.taskNo 改为可空;BoxLabelCommand 补
showIndexNo / showOriginCountry / paperTypeCode / fileNamingType
顺带修正一处笔误:AddressClassificationCapable 的 @param city
被改成「必」,恢复为「必填」。
验证:mvn test 全量通过,恒健 340 个用例(+11)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
lml
|
b634ff2e93
|
feat(hengjian): 对接销毁计划创建 / 查询(路径待真机确认)
⚠ 这两个路径在测试环境真机返回 404 No handler found(2026-11-17),
文档路径及 26 个变体全试过;同环境其它接口正常响应,不是网络问题。
代码按文档实现,路径常量加了显式警告,联调时只需改一处。
- 创建:hopeDestroyData 字段名照抄(Data 不是 Date);orderNo 不传
(文档标必填但示例没有,仓方自生成);响应无 data,不回仓单号也不回状态
- 查询:请求体是裸数组;data 也是数组且查不到的单号不返回;
按来源单号查(示例里数组的值正是响应里的 sourceNo),也兼容仓方计划单号
- 新增 HengjianDestructionStatus:7 个状态值精确匹配;core 没有销毁状态
枚举,保留仓方码 + 中文名,不硬造跨仓枚举
- core DestructionCommand 补 lineName,DestructionOrder 补
lineName / hopeDestroyDate / createdAt
验证:mvn test 全量通过,恒健 329 个用例(+16)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
lml
|
1325314957
|
fix(hengjian): 异动单查询补齐未映射字段,并修正 changeRequestNo 语义
服务端字段原先只映射了一部分,排障要看的几组被丢掉了:
- 来源三维各存各的:sourceId / sourceNo / sourceOrderType,
orderNo 取 sourceNo(我们下发的单号落在那里),upstreamNo 不再合并进来
——合并就分不清哪一层出的问题
- 收件人对照:originalRecipient* / newRecipient* 三项都保留,
换址场景要能看到「原 → 新」
- carrierIsAcceptance 补齐并加 carrierAccepted():恒健是 1 否 / 2 是,
不是 0/1;缺失或非法值返回 null(未知),不猜
- trackingLabel 补齐并加 recalling()(1 召回中)
- errorStatus 与 errorMessage 分开保留:码用于判断、文本用于展示
- customerRemark / acceptanceRemark 两个字段不合并
修正 changeRequestNo 语义:查询响应里仓方不回 OMS 申请号,
原先把它填成仓单号,会让调用方误以为两者相等。现改为查询结果为 null,
创建结果仍填(那才是真的 OMS 单号)。字段改为允许 null。
验证:mvn test 全量通过,恒健 313 个用例(+8)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
lml
|
757b058697
|
feat(hengjian): 对接订单上传附件 /v1/saleOrder/createAttachment
- 新增 HengjianOrderAttachmentDtos,在 OutboundCapable 上加
uploadAttachments()(default 拒绝),恒健覆盖
- 门面新增 outbound().attachment(ref, list):写操作走幂等守卫,
业务键是「单号 + 附件名 + attachment」——同附件重传幂等、
不同附件各自一次(只用单号做键会让第二次附件被判成重复)
- 请求平铺;type 在这个接口是 INTEGER 0~6(创建订单那边标 STRING,
两页不一致),认不出即拒绝,不猜
- 给了 contentBase64 时忽略 url 并剥掉 data: 前缀(仓方语义)
- 真机无 token 时直接 403、不做参数校验,必填项按文档实现:
orderNo + 非空列表,每行 name/type 必填、url 与 file 二选一
- 响应无 data,只有 code/message
验证:mvn test 全量通过,恒健 305 个用例(+12)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
3 days ago |
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>
|
4 days ago |
lml
|
d126757e80
|
feat(hengjian): 对接库存查询 / 批量分页 / 库存变动流水
三个接口真机均确认存在(无 token 时返回各自的 Unauthorized 文案,
与 404 对照组可区分)。
按 SKU 查 /v1/inventory/getInventory、批量分页 /v2/inventory/get_inventory_by_page
- 恒健有两个库存接口且能力不同,统一模型只有一个 query(),按条件分流:
给 providerSkus 走按 SKU(不分页),只给 warehouseCodes 走分页
- 两个都给 → 拒绝(恒健无此接口);都不给 → 拒绝(不退化成整仓全量);
给 updatedAfter / inventoryType / includeZeroStock → 拒绝(不支持)
- 分页接口 rows 上限 500(文档明写),超过拒绝不截断
- 字段名两套:字段表写 snake_case、示例写 camelCase,DTO 用 @JsonAlias 同时接住
- data 形状两套:对象(含 content)与数组,用 JsonNode 判形状后分流
- updatedAt 缺失时报错而非填 EPOCH——快照时间是对账对齐依据
- syncStrategy = FULL_PULL_DIFF:两个接口都没有增量入参
库存变动流水 /v1/inventory/task/query
- 真机确认 skus / beginDateTime / endDateTime 必填,缺项回 MethodArgumentNotValidException
- 日期跨度按「含首尾」口径算:10-01~10-30 合法(30 天),10-01~10-31 非法
- rows 上限 100(文档明写)
- 新增 core 模型 InventoryMovement / InventoryMovementQuery / queryMovements()
- changeQty 按原值保留不转符号;单据类型与变动方向保留仓方原文不归一
- 单行缺 sku / createTime 时跳过该行而非整页失败
验证:mvn test 全量通过,恒健 203 个用例(+23)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
4 days ago |
lml
|
73892d6052
|
feat(hengjian): 对接运费测算与地址属性识别
两个接口都在 /v2/api/shipping 下,真机均确认可用(无 token 时的
参数校验响应与 404 对照组可区分)。
运费测算 /v2/api/shipping/calculate
- 真机确认必填项是包裹四项 + 两个单位 + 收货方五项;文档标必填的
shipper* 系列实际可不传
- 单位 cm/g 与统一模型一致,不换算
- 包裹尺寸在恒健是 INTEGER,厘米值四舍五入(截断会让报价偏低)
- totalRate 取 conversionTotalRate(折算价 / 客户实付),
不取 originalTotalRate(承运商牌价)
- 恒健不按仓返回,统一结果只有一个实例,仓编码用账户仓填充
地址属性 /v2/api/shipping/addressClassification
- 新增能力位 ADDRESS_CLASSIFICATION + AddressClassificationCapable
+ core 枚举 AddressType(BUSINESS/RESIDENTIAL/MIXED/UNKNOWN)
- 真机确认 street1/zip/city/state/country 五项必填,本地先挡
- 认不出归 UNKNOWN 不猜;MIXED 在 residential() 里按住宅计
- 文档域名写的是 open-api.thebizark.com(别家),真机确认本仓域名可用
顺带修 core 缺陷:FeeEstimateQuery.logisticsServiceCode 原为构造期必填,
而恒健允许不传(由仓报全部渠道)。改为选填,并新增 hasLogisticsServiceCode();
运去哪要求必填,改为在它的 mapper 里校验,不影响既有行为。
验证:mvn test 全量通过,恒健 180 个用例(+14)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
4 days ago |
lml
|
a4c38a4408
|
feat(warehouse): 补齐文档有而模型缺的入参,恒健已接接口全部可传
对照恒健接口文档逐个核对后,发现上一轮只修了「有字段但不生效」,
还有一批「模型里压根没字段、调用方传不进来」。这次补齐:
OutboundCommand(下单,5 项 + 附件列表)
- paidAt / pickupTime / directFulfillment / thirdPartyAccount / warehouseRemark
- warehouseRemark 与 remark 是两个字段:前者给仓作业看(恒健 warehouseRemark),
后者是客户备注(customerRemark),不能合并
- attachments: List<WarehouseAttachment>,支持 URL 与 base64 的通用附件,
与平台面单快捷入口 labelContentBase64 并存
- WarehouseAttachment 补 contentBase64(下发用;查询回来恒为 null)
OutboundQuery(列表查询,5 个维度)
- channel / channelAccount / poNo / providerOrderIds / updatedAfter+updatedBefore
- updatedAfter/Before 是独立的更新时间窗,与创建时间窗 after/before 分开——
增量同步按更新时间更准
WarehouseProduct(商品建档,2 项)
- imageUrls:产品测量图(复核长宽高),不是商品主图 imageUrl
- specialOuterPackaging:特殊外包装布尔开关,不是 packageStyle 三选一
二者原先被判为「语义不同不能顶替」直接丢弃,现在各有独立字段
恒健侧同步映射,并对不完整的附件(缺 name/type/url+base64)本地拒绝。
验证:mvn test 全量通过,恒健 166 个用例(+9)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
4 days ago |
lml
|
53c296c12f
|
fix(warehouse): 排序/分页/仓过滤改为可配,停止静默吞参数与静默截断
审计恒健已接接口时发现的四类问题,一并修正:
1) sort 被写死成 desc。文档里 sidx「可写死 id」、sort 明确是 asc/desc 两值,
而 OutboundQuery 根本没有排序字段,调用方无处表达。
→ core 新增 SortDirection 与 OutboundQuery.sortField / sortDirection;
恒健未指定时用文档默认(sidx=id、sort=desc),指定则透传。
2) 静默吞参数:orderRef / providerSku / noType 传了不生效也不报错。
→ 三者均改为显式拒绝(与同方法里 statuses 的处理一致)。
3) 静默截断:rows 超 100、计费 size 超 200 被悄悄改小,
调用方按自己的 pageSize 判末页会误判「还有下一页」,导致漏账。
→ 改为超限直接报错。rows=100 是文档明写上限;size=200 是我编的保守值,
已在注释标注待真机确认。
4) 计费仓过滤写死账户仓。恒健接口参数本就是复数 orgWarehouseCodes,
写死会让调用方无法表达「全部仓」或「其中几个仓」。
→ FeeQuery 新增 warehouseCodes(与 InventoryQuery 同口径),
非空用调用方的,空才退回账户仓。
验证:mvn test 全量通过,恒健 157 个用例(+8)通过。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
4 days ago |
lml
|
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>
|
4 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
|
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 |