Order Synchronization
Table of Contents
- Introduction
- Project Structure
- Core Components
- Architecture Overview
- Detailed Component Analysis
- Dependency Analysis
- Performance Considerations
- Troubleshooting Guide
- Conclusion
- Appendices
Introduction
This document describes the Jushuitan order synchronization system within the bi-api-jushuitan service. It explains the complete order lifecycle including upload, query, cancellation, splitting, modification, and status tracking. It documents the OrderUpload, OrderQuery, OrderCancel, OrderSplit, and OrderSentUpload operations with detailed request/response schemas, pagination behavior via HasNext, and batch processing patterns. It also covers status transitions, exception handling, duplicate order conflict resolution, and strategies to maintain data consistency across systems.
Project Structure
The order synchronization capability is encapsulated in the common/sdkhelper/order package and integrated into the bi-api-jushuitan service via the data layer and consumers. The service initializes clients, registers Kafka consumers, and orchestrates order operations against the Jushuitan open platform.
Diagram sources
Section sources
Core Components
- Order API interface: Defines order operations including upload, query, cancel, split, modify WMS, mark question, remark, node set, label upload, sent upload, and action query.
- Order types: Strongly typed request/response models for all order operations.
- SDK client: Encapsulates HTTP signing, request/response handling, and error mapping.
- Data client: Creates the Jushuitan SDK client with configured credentials and timeouts.
- Consumer handlers: Registers Kafka consumers and applies rate limiting for order-related operations.
Key responsibilities:
- Order API: Exposes operation methods with clear request/response shapes.
- SDK Client: Handles authentication, signing, retries, logging, and error propagation.
- Data Layer: Provides Jushuitan client initialization and integrates with runtime configuration.
- Consumers: Orchestrates order event processing with concurrency and merchant-level rate limits.
Section sources
Architecture Overview
The order synchronization system follows a message-driven architecture:
- The service starts, loads configuration, initializes clients, and registers consumers.
- Kafka consumers trigger order operations against the Jushuitan open platform via the SDK client.
- The SDK signs requests, sends HTTP form-encoded payloads, and unmarshals responses.
- Errors are mapped to structured APIError types for downstream handling.
Diagram sources
Detailed Component Analysis
Order Upload (OrderUpload)
Purpose: Upload self-service mall orders to ERP.
- Operation: Calls the SDK requester with endpoint "/open/jushuitan/orders/upload".
- Request shape: OrderUploadRequest with Orders array (up to 50 items).
- Required fields per item: ShopID, SoID, OrderDate, Receiver*, PayAmount, Items[] (SkuID, OuterOiID, Qty, Price, Amount).
- Response: No payload returned; success indicated by absence of error.
Diagram sources
Section sources
Order Query (OrderQuery)
Purpose: Query non-Taobao orders from ERP with pagination.
- Operation: Calls "/open/orders/single/query" with optional filters.
- Pagination: Uses PageIndex (1-based), PageSize (default 30, max 50), HasNext flag indicates more pages.
- Filters: StartTime, EndTime, SoIDs[], Status, ShopID, DateType (1=order time, 2=modify time).
- Response: PageResult[Order] containing Datas[], PageIndex, PageSize, HasNext.
Diagram sources
Section sources
Order Cancel (OrderCancel)
Purpose: Cancel an unfilled order.
- Endpoint: "/open/jushuitan/orderbyoid/cancel"
- Request: SoID, ShopID.
- Response: No payload; success indicated by absence of error.
Section sources
Order Split (OrderSplit)
Purpose: Split an ERP order (one-to-many split).
- Endpoint: "/open/jushuitan/drporder/split"
- Request: OID, Items[] (child order IDs to split).
- Response: No payload.
Section sources
Order Modify WMS (OrderModifyWms)
Purpose: Change the warehouse for specified orders.
- Endpoint: "/open/orders/modifywms/upload"
- Request: Items[] with OID and WmsID.
- Response: No payload.
Section sources
Order To Question (OrderToQuestion)
Purpose: Mark an unfilled order as question/exception.
- Endpoint: "/open/webapi/orderapi/questionorder/questions"
- Request: OID, Reason.
- Response: No payload.
Section sources
Order Remark Upload (OrderRemarkUpload)
Purpose: Update seller remark on an order.
- Endpoint: "/open/jushuitan/order/remark/upload"
- Request: ShopID, SoID, SellerMemo.
- Response: No payload.
Section sources
Order Node Set (OrderNodeSet)
Purpose: Set offline node metadata on an order.
- Endpoint: "/open/order/node/soid/set"
- Request: SoID, Node.
- Response: No payload.
Section sources
Order Label Upload (OrderLabelUpload)
Purpose: Add or remove labels on an order.
- Endpoint: "/open/jushuitan/order/label/upload"
- Request: OID, Labels[], Action ("add" or "remove").
- Response: No payload.
Section sources
Order Sent Upload (OrderSentUpload)
Purpose: Mark orders as shipped with logistics info.
- Endpoint: "/open/order/sent/upload"
- Request: Items[] with OID, LcID, LogisticsNo.
- Response: No payload.
Section sources
Order Action Query (OrderActionQuery)
Purpose: Retrieve order action logs.
- Endpoint: "/open/order/action/query"
- Request: OID.
- Response: Array of OrderAction with ActionID, ActionType, ActionTime, Operator, Remark.
Section sources
Order Data Models
Core models used across operations:
Diagram sources
Section sources
Batch Processing and Pagination
- Pagination is controlled by PageIndex (1-based) and PageSize (default 30, max 50).
- HasNext indicates whether another page exists; callers should loop until HasNext is false.
- Typical batch pattern:
- Start with PageIndex=1, PageSize=30.
- On each response, process Datas[].
- If HasNext is true, increment PageIndex and fetch next page.
- Stop when HasNext becomes false.
Section sources
Order Status Transition Patterns
- Typical lifecycle: WaitConfirm → Confirmed → Packed/Shipped → Completed/Cancelled.
- Transitions are initiated by operations:
- OrderUpload: creates/updates order records.
- OrderCancel: moves to Cancelled if unfilled.
- OrderSentUpload: marks Shipped.
- OrderToQuestion: marks Question.
- OrderModifyWms: adjusts fulfillment source.
- Action logs can be queried via OrderActionQuery to audit state changes.
Note: The exact status enumeration and allowed transitions depend on the Jushuitan platform; consult platform documentation for authoritative values.
Section sources
Exception Handling and Error Recovery
- Response envelope: code, msg, data.
- Success: code == 0.
- Failure: APIError with Code and Msg; IsAPIError can be used to detect.
- Common error categories (non-exhaustive):
- Authentication/authorization errors (invalid token, IP, permissions).
- Parameter validation errors.
- Rate limit/throttling.
- Platform internal errors.
- Retry strategy:
- Use exponential backoff with jitter for transient failures.
- Respect HasNext for pagination; do not skip pages.
- Dead letter queue (DLQ) topic is supported for failed messages.
Section sources
Order Conflict Resolution and Data Consistency
- Duplicate orders:
- Prefer upsert semantics on SoID+ShopID composite key.
- Use OrderQuery with SoIDs[] to deduplicate before upload.
- Apply optimistic concurrency: compare timestamps or checksums.
- Idempotency:
- For OrderUpload, de-duplicate by SoID before sending.
- For OrderSentUpload, guard by checking current status and last update time.
- Consistency:
- Use transactional writes where possible (e.g., batch writes to StarRocks via StreamLoad).
- Maintain audit logs via OrderActionQuery to reconcile discrepancies.
- Enforce merchant-level rate limits to avoid throttling and partial failures.
Section sources
Dependency Analysis
The order subsystem depends on the SDK client and configuration, and is wired into the application via dependency injection.
Diagram sources
Section sources
Performance Considerations
- Concurrency and rate limiting:
- Merchant-level rate limiter (tokens per minute) and concurrency limiter (per-merchant concurrent requests) are configured in consumer handlers.
- These prevent throttling and improve throughput stability.
- Request batching:
- OrderUpload supports up to 50 orders per request; batch uploads to reduce overhead.
- Pagination:
- Use HasNext to iterate pages efficiently; avoid fetching unnecessary pages.
- Logging and observability:
- Structured logs capture request/response details and latency for diagnostics.
Section sources
Troubleshooting Guide
Common issues and resolutions:
- Authentication failures:
- Verify AppKey/AppSecret/BaseURL and AccessToken.
- Refresh tokens if ErrCodeAuthError occurs.
- Signature/validation errors:
- Ensure parameters are sorted and signed correctly; check charset/version/timestamp.
- Throttling:
- Respect merchant rate limits and concurrency caps; implement backoff.
- Empty or malformed data:
- Validate required fields in requests; confirm JSON encoding.
- Network errors:
- Inspect request URL and body; confirm connectivity to BaseURL.
Operational tips:
- Use IsAPIError to detect platform errors and handle accordingly.
- Enable debug mode to log raw requests/responses.
- Monitor HasNext during pagination to avoid missing data.
Section sources
Conclusion
The Jushuitan order synchronization system provides a robust, rate-limited, and observable pipeline for managing orders across platforms. By leveraging strongly typed models, pagination with HasNext, and structured error handling, it supports reliable batch processing and real-time status updates. Adhering to idempotent patterns, merchant-level controls, and audit logging ensures data consistency and operational resilience.
Appendices
Example Workflows
Order Creation Workflow
- Build OrderUploadRequest with Orders[] (up to 50).
- Send OrderUpload; on success, optionally query OrderQuery by SoIDs[] to confirm creation.
- Track status via OrderActionQuery for auditability.
Real-time Status Updates
- Poll OrderQuery with date filters and HasNext loops.
- On status change, trigger downstream actions (e.g., shipping, notifications).
Error Recovery Strategies
- For APIError, inspect Code and apply targeted retries or corrective actions.
- For rate limit errors, back off and retry later; consider reducing batch sizes or concurrency.
Section sources