Rhythm 2.0 Specifications

Appearance

CAP-COM-FUL-020Import Commerce history and reconcile source records

Markdown

CAP-COM-FUL-020

Import Commerce history and reconcile source records

Markdown
  • DocumentDraft
  • Product intentProposed
  • ImplementationObserved

Planning

Feature
FEAT-COM-FUL-05
Exercised by
FAS-COM-FUL-05-01, FAS-COM-FUL-05-02, FAS-COM-FUL-05-03, FAS-COM-FUL-05-04, FAS-COM-FUL-05-05
Key concepts
CON-COM-FUL-005, CON-COM-FUL-001
Actors
ACT-COM-009
Journeys
JNY-COM-FUL-006
Related
CAP-COM-FUL-017
Open questions
OQ-COM-FUL-003
Proved by
ATS-COM-FUL-020

Implementation

Executable suites
TST-COM-FUL-003, TST-COM-FUL-004, TST-COM-FUL-005, TST-COM-FUL-006, TST-COM-FUL-007, TST-COM-FUL-009, TST-COM-FUL-011, TST-COM-FUL-013, TST-COM-FUL-014, TST-COM-FUL-015

KindCapabilityProduct areaCommerceModuleFulfillment, Shipping and InventoryRevision1

Read atservices-commerce c8b66a98

Import Commerce history and reconcile source records ​

Purpose ​

Implementation staff load prepared migration records and verify their resulting identities.

How It Works ​

Staff submit prepared records to the collection's data-job workflow. Validation describes the impact before application is requested. Batches run with the submitter's current authority and retain their committed results. Missing references can wait for related records to arrive. Source-key readback lets staff reconcile the imported shape against the original records. Migrated orders and stock use their own opening behavior rather than ordinary live selling. The product should settle whether each import belongs with its record-owning module before design begins.

Relationships ​

  • Keep stock movements and transfers accountable supplies or consumes related delivery records.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Imported Commerce history supplies the migrating workspace's opening records.Source identities support reconciliation with original historical records.
Surfaces
apijob

Controls

45 controls apply, from the corpus control catalogue.

TC-IAM-006 TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-AZ-006 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-SEC-001 TC-SEC-002 TC-SEC-003 TC-SEC-004 TC-CRY-001 TC-CRY-004 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-LOG-001 TC-LOG-002 TC-LOG-003 TC-LOG-004 TC-LOG-005 TC-CHG-001 TC-CHG-002 TC-CHG-003 TC-CHG-004 TC-CHG-007 TC-AVL-004 TC-MON-001 TC-MON-002 TC-MON-004 TC-PI-001 TC-PI-002 TC-PI-003 TC-PI-004 TC-PI-005 TC-VEN-001 TC-VEN-002 TC-VEN-003 TC-PRV-001 TC-PRV-002

Permissions

KeyChecked atScope
commerce.inventory.bulkapitenant
commerce.inventory.updateapitenant

Business Rules

13 rules, 11 to be proved before approval. A rule's product intent is derived from its origin: 0 confirmed by a product decision, the rest inheriting this capability's proposed.

