vitepress-template

Appearance

Goods Catalog Integration ​

**Referenced Files in This Document** - [[types.go]](file/bi-api-jushuitan/common/sdkhelper/goods/types.go) - [[api.go]](file/bi-api-jushuitan/common/sdkhelper/goods/api.go) - [[impl.go]](file/bi-api-jushuitan/common/sdkhelper/goods/impl.go) - [[client.go]](file/bi-api-jushuitan/common/sdkhelper/client.go) - [[types.go]](file/bi-api-jushuitan/common/sdkhelper/types.go) - [[jushuitan.go]](file/bi-api-jushuitan/internal/data/client/jushuitan.go) - [[conf.proto]](file/bi-api-jushuitan/internal/conf/conf.proto) - [[main.go]](file/bi-api-jushuitan/cmd/bi-api-jushuitan/main.go) - [[goods_category.pb.go]](file/bi-basic/api/good-category/v1/goods-category.pb.go) - [[goods.pb.go]](file/bi-basic/api/goods/v1/goods.pb.go) - [[goods.go]](file/bi-basic/internal/biz/bo/goods.go) - [[goods_sku.go]](file/bi-basic/internal/biz/bo/goods-sku.go) - [[good_category.go]](file/bi-basic/internal/biz/bo/good-category.go) - [[goods.go]](file/bi-basic/internal/biz/logic/goods.go) - [[goods.go]](file/bi-basic/internal/data/do/goods.go) - [[goods_link_template.go]](file/bi-basic/internal/biz/logic/goods-link-template.go) - [[goods_category.go]](file/bi-basic/internal/data/do/good-category.go) - [[goods.go]](file/bi-basic/internal/service/good-category.go) - [[goods.go]](file/bi-basic/internal/service/goods.go) - [[goods.go]](file/bi-basic/internal/service/consumer-handlers/goods.go) - [[goods.go]](file/bi-api-jushuitan/internal/service/consumer-handlers/goods.go) - [[goods.go]](file/bi-api-jushuitan/internal/service/goods.go) - [[goods.go]](file/bi-api-jushuitan/internal/biz/usecase/goods.go) - [[goods.go]](file/bi-api-jushuitan/internal/biz/repo/goods.go) - [[goods.go]](file/bi-api-jushuitan/internal/data/repo/goods.go) - [[goods.go]](file/bi-api-jushuitan/internal/data/store/goods.go) - [[goods.go]](file/bi-api-jushuitan/internal/data/model/goods-query.go) - [[goods.go]](file/bi-api-jushuitan/internal/data/ratelimit/goods.go) - [[goods.go]](file/bi-api-jushuitan/internal/server/goods.go) - [[goods.go]](file/bi-api-jushuitan/internal/errors/goods.go) - [[goods.go]](file/bi-api-jushuitan/internal/data/message/goods.go) - [[goods.go]](file/bi-api-jushuitan/internal/data/client/jushuitan.go) - [[goods.go]](file/bi-api-jushuitan/internal/service/service.go) - [[goods.go]](file/bi-api-jushuitan/internal/conf/conf.proto) - [[goods.go]](file/bi-api-jushuitan/cmd/bi-api-jushuitan/main.go)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion
  10. Appendices

Introduction ​

This document describes the Jushuitan goods catalog integration within the bi-api-jushuitan service. It covers product data synchronization across SKUs, product attributes, pricing information, category mappings, and platform-to-ERP linkage. It also documents goods upload, query, and update operations with detailed schemas for product master data, product hierarchy management (categories, brands, attribute groups), image and media asset synchronization, and practical workflows for product creation, bulk updates, and category reorganization. Guidance is included for product data validation, attribute mapping between systems, handling of product variants and SKUs, and search optimization and catalog performance tuning.

Project Structure ​

The Jushuitan integration is implemented as a dedicated microservice with a layered architecture:

  • Entry point initializes configuration, logging, service registration, and Kafka consumers.
  • SDK helper encapsulates the Jushuitan API client, request signing, and typed requests/responses.
  • Business logic orchestrates product synchronization, category mapping, and variant handling.
  • Data layer persists and queries product entities and supports rate limiting and message handling.
  • Service layer exposes APIs and integrates with bi-basic services for category and product data.

Diagram sources

Section sources

Core Components ​

  • Jushuitan SDK client: Provides typed requests and responses for goods, category, and mapping operations; handles signing, retries, and logging.
  • Goods API module: Defines request/response schemas for SKU upload/query, item query, SKU mapping, combine SKU, category operations, and history cost price retrieval.
  • Product synchronization pipeline: Orchestrates product creation, updates, and variant handling via bi-basic services and Jushuitan APIs.
  • Category management: Integrates with bi-basic category services to maintain hierarchical category structures and brand/attribute group alignment.
  • Image/media synchronization: Supports product image URLs and media assets via standardized fields in SKU and item schemas.

