Deep Dive Tutorial on the 'Query Wangdian Goods' Strategy: End-to-End Breakdown from API Pull to Data Landing

What This Strategy Solves

In one of our real projects, a retail enterprise used Wangdian Enterprise for warehouse and e-commerce management, and Kingdee Cosmic for finance and supply chain general ledger. Both sides maintained their own copy of 'good/inventory item' master data, and after three months the two sides' numbers no longer reconciled, bringing the monthly closing to a halt.

The purpose of the 'Query Wangdian Goods' strategy is to pull goods master data from the Wangdian side incrementally within a time window into the middle layer, serving as the 'single source of truth' for the subsequent writes into Kingdee Cosmic. It only reads, never writes, a typical QUERY_ONLY document-class strategy, essentially laying the foundation for the entire master data sync chain.

Data Flow Direction and Field Mapping

The data flow is 'Wangdian Enterprise → Qeasy Integration Platform (Qingyiyun)'. The source is the business system; the target platform only does staging and transit, while the real write action is performed by downstream strategies that depend on this one.

Key field mapping for understanding pull semantics:

Note that the source-side end_time is annotated in the materials with a description belonging to another field (e.g., 'store unique code'). When configuring, follow the official Wangdian documentation rather than the metadata description.

How to Configure in Qeasy (Qingyiyun)

To land this strategy in the Qeasy Data Integration Platform, configuration essentials fall into four parts:

1. Data source registration: Pick 'Wangdian Enterprise' as source platform, choose goods_query as API, method POST, effect QUERY. Confirm tenant authorization and store codes are available, or the pull will return empty.
2. Request parameter orchestration: Bind start_time / end_time to the platform's built-in time variables {{LAST_SYNC_TIME|datetime}} and {{CURRENT_TIME|datetime}}. Use the universal paginator for pagination: page_size from {{PAGINATION_PAGE_SIZE}}, page_no from {{PAGINATION_START_PAGE}}.
3. Response parsing: Turn on autoFillResponse so the platform builds the model from sample responses automatically, saving manual table creation. Use goods_no as the primary key for downstream deduplication.
4. Target handling: The target platform is 'Qeasy Integration Platform', effect EXECUTE, API 'Empty Write'. Its job is to capture and stage the data for downstream strategies to consume. Though it looks 'empty', it plays the role of breakpoint resume and idempotent buffering. A common pattern among Qeasy customers is to treat them as staging, so the upstream is not hammered with retries when downstream writes fail.

Two easily overlooked configuration items: set idCheck to false (checking by goods_no existence is enough, do not let the platform additionally validate auto-increment IDs); set buildModel to false (avoid generating redundant field models in the empty-write target).

Implementation Steps

This strategy's schedule, as provided in the materials, is 3 2 * * * (daily at 02:03), while the target-end is 1 1 1 1 1 (effectively manual trigger). Therefore implementation has three phases:

• First-time full sync: Manually trigger on launch day without an upper bound for start_time, letting Wangdian dump all goods into the middle layer. Schedule this during the off-peak early hours and reserve a window 2~3× the daily data volume.
• Switch to incremental anchor: After full sync completes, anchor LAST_SYNC_TIME to the full-sync end time; subsequent schedules use windowed incremental start_time = LAST_SYNC_TIME, end_time = CURRENT_TIME. A common pattern among Qeasy customers is dual-track incremental and full: incremental daily, full sync monthly at month start for reconciliation.
• Scheduling frequency and dependency orchestration: Triggered daily at 02:03, this single strategy has no dependencies (depends_on is empty). In the customer's overall plan, this strategy is typically sequence A, depended on by sequence B ('Query Kingdee Material_Guangzhou') and subsequent write strategies, so its stability decides the stability of the entire master data sync chain.

Pitfall Retrospective

1. Field description confusion: The source end_time got a description belonging to 'store unique code' mixed into its metadata in the original materials. Copying it verbatim misleads. The safe approach is follow official platform API documentation; metadata descriptions are only reference.
2. idCheck default value trap: If idCheck is enabled, the platform tries to validate auto-increment IDs, but the goods primary key is goods_no, and validation will fail and throw errors. Must explicitly set it to false.
3. Empty-write target ignored: Many people see 'Empty Write' as a placeholder strategy and skip the staging meaning. In practice, a common Qeasy customer pattern is to centralize code mapping management at this layer—when pushing materials to Kingdee Cosmic later, do the goods_no → Kingdee material code mapping here, avoiding duplicated maintenance in every downstream strategy.
4. No upper bound on first full sync: If full sync is triggered without end_time, some versions pull the 'currently open time window' as well, overlapping with later incremental pulls and causing brief duplicates. Safe approach: also explicitly provide an end_time during full sync, then switch to incremental anchor after completion.
5. Pagination not fully configured: Source page_size range 1~100, default 40 if not provided. If the middle-layer table is wide, batches beyond 100 will lose data. Safe approach: fix at 100, and observe pagination loop count in monitoring.

Applicable and Non-applicable Scenarios

Applicable: single warehouse / single store or stable store count, controllable goods change frequency (daily new/modify below tens of thousands), small-to-medium retail and distribution enterprises that need a unified goods master source for downstream finance/supply chain.

Non-applicable: multi-warehouse with frequent cross-warehouse transfers, strong real-time inventory requirements (intra-day multiple syncs), and ultra-simplified 'source-to-target direct push' architectures—the latter often struggles with breakpoint resume and idempotency once data volume exceeds millions.