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 |
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>
|
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 |
chenchuchuan
|
12718ec376
|
Merge branch 'master' of http://124.222.6.97:3000/chencc/common-ecommerce
|
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 |
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 |
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 |
chenchuchuan
|
274425c0e5
|
feat(edayun): 对接取消前校验与取消订单
两个接口请求体同构(orderNo / poNumber 二选一,orderNo 优先级更高):
- POST /webApi/order/v1/checkCancelStatus → CancelEligibility
- POST /webApi/order/v1/cancelOrder → CancelResult
enums/EdayunCancelStatus 按文档口径映射:
- Published → FREE(可不收费取消)
- Shipment → CHARGED(可取消但收费)
- Cancelled / InterceptSuccess / InterceptProcessing / InterceptFailure /
UnableCancel → BLOCKED
- 未知值 → BLOCKED(取消不可逆,认不出时宁可拒绝)
**文档笔误**:响应说明里 InterceptSuccess 出现两次(一次成功一次失败)。
按订单状态字典命名,失败按 InterceptFailure 处理,已在枚举 Javadoc 注明。
cancel 的 data=false 不当异常:表示仓侧拒绝,msg 带原因,回填到 rawStatus。
不做「CHARGED 必须 acceptCharge」的强制拦截——校验与取消是两次调用,
中间状态可能变化,是否继续由宿主决定。
测试 15 个(状态映射 5 + 请求响应 10)。只跑 edayun 模块:71 个全绿。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
03f4773cb8
|
feat(edayun): 对接查询出库单与查询面单
两个接口:
- POST /webApi/order/v1/getOrderInfo → OutboundOrder
- POST /webApi/order/v1/getOrderLabel → List<PackageResult>(含 labelRef)
enums/EdayunOrderStatus:文档给了 24 个状态,按「宿主是否需要区分」折叠:
- ReadyToShip → SUBMITTED,Shipment → PICKING
- Shipped / Online / Delivered / Returns → SHIPPED(文档定义的「已发货」)
- Cancelled / InterceptSuccess → CANCELLED(文档定义的「已取消」)
- 其余 19 个异常类 → EXCEPTION,具体原因在 errorMsg / rawStatus
精确匹配不做子串:Shipment(发货中)不能因为含 Ship 就判成已发货。
adapter/EdayunOrderQueryMapper:
- 订单详情映射:poNumber→来源单号、orderNo→仓侧单号;毫秒时间戳;
SN 按 SKU 汇总;包裹 fileUrl 转附件;0/1 旗标 null 保持 null
- 面单映射:trackingNo 与 labels 按逗号位置一一对应到 PackageResult
- 地址优先取二字码(destProvince),全称兜底
适配器 get / packages 已实现;query / cancel / checkCancel 仍显式不支持。
测试 15 个(状态映射、地址口径、SN、旗标 null、多包裹对应、空面单)。
只跑 edayun 模块:56 个测试全绿。
Co-Authored-By: Claude <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 |
chenchuchuan
|
15605b58db
|
feat(edayun): 对接创建出库单(POST /webApi/order/v1/createOrder)
- dto/EdayunCreateOrderDtos:按文档建模,含地址 / 商品行 / 增值服务附件 /
打包数据 / 卡车约车等子结构
- adapter/EdayunOrderMapper:字段映射
- adapter/EdayunAdapter:实现 create,声明 OUTBOUND 能力位
(get/query/cancel/packages 显式抛不支持,文档还没给)
四处容易错的口径:
1. 幂等键是 poNumber。文档要求「取消重推时平台单号保持不变」,
映射自 orderRef,缺失时退回 outboundRequestNo,不能为 null。
2. promiseShipTime 是毫秒时间戳,不是秒。
3. destProvinceName 要州全称(California),不是二字码(CA)。
当前原样透传,调用方需自己给全称——映射表待业务确认。
4. 面单要文件 URL,不是 base64。传 base64 在本地就拒绝,
提示先上传拿 URL,避免发出去被仓方以「不可访问」拒绝。
另:unitPrice 是单价,直接取 declareValue 不乘数量(与运去哪的 skuAmount
总额口径相反);signatureRequired 映射到 addService 的 is_signature。
测试 11 个。edayun 模块 40 个测试全绿。
Co-Authored-By: Claude <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 |
chenchuchuan
|
c96b43faed
|
feat(edayun): 对接创建产品(POST /webApi/skuInfo/v1/createProduct)
- dto/EdayunCreateProductDtos:按文档建模,含组合产品 / 证书 / 图片 /
申报 / 批次等子结构;字段名是驼峰(与 token 接口的下划线风格不同)
- enums/EdayunYesNo:0 是 / 1 否 的统一封装。这个口径与直觉相反,
单独成枚举避免各处手写 x ? 0 : 1 把方向写反
- enums/EdayunDeclarationType:出口 / 进口(文档未给码值,按示例推断 0/1)
- adapter/EdayunProductMapper:g → kg 换算;反向标志统一走 EdayunYesNo;
申报信息按「出口=原产国 + 进口=US」组两条,缺值时整组不下发
- adapter/EdayunAdapter:实现 createOrUpdate,声明 PRODUCT 能力位
- 请求头从单独的小写 token 改为文档写的 Authorization: Bearer <token>
(实测两者都接受,以文档为准)
测试 9 个:字段映射、g→kg、brandFlag 反向、默认不带电、序列号与批次标志、
申报信息缺值不下发、图片、枚举码值、能力位。
探针 EdayunCreateProductProbeTest:默认 dry-run 只打印报文,真跑需
-Dedayun.probe.write=true,且用 PROBE- 前缀的随机 SKU 避免撞车。
全量 544 个测试通过。
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 |
chenchuchuan
|
5962988f86
|
feat(edayun): token 接口真机验证通过,按实际报文修正解析
真机调用(PR 环境):
POST https://test.omniselling.com.cn/saas-service/openapi/microService/oauth/token
{"client_id":"openapi-test","client_secret":"123456"}
→ HTTP 200 {"access_token":"0dabff46-...","token_type":"bearer","scope":"server"}
文档与实际不符的两处,已按实测调整:
1. 响应是**扁平结构**,没有 code、没有 data 包裹。
原来强制要求 code,会把成功当失败。改为:缺 code 不算失败,
交给「有没有 access_token」判断;显式给了非 200 的 code 才判失败。
2. 响应**没有有效期字段**(文档说「永久,建议留窗口刷新」),也没有
refresh_token。expiresAt 改为明确的估算值语义:让 TokenManager 定期
重登一次,不是真的到期。
DTO 补了顶层 access_token / token_type / scope,data 保留为兼容分支。
探针 EdayunTokenProbeTest 实跑结果:token 取到(脱敏输出)、
tokenType=bearer、剩 7200 秒、refreshToken=null。
测试 13 个(新增 acceptsFlatShapeWithoutCode 固化实测形态;
missingCodeIsRejected 改为 missingCodeWithoutTokenIsRejected,
报「no access token」而不是「no code」)。
全量 535 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
c07d848628
|
feat(edayun): 补测试环境基址 + 免签请求重载 + token 探针
- EdayunConstants.PR_BASE_URL 填成
https://test.omniselling.com.cn/saas-service/openapi/microService
- HEADER_TOKEN 的 Javadoc 写明「仅业务接口使用」:POST /oauth/token 本身不带
这个头,文档里那行是全局头定义,不是该接口的参数(已确认)
- EdayunRequestFactory.businessUnsigned(...):测试环境可直接把
openApiAdminSecret 当 sign 传,不必算 MD5;生产走带 appSecret 的重载
新增 EdayunTokenProbeTest(默认跳过):
- probeToken:真实调用 /oauth/token,打印 token 脱敏、tokenType、过期时刻、
剩余秒数、是否带 refreshToken;异常只打印不抛出
- probeSignatureShape:不联网,核对 MD5(body + "." + appSecret) 形态
凭据一律走系统属性,不入库:
-Dedayun.probe.clientId / clientSecret / appSecret
全量测试仍绿(533)。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
chenchuchuan
|
e522c08377
|
feat(edayun): 对接获取 token(POST /oauth/token)
按文档实现鉴权第一段:
- auth/EdayunTokenClient:POST /oauth/token,body 用 client_id / client_secret
(下划线风格照文档),无业务请求头
- http/EdayunRequestFactory:构造 token 请求;另备了业务请求构造(token / appKey /
timestamp / sign 四个头)与 sign() = MD5(body + "." + appSecret)
- adapter/EdayunAdapter.token(ctx):走 TokenManager 缓存,按 appKey + clientId 维度
- 工厂构造函数接收 TokenStore / LockProvider / Clock,与信仓同构
**文档只给了 code 取值(200/500/503/504),没给响应体结构**,所以做了兼容:
优先 data.access_token + data.expires_in,其次 data.expiry(绝对时刻),
再其次顶层 token;都没有则失败并带出截断的原始报文,不猜。
有效期同样三级兜底,最后按 2 小时(常量里标了「待联调确认」)。
错误分级:
- 500 明确失败,不重试
- 503 网关无效 / 504 超时,标记 retryable
- HTTP 非 2xx 单独处理,5xx(除 504)可重试
测试 12 个:请求形状、三种响应形态、无 token、500 不可重试、
503/504 可重试、缺 code、非 2xx、凭据缺失不发请求、MD5 签名(独立实现对照)、
空 body 签名。
全量 533 个测试通过。
Co-Authored-By: Claude <noreply@anthropic.com>
|
1 week ago |
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 |