Rhythm 2.0 Specifications

Appearance

DOM-COM-CAT-006Recommendation

Markdown

DOM-COM-CAT-006

Recommendation

Markdown
  • DocumentDraft
  • ImplementationPartially observed

Planning

Specified by
CON-COM-CAT-006

Design

Owned by
SVC-COM-CAT-recommendations

KindDomain objectProduct areaCommerceModuleCatalog and Selling ConfigurationRevision1

Read atservices-commerce c8b66a98

Recommendation ​

What It Models ​

A recommendation rule determines a suggestion at an application placement. Evaluation produces offers for a particular subject, including deliberate holdouts. Supported suggestions include related products, add-ons and upgrades, with acceptance or dismissal recorded separately from presentation.

Identity and Attributes ​

Rules use readable keys and distinct names. Qualified keys identify placements and registered application flows. Offer identifiers connect accepted items to checkout and order lines. Displayed amounts expire with the quote and are recalculated by ordinary checkout processing.

Relationships ​

Related candidates come from listings, prices come from quotes and promotion actions use codes. Store restrictions narrow a rule’s scope. Commerce seeds five storefront placements.

Invariants ​

Validation constrains kinds, actions and placement limits. Presentation fixes protected rule fields, and holdout calculation is stable. Completed responses repeat safely in sequential requests, but the history index alone does not prove once-only concurrent checkout actions. Anonymous estimates cannot be accepted.

How It Is Stored and Shared ​

Recommendations owns rules, placement bindings, flow declarations, presentations and interactions. Acceptance calls checkout workflows to add or replace items. Promotion application and acceptance history use separate commits. No custom-field capability or external change event is declared.

Open Design Questions ​

Product scope is still open and no staff administration screen exists. Membership-savings evaluation, application-flow execution and presentation retention remain deferred. Concurrent first acceptance needs proof or serialization.

Relationships

ToCardinalityOwnershipCrosses a serviceOn archive or delete
DOM-COM-CAT-003one listing to up to eight related candidatesListing links supply related-product candidates; other rule kinds retain their own candidate references.no
DOM-COM-CAT-004one quote per evaluationThe subject’s quote supplies candidate amounts without fixing the price ultimately charged.no
DOM-COM-CAT-005many rules to one codeA promotion action passes its code through the checkout promotion path.no
DOM-COM-CAT-002many rules to many storesStore references narrow rule scope; the seeded storefront placements are declared by Commerce.no

Invariants

InvariantProtectsEnforced atProvenance
INV-DOM-COM-CAT-006-01
Rules accept only parameters supported by their kind; add-on rules require candidate products.
servicetest
services-commerce:modules/recommendations/tests/unit/rule-rules.spec.js#refuses an add_on rule with no products, parameters_invalid, naming the path
INV-DOM-COM-CAT-006-02
Bindings require a compatible placement and action, with an offer limit from one through ten that does not exceed the placement limit.
service, databasetest
services-commerce:modules/recommendations/tests/e2e/recommendation-rules.e2e.spec.js#refuses a cap above the placement’s, 400 max_offers_exceeds_placement
INV-DOM-COM-CAT-006-03
Activation rejects a placement already holding twenty-five active rules.
servicetest
services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-rules.integration.spec.js#refuses the twenty-sixth active rule of one placement, too_many_active_rules, naming the placement
INV-DOM-COM-CAT-006-04
A first presentation fixes the protected rule fields, while message editing remains available.
servicetest
services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-rules.integration.spec.js#refuses the substance of a locked rule, rule_locked, naming the columns, while the message stays editable
INV-DOM-COM-CAT-006-05
A subject and rule produce the same holdout assignment on repeated calculation.
servicetest
services-commerce:modules/recommendations/tests/unit/holdout.spec.js#answers the same bucket for the same subject and rule every time
INV-DOM-COM-CAT-006-06
After an acceptance has completed, a later request returns its recorded outcome; concurrent first-action execution remains unproved.
servicetest
services-commerce:modules/recommendations/tests/e2e/offers.e2e.spec.js#answers the first acceptance to a second, repeated, adding nothing
INV-DOM-COM-CAT-006-07
Offers recorded for anonymous sessions cannot be accepted.
servicetest
services-commerce:modules/recommendations/tests/e2e/offers.e2e.spec.js#cannot have the estimate accepted, even by a signed-in member: 409 sign_in_required
INV-DOM-COM-CAT-006-08
Live evaluation commits presentations and first-presentation locks together; preview commits neither.
serviceobserved
services-commerce:modules/recommendations/services/persistence/offer-presentations.ts:insertOfferPresentations

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