Key capabilities:

  • Upload and query of SKUs, items (style), SKU-to-platform mappings, and combine SKUs.
  • Category upload/update and query with hierarchical support.
  • Historical cost price retrieval per SKU.
  • Robust error handling and logging for API interactions.

Section sources

Architecture Overview ​

The integration follows a clean architecture with clear separation of concerns:

  • Presentation: HTTP/gRPC servers expose product and category operations.
  • Application: Use cases orchestrate product synchronization and category updates.
  • Domain/Data: Repositories and stores manage persistence and rate-limiting.
  • External integrations: Jushuitan SDK client communicates with the Jushuitan Open Platform.

Diagram sources

Detailed Component Analysis ​

Jushuitan Goods API Module ​

The goods module defines comprehensive schemas for product master data synchronization:

  • ItemSkuUploadRequest: Uploads SKU-level product data including pricing, dimensions, images, supplier info, lifecycle attributes, and labels.
  • SkuQueryRequest/Sku: Queries SKUs with pagination and time-range filters.
  • MallItemQueryRequest/MallItem: Retrieves items (styles) with associated SKUs.
  • SkuMapUploadRequest/SkuMapQuery/SkuMap: Manages mapping between ERP SKUs and external platform identifiers.
  • CombineSkuUploadRequest/CombineSkuQuery/CombineSku: Handles composite product bundles with sub-item quantities.
  • CategoryUploadRequest/CategoryQuery/Category: Manages category hierarchy and leaf-node validation.
  • HistoryCostPriceQueryRequest/HistoryCostPriceQueryResponse/HistoryCostPrice: Retrieves historical cost prices per SKU.

Implementation highlights:

  • API interface abstraction decouples transport from business logic.
  • Implementation delegates to a requester that signs and posts requests to Jushuitan endpoints.
  • Response unmarshalling into typed results with pagination support.

Diagram sources

Section sources

Jushuitan SDK Client and Request Signing ​

The SDK client:

  • Encapsulates configuration (app key, secret, base URL, timeout, logger).
  • Signs requests deterministically using MD5 over sorted parameter keys and values.
  • Logs requests and responses with latency and structured fields.
  • Returns typed responses and unwraps nested data payloads.

Diagram sources

Section sources

Product Master Data Synchronization Workflows ​

  • Goods upload (SKU): Build ItemSkuUploadRequest with required fields (SKU ID, style ID, name) and optional attributes (pricing, dimensions, images, labels). Submit via ItemSkuUpload. Handle response per-item success and messages.
  • Goods query (by SKU): Use SkuQueryRequest with paging and modified date filters to fetch latest product data.
  • Goods query (by item/style): Use MallItemQueryRequest to retrieve items with embedded SKUs for variant management.
  • SKU-to-platform mapping: Use SkuMapUploadRequest to link ERP SKUs to external platform identifiers; query via SkuMapQuery.
  • Combine SKU: Upload composite bundles with sub-items and quantities; query to synchronize bundle definitions.
  • Category mapping: Upload categories with parent-child relationships; query to keep local caches synchronized.

Diagram sources

Section sources

Product Hierarchy Management (Categories, Brands, Attribute Groups) ​

  • Categories: Use CategoryUploadRequest to add or update categories with parent IDs; enforce leaf-node constraint for product classification. Query via CategoryQuery for caching and validation.
  • Brands: Exposed as part of product schemas; ensure brand names align with centralized brand definitions in bi-basic services.
  • Attribute groups: Product attributes (e.g., properties value, other attributes) are mapped to Jushuitan fields; maintain attribute dictionaries for cross-system mapping.

Integration touchpoints:

  • bi-basic category APIs define canonical category structures consumed by the goods service.
  • Local category caches should be refreshed via CategoryQuery to reflect upstream changes.

Section sources

Image and Media Asset Synchronization ​

  • Product images: Fields include style picture, big picture, and SKU-specific picture. Populate these URLs during upload and update to keep listings visually consistent.
  • Media assets: Treat as external URLs; ensure they are accessible and validated before upload. Consider CDN caching and fallbacks.

Operational guidance:

  • Validate image URLs and sizes before submitting uploads.
  • Keep image URLs aligned with platform requirements and branding guidelines.

Section sources

