Inventory Management
Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
Introduction
This document describes the Jushuitan inventory management integration, focusing on how stock levels are synchronized, how allocations and virtual inventory are handled, and how warehouse-related queries are processed. It explains the mechanisms for real-time and batch inventory updates, multi-location inventory handling via warehouse and pack-level queries, and the integration with warehouse management systems. It also covers inventory reconciliation, stock correction workflows, and inventory aging reporting strategies, along with conflict resolution approaches for maintaining accurate stock levels across distributed systems.
Project Structure
The Jushuitan inventory integration is organized around a layered architecture:
- SDK helper layer: exposes typed APIs for inventory operations against Jushuitan.
- Business layer: use cases orchestrate inventory workflows.
- Data layer: repositories implement inventory fetching, caching, rate limiting, and persistence.
- Service layer: gRPC service handlers expose inventory operations to clients.
- Models: define persisted inventory query records and business objects.
Diagram sources
- [api.go]
- [impl.go]
- [types.go]
- [inventory.go]
- [inventory.go]
- [inventory.go]
- [inventory.go]
- [inventory_query.go]
- [inventory.go]
Section sources
- [api.go]
- [impl.go]
- [types.go]
- [inventory.go]
- [inventory.go]
- [inventory.go]
- [inventory.go]
- [inventory_query.go]
- [inventory.go]
Core Components
- SDK Inventory API: Defines typed requests and responses for inventory operations, including product-level queries, pack/position queries, count uploads, count queries, and virtual quantity updates.
- Inventory Usecase: Orchestrates asynchronous and synchronous inventory fetching flows.
- Inventory Repo: Implements async batch dispatch to Kafka, synchronous per-request fetching with rate limiting, cost price enrichment, and persistence via StarRocks StreamLoad.
- Inventory Model: Represents persisted inventory query records with fields for actual stock, reserved quantities, virtual inventory, and safety thresholds.
- Inventory Service: Exposes gRPC endpoints for async and sync inventory retrieval.
Key capabilities:
- Real-time stock updates via synchronous SKU queries with cost price enrichment.
- Batch inventory ingestion via Kafka-triggered pagination and persistence.
- Warehouse and pack-level visibility via dedicated pack query endpoint.
- Virtual inventory updates for WMS virtual quantities.
- Safety thresholds (min/max) and aging metadata for reporting and reconciliation.
Section sources
Architecture Overview
The integration follows a publish-subscribe pattern for batch inventory fetching and a request-response pattern for on-demand queries. It integrates with:
- Jushuitan WebAPI for inventory operations.
- bi-basic for shop authorization data.
- Redis for shop verification caching.
- Kafka for asynchronous inventory fetch tasks.
- StarRocks StreamLoad for fast persistence of inventory snapshots.
Diagram sources
Detailed Component Analysis
SDK Inventory API and Implementation
- API surface includes product-level inventory query, pack/position query, inventory count upload/query, and virtual quantity update.
- Implementation delegates to a generic Requester with explicit endpoint routing and JSON marshalling/unmarshalling.
Diagram sources
Section sources
Inventory Usecase
- Provides AsyncFetch to submit batch inventory retrieval tasks.
- Provides SyncFetch to fetch specific SKUs synchronously with rate limiting and cost price enrichment.
Diagram sources
Section sources
Inventory Repository
- AsyncFetchInventory:
- Fetches tenant/shop authorization from bi-basic.
- Verifies shop existence against Jushuitan via ShopsQuery and caches results in Redis.
- Computes total pages from the first page’s data count and publishes Kafka messages per page.
- Uses concurrency control and wait groups to manage parallelism.
- SyncFetchInventory:
- Enforces merchant-level rate limiting.
- Calls InventoryQuery with up to 100 SKUs per request.
- Enriches with latest cost prices and persists records via StreamLoad.
Diagram sources
Section sources
Data Model: InventoryQuery
- Stores a snapshot of inventory per SKU with:
- Actual stock, order locks, pick locks, virtual quantity, purchase and return quantities, defective and in-qty.
- Safety thresholds (min/max), cost price, and modification timestamps.
- Name, IID, and other attributes for reporting and reconciliation.
Diagram sources
Section sources
Service Layer: gRPC InventoryService
- Exposes AsyncFetch and SyncFetch endpoints.
- Translates business objects to protobuf responses.
Diagram sources
Section sources
Dependency Analysis
- The SDK inventory API depends on a generic Requester abstraction, enabling testability and decoupling from transport details.
- The use case depends on the repository interface, promoting separation of concerns.
- The repository implementation depends on:
- Jushuitan SDK for inventory operations.
- bi-basic gRPC for shop authorization.
- Redis for caching shop verification results.
- Kafka for asynchronous task distribution.
- StarRocks StreamLoad for bulk persistence.
- Merchant-level rate limiting ensures controlled API usage per tenant.
Diagram sources
Section sources
Performance Considerations
- Concurrency control: AsyncFetchInventory uses a semaphore to cap concurrent goroutines when publishing Kafka tasks.
- Pagination: Computes total pages from the first page’s data count to avoid redundant queries.
- Merchant-level rate limiting: Ensures each tenant respects a fixed QPS budget to prevent throttling.
- Caching: Redis cache reduces repeated verification of shop existence across tenants.
- Batch writes: StreamLoad is used for efficient bulk persistence of inventory snapshots.
Recommendations:
- Monitor Kafka lag and adjust maxConcurrency accordingly.
- Tune merchant rate limit window and capacity based on observed Jushuitan SLAs.
- Consider partitioning Kafka topics by tenant to improve throughput and isolation.
Section sources
Troubleshooting Guide
Common issues and resolutions:
- Empty or missing shop authorization:
- Verify bi-basic gRPC responses and ensure ListShopAuthDetail returns expected data.
- Check for empty tokens or platform shop IDs and skip invalid entries.
- Shop verification failures:
- Confirm ShopsQuery returns the expected SessionUID; otherwise, skip the shop and log warnings.
- Rate limit exceeded:
- Increase timeout allowance or reduce batch sizes; monitor merchant limiter logs.
- Kafka write failures:
- Inspect producer initialization and topic configuration; ensure brokers are reachable.
- Cost price enrichment failures:
- Fallback to zero cost price and log warnings; reconcile later via count uploads or manual adjustments.
- Persistence errors:
- Validate StreamLoad connectivity and schema alignment with InventoryQuery model.
Operational checks:
- Confirm Redis connectivity for caching.
- Validate Jushuitan access token validity and permissions.
- Review inventory query logs for error codes and messages.
Section sources
Conclusion
The Jushuitan inventory integration provides robust mechanisms for synchronizing stock levels, tracking allocations and virtual inventory, and querying warehouse and pack-level data. Through asynchronous batch ingestion, synchronous SKU queries with cost enrichment, and persistent storage, it supports real-time and near-real-time inventory visibility. The system incorporates caching, rate limiting, and Kafka-driven workflows to scale across tenants and locations. By leveraging the provided APIs and operational practices, teams can maintain accurate stock levels and support reliable order fulfillment across distributed environments.