Skip to content

Commit c7cde0a

Browse files
author
shopwareBot
committed
[create-pull-request] automated change
1 parent 3049f90 commit c7cde0a

13 files changed

+762
-9
lines changed

‎resources/references/adr/2021-11-09-increment-pattern.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Introduce increment pattern
33
date: 2021-11-09
4-
area: system-settings
4+
area: services-settings
55
tags: [architecture, increment, message-queue-stats]
66
---
77

‎resources/references/adr/2022-03-25-prevent-mail-updates.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Prevent mail updates
33
date: 2022-03-25
4-
area: system-settings
4+
area: services-settings
55
tags: [mail, flow]
66
---
77

‎resources/references/adr/2024-04-01-checkout-gateway.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
title: Checkout gateway
3+
date: 2024-04-01
4+
area: checkout
5+
tags: [checkout, app, payment, shipping, cart]
6+
---
7+
8+
# Checkout gateway
9+
10+
::: info
11+
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
12+
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2024-04-01-checkout-gateway.md)
13+
:::
14+
15+
# ADR: Enhanced Checkout Gateway Feature
16+
## Context
17+
In response to the evolving landscape of checkout decision-making, we propose the introduction of a centralized and opinionated solution.
18+
This solution aims to facilitate informed decisions during the checkout process based on both the cart contents and the current sales channel context.
19+
The app-system, in particular, stands to benefit significantly, enabling seamless communication with the app server.
20+
Presently, achieving such functionality is constrained to app scripts, limiting the capacity for making nuanced decisions during checkout based on app server logic.
21+
22+
Moreover, payment and shipping providers necessitate specific criteria for determining the availability of their respective methods.
23+
These criteria include considerations such as risk assessment related to the current customer and cart, unavailability criteria,
24+
merchant connection status validation (e.g., checking for correct credentials), and service availability testing (e.g., detecting provider outages).
25+
Additionally, these providers require the ability to block carts during checkout based on risk assessment decisions.
26+
27+
While this ADR focuses on the aforementioned features, the implementation is designed to allow for seamless future extensions.
28+
29+
## Decision
30+
### CheckoutGatewayInterface
31+
To address the outlined challenges, we propose the introduction of the CheckoutGatewayInterface.
32+
This interface will be invoked during the checkout process to determine a response tailored to the current cart and sales channel context.
33+
34+
```php
35+
<?php declare(strict_types=1);
36+
37+
namespace Shopware\Core\Checkout\Gateway;
38+
39+
use Shopware\Core\Checkout\Gateway\Command\Struct\CheckoutGatewayPayloadStruct;
40+
use Shopware\Core\Framework\Log\Package;
41+
42+
#[Package('checkout')]
43+
interface CheckoutGatewayInterface
44+
{
45+
/**
46+
* The input struct consists of the cart, sales channel context and currently available payment and shipping methods.
47+
*/
48+
public function process(CheckoutGatewayPayloadStruct): CheckoutGatewayResponse;
49+
}
50+
```
51+
52+
Plugin developers are encouraged to create custom implementations of the `CheckoutGatewayInterface` for their specific checkout logic based on decisions from external systems (e.g., ERP, PIM).
53+
54+
The `CheckoutGatewayResponse` will include an `EntityCollection` of payment and shipping methods suitable for the current context, along with a collection of `CartErrors`.
55+
The input struct and the response is designed for future extension, allowing for more intricate decision-making during checkout.
56+
57+
#### Store-API
58+
A new store API route, `CheckoutGatewayRoute` '/store-api/checkout/gateway', will be introduced.
59+
This route will call a `CheckoutGatewayInterface` implementation and respond accordingly,
60+
and is integral to `CartOrderRoute` requests, ensuring the cart's validity for checkout during the order process.
61+
62+
#### Storefront
63+
The default invocation of the `CheckoutGatewayRoute` will occur during the checkout-confirm page and edit-order page (so-called "after order").
64+
Any changes to the context (e.g., language, currency) will trigger a reload of the payment method selection, calling the app server again.
65+
66+
#### Checkout Gateway Commands
67+
For streamlined response manipulation by plugins and app servers alike, we propose an executable chain of `CheckoutGatewayCommands`.
68+
The implementation of the app-system will heavily rely on the command structure.
69+
However, it is encouraged, but not mandatory for a custom implementation plugin-system implementation of the `CheckoutGatewayInterface` to follow the command structure.
70+
71+
These commands, chosen from a predefined set, can be responded with by plugins and app servers.
72+
The initial release will include the following commands: `add-payment-method`, `remove-payment-method`, `add-shipping-method`, `remove-shipping-method`, and `add-cart-error`.
73+
Depending on the command, the payload may differ, necessitating updates to the documentation.
74+
We propose the use of a handler pattern, to facilitate the execution of these commands.
75+
Commands will be executed in the order provided in the response.
76+
77+
### App-System
78+
For the initial release, Shopware will support a single implementation of the `CheckoutGatewayInterface`, provided by the app-system.
79+
The `AppCheckoutGateway` will sequentially call active apps, but only if the app has a defined `checkout-gateway-url` in its manifest.xml file.
80+
81+
#### App Manifest
82+
To address challenges for apps, a new app endpoint can be defined in the manifest.xml.
83+
A new key `gateways` will be added to the manifest file, with a sub-key `checkout` to define the endpoint.
84+
The `gateways` key signalizes possible future similar endpoints for different purposes.
85+
The checkout gateway endpoint is configured using a new element called `checkout`.
86+
87+
```xml
88+
<?xml version="1.0" encoding="UTF-8"?>
89+
<manifest>
90+
<!-- ... -->
91+
92+
<gateways>
93+
<checkout>https://example.com/checkout/gateway</checkout>
94+
</gateways>
95+
</manifest>
96+
```
97+
98+
#### Checkout Gateway App Payload
99+
The app server will receive the current `SalesChannelContext`, `Cart`, and available payment and shipping methods as part of the payload.
100+
The `AppCheckoutGateway` will call the app server with this payload.
101+
102+
```json
103+
{
104+
"salesChannelContext": SalesChannelContextObject,
105+
"cart": CartObject,
106+
"paymentMethods": [
107+
"payment-method-technical-name-1",
108+
"payment-method-technical-name-2",
109+
"payment-method-technical-name-3",
110+
...
111+
],
112+
"shippingMethods": [
113+
"shipping-method-technical-name-1",
114+
"shipping-method-technical-name-2",
115+
"shipping-method-technical-name-3",
116+
...
117+
]
118+
}
119+
```
120+
121+
Note that the paymentMethods and shippingMethods arrays will only contain the technical names of the methods, not the full entities.
122+
123+
#### Checkout Gateway App Response
124+
125+
```json
126+
[
127+
{
128+
"command": "remove-payment-method",
129+
"payload": {
130+
"paymentMethodTechnicalName": "payment-myApp-payment-method"
131+
}
132+
},
133+
{
134+
"command": "add-cart-error",
135+
"payload": {
136+
"reason": "Payment method not available for this cart.",
137+
"level": 20,
138+
"blockOrder": true
139+
}
140+
}
141+
]
142+
```
143+
144+
#### Event
145+
A new event `CheckoutGatewayCommandsCollectedEvent` will be introduced.
146+
This event is dispatched after the `AppCheckoutGateway` has collected all commands from all app servers.
147+
It allows plugins to manipulate the commands before they are executed, based on the same payload the app servers retrieve.
148+
149+
## Consequences
150+
### App PHP SDK
151+
The app-php-sdk will be enhanced to support the new endpoint and data types, ensuring seamless integration with the command structure.
152+
The following adaptations will be made:
153+
154+
Checkout gateway requests with payload will be deserialized into a `CheckoutGatewayRequest` object.
155+
Checkout gateway responses will be deserialized into a `CheckoutGatewayResponse` object.
156+
Every possible checkout gateway command will have a class representing it, facilitating easy manipulation of its payload.

