Browse Source

docs(readme): 包结构改为按当前代码目录展开

- 「一、包职责」改为「一、包结构」,按 shared / channel / http / lingxing
  实际包与类逐目录列出,lingxing 下展开到子平台(含各自 dto/product/order/shop)
- testkit 归到 shared.testkit 下展示,与实际包名一致
- GUIDE / 操作手册 中指向 README 的说法同步

Co-Authored-By: Claude <noreply@anthropic.com>
feature/supplier-lingxing
chenchuchuan 2 weeks ago
parent
commit
86843c4b5a
  1. 2
      GUIDE.md
  2. 153
      README.md
  3. 2
      操作手册.md

2
GUIDE.md

@ -3,7 +3,7 @@ @@ -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 总体设计)。
---

153
README.md

@ -139,33 +139,132 @@ mvn clean test @@ -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 @@ -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` |
| 类 | 包袱 | 职责 |
|:---|:---|:---|

2
操作手册.md

@ -1,7 +1,7 @@ @@ -1,7 +1,7 @@
# common-ecommerce 操作手册
> 面向接入本 SDK 的宿主开发者。本文只讲**怎么调、参数怎么传**。
> 设计原理见 [`GUIDE.md`](GUIDE.md),包职责速查见 [`README.md`](README.md)。
> 设计原理见 [`GUIDE.md`](GUIDE.md),架构图与包结构见 [`README.md`](README.md)。
---

Loading…
Cancel
Save