Getting Started

Minimal Setup

Installation

composer require baks-dev/wildberries-manufacture
php bin/console baks:assets:install
php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrate

Verify the package is registered in config/packages/baks_dev_wildberries_manufacture.yaml (auto-generated by the installer).

First Use Case: Order Production Trigger

Hook into Wildberries order events (e.g., OrderReceivedEvent) to initiate production:

use BaksDev\WildberriesManufacture\Event\OrderProductionTriggered;

// In your event subscriber/listener
public function onOrderReceived(OrderReceivedEvent $event) {
    $productionService = app()->make(OrderProductionService::class);
    $productionService->triggerProduction($event->getOrder());
}

Key Classes to Explore
- OrderProductionService: Core service for managing production workflows.
- ProductionStatus: Enum for tracking production stages (e.g., PENDING, IN_PROGRESS, COMPLETED).
- ProductionLog: Model for auditing production steps (check src/Entity/ProductionLog.php).

Implementation Patterns

Workflow Integration

Event-Driven Production

Extend the package’s event system to fit your workflow:

// Example: Custom event for manual production start
class ManualProductionTriggered extends OrderProductionTriggered {
    public function __construct(Order $order, string $initiatedBy) {
        parent::__construct($order);
        $this->initiatedBy = $initiatedBy;
    }
}

Dispatch events in your controllers/services:

event(new ManualProductionTriggered($order, 'admin'));

Production Steps as Commands

Use Symfony’s command bus to chain production steps:

// Define a command for a specific step (e.g., cutting fabric)
class CutFabricCommand implements CommandInterface {
    public function __invoke(OrderProductionContext $context) {
        // Logic for cutting fabric
        $context->addLog('Fabric cut for SKU: ' . $context->getSku());
    }
}

production_steps:
    cut_fabric: App\Command\CutFabricCommand
    assemble: App\Command\AssembleProductCommand

Inventory Sync

Hook into the ProductionCompleted event to update inventory:

public function onProductionCompleted(ProductionCompleted $event) {
    $inventoryService = app()->make(InventoryService::class);
    $inventoryService->deductMaterials($event->getProduction()->getMaterials());
}

API Integration

Wildberries API Sync: Use the WildberriesApiClient to fetch/update order data:

$client = app()->make(WildberriesApiClient::class);
$order = $client->fetchOrder($orderId);

Configure API credentials in .env:

WILDBERRIES_API_KEY=your_key
WILDBERRIES_API_SECRET=your_secret

Webhook Handling: Validate and process Wildberries webhooks (e.g., order status updates):

public function handleWebhook(Request $request) {
    $validator = app()->make(WebhookValidator::class);
    if (!$validator->validate($request)) {
        abort(403);
    }
    $payload = $validator->getPayload();
    // Dispatch internal events based on payload
}

Gotchas and Tips

Pitfalls

Migration Conflicts
- The package includes Doctrine migrations. If you’ve modified the production or production_log tables manually:
  - Run php bin/console doctrine:schema:update --dump-sql to preview changes.
  - Use --complete flag if migrations fail:
```
php bin/console doctrine:migrations:migrate --complete
```

Event Dispatching Order

Ensure events are dispatched after order persistence to avoid EntityNotFoundException:

// Bad: Dispatching before saving
event(new OrderReceivedEvent($order));
$entityManager->persist($order);

// Good: Dispatch after flush
$entityManager->persist($order);
$entityManager->flush();
event(new OrderReceivedEvent($order));

Production Step Dependencies

Steps may fail silently if dependencies (e.g., materials) are missing. Add validation:

public function __invoke(OrderProductionContext $context) {
    if (!$context->hasMaterial('fabric')) {
        throw new \RuntimeException('Missing fabric for SKU: ' . $context->getSku());
    }
}

Debugging

Enable Production Logging: Configure Monolog in config/packages/monolog.yaml to log production steps:

handlers:
    production_log:
        type: stream
        path: "%kernel.logs_dir%/production.log"
        level: debug
        channels: ["production"]

Log context in commands:

$this->logger->debug('Production step', [
    'order_id' => $context->getOrder()->getId(),
    'sku' => $context->getSku(),
    'status' => $context->getStatus()->value,
]);

Test Production Workflows: Use the test group to validate edge cases:

php bin/phpunit --group=wildberries-manufacture --filter=testProductionWithMissingMaterial

Extension Points

Custom Production Statuses Extend the ProductionStatus enum:

namespace App\Enum;

use BaksDev\WildberriesManufacture\Enum\ProductionStatus as BaseStatus;

final class CustomProductionStatus extends BaseStatus {
    public const QUALITY_CHECK = 'quality_check';
}

Update the production_status table migration to include new values.

Material Management Override material validation logic by extending MaterialValidator:

class CustomMaterialValidator extends MaterialValidator {
    protected function validateQuantity(Material $material) {
        if ($material->getQuantity() < 10) {
            throw new \RuntimeException('Minimum quantity is 10');
        }
    }
}

Bind the service in config/services.yaml:

BaksDev\WildberriesManufacture\Validator\MaterialValidator: '@App\Validator\CustomMaterialValidator'

UI Integration

Use the ProductionStatus enum in templates:

{# templates/production/status.html.twig #}
<span class="status {{ production.status.value }}">
    {{ production.status.label|trans }}
</span>

Add translations for custom statuses in translations/messages.en.yaml:
```
production_status:
    quality_check: "Quality Check"
```

Configuration Quirks

API Rate Limiting: The WildberriesApiClient uses Guzzle with default retry logic. Adjust in config/packages/baks_dev_wildberries_manufacture.yaml:
```
wildberries_api:
    retry:
        max_attempts: 3
        delay: 100
```
Timezone Handling: Production timestamps default to UTC. Override in config/packages/baks_dev_wildberries_manufacture.yaml:
```
timezone: Europe/Moscow
```
File Storage: The package stores production files (e.g., logs) in var/production/. Customize the path:
```
storage:
    production_dir: "%kernel.project_dir%/var/custom_production"
```

Wildberries Manufacture Laravel Package