‎resources/references/adr/2024-06-12-add-jest-runner-with-disabled-compat-mode.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: Add jest runner with disabled compat mode
3+
date: 2024-06-12
4+
area: administration
5+
tags: [administration, jest, pipeline, testing, unit]
6+
---
7+
8+
# Add jest runner with disabled compat mode
9+
10+
::: info
11+
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
12+
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2024-06-12-add-jest-runner-with-disabled-compat-mode.md)
13+
:::
14+
15+
## Context
16+
17+
Currently, our component tests in Jest are running with enabled compat mode. To remove the compat mode for each
18+
component, we need to add a new Jest runner with disabled compat mode to make sure that the tests are running without compat mode.
19+
20+
## Decision
21+
22+
I added a new runner command in the NPM scripts to run the Jest tests without compat mode. The new runner command is
23+
`unit:disabled-compat` and `unit-watch:disabled-compat`. Also, the composer commands are added to run the tests. These commands are `admin:unit:disabled-compat` and `admin:unit-watch:disabled-compat`. These commands are using the environment variable `DISABLE_JEST_COMPAT_MODE` to disable the compat mode.
24+
25+
For the pipeline, I added a new stage to run the Jest tests without compat mode. The stage is `Jest (Administration with disabled compat mode)`.
26+
27+
To mark a test file working without the compat mode you need to add a comment with the `@group` tag. The tag is `@group disabledCompat`.
28+
29+
Example:
30+
31+
```javascript
32+
/**
33+
* @package admin
34+
* @group disabledCompat
35+
*/
36+
37+
import { mount } from '@vue/test-utils';
38+
39+
async function createWrapper() {
40+
...
41+
```
42+
43+
With this tag, the test file is running without compat mode. To make a component working for both modes, you can use the
44+
compatUtils helper function from Vue compat:
45+
46+
```javascript
47+
// Example
48+
import { compatUtils } from '@vue/compat';
49+
50+
...
51+
52+
if (compatUtils.isCompatEnabled('INSTANCE_LISTENERS')) {
53+
return this.$listeners;
54+
}
55+
56+
return {};
57+
58+
...
59+
```
60+
61+
Important: the test still runs also with compat mode activated in parallel.
62+
63+
## Consequences
64+
65+
- Fixing the components and tests to run also without compat mode. This has to be done by removing the compat mode for each component.
66+
- Marking fixed tests with `@group disabledCompat` to run without compat mode.
67+
- When everything is fixed, we can remove the compat mode from the Jest configuration.

