diff --git a/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java
new file mode 100644
index 0000000..84eafe7
--- /dev/null
+++ b/warehouse-sdk-yqn/src/test/java/common/ecommerce/yqn/probe/YqnReadOnlyProbeTest.java
@@ -0,0 +1,297 @@
+package common.ecommerce.yqn.probe;
+
+import common.ecommerce.http.JacksonJsonCodec;
+import common.ecommerce.http.OkHttpTransport;
+import common.ecommerce.shared.error.ChannelException;
+import common.ecommerce.shared.spi.ChannelSecret;
+import common.ecommerce.warehouse.enums.WarehouseProvider;
+import common.ecommerce.warehouse.sdk.WarehouseConnection;
+import common.ecommerce.warehouse.sdk.WarehouseContext;
+import common.ecommerce.yqn.YqnConstants;
+import common.ecommerce.yqn.adapter.YqnAdapter;
+import org.junit.jupiter.api.Assumptions;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.condition.EnabledIfSystemProperty;
+
+import java.time.Clock;
+
+/**
+ * 运去哪只读探针:核对已对接接口的真实出入参。
+ *
+ *
默认跳过,用 {@code -Dyqn.probe=true} 显式开启;凭据走系统属性,
+ * 真实 token 不入库:
+ *
+ *
+ * mvn -pl warehouse-sdk-yqn -DfailIfNoTests=false \
+ * -Dyqn.probe=true \
+ * -Dyqn.probe.token=你的x-api-key \
+ * -Dyqn.probe.warehouseCode=RF_NY_US \
+ * -Dtest=YqnReadOnlyProbeTest test
+ *
+ *
+ * 只跑查询类接口:出库 / 入库 / 调拨 / 退货 / 销毁的下单类接口会真实创建单据,
+ * 没有测试环境,一律不碰(见 feedback-no-live-write-tests)。
+ *
+ * 输出只打印字段名与取值摘要,不打印完整报文(可能含 PII)。
+ */
+@EnabledIfSystemProperty(named = "yqn.probe", matches = "true")
+class YqnReadOnlyProbeTest {
+
+ // 真实凭据不入库:本地跑探针时用 -Dyqn.probe.token=...
+ private static final String TOKEN = System.getProperty("yqn.probe.token", "");
+ private static final String BASE_URL = opt("yqn.probe.baseUrl", YqnConstants.PR_BASE_URL);
+ private static final String AUX_URL = opt("yqn.probe.auxBaseUrl", YqnConstants.AUX_BASE_URL_PR);
+ private static final String WAREHOUSE_CODE = opt("yqn.probe.warehouseCode", "YQN-PROBE");
+ private static final String PROVIDER_WAREHOUSE = opt("yqn.probe.providerWarehouseId", "");
+
+ private static WarehouseContext ctx() {
+ return WarehouseContext.of(WAREHOUSE_CODE, WarehouseProvider.YQN,
+ PROVIDER_WAREHOUSE.isEmpty() ? null : PROVIDER_WAREHOUSE,
+ WarehouseConnection.of(BASE_URL, AUX_URL,
+ ChannelSecret.builder().appSecret(TOKEN).build()),
+ "probe-" + System.currentTimeMillis(), Clock.systemUTC());
+ }
+
+ private static YqnAdapter adapter() {
+ return new YqnAdapter(new OkHttpTransport("common-ecommerce-yqn-probe"),
+ new JacksonJsonCodec());
+ }
+
+ /** 仓库目录:不依赖任何单号,最容易验通。 */
+ @Test
+ void probeWarehouseDirectory() {
+ assumeToken();
+ run("GET /v1/warehouse/findAll", () -> {
+ java.util.List list =
+ adapter().warehouses(ctx());
+ System.out.println("[warehouses] 返回 " + list.size() + " 个仓");
+ for (int i = 0; i < Math.min(list.size(), 5); i++) {
+ common.ecommerce.warehouse.model.WarehouseInfo w = list.get(i);
+ System.out.println(" [" + i + "] code=" + w.warehouseCode()
+ + " name=" + w.name()
+ + " country=" + w.country()
+ + " city=" + w.city());
+ }
+ });
+ }
+
+ /** 物流产品:验证「GET 但参数写在 query」这条路是否被仓方接受。 */
+ @Test
+ void probeLogisticsProducts() {
+ assumeToken();
+ run("GET /v2/sysCarrierGroup/getCarrierGroupList", () -> {
+ java.util.List list =
+ adapter().products(ctx(), PROVIDER_WAREHOUSE.isEmpty() ? null : PROVIDER_WAREHOUSE);
+ System.out.println("[products] 返回 " + list.size() + " 个物流产品");
+ for (int i = 0; i < Math.min(list.size(), 5); i++) {
+ common.ecommerce.warehouse.model.LogisticsProduct p = list.get(i);
+ System.out.println(" [" + i + "] code=" + p.logisticsProductCode()
+ + " name=" + p.logisticsProductName()
+ + " crossCountry=" + p.crossCountry());
+ }
+ });
+ }
+
+ /** 库存查询:验证分页结构与字段名(下划线风格)。 */
+ @Test
+ void probeInventory() {
+ assumeToken();
+ run("GET /v2/inventory/get_inventory_by_page", () -> {
+ common.ecommerce.warehouse.model.InventoryQuery query =
+ common.ecommerce.warehouse.model.InventoryQuery.builder()
+ .pageSize(5).build();
+ common.ecommerce.shared.support.Page page =
+ adapter().query(ctx(), query);
+ System.out.println("[inventory] 返回 " + page.size()
+ + " 条, 游标=" + page.nextCursor());
+ for (common.ecommerce.warehouse.model.InventorySnapshot s : page.items()) {
+ System.out.println(" sku=" + s.providerSku()
+ + " avail=" + s.available()
+ + " onHand=" + s.onHand()
+ + " type=" + s.inventoryType()
+ + " asOf=" + s.asOfUtc());
+ }
+ });
+ }
+
+ /** 结算明细:需要单号,没有就跳过。 */
+ @Test
+ void probeFeeDetail() {
+ assumeToken();
+ String saleOrderNo = System.getProperty("yqn.probe.saleOrderNo", "");
+ Assumptions.assumeTrue(!saleOrderNo.trim().isEmpty(),
+ "未提供 -Dyqn.probe.saleOrderNo,跳过结算明细探针");
+ run("POST /v1/warehouse/operation/costs/detail", () -> {
+ java.util.List list =
+ adapter().settlements(ctx(),
+ common.ecommerce.warehouse.model.FeeQuery.builder()
+ .saleOrderNo(saleOrderNo).build());
+ System.out.println("[fees] 返回 " + list.size() + " 条");
+ for (common.ecommerce.warehouse.model.BillingDocument d : list) {
+ System.out.println(" name=" + d.feeName()
+ + " type=" + d.feeType()
+ + " amount=" + d.amount()
+ + " estimated=" + d.estimated()
+ + " settledAt=" + d.settledAt());
+ }
+ });
+ }
+
+ /** 出库单详情:只查,不下单。 */
+ @Test
+ void probeOutboundDetail() {
+ assumeToken();
+ String orderNo = System.getProperty("yqn.probe.outboundOrderNo", "");
+ Assumptions.assumeTrue(!orderNo.trim().isEmpty(),
+ "未提供 -Dyqn.probe.outboundOrderNo,跳过出库详情探针");
+ run("POST /v1/saleOrder/findOne", () -> {
+ common.ecommerce.warehouse.model.OutboundOrder order =
+ adapter().get(ctx(),
+ common.ecommerce.warehouse.model.OutboundRef.ofRequestNo(orderNo));
+ if (order == null) {
+ System.out.println("[outbound] 未找到该单");
+ return;
+ }
+ System.out.println("[outbound] status=" + order.status()
+ + " rawStatus=" + order.rawStatus()
+ + " tracking=" + order.trackingNumber()
+ + " carrierCode=" + order.carrierCode()
+ + " paidAt=" + order.paidAt()
+ + " shippedAt=" + order.shippedAt());
+ System.out.println(" 行数=" + order.lines().size()
+ + " 附件数=" + order.attachments().size()
+ + " SN数=" + order.serialNumbers().size()
+ + " signatureRequired=" + order.signatureRequired()
+ + " insured=" + order.insured());
+ for (common.ecommerce.warehouse.model.OutboundLine l : order.lines()) {
+ System.out.println(" line sku=" + l.providerSku()
+ + " qty=" + l.quantity()
+ + " totalAmount=" + l.totalAmount()
+ + " batchNos=" + l.batchNos()
+ + " ordIds=" + l.platformOrderItemIds());
+ }
+ for (common.ecommerce.warehouse.model.WarehouseAttachment a : order.attachments()) {
+ System.out.println(" attach type=" + a.type() + " name=" + a.name() + " url=" + a.url());
+ }
+ });
+ }
+
+ /** 入库计划查询:只查,不创建。 */
+ @Test
+ void probeInboundPlan() {
+ assumeToken();
+ String orderNo = System.getProperty("yqn.probe.inboundOrderNo", "");
+ Assumptions.assumeTrue(!orderNo.trim().isEmpty(),
+ "未提供 -Dyqn.probe.inboundOrderNo,跳过入库计划探针");
+ run("POST /v1/inbound/getInboundPlanInfo", () -> {
+ common.ecommerce.warehouse.model.InboundOrder order =
+ adapter().get(ctx(), orderNo);
+ if (order == null) {
+ System.out.println("[inbound] 未找到该单");
+ return;
+ }
+ System.out.println("[inbound] status=" + order.status()
+ + " planned=" + order.plannedQuantity()
+ + " packed=" + order.packedQuantity()
+ + " received=" + order.receivedQuantity()
+ + " boxes=" + order.boxCount()
+ + " containers=" + order.containers().size());
+ for (common.ecommerce.warehouse.model.InboundOrderBatch b : order.batches()) {
+ System.out.println(" batch phase=" + b.phase() + " carton=" + b.cartonNo()
+ + " qty=" + b.quantity() + " invType=" + b.inventoryType());
+ }
+ });
+ }
+
+ /** 退货计划查询:验证明细行 id(API 77 的操作键)能否拿到。 */
+ @Test
+ void probeReturnPlan() {
+ assumeToken();
+ String orderNo = System.getProperty("yqn.probe.returnOrderNo", "");
+ Assumptions.assumeTrue(!orderNo.trim().isEmpty(),
+ "未提供 -Dyqn.probe.returnOrderNo,跳过退货计划探针");
+ run("POST /v3/saleReturn/getInboundPlanInfo", () -> {
+ common.ecommerce.warehouse.model.WarehouseReturn ret =
+ adapter().getReturn(ctx(), orderNo);
+ if (ret == null) {
+ System.out.println("[return] 未找到该单");
+ return;
+ }
+ System.out.println("[return] status=" + ret.status()
+ + " rawStatus=" + ret.rawStatus()
+ + " inspected=" + ret.inspectedQuantity()
+ + " lines=" + ret.lines().size());
+ for (common.ecommerce.warehouse.model.WarehouseReturn.ReturnLine l : ret.lines()) {
+ System.out.println(" line id=" + l.lineId()
+ + " sku=" + l.providerSku()
+ + " qty=" + l.quantity()
+ + " suggested=" + l.suggestedDisposition());
+ }
+ });
+ }
+
+ /** 物流轨迹:需要运单号。 */
+ @Test
+ void probeTracking() {
+ assumeToken();
+ String trackingNo = System.getProperty("yqn.probe.trackingNo", "");
+ Assumptions.assumeTrue(!trackingNo.trim().isEmpty(),
+ "未提供 -Dyqn.probe.trackingNo,跳过轨迹探针");
+ run("GET /api/v2/orderShipment/track/{trackingNo}", () -> {
+ common.ecommerce.warehouse.model.TrackingInfo info =
+ adapter().trackShipment(ctx(), trackingNo);
+ System.out.println("[tracking] status=" + info.status()
+ + " carrier=" + info.carrier()
+ + " signedBy=" + info.signedBy()
+ + " events=" + info.events().size()
+ + " parcelWeightG=" + info.parcelWeightGrams()
+ + " parcelLenCm=" + info.parcelLengthCm()
+ + " guaranteedDelivery=" + info.guaranteedDeliveryDate());
+ });
+ }
+
+ // ---------------------------------------------------------------- helpers
+
+ private static void assumeToken() {
+ Assumptions.assumeTrue(!TOKEN.trim().isEmpty(),
+ "未提供 -Dyqn.probe.token,跳过运去哪探针");
+ }
+
+ /** 探针异常只打印不抛出,方便一次跑完并对照真实报文。 */
+ private static void run(String api, Runnable r) {
+ System.out.println("\n================ yqn / " + api + " ================");
+ System.out.println("[probe] baseUrl=" + BASE_URL + " auxUrl=" + AUX_URL
+ + " warehouse=" + WAREHOUSE_CODE + " token=" + mask());
+ try {
+ r.run();
+ System.out.println("[OK] " + api);
+ } catch (RuntimeException e) {
+ String msg = e.getMessage() == null ? e.getClass().getSimpleName() : e.getMessage();
+ System.out.println("[ERROR] " + e.getClass().getSimpleName() + ": "
+ + (msg.length() <= 300 ? msg : msg.substring(0, 300) + "…"));
+ if (e instanceof ChannelException) {
+ ChannelException ce = (ChannelException) e;
+ System.out.println(" platformCode=" + ce.platformCode()
+ + " platformRequestId=" + ce.platformRequestId()
+ + " retryable=" + ce.retryable());
+ }
+ }
+ }
+
+ private static String mask() {
+ if (TOKEN.length() <= 6) {
+ return "***";
+ }
+ return TOKEN.substring(0, 4) + "***"
+ + TOKEN.substring(TOKEN.length() - 2);
+ }
+
+ private static String opt(String name, String fallback) {
+ String value = System.getProperty(name, "");
+ if (value == null) {
+ return fallback;
+ }
+ String trimmed = value.trim();
+ return trimmed.isEmpty() ? fallback : trimmed;
+ }
+}