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,42 @@
+---
+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 in order for an order to be approved. These conditions can be based on the order's total value, the order's currency or for all orders placed by employees with a specific role. Each approval rule can be assigned the reviewer to a specific role, which means that only employees with that role can approve orders that match the rule's conditions, and it can be assigned to specific role, which means that only employees with that role will need to request approval for orders that match the rule's conditions; and a priority, which is used to determine the order 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:
+
+![Order approval work flow](./media/work-flow.png)
+
+
+## Who can request approval?
+
+- Employees which have the role that is assigned as the "Effective role" of the approval rule that matched the order.
+
+## Who can view pending orders?
+
+- Employees with the "Can view all pending orders" permission can view all pending orders.
+- Employees which requested approval for the order can view his pending orders.
+- Business Partners can view all pending orders of their employees.
+
+## Who can approve/decline pending orders?
+
+- Employees with the "Can approve/decline all pending orders" permission can approve/decline all pending orders.
+- Employees with the "Can approve/decline pending orders" permission can approve/decline pending orders that assigned to him.
+- Business Partners can approve/decline all pending orders of their employees.

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

@@ -0,0 +1,28 @@
+---
+nav:
+  title: Order approval permissions
+  position: 20
+
+---
+
+# Order approval permissions
+## Introduction
+
+Below you can find a list of all the order approval rules that are available in the order approval component, which you can use to assign to the roles of 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 pending orders that assigned to him. |
+| `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,43 @@
+---
+nav:
+  title: Payment Process
+  position: 30
+
+---
+
+# Order approval's Payment Process
+
+## Introduction
+
+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, with the exception that if this is the online payment method (Visa, Paypal, etc.), the payment process will be executed only after the order has been approved.
+
+## 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,75 @@
+---
+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 that you can use to define your approval rules. However, if you need to add a new condition, you can do so via app or plugin.
+
+## Plugin
+
+Each condition is represented by a class that extends the abstract class `Shopware\Commercial\B2B\OrderApproval\Domain\ApprovalRule\Rule\OrderApprovalRule` class. 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');
+    }
+}
+```
+
+## App
+
+(We will update this section soon)

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)).