Organize product shelves

Purpose

Administrators group products into browsable categories used by store assortments.

How It Works

Staff create categories and arrange their products in a deliberate order. A category carries its own presentation and sort choices. Products can also be assigned to shelves from their listing work. Saving membership replaces the selected collection and detects repeated products. Store references can prevent removal of a shelf customers still offer. Removing an unused shelf clears its memberships while retaining the products themselves. Image preparation and stale-version failures leave staff with an explicit reason to correct their request.

Relationships

The configure a store’s offered assortment capability supplies related configuration or assessment used in this work.

The prepare and publish product presentations capability supplies related configuration or assessment used in this work.

The present the store’s available products capability supplies related configuration or assessment used in this work.

Show evidence (sources, provenance, origins, pinned commits)

The Formal Contract

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

Outcomes: Shelves organize items around shopper browsing needs.A shelf a store depends on is does not deleted from under it.
Surfaces: consoleapi
Intent sources: services-commerce:docs/milestones/plans/COMM-M1-plan.md#2. Scope (item 3)services-commerce:docs/milestones/COMM-M1-set-up-what-you-sell.md#D-REC-2 (to confirm)

Controls

22 controls apply, from the corpus control catalogue.

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-PI-001 TC-PI-003 TC-PI-005 TC-PRV-001 TC-PRV-002

Permissions

Key	Checked at	Scope
`commerce.product-categories.read`	api	tenant
`commerce.product-categories.create`	api	tenant
`commerce.product-categories.update`	api	tenant
`commerce.product-categories.delete`	api	tenant
`commerce.product-categories.bulk`	api	tenant

Business Rules

10 rules, 8 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.

Id	Rule	Kind	Enforced at	Provenance
`01` Proposed	A category retains its supplied or name-derived identity, and another category cannot take that identity.	validation	service	test services-commerce:modules/catalog/tests/integration/services/persistence/product-categories.integration.spec.js#refuses a second category under the same id (400)
`02`must prove Proposed	Categories form a flat collection, with parent relationships reserved and refused. proved by `ATS-COM-CAT-005-01`, `TST-COM-CAT-014`, `TST-COM-CAT-017`	validation	api, database	test services-commerce:modules/catalog/tests/e2e/product-categories.e2e.spec.js#answers 400 to a parent_id: the hierarchy is reserved
`03`must prove Proposed	A category accepts only a supported catalog sort as its default. proved by `ATS-COM-CAT-005-01`, `TST-COM-CAT-014`, `TST-COM-CAT-017`	validation	api, database	test services-commerce:modules/catalog/tests/e2e/product-categories.e2e.spec.js#answers 400 to a default sort outside the catalog sorts, naming the property
`04`must prove Proposed	Category membership replacement preserves the supplied order without duplicate products; assigning a product’s categories appends new memberships and removes omitted ones. proved by `ATS-COM-CAT-005-02`, `ATS-COM-CAT-005-09`, `ATS-COM-CAT-005-10`, `ATS-COM-CAT-006-12`, `ATS-COM-CAT-008-07`, `TST-COM-CAT-019`	policy	service	test services-commerce:modules/catalog/tests/integration/services/persistence/product-categories.integration.spec.js#refuses a list naming one product twice (400) and an unknown category (404)
`05`must prove Proposed	A store’s home or assortment reference prevents category deletion, with the refusal reporting the number of dependent stores and up to five names. proved by `ATS-COM-CAT-003-11`, `ATS-COM-CAT-005-03`, `ATS-COM-CAT-005-08`, `TST-COM-CAT-014`, `TST-COM-CAT-019`	lifecycle	service	test services-commerce:modules/catalog/tests/integration/services/persistence/product-categories.integration.spec.js#is refused while stores name it in their assortment, naming five of them and the count
`06` Proposed	Category deletion removes its memberships and detaches its image while retaining the products.	lifecycle	service, database	test services-commerce:modules/catalog/tests/integration/services/persistence/product-categories.integration.spec.js#deletes the category with its memberships and detaches its picture; a second delete is 404
`07`must prove Proposed	The shared asset pipeline must read a category image as a file and retain it in the category’s permanent storage location. origin: COMM-M1 D11 (docs/milestones/COMM-M1-set-up-what-you-sell.md) proved by `ATS-COM-CAT-003-12`, `ATS-COM-CAT-003-17`, `ATS-COM-CAT-005-04`, `ATS-COM-CAT-005-11`, `ATS-COM-CAT-005-12`, `ATS-COM-CAT-005-13`, `ATS-COM-CAT-006-19`, `TST-COM-CAT-014`, `TST-COM-CAT-019`	validation	service	test services-commerce:modules/catalog/tests/e2e/product-categories.e2e.spec.js#answers 400 to a picture the pipeline cannot read as a file, creating nothing
`08`must prove Proposed	A complete category replacement uses the read version and refuses an intervening version change. proved by `ATS-COM-CAT-005-05`, `ATS-COM-CAT-005-12`, `TST-COM-CAT-014`	invariant	api, service	test services-commerce:modules/catalog/tests/e2e/product-categories.e2e.spec.js#replaces at the version read and refuses the stale version 409
`09`must prove Proposed	Category reads require read permission and all category writes require the matching administrator permissions. proved by `ATS-COM-CAT-005-06`, `TST-COM-CAT-011`	permission	api, console	test services-commerce:modules/catalog/tests/e2e/catalog-security.e2e.spec.js#refuses a read-only principal every write, 403 permission_missing
`10`must prove Proposed	A full lock prevents replacing a category, and either full or deletion-only locking prevents removing it. proved by `ATS-COM-CAT-005-07`, `ATS-COM-CAT-005-12`	policy	service	observed services-commerce:modules/catalog/services/persistence/product-categories.ts

Scenarios

Id	Given	When	Then	Provenance
`01`	Bookstore includes Books in its assortment	Delete Books before and after moving the store’s reference	The dependency refusal identifies Bookstore; deletion succeeds after the reference is removed	test services-commerce:modules/catalog/tests/integration/services/persistence/product-categories.integration.spec.js#is refused 409 category_in_use while a store has it as its home category, naming the store, and deleted once the store moves

Planning

Implementation

Organize product shelves ​

Purpose ​

How It Works ​

Relationships ​