chenchuchuan
|
8d76933a8d
|
Merge branch 'feature/supplier-lingxing' of http://124.222.6.97:3000/chencc/common-ecommerce into feature/supplier-lingxing
|
1 week ago |
lml
|
85e1fed8d4
|
docs(warehouse): 新增信仓接入汇总文档
参照 docs-warehouse/yqn/README.md 的结构,补一份信仓的:
- 基本信息:测试端点、query token 鉴权、2h 无 refresh、客户级 token、
成功判定(errno + rst.code)、北京时间、英寸/磅/美元
- 接口清单:19 个已对接接口与能力位,另列 3 个已声明常量但未接入的
- 业务流程:出库 / 转运 / 头程预报 / 商品四条链路的分步说明
- 枚举映射:订单 12 码、转运 8 码、预报 10 码、order_type 两套字典
并标注转运「列表与详情码表不一致」的差异
- 字段口径:ckh 唯一、amount 必填美元、po / rfc_sku_count 兜底规则、
is_pallet 必填、库存单仓限制等 13 条
- 平台限制与协议待核对:生产域名缺失、限流未公开、
calculate_order_v3 的 GET + JSON body 与 OkHttp 冲突
- 联调探针:三个探针的运行命令与全部可选属性,标明哪些会留数据
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
1 week ago |
lml
|
6df61b8efc
|
Merge remote-tracking branch 'origin/feature/supplier-lingxing' into feature/supplier-lingxing
# Conflicts:
# warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/capability/WarehouseProduct.java
# warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/InboundOrder.java
# warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/OutboundOrder.java
# warehouse-sdk-core/src/main/java/common/ecommerce/warehouse/model/TransferOrder.java
# warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnInboundMapper.java
# warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnProductMapper.java
# warehouse-sdk-yqn/src/main/java/common/ecommerce/yqn/adapter/YqnTransferMapper.java
|
1 week ago |
chenchuchuan
|
ae25e73b50
|
feat(edayun): 新建易达云适配器骨架
按 docs-warehouse/onboarding-checklist.md 阶段 1 搭好模块:
- warehouse-sdk-edayun:pom、注册到根 modules
- EdayunConstants:端点 / 限流(带 TODO 占位,等文档)
- EdayunAdapter / EdayunAdapterFactory:类型就绪,能力位为空
- dto / enums / http / webhook 四个包的 package-info 写明约定,
后续按约定往里填
骨架阶段的行为:任何业务调用抛 WarehouseUnsupportedCapabilityException。
未实现的能力不声明——声明了就必须有实现,否则调用方看能力位会以为能用。
测试 EdayunAdapterTest(5 个):适配器标识、能力位为空、注册后可解析、
未实现能力显式拒绝、能力查询不触发真实 API。
文档 docs-warehouse/edayun/README.md 记了当前状态和 8 项待确认
(文档、测试环境、鉴权、限流、能否走写、回调、费用口径、库存同步)。
全量 510 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
a82379cc07
|
docs: 接入清单补充「出入参怎么处理」和「枚举怎么处理」
两节详述,都是这段时间实际踩出来的规则:
出入参(阶段 2.5):
- 三层各管什么:DTO 只反序列化、Mapper 做换算与映射、标准模型不认识任何仓
- 入参四种情况分别怎么处理(直搬 / 换算 / 码值映射 / 平台没有)
- 出参必做四件事:rawStatus 必填、sourceProvider 必填、认不出归 UNKNOWN、
平台没给的不伪造
- 平台有模型没有 / 模型有平台没有 分别怎么标注
- 子结构别图省事重复建(退货 Attachment 合并的教训)
枚举(阶段 2.6):
- 为什么必须两层(只放 core 会认识仓方码,只放适配器宿主没法统一 switch)
- 底层枚举规则:code 步长 10、UNKNOWN 固定 0、只追加不合并、不含仓方码
- 平台枚举规则:精确匹配不用 contains、未知归 UNKNOWN、容器类型按原样、
提供反向 codeOf
- 三套码表不能混(运去哪退货三套)
- 状态码依赖上下文时把 (type, status) 一起带出去
- 什么时候不建枚举(>50 个透传、按中文名归类、只展示用)
- 枚举测试必须覆盖什么(全量映射 / 未知兜底 / 精度陷阱)
文档索引同步更新。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
bedb52e6a1
|
docs: 新增「接入新三方仓操作清单」
按运去哪 / 信仓的实践整理成 6 个阶段,每步带验收标准:
0. 先确认文档、测试环境、能否走写操作
1. 模块骨架(目录结构 + 注册 + 别漏 callObserver)
2. 每个接口的 6 步固定动作(DTO / Mapper / 平台枚举 / Capability /
门面 observe / 测试)
3. 真机验证:只读探针 + 全链路探针,重点核对参数名/成功码/单位
4. 回调:实现 WarehouseWebhookCapable + 确认时间戳单位与响应体
5. 收尾:文档、平台限制标注、待确认清单
附「踩过的坑速查」10 条,都是这段时间实际踩到的。
Co-Authored-By: Claude <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 |
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 |
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
|
2bf70e0af2
|
Merge remote-tracking branch 'common-ecommerce/feature/supplier-lingxing'
冲突处理:
1. WarehouseDirectoryCapable(add/add)
两侧各建了一个同名接口:本地返回 WarehouseInfo,远端返回 WarehouseFacility
并多了 carriers()。合并为:统一用 WarehouseFacility(远端模型,含
providerWarehouseId / postcode 等字段),carriers() 保留但给默认实现
(没有承运商接口的仓抛不支持,不返回空列表)。删除本地 WarehouseInfo。
2. WarehouseCapability
两侧都加了「基础资料」能力位:本地 WAREHOUSE_DIRECTORY(230),远端
DIRECTORY(210)。统一为 DIRECTORY,删掉重复项;顺带修掉合并时产生的
枚举顺序错乱与重复注释。
3. InboundCommand
本地补了运去哪的 11 个字段(lineName / shipmentId / attachments /
transportType 等),远端补了信仓的 10 个字段(shipmentType / cabinetType /
deliveryRequirements 等)。两侧都保留——不同仓的字段并集。
4. InboundCapable
本地加了 printBoxLabel / printSkuLabel,远端加了 improve / submit。
两侧都保留。
运去哪适配器跟随改为返回 WarehouseFacility,映射 state→province 双写、
postal→postcode。
全量 505 个测试通过(新增信仓 17 个)。
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 |
chenchuchuan
|
30758c7acb
|
fix(yqn): 结算明细单号口径 + 测试跟随真机行为
结算明细(costs/detail)的 saleOrderNo 要的是<b>数字单号</b>,即创建出库单
返回的 providerOrderId(实测 200171697),不是我们下发的来源单号。真机用
PROBE-xxx-OUT 去查会被适配器拦下。
- FeeQuery.saleOrderNo 的 Javadoc 写清口径,并说明传非数字会被拒绝
- 适配器报错信息补上出处(providerOrderId returned by saleOrder/create)
- 探针的结算明细改为读 -Dyqn.probe.saleOrderNo,不再复用出库单号
真机验证:用 200171697 查询返回 0 条(该单刚创建,还没产生费用),
接口本身通。
测试跟随真机行为更新:
- 物流产品:URL 参数名从 query.warehouseCode 改为 warehouseCode
- 仓库目录:成功 status 从 1 改为 200
全量 488 个测试通过(yqn 163 个)。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
0b8d687984
|
fix(yqn): 运费试算的信封兼容 + 全链路探针(真机验证)
真机验证发现 运费试算(POST /v1/saleOrder/calculate)与仓库目录一样,
响应没有 code 字段,只有 status=200 / message=success。原来走 execute()
(强制要求业务码 200),把成功当失败了。
把「容忍式信封」抽成通用实现:
- requireEnvelopeTolerant:有 code 按 200 校验,没有则看 status==200
(实测成功是 200,不是文档示例的 1)
- executeTolerant:非 2xx 仍交给 YqnEnvelope 分类,2xx 才走容忍判定
- 运费试算改用 executeTolerant
新增 YqnFullFlowProbeTest(15 步,按 @Order 串链路):
出库创建 → 详情 → 取消;库存;试算;结算明细;入库创建 → 查询 →
箱标 → SKU 标;调拨;退货;销毁;商品建档。
默认跳过,需 -Dyqn.probe.all=true + token,仅限 PR 环境。
真机结论:
- 出库全链路通(创建 / 详情 / 取消),且 UNSHIPPED 正确映射为 SUBMITTED
- 调拨 totalWeight=1000.0(1 件 500g)→ 单位确认是 kg,不是 lb
- 入库创建 → 查询通,能拿到计划单号
- 箱标 / SKU 标:仓方内部接口 Read timed out(他们那边的问题,非我们的报文)
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
05063853d1
|
fix(yqn): 真机联调发现三处参数名/成功码错误
用 pr 环境(RF_NY_US)跑只读探针,三处与文档不符:
1. 库存查询(get_inventory_by_page):参数名不该带 query. 前缀。
实测 400 "Required List parameter 'warehouseCodes' is not present",
说明仓方按扁平参数名取:warehouseCodes / inventoryType / rows / page。
之前照文档写的 query.warehouseCodes 被忽略。
2. 物流产品(getCarrierGroupList):同上,应为 warehouseCode 而非
query.warehouseCode,实测 400 "Required String parameter
'warehouseCode' is not present"。
3. 仓库目录(warehouse/findAll):实测 status=200 / message=success 才是
成功,不是文档示例里的 status=1。原来按 1 判定,把成功响应当失败。
另外给 YqnEnvelope 的 4xx 错误补上响应体:之前只报 http 400,看不到
仓方给的 message,排查全靠猜。
修完三个只读接口全部跑通:库存 2 条、仓库 1 个、物流产品 100 个。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
lml
|
6d4d6c1c20
|
test(xincang): 补齐所有已接入接口的联网探针
新增三个探针文件,默认全部跳过,凭据与业务数据全部走 -D 系统属性:
- XincangProbeSupport:公共基座。装配真实 adapter、报文打印(URL 与 token 脱敏、
截断 2000 字符)、单步执行(异常只打印不抛)、仓代码 / 承运商自动发现、
带时间戳的业务单号后缀(重跑不撞唯一约束)
- XincangReadProbeTest:只读接口逐个探针
仓库 / 承运商 / 实时库存 / 库龄 / 订单详情 / 转运详情 / 预报详情 / 最优渠道
- XincangWriteProbeTest:写接口探针,需 -Dxincang.probe.write=true 二次确认
商品建档、出库闭环(下单→回读→删除自清理)、
转运闭环(建→详情→删除自清理)、转运审核(审核后不可删,需单独开关)、
预报闭环(无删除接口,会留下数据)
业务输入不写默认值:SKU / 邮编 / 单号一律由 -D 传入,缺了就跳过对应用例,
不影响其他探针;仓代码与承运商从目录接口现取,换环境不用改代码。
运行方式见两个探针类的类注释。
Co-Authored-By: Claude Code <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
38db00cd4d
|
test(yqn): 新增只读联调探针 YqnReadOnlyProbeTest
运去哪之前只有单元测试(RecordingTransport 打桩),没有真机验证。补一个
只读探针,默认跳过,需显式开启:
mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \
-Dyqn.probe=true -Dyqn.probe.token=<x-api-key> \
-Dyqn.probe.providerWarehouseId=RF_NY_US \
-Dtest=YqnReadOnlyProbeTest test
覆盖 7 个查询接口:
- GET /v1/warehouse/findAll 仓库目录(不依赖单号)
- GET /v2/sysCarrierGroup/getCarrierGroupList 物流产品(验 GET+query 参数)
- GET /v2/inventory/get_inventory_by_page 库存(验分页与下划线字段名)
- POST /v1/warehouse/operation/costs/detail 结算明细(需 saleOrderNo)
- POST /v1/saleOrder/findOne 出库详情(需 outboundOrderNo)
- POST /v1/inbound/getInboundPlanInfo 入库计划(需 inboundOrderNo)
- POST /v3/saleReturn/getInboundPlanInfo 退货计划(需 returnOrderNo)
- GET api/v2/orderShipment/track/{no} 轨迹(需 trackingNo)
**不碰任何写接口**:下单 / 建入库 / 建调拨 / 建退货 / 销毁都会真实创建单据,
没有测试环境,一律不跑(遵守 feedback-no-live-write-tests)。
安全:
- 凭据只走系统属性,不入库
- 输出打印 token 掩码(前 4 + 后 2),不打印完整 token
- 只打印字段摘要,不打印完整报文(可能含 PII)
异常只打印不抛出,一次跑完便于对照真实报文。全量 162 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
7fd5bb43df
|
refactor(warehouse): OutboundQuery.providerOrderId → outboundRequestNo
原名有误导:这个字段装的从来不是仓内部 id,而是我们下发的来源单号
(outboundRequestNo)。运去哪创建订单(API 123)返回的 data.orderId 是
内部数字 id,只能用于列表/关联,不能作为详情查询(API 128 findOne)的入参。
改名后语义与 OutboundOrder.providerOrderId(真正的仓侧 id)明确区分。
调用方需同步改:query(OutboundQuery.builder().outboundRequestNo(...))。
全量 486 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
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
|
fa87226145
|
Merge remote-tracking branch 'common-ecommerce/feature/supplier-lingxing' into feature/supplier-lingxing
|
1 week ago |
chenchuchuan
|
208b549c96
|
feat(yqn): 接入销售退货计划查询,退货链路闭环
新增 API 83(POST /v3/saleReturn/getInboundPlanInfo)。这个接口补上了
退货链路的关键缺口:saleReturnOrderItems[].id 就是退货条目处理(API 77)
要求的明细行 id,之前没有任何途径能拿到。
链路现在是:
创建退货(API 81)
→ 退货入库完成回调(API 142,通知处理结果)
→ 退货计划查询(API 83,拿明细行 id)
→ 退货条目处理(API 77,按行设置处理方式)
模型变更:
- WarehouseReturn.status 从 String 改为 ReturnStatus 枚举(新增底层枚举:
草稿/待审核/审核拒绝/退货中/待收货/已完成/已关闭/UNKNOWN);仓方原值仍在
rawStatus。运去哪的状态是中文文本,按完整值精确匹配,未知归 UNKNOWN
- WarehouseReturn 补头级字段:actualReceivedAt / inspectedQuantity /
relatedProcessNo / lineName / attachments
- ReturnLine 补:lineId(API 77 操作键)、inventoryType、processedQuantity、
suggestedDisposition、newSku、pictureUrls、remark
顺带修正 toCreated:status 之前硬编码字符串 "SUBMITTED",现在为 UNKNOWN
——创建接口不回状态,真实状态要查 API 83 才知道。
新增 YqnReturnQueryTest(9 个):头级字段、明细行 id、行明细、附件、
状态枚举全量映射、未知状态、空 data、空单号拒绝。
全量 421 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
1805bbdf94
|
fix(yqn): 入库批次区分计划/上架;退货回调补批次字段
入库查询(getInboundPlanInfo):
仓方分两段给批次——planBatchItems 是预报装箱、inboundBatchItems 是实际
上架。原来合并进同一个列表且不标来源,同一 SKU/箱会出现两条数量不同的
记录(计划 60 / 实收 58),宿主无法判断哪条是计划、短少核对失真。
InboundOrderBatch 增加 Phase 枚举(PLANNED / INBOUNDED)。
退货入库回调(API 142):
items[].batchParamNo(批次号)与 batchParam(批次属性)之前完全丢弃,
退回货品的批次/效期无法回填库存。ReturnLinePayload 增加 batchNo 与
batchParams。换标上架场景仓方不传 batchParam,为空列表属正常。
测试:入库批次阶段断言、退货回调批次字段断言。
全量 412 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
732d77cac0
|
fix(yqn): 时区改由调用方传入;申报额按行总额下发
时区(影响所有时间字段):
原来 zoneOf 硬编码 Asia/Shanghai,运去哪仓在美国,所有本地时间被整体
平移 13–16 小时。改成:
- WarehouseConnection 增加可选 zoneId,由 OMS 显式传入
(账户时区不一定有,且同一 provider 多仓可能跨时区,SDK 不做地理推断)
- 未指定时按 UTC 解释,不再猜成北京时间
- WarehouseContext.zone() 暴露给适配器;各 mapper 的 DEFAULT_ZONE 统一改 UTC
- 下发时间(latestShipDate / estimatedDeliveryTime)也按该时区格式化,
原来按上海格式化,仓按所在地解释会跨日
申报金额:
运去哪 createSaleOrder 的 skuAmount 是「当前 SKU 总金额」,我们原来只传
单价、没乘数量,整单申报额少算 quantity 倍。改为 单价 × 数量。
OutboundLine.declareValue 的 Javadoc 明确「语义是单价」。
测试:
- YqnAdapterTest 默认时区断言从 UTC+8 改为 UTC
- 新增 usesConnectionZoneWhenProvided:纽约仓 09:00 → 14:00Z
全量 411 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
de11a900af
|
fix(yqn): 修 P0 状态误判 + 三处回调数据丢失 + 结算/库存口径
全链路审计(18 个接口逐字段比对)后的第一批修复。
P0:
- YqnOutboundStatus 用 contains("SHIP") 匹配,UNSHIPPED(未发货)被判成
SHIPPED(已交运)。下游会认为货已发出,checkCancel 直接 BLOCKED。
改为按 API 128 的文档枚举精确匹配(canceled/shipped/picked/approved/
assigned/unshipped/pending),未收录值归 UNKNOWN。测试固化 UNSHIPPED
不再命中。
P1(回调数据丢失):
- API 154 业务单据变动:orderNoStatus / orderNoStatusDesc 完全没带出去,
只剩「有变化」通知。WarehouseCallback 增加 rawStatus 字段,与
rawEventType 里的单据类型一起解释(同一个 5 在四套码表下含义不同)
- API 142 退货入库:processMode=3(不良品上架)与 5(良品上架)都映射
RESTOCK,不良品被报成良品。core 新增 RESTOCK_UNSELLABLE(50)
- API 150 库存变动:opLabel 缺失或未知时默认判出库,入库流水可能被反向
扣减。InventoryPayload.inbound 改为 Boolean,未知返回 null
P1(口径):
- API 133 结算:settlementType 为 null 时被当作「实际结算」,正踩
Javadoc 警告的反向风险。改为「只有 1 才是实际,其余一律按预估」
- API 107 库存:warehouseCode 回退用的是仓方编码,与出库/入库单的 OMS
编码口径不一致;asOfUtc 缺省时用 Instant.now() 而非注入的 clock
全量 410 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
0e539ce12a
|
feat(yqn): API 81 补 lineName;确认 code 为字符串形态
两处按文档对齐:
1. lineName(项目名称,非必填)之前没有标准字段,直接丢弃。
ReturnCommand 增加 lineName(),YqnReturnMapper 下发。仓方按项目分账 /
路由时缺这个字段会走默认项目,属于静默偏差。
2. API 81 的响应 code 是 **string**("200"),多数接口是数字 200。
现有 YqnEnvelope 用 stringAt 读再转整数,两种形态本来就能识别——
但此前没有测试锁定这个行为,改严格数字解析会把退货创建打挂。
新增 YqnEnvelopeTest(11 个)覆盖:
数字码 / 字符串码 / 带空白字符串码 / 数字失败码 / 字符串失败码 /
缺码 / 非数字码 / 空 body / 401 / 429 / 503
全量 406 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
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
|
80f8097186
|
docs(yqn): 标注 API 77 实际不可用(拿不到明细行 id,处理方式由仓侧决定并经回调通知)
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
1f5e6334c6
|
feat(yqn): 补全 API 101 入库计划响应 + 补测试
按你提供的完整文档核对出入参,补齐之前缺的部分:
API 101 响应侧(之前只映射了 22/40 个字段):
- 头级三层数量 planQty / packedQty / receivedQty → InboundOrder 新增
plannedQuantity / packedQuantity / receivedQuantity。之前只有行级,
头-行交叉校验(短少 / 溢装定位)做不了
- batchInfo(计划批次 + 上架批次)→ 新增 InboundOrderBatch,含箱唛号与
库存类型。注意与下发的 InboundBatch 不是一回事:那个是请求侧、
这个是回查侧
- boxInfo(每箱装了哪些 SKU、计划量与上架量)→ 新增 InboundOrderBox
- packingLabelUrl → 原样带出,Javadoc 注明仓方称将改为异步箱标任务
createdAt 确认运去哪不提供(文档无该字段),维持 null 并已标注。
测试补充:
- YqnInboundPlanTest(9 个):完整响应逐字段断言、可选段缺失、未知状态
归 UNKNOWN、按单号查、空单号拒绝
- WarehouseWebhookSdkTest(9 个)+ FakeWebhookAdapter:门面 sdk.webhook
按 provider 分派、不依赖仓账户、验签失败不进 parse、未注册 provider、
无 WEBHOOK 能力、解析结果透传
顺带修:sdk.webhook 传 null secret 时 WarehouseConnection 构造抛 NPE,
改为给空凭据,是否可用由适配器验签决定。
全量 395 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
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 |
chenchuchuan
|
9c814851dd
|
docs(warehouse): 标注运去哪不提供入库单创建时间 / API 101 只支持按单号查
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
|
4184b5aeaa
|
fix(yqn): 修复出库链路四处参数丢失 / 语义错误
逐字段审计「标准出入参 ↔ 运去哪出入参」后发现的问题,只修能明确判定为
bug 的,不涉及模型结构调整:
1. 平台面单文件从未下发
OutboundCommand.labelContentBase64 无任何映射,attachInfoItems 整类
从未被构造。结果是 labelMode=PLATFORM_LABEL 校验通过、面单一个字节
都没发,仓没有面单可打。现在映射为 attachInfoItems(type=0 面单),
去掉 data URI 头、从 MIME 取 fileType;单包裹时带 packageNo。
同时加了「PLATFORM_LABEL 必须给面单内容」的校验,只声明模式不给文件
会直接拒绝,不再静默失败。
2. 声明了 SPLIT 但没有对应字段
运去哪下单接口没有拆单字段,splitOrder 无法下发,却声明了
WarehouseCapability.SPLIT。撤掉该能力位,避免调用方以为能控制拆单。
3. 出库查询把 orderRef 当来源单号
query() 用 firstNonBlank(providerOrderId, orderRef),而 API 128 只按
来源单号查;orderRef 是平台单号,传进去查不到或查错单。现在只接受
providerOrderId,并在报错里说明原因。
4. 回查路径上 OutboundOrder 三个字段恒空
providerOrderId 在 API 128 里没有(只有 API 123 创建时返回),
labelMode 与 requestedAt 也不回传。labelMode 之前直接走构造器默认值
WAREHOUSE_LABEL,会把平台面单订单报成仓面单。改为由调用方显式传入
(get/query 传 null 时按仓自有面单兜底),并给 PackageResult 补
carrierCode(包裹级承运商 code,之前只映射了名称)。
5. 顺带补上现成落点没赋值的两个字段
shopName → channelAccount、sfp → isPrime(1/2),之前 DTO 有字段
却从不 set,多店铺与 SFP 场景静默失效。
文档补充:
- InventoryCapable.query / OutboundQuery.orderRef 标注「并非所有仓支持,
过滤可能不生效」,按 SKU 过滤目前在 YQN 侧完全未实现
新增 YqnOutboundPayloadTest(9 个)覆盖面单附件、data URI、两种面单模式、
店铺/SFP、查询语义、SPLIT 撤销。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
08b982d8a6
|
fix(yqn): 调拨单补齐响应字段并修掉 sourceNo 缺失导致创建失败
API 139 的创建响应有 80 多个字段,之前只取了 9 个,调拨失败时
errorCode / errorReason 直接丢失——status 只告诉你「已驳回」或
「取消异常」,具体原因查不到。补上:
- errorCode / errorReason + hasError() 便捷判断
- orgWarehouseTitle / inOrgWarehouseTitle(调出/调入仓名称)
- carrierCode / totalWeight / totalVolume
- TransferOrder 新增字段全部加 Javadoc 说明「缺失时为 null」
顺带修一个真实 bug:响应不回填 sourceNo 时,toOrder 直接把 null 传给
TransferOrder.transferRequestNo,构造期抛 IllegalArgumentException。
sourceNo 同时是幂等键,不能为空——改为回落到请求侧的 transferRequestNo。
新增 YqnTransferTest 覆盖:出库调拨带 shipTo、响应字段映射、
异常字段、未知状态归 UNKNOWN、type 取自请求侧。
单元体积单位运去哪未标明,按 kg / m³ 命名但不做换算,Javadoc 注明。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week 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>
|
1 week 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>
|
1 week 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>
|
1 week 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>
|
1 week 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>
|
1 week 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>
|
1 week ago |
chenchuchuan
|
86b05dc79d
|
Merge remote-tracking branch 'common-ecommerce/feature/supplier-lingxing' into feature/supplier-lingxing
# Conflicts:
# warehouse-sdk-xincang/src/main/java/common/ecommerce/xincang/adapter/XincangTransferMapper.java
|
1 week 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>
|
1 week ago |