From 86843c4b5a4cb82c9aa72e31546a7f5591a68ee3 Mon Sep 17 00:00:00 2001 From: chenchuchuan <13554600537@163.com> Date: Fri, 6 Nov 2026 17:58:27 +0800 Subject: [PATCH] =?UTF-8?q?docs(readme):=20=E5=8C=85=E7=BB=93=E6=9E=84?= =?UTF-8?q?=E6=94=B9=E4=B8=BA=E6=8C=89=E5=BD=93=E5=89=8D=E4=BB=A3=E7=A0=81?= =?UTF-8?q?=E7=9B=AE=E5=BD=95=E5=B1=95=E5=BC=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 「一、包职责」改为「一、包结构」,按 shared / channel / http / lingxing 实际包与类逐目录列出,lingxing 下展开到子平台(含各自 dto/product/order/shop) - testkit 归到 shared.testkit 下展示,与实际包名一致 - GUIDE / 操作手册 中指向 README 的说法同步 Co-Authored-By: Claude --- GUIDE.md | 2 +- README.md | 153 +++++++++++++++++++++++++++++++++++++++++++++----------- 操作手册.md | 2 +- 3 files changed, 127 insertions(+), 30 deletions(-) diff --git a/GUIDE.md b/GUIDE.md index 727e78b..f1da7cc 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -3,7 +3,7 @@ > 面向「要接入一个新平台」和「要写业务调用」的人。 > 读完之后你应该能回答三个问题:SDK 的分层是什么、加一个供应商要动哪些文件、加完之后怎么测。 > -> 配套材料:`README.md`(包职责与调用方式速查)、`D:\woker\文档\01需求分析\2026-10-28-电商平台\2026-10-26-cross-border-fulfillment-sdk-design.md`(Spec 0 总体设计)。 +> 配套材料:`README.md`(架构图、包结构与调用方式速查)、`D:\woker\文档\01需求分析\2026-10-28-电商平台\2026-10-26-cross-border-fulfillment-sdk-design.md`(Spec 0 总体设计)。 --- diff --git a/README.md b/README.md index 90b475d..69fa6c7 100644 --- a/README.md +++ b/README.md @@ -139,33 +139,132 @@ mvn clean test --- -## 一、包职责 +## 一、包结构 + +按当前代码实际目录生成(`src/main/java`,测试包与主代码同构)。模块名在注释里标出。 ``` common.ecommerce -├── shared 跨域共享层(shared) -│ ├── model Platform / ChannelProvider / Capability / FulfillmentMode -│ ├── error 统一异常体系 -│ ├── spi AccessToken / TokenStore / LockProvider / IdempotencyStore / SyncCursorStore … -│ ├── idempotency 写操作双锁幂等守卫 -│ ├── audit CallObserver / CallRecord -│ ├── sync SyncSpec / SyncResult -│ └── support Money / PlatformTime / Page / CanonicalKeys -├── channel 渠道域(channel) -│ ├── model 领域模型 -│ │ ├── account AccountKey / ChannelAccount -│ │ ├── order SalesOrder / OrderLine / Query / Ref -│ │ ├── product ProductListing / Query / Ref / SearchField / SyncStrategy -│ │ ├── fulfillment OutboundOrder / OutboundPackage / ShippingLabel / OrderEdit / ShipmentReview -│ │ ├── aftersale AfterSale / Query / Type -│ │ └── settlement SettlementQuery / SettlementTransaction -│ ├── capability 能力接口,适配器实现这些 -│ ├── sdk 门面、上下文、适配器工厂接口 -│ ├── sync 同步引擎 -│ └── spi ChannelAccountRepository / Sink -├── http HTTP 传输、JSON、签名、令牌(http) -├── testkit 测试替身与夹具(testkit) -└── lingxing 领星适配器(lingxing) +│ +├── shared 跨域共享层(shared) +│ ├── model Platform / ChannelProvider / Capability / FulfillmentMode +│ ├── error ChannelException + Auth / RateLimit / Transient / Validation / +│ │ PlatformBusiness / IdempotencyConflict / CrossProviderConflict +│ ├── spi AccessToken / ChannelSecret / TokenStore / LockProvider / +│ │ IdempotencyStore(+Claim/Record/Status) / SyncCursorStore / +│ │ SecretProvider(已废弃) +│ ├── idempotency IdempotencyGuard / WriteScope / WriteResult / WriteAudit +│ ├── audit CallObserver / CallRecord / CallOutcome / Slf4jCallObserver +│ ├── sync SyncSpec / SyncResult +│ ├── support Money / PlatformTime / Page / CanonicalKeys +│ └── testkit 测试替身(testkit 模块): +│ FakeDirectAdapter / InMemory*(Accounts·Token·Cursor·Sink· +│ Lock·Idempotency) / RecordingTransport / Responses / +│ JsonFixture / MutableClock / TestData +│ +├── channel 渠道域(channel) +│ ├── model +│ │ ├── account AccountKey / ChannelAccount +│ │ ├── order SalesOrder / OrderLine / SalesOrderQuery / SalesOrderRef +│ │ ├── product ProductListing / ProductQuery / ProductRef / +│ │ │ ProductSearchField / ProductStatus / ProductSyncStrategy +│ │ ├── fulfillment DeclaredItem / LabelQuery / OrderEditRequest / OrderEditResult / +│ │ │ OutboundOrder / OutboundOrderLine / OutboundOrderQuery / +│ │ │ OutboundPackage / OutboundResult / ShipmentReviewResult / +│ │ │ ShippingLabel +│ │ ├── aftersale AfterSale / AfterSaleQuery / AfterSaleType +│ │ └── settlement SettlementQuery / SettlementTransaction +│ ├── capability PlatformAdapter / AggregatorCapable / CapabilityReport / +│ │ AdapterCapabilityReport / +│ │ SalesOrderCapable / ProductCapable / SettlementCapable / +│ │ AfterSaleCapable / OutboundCapable / OutboundOrderCapable / +│ │ ShippingLabelCapable / ShipmentReviewCapable / OrderEditCapable / +│ │ 门面视图:SalesOrders / Products / Settlements / AfterSales / Outbounds +│ ├── sdk ChannelSdk / ChannelContext / ChannelConnection / +│ │ AdapterFactory / ProviderResolver / CallSupport +│ ├── spi ChannelAccountRepository / Sink +│ └── sync SyncEngine +│ +├── http HTTP 与令牌(http) +│ HttpTransport / OkHttpTransport / HttpRequest / HttpResponse / +│ JsonCodec / JacksonJsonCodec / Signer / TokenManager / Responses +│ +└── lingxing 领星聚合适配器(lingxing) + ├── LingxingApi 接口定义(路径 + 限流参数) + ├── LingxingConstants 端点、分页/时间窗限制、platform_code → Platform + ├── adapter LingxingAdapter / LingxingAdapterFactory + ├── auth LingxingTokenClient + ├── http LingxingSigner / LingxingRequestFactory / LingxingRateLimiter / + │ LingxingEnvelope + ├── mapper LingxingOrderMapper + ├── dto 订单报文:LingxingOrderDto / OrderItem / OrderTag / LogisticsInfo / + │ PlatformInfo / SubProduct / TransactionInfo + └── platform + ├── LingxingSubPlatform / LingxingSubPlatforms / LingxingSubPlatformDefaults + ├── LingxingCall 每次调用的公共设施(token/限流/签名/信封) + ├── Lingxing{Order,Product,Shop,Settlement,AfterSale,Outbound}Source + ├── Lingxing{OutboundOrder,Label,ShipmentReview,OrderEdit}Source ERP 级,全平台共用 + │ + ├── multiplatform/ 多平台统一接口(大多数子平台共用) + │ ├── order MultiPlatformOrderSource / LingxingOrderFilters + │ ├── product LingxingProductSearchMapper / LingxingProductSearchBody + │ ├── shop MultiPlatformShopSource + │ ├── outbound MultiPlatformOutboundSource / OutboundOkDto / OutboundFailDto + │ └── dto MultiPlatformShopDto + │ + ├── amazon/ + │ ├── dto FbmOrderDto / FbmOrderItemDto + │ ├── order AmazonOrderSource / AmazonFbmOrderSource + │ ├── sc/ AmazonScSubPlatform + │ │ ├── product AmazonScProductSource + │ │ ├── shop AmazonScShopSource + │ │ └── dto AmazonOrder(Dto|Item|DetailDto|DetailItemDto) / + │ │ AmazonScListingDto / AmazonScShopDto / + │ │ AmazonSettlementTransactionDto / FbmOrderDetailDto + │ ├── vc/ AmazonVcSubPlatform + │ │ ├── order VcOrderSource + │ │ ├── product AmazonVcProductSource + │ │ ├── shop VcShopSource + │ │ └── dto VcOrderDto / VcOrderItemDto / VcOrderDfDetailDto / + │ │ VcOrderPoDetailDto / VcOrderDetailItemDto / + │ │ AmazonVcListingDto / VcShopDto + │ └── settlement AmazonSettlementSource + │ + ├── wms/ ERP 级实现(不区分平台) + │ ├── WmsOutboundOrderSource / WmsLabelSource / + │ │ ShipmentReviewSource / OrderEditSource + │ └── dto WmsOutboundOrder(Dto|ItemDto) / WmsLogisticsLabelDto / + │ WmsSurfaceFileDto / ShipmentReview(Data|Success|Failure)Dto / + │ OrderEditErrorDto + │ + ├── aftersale/ LingxingAfterSaleListSource / LingxingAfterSaleMapper + │ └── dto AfterSaleDto / AfterSaleItemDto / AmountDetailDto + │ + ├── aliexpress/ AliexpressSubPlatform + │ ├── product AliexpressProductSource + │ └── dto AliexpressListingDto / Warehouse / SupplyPrice + ├── ebay/ EbaySubPlatform + │ ├── product EbayProductSource + │ └── dto EbayListingDto / EbayAutoRestockDto + ├── shein/ SheinSubPlatform + │ ├── product SheinProductSource + │ └── dto SheinListingDto / Site / Warehouse / SupplyPrice + ├── target/ TargetSubPlatform + │ ├── product TargetProductSource + │ └── dto TargetListingDto / TargetLocationDto + ├── temu/ TemuSubPlatform + │ ├── product TemuProductSource + │ └── dto TemuListingDto / Warehouse / SupplyPrice / PromotionalPrice + ├── tiktok/ TiktokSubPlatform + │ ├── product TiktokProductSource + │ └── dto TiktokListingDto / TiktokWarehouseDto + ├── walmart/ WalmartSubPlatform + │ ├── order WalmartOrderSource + │ ├── product WalmartProductSource + │ └── dto WalmartListingDto + │ + └── 仅订单 + 店铺(多平台通用接口): + aeph/ · bestbuy/ · custom/ · echo/ · losdlius/ · michaels/ · mirakl/ · wayfair/ ``` 包名统一前缀 `common.ecommerce.`,下表省略前缀。 @@ -190,14 +289,12 @@ common.ecommerce | 子包 | 内容 | |:---|:---| -| `shared.model` | **枚举**:`Platform` / `ChannelProvider` / `Capability` / `FulfillmentMode` | | `channel.model.account` | `AccountKey` / `ChannelAccount` | | `channel.model.order` | `SalesOrder` / `OrderLine` / `SalesOrderQuery` / `SalesOrderRef` | -| `channel.model.product` | `ProductListing` / `ProductQuery` / `ProductRef` / `ProductSearchField` / `ProductSyncStrategy` | -| `channel.model.fulfillment` | `OutboundOrder` / `OutboundPackage` / `ShippingLabel` / `OrderEditRequest` / `ShipmentReviewResult` … | +| `channel.model.product` | `ProductListing` / `ProductQuery` / `ProductRef` / `ProductSearchField` / `ProductStatus` / `ProductSyncStrategy` | +| `channel.model.fulfillment` | `OutboundOrder` / `OutboundOrderLine` / `OutboundOrderQuery` / `OutboundPackage` / `OutboundResult` / `ShippingLabel` / `LabelQuery` / `OrderEditRequest` / `OrderEditResult` / `ShipmentReviewResult` / `DeclaredItem` | | `channel.model.aftersale` | `AfterSale` / `AfterSaleQuery` / `AfterSaleType` | | `channel.model.settlement` | `SettlementQuery` / `SettlementTransaction` | -| `shared.support` | `Money` / `PlatformTime` / `Page` / `CanonicalKeys` | | 类 | 包袱 | 职责 | |:---|:---|:---| diff --git a/操作手册.md b/操作手册.md index 29a171d..0f1cded 100644 --- a/操作手册.md +++ b/操作手册.md @@ -1,7 +1,7 @@ # common-ecommerce 操作手册 > 面向接入本 SDK 的宿主开发者。本文只讲**怎么调、参数怎么传**。 -> 设计原理见 [`GUIDE.md`](GUIDE.md),包职责速查见 [`README.md`](README.md)。 +> 设计原理见 [`GUIDE.md`](GUIDE.md),架构图与包结构见 [`README.md`](README.md)。 ---