IdRuleKindEnforced atProvenance
01
Proposed
Migration serves twelve collections with eleven job operations each: stores, ordering profiles, orders, promotions, redemptions, categories, listings, merchandise option sets, merchandise, warehouses, locations and stock items.
policyapitest
services-commerce:modules/data-operations/tests/unit/operations/data-operations.spec.js#serves the twelve object types of the migration
02must prove
Proposed
Submission accepts up to 500 prepared records in validate or apply mode with insert, upsert or update semantics, rejects patch selections, and requires a source key or identity per record and a source system for keyed records.
proved by ATS-COM-FUL-020-01, TST-COM-FUL-003, TST-COM-FUL-013, TST-COM-FUL-014
validationapitest
services-commerce:modules/data-operations/tests/unit/api/data-jobs-schemas.spec.js#refuses a selection with a patch: no Commerce operation changes records in place by id
03must prove
Proposed
Data jobs require collection bulk authority and recheck record-write authority, rejecting read-only job callers and portal members.
proved by ATS-COM-FUL-020-01, TST-COM-FUL-003, TST-COM-FUL-013, TST-COM-FUL-014
permissionapi, servicetest
services-commerce:modules/data-operations/tests/e2e/data-jobs.e2e.spec.js#refuses a principal holding the read key alone on every data-job route of the collection, 403 permission_missing
04must prove
Proposed
Repeating an identical submission under its idempotency key returns the existing job marked reused.
proved by ATS-COM-FUL-020-02, TST-COM-FUL-003, TST-COM-FUL-004
invariantservicetest
services-commerce:modules/data-operations/tests/e2e/data-jobs.e2e.spec.js#answers a second submission of the same body under the same Idempotency-Key with the same job, reused
05must prove
Proposed
Validation records impact without writes, and apply rejects an absent or mismatched validation-impact digest.
proved by ATS-COM-FUL-020-02, TST-COM-FUL-003, TST-COM-FUL-004
validationservicetest
services-commerce:modules/data-operations/tests/integration/services/jobs/data-jobs.integration.spec.js#refuses an apply that echoes a digest other than the validation recorded, impact_digest_mismatch
06must prove
Proposed
Bulk-key holders can inspect all jobs in their collection and other callers only their own, while cross-collection job reads and mismatched collection submissions are rejected.
proved by ATS-COM-FUL-020-03, TST-COM-FUL-004
permissionservicetest
services-commerce:modules/data-operations/tests/integration/services/jobs/data-jobs.integration.spec.js#lists only the jobs a caller submitted themselves when they lack the collection’s bulk key
07must prove
Proposed
Initial import requires an implementation workspace in loading state, where job routes remain available and ordinary routes are closed.
proved by ATS-COM-FUL-020-04, TST-COM-FUL-003, TST-COM-FUL-004
policyapi, servicetest
services-commerce:modules/data-operations/tests/integration/services/jobs/data-jobs.integration.spec.js#is refused for a tenant that is live
08must prove
Proposed
Batch execution reloads the submitter's permissions, fails the job if authority was revoked, avoids duplicate application on redelivery and dead-letters unreadable messages.
proved by ATS-COM-FUL-020-05, TST-COM-FUL-011
permissionservicetest
services-commerce:modules/data-operations/tests/integration/services/queue/data-job-worker.integration.spec.js#acknowledges the message as access_revoked and fails the job whole with that code, nothing left on the queue
09must prove
Proposed
Missing references defer records with the dependency field identified, typed failures retain their code, duplicate errors disclose constraint names rather than colliding values, and dropped connections are transient.
proved by ATS-COM-FUL-020-06, TST-COM-FUL-005, TST-COM-FUL-015
policyservicetest
services-commerce:modules/data-operations/tests/unit/operations/error-classification.spec.js#blocks an item whose reference nobody has loaded, on the engine’s dependency_missing, at the field that names it
10must prove
Proposed
Readback accepts up to 100 source keys, returns imported shapes and missing-key lists and excludes records from other workspaces.
proved by ATS-COM-FUL-020-07, TST-COM-FUL-003, TST-COM-FUL-006
permissionservicetest
services-commerce:modules/data-operations/tests/e2e/data-jobs.e2e.spec.js#answers the key missing before the apply, and the store as its load carried it once the job is applied and run
11must prove
Proposed
Migrated orders preserve original numbers, arrive accepted, billed and marked migrated, create completed or blocked item-line obligations and defer unresolved invoice linking for a later same-key relink.
origin: D-C-04 (build decision, not a product ruling): services-commerce:docs/migrations/data-operations/README.md
proved by ATS-COM-FUL-002-15, ATS-COM-FUL-004-13, ATS-COM-FUL-020-08, ATS-COM-FUL-020-11, TST-COM-FUL-009
policyservicetest
services-commerce:modules/data-operations/tests/integration/services/operations/order-import.integration.spec.js#creates one obligation per item line in its final state: completed and open for the fulfilled line, blocked for the other
12must prove
Proposed
Migrated stock opening uses count-correction and damage ledger entries instead of direct balance writes, rejecting repeat keys and inactive destinations.
proved by ATS-COM-FUL-016-08, ATS-COM-FUL-017-12, ATS-COM-FUL-020-09, ATS-COM-FUL-020-10, TST-COM-FUL-007
invariantservicetest
services-commerce:modules/data-operations/tests/integration/services/operations/inventory-import.integration.spec.js#opens the mug’s item through the ledger: a count correction of twelve and a damage of two, so the trigger holds ten available
13
Proposed
Pause, resume, cancellation and retry take effect between batches, and cancellation preserves and reports already committed records.
lifecycleapi, serviceobserved
services-commerce:modules/data-operations/aws/api/data-operations.routes.ts:dataJobRoutesOf

Scenarios

IdGivenWhenThenProvenance
01A prepared store import has passed validation.Apply its recorded impact digest and execute the queued batch.The created store is available through its original source key in imported shape.test
services-commerce:modules/data-operations/tests/e2e/data-jobs.e2e.spec.js#answers the key missing before the apply, and the store as its load carried it once the job is applied and run

Edge Cases

IdGivenWhenThenProvenance
02A listing references a product not yet imported.Execute its import batch.The item waits on the identified missing dependency without being written.test
services-commerce:modules/data-operations/tests/integration/services/operations/catalog-import.integration.spec.js#blocks a listing whose product nothing has loaded as dependency_missing, naming the product source key, and writes nothing

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software