--- id: CAP-COM-CAT-019 title: Configure recommendation rules and placements feature: FEAT-COM-CAT-05 product_area: commerce module: catalog revision: 1 status: draft product_intent: proposed implementation_evidence: partially-observed source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b purpose: >- Administrators prepare supported selling suggestions and control where they may appear. outcomes: - Suggestions appear exclusively where a placement can show them. - >- A rule that has been displayed does not permit edit what it offers underneath its results. concepts: - CON-COM-CAT-006 actors: - ACT-COM-001 - ACT-COM-004 - ACT-COM-007 surfaces: - api permissions: - key: commerce.recommendation-rules.read where_checked: api scope: tenant - key: commerce.recommendation-rules.create where_checked: api scope: tenant - key: commerce.recommendation-rules.update where_checked: api scope: tenant - key: commerce.recommendation-rules.activate where_checked: api scope: tenant - key: commerce.recommendation-rules.delete where_checked: api scope: tenant - key: commerce.recommendation-rules.bulk where_checked: api scope: tenant - key: commerce.recommendation-placements.read where_checked: api scope: tenant - key: commerce.recommendation-journeys.read where_checked: api scope: tenant - key: commerce.recommendation-journeys.create where_checked: api scope: tenant - key: commerce.recommendation-journeys.update where_checked: api scope: tenant - key: commerce.recommendation-journeys.delete where_checked: api scope: tenant - key: commerce.recommendation-journeys.bulk where_checked: api scope: tenant rules: - id: BR-CAP-COM-CAT-019-01 proved_by: [ATS-COM-CAT-019-01, TST-COM-CAT-136, TST-COM-CAT-151] statement: >- Recommendation rules select related products, add-ons, upgrades or membership savings and accept only their kind’s parameters, with add-ons requiring products. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/recommendations/tests/unit/rule-rules.spec.js#refuses an add_on rule with no products, parameters_invalid, naming the path origin: none - id: BR-CAP-COM-CAT-019-02 proved_by: [ATS-COM-CAT-010-11, ATS-COM-CAT-019-02, ATS-COM-CAT-019-09, TST-COM-CAT-136, TST-COM-CAT-138] statement: >- Placement bindings must support the rule kind and constrain its offer cap to one through ten without exceeding the placement’s cap. kind: validation enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/recommendations/tests/e2e/recommendation-rules.e2e.spec.js#refuses a cap above the placement’s, 400 max_offers_exceeds_placement origin: none - id: BR-CAP-COM-CAT-019-03 proved_by: [] statement: >- Unless overridden, a rule adds its candidate to checkout or replaces the existing item for an upgrade. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-commerce:modules/recommendations/tests/unit/rule-rules.spec.js#is the kind’s default: add to the checkout, or replace the item for an upgrade origin: none - id: BR-CAP-COM-CAT-019-04 proved_by: [ATS-COM-CAT-019-03, TST-COM-CAT-136, TST-COM-CAT-151] statement: >- Application-flow actions remain unavailable, while membership-savings configuration is accepted for later evaluation. kind: policy enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/recommendations/tests/e2e/recommendation-rules.e2e.spec.js#refuses a rule whose action is start_journey, 409 action_unavailable: the journeys are R3’s origin: none - id: BR-CAP-COM-CAT-019-05 proved_by: [ATS-COM-CAT-019-04, ATS-COM-CAT-019-08, ATS-COM-CAT-019-10, TST-COM-CAT-136, TST-COM-CAT-148] statement: >- Recommendation lifecycle uses draft, active, paused, ended and archived states; activation requires placement binding and a placement accepts at most twenty-five active rules. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-CAT-019-06 proved_by: [ATS-COM-CAT-019-05, ATS-COM-CAT-019-08, ATS-COM-CAT-019-10, TST-COM-CAT-141, TST-COM-CAT-148] statement: >- The first presentation locks rule substance while permitting message changes. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- 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 origin: none - id: BR-CAP-COM-CAT-019-07 proved_by: [ATS-COM-CAT-019-06, TST-COM-CAT-148, TST-COM-CAT-150] statement: >- Recommendation names are workspace-unique and deterministic subject assignment can withhold offers from up to half the audience. kind: validation enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/recommendations/tests/unit/holdout.spec.js#answers the same bucket for the same subject and rule every time origin: none - id: BR-CAP-COM-CAT-019-08 proved_by: [] statement: >- Five store placements cover catalog, product, cart, checkout review and order confirmation, while applications register placements and flows under their own names. kind: policy enforced_at: - service must_prove: false provenance: test source: >- services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-placements.integration.spec.js#inserts the five store placements the first time, under commerce, declared now origin: none - id: BR-CAP-COM-CAT-019-09 proved_by: [] statement: >- Application-flow registrations are unique per kind and refuse updates or deletion while locked. kind: lifecycle enforced_at: - service must_prove: false provenance: test source: >- services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-journeys.integration.spec.js#refuses to update or delete a locked journey, record_locked origin: none - id: BR-CAP-COM-CAT-019-10 proved_by: [] statement: >- Recommendation performance aggregates shown, accepted and converted offers and their value by placement and day. kind: calculation enforced_at: - service must_prove: false provenance: test source: >- services-commerce:modules/recommendations/tests/integration/services/persistence/recommendation-performances.queries.integration.spec.js#answers one row per placement and day, counted from the rows: the cart on the seventh and the review on the eighth origin: none - id: BR-CAP-COM-CAT-019-11 proved_by: [ATS-COM-CAT-019-07, TST-COM-CAT-137] statement: >- Rules and placements require their read permissions; rule and flow writes require administrator permissions and launch or resume requires separate activation authority. kind: permission enforced_at: - api must_prove: true provenance: test source: >- services-commerce:modules/recommendations/tests/e2e/recommendations-security.e2e.spec.js#lists the rules and the placements, and is refused a create and an activation 403 permission_missing origin: none scenarios: - id: SC-CAP-COM-CAT-019-01 given: A related-products rule is bound to the cart when: Exercise the supported lifecycle sequence then: >- It passes through active, paused, active, ended and archived, refusing unsupported transitions provenance: test source: >- services-commerce:modules/recommendations/tests/e2e/recommendation-rules.e2e.spec.js#moves through active, paused, active, ended, archived depends_on: - CAP-COM-CAT-006 related: - CAP-COM-CAT-020 journeys: - JNY-COM-CAT-006 open_questions: - OQ-COM-CAT-005 evidence: - >- Pinned service inputs: modules/recommendations/aws/api/recommendation-rules.routes.ts, recommendation-registry.routes.ts, recommendations.schemas.ts; services/rules/**, services/placements/**, services/manifest/**, services/persistence/**; db/recommendation-*.table.ts; tests (rules e2e, security, persistence, table, holdout, messages, manifest) - 'Pinned console inputs: no recommendation screen exists at the pinned commit' controls: [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-CRY-001, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-004, TC-LOG-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-007, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002] exercised_by: [FAS-COM-CAT-05-01, FAS-COM-CAT-05-02, FAS-COM-CAT-05-03, FAS-COM-CAT-05-04, FAS-COM-CAT-05-05] suites: [TST-COM-CAT-136, TST-COM-CAT-137, TST-COM-CAT-138, TST-COM-CAT-141, TST-COM-CAT-148, TST-COM-CAT-150, TST-COM-CAT-151] --- # Configure recommendation rules and placements ## Purpose Administrators prepare supported selling suggestions and control where they may appear. ## How It Works API clients create rules with kind-specific parameters and bind them to registered placements. The application owning a placement determines which kinds and caps it supports. Administrators activate prepared rules after binding and capacity checks. A presentation later locks substantive settings while leaving the message editable. Membership savings and application-flow actions remain delivery edges rather than fully evaluated buyer behaviour. Performance supports review of shown, accepted and converted offers. The product should approve the feature scope before designing console administration. ## Relationships The prepare and publish product presentations capability supplies related configuration or assessment used in this work. The present offers and process buyer responses capability supplies related configuration or assessment used in this work.