diff --git a/core/src/main/java/common/ecommerce/audit/CallObserver.java b/core/src/main/java/common/ecommerce/audit/CallObserver.java
new file mode 100644
index 0000000..f6b0b2e
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/audit/CallObserver.java
@@ -0,0 +1,29 @@
+package common.ecommerce.audit;
+
+/**
+ * SDK 调用观察者:操作日志 / 审计日志的宿主扩展点。
+ *
+ *
SDK 是纯库,不写数据库、不写文件、不起线程。需要把调用记录落库、发 MQ 或接监控时,
+ * 由宿主实现本接口并注入 {@code ChannelSdk.Builder.callObserver(...)}。
+ *
+ * 实现约束:
+ *
+ * - 不要抛异常。SDK 会兜底捕获,但吞掉异常会掩盖实现问题;
+ * - 回调发生在业务线程上,方法应尽快返回。慢操作请自行投递到宿主的异步通道;
+ * - {@link CallRecord#params()} 只放摘要,不要补写密钥、买家姓名、收货地址等敏感信息。
+ *
+ */
+public interface CallObserver {
+
+ /** 空实现:不记录任何内容,也是默认值。 */
+ CallObserver NOOP = record -> {
+ // 默认不做任何事
+ };
+
+ /**
+ * 每次门面调用结束后回调一次;成功与失败都会回调。
+ *
+ * @param record 不可变的调用记录
+ */
+ void onCall(CallRecord record);
+}
diff --git a/core/src/main/java/common/ecommerce/audit/CallOutcome.java b/core/src/main/java/common/ecommerce/audit/CallOutcome.java
new file mode 100644
index 0000000..005e1e2
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/audit/CallOutcome.java
@@ -0,0 +1,13 @@
+package common.ecommerce.audit;
+
+/**
+ * 一次 SDK 调用的结果状态。
+ */
+public enum CallOutcome {
+
+ /** 调用成功(适配器没有抛异常)。 */
+ SUCCESS,
+
+ /** 调用失败(能力不支持、参数校验、平台返回错误、网络异常等)。 */
+ FAILURE
+}
diff --git a/core/src/main/java/common/ecommerce/audit/CallRecord.java b/core/src/main/java/common/ecommerce/audit/CallRecord.java
new file mode 100644
index 0000000..77fdd44
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/audit/CallRecord.java
@@ -0,0 +1,278 @@
+package common.ecommerce.audit;
+
+import common.ecommerce.error.ChannelException;
+import common.ecommerce.model.ChannelProvider;
+import common.ecommerce.model.Platform;
+
+import java.time.Instant;
+import java.time.ZoneId;
+import java.time.ZonedDateTime;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Objects;
+/**
+ * 一次 SDK 调用的操作记录(不可变)。
+ *
+ * 内容只覆盖排查所需的最小集合:调用方是谁、对哪个账户、调了哪个能力、
+ * 用了什么摘要参数、耗时、结果数量、失败原因。
+ *
+ * 敏感信息约定:{@link #params()} 只允许放时间窗、分页、游标、
+ * 单号数量这类摘要;密钥、买家姓名、收货地址、完整报文一律不放。
+ * SDK 自身绝不会把 {@code ChannelSecret} 写进来。
+ */
+public final class CallRecord {
+
+ private final Instant occurredAt;
+ private final String requestId;
+ private final ChannelProvider provider;
+ private final Platform platform;
+ private final String omsStoreId;
+ private final String externalStoreId;
+ private final String operation;
+ private final CallOutcome outcome;
+ private final long durationMillis;
+ private final int resultCount;
+ private final Map params;
+ private final String errorType;
+ private final String errorMessage;
+ private final Boolean retryable;
+ private final String platformRequestId;
+
+ private CallRecord(Builder b) {
+ this.occurredAt = Objects.requireNonNull(b.occurredAt, "occurredAt");
+ this.requestId = b.requestId;
+ this.provider = b.provider;
+ this.platform = b.platform;
+ this.omsStoreId = b.omsStoreId;
+ this.externalStoreId = b.externalStoreId;
+ this.operation = Objects.requireNonNull(b.operation, "operation");
+ this.outcome = Objects.requireNonNull(b.outcome, "outcome");
+ this.durationMillis = b.durationMillis;
+ this.resultCount = b.resultCount;
+ this.params = Collections.unmodifiableMap(
+ new LinkedHashMap<>(b.params));
+ this.errorType = b.errorType;
+ this.errorMessage = b.errorMessage;
+ this.retryable = b.retryable;
+ this.platformRequestId = b.platformRequestId;
+ }
+
+ public static Builder builder() {
+ return new Builder();
+ }
+
+ /** 调用开始时间(UTC);结束时间可用 {@link #finishedAt()}。 */
+ public Instant occurredAt() {
+ return occurredAt;
+ }
+
+ /**
+ * 按宿主时区展示的开始时间。
+ *
+ * {@link #occurredAt()} 是 {@link Instant},本身就是 UTC,直接 {@code toString()}
+ * 永远带 {@code Z};要本地时间就用这个方法,例如
+ * {@code record.occurredAt(ZoneId.of("Asia/Shanghai"))}。
+ */
+ public ZonedDateTime occurredAt(ZoneId zone) {
+ return occurredAt.atZone(Objects.requireNonNull(zone, "zone"));
+ }
+
+ /** 调用结束时间(UTC)= 开始时间 + {@link #durationMillis()}。 */
+ public Instant finishedAt() {
+ return occurredAt.plusMillis(durationMillis);
+ }
+
+ /** 按宿主时区展示的结束时间。 */
+ public ZonedDateTime finishedAt(ZoneId zone) {
+ return finishedAt().atZone(Objects.requireNonNull(zone, "zone"));
+ }
+
+ /** 链路 ID,与 HTTP 层日志、平台 request_id 关联用。 */
+ public String requestId() {
+ return requestId;
+ }
+
+ public ChannelProvider provider() {
+ return provider;
+ }
+
+ public Platform platform() {
+ return platform;
+ }
+
+ /** 宿主侧的店铺 ID(业务主键的一部分)。 */
+ public String omsStoreId() {
+ return omsStoreId;
+ }
+
+ /** 渠道侧店铺 ID;领星是 {@code store_id},亚马逊 SC 是 {@code sid}。 */
+ public String externalStoreId() {
+ return externalStoreId;
+ }
+
+ /** 门面操作名,如 {@code salesOrders.pull}、{@code outbounds.labels}。 */
+ public String operation() {
+ return operation;
+ }
+
+ public CallOutcome outcome() {
+ return outcome;
+ }
+
+ /** 耗时(毫秒);测试注入固定时钟时为 0。 */
+ public long durationMillis() {
+ return durationMillis;
+ }
+
+ /** 结果条数;单对象为 1,不适用(写操作等)为 -1。 */
+ public int resultCount() {
+ return resultCount;
+ }
+
+ /** 参数摘要,只读;见类注释里的敏感信息约定。 */
+ public Map params() {
+ return params;
+ }
+
+ /** 失败时的异常类名;成功为 null。 */
+ public String errorType() {
+ return errorType;
+ }
+
+ /** 失败时的异常消息;成功为 null。 */
+ public String errorMessage() {
+ return errorMessage;
+ }
+
+ /**
+ * 是否可重试;仅当失败异常是 {@code ChannelException} 时有值,其余为 null。
+ *
+ * 运维可直接据此决定「重跑」还是「人工介入」。
+ */
+ public Boolean retryable() {
+ return retryable;
+ }
+
+ /**
+ * 平台返回的 request_id / 链路 ID;仅当失败异常是 {@code ChannelException}
+ * 且适配器填了该字段时有值。排查时需要拿它找平台侧日志。
+ */
+ public String platformRequestId() {
+ return platformRequestId;
+ }
+
+ public boolean failed() {
+ return outcome == CallOutcome.FAILURE;
+ }
+
+ @Override
+ public String toString() {
+ return "CallRecord{" + outcome
+ + " at=" + occurredAt
+ + " op=" + operation
+ + " " + provider + "/" + platform
+ + " omsStoreId=" + omsStoreId
+ + " storeId=" + externalStoreId
+ + " requestId=" + requestId
+ + " cost=" + durationMillis + "ms"
+ + " result=" + resultCount
+ + " params=" + params
+ + (failed() ? " error=" + errorType + ": " + errorMessage
+ + " retryable=" + retryable
+ + " platformRequestId=" + platformRequestId
+ : "")
+ + '}';
+ }
+
+ public static final class Builder {
+
+ private Instant occurredAt = Instant.EPOCH;
+ private String requestId;
+ private ChannelProvider provider;
+ private Platform platform;
+ private String omsStoreId;
+ private String externalStoreId;
+ private String operation;
+ private CallOutcome outcome = CallOutcome.SUCCESS;
+ private long durationMillis;
+ private int resultCount = -1;
+ private Map params = Collections.emptyMap();
+ private String errorType;
+ private String errorMessage;
+ private Boolean retryable;
+ private String platformRequestId;
+
+ public Builder occurredAt(Instant occurredAt) {
+ this.occurredAt = occurredAt;
+ return this;
+ }
+
+ public Builder requestId(String requestId) {
+ this.requestId = requestId;
+ return this;
+ }
+
+ public Builder provider(ChannelProvider provider) {
+ this.provider = provider;
+ return this;
+ }
+
+ public Builder platform(Platform platform) {
+ this.platform = platform;
+ return this;
+ }
+
+ public Builder omsStoreId(String omsStoreId) {
+ this.omsStoreId = omsStoreId;
+ return this;
+ }
+
+ public Builder externalStoreId(String externalStoreId) {
+ this.externalStoreId = externalStoreId;
+ return this;
+ }
+
+ public Builder operation(String operation) {
+ this.operation = operation;
+ return this;
+ }
+
+ public Builder outcome(CallOutcome outcome) {
+ this.outcome = outcome;
+ return this;
+ }
+
+ public Builder durationMillis(long durationMillis) {
+ this.durationMillis = durationMillis;
+ return this;
+ }
+
+ public Builder resultCount(int resultCount) {
+ this.resultCount = resultCount;
+ return this;
+ }
+
+ public Builder params(Map params) {
+ this.params = params == null ? Collections.emptyMap() : params;
+ return this;
+ }
+
+ public Builder error(Throwable error) {
+ if (error != null) {
+ this.errorType = error.getClass().getName();
+ this.errorMessage = error.getMessage();
+ if (error instanceof ChannelException) {
+ ChannelException channelError = (ChannelException) error;
+ this.retryable = channelError.retryable();
+ this.platformRequestId = channelError.requestId();
+ }
+ }
+ return this;
+ }
+
+ public CallRecord build() {
+ return new CallRecord(this);
+ }
+ }
+}
diff --git a/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java b/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java
new file mode 100644
index 0000000..712bb66
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/audit/Slf4jCallObserver.java
@@ -0,0 +1,104 @@
+package common.ecommerce.audit;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.time.Instant;
+import java.time.ZoneId;
+import java.time.format.DateTimeFormatter;
+import java.util.Objects;
+
+/**
+ * 基于 SLF4J 的默认观察者:成功打 INFO,失败打 WARN。
+ *
+ * 适合「先把调用链看清」的起步阶段;需要落库审计或接监控时,
+ * 换成一个写 {@code IdempotencyStore} / 数据库 / MQ 的 {@link CallObserver} 即可。
+ *
+ * 日志里不包含凭证与报文;凭据只由 {@code ChannelConnection.toString()} 打指纹。
+ *
+ * 时间显示:{@link CallRecord} 内部始终是 UTC;这里只负责格式化。
+ * 时区取值优先级:
+ *
+ * - 构造时显式传入的 {@link ZoneId}(推荐,由宿主从配置/环境读取);
+ * - 缺省用 {@link ZoneId#systemDefault()},即 JVM 默认时区
+ * (受 {@code -Duser.timezone}、{@code TZ} 环境变量、容器时区影响)。
+ *
+ *
+ * 注意:容器/CI 里 {@code systemDefault()} 通常是 UTC。想固定成本地时间,
+ * 建议显式传 {@code ZoneId.of("Asia/Shanghai")},而不是依赖运行环境。
+ */
+public final class Slf4jCallObserver implements CallObserver {
+
+ private static final Logger LOG = LoggerFactory.getLogger(Slf4jCallObserver.class);
+
+ /** 默认时间格式:24 小时制、精确到秒,例如 {@code 2026-11-05 08:00:00}。 */
+ public static final String DEFAULT_TIME_PATTERN = "yyyy-MM-dd HH:mm:ss";
+
+ private final ZoneId zone;
+ private final String pattern;
+ private final DateTimeFormatter formatter;
+
+ /** 使用 JVM 默认时区与默认格式 {@value #DEFAULT_TIME_PATTERN}。 */
+ public Slf4jCallObserver() {
+ this(ZoneId.systemDefault());
+ }
+
+ /**
+ * @param zone 日志展示用的时区;不要传 null
+ */
+ public Slf4jCallObserver(ZoneId zone) {
+ this(zone, DEFAULT_TIME_PATTERN);
+ }
+
+ /**
+ * @param zone 日志展示用的时区;不要传 null
+ * @param pattern {@link DateTimeFormatter} 格式,如 {@code yyyy-MM-dd HH:mm:ss};
+ * 需要偏移量时用 {@code yyyy-MM-dd HH:mm:ss.SSSXXX}
+ */
+ public Slf4jCallObserver(ZoneId zone, String pattern) {
+ this.zone = Objects.requireNonNull(zone, "zone");
+ this.pattern = Objects.requireNonNull(pattern, "pattern");
+ this.formatter = DateTimeFormatter.ofPattern(pattern).withZone(zone);
+ }
+
+ /** 当前使用的时区,便于启动日志里打印一次。 */
+ public ZoneId zone() {
+ return zone;
+ }
+
+ /** 当前使用的时间格式。 */
+ public String pattern() {
+ return pattern;
+ }
+
+ /** 按当前时区与格式渲染时间;包内可见,便于单测。 */
+ String format(Instant instant) {
+ return formatter.format(instant);
+ }
+
+ @Override
+ public void onCall(CallRecord record) {
+ if (record.failed()) {
+ LOG.warn("sdk-call-failed at={} op={} provider={} platform={} omsStoreId={} storeId={} "
+ + "requestId={} cost={}ms result={} params={} retryable={} platformRequestId={} "
+ + "error={}: {}",
+ at(record.occurredAt()),
+ record.operation(), record.provider(), record.platform(),
+ record.omsStoreId(), record.externalStoreId(), record.requestId(),
+ record.durationMillis(), record.resultCount(), record.params(),
+ record.retryable(), record.platformRequestId(),
+ record.errorType(), record.errorMessage());
+ } else {
+ LOG.info("sdk-call at={} op={} provider={} platform={} omsStoreId={} storeId={} "
+ + "requestId={} cost={}ms result={} params={}",
+ at(record.occurredAt()),
+ record.operation(), record.provider(), record.platform(),
+ record.omsStoreId(), record.externalStoreId(), record.requestId(),
+ record.durationMillis(), record.resultCount(), record.params());
+ }
+ }
+
+ private String at(Instant instant) {
+ return format(instant);
+ }
+}
diff --git a/core/src/main/java/common/ecommerce/capability/AfterSales.java b/core/src/main/java/common/ecommerce/capability/AfterSales.java
index f932feb..7ac744f 100644
--- a/core/src/main/java/common/ecommerce/capability/AfterSales.java
+++ b/core/src/main/java/common/ecommerce/capability/AfterSales.java
@@ -1,11 +1,13 @@
package common.ecommerce.capability;
+import common.ecommerce.audit.CallObserver;
import common.ecommerce.error.ChannelException;
import common.ecommerce.model.Capability;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.aftersale.AfterSale;
import common.ecommerce.model.aftersale.AfterSaleQuery;
import common.ecommerce.model.support.Page;
+import common.ecommerce.sdk.CallSupport;
import common.ecommerce.sdk.ChannelContext;
/**
@@ -16,16 +18,35 @@ public final class AfterSales {
private final PlatformAdapter adapter;
private final ChannelAccount account;
private final ChannelContext ctx;
+ private final CallObserver observer;
public AfterSales(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) {
+ this(adapter, account, ctx, CallObserver.NOOP);
+ }
+
+ public AfterSales(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx,
+ CallObserver observer) {
this.adapter = adapter;
this.account = account;
this.ctx = ctx;
+ this.observer = observer == null ? CallObserver.NOOP : observer;
}
- public Page pull(AfterSaleQuery query) {
- requireAfterSaleCapable();
- return ((AfterSaleCapable) adapter).pull(ctx, query);
+ public Page pull(final AfterSaleQuery query) {
+ return CallSupport.observe(observer, ctx, "afterSales.pull",
+ CallSupport.params(
+ "startDate", query.startDate(),
+ "endDate", query.endDate(),
+ "dateType", query.dateType(),
+ "typeCount", query.types().size(),
+ "channelOrderIdCount", query.channelOrderIds().size(),
+ "pageSize", query.pageSize(),
+ "cursor", query.cursor()),
+ page -> page.size(),
+ () -> {
+ requireAfterSaleCapable();
+ return ((AfterSaleCapable) adapter).pull(ctx, query);
+ });
}
private void requireAfterSaleCapable() {
diff --git a/core/src/main/java/common/ecommerce/capability/Outbounds.java b/core/src/main/java/common/ecommerce/capability/Outbounds.java
index 3984d18..8ceba1a 100644
--- a/core/src/main/java/common/ecommerce/capability/Outbounds.java
+++ b/core/src/main/java/common/ecommerce/capability/Outbounds.java
@@ -1,5 +1,6 @@
package common.ecommerce.capability;
+import common.ecommerce.audit.CallObserver;
import common.ecommerce.error.ChannelException;
import common.ecommerce.model.Capability;
import common.ecommerce.model.account.ChannelAccount;
@@ -11,6 +12,7 @@ import common.ecommerce.model.fulfillment.OutboundResult;
import common.ecommerce.model.fulfillment.ShipmentReviewResult;
import common.ecommerce.model.fulfillment.ShippingLabel;
import common.ecommerce.model.support.Page;
+import common.ecommerce.sdk.CallSupport;
import common.ecommerce.sdk.ChannelContext;
import java.util.List;
@@ -26,39 +28,81 @@ public final class Outbounds {
private final PlatformAdapter adapter;
private final ChannelAccount account;
private final ChannelContext ctx;
+ private final CallObserver observer;
public Outbounds(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) {
+ this(adapter, account, ctx, CallObserver.NOOP);
+ }
+
+ public Outbounds(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx,
+ CallObserver observer) {
this.adapter = adapter;
this.account = account;
this.ctx = ctx;
+ this.observer = observer == null ? CallObserver.NOOP : observer;
}
- public boolean submit(List packages) {
- requireOutboundCapable();
- return ((OutboundCapable) adapter).submit(ctx, packages);
+ public boolean submit(final List packages) {
+ return CallSupport.observe(observer, ctx, "outbounds.submit",
+ CallSupport.params("packageCount", packages == null ? 0 : packages.size()),
+ result -> CallSupport.NO_COUNT,
+ () -> {
+ requireOutboundCapable();
+ return ((OutboundCapable) adapter).submit(ctx, packages);
+ });
}
- public OutboundResult results(List globalOrderNos) {
- requireOutboundCapable();
- return ((OutboundCapable) adapter).results(ctx, globalOrderNos);
+ public OutboundResult results(final List globalOrderNos) {
+ return CallSupport.observe(observer, ctx, "outbounds.results",
+ CallSupport.params("orderCount", globalOrderNos == null ? 0 : globalOrderNos.size()),
+ result -> CallSupport.NO_COUNT,
+ () -> {
+ requireOutboundCapable();
+ return ((OutboundCapable) adapter).results(ctx, globalOrderNos);
+ });
}
/** 销售出库单列表。 */
- public Page pull(OutboundOrderQuery query) {
- require(Capability.OUTBOUND_ORDER, OutboundOrderCapable.class);
- return ((OutboundOrderCapable) adapter).pull(ctx, query);
+ public Page pull(final OutboundOrderQuery query) {
+ return CallSupport.observe(observer, ctx, "outbounds.pull",
+ CallSupport.params(
+ "after", query.after(),
+ "before", query.before(),
+ "timeType", query.timeType(),
+ "sidCount", query.sids().size(),
+ "statuses", query.statuses(),
+ "logisticsStatuses", query.logisticsStatuses(),
+ "pageSize", query.pageSize(),
+ "cursor", query.cursor()),
+ page -> page.size(),
+ () -> {
+ require(Capability.OUTBOUND_ORDER, OutboundOrderCapable.class);
+ return ((OutboundOrderCapable) adapter).pull(ctx, query);
+ });
}
/** 销售出库单物流面单。 */
- public List labels(LabelQuery query) {
- require(Capability.LABEL, ShippingLabelCapable.class);
- return ((ShippingLabelCapable) adapter).labels(ctx, query);
+ public List labels(final LabelQuery query) {
+ return CallSupport.observe(observer, ctx, "outbounds.labels",
+ CallSupport.params(
+ "woCount", query.woNumbers().size(),
+ "orderCount", query.orderNumbers().size()),
+ labels -> labels.size(),
+ () -> {
+ require(Capability.LABEL, ShippingLabelCapable.class);
+ return ((ShippingLabelCapable) adapter).labels(ctx, query);
+ });
}
/** 审核发货(写操作,调用方需包在 {@code sdk.writes()} 里)。 */
- public ShipmentReviewResult review(List globalOrderNos) {
- require(Capability.SHIPMENT_REVIEW, ShipmentReviewCapable.class);
- return ((ShipmentReviewCapable) adapter).review(ctx, globalOrderNos);
+ public ShipmentReviewResult review(final List globalOrderNos) {
+ return CallSupport.observe(observer, ctx, "outbounds.review",
+ CallSupport.params("orderCount", globalOrderNos == null ? 0 : globalOrderNos.size()),
+ result -> CallSupport.NO_COUNT,
+ () -> {
+ require(Capability.SHIPMENT_REVIEW, ShipmentReviewCapable.class);
+ return ((ShipmentReviewCapable) adapter).review(ctx, globalOrderNos);
+ });
}
private void requireOutboundCapable() {
diff --git a/core/src/main/java/common/ecommerce/capability/Products.java b/core/src/main/java/common/ecommerce/capability/Products.java
index 19a16fb..adb8994 100644
--- a/core/src/main/java/common/ecommerce/capability/Products.java
+++ b/core/src/main/java/common/ecommerce/capability/Products.java
@@ -1,5 +1,6 @@
package common.ecommerce.capability;
+import common.ecommerce.audit.CallObserver;
import common.ecommerce.error.ChannelException;
import common.ecommerce.model.Capability;
import common.ecommerce.model.account.ChannelAccount;
@@ -7,6 +8,7 @@ import common.ecommerce.model.support.Page;
import common.ecommerce.model.product.ProductListing;
import common.ecommerce.model.product.ProductQuery;
import common.ecommerce.model.product.ProductRef;
+import common.ecommerce.sdk.CallSupport;
import common.ecommerce.sdk.ChannelContext;
/** 门面持有的商品视图。 */
@@ -15,21 +17,45 @@ public final class Products {
private final PlatformAdapter adapter;
private final ChannelAccount account;
private final ChannelContext ctx;
+ private final CallObserver observer;
public Products(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) {
+ this(adapter, account, ctx, CallObserver.NOOP);
+ }
+
+ public Products(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx,
+ CallObserver observer) {
this.adapter = adapter;
this.account = account;
this.ctx = ctx;
+ this.observer = observer == null ? CallObserver.NOOP : observer;
}
- public Page pull(ProductQuery query) {
- requireProductCapable();
- return ((ProductCapable) adapter).pull(ctx, query);
+ public Page pull(final ProductQuery query) {
+ return CallSupport.observe(observer, ctx, "products.pull",
+ CallSupport.params(
+ "updatedAfter", query.updatedAfter(),
+ "updatedBefore", query.updatedBefore(),
+ "pageSize", query.pageSize(),
+ "cursor", query.cursor(),
+ "searchField", query.searchField(),
+ "searchValue", query.searchValue(),
+ "searchValueCount", query.searchValues().size()),
+ page -> page.size(),
+ () -> {
+ requireProductCapable();
+ return ((ProductCapable) adapter).pull(ctx, query);
+ });
}
- public ProductListing get(String platformSku) {
- requireProductCapable();
- return ((ProductCapable) adapter).get(ctx, ProductRef.of(platformSku));
+ public ProductListing get(final String platformSku) {
+ return CallSupport.observe(observer, ctx, "products.get",
+ CallSupport.params("platformSku", platformSku),
+ result -> 1,
+ () -> {
+ requireProductCapable();
+ return ((ProductCapable) adapter).get(ctx, ProductRef.of(platformSku));
+ });
}
private void requireProductCapable() {
diff --git a/core/src/main/java/common/ecommerce/capability/SalesOrders.java b/core/src/main/java/common/ecommerce/capability/SalesOrders.java
index fad45d2..5fcb3d3 100644
--- a/core/src/main/java/common/ecommerce/capability/SalesOrders.java
+++ b/core/src/main/java/common/ecommerce/capability/SalesOrders.java
@@ -1,49 +1,81 @@
package common.ecommerce.capability;
+import common.ecommerce.audit.CallObserver;
+import common.ecommerce.error.ChannelException;
import common.ecommerce.model.Capability;
import common.ecommerce.model.account.ChannelAccount;
-import common.ecommerce.error.ChannelException;
import common.ecommerce.model.fulfillment.OrderEditRequest;
import common.ecommerce.model.fulfillment.OrderEditResult;
import common.ecommerce.model.order.SalesOrder;
import common.ecommerce.model.order.SalesOrderQuery;
import common.ecommerce.model.order.SalesOrderRef;
import common.ecommerce.model.support.Page;
+import common.ecommerce.sdk.CallSupport;
import common.ecommerce.sdk.ChannelContext;
import java.util.List;
/**
* 门面持有的销售订单视图。调用前做能力检查,缺失时显式拒绝。
+ *
+ * 每次调用都会生成一条 {@code CallRecord} 交给 {@link CallObserver},
+ * 默认是空实现,注入方式见 {@code ChannelSdk.Builder#callObserver}。
*/
public final class SalesOrders {
private final PlatformAdapter adapter;
private final ChannelAccount account;
private final ChannelContext ctx;
+ private final CallObserver observer;
public SalesOrders(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) {
+ this(adapter, account, ctx, CallObserver.NOOP);
+ }
+
+ public SalesOrders(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx,
+ CallObserver observer) {
this.adapter = adapter;
this.account = account;
this.ctx = ctx;
+ this.observer = observer == null ? CallObserver.NOOP : observer;
}
- public Page pull(SalesOrderQuery query) {
- requireSalesOrderCapable();
- return ((SalesOrderCapable) adapter).pull(ctx, query);
+ public Page pull(final SalesOrderQuery query) {
+ return CallSupport.observe(observer, ctx, "salesOrders.pull",
+ CallSupport.params(
+ "updatedAfter", query.updatedAfter(),
+ "updatedBefore", query.updatedBefore(),
+ "pageSize", query.pageSize(),
+ "cursor", query.cursor()),
+ page -> page.size(),
+ () -> {
+ requireSalesOrderCapable();
+ return ((SalesOrderCapable) adapter).pull(ctx, query);
+ });
}
- public SalesOrder get(String channelOrderId) {
- requireSalesOrderCapable();
- return ((SalesOrderCapable) adapter).get(ctx, SalesOrderRef.of(channelOrderId));
+ public SalesOrder get(final String channelOrderId) {
+ return CallSupport.observe(observer, ctx, "salesOrders.get",
+ CallSupport.params("channelOrderId", channelOrderId),
+ result -> 1,
+ () -> {
+ requireSalesOrderCapable();
+ return ((SalesOrderCapable) adapter).get(ctx, SalesOrderRef.of(channelOrderId));
+ });
}
/** 批量编辑订单(写操作,调用方需包在 {@code sdk.writes()} 里)。 */
- public OrderEditResult edit(List requests) {
- if (!adapter.supports(account, Capability.ORDER_EDIT) || !(adapter instanceof OrderEditCapable)) {
- throw new ChannelException.UnsupportedCapabilityException(Capability.ORDER_EDIT);
- }
- return ((OrderEditCapable) adapter).edit(ctx, requests);
+ public OrderEditResult edit(final List requests) {
+ return CallSupport.observe(observer, ctx, "salesOrders.edit",
+ CallSupport.params("requestCount", requests == null ? 0 : requests.size()),
+ result -> CallSupport.NO_COUNT,
+ () -> {
+ if (!adapter.supports(account, Capability.ORDER_EDIT)
+ || !(adapter instanceof OrderEditCapable)) {
+ throw new ChannelException.UnsupportedCapabilityException(Capability.ORDER_EDIT);
+ }
+ return ((OrderEditCapable) adapter).edit(ctx, requests);
+ });
}
private void requireSalesOrderCapable() {
diff --git a/core/src/main/java/common/ecommerce/capability/Settlements.java b/core/src/main/java/common/ecommerce/capability/Settlements.java
index 9f6e110..790af8a 100644
--- a/core/src/main/java/common/ecommerce/capability/Settlements.java
+++ b/core/src/main/java/common/ecommerce/capability/Settlements.java
@@ -1,11 +1,13 @@
package common.ecommerce.capability;
+import common.ecommerce.audit.CallObserver;
import common.ecommerce.error.ChannelException;
import common.ecommerce.model.Capability;
import common.ecommerce.model.account.ChannelAccount;
import common.ecommerce.model.settlement.SettlementQuery;
import common.ecommerce.model.settlement.SettlementTransaction;
import common.ecommerce.model.support.Page;
+import common.ecommerce.sdk.CallSupport;
import common.ecommerce.sdk.ChannelContext;
/**
@@ -16,16 +18,38 @@ public final class Settlements {
private final PlatformAdapter adapter;
private final ChannelAccount account;
private final ChannelContext ctx;
+ private final CallObserver observer;
public Settlements(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx) {
+ this(adapter, account, ctx, CallObserver.NOOP);
+ }
+
+ public Settlements(PlatformAdapter adapter, ChannelAccount account, ChannelContext ctx,
+ CallObserver observer) {
this.adapter = adapter;
this.account = account;
this.ctx = ctx;
+ this.observer = observer == null ? CallObserver.NOOP : observer;
}
- public Page pull(SettlementQuery query) {
- requireSettlementCapable();
- return ((SettlementCapable) adapter).pull(ctx, query);
+ public Page pull(final SettlementQuery query) {
+ return CallSupport.observe(observer, ctx, "settlements.pull",
+ CallSupport.params(
+ "settledAfter", query.settledAfter(),
+ "settledBefore", query.settledBefore(),
+ "modifiedAfter", query.modifiedAfter(),
+ "modifiedBefore", query.modifiedBefore(),
+ "eventType", query.eventType(),
+ "transactionType", query.transactionType(),
+ "searchField", query.searchField(),
+ "searchValueCount", query.searchValues().size(),
+ "pageSize", query.pageSize(),
+ "cursor", query.cursor()),
+ page -> page.size(),
+ () -> {
+ requireSettlementCapable();
+ return ((SettlementCapable) adapter).pull(ctx, query);
+ });
}
private void requireSettlementCapable() {
diff --git a/core/src/main/java/common/ecommerce/sdk/CallSupport.java b/core/src/main/java/common/ecommerce/sdk/CallSupport.java
new file mode 100644
index 0000000..8300416
--- /dev/null
+++ b/core/src/main/java/common/ecommerce/sdk/CallSupport.java
@@ -0,0 +1,136 @@
+package common.ecommerce.sdk;
+
+import common.ecommerce.audit.CallObserver;
+import common.ecommerce.audit.CallOutcome;
+import common.ecommerce.audit.CallRecord;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.time.Instant;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.function.Supplier;
+
+/**
+ * 门面埋点工具:统计耗时、结果数量与异常,生成 {@link CallRecord} 并回调
+ * {@link CallObserver}。
+ *
+ * 不是公开 API,只给 core 内部的门面使用。SDK 不写日志目的地,
+ * 落库 / 发 MQ / 接监控都交给宿主实现的 {@link CallObserver}。
+ *
+ * 约定:
+ *
+ * - 观察者异常一律吞掉并打 WARN,绝不影响业务调用;
+ * - 业务异常原样抛出,不包装、不改变类型;
+ * - 耗时用 {@code ChannelContext} 的时钟,测试注入固定时钟时为 0。
+ *
+ */
+public final class CallSupport {
+
+ private static final Logger LOG = LoggerFactory.getLogger(CallSupport.class);
+
+ /** 结果数量不适用(单对象、写操作等)。 */
+ public static final int NO_COUNT = -1;
+
+ private CallSupport() {
+ }
+
+ /**
+ * 构造参数摘要,按 {@code key1, value1, key2, value2, ...} 传入。
+ *
+ * 只放排查用的非敏感摘要(时间窗、分页、游标、数量),
+ * 不要放密钥、买家信息、完整报文。
+ */
+ public static Map params(Object... keyValues) {
+ if (keyValues == null || keyValues.length == 0) {
+ return Collections.emptyMap();
+ }
+ if (keyValues.length % 2 != 0) {
+ throw new IllegalArgumentException("params must be key/value pairs");
+ }
+ Map map = new LinkedHashMap<>();
+ for (int i = 0; i < keyValues.length; i += 2) {
+ Object key = keyValues[i];
+ if (key == null) {
+ continue;
+ }
+ map.put(String.valueOf(key), keyValues[i + 1]);
+ }
+ return map;
+ }
+
+ /** 从返回值里取结果数量;不适用时返回 {@link #NO_COUNT}。 */
+ public interface ResultSize {
+
+ int sizeOf(T result);
+ }
+
+ /**
+ * 执行一次门面调用并记录日志。
+ *
+ * @param observer 观察者;null 等价于 {@link CallObserver#NOOP}
+ * @param ctx 本次调用上下文(提供账户、链路 ID、时钟)
+ * @param operation 操作名,如 {@code salesOrders.pull}
+ * @param params 参数摘要,见 {@link #params(Object...)}
+ * @param resultSize 结果数量提取器;不关心数量时传 {@code null}
+ * @param action 真正的适配器调用
+ */
+ public static T observe(CallObserver observer, ChannelContext ctx, String operation,
+ Map params, ResultSize resultSize,
+ Supplier action) {
+ CallObserver effective = observer == null ? CallObserver.NOOP : observer;
+ Instant startedAt = Instant.now(ctx.clock());
+ long startedMillis = ctx.clock().millis();
+ try {
+ T result = action.get();
+ notifyObserver(effective, ctx, operation, params, resultSize,
+ result, null, startedAt, startedMillis);
+ return result;
+ } catch (RuntimeException e) {
+ notifyObserver(effective, ctx, operation, params, resultSize,
+ null, e, startedAt, startedMillis);
+ throw e;
+ }
+ }
+
+ private static void notifyObserver(CallObserver observer, ChannelContext ctx, String operation,
+ Map params, ResultSize resultSize,
+ T result, RuntimeException error,
+ Instant startedAt, long startedMillis) {
+ int count = NO_COUNT;
+ if (error == null && result != null && resultSize != null) {
+ try {
+ count = resultSize.sizeOf(result);
+ } catch (RuntimeException e) {
+ // 提取数量失败不应该影响业务结果,按“不适用”处理
+ count = NO_COUNT;
+ }
+ }
+
+ CallRecord.Builder record = CallRecord.builder()
+ .occurredAt(startedAt)
+ .requestId(ctx.requestId())
+ .provider(ctx.provider())
+ .platform(ctx.platform())
+ .omsStoreId(ctx.omsStoreId())
+ .externalStoreId(ctx.account().externalStoreId())
+ .operation(operation)
+ .durationMillis(Math.max(0L, ctx.clock().millis() - startedMillis))
+ .resultCount(count)
+ .params(params);
+ if (error == null) {
+ record.outcome(CallOutcome.SUCCESS);
+ } else {
+ record.outcome(CallOutcome.FAILURE).error(error);
+ }
+
+ try {
+ observer.onCall(record.build());
+ } catch (RuntimeException e) {
+ // 观察者自己的问题不能影响业务调用,只在自己的日志里留痕
+ LOG.warn("sdk call observer failed, record dropped: op={} requestId={}",
+ operation, ctx.requestId(), e);
+ }
+ }
+}
diff --git a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
index 47aff82..b27cd9e 100644
--- a/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
+++ b/core/src/main/java/common/ecommerce/sdk/ChannelSdk.java
@@ -1,6 +1,7 @@
package common.ecommerce.sdk;
import common.ecommerce.model.Platform;
+import common.ecommerce.audit.CallObserver;
import common.ecommerce.capability.AdapterCapabilityReport;
import common.ecommerce.capability.AfterSales;
import common.ecommerce.capability.AggregatorCapable;
@@ -86,6 +87,14 @@ public final class ChannelSdk implements ProviderResolver {
*/
private final IdempotencyGuard idempotencyGuard;
+ /**
+ * 调用观察者(操作日志)。
+ *
+ * 默认 {@link CallObserver#NOOP};注入后每次门面调用结束都会回调一条
+ * {@code CallRecord},成功与失败都记。
+ */
+ private final CallObserver callObserver;
+
private ChannelSdk(Builder b) {
this.adapters = Collections.unmodifiableMap(new LinkedHashMap(b.adapters));
this.accountRepository = b.accountRepository;
@@ -93,6 +102,7 @@ public final class ChannelSdk implements ProviderResolver {
this.idempotencyGuard = b.idempotencyStore == null ? null
: new IdempotencyGuard(b.idempotencyStore, b.idempotencyOwner, b.clock,
IdempotencyGuard.DEFAULT_CLAIM_TTL_SECONDS);
+ this.callObserver = b.callObserver == null ? CallObserver.NOOP : b.callObserver;
}
public static Builder builder() {
@@ -122,7 +132,7 @@ public final class ChannelSdk implements ProviderResolver {
*/
public SalesOrders salesOrders(AccountKey key, ChannelConnection connection) {
ChannelAccount account = requireAccount(key);
- return new SalesOrders(resolve(key), account, newContext(account, connection));
+ return new SalesOrders(resolve(key), account, newContext(account, connection), callObserver);
}
/**
@@ -132,13 +142,13 @@ public final class ChannelSdk implements ProviderResolver {
*/
public Products products(AccountKey key, ChannelConnection connection) {
ChannelAccount account = requireAccount(key);
- return new Products(resolve(key), account, newContext(account, connection));
+ return new Products(resolve(key), account, newContext(account, connection), callObserver);
}
/** 结算 / 账单交易明细视图。 */
public Settlements settlements(AccountKey key, ChannelConnection connection) {
ChannelAccount account = requireAccount(key);
- return new Settlements(resolve(key), account, newContext(account, connection));
+ return new Settlements(resolve(key), account, newContext(account, connection), callObserver);
}
/**
@@ -149,7 +159,7 @@ public final class ChannelSdk implements ProviderResolver {
*/
public AfterSales afterSales(AccountKey key, ChannelConnection connection) {
ChannelAccount account = requireAccount(key);
- return new AfterSales(resolve(key), account, newContext(account, connection));
+ return new AfterSales(resolve(key), account, newContext(account, connection), callObserver);
}
/**
@@ -159,7 +169,7 @@ public final class ChannelSdk implements ProviderResolver {
*/
public Outbounds outbounds(AccountKey key, ChannelConnection connection) {
ChannelAccount account = requireAccount(key);
- return new Outbounds(resolve(key), account, newContext(account, connection));
+ return new Outbounds(resolve(key), account, newContext(account, connection), callObserver);
}
/**
@@ -172,11 +182,17 @@ public final class ChannelSdk implements ProviderResolver {
*/
public List subChannels(AccountKey key, ChannelConnection connection) {
ChannelAccount account = requireAccount(key);
- PlatformAdapter adapter = resolve(key);
- if (!(adapter instanceof AggregatorCapable)) {
- throw new IllegalStateException("adapter is not an aggregator: " + key);
- }
- return ((AggregatorCapable) adapter).listSubChannels(newContext(account, connection));
+ final PlatformAdapter adapter = resolve(key);
+ final ChannelContext ctx = newContext(account, connection);
+ return CallSupport.observe(callObserver, ctx, "subChannels.list",
+ CallSupport.params("endpoint", connection.endpointBaseUrl()),
+ channels -> channels.size(),
+ () -> {
+ if (!(adapter instanceof AggregatorCapable)) {
+ throw new IllegalStateException("adapter is not an aggregator: " + key);
+ }
+ return ((AggregatorCapable) adapter).listSubChannels(ctx);
+ });
}
/**
@@ -249,6 +265,9 @@ public final class ChannelSdk implements ProviderResolver {
/** 幂等抢占方标识,多实例部署时应能区分;缺省随机 UUID。 */
private String idempotencyOwner = UUID.randomUUID().toString();
+ /** 调用观察者,默认不记录。 */
+ private CallObserver callObserver = CallObserver.NOOP;
+
/** 时钟,默认 UTC;测试注入固定时钟。 */
private Clock clock = Clock.systemUTC();
@@ -292,6 +311,22 @@ public final class ChannelSdk implements ProviderResolver {
}
/**
+ * 注入调用观察者(操作日志 / 审计日志)。
+ *
+ * 每次门面调用结束回调一次 {@code CallRecord},成功与失败都记;
+ * 不注入时为空实现,不做任何记录。SDK 不落盘、不起线程,
+ * 落库 / MQ / 监控由宿主在 {@link CallObserver#onCall} 里实现。
+ *
+ * 最省事的写法是 {@code callObserver(new Slf4jCallObserver())};
+ * 需要审计时实现自己的 {@link CallObserver}。观察者抛出的异常会被吞掉并打 WARN,
+ * 不会影响业务调用。
+ */
+ public Builder callObserver(CallObserver callObserver) {
+ this.callObserver = callObserver;
+ return this;
+ }
+
+ /**
* 注册适配器工厂。
*
* 生产推荐这种写法:工厂在 {@link #build()} 时调用 {@code create(...)},