Getting Started

Minimal Steps to First Use

Install Dependencies:
```
composer require baks-dev/ozon-package baks-dev/ozon-manufacture
```
- Verify composer.json for PHP 8.4+ compatibility.
Publish Configuration and Assets:
```
php artisan baks:assets:install
```
- This copies config files (e.g., config/ozon-manufacture.php) and migrations to your project.
Run Database Migrations:
```
php artisan doctrine:migrations:diff
php artisan doctrine:migrations:migrate
```
- Inspect generated migrations for schema changes (e.g., manufacturing_orders, production_steps tables).

Configure .env: Add Ozon API credentials:

OZON_API_KEY=your_api_key
OZON_API_SECRET=your_secret
OZON_WEBHOOK_URL=https://your-app.com/ozon/webhook

First Use Case: Trigger Manufacturing for an Order Use the package’s service class to start manufacturing:

use BaksDev\OzonManufacture\Facades\OzonManufacture;

$orderId = 'ozon_order_12345';
$result = OzonManufacture::startProduction($orderId);

if ($result->isSuccess()) {
    // Manufacturing initiated; check status later
} else {
    // Handle failure (e.g., order not found, API error)
}

Verify Webhook Setup (if applicable):
- Ensure your Laravel routes handle Ozon’s webhook payloads (e.g., POST /ozon/webhook).
- Test with Ozon’s sandbox environment first.

Implementation Patterns

Core Workflows

1. Order-Based Manufacturing

Pattern: Use the package’s facade or service class to kick off manufacturing for Ozon orders.

// Start production for a single order
OzonManufacture::startProduction($orderId);

// Bulk process orders (if supported)
OzonManufacture::bulkStartProduction([$orderId1, $orderId2]);

Integration Tip: Hook into Laravel’s orders.placed event to auto-trigger manufacturing:

Event::listen(OrderPlaced::class, function ($event) {
    OzonManufacture::startProduction($event->order->ozon_id);
});

2. Production Status Tracking

Pattern: Query the manufacturing status via the package’s API:

$status = OzonManufacture::getProductionStatus($orderId);
// $status->currentStep, $status->isCompleted, $status->errors

Integration Tip: Poll statuses in a scheduled job (e.g., every 5 minutes):

// app/Console/Commands/CheckManufacturingStatus.php
public function handle() {
    $pendingOrders = Order::where('manufacturing_status', 'pending')->get();
    foreach ($pendingOrders as $order) {
        $status = OzonManufacture::getProductionStatus($order->ozon_id);
        if ($status->isCompleted()) {
            $order->update(['manufacturing_status' => 'completed']);
        }
    }
}

3. Webhook-Driven Updates

Pattern: Handle Ozon’s webhook payloads to update manufacturing status in real-time.

// routes/web.php
Route::post('/ozon/webhook', [OzonWebhookController::class, 'handle']);

// app/Http/Controllers/OzonWebhookController.php
public function handle(Request $request) {
    $payload = $request->json()->all();
    OzonManufacture::handleWebhook($payload);
}

Integration Tip: Validate webhook signatures (if Ozon provides HMAC) and log payloads for debugging.

4. Error Handling and Retries

Pattern: Use Laravel’s queue system to retry failed manufacturing jobs:

// Configure in config/ozon-manufacture.php
'queue' => [
    'driver' => 'database',
    'retry_after' => 60, // seconds
];

// Dispatch a job with retry logic
OzonManufacture::dispatchProductionJob($orderId);

Integration Tip: Extend the package’s job class to add custom retry logic or notifications:

OzonManufacture::failed(function ($job, $exception) {
    // Send Slack/email alert
    Notification::route('mail', 'team@example.com')
                ->notify(new ManufacturingFailed($exception));
});

Advanced Patterns

1. Custom Manufacturing Rules

Pattern: Override default manufacturing logic by extending the package’s services.

// app/Services/CustomOzonManufacture.php
use BaksDev\OzonManufacture\Services\OzonManufacture as BaseOzonManufacture;

class CustomOzonManufacture extends BaseOzonManufacture {
    public function startProduction($orderId) {
        // Add custom validation
        if (!$this->isOrderEligible($orderId)) {
            throw new \Exception("Order not eligible for manufacturing");
        }
        return parent::startProduction($orderId);
    }

    protected function isOrderEligible($orderId) {
        // Your custom logic
        return true;
    }
}

Integration Tip: Bind your custom service in AppServiceProvider:

$this->app->bind(
    \BaksDev\OzonManufacture\Contracts\OzonManufacture::class,
    \App\Services\CustomOzonManufacture::class
);

2. Multi-Step Production Workflows

Pattern: Define custom production steps by extending the package’s step models.

// app/Models/CustomProductionStep.php
use BaksDev\OzonManufacture\Models\ProductionStep;

class CustomProductionStep extends ProductionStep {
    protected $customAttribute = 'value';

    // Add custom logic for step transitions
}

Integration Tip: Use Laravel’s model events to hook into step changes:
```
ProductionStep::observe(CustomProductionStepObserver::class);
```

3. Testing Manufacturing Workflows

Pattern: Use the package’s PHPUnit group to run tests:
```
php artisan test --group=ozon-manufacture
```

Integration Tip: Write integration tests for your custom workflows:

public function test_custom_manufacturing_workflow() {
    $order = Order::factory()->create(['ozon_id' => 'test_123']);
    $this->actingAs(user())
         ->post('/ozon/webhook', ['event' => 'order.received'])
         ->assertOk();

    $this->assertDatabaseHas('production_steps', [
        'order_id' => $order->id,
        'step' => 'cutting',
    ]);
}

Gotchas and Tips

Pitfalls

Ozon API Rate Limits:

Gotcha: The package may not handle rate limits gracefully by default. Monitor API responses for 429 Too Many Requests.

Fix: Implement exponential backoff in your custom service layer:

use Symfony\Component\HttpClient\RetryableHttpClient;

$client = new RetryableHttpClient(
    $baseClient,
    [
        'max_retries' => 3,
        'delay' => 1000, // ms
        'multiplier' => 2,
        'max_delay' => 5000,
    ]
);

Database Locking:
- Gotcha: Concurrent manufacturing jobs may cause deadlocks on shared tables (e.g., production_steps).
- Fix: Use database transactions with appropriate isolation levels:
```
DB::transaction(function () use ($orderId) {
    OzonManufacture::startProduction($orderId);
}, 5); // Retry 5 times on deadlock
```

Webhook Idempotency:

Gotcha: Ozon may retry webhook deliveries. The package might process the same payload multiple times.

Fix: Add idempotency checks in your webhook handler:

public function handle(Request $request) {
    $payload = $request->json()->all();
    $signature = $request->header('X-Ozon-Signature');

    if (!$this->verifySignature($payload, $signature)) {
        abort(403);
    }

    $eventId = $payload['event_id'];
    if (WebhookLog::where('event_id', $eventId)->exists()) {
        return response()->json(['status' => 'already_processed']);
    }

    OzonManufacture::handleWebhook($payload);
    WebhookLog::create(['event_id' => $eventId]);
}

Ozon Manufacture Laravel Package