‎resources/references/adr/2024-06-17-error-code-log-level-configuration-in-cloud-and-platform.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Error-code log Level configuration in platform or cloud
3+
date: 2024-06-17
4+
area: core
5+
tags: [core, devops, observability]
6+
---
7+
8+
# Error-code log Level configuration in platform or cloud
9+
10+
::: info
11+
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
12+
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2024-06-17-error-code-log-level-configuration-in-cloud-and-platform.md)
13+
:::
14+
15+
## Context
16+
In the configuration files for platform and cloud, specific error codes can be set to the notice level.
17+
Some time ago, we decided to configure this in platform ([Exception Log Level configuration](2023-05-25-exception-log-levels)).
18+
19+
As it is still essential for some errors to be logged at the highest level for customers with own servers, we now have to decide which errors we can decrease for all customers and which only for cloud. The key consideration is whether it makes sense for on-premise customers to continue logging these errors at a high level. If it does, the error codes must be added to the cloud configuration file in the SaaS template.
20+
21+
For example, an incorrectly configured flow on the customer side is not an error that needs to be analyzed by us and has to be recorded by our error monitoring, but it is important for the customer to be informed about it at the highest log level.
22+
23+
## Decision
24+
25+
We have to decide for each error code whether it makes sense for on-premise customers to continue logging these errors at a high level. If so, the error codes have to be added to the cloud configuration file in the SaaS template.
26+
27+
### This could be a small guide for the decision:
28+
* Never decrease critical errors in platform
29+
30+
Errors that shall be configured in cloud:
31+
* all the unexpected stuff that should not happen and a dev should look at this, even though the fix is not in Shopware itself but probably in some calling code/configuration
32+
* like API misuses
33+
* or misconfigurations on the customer side
34+
35+
Errors that shall be configured in platform:
36+
* all the expected stuff, it is totally normal that those things happen and no dev needs to change something
37+
* like 404 errors
38+
* or invalid user credentials at login
39+
40+
## Consequences
41+
42+
By implementing this approach, we ensure that critical errors are properly logged and monitored in both on-premise and cloud environments, aligning with the needs and contexts of different customer bases.

0 commit comments

Comments
 (0)