docs: Add advanced product catalog development doc

.wordlist.txt

@@ -594,6 +594,8 @@ ORM
 ORMs
 OTEL
 OTLP
+OU
+OUs
 ObjectField
 ObjectType
 OffCanvas

products/extensions/b2b-components/advanced-product-catalog/concepts/entities-and-schema.md

@@ -0,0 +1,64 @@
+---
+nav:
+  title: Entities & Schema
+  position: 20
+
+---
+
+# Entities and schema
+
+## Entities
+
+### Advanced Product Catalog
+
+The Advanced Product Catalog entity represents a customized product catalog that can be associated with specific customer groups, organizational units, and sales channels. It allows merchants to control product visibility and create tailored catalog experiences for different B2B customer segments.
+
+### Advanced Product Catalog Category
+
+The Advanced Product Catalog Category entity represents the relationship between product catalogs and product categories, enabling merchants to define which categories are included in specific catalogs. This is implemented as a junction table that links catalogs to categories with version support.
+
+## Schema
+
+```mermaid
+erDiagram
+    b2b_components_advanced_product_catalogs {
+        uuid id PK
+        boolean auto_add_new_categories
+        uuid sales_channel_id FK
+        uuid created_by_id FK
+        uuid updated_by_id FK
+        uuid customer_id FK
+        uuid organization_id FK
+        uuid customer_group_id FK
+        datetime updated_at
+        datetime created_at
+        json custom_fields
+    }
+    b2b_components_advanced_product_catalogs_category {
+        uuid advanced_product_catalogs_id FK
+        uuid category_id FK
+        uuid category_version_id FK
+    }
+    category {
+        uuid id PK
+        uuid version_id PK
+    }
+    b2b_components_advanced_product_catalogs ||o{ b2b_components_advanced_product_catalogs_category : "has categories"
+    b2b_components_advanced_product_catalogs_category }o|| category : "belongs to"
+```
+
+The Advanced Product Catalog system consists of two main tables:
+
+**b2b_components_advanced_product_catalogs:**
+
+- `auto_add_new_categories`: Controls whether new categories are automatically included in the catalog
+- `organization_id`: Required field linking the catalog to a specific organizational unit
+- `customer_group_id`: Optional field for customer group-specific catalogs (unique constraint)
+- `sales_channel_id`: Optional field for sales channel-specific catalogs
+- `custom_fields`: JSON field for additional metadata and extensibility
+
+**b2b_components_advanced_product_catalogs_category:**
+
+- Junction table linking catalogs to categories with version support
+- Composite primary key: `(advanced_product_catalogs_id, category_id, category_version_id)`
+- Supports Shopware's versioning system for categories

products/extensions/b2b-components/advanced-product-catalog/guides/setup-and-configuration.md