Product Variants and SKUs ​

  • SKU vs Item: Items represent styles; SKUs represent variants (color/size/etc.). Use MallItemQuery to fetch items with embedded SKUs for variant enumeration.
  • Variant attributes: Map product properties (e.g., color/specifications) to Jushuitan properties_value and other attribute fields.
  • Combine SKUs: Composite bundles with sub-item quantities; ensure sub-SKUs exist and quantities are valid.

Validation and mapping:

  • Validate leaf-category requirement for product classification.
  • Ensure unique SKU IDs and consistent style IDs across updates.

Section sources

Product Creation, Bulk Updates, and Category Reorganization ​

  • Product creation: Build ItemSkuUploadRequest with minimal required fields, then submit. Monitor per-item responses and handle partial failures.
  • Bulk updates: Paginate uploads (max 200 items per request) and batch queries for incremental synchronization.
  • Category reorganization: Update parent IDs via CategoryUploadRequest and invalidate local caches; re-validate product category assignments.

Operational tips:

  • Use modified date filters in queries to minimize data transfer.
  • Implement idempotent upsert logic to avoid duplicates.

Section sources

Product Data Validation and Attribute Mapping ​

  • Required fields: SKU ID, style ID, and name are mandatory for SKU upload.
  • Attribute mapping: Align bi-basic product attributes with Jushuitan fields (e.g., properties_value, other attributes). Maintain a mapping dictionary for cross-system compatibility.
  • Validation rules: Validate leaf-category requirement, numeric fields (prices, weights, dimensions), and lifecycle attributes (shelf life, hand day, etc.).

Section sources

Search Optimization and Catalog Performance Tuning ​

  • Pagination: Use page_index and page_size consistently across queries to limit payload sizes.
  • Filtering: Apply modified_begin/modified_end to reduce dataset size for incremental syncs.
  • Caching: Cache category hierarchies and brand lists; refresh periodically via CategoryQuery.
  • Rate limiting: Respect API limits; implement token bucket or merchant-level throttling if needed.
  • Indexing: Ensure database indices on SKU IDs, style IDs, and category IDs for fast lookups.

Section sources

Dependency Analysis ​

The integration exhibits low coupling and high cohesion:

  • Goods API module depends on the SDK client requester interface, enabling testability and transport flexibility.
  • The SDK client encapsulates HTTP, signing, and logging concerns, keeping higher layers focused on business logic.
  • Configuration is injected via protobuf-defined Bootstrap settings, ensuring consistent initialization.

Diagram sources

Section sources

Performance Considerations ​

  • Request batching: Upload up to 200 items per request for SKU uploads; split larger datasets accordingly.
  • Incremental sync: Use modified date filters to process only changed records.
  • Concurrency: Tune Kafka consumer workers and HTTP client timeouts for throughput.
  • Retries: Implement exponential backoff for transient errors; distinguish between retryable and fatal errors.
  • Monitoring: Track request latency, error rates, and rate-limit triggers; alert on recurring failures.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

Common issues and resolutions:

  • Authentication errors: Verify app key, app secret, and base URL; ensure IP whitelist compliance.
  • Signature failures: Confirm parameter sorting and MD5 signing algorithm; check charset and version parameters.
  • Rate limiting: Reduce request frequency or implement token bucket; monitor error code 200.
  • Empty or invalid data: Validate required fields and payload structure; ensure leaf-category constraint.
  • Time sync errors: Align system clocks with Jushuitan; retry after synchronization.

Diagnostic aids:

  • Inspect structured logs for request URL, path, latency, and response bodies.
  • Use IsAPIError to extract detailed error codes and messages.

Section sources

Conclusion ​

The Jushuitan goods catalog integration provides a robust, modular solution for synchronizing product master data, variants, categories, and mappings. By leveraging typed schemas, a secure SDK client, and layered architecture, the system supports scalable product operations, reliable error handling, and efficient performance. Adopting the recommended workflows, validations, and performance tuning practices ensures smooth operations across product creation, bulk updates, and category reorganization.

[No sources needed since this section summarizes without analyzing specific files]

Appendices ​

API Operation Reference ​

  • ItemSkuUpload: Upload SKU-level product data.
  • SkuQuery: Query SKUs with pagination and date filters.
  • MallItemQuery: Retrieve items with embedded SKUs.
  • SkuMapUpload/SkuMapQuery: Manage platform-to-ERP SKU mappings.
  • CombineSkuUpload/CombineSkuQuery: Manage composite bundles.
  • CategoryUpload/CategoryQuery: Manage category hierarchy.
  • HistoryCostPriceQuery: Retrieve historical cost prices.

Section sources