diff --git a/assets/auditlog-structure.svg b/assets/auditlog-structure.svg deleted file mode 100644 index 787f45a01..000000000 --- a/assets/auditlog-structure.svg +++ /dev/null @@ -1,2 +0,0 @@ - -

b2b_audit_log_index

id
audit_log_id
reference_table
reference_id

[Not supported by viewer]

b2b_audit_log

id

log_value

log_type

event_date

author_hash

[Not supported by viewer]
n
n

b2b_audit_log_author

hash
salutation
title
firstname
lastname
email

[Not supported by viewer]
1
1
n
n
1
1 \ No newline at end of file diff --git a/assets/cart-calculation-steps.png b/assets/cart-calculation-steps.png deleted file mode 100644 index bc800628e..000000000 Binary files a/assets/cart-calculation-steps.png and /dev/null differ diff --git a/assets/cart-enrichtment-steps.png b/assets/cart-enrichtment-steps.png deleted file mode 100644 index f1df785c3..000000000 Binary files a/assets/cart-enrichtment-steps.png and /dev/null differ diff --git a/assets/cart-state.png b/assets/cart-state.png deleted file mode 100644 index dcfa58ad2..000000000 Binary files a/assets/cart-state.png and /dev/null differ diff --git a/assets/cart-validation.png b/assets/cart-validation.png deleted file mode 100644 index 4aa696d5a..000000000 Binary files a/assets/cart-validation.png and /dev/null differ diff --git a/assets/concept-catalog-products-datamodel.png b/assets/concept-catalog-products-datamodel.png deleted file mode 100644 index 5855b9aea..000000000 Binary files a/assets/concept-catalog-products-datamodel.png and /dev/null differ diff --git a/assets/concept-catalog-products-variantModel.png b/assets/concept-catalog-products-variantModel.png deleted file mode 100644 index 01829dc32..000000000 Binary files a/assets/concept-catalog-products-variantModel.png and /dev/null differ diff --git a/assets/flow-concept-1.png b/assets/flow-concept-1.png deleted file mode 100644 index 8efa428df..000000000 Binary files a/assets/flow-concept-1.png and /dev/null differ diff --git a/assets/flow-concept-2.png b/assets/flow-concept-2.png deleted file mode 100644 index 8aaff5814..000000000 Binary files a/assets/flow-concept-2.png and /dev/null differ diff --git a/assets/multi-inventory-data-structure.png b/assets/multi-inventory-data-structure.png deleted file mode 100644 index 9b4a0d3a1..000000000 Binary files a/assets/multi-inventory-data-structure.png and /dev/null differ diff --git a/assets/rule-objects.png b/assets/rule-objects.png deleted file mode 100644 index 7c522c645..000000000 Binary files a/assets/rule-objects.png and /dev/null differ diff --git a/assets/rule-sequence.png b/assets/rule-sequence.png deleted file mode 100644 index 3fa5ac051..000000000 Binary files a/assets/rule-sequence.png and /dev/null differ diff --git a/concepts/commerce/catalog/products.md b/concepts/commerce/catalog/products.md index f751a469d..8a549e4ee 100644 --- a/concepts/commerce/catalog/products.md +++ b/concepts/commerce/catalog/products.md @@ -11,32 +11,77 @@ Products are sellable entities (physical and digital products) within your shop. Depending on your setup, Shopware can easily handle thousands of products. However, an upsurge in the product quantity (in millions) needs some tweaks for robust running of the environment as it depends on factors like the number of [categories](../../../concepts/commerce/catalog/categories), [sales channels](../../../concepts/commerce/catalog/sales-channels), [product properties](../../../concepts/commerce/catalog/products#property-groups--options), etc. Every product added to your shop can be made available on one or more [sales channels](../../../concepts/commerce/catalog/sales-channels). -Let us start understanding about product more in detail: - -* **Product details**: General information about a Product - for example, title, manufacturer, prices, media, etc. -* **Product properties**: Product properties encapsulates property groups and options. -* **Product variant**: A sellable good. Product Variants are generally mapped to products. Inventory is modeled per variant. -* **Category**: Products in Shopware are organised in categories. It is a grouping of products based on characteristics, marketing or search concerns. Categories are represented as a hierarchical tree to form a navigation menu. A product can be contained in multiple categories. - -Look at the below condensed overview of the product data model: - -![Condensed overview of the product data model](../../../assets/concept-catalog-products-datamodel.png) - -Besides their relation to categories, products can also link to a set of *property group options*. - -## Property groups and options - -Product properties can be modeled using property groups and -options. They can be displayed in a table on your product detail pages, in listings, or even be used for filtering. - -Examples of property group garments are *Size*, *Color* or *Material*. The corresponding values of each group are referred to as *property group options*. A product can have arbitrarily many property group options. - -## Product variants - -Different variations of a product can be modeled using *product variants*. Products are a self-referencing entity, which is interpreted as a parent-child relationship. This mechanism is also used to model variants. This also provides inheritance between field values from parent products to child products. - -![Variant model](../../../assets/concept-catalog-products-variantModel.png) - -However, it is also useful to attach some additional properties to differentiate product variants next to the field inheritance. For that reason, it is critical to understand the difference between *properties* and *options*: +Let's delve into a more detailed understanding of products using the example of garments: + +* **Product details**: General information about a Product. + +| Title | Product Id | Manufacturer | Prices | .... | +|-------|-----------|--------------|--------|----------| +| Levis Ocean Hoodie | SW1001 | CA | 40 | ... | + +* **Product properties**: Product properties encapsulates property groups and options. They are displayed in a table on product details page, in listings, or even be used for filtering. A product can have arbitrarily many property group options. + +| Property Group | Property Group Options | +|----------------|-----------------------| +| Size | *S*, *M*, *L*, *XL*, etc | +| Color | *Red*, *Blue*, *Green*, *Black* | +| Material | *Leather*, *Cotton*, *Jeans* | + +* **Category**: Products in Shopware are organized in categories. It is a grouping of products based on characteristics, marketing or search concerns. Categories are represented as a hierarchical tree to form a navigation menu. A product can be contained in multiple categories. + +Look at the below condensed overview of relationships between entities - products, categories, options, and property groups are interconnected in the database schema. + +```mermaid +erDiagram + Product||--|{ ProductCategory : "M:1" + ProductCategory}|--|| Category : "1:M" + Product { + uuid product_id + } + ProductCategory { + uuid product_id + uuid category_id + } + Category { + uuid category_id + } + Product ||--|{ ProductOption : "1:M" + ProductOption{ + uuid product_id + uuid property_group_option_id + } + ProductOption }|--|| PropertyGroupOption : "M:1" + PropertyGroupOption{ + uuid property_group_option_id + uuid property_group_id + } + PropertyGroupOption }|--|| PropertyGroup : "M:1" + PropertyGroup{ + uuid property_group_id + } +``` + +* **Product variant**: A sellable product. Products are a self-referencing entity, which is interpreted as a parent-child relationship. Similarly, product variants are also generally mapped to products. This mechanism is used to model variants. This also provides inheritance between field values from parent products to child products. + +```mermaid +erDiagram + Product||--|| Product : "uuid=variant" + Product { + uuid product_id + uuid parent_id + } + Product ||--|{ PropertyGroupOption : "1:M" + PropertyGroupOption{ + uuid property_group_option_id + uuid property_group_id + } + PropertyGroupOption }|--|| PropertyGroup : "M:1" + PropertyGroup{ + uuid property_group_id + } +``` + +It is also useful to attach some additional properties to differentiate product variants next to the field inheritance. For that reason, it is critical to understand the difference between *properties* and *options*: **Properties** are used to model facts about a product, but usually, different product variants share these facts. We can refer to properties as *non variant defining*. They could be useful to represent the following information: @@ -50,9 +95,14 @@ Opposed to that **options** are considered variant defining, as they are the fac * Color * Container volume -It is important to understand the difference between those two because both provide a relation between the product and the property group option entity. However only one constitutes to product variants. +It is important to understand the difference between those two because both provide a relation between the *product* and the *property group option* entity. However only one constitutes to *product variants*. + +| Variant | Product | Category | Product Group | Product Group Option | +|---------|---------|----------|---------------|----------------------| +| Variant 1 | Levis Ocean Hoodie | Hoodie & Sweaters | Color | Red | +| Variant 2 | Levis Ocean Hoodie | Hoodie & Sweaters | Color | Black | -### Configurator +## Configurator When a variant product is loaded for a [Store API](../../api/store-api)-scoped request, Shopware assembles a configurator object which includes all different property groups and the corresponding variants. This way client applications, such as the [Storefront](../../../guides/plugins/plugins/storefront/) or the [PWA](../../../products/pwa) can display the different variant options of the product. diff --git a/concepts/commerce/checkout-concept/cart.md b/concepts/commerce/checkout-concept/cart.md index 94eb03b8d..7df8e362d 100644 --- a/concepts/commerce/checkout-concept/cart.md +++ b/concepts/commerce/checkout-concept/cart.md @@ -68,13 +68,48 @@ The price of all line items, including tax, delivery costs, voucher discounts, a Shopware 6 manages the cart's state through different services. The diagram below illustrates the different states the cart can have and the state changes it can go through. -![Cart state](../../../assets/cart-state.png) +```mermaid +--- +title: Cart State +--- +stateDiagram-v2 + [*] --> Empty + Empty --> Dirty : add line item + Dirty --> Calculated : calculate + Calculated --> Dirty : modify line item/shipping/payment + Calculated --> Calculated : order invalid + Calculated --> [*] : order +``` + +| Cart state | Description| +|------|------------| +| Empty | A cart with no items will have default shipping and payment settings. | +| Dirty | On adding a new line item, the cart undergoes modifications with invalid prices, raw line items, and uncertain delivery validity. Consequently, calculations are necessary.| +| Calculated | After accurate calculations, the cart can be either submitted as an order or may contain errors that need to be addressed. | ## Calculation Calculating a cart is one of the more costly operations an ecommerce system must support. Therefore the interfaces of the cart are designed as precise and as quick as possible. The calculation is a multi-stage process that revolves around the mutation of the data structure of the cart struct shown in the diagram below: -![Cart calculation](../../../assets/cart-calculation-steps.png) +```mermaid +--- +title: Cart Calculation +--- +stateDiagram-v2 + [*] --> Enrich + Enrich --> Process + Process --> Validate + Validate --> Validate : repeat until no changes occur + Validate --> Persist + Persist --> [*] +``` + +| Cart calculation state | Description| +|------|------------| +| Enrich | The calculation process in the **enrich state** for line items involves adding images, its descriptions and determining prices | +| Process | During the **process state**, price updates occur, adjustments to shipping and payment are made| +| Validate | In the **validate state**, validation is performed using the rule system and cart changes based on plausibility checks. | +| Persist | The **persist state** is responsible for updating the storage. | ### Cart enrichment @@ -105,7 +140,28 @@ A default set of collectors is implemented in Shopware 6, which has a set call o | Shopware\Core\Checkout\Promotion\Cart\CartPromotionsCollector | Enrich add, remove and validate promotions | | Shopware\Core\Checkout\Shipping\Cart\ShippingMethodPriceCollector | Handle shipping prices | -![Cart enrichment steps](../../../assets/cart-enrichtment-steps.png) +```mermaid +--- +title: Enrichment +--- +sequenceDiagram +Enrichment->>Enrichment : +box + participant Enrichment + participant ProductCartProcessor + participant CartPromotionsCollector + participant CartDiscountCollector + end + Note over Enrichment,CartDiscountCollector: Collect + Enrichment->>ProductCartProcessor: collect + Enrichment->>CartPromotionsCollector: collect + Enrichment->>CartDiscountCollector: collect + Note over Enrichment,CartDiscountCollector: Enrichment + Enrichment->>ProductCartProcessor: enrich + Enrichment->>CartPromotionsCollector: enrich + Enrichment->>CartDiscountCollector: enrich + Enrichment->>Enrichment : +``` ## Cart processors - price calculation and validation @@ -124,7 +180,16 @@ After the cart has been processed, it is validated against the rules, which can * Everybody buying a car gets a pair of sunglasses for free. * Every cart containing two products gets a discount of 2%. -![Cart validation](../../../assets/cart-validation.png) +```mermaid +stateDiagram-v2 + [*] --> Empty_cart : checkout started + Empty_cart --> Enrichment : User orders a car + state Enrichment { + Cart_with_lineitem(car) --> Cart_with_lineitem(car+sunglasses) : Iteration 1 - Cart automatically adds sunglasses + Cart_with_lineitem(car+sunglasses) --> Cart_with_lineitem(car+sunglasses+2%discount) : Iteration 2 - Cart automatically adds discount + } + Cart_with_lineitem(car+sunglasses+2%discount) --> [*] : valid +``` As you can see in the diagram above, the cart is modified during the enrichment process. The sunglasses are added in the first iteration, and in the second iteration, the discount is added as the cart contains two products. This results in the expected state of one car, one pair of sunglasses, and a two-percent discount. diff --git a/concepts/framework/flow-concept.md b/concepts/framework/flow-concept.md index 8731f0eb6..5b203cf22 100644 --- a/concepts/framework/flow-concept.md +++ b/concepts/framework/flow-concept.md @@ -43,8 +43,35 @@ In Shopware, you have multiple interfaces and classes for different types of eve Once the action on the Storefront or from the app happens, the FlowDispatcher will dispatch FlowEventAware to the FlowExecutor. From here, the FlowExecutor will check the condition to decide whether to execute the action. -![Flow builder concept for flow sequence](../../assets/flow-concept-1.png) +```mermaid +flowchart-elk TD + A([Start])-->B["`FlowDispatcher::dispatch()`"] + B--dispatches (FlowEventAware)-->C["`FlowExecutor::execute()`"] + C-->D{"`FlowExecutor::sequenceRuleMatches()`"} + C--no condition-->E["`FlowExecutor::executeAction3()`"] + D--Yes-->I["`FlowExecutor::executeAction2()`"] + E-->F["`StopFlowAction::handleFlow()`"] + F-->G([End]) + D--No -->H["`FlowExecutor::executeAction1()`"] + H-->F + I-->F +``` Here is an example flow of what happens in the system when an order is placed on the Storefront. -![Flow builder concept for order placed](../../assets/flow-concept-2.png) +```mermaid +flowchart-elk TD + A([Start]) +subgraph Storefront + B[User] +end +A-->Storefront +Storefront--Place an order-->Core +subgraph Core + C["`CartOrderRoute::Order()`"]--dispatch [checkout.order.place]-->D["`FlowDispatcher::dispatch()`"] + D-->E["`FlowExecutor::execute()`"] + E-->F["`FlowExecutor::executeAction()`"] + F-->G["`StopFlowAction::handleFlow()`"] +end + G-->H([End]) +``` diff --git a/concepts/framework/rules.md b/concepts/framework/rules.md index 23bcfa017..abf4cb0fd 100644 --- a/concepts/framework/rules.md +++ b/concepts/framework/rules.md @@ -39,11 +39,32 @@ The center of the rule system is the `Rule`. It is realized as a variant of the As well as a Specification class, a Rule class represents a condition to fulfill. It implements the `match(RuleScope $scope)` function to validate user defined values against a runtime state. See the following object diagram for a better understanding: -![](../../assets/rule-objects.png) +```mermaid +classDiagram + root-OrRule .. lineItemCount - LineItemsInCartCountRule + root-OrRule .. cartPrice - GoodsPriceRule + class root-OrRule{ + rules=[lineItemCount, cartPrice] + } + class lineItemCount - LineItemsInCartCountRule{ + operator=">=" + count="40" + } + class cartPrice - GoodsPriceRule{ + operator=">=" + count="500" + } +``` This will result in the following call order: -![](../../assets/rule-sequence.png) +```mermaid +sequenceDiagram + root-->>lineItemCount: match()? + lineItemCount-->>root: false + root-->>cartPrice: match()? + cartPrice-->>root: false +``` As you can see, a single rule can either contain user defined values or other user defined rules. These are Container rules. The rule system here bears some resemblance to the [SearchCriteria](../../guides/plugins/plugins/framework/data-handling/reading-data#Filtering), although independent. A Search Criteria is the representation of a query that gets translated and executed through the storage engine. The rule matches in-memory in PHP and does not access the underlying storage. diff --git a/guides/plugins/plugins/api/multi-inventory.md b/guides/plugins/plugins/api/multi-inventory.md index f2be20fea..084bb8902 100644 --- a/guides/plugins/plugins/api/multi-inventory.md +++ b/guides/plugins/plugins/api/multi-inventory.md @@ -34,7 +34,61 @@ Meanwhile, refer to the following links regarding the general use of the Admin A The Multi-Inventory feature implements a specific data structure for its internal stock handling. The following entity-relationship model visually represents the new entities, as well as the relationships between them and platform entities. -![multi-inventory_data-structure](../../../../assets/multi-inventory-data-structure.png) +```mermaid +erDiagram + OrderWarehouseGroup }|..|| Order : "M:1" + OrderWarehouseGroup { + uuid order_id + uuid warehouse_group_id + } + OrderWarehouseGroup }|..|| WarehouseGroup : "M:1" + OrderProductWarehouse }|..|| Order : "1:M" + OrderProductWarehouse{ + uuid order_id + uuid product_id + uuid warehouse_id + } + Order { + uuid order_id + } + OrderProductWarehouse }|..|{ WarehouseGroupWarehouse : "M:N" + Warehouse { + uuid warehouse_id + } + WarehouseGroup }|..|| Rule : "M:1" + Rule{ + uuid rule_id + } + WarehouseGroup { + uuid rule_id + uuid warehouse_group_id + } + WarehouseGroup ||..|{ ProductWarehouseGroup : "1:M" + ProductWarehouseGroup { + uuid product_id + uuid warehouse_group_id + } + WarehouseGroup ||..|{ WarehouseGroupWarehouse : "1:M" + WarehouseGroup }|..|{ WarehouseGroupWarehouse : "M:N" + WarehouseGroupWarehouse { + uuid warehouse_id + uuid warehouse_group_id + } + ProductWarehouseGroup }|..|| Product : "M:1" + OrderProductWarehouse }|..|| Product : "M:1" + Product { + uuid produtc_id + } + ProductWarehouse }|..|| Product : "M:1" + WarehouseGroupWarehouse }|..|| Warehouse : "M:1" + WarehouseGroupWarehouse }|..|{ Warehouse : "M:N" + ProductWarehouse }|..|| Warehouse : "1:M" + ProductWarehouse { + uuid product_id + uuid warehouse_id + } + Warehouse ||..|{ OrderProductWarehouse : "1:M" +``` ## Working with the API diff --git a/products/extensions/b2b-suite/concept/line-item-list.md b/products/extensions/b2b-suite/concept/line-item-list.md index 9c35e25de..7f6eb3ce7 100644 --- a/products/extensions/b2b-suite/concept/line-item-list.md +++ b/products/extensions/b2b-suite/concept/line-item-list.md @@ -17,7 +17,6 @@ The LineItemList component is the central representation of product lists in the * Guaranteed audit logging The component is used across multiple different child components throughout the B2B Suite. - ![image](../../../../assets/line-item-list-outer-dependencies.svg) The yellow colored blocks represent components, while the smaller green ones are context objects that contain the component specific information. diff --git a/products/extensions/b2b-suite/guides/core/audit-log.md b/products/extensions/b2b-suite/guides/core/audit-log.md index 4677fb210..8591341d9 100644 --- a/products/extensions/b2b-suite/guides/core/audit-log.md +++ b/products/extensions/b2b-suite/guides/core/audit-log.md @@ -14,7 +14,32 @@ nav: The B2B Suite provides a general audit log that can be implemented in every component. The audit log component can save different log types and author information like first name, last name, and email. It provides a one-to-many association index. The database structure is described in the graphic below: -![image](../../../../../assets/auditlog-structure.svg) +```mermaid +classDiagram + b2b_audit_log_index <--o b2b_audit_log : n to 1 + b2b_audit_log o--> b2b_audit_log_author : n to 1 + class b2b_audit_log_index{ + id + audit_log_id + reference_table + reference_id + } + class b2b_audit_log{ + id + log_value + log_type + event_date + author_hash + } + class b2b_audit_log_author{ + hash + salutation + title + firstname + lastname + email + } +``` As you can see, the database structure is very flat. In the `b2b_audit_log` table, we save a log type and a serialized *AuditLogValueEntity*. All required author information is saved in the `b2b_audit_log_author` table. diff --git a/products/extensions/b2b-suite/guides/storefront/ajax-panel.md b/products/extensions/b2b-suite/guides/storefront/ajax-panel.md index ef849a12c..94b958258 100644 --- a/products/extensions/b2b-suite/guides/storefront/ajax-panel.md +++ b/products/extensions/b2b-suite/guides/storefront/ajax-panel.md @@ -21,7 +21,7 @@ The most basic ajax panel looks like this: ```twig