@@ -0,0 +1,65 @@
+---
+nav:
+  title: Setup and Configuration
+  position: 10
+
+---
+
+# Setup and Configuration
+
+This guide will walk you through the initial setup and configuration of the Advanced Product Catalog component for your B2B shop.
+
+## Prerequisites
+
+Before you can use the Advanced Product Catalog, ensure you have:
+
+* **Shopware 6.7** installed and configured
+* **B2B Components** plugin was installed
+* **Organisational Unit** feature is activated
+* **Employee Management** component configured
+
+## Enabling the Feature
+
+The Advanced Product Catalog is automatically available when:
+
+1. **B2B Components Enabled**: Ensure the B2B Components are properly installed and configured
+2. **Organisational Unit is active**: The feature becomes available when at least one organisational unit is created and active
+
+## Initial Configuration
+
+### Step 1: Create Organizational Units
+
+1. Navigate to **Customer → Company → Organizational Unit**
+2. Click **Add unit**
+3. Click **Advanced product catalog** section
+
+### Step 2: Assign Employees
+
+1. Navigate to the **General** section
+2. Select employees
+3. Assign them to the appropriate organizational unit
+
+### Step 3: Configure Advanced Product Catalog
+
+1. In the organizational unit detail view, locate the **Advanced Product Catalog** section
+
+2. Configure the following settings:
+
+* **Automatically add new categories to selection**: Enable if you want new categories automatically included
+* **Categories**: Select which product categories should be visible to this organizational unit
+
+## Next Steps
+
+Once basic configuration is complete, you can:
+
+* [Configure the Administration Interface](./administration-interface.md)
+* [Set up API integrations](./api-and-integration.md)
+* [Optimize performance](./performance-and-caching.md)
+
+### Support
+
+For additional support, refer to:
+
+* [Shopware Community](https://community.shopware.com/)
+* [Shopware Documentation](https://docs.shopware.com/)
+* [B2B Components Overview](../index.md)

products/extensions/b2b-components/advanced-product-catalog/guides/store-api.md

@@ -0,0 +1,55 @@
+---
+nav:
+  title: Store API
+  position: 40
+
+---
+
+## Store API
+
+Here are some of the actions you can perform on *Advanced Product Catalog* using the Store API.
+
+### List advanced product catalog categories
+
+```http request
+GET|POST {url}/store-api/advanced-product-catalogs/categories
+```
+
+### Search advanced product catalog categories
+
+```http request
+GET {url}/store-api/advanced-product-catalogs/categories/search
+```
+
+### Create or update advanced product catalog
+
+```http request
+POST {url}/store-api/advanced-product-catalogs/save {
+    organizationId: {uuid},
+    id: {uuid} (optional),
+    autoAddNewCategories: {boolean},
+    selectedCategories: {array of uuid}
+}
+```
+
+### Update advanced product catalog
+
+```http request
+PATCH {url}/store-api/advanced-product-catalogs/save {
+    organizationId: {uuid},
+    id: {uuid} (optional),
+    autoAddNewCategories: {boolean},
+    selectedCategories: {array of uuid}
+}
+```
+
+### Remove categories from advanced product catalog
+
+```http request
+DELETE {url}/store-api/advanced-product-catalogs/categories/remove {
+    id: {uuid},
+    removedCategories: {array of uuid}
+}
+```
+
+For more details, refer to [B2B Advanced Product Catalog](https://shopware.stoplight.io/docs/store-api/branches/main/b286c1f43d395-shopware-store-api) from Store API docs.

products/extensions/b2b-components/advanced-product-catalog/index.md

@@ -0,0 +1,64 @@
+---
+nav:
+  title: Advanced Product Catalog
+  position: 10
+
+---
+
+# Advanced Product Catalog
+
+The Advanced Product Catalog component enables B2B merchants to create customized product catalogs tailored to specific organizational units (OUs). This powerful feature allows businesses to control product visibility and create personalized catalog experiences for employees within specific organizational structures, ensuring that users see only the products and categories relevant to their assigned OU.
+
+## Key Features
+
+* **Organizational Unit-Based Access**: Catalogs are tied to specific organizational units, controlling which employees can access which products
+* **Automatic Category Management**: Option to automatically include new product categories in existing catalogs
+* **Version Support**: Full compatibility with Shopware's versioning system for categories
+* **Custom Fields**: Extensible metadata support through custom fields for additional catalog configuration
+* **Feature Toggle Integration**: The feature is automatically available when an organizational unit is active
+
+## How It Works
+
+The Advanced Product Catalog system operates through a sophisticated entity relationship model that links catalogs to organizational units and product categories. When an organizational unit is active, employees within that OU automatically gain access to the Advanced Product Catalog feature.
+
+## Administration Interface
+
+The Advanced Product Catalog can be configured through the Shopware administration interface:
+
+* **Location**: Navigate to **Customer → Company → Organizational Unit**
+* **Functionality**: Create, update, and manage catalog settings for each organizational unit
+* **Configuration**: Select category access, and configure automatic category inclusion
+
+## Integration
+
+The Advanced Product Catalog is an integral part of the Organization Unit system:
+
+* **Organizational Unit Dependency**: The feature is only available when organizational units are active
+* **Employee Access Control**: Catalogs serve as settings that determine which products employees in specific OUs can access
+* **B2B Component Integration**: Works seamlessly with other B2B components like Employee Management and Organization Units
+* **Customer-Specific Features**: Supports the B2B component feature toggle system for granular access control
+
+## Use Cases
+
+* **Organizational Structure Management**: Control product visibility based on company hierarchy and organizational units
+* **Employee Access Control**: Ensure employees only see products relevant to their role and organizational level
+* **Product Portfolio Management**: Curate product offerings for specific organizational segments
+* **Access Control**: Ensure sensitive or specialized products are only visible to authorized organizational units
+* **Multi-Company Support**: Manage different product catalogs for different business entities or subsidiaries
+
+## Benefits
+
+* **Enhanced Employee Experience**: Employees see only relevant products based on their organizational context
+* **Improved Access Control**: Granular control over which products are visible to which organizational units
+* **Better Inventory Management**: Control which products are accessible to prevent unauthorized access
+* **Flexible Configuration**: Easy setup and management through the administration interface
+* **Performance Optimized**: Built-in caching support for improved catalog loading times
+
+## Feature Toggle System
+
+The Advanced Product Catalog follows the B2B component feature toggle pattern:
+
+* **Organizational Unit Activation**: The feature becomes available when an organizational unit is active
+* **Customer-Specific Control**: Merchants can control access through the customer-specific features system
+
+The Advanced Product Catalog component is essential for B2B merchants who need granular control over product visibility based on organizational structure and want to create personalized shopping experiences for their employees within different organizational units.

products/extensions/b2b-components/index.md

@@ -23,6 +23,8 @@ In the world of digital B2B commerce, where businesses engage with other compani
 
 * **Digital Sales Composables** aims to provide a set of composable frontends to cover more complex Sales Representative jobs.
 
+* **Advanced product catalog** allows merchants to define and manage product visibility for customer groups and organizational units, ensuring tailored catalogues.
+
 ## Configuring custom toggles for B2B components
 
 The B2B components allow merchants to selectively choose and configure B2B features according to their needs. They offer merchants the ability to craft a tailored B2B ecommerce experience for their business partners while also allowing agencies to fine-tune Shopware to meet specific requirements. This means that B2B components can be individually activated or deactivated for each business partner within the shop.