Getting Started

Minimal Steps to First Use

Install the Package
```
composer require baks-dev/avito-orders
```

Set Up Required Profiles and Delivery Methods Run these commands based on your Avito integration model:

For FBS (Fulfillment by Avito):

php artisan baks:users-profile-type:avito-fbs
php artisan baks:payment:avito-fbs
php artisan baks:delivery:avito-fbs

For DBS (Delivery by Avito):

php artisan baks:users-profile-type:avito-dbs
php artisan baks:payment:avito-dbs
php artisan baks:delivery:avito-dbs

Verify Installation Check the database for new tables related to Avito profiles, payments, and deliveries. Run the provided tests to ensure functionality:
```
php artisan test --group=avito-orders
```

First Integration Use the package’s services to create or fetch an Avito order. Example:

use BaksDev\AvitoOrders\Services\AvitoOrderService;

$orderService = app(AvitoOrderService::class);
$order = $orderService->createOrder($avitoOrderData);

Implementation Patterns

Usage Patterns

Order Management

Create Orders: Use AvitoOrderService to handle order creation with Avito-specific logic.

$orderService = app(AvitoOrderService::class);
$order = $orderService->createOrder([
    'avito_order_id' => 'AV12345',
    'items' => [...],
    'delivery_method' => 'fbs',
]);

Update Order Status: Leverage the package’s status transitions (e.g., pending, shipped, delivered).
```
$orderService->updateOrderStatus($orderId, 'shipped');
```

Payment Workflows

Process Payments: Use the payment service to handle Avito-specific payment logic.

$paymentService = app(AvitoPaymentService::class);
$payment = $paymentService->processPayment($orderId, $amount);

Refunds: Implement refund logic via the payment service.
```
$paymentService->refundPayment($paymentId, $amount);
```

Delivery Workflows

FBS (Fulfillment by Avito): Use the delivery service to manage warehouse fulfillment.

$deliveryService = app(AvitoDeliveryService::class);
$delivery = $deliveryService->fulfillOrder($orderId, 'fbs_warehouse_id');

DBS (Delivery by Avito): Handle direct-to-consumer deliveries.
```
$deliveryService->shipOrder($orderId, $trackingNumber);
```

Profile Management

User Profiles: Attach Avito-specific profiles to users.

$profileService = app(AvitoProfileService::class);
$profile = $profileService->createProfile($userId, 'avito_fbs');

Workflows

Order Lifecycle
- Creation: Triggered by Avito webhook or manual input.
- Status Updates: Automated via Avito API or manual intervention.
- Completion: Marked as delivered and close the order.
Payment Lifecycle
- Capture: Process payment upon order confirmation.
- Refund: Handle refunds via Avito’s payment system.
- Disputes: Log and resolve payment disputes.
Delivery Lifecycle
- FBS: Sync with Avito’s warehouse system for fulfillment.
- DBS: Manage shipping labels and carrier integrations.

Integration Tips

Laravel Service Container Bind the package’s services to Laravel’s container in a service provider:

public function register()
{
    $this->app->bind(
        \BaksDev\AvitoOrders\Services\AvitoOrderService::class,
        fn($app) => new \BaksDev\AvitoOrders\Services\AvitoOrderService(
            $app->make(\BaksDev\Core\Database\Connection::class)
        )
    );
}

Event Listeners Extend the package’s events for custom logic. Example:

use BaksDev\AvitoOrders\Events\OrderCreated;

public function handle(OrderCreated $event)
{
    // Custom logic after order creation
    Log::info('Avito order created: ' . $event->order->id);
}

Queue Jobs Offload long-running tasks (e.g., delivery processing) to Laravel queues:

use BaksDev\AvitoOrders\Jobs\ProcessDelivery;

ProcessDelivery::dispatch($orderId)->onQueue('avito');

API Integration Use Laravel’s HTTP client to interact with Avito’s API if the package doesn’t cover specific endpoints:
```
$response = Http::withToken($avitoToken)
    ->post('https://api.avito.ru/orders', $orderData);
```

Gotchas and Tips

Pitfalls

Symfony Dependency Conflicts
- The package relies on Symfony components (e.g., Console, HttpKernel). Ensure your Laravel project can handle these dependencies without conflicts.
- Fix: Use spatie/laravel-symfony or manually resolve conflicts in composer.json.
Database Schema Mismatches
- The package introduces Avito-specific tables. Ensure your Laravel migrations don’t conflict with these.
- Fix: Run Avito migrations after your Laravel migrations or use a separate database schema.
Artisan Command Conflicts
- The package registers Symfony-style commands. Laravel’s Artisan may not handle them natively.
- Fix: Override the command registration in a Laravel service provider or use a custom facade.
PHP Version Requirements
- The package requires PHP 8.4+. Ensure your Laravel environment meets this requirement.
- Fix: Upgrade to Laravel 11+ (PHP 8.3+) or 12+ (PHP 8.4+).
Testing Gaps
- The package’s tests are PHPUnit-based but may not cover Laravel-specific scenarios.
- Fix: Write additional tests for Laravel integrations (e.g., queue jobs, event listeners).

Debugging

Log Avito-Specific Events Enable logging for Avito-related events to trace issues:
```
\BaksDev\AvitoOrders\Logging\AvitoLogger::enable();
```
Check Command Output Run Avito commands with verbose output to diagnose issues:
```
php artisan baks:delivery:avito-fbs --verbose
```
Validate API Responses If the package interacts with Avito’s API, log responses for debugging:
```
Http::withOptions(['debug' => true])->post(...);
```

Database Transactions Wrap Avito operations in transactions to avoid partial updates:

DB::transaction(function () use ($orderService) {
    $order = $orderService->createOrder($data);
});

Config Quirks

Configuration Files The package may expect a specific config structure. Override it in Laravel’s config directory:

// config/avito-orders.php
return [
    'api_token' => env('AVITO_API_TOKEN'),
    'webhook_secret' => env('AVITO_WEBHOOK_SECRET'),
];

Environment Variables Ensure all required environment variables are set (e.g., AVITO_API_TOKEN, AVITO_WEBHOOK_URL).

Service Binding Overrides Override default service bindings if needed:

$this->app->bind(
    \BaksDev\AvitoOrders\Services\AvitoOrderService::class,
    fn($app) => new CustomAvitoOrderService($app->make(\BaksDev\Core\Database\Connection::class))
);

Extension Points

Custom Order Models Extend the package’s order model to add custom fields:

class AvitoOrder extends \BaksDev\AvitoOrders\Models\Order
{
    protected $casts = [
        'custom_field' => 'string',
    ];
}

Webhook Handlers Extend the package’s webhook logic to handle custom payloads:

use BaksDev\AvitoOrders\Events\WebhookReceived;

public function handle(WebhookReceived $event)
{
    if ($event->payload['type'] === 'custom_event') {
        // Handle custom event
    }
}

Delivery Methods Add custom delivery methods beyond FBS/DBS:
```
$deliveryService->registerDeliveryMethod('custom
```

Avito Orders Laravel Package