NEXT-32619 - Write document for order approval

products/extensions/b2b-components/index.md

@@ -15,6 +15,8 @@ In the world of digital B2B commerce, where businesses engage with other compani
 
 * **Quote Managements** covers Sales Representative related jobs around negotiating quotes with customers.
 
+* **Order Approval** allows for a more controlled buying process by introducing an approval workflow.
+
 * **Quick Order and Order List** takes care of distinctive B2B buying behaviors.
 
 * **Digital Sales Composables** aims to provide a set of composable frontends to cover more complex Sales Representative jobs.

products/extensions/b2b-components/order-approval/01-entities-and-workflow.md

@@ -0,0 +1,49 @@
+---
+nav:
+  title: Entities and workflow
+  position: 10
+
+---
+
+
+# Entities and workflow
+
+## Entities
+
+### Approval Rule
+
+The approval rule entity represents a set of conditions that need to be met for an order to be approved. These conditions might be based on the order's total value, the order's currency or orders placed by employees with a specific role. Each approval rule can be assigned to a reviewer with specific role, which means that only employees that only employees possessing that role are authorized to approve orders meeting the rule's conditions. Additionally, it can be assigned to a particular role, requiring employees with that role to seek approval for orders meeting the rule's criteria. The rule also includes a priority, dictating the sequence in which the rules are evaluated.
+
+### Pending Order
+
+The pending order entity represents an order that has been placed by an employee that requires approval. It contains the order's data, the employee that placed the order and the approval rule that matched the order.
+
+## Workflow
+
+The following diagram shows the workflow of the order approval component:
+
+```mermaid
+flowchart TD
+    A(Employee places an order) -->B{Approval rule applies}
+    B-->|No| C[Event: Order Placed]
+    B-->|Yes| D[Event: Order needs approval]
+    D-->E{Order approved?}
+    E-->|No| F[Event: Order declined]
+    E-->|Yes| G[Event: Order Approved & Event: Order placed]
+```
+
+## Who can request approval?
+
+* Employees holding the role designated as the "Effective role" in the approval rule corresponding to the order are authorized to request approval.
+
+## Who can view pending orders?
+
+- Employees with the "Can view all pending orders" permission can view all pending orders.
+- Employees who requested approval for the order can view their pending orders.
+- Business Partners can view all pending orders of their employees.
+
+## Who can approve or decline pending orders?
+
+- Employees with the "Can approve/decline all pending orders" permission can approve or decline all pending orders.
+- Employees with the "Can approve/decline pending orders" permission can approve or decline pending orders that assigned to them.
+- Business Partners can approve or decline all pending orders of their employees.

products/extensions/b2b-components/order-approval/02-order-approval-permissions.md

@@ -0,0 +1,27 @@
+---
+nav:
+  title: Order approval permissions
+  position: 20
+
+---
+
+# Order approval permissions
+
+Below you can find a list of all the order approval rules that are available in the order approval component. You can utilize these rules for assigning roles to your employees.
+
+### Approval rule permissions
+
+| Permission                  | Description                                   |
+|-----------------------------|-----------------------------------------------|
+| `Can create approval rules` | Allows the employee to create approval rules |
+| `Can update approval rules` | Allows the employee to update approval rules |
+| `Can delete approval rules` | Allows the employee to delete approval rules |
+| `Can read approval rules`   | Allows the employee to view approval rules  |
+
+### Pending order Permissions
+
+| Permission                               | Description                                                         |
+|------------------------------------------|---------------------------------------------------------------------|
+| `Can approve/decline all pending orders` | Allows the employee to approve or decline all pending orders        |
+| `Can approve/decline pending orders`     | Allows the employee to approve or decline assigned pending orders   |
+| `Can view all pending orders`            | Allows the employee to view all pending orders                      |

products/extensions/b2b-components/order-approval/03-payment-process.md

@@ -0,0 +1,41 @@
+---
+nav:
+  title: Payment Process
+  position: 30
+
+---
+
+# Order approval's payment process
+
+The payment process of the order approval component is the same as the payment process of the order component. You can select the payment method that you want to use for your orders; however unlike the standard order component, the payment process will be executed only after the order has been approved in case of the online payment method (Visa, PayPal, etc.).
+
+## Customization
+
+### Storefront
+
+The payment process of the order approval component can be customized by extending or overriding this page `@OrderApproval/storefront/pending-order/page/pending-approval/detail.html.twig`
+
+### Payment process
+
+Normally, after reviewer approves the order, the payment process will be executed automatically. However, if you just want to approve the order without executing the payment process, you can subscribe to the `PendingOrderApprovedEvent` event and set the `PendingOrderApprovedEvent::shouldProceedPlaceOrder` to `false`. This event is dispatched in the `Shopware\Commercial\B2B\OrderApproval\Storefront\Controller\ApprovalPendingOrderController::order` method.
+
+```PHP
+
+use Shopware\Commercial\B2B\OrderApproval\Event\PendingOrderApprovedEvent;
+
+class MySubscriber implements EventSubscriberInterface
+{
+    public static function getSubscribedEvents(): array
+    {
+        return [
+            PendingOrderApprovedEvent::class => 'onPendingOrderApproved'
+        ];
+    }
+
+    public function onPendingOrderApproved(PendingOrderApprovedEvent $event): void
+    {
+        $event->setShouldProceedPlaceOrder(false);
+    }
+}
+```
+

products/extensions/b2b-components/order-approval/04-add-new-approval-condition.md

@@ -0,0 +1,83 @@
+---
+nav:
+  title: How to add a new approval condition
+  position: 40
+
+---
+
+# How to add a new approval condition
+
+The order approval component provides a set of conditions for defining your approval rules. However, if you need to add a new condition, you can do so via an app or a plugin.
+
+## Plugin
+
+Each condition is represented by a class that extends the abstract class `Shopware\Commercial\B2B\OrderApproval\Domain\ApprovalRule\Rule\OrderApprovalRule`. To add a new condition, you need to create a new class that extends the `OrderApprovalRule` class and implements the `match` and `getConstraints` methods. The `match` method is used to determine if the condition is met, and the `getConstraints` method is used to define the field, value or operator constraints that can be used in the condition.
+
+Example:
+
+```PHP
+<?php declare(strict_types=1);
+
+namespace YourPluginNameSpace;
+
+use Shopware\Commercial\B2B\OrderApproval\Domain\ApprovalRule\Rule\OrderApprovalRule;
+
+class CartAmountRule extends OrderApprovalRule
+{
+    final public const RULE_NAME = self::PREFIX . 'cart-amount';
+
+    public const AMOUNT = 1000;
+
+    protected float $amount;
+
+    /**
+     * @internal
+     */
+    public function __construct(
+        protected string $operator = self::OPERATOR_GTE,
+        ?float $amount = self::AMOUNT
+    ) {
+        parent::__construct();
+        $this->amount = (float) $amount;
+    }
+
+    /**
+     * @throws UnsupportedOperatorException
+     */
+    public function match(RuleScope $scope): bool
+    {
+        if (!$scope instanceof CartRuleScope) {
+            return false;
+        }
+
+        return RuleComparison::numeric($scope->getCart()->getPrice()->getTotalPrice(), $this->amount, $this->operator);
+    }
+
+    public function getConstraints(): array
+    {
+        return [
+            'amount' => RuleConstraints::float(),
+            'operator' => RuleConstraints::numericOperators(false),
+        ];
+    }
+
+    public function getConfig(): RuleConfig
+    {
+        return (new RuleConfig())
+            ->operatorSet(RuleConfig::OPERATOR_SET_NUMBER)
+            ->numberField('amount');
+    }
+}
+```
+
+And then tag your class with the `shopware.approval_rule.definition` tag:
+
+```XML
+ <service id="YourPluginNameSpace\CartAmountRule" public="true">
+    <tag name="shopware.approval_rule.definition"/>
+ </service>
+```
+
+## App
+
+We have not yet added support for extending custom `OrderApprovalRules` for the app.

products/extensions/b2b-components/order-approval/index.md

@@ -0,0 +1,14 @@
+---
+nav:
+  title: Order Approval
+  position: 20
+
+---
+
+# Order approval component
+
+Order approval component is a part of the B2B Employee Management. It allows you to define rules that determine which orders require approval and which employees can approve them. It also allows you to view all pending orders and approve or decline them.
+
+## Requirements
+
+* You need to have Employee Management component installed and activated (see [Employee Management](../employee-management/README.md)).