This commit is contained in:
2026-09-15 10:35:56 +08:00
commit 782f8ea7aa
4086 changed files with 631288 additions and 0 deletions
@@ -0,0 +1,25 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Api;
class ApiException extends \RuntimeException
{
public function __construct(
string $message,
private readonly string $errorCode = '',
private readonly array $response = []
) {
parent::__construct($message);
}
public function getErrorCode(): string
{
return $this->errorCode;
}
public function getResponse(): array
{
return $this->response;
}
}
@@ -0,0 +1,63 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Api;
use Esun\LingxingErp\Model\Config;
use Magento\Framework\HTTP\Client\CurlFactory;
class Client
{
public function __construct(
private readonly Config $config,
private readonly TokenProvider $tokenProvider,
private readonly Signer $signer,
private readonly CurlFactory $curlFactory
) {
}
public function post(string $path, array $businessParameters): array
{
$this->config->assertCredentialsReady();
$token = $this->tokenProvider->getAccessToken();
$timestamp = time();
$public = [
'access_token' => $token,
'timestamp' => $timestamp,
'app_key' => $this->config->getAppId(),
];
$signedParameters = array_merge($businessParameters, $public);
$query = $public + ['sign' => $this->signer->sign($signedParameters, $this->config->getAppId())];
$url = $this->config->getApiBaseUrl() . '/' . ltrim($path, '/') . '?' . http_build_query(
$query,
'',
'&',
PHP_QUERY_RFC3986
);
$curl = $this->curlFactory->create();
$curl->setTimeout(30);
$curl->addHeader('Content-Type', 'application/json');
$curl->addHeader('X-HTTP-Method-Override', 'POST');
$curl->post($url, (string)json_encode($signedParameters, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR));
$response = $this->decodeResponse($curl->getBody());
if ($curl->getStatus() < 200 || $curl->getStatus() >= 300 || (int)($response['code'] ?? -1) !== 0) {
throw new ApiException(
(string)($response['message'] ?? $response['msg'] ?? 'Lingxing API request failed.'),
(string)($response['code'] ?? $curl->getStatus()),
$response
);
}
return $response;
}
private function decodeResponse(string $body): array
{
try {
$decoded = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
} catch (\JsonException $exception) {
throw new ApiException('Lingxing returned invalid JSON: ' . $exception->getMessage(), 'invalid_json');
}
return is_array($decoded) ? $decoded : [];
}
}
@@ -0,0 +1,30 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Api;
class Endpoint
{
public const STORE_LIST = '/pb/mp/shop/v2/getSellerList';
public const ORDER_CREATE = '/pb/mp/order/v2/create';
public const ORDER_LIST = '/pb/mp/order/v2/list';
public const PAIR_LIST = '/pb/mp/listing/v2/getPairList';
public const WMS_ORDER_LIST = '/erp/sc/routing/wms/order/wmsOrderList';
public const WAREHOUSE_LIST = '/erp/sc/data/local_inventory/warehouse';
public const INVENTORY_DETAILS = '/erp/sc/routing/data/local_inventory/inventoryDetails';
private const BY_OPERATION = [
'store_sync' => self::STORE_LIST,
'order_create' => self::ORDER_CREATE,
'sku_pair_lookup' => self::PAIR_LIST,
'shipment_pull' => self::WMS_ORDER_LIST,
'warehouse_sync' => self::WAREHOUSE_LIST,
'inventory_pull' => self::INVENTORY_DETAILS,
'inventory_sync' => self::INVENTORY_DETAILS,
];
public static function forOperation(string $operation): string
{
return self::BY_OPERATION[$operation] ?? '';
}
}
@@ -0,0 +1,52 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Api;
class Signer
{
public function sign(array $parameters, string $appId): string
{
ksort($parameters);
$pairs = [];
foreach ($parameters as $key => $value) {
if (is_array($value)) {
$value = $this->removeNullArrayValues($value);
$pairs[] = $key . '=' . json_encode(
$value,
JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR
);
continue;
}
if ($value === '') {
continue;
}
if (is_bool($value)) {
$value = $value ? 'true' : 'false';
} elseif ($value === null) {
$value = 'null';
}
$pairs[] = $key . '=' . $value;
}
// phpcs:ignore Magento2.Security.InsecureFunction.FoundWithAlternative -- Required by Lingxing's protocol.
$md5 = strtoupper(md5(implode('&', $pairs)));
$encrypted = openssl_encrypt($md5, 'AES-128-ECB', $appId, OPENSSL_RAW_DATA);
if ($encrypted === false) {
throw new \RuntimeException('Unable to generate Lingxing request signature.');
}
return base64_encode($encrypted);
}
private function removeNullArrayValues(array $value): array
{
foreach ($value as $key => $item) {
if (is_array($item)) {
$value[$key] = $this->removeNullArrayValues($item);
} elseif ($item === null) {
unset($value[$key]);
}
}
return $value;
}
}
@@ -0,0 +1,107 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Api;
use Esun\LingxingErp\Model\Config;
use Magento\Framework\App\CacheInterface;
use Magento\Framework\HTTP\Client\CurlFactory;
use Magento\Framework\Lock\LockManagerInterface;
class TokenProvider
{
private const CACHE_KEY = 'esun_lingxing_access_token';
private const LOCK_NAME = 'esun_lingxing_access_token_lock';
public function __construct(
private readonly Config $config,
private readonly CacheInterface $cache,
private readonly CurlFactory $curlFactory,
private readonly LockManagerInterface $lockManager
) {
}
public function getAccessToken(): string
{
$cached = $this->loadCached();
if ($cached !== null) {
return $cached;
}
if (!$this->lockManager->lock(self::LOCK_NAME, 10)) {
throw new ApiException('Another process is refreshing the Lingxing access token.', 'token_locked');
}
try {
$cached = $this->loadCached();
return $cached ?? $this->generateToken();
} finally {
$this->lockManager->unlock(self::LOCK_NAME);
}
}
public function invalidate(): void
{
$this->cache->remove(self::CACHE_KEY);
}
private function loadCached(): ?string
{
$raw = $this->cache->load(self::CACHE_KEY);
if (!is_string($raw) || $raw === '') {
return null;
}
try {
$data = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
} catch (\JsonException) {
return null;
}
if (empty($data['access_token']) || (int)($data['expires_at'] ?? 0) <= time() + 120) {
return null;
}
return (string)$data['access_token'];
}
private function generateToken(): string
{
$this->config->assertCredentialsReady();
$url = $this->config->getApiBaseUrl() . '/api/auth-server/oauth/access-token?' . http_build_query([
'appId' => $this->config->getAppId(),
'appSecret' => $this->config->getAppSecret(),
], '', '&', PHP_QUERY_RFC3986);
$curl = $this->curlFactory->create();
$curl->setTimeout(20);
$curl->post($url, '');
$response = $this->decodeResponse($curl->getBody());
$businessCode = (string)($response['code'] ?? '');
if ($curl->getStatus() < 200 || $curl->getStatus() >= 300
|| !in_array($businessCode, ['0', '200'], true)
) {
throw new ApiException(
(string)($response['message'] ?? $response['msg'] ?? 'Unable to obtain Lingxing access token.'),
(string)($response['code'] ?? $curl->getStatus()),
$response
);
}
$data = is_array($response['data'] ?? null) ? $response['data'] : [];
$token = (string)($data['access_token'] ?? '');
if ($token === '') {
throw new ApiException('Lingxing token response did not include access_token.', 'invalid_token_response');
}
$expiresIn = max(300, (int)($data['expires_in'] ?? 3600));
$this->cache->save((string)json_encode([
'access_token' => $token,
'expires_at' => time() + $expiresIn,
], JSON_THROW_ON_ERROR), self::CACHE_KEY, [], $expiresIn);
return $token;
}
private function decodeResponse(string $body): array
{
try {
$decoded = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
} catch (\JsonException $exception) {
throw new ApiException('Lingxing returned invalid JSON: ' . $exception->getMessage(), 'invalid_json');
}
return is_array($decoded) ? $decoded : [];
}
}
+169
View File
@@ -0,0 +1,169 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model;
use Magento\Framework\App\Config\ScopeConfigInterface;
use Magento\Framework\Encryption\EncryptorInterface;
use Magento\Store\Model\ScopeInterface;
class Config
{
private const BASE = 'esun_lingxing/';
public function __construct(
private readonly ScopeConfigInterface $scopeConfig,
private readonly EncryptorInterface $encryptor
) {
}
public function isEnabled(): bool
{
return $this->scopeConfig->isSetFlag(self::BASE . 'general/enabled');
}
public function getApiBaseUrl(): string
{
return rtrim((string)$this->scopeConfig->getValue(self::BASE . 'general/api_base_url'), '/');
}
public function getAppId(): string
{
return trim((string)$this->scopeConfig->getValue(self::BASE . 'general/app_id'));
}
public function getAppSecret(): string
{
$value = (string)$this->scopeConfig->getValue(self::BASE . 'general/app_secret');
return $value !== '' ? (string)$this->encryptor->decrypt($value) : '';
}
public function getPlatformCode(int $websiteId): int
{
return $this->getStoreMapping($websiteId)['platform_code'];
}
public function getLingxingStoreId(int $websiteId): string
{
return $this->getStoreMapping($websiteId)['store_id'];
}
public function getWarehouseId(int $websiteId = 0): string
{
return trim((string)$this->getWebsiteValue('general/warehouse_id', $websiteId));
}
public function getLogisticsTypeId(int $websiteId = 0): string
{
return trim((string)$this->getWebsiteValue('general/logistics_type_id', $websiteId));
}
/** @return string[] */
public function getEligibleStatuses(): array
{
$value = (string)$this->scopeConfig->getValue(self::BASE . 'general/eligible_statuses');
return array_values(array_filter(array_map('trim', explode(',', $value))));
}
public function getOrderBatchSize(): int
{
return min(100, max(1, (int)$this->scopeConfig->getValue(self::BASE . 'orders/batch_size')));
}
public function getOrderMaxAttempts(): int
{
return min(50, max(1, (int)$this->scopeConfig->getValue(self::BASE . 'orders/max_attempts')));
}
public function getStockDeductionType(): int
{
return (int)$this->scopeConfig->getValue(self::BASE . 'orders/stock_deduction_type') === 2 ? 2 : 1;
}
public function getShipmentPageSize(): int
{
return min(200, max(1, (int)$this->scopeConfig->getValue(self::BASE . 'shipments/page_size')));
}
public function getShipmentMaxPages(): int
{
return min(100, max(1, (int)$this->scopeConfig->getValue(self::BASE . 'shipments/max_pages')));
}
public function getShipmentMaxAttempts(): int
{
return min(50, max(1, (int)$this->scopeConfig->getValue(self::BASE . 'shipments/max_attempts')));
}
public function shouldNotifyCustomer(): bool
{
return $this->scopeConfig->isSetFlag(self::BASE . 'shipments/notify_customer');
}
public function isSkuSyncEnabled(): bool
{
return $this->scopeConfig->isSetFlag(self::BASE . 'sku_sync/enabled');
}
public function getSkuSyncPageSize(): int
{
return min(200, max(1, (int)$this->scopeConfig->getValue(self::BASE . 'sku_sync/page_size')));
}
public function getSuccessLogRetentionDays(): int
{
return min(365, max(1, (int)$this->scopeConfig->getValue(self::BASE . 'logging/success_retention_days')));
}
public function getErrorLogRetentionDays(): int
{
return min(730, max(1, (int)$this->scopeConfig->getValue(self::BASE . 'logging/error_retention_days')));
}
public function hasStoreMapping(int $websiteId): bool
{
$mapping = $this->getStoreMapping($websiteId);
return $mapping['platform_code'] > 0 && $mapping['store_id'] !== '';
}
public function assertCredentialsReady(): void
{
if ($this->getApiBaseUrl() === '' || $this->getAppId() === '' || $this->getAppSecret() === '') {
throw new \RuntimeException('Lingxing API base URL, App ID and App Secret must be configured.');
}
}
public function assertOrderMappingReady(int $websiteId): void
{
$mapping = $this->getStoreMapping($websiteId);
if ($mapping['platform_code'] <= 0 || $mapping['store_id'] === '') {
throw new \RuntimeException(sprintf(
'No Lingxing store is configured for Magento Website ID %d.',
$websiteId
));
}
if (($this->getWarehouseId($websiteId) === '') !== ($this->getLogisticsTypeId($websiteId) === '')) {
throw new \RuntimeException('Lingxing warehouse and logistics type must either both be set or both be blank.');
}
}
/** @return array{platform_code:int, store_id:string} */
private function getStoreMapping(int $websiteId): array
{
$value = trim((string)$this->scopeConfig->getValue(
self::BASE . 'general/store_mapping',
ScopeInterface::SCOPE_WEBSITE,
$websiteId
));
[$platformCode, $storeId] = array_pad(explode('|', $value, 2), 2, '');
return ['platform_code' => max(0, (int)$platformCode), 'store_id' => trim($storeId)];
}
private function getWebsiteValue(string $path, int $websiteId): mixed
{
if ($websiteId <= 0) {
return $this->scopeConfig->getValue(self::BASE . $path);
}
return $this->scopeConfig->getValue(self::BASE . $path, ScopeInterface::SCOPE_WEBSITE, $websiteId);
}
}
@@ -0,0 +1,89 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Inventory;
use Esun\LingxingErp\Model\Api\ApiException;
use Esun\LingxingErp\Model\Api\Client;
use Esun\LingxingErp\Model\Api\Endpoint;
use Esun\LingxingErp\Model\Sync\LogWriter;
class InventoryFetcher
{
/**
* Lingxing API documentation:
* https://apidoc.lingxing.com/#/docs/Warehouse/InventoryDetails
*/
private const PAGE_SIZE = 800;
public function __construct(
private readonly Client $client,
private readonly LogWriter $logWriter
) {
}
/** @return array<int, array<string, mixed>> */
public function fetchAll(int $wid): array
{
$inventory = [];
$offset = 0;
do {
$request = [
'wid' => (string)$wid,
'offset' => $offset,
'length' => self::PAGE_SIZE,
];
$started = microtime(true);
$response = [];
try {
$response = $this->client->post(Endpoint::INVENTORY_DETAILS, $request);
$rows = $response['data'] ?? null;
if (!is_array($rows)) {
throw new \RuntimeException('Lingxing inventory response is missing data.');
}
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'inventory_pull',
'entity_type' => 'inventory',
'external_id' => (string)$wid,
'status' => 'success',
'attempt_number' => 1,
'request_id' => (string)($response['request_id'] ?? ''),
'request_payload' => $request,
'response_payload' => $response,
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
} catch (\Throwable $exception) {
$apiResponse = $exception instanceof ApiException ? $exception->getResponse() : $response;
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'inventory_pull',
'entity_type' => 'inventory',
'external_id' => (string)$wid,
'status' => 'failed',
'attempt_number' => 1,
'error_code' => $exception instanceof ApiException
? $exception->getErrorCode()
: (string)$exception->getCode(),
'error_message' => $exception->getMessage(),
'request_id' => (string)($apiResponse['request_id'] ?? ''),
'request_payload' => $request,
'response_payload' => $apiResponse,
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
throw $exception;
}
foreach ($rows as $row) {
if (is_array($row)) {
$inventory[] = $row;
}
}
$received = count($rows);
$offset += $received;
$total = max(0, (int)($response['total'] ?? $offset));
} while ($received > 0 && $offset < $total);
return $inventory;
}
}
@@ -0,0 +1,178 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Inventory;
use Esun\LingxingErp\Model\Sku\ProductErpSkuRepository;
use Esun\LingxingErp\Model\Sync\LogWriter;
use Esun\LingxingErp\Model\Warehouse\WarehouseRepository;
use Magento\Framework\Lock\LockManagerInterface;
use Magento\InventoryApi\Api\Data\SourceItemInterface;
use Magento\InventoryApi\Api\Data\SourceItemInterfaceFactory;
use Magento\InventoryApi\Api\SourceItemsSaveInterface;
class InventorySynchronizer
{
private const LOCK_NAME = 'esun_lingxing_inventory_sync';
private const SAVE_BATCH_SIZE = 500;
public function __construct(
private readonly WarehouseRepository $warehouseRepository,
private readonly InventoryFetcher $fetcher,
private readonly ProductErpSkuRepository $productErpSkuRepository,
private readonly SourceItemInterfaceFactory $sourceItemFactory,
private readonly SourceItemsSaveInterface $sourceItemsSave,
private readonly LogWriter $logWriter,
private readonly LockManagerInterface $lockManager
) {
}
/** @return array{warehouses:int,items:int,unmapped:int,errors:array<int, string>} */
public function synchronizeAll(): array
{
if (!$this->lockManager->lock(self::LOCK_NAME, 0)) {
throw new \RuntimeException('Inventory synchronization is already running.');
}
$summary = ['warehouses' => 0, 'items' => 0, 'unmapped' => 0, 'errors' => []];
try {
foreach ($this->warehouseRepository->getInventoryTargets() as $warehouse) {
$wid = (int)$warehouse['wid'];
$started = microtime(true);
try {
$result = $this->synchronizeWarehouse($warehouse);
$summary['warehouses']++;
$summary['items'] += $result['items'];
$summary['unmapped'] += $result['unmapped'];
$this->warehouseRepository->markInventorySynchronized($wid);
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'inventory_sync',
'entity_type' => 'inventory',
'external_id' => (string)$wid,
'status' => 'success',
'attempt_number' => 1,
'request_payload' => [
'wid' => $wid,
'source_code' => (string)$warehouse['source_code'],
'quantity_field' => 'product_valid_num',
],
'response_payload' => $result,
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
} catch (\Throwable $exception) {
$summary['errors'][$wid] = $exception->getMessage();
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'inventory_sync',
'entity_type' => 'inventory',
'external_id' => (string)$wid,
'status' => 'failed',
'attempt_number' => 1,
'error_code' => (string)$exception->getCode(),
'error_message' => $exception->getMessage(),
'request_payload' => [
'wid' => $wid,
'source_code' => (string)$warehouse['source_code'],
'quantity_field' => 'product_valid_num',
],
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
}
}
} finally {
$this->lockManager->unlock(self::LOCK_NAME);
}
return $summary;
}
/**
* @param array<string, mixed> $warehouse
* @return array{items:int,unmapped:int,zeroed:int,preserved_without_erp_sku:int,unmapped_erp_skus:string[]}
*/
private function synchronizeWarehouse(array $warehouse): array
{
$wid = (int)$warehouse['wid'];
$sourceCode = (string)$warehouse['source_code'];
$websiteIds = $this->warehouseRepository->getWebsiteIdsForSource($sourceCode);
if ($websiteIds === []) {
throw new \RuntimeException(sprintf(
'Magento Source "%s" is not assigned to a Stock with a Website sales channel.',
$sourceCode
));
}
$rows = $this->fetcher->fetchAll($wid);
$quantitiesBySku = [];
$unmapped = [];
foreach ($rows as $row) {
$erpSku = trim((string)($row['sku'] ?? ''));
if ($erpSku === '') {
continue;
}
$magentoSkus = $this->resolveMagentoSkus($websiteIds, $erpSku);
if ($magentoSkus === []) {
$unmapped[$erpSku] = true;
continue;
}
$quantity = max(0.0, (float)($row['product_valid_num'] ?? 0));
foreach ($magentoSkus as $magentoSku) {
// The customer accepts that every Magento SKU paired to the ERP SKU receives the full ERP quantity.
$quantitiesBySku[$magentoSku] = $quantity;
}
}
$existingSkus = $this->warehouseRepository->getExistingSourceItemSkus($sourceCode);
$mappedSkus = $this->getMappedMagentoSkus($websiteIds);
$zeroCandidates = array_values(array_intersect($existingSkus, $mappedSkus));
$preservedWithoutErpSku = array_values(array_diff($existingSkus, $mappedSkus));
$zeroed = array_values(array_diff($zeroCandidates, array_keys($quantitiesBySku)));
foreach ($zeroed as $sku) {
$quantitiesBySku[$sku] = 0.0;
}
$sourceItems = [];
foreach ($quantitiesBySku as $sku => $quantity) {
$sourceItem = $this->sourceItemFactory->create();
$sourceItem->setSourceCode($sourceCode);
$sourceItem->setSku($sku);
$sourceItem->setQuantity($quantity);
$sourceItem->setStatus($quantity > 0
? SourceItemInterface::STATUS_IN_STOCK
: SourceItemInterface::STATUS_OUT_OF_STOCK);
$sourceItems[] = $sourceItem;
}
foreach (array_chunk($sourceItems, self::SAVE_BATCH_SIZE) as $batch) {
$this->sourceItemsSave->execute($batch);
}
return [
'items' => count($quantitiesBySku),
'unmapped' => count($unmapped),
'zeroed' => count($zeroed),
'preserved_without_erp_sku' => count($preservedWithoutErpSku),
'unmapped_erp_skus' => array_slice(array_keys($unmapped), 0, 200),
];
}
/** @param int[] $websiteIds */
private function resolveMagentoSkus(array $websiteIds, string $erpSku): array
{
$matches = [];
foreach ($websiteIds as $websiteId) {
foreach ($this->productErpSkuRepository->findMskusByErpSku($websiteId, $erpSku) as $sku) {
$matches[$sku] = true;
}
}
return array_map('strval', array_keys($matches));
}
/** @param int[] $websiteIds @return string[] */
private function getMappedMagentoSkus(array $websiteIds): array
{
$mapped = [];
foreach ($websiteIds as $websiteId) {
foreach ($this->productErpSkuRepository->getWebsiteProductSkusWithErpSku($websiteId) as $sku) {
$mapped[$sku] = true;
}
}
return array_map('strval', array_keys($mapped));
}
}
@@ -0,0 +1,56 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Order;
use Magento\Framework\App\RequestInterface;
use Magento\Framework\App\State;
class CancellationSourceResolver
{
public const CUSTOMER = 'customer';
public const SCHEDULED_TASK = 'scheduled_task';
public const ADMINISTRATOR = 'administrator';
public const SYSTEM = 'system';
public function __construct(
private readonly State $appState,
private readonly RequestInterface $request
) {
}
public function resolve(): string
{
$areaCode = '';
try {
$areaCode = $this->appState->getAreaCode();
} catch (\Throwable) {
// Some programmatic cancellations run before an area is initialized.
}
if ($areaCode === 'crontab') {
return self::SCHEDULED_TASK;
}
$fullActionName = method_exists($this->request, 'getFullActionName')
? (string)$this->request->getFullActionName()
: '';
if ($fullActionName === 'esun_customer_order_cancel') {
return self::CUSTOMER;
}
if ($areaCode === 'adminhtml') {
return self::ADMINISTRATOR;
}
return self::SYSTEM;
}
public function getComment(string $source): string
{
return match ($source) {
self::CUSTOMER => 'The customer canceled this order from their account.',
self::SCHEDULED_TASK => 'A scheduled task canceled this order automatically.',
self::ADMINISTRATOR => 'An administrator canceled this order.',
default => 'A system process canceled this order.',
};
}
}
@@ -0,0 +1,88 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Order;
use Esun\LingxingErp\Model\Api\ApiException;
use Esun\LingxingErp\Model\Api\Client;
use Esun\LingxingErp\Model\Api\Endpoint;
use Esun\LingxingErp\Model\Config;
use Magento\Sales\Api\Data\OrderInterface;
use Magento\Store\Model\StoreManagerInterface;
class OrderExporter
{
public function __construct(
private readonly Client $client,
private readonly Config $config,
private readonly OrderPayloadBuilder $payloadBuilder,
private readonly StoreManagerInterface $storeManager
) {
}
public function export(OrderInterface $order, ?array $payload = null): array
{
$payload ??= $this->payloadBuilder->build($order);
$websiteId = (int)$this->storeManager->getStore((int)$order->getStoreId())->getWebsiteId();
try {
$response = $this->client->post(Endpoint::ORDER_CREATE, $payload);
} catch (ApiException $exception) {
// The ERP may have committed the order even if the response was lost. Reconcile before retrying.
try {
$existing = $this->findExisting((string)$order->getIncrementId(), $websiteId);
} catch (\Throwable) {
throw $exception;
}
if ($existing !== null) {
return [
'payload' => $payload,
'response' => $exception->getResponse(),
'global_order_no' => $existing,
];
}
throw $exception;
}
$successes = $response['data']['success_details'] ?? [];
foreach (is_array($successes) ? $successes : [] as $success) {
if ((string)($success['platform_order_no'] ?? '') === (string)$order->getIncrementId()
&& (string)($success['global_order_no'] ?? '') !== '') {
return ['payload' => $payload, 'response' => $response, 'global_order_no' => (string)$success['global_order_no']];
}
}
$existing = $this->findExisting((string)$order->getIncrementId(), $websiteId);
if ($existing !== null) {
return ['payload' => $payload, 'response' => $response, 'global_order_no' => $existing];
}
$errors = $response['data']['error_details'] ?? [];
$message = is_array($errors) && $errors !== []
? implode('; ', array_filter(array_map(static fn(array $error): string => (string)($error['error_message'] ?? ''), $errors)))
: 'Lingxing did not return a success record for this order.';
throw new ApiException($message, 'order_not_created', $response);
}
private function findExisting(string $incrementId, int $websiteId): ?string
{
$response = $this->client->post(Endpoint::ORDER_LIST, [
'offset' => 0,
'length' => 20,
'store_id' => [$this->config->getLingxingStoreId($websiteId)],
'platform_code' => [$this->config->getPlatformCode($websiteId)],
'platform_order_nos' => [$incrementId],
]);
foreach (($response['data']['list'] ?? []) as $order) {
foreach (($order['platform_info'] ?? []) as $platformInfo) {
if ((string)($platformInfo['platform_order_no'] ?? '') === $incrementId) {
return (string)($order['global_order_no'] ?? '') ?: null;
}
}
foreach (($order['item_info'] ?? []) as $item) {
if ((string)($item['platform_order_no'] ?? '') === $incrementId) {
return (string)($order['global_order_no'] ?? '') ?: null;
}
}
}
return null;
}
}
@@ -0,0 +1,108 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Order;
use Esun\LingxingErp\Model\Config;
use Magento\Sales\Api\Data\OrderInterface;
use Magento\Store\Model\StoreManagerInterface;
class OrderPayloadBuilder
{
/**
* Lingxing API documentation:
* https://apidoc.lingxing.com/#/docs/hide/CreateOrdersV2.md
*/
public function __construct(
private readonly Config $config,
private readonly StoreManagerInterface $storeManager
) {
}
public function build(OrderInterface $order): array
{
$websiteId = (int)$this->storeManager->getStore((int)$order->getStoreId())->getWebsiteId();
$this->config->assertOrderMappingReady($websiteId);
$address = $order->getShippingAddress() ?: $order->getBillingAddress();
if ($address === null) {
throw new \RuntimeException('Magento order has no shipping or billing address.');
}
$items = [];
foreach ($order->getAllVisibleItems() as $item) {
if ($item->getIsVirtual()) {
continue;
}
$sku = trim((string)$item->getSku());
if ($sku === '') {
throw new \RuntimeException('Magento order item has an empty SKU.');
}
$items[] = [
'msku' => $sku,
'quantity' => (int)$item->getQtyOrdered(),
'unit_price' => (float)$item->getPrice(),
'stock_deduction_type' => $this->config->getStockDeductionType(),
];
}
if ($items === []) {
throw new \RuntimeException('Magento order has no physical SKU to export.');
}
$street = $address->getStreet();
$streetLines = array_values(array_filter(array_map(
static fn ($line): string => trim((string)$line),
is_array($street) ? $street : [(string)$street]
), static fn (string $line): bool => $line !== ''));
$receiverName = trim((string)$address->getFirstname() . ' ' . (string)$address->getLastname());
$buyerName = trim(implode(' ', array_filter([
trim((string)$order->getCustomerFirstname()),
trim((string)$order->getCustomerMiddlename()),
trim((string)$order->getCustomerLastname()),
], static fn (string $part): bool => $part !== '')));
$buyerEmail = trim((string)$order->getCustomerEmail());
if ($buyerEmail === '') {
$buyerEmail = trim((string)$address->getEmail());
}
$orderData = [
'platform_order_no' => (string)$order->getIncrementId(),
'receiver_country_code' => (string)$address->getCountryId(),
'customer_shipping_amount' => (float)$order->getShippingAmount(),
'customer_tax_amount' => (float)$order->getTaxAmount(),
'order_total_amount' => (float)$order->getGrandTotal(),
'global_purchase_time' => (new \DateTimeImmutable((string)$order->getCreatedAt(), new \DateTimeZone('UTC')))->getTimestamp(),
'receiver_name' => $receiverName,
'receiver_company_name' => (string)$address->getCompany(),
'city' => (string)$address->getCity(),
'address_line1' => $streetLines[0] ?? '',
'amount_currency' => (string)$order->getOrderCurrencyCode(),
'items' => $items,
];
$optionalAddressData = [
'state_or_region' => trim((string)$address->getRegion()),
'postal_code' => trim((string)$address->getPostcode()),
'address_line2' => $streetLines[1] ?? '',
'address_line3' => count($streetLines) > 2 ? implode(' ', array_slice($streetLines, 2)) : '',
'receiver_mobile' => trim((string)$address->getTelephone()),
'buyer_email' => $buyerEmail,
'buyer_name' => $buyerName !== '' ? $buyerName : $receiverName,
];
foreach ($optionalAddressData as $field => $value) {
if ($value !== '') {
$orderData[$field] = $value;
}
}
if ((string)$order->getCustomerNote() !== '') {
$orderData['buyer_note'] = (string)$order->getCustomerNote();
}
if ($this->config->getWarehouseId($websiteId) !== '') {
$orderData['wid'] = $this->config->getWarehouseId($websiteId);
$orderData['logistics_type_id'] = $this->config->getLogisticsTypeId($websiteId);
}
return [
'platform_code' => $this->config->getPlatformCode($websiteId),
'store_id' => $this->config->getLingxingStoreId($websiteId),
'orders' => [$orderData],
];
}
}
@@ -0,0 +1,23 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Product\Attribute\Backend;
use Magento\Eav\Model\Entity\Attribute\Backend\AbstractBackend;
/**
* Normalizes ERP SKU values.
*
* The class name is retained because installed attributes reference it. Multiple Magento SKUs are intentionally
* allowed to use the same ERP SKU within one Website.
*/
class WebsiteUnique extends AbstractBackend
{
public function beforeSave($object): self
{
$attributeCode = (string)$this->getAttribute()->getAttributeCode();
$value = trim((string)$object->getData($attributeCode));
$object->setData($attributeCode, $value);
return parent::beforeSave($object);
}
}
@@ -0,0 +1,41 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\ResourceModel\Log\Grid;
use Magento\Framework\App\RequestInterface;
use Magento\Framework\Data\Collection\Db\FetchStrategyInterface as FetchStrategy;
use Magento\Framework\Data\Collection\EntityFactoryInterface as EntityFactory;
use Magento\Framework\Event\ManagerInterface as EventManager;
use Magento\Framework\View\Element\UiComponent\DataProvider\SearchResult;
use Psr\Log\LoggerInterface as Logger;
class Collection extends SearchResult
{
public function __construct(
EntityFactory $entityFactory,
Logger $logger,
FetchStrategy $fetchStrategy,
EventManager $eventManager,
RequestInterface $request,
$mainTable = 'esun_lingxing_sync_log',
$resourceModel = null,
$identifierName = null,
$connectionName = null
) {
parent::__construct(
$entityFactory,
$logger,
$fetchStrategy,
$eventManager,
$mainTable,
$resourceModel,
$identifierName,
$connectionName
);
$filters = (array)$request->getParam('filters', []);
if (!isset($filters['status']) || trim((string)$filters['status']) === '') {
$this->addFieldToFilter('status', ['in' => ['failed', 'retrying']]);
}
}
}
@@ -0,0 +1,115 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Shipment;
class FulfillmentNormalizer
{
/**
* A Lingxing order can have multiple wo_number records. If package-level item quantities
* are present, each package becomes a Magento shipment; otherwise one outbound record
* becomes one shipment with all tracking numbers attached.
*/
public function normalize(array $outbound): array
{
$woNumber = (string)($outbound['wo_number'] ?? $outbound['woNumber'] ?? '');
if ($woNumber === '') {
throw new \RuntimeException('Lingxing outbound data is missing wo_number.');
}
$packages = $outbound['package_delivered_data'] ?? $outbound['packageDeliveredData'] ?? [];
if (is_array($packages) && count($packages) > 1 && $this->allPackagesHaveProducts($packages)) {
$result = [];
foreach (array_values($packages) as $index => $package) {
$packageNo = (string)($package['package_no'] ?? $package['packageNo'] ?? '');
$tracks = $this->extractTracks($package, $outbound);
$packageIdentity = $packageNo ?: (($tracks[0]['number'] ?? '') ?: (string)($index + 1));
$result[] = $this->makePayload(
$outbound,
$woNumber . '|' . $packageIdentity,
$packageNo,
$package['product_info'] ?? $package['productInfo'],
$tracks
);
}
return $result;
}
$tracks = $this->extractTracks($outbound);
foreach (is_array($packages) ? $packages : [] as $package) {
foreach ($this->extractTracks($package) as $track) {
$tracks[] = $track;
}
}
$tracks = $this->uniqueTracks($tracks);
return [$this->makePayload(
$outbound,
$woNumber,
(string)($outbound['package_no'] ?? $outbound['packageNo'] ?? ''),
$outbound['product_info'] ?? $outbound['productInfo'] ?? [],
$tracks
)];
}
private function allPackagesHaveProducts(array $packages): bool
{
foreach ($packages as $package) {
$products = $package['product_info'] ?? $package['productInfo'] ?? null;
if (!is_array($products) || $products === []) {
return false;
}
}
return true;
}
private function makePayload(array $outbound, string $externalKey, string $packageNo, array $products, array $tracks): array
{
$normalizedProducts = [];
foreach ($products as $product) {
$sku = trim((string)($product['sku'] ?? ''));
$quantity = (float)($product['count'] ?? $product['quantity'] ?? 0);
if ($sku === '' || $quantity <= 0 || (int)($product['bundle_type'] ?? 0) === 2) {
continue;
}
$normalizedProducts[] = ['erp_sku' => $sku, 'quantity' => $quantity];
}
return [
'external_key' => mb_substr($externalKey, 0, 191),
'global_order_no' => (string)($outbound['order_number'] ?? $outbound['orderNumber'] ?? ''),
'platform_order_nos' => array_values(array_filter((array)($outbound['platform_order_no'] ?? [$outbound['amazonOrderId'] ?? '']))),
'wo_id' => (int)($outbound['wo_id'] ?? $outbound['woId'] ?? 0),
'wid' => (int)($outbound['wid'] ?? $outbound['warehouse_id'] ?? $outbound['warehouseId'] ?? 0),
'wo_number' => (string)($outbound['wo_number'] ?? $outbound['woNumber'] ?? ''),
'package_no' => $packageNo,
'carrier' => (string)($outbound['logistics_provider_name'] ?? $outbound['actualCarrier'] ?? ''),
'products' => $normalizedProducts,
'tracks' => $this->uniqueTracks($tracks),
];
}
private function extractTracks(array $primary, array $fallback = []): array
{
$tracks = [];
foreach ([
$primary['tracking_no'] ?? $primary['trackingNo'] ?? '',
$primary['waybill_no'] ?? $primary['waybillNo'] ?? '',
] as $number) {
$number = trim((string)$number);
if ($number !== '') {
$tracks[] = ['number' => $number, 'title' => (string)($primary['logistics_provider_name'] ?? $primary['actualCarrier'] ?? $fallback['logistics_provider_name'] ?? 'Lingxing')];
}
}
return $tracks;
}
private function uniqueTracks(array $tracks): array
{
$result = [];
foreach ($tracks as $track) {
$number = trim((string)($track['number'] ?? ''));
if ($number !== '') {
$result[$number] = ['number' => $number, 'title' => (string)($track['title'] ?? 'Lingxing')];
}
}
return array_values($result);
}
}
@@ -0,0 +1,170 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Shipment;
use Esun\LingxingErp\Model\Config;
use Esun\LingxingErp\Model\Sku\ProductErpSkuRepository;
use Esun\LingxingErp\Model\Sync\OrderSyncRepository;
use Esun\LingxingErp\Model\Warehouse\WarehouseRepository;
use Magento\Sales\Api\Data\ShipmentCreationArgumentsExtensionInterfaceFactory;
use Magento\Sales\Api\Data\ShipmentCreationArgumentsInterfaceFactory;
use Magento\Sales\Api\Data\ShipmentItemCreationInterfaceFactory;
use Magento\Sales\Api\Data\ShipmentTrackCreationInterfaceFactory;
use Magento\Sales\Api\OrderRepositoryInterface;
use Magento\Sales\Api\ShipOrderInterface;
use Magento\Store\Model\StoreManagerInterface;
class ShipmentImporter
{
public function __construct(
private readonly OrderSyncRepository $orderSyncRepository,
private readonly OrderRepositoryInterface $orderRepository,
private readonly ShipmentItemCreationInterfaceFactory $itemFactory,
private readonly ShipmentTrackCreationInterfaceFactory $trackFactory,
private readonly ShipOrderInterface $shipOrder,
private readonly Config $config,
private readonly ProductErpSkuRepository $productErpSkuRepository,
private readonly StoreManagerInterface $storeManager,
private readonly WarehouseRepository $warehouseRepository,
private readonly ShipmentCreationArgumentsInterfaceFactory $shipmentArgumentsFactory,
private readonly ShipmentCreationArgumentsExtensionInterfaceFactory $shipmentArgumentsExtensionFactory
) {
}
public function import(array $payload): array
{
$mapping = null;
if ((string)($payload['global_order_no'] ?? '') !== '') {
$mapping = $this->orderSyncRepository->findByGlobalOrderNo((string)$payload['global_order_no']);
}
if ($mapping === null) {
foreach (($payload['platform_order_nos'] ?? []) as $incrementId) {
$mapping = $this->orderSyncRepository->findByIncrementId((string)$incrementId);
if ($mapping !== null) {
break;
}
}
}
if ($mapping === null || (string)$mapping['status'] !== 'success') {
throw new \RuntimeException('No successfully synchronized Magento order matches the Lingxing outbound order.');
}
$order = $this->orderRepository->get((int)$mapping['order_id']);
if (!$order->canShip()) {
throw new \RuntimeException('Magento order cannot be shipped or is already fully shipped.');
}
$websiteId = (int)$this->storeManager->getStore((int)$order->getStoreId())->getWebsiteId();
$quantities = $this->allocateQuantities($order->getAllItems(), $payload['products'] ?? [], $websiteId);
if ($quantities === []) {
throw new \RuntimeException('Lingxing outbound data contains no Magento order item quantity to ship.');
}
$items = [];
foreach ($quantities as $orderItemId => $quantity) {
$item = $this->itemFactory->create();
$item->setOrderItemId((int)$orderItemId);
$item->setQty($quantity);
$items[] = $item;
}
$tracks = [];
foreach (($payload['tracks'] ?? []) as $trackData) {
$track = $this->trackFactory->create();
$track->setCarrierCode('custom');
$track->setTitle((string)($trackData['title'] ?? $payload['carrier'] ?? 'Lingxing'));
$track->setTrackNumber((string)$trackData['number']);
$tracks[] = $track;
}
$wid = (int)($payload['wid'] ?? 0);
$sourceCode = $this->warehouseRepository->findSourceCodeByWid($wid);
if ($sourceCode === null) {
throw new \RuntimeException(sprintf(
'Lingxing warehouse WID %d is not mapped to a Magento Inventory Source.',
$wid
));
}
$argumentsExtension = $this->shipmentArgumentsExtensionFactory->create();
$argumentsExtension->setSourceCode($sourceCode);
$arguments = $this->shipmentArgumentsFactory->create();
$arguments->setExtensionAttributes($argumentsExtension);
$shipmentId = (int)$this->shipOrder->execute(
(int)$order->getEntityId(),
$items,
$this->config->shouldNotifyCustomer(),
false,
null,
$tracks,
[],
$arguments
);
return ['order_id' => (int)$order->getEntityId(), 'increment_id' => (string)$order->getIncrementId(), 'shipment_id' => $shipmentId];
}
private function allocateQuantities(array $orderItems, array $products, int $websiteId): array
{
$shippableItems = [];
foreach ($orderItems as $item) {
if ($item->getIsVirtual() || (float)$item->getQtyToShip() <= 0) {
continue;
}
$shippableItems[] = $item;
}
usort(
$shippableItems,
static fn($left, $right): int => (int)$left->getItemId() <=> (int)$right->getItemId()
);
$result = [];
foreach ($products as $product) {
// New tasks carry erp_sku; sku remains supported for tasks queued before this upgrade.
$erpSku = trim((string)($product['erp_sku'] ?? $product['sku'] ?? ''));
$candidateSkus = $this->productErpSkuRepository->findMskusByErpSku($websiteId, $erpSku);
if ($candidateSkus === [] && $this->containsSku($shippableItems, $erpSku)) {
// Backward-compatible self-mapping when Lingxing and Magento use the same SKU.
$candidateSkus = [$erpSku];
}
$remaining = (float)($product['quantity'] ?? 0);
$candidateLookup = array_fill_keys($candidateSkus, true);
$matchedItems = [];
foreach ($shippableItems as $item) {
if (isset($candidateLookup[(string)$item->getSku()])) {
$matchedItems[] = $item;
}
}
if ($remaining <= 0 || $matchedItems === []) {
throw new \RuntimeException(sprintf(
'Lingxing ERP SKU "%s" cannot be matched to a shippable Magento order item in Website ID %d.',
$erpSku,
$websiteId
));
}
foreach ($matchedItems as $item) {
$alreadyAllocated = (float)($result[(int)$item->getItemId()] ?? 0);
$available = max(0.0, (float)$item->getQtyToShip() - $alreadyAllocated);
$allocated = min($remaining, $available);
if ($allocated > 0) {
$result[(int)$item->getItemId()] = $alreadyAllocated + $allocated;
$remaining -= $allocated;
}
if ($remaining <= 0.00001) {
break;
}
}
if ($remaining > 0.00001) {
throw new \RuntimeException(sprintf('Lingxing quantity for ERP SKU "%s" exceeds Magento quantity available to ship.', $erpSku));
}
}
return $result;
}
private function containsSku(array $items, string $sku): bool
{
foreach ($items as $item) {
if ((string)$item->getSku() === $sku) {
return true;
}
}
return false;
}
}
@@ -0,0 +1,142 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Shipment;
use Esun\LingxingErp\Model\Api\Client;
use Esun\LingxingErp\Model\Api\Endpoint;
use Esun\LingxingErp\Model\Config;
use Esun\LingxingErp\Model\Sync\LogWriter;
use Esun\LingxingErp\Model\Sync\OrderSyncRepository;
use Esun\LingxingErp\Model\Sync\ShipmentSyncRepository;
use Magento\Framework\Stdlib\DateTime\TimezoneInterface;
use Magento\Framework\FlagManager;
class ShipmentPuller
{
/**
* Lingxing API documentation:
* https://apidoc.lingxing.com/#/docs/Warehouse/WmsOrderList
*/
private const ORDER_FILTER_BATCH_SIZE = 100;
public function __construct(
private readonly Client $client,
private readonly Config $config,
private readonly TimezoneInterface $timezone,
private readonly FlagManager $flagManager,
private readonly FulfillmentNormalizer $normalizer,
private readonly OrderSyncRepository $orderSyncRepository,
private readonly ShipmentSyncRepository $repository,
private readonly LogWriter $logWriter
) {
}
public function pull(): void
{
$now = $this->timezone->date();
$lastSuccess = (string)$this->flagManager->getFlagData('esun_lingxing_shipment_last_success_date');
$earliest = (clone $now)->modify('-30 days')->format('Y-m-d');
$start = $lastSuccess !== '' && $lastSuccess >= $earliest
? $lastSuccess
: (clone $now)->modify('-1 day')->format('Y-m-d');
$end = $now->format('Y-m-d');
$pageSize = $this->config->getShipmentPageSize();
$platformOrderNos = $this->orderSyncRepository->getTrackablePlatformOrderNos();
if ($platformOrderNos === []) {
return;
}
$completedRange = true;
foreach (array_chunk($platformOrderNos, self::ORDER_FILTER_BATCH_SIZE) as $orderNumberBatch) {
if (!$this->pullOrderNumberBatch($orderNumberBatch, $pageSize, $start, $end)) {
$completedRange = false;
break;
}
}
if ($completedRange) {
$this->flagManager->saveFlag('esun_lingxing_shipment_last_success_date', $end);
}
}
/** @param string[] $platformOrderNos */
private function pullOrderNumberBatch(
array $platformOrderNos,
int $pageSize,
string $start,
string $end
): bool {
for ($page = 1; $page <= $this->config->getShipmentMaxPages(); $page++) {
$request = [
'page' => $page,
'page_size' => $pageSize,
'platform_order_no_arr' => $platformOrderNos,
'status_arr' => [3],
'time_type' => 'update_at',
'start_date' => $start,
'end_date' => $end,
];
$started = microtime(true);
$response = $this->client->post(Endpoint::WMS_ORDER_LIST, $request);
$rows = is_array($response['data'] ?? null) ? $response['data'] : [];
$this->enqueueOutbounds($rows, $response);
$this->logWriter->write([
'direction' => 'pull', 'operation' => 'shipment_pull', 'entity_type' => 'shipment',
'status' => 'success', 'attempt_number' => 1,
'request_id' => (string)($response['request_id'] ?? ''),
'request_payload' => $request,
'response_payload' => $response,
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
if (count($rows) < $pageSize) {
return true;
}
}
return false;
}
/** @param array<int, array<string, mixed>> $outbounds */
private function enqueueOutbounds(array $outbounds, array $response): void
{
foreach ($outbounds as $outbound) {
if (!$this->belongsToSynchronizedMagentoOrder($outbound)) {
continue;
}
try {
foreach ($this->normalizer->normalize($outbound) as $payload) {
$this->repository->enqueue($payload, (string)($response['request_id'] ?? ''));
}
} catch (\Throwable $exception) {
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'shipment_normalize',
'entity_type' => 'shipment',
'external_id' => (string)($outbound['wo_number'] ?? ''),
'status' => 'failed',
'attempt_number' => 1,
'error_code' => (string)$exception->getCode(),
'error_message' => $exception->getMessage(),
'request_id' => (string)($response['request_id'] ?? ''),
'response_payload' => $outbound,
]);
}
}
}
private function belongsToSynchronizedMagentoOrder(array $outbound): bool
{
$globalOrderNo = (string)($outbound['order_number'] ?? $outbound['orderNumber'] ?? '');
if ($globalOrderNo !== '' && $this->orderSyncRepository->findByGlobalOrderNo($globalOrderNo) !== null) {
return true;
}
$platformOrderNos = (array)($outbound['platform_order_no'] ?? [$outbound['amazonOrderId'] ?? '']);
foreach ($platformOrderNos as $incrementId) {
if ((string)$incrementId !== ''
&& $this->orderSyncRepository->findByIncrementId((string)$incrementId) !== null
) {
return true;
}
}
return false;
}
}
@@ -0,0 +1,97 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Sku;
use Esun\LingxingErp\Model\Api\ApiException;
use Esun\LingxingErp\Model\Api\Client;
use Esun\LingxingErp\Model\Api\Endpoint;
use Esun\LingxingErp\Model\Sync\LogWriter;
class PairFetcher
{
/**
* Lingxing API documentation:
* https://apidoc.lingxing.com/#/docs/MultiPlatform/V2/PairListV2
*/
private const MAX_PAGES = 10000;
private const MSKU_BATCH_SIZE = 200;
public function __construct(
private readonly Client $client,
private readonly LogWriter $logWriter
) {
}
/** @param string[] $mskus @return array<int, array<string, mixed>> */
public function fetchAll(int $platformCode, string $storeId, array $mskus, int $pageSize): array
{
$pairs = [];
foreach (array_chunk(array_values(array_unique($mskus)), self::MSKU_BATCH_SIZE) as $mskuBatch) {
$offset = 0;
for ($page = 1; $page <= self::MAX_PAGES; $page++) {
$request = [
'offset' => $offset,
'length' => $pageSize,
'msku' => $mskuBatch,
'platform_codes' => [(string)$platformCode],
'store_ids' => [$storeId],
];
$started = microtime(true);
$response = [];
try {
$response = $this->client->post(Endpoint::PAIR_LIST, $request);
$rows = $response['data']['list'] ?? null;
if (!is_array($rows)) {
throw new \RuntimeException('Lingxing PairListV2 response is missing data.list.');
}
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'sku_pair_lookup',
'entity_type' => 'product',
'external_id' => $storeId,
'status' => 'success',
'attempt_number' => 1,
'request_id' => (string)($response['request_id'] ?? ''),
'request_payload' => $request,
'response_payload' => $response,
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
} catch (\Throwable $exception) {
$apiResponse = $exception instanceof ApiException ? $exception->getResponse() : $response;
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'sku_pair_lookup',
'entity_type' => 'product',
'external_id' => $storeId,
'status' => 'failed',
'attempt_number' => 1,
'error_code' => $exception instanceof ApiException
? $exception->getErrorCode()
: (string)$exception->getCode(),
'error_message' => $exception->getMessage(),
'request_id' => (string)($apiResponse['request_id'] ?? ''),
'request_payload' => $request,
'response_payload' => $apiResponse,
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
throw $exception;
}
foreach ($rows as $row) {
if (is_array($row)) {
$pairs[] = $row;
}
}
$count = count($rows);
if ($count < $pageSize) {
break;
}
$offset += $count;
if ($page === self::MAX_PAGES) {
throw new \RuntimeException('Lingxing PairListV2 exceeded the maximum pagination limit.');
}
}
}
return $pairs;
}
}
@@ -0,0 +1,219 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Sku;
use Magento\Catalog\Model\ResourceModel\Product\Action as ProductActionResource;
use Magento\Catalog\Api\Data\ProductInterface;
use Magento\Catalog\Model\Product;
use Magento\Eav\Model\Config as EavConfig;
use Magento\Framework\App\ResourceConnection;
use Magento\Framework\EntityManager\MetadataPool;
use Magento\Store\Model\StoreManagerInterface;
class ProductErpSkuRepository
{
public function __construct(
private readonly ResourceConnection $resource,
private readonly ProductActionResource $productActionResource,
private readonly StoreManagerInterface $storeManager,
private readonly EavConfig $eavConfig,
private readonly MetadataPool $metadataPool
) {
}
/** @return string[] */
public function getWebsiteProductSkus(int $websiteId): array
{
return array_keys($this->getWebsiteProductIdsBySku($websiteId));
}
/** @return string[] */
public function getWebsiteProductSkusWithErpSku(int $websiteId): array
{
$defaultStore = $this->getDefaultStore($websiteId);
$attributeId = (int)$this->eavConfig
->getAttribute(Product::ENTITY, 'erp_sku')
->getAttributeId();
if ($attributeId <= 0) {
throw new \RuntimeException('The erp_sku product attribute does not exist.');
}
$connection = $this->resource->getConnection();
$linkField = $this->metadataPool->getMetadata(ProductInterface::class)->getLinkField();
$select = $connection->select()
->distinct()
->from(
['product' => $this->resource->getTableName('catalog_product_entity')],
['sku']
)
->joinInner(
['website' => $this->resource->getTableName('catalog_product_website')],
'website.product_id = product.entity_id',
[]
)
->joinInner(
['erp_sku_value' => $this->resource->getTableName('catalog_product_entity_varchar')],
sprintf('erp_sku_value.%1$s = product.%1$s', $linkField),
[]
)
->where('website.website_id = ?', $websiteId)
->where('erp_sku_value.attribute_id = ?', $attributeId)
->where('erp_sku_value.store_id = ?', (int)$defaultStore->getId())
->where('erp_sku_value.value IS NOT NULL')
->where('TRIM(erp_sku_value.value) <> ?', '')
->order('product.entity_id ASC');
return array_map('strval', $connection->fetchCol($select));
}
/** @return string[] */
public function findMskusByErpSku(int $websiteId, string $erpSku): array
{
$erpSku = trim($erpSku);
if ($erpSku === '') {
return [];
}
$defaultStore = $this->getDefaultStore($websiteId);
$attributeId = (int)$this->eavConfig
->getAttribute(Product::ENTITY, 'erp_sku')
->getAttributeId();
if ($attributeId <= 0) {
throw new \RuntimeException('The erp_sku product attribute does not exist.');
}
$connection = $this->resource->getConnection();
$linkField = $this->metadataPool->getMetadata(ProductInterface::class)->getLinkField();
$select = $connection->select()
->from(
['product' => $this->resource->getTableName('catalog_product_entity')],
['sku']
)
->joinInner(
['website' => $this->resource->getTableName('catalog_product_website')],
'website.product_id = product.entity_id',
[]
)
->joinInner(
['erp_sku_value' => $this->resource->getTableName('catalog_product_entity_varchar')],
sprintf('erp_sku_value.%1$s = product.%1$s', $linkField),
[]
)
->where('website.website_id = ?', $websiteId)
->where('erp_sku_value.attribute_id = ?', $attributeId)
->where('erp_sku_value.store_id = ?', (int)$defaultStore->getId())
->where('erp_sku_value.value = ?', $erpSku)
->order('product.entity_id ASC');
return array_values(array_unique(array_map('strval', $connection->fetchCol($select))));
}
/**
* @param array<int, array<string, mixed>> $rawPairs
* @return array{requested:int,pairs:int,mapped:int,unmapped:int,unmapped_mskus:string[]}
*/
public function updateWebsiteErpSkus(
int $websiteId,
int $platformCode,
string $storeId,
array $rawPairs
): array {
$pairs = $this->normalizeAndValidate($platformCode, $storeId, $rawPairs);
$productIdsBySku = $this->getWebsiteProductIdsBySku($websiteId);
$defaultStore = $this->getDefaultStore($websiteId);
$storeViewId = (int)$defaultStore->getId();
if ($productIdsBySku !== []) {
$this->productActionResource->updateAttributes(
array_values($productIdsBySku),
['erp_sku' => null],
$storeViewId
);
}
$mappedMskus = [];
foreach ($pairs as $msku => $erpSku) {
if (!isset($productIdsBySku[$msku])) {
continue;
}
$this->productActionResource->updateAttributes(
[$productIdsBySku[$msku]],
['erp_sku' => $erpSku],
$storeViewId
);
$mappedMskus[$msku] = true;
}
$unmappedMskus = array_values(array_diff(array_keys($productIdsBySku), array_keys($mappedMskus)));
return [
'requested' => count($productIdsBySku),
'pairs' => count($pairs),
'mapped' => count($mappedMskus),
'unmapped' => count($unmappedMskus),
// Keep attempt logs useful without allowing one response to exceed the log column.
'unmapped_mskus' => array_slice($unmappedMskus, 0, 200),
];
}
/** @param array<int, array<string, mixed>> $rawPairs @return array<string, string> */
private function normalizeAndValidate(int $platformCode, string $storeId, array $rawPairs): array
{
$byMsku = [];
$erpSkuByNormalizedMsku = [];
foreach ($rawPairs as $row) {
if ((string)($row['platform_code'] ?? '') !== (string)$platformCode
|| (string)($row['store_id'] ?? '') !== $storeId
) {
continue;
}
$msku = trim((string)($row['msku'] ?? ''));
$erpSku = trim((string)($row['sku'] ?? ''));
if ($msku === '' || $erpSku === '') {
continue;
}
$normalizedMsku = mb_strtolower($msku);
if (isset($erpSkuByNormalizedMsku[$normalizedMsku])
&& $erpSkuByNormalizedMsku[$normalizedMsku] !== $erpSku
) {
throw new \RuntimeException(sprintf(
'Lingxing returned multiple ERP SKUs for MSKU "%s" in Website mapping %d/%s.',
$msku,
$platformCode,
$storeId
));
}
$byMsku[$msku] = $erpSku;
$erpSkuByNormalizedMsku[$normalizedMsku] = $erpSku;
}
return $byMsku;
}
/** @return array<string, int> */
private function getWebsiteProductIdsBySku(int $websiteId): array
{
$connection = $this->resource->getConnection();
$select = $connection->select()
->from(['product' => $this->resource->getTableName('catalog_product_entity')], ['sku', 'entity_id'])
->joinInner(
['website' => $this->resource->getTableName('catalog_product_website')],
'website.product_id = product.entity_id',
[]
)
->where('website.website_id = ?', $websiteId)
->where('product.sku <> ?', '')
->order('product.entity_id ASC');
$result = [];
foreach ($connection->fetchAll($select) as $row) {
$result[(string)$row['sku']] = (int)$row['entity_id'];
}
return $result;
}
private function getDefaultStore(int $websiteId): \Magento\Store\Api\Data\StoreInterface
{
$store = $this->storeManager->getWebsite($websiteId)->getDefaultStore();
if ($store === null) {
throw new \RuntimeException(sprintf('Magento Website ID %d has no default store view.', $websiteId));
}
return $store;
}
}
@@ -0,0 +1,96 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Sku;
use Esun\LingxingErp\Model\Config;
use Esun\LingxingErp\Model\Sync\LogWriter;
use Magento\Framework\Lock\LockManagerInterface;
use Magento\Store\Model\StoreManagerInterface;
class SkuSynchronizer
{
private const LOCK_NAME = 'esun_lingxing_sku_sync';
public function __construct(
private readonly Config $config,
private readonly StoreManagerInterface $storeManager,
private readonly PairFetcher $pairFetcher,
private readonly ProductErpSkuRepository $repository,
private readonly LogWriter $logWriter,
private readonly LockManagerInterface $lockManager
) {
}
/** @return array{websites:int,pairs:int,mapped:int,unmapped:int,errors:array<int, string>} */
public function synchronizeAll(): array
{
if (!$this->lockManager->lock(self::LOCK_NAME, 0)) {
throw new \RuntimeException('ERP SKU synchronization is already running.');
}
$summary = ['websites' => 0, 'pairs' => 0, 'mapped' => 0, 'unmapped' => 0, 'errors' => []];
try {
foreach ($this->storeManager->getWebsites(false) as $website) {
$websiteId = (int)$website->getId();
if ($websiteId <= 0 || !$this->config->hasStoreMapping($websiteId)) {
continue;
}
$started = microtime(true);
$platformCode = $this->config->getPlatformCode($websiteId);
$storeId = $this->config->getLingxingStoreId($websiteId);
$request = [
'website_id' => $websiteId,
'platform_codes' => [(string)$platformCode],
'store_ids' => [$storeId],
];
try {
$mskus = $this->repository->getWebsiteProductSkus($websiteId);
$pairs = $this->pairFetcher->fetchAll(
$platformCode,
$storeId,
$mskus,
$this->config->getSkuSyncPageSize()
);
$result = $this->repository->updateWebsiteErpSkus(
$websiteId,
$platformCode,
$storeId,
$pairs
);
$summary['websites']++;
$summary['pairs'] += $result['pairs'];
$summary['mapped'] += $result['mapped'];
$summary['unmapped'] += $result['unmapped'];
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'sku_sync',
'entity_type' => 'product',
'external_id' => $storeId,
'status' => 'success',
'attempt_number' => 1,
'request_payload' => $request,
'response_payload' => $result,
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
} catch (\Throwable $exception) {
$summary['errors'][$websiteId] = $exception->getMessage();
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'sku_sync',
'entity_type' => 'product',
'external_id' => $storeId,
'status' => 'failed',
'attempt_number' => 1,
'error_code' => (string)$exception->getCode(),
'error_message' => $exception->getMessage(),
'request_payload' => $request,
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
}
}
} finally {
$this->lockManager->unlock(self::LOCK_NAME);
}
return $summary;
}
}
@@ -0,0 +1,17 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Source;
use Magento\Framework\Data\OptionSourceInterface;
class Direction implements OptionSourceInterface
{
public function toOptionArray(): array
{
return [
['value' => 'push', 'label' => __('Push to Lingxing')],
['value' => 'pull', 'label' => __('Pull from Lingxing')],
];
}
}
@@ -0,0 +1,47 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Source;
use Esun\LingxingErp\Model\Store\StoreRepository;
use Magento\Framework\Data\OptionSourceInterface;
class LingxingStore implements OptionSourceInterface
{
public function __construct(
private readonly StoreRepository $repository
) {
}
public function toOptionArray(): array
{
$options = [['value' => '', 'label' => __('-- Select a Lingxing store --')]];
$stores = $this->repository->getAll();
if ($stores === []) {
$options[] = [
'value' => '',
'label' => __('No local stores. Use Esun > Lingxing ERP > Stores > Sync Stores.'),
'disabled' => true,
];
return $options;
}
foreach ($stores as $store) {
$platformCode = (int)$store['platform_code'];
$storeId = (string)$store['store_id'];
$active = (int)$store['is_sync'] === 1 && (int)$store['status'] === 1;
$options[] = [
'value' => $platformCode . '|' . $storeId,
'disabled' => !$active,
'label' => sprintf(
'%s[%s / %d] %s (%s)',
$active ? '' : (string)__('Inactive: '),
(string)($store['platform_name'] ?? 'Platform'),
$platformCode,
(string)($store['store_name'] ?? $storeId),
$storeId
),
];
}
return $options;
}
}
@@ -0,0 +1,42 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Source;
use Magento\Framework\App\ResourceConnection;
use Magento\Framework\Data\OptionSourceInterface;
class LingxingWarehouse implements OptionSourceInterface
{
public function __construct(private readonly ResourceConnection $resource)
{
}
public function toOptionArray(): array
{
$options = [['value' => '', 'label' => __('Not mapped')]];
$connection = $this->resource->getConnection();
$table = $this->resource->getTableName('esun_lingxing_warehouse');
if (!$connection->isTableExists($table)) {
return $options;
}
$rows = $connection->fetchAll($connection->select()
->from($table, ['wid', 'warehouse_name', 'source_code'])
->where('warehouse_type = ?', 3)
->where('is_deleted = ?', 0)
->where('lingxing_status = ?', 1)
->order(['warehouse_type ASC', 'warehouse_name ASC']));
foreach ($rows as $row) {
$options[] = [
'value' => (string)$row['wid'],
'label' => sprintf(
'%s (WID %s%s)',
$row['warehouse_name'],
$row['wid'],
$row['source_code'] ? ' / mapped to ' . $row['source_code'] : ''
),
];
}
return $options;
}
}
@@ -0,0 +1,23 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Source;
use Magento\Framework\Data\OptionSourceInterface;
class SyncStatus implements OptionSourceInterface
{
public function toOptionArray(): array
{
return [
['value' => 'pending', 'label' => __('Pending')],
['value' => 'processing', 'label' => __('Processing')],
['value' => 'retrying', 'label' => __('Retrying')],
['value' => 'success', 'label' => __('Success')],
['value' => 'failed', 'label' => __('Failed')],
['value' => 'ignored', 'label' => __('Ignored')],
['value' => 'canceled', 'label' => __('Canceled')],
['value' => 'not_required', 'label' => __('Not Required')],
];
}
}
@@ -0,0 +1,19 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Source;
use Magento\Framework\Data\OptionSourceInterface;
class WarehouseType implements OptionSourceInterface
{
public function toOptionArray(): array
{
return [
['value' => 1, 'label' => __('Local Warehouse')],
['value' => 3, 'label' => __('Overseas Warehouse')],
['value' => 4, 'label' => __('Platform Warehouse')],
['value' => 6, 'label' => __('AWD Warehouse')],
];
}
}
@@ -0,0 +1,50 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Store;
use Esun\LingxingErp\Model\Api\ApiException;
use Esun\LingxingErp\Model\Api\Client;
use Esun\LingxingErp\Model\Api\Endpoint;
class StoreFetcher
{
private const PAGE_SIZE = 200;
private const PLATFORM_CODE = 10009;
public function __construct(private readonly Client $client)
{
}
/** @return array<int, array<string, mixed>> */
public function fetchAll(): array
{
$stores = [];
$offset = 0;
do {
$response = $this->client->post(Endpoint::STORE_LIST, [
'offset' => $offset,
'length' => self::PAGE_SIZE,
'platform_code' => [self::PLATFORM_CODE],
]);
$list = is_array($response['data']['list'] ?? null) ? $response['data']['list'] : [];
foreach ($list as $store) {
if (!is_array($store)) {
continue;
}
$platformCode = (int)($store['platform_code'] ?? 0);
$storeId = trim((string)($store['store_id'] ?? ''));
if ($platformCode <= 0 || $storeId === '') {
throw new ApiException('StoreInfoV2 returned a store without platform_code or store_id.', 'invalid_store_data');
}
$stores[] = $store;
}
$received = count($list);
$offset += $received;
$total = max(0, (int)($response['data']['total'] ?? $offset));
} while ($received > 0 && $offset < $total);
return $stores;
}
}
@@ -0,0 +1,78 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Store;
use Magento\Framework\App\ResourceConnection;
class StoreRepository
{
public function __construct(private readonly ResourceConnection $resource)
{
}
/** @return array<int, array<string, mixed>> */
public function getAll(): array
{
$connection = $this->resource->getConnection();
$select = $connection->select()
->from($this->resource->getTableName('esun_lingxing_store'))
->order(['platform_name ASC', 'store_name ASC', 'store_id ASC']);
return $connection->fetchAll($select);
}
/** @return array<int, string> */
public function getActiveStoreNames(): array
{
$connection = $this->resource->getConnection();
$select = $connection->select()
->from($this->resource->getTableName('esun_lingxing_store'), ['store_name'])
->where('platform_code = ?', 10009)
->where('is_sync = ?', 1)
->where('status = ?', 1)
->order('store_name ASC');
return array_values(array_filter(array_map(
static fn ($name): string => trim((string)$name),
$connection->fetchCol($select)
)));
}
/** @param array<int, array<string, mixed>> $stores */
public function synchronize(array $stores): void
{
$connection = $this->resource->getConnection();
$table = $this->resource->getTableName('esun_lingxing_store');
$now = gmdate('Y-m-d H:i:s');
$rows = [];
foreach ($stores as $store) {
$rows[] = [
'platform_code' => (int)$store['platform_code'],
'platform_name' => trim((string)($store['platform_name'] ?? '')),
'store_id' => trim((string)$store['store_id']),
'sid' => trim((string)($store['sid'] ?? '')),
'store_name' => trim((string)($store['store_name'] ?? '')),
'currency' => trim((string)($store['currency'] ?? '')),
'is_sync' => (int)($store['is_sync'] ?? 0),
'status' => (int)($store['status'] ?? 0),
'last_synced_at' => $now,
];
}
$connection->beginTransaction();
try {
// Rows absent from a complete response remain visible, but cannot be selected as active stores.
$connection->update($table, ['is_sync' => 0, 'status' => 0]);
if ($rows !== []) {
$connection->insertOnDuplicate($table, $rows, [
'platform_code', 'platform_name', 'sid', 'store_name', 'currency',
'is_sync', 'status', 'last_synced_at',
]);
}
$connection->commit();
} catch (\Throwable $exception) {
$connection->rollBack();
throw $exception;
}
}
}
@@ -0,0 +1,49 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Store;
use Esun\LingxingErp\Model\Api\ApiException;
use Esun\LingxingErp\Model\Sync\LogWriter;
class StoreSynchronizer
{
public function __construct(
private readonly StoreFetcher $fetcher,
private readonly StoreRepository $repository,
private readonly LogWriter $logWriter
) {
}
public function synchronize(): int
{
$started = microtime(true);
try {
$stores = $this->fetcher->fetchAll();
$this->repository->synchronize($stores);
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'store_sync',
'entity_type' => 'store',
'status' => 'success',
'response_payload' => ['store_count' => count($stores)],
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
return count($stores);
} catch (\Throwable $exception) {
$code = $exception instanceof ApiException ? $exception->getErrorCode() : (string)$exception->getCode();
$response = $exception instanceof ApiException ? $exception->getResponse() : [];
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'store_sync',
'entity_type' => 'store',
'status' => 'failed',
'error_code' => $code,
'error_message' => $exception->getMessage(),
'response_payload' => $response,
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
throw $exception;
}
}
}
@@ -0,0 +1,66 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Sync;
use Magento\Framework\App\ResourceConnection;
class DetailProvider
{
private const SYNC_TABLES = [
'order' => 'esun_lingxing_order_sync',
'shipment' => 'esun_lingxing_shipment_sync',
];
public function __construct(private readonly ResourceConnection $resource)
{
}
/** @return array<string, mixed>|null */
public function getRecord(string $type, int $id): ?array
{
$table = $type === 'log'
? 'esun_lingxing_sync_log'
: (self::SYNC_TABLES[$type] ?? '');
if ($table === '' || $id <= 0) {
return null;
}
$connection = $this->resource->getConnection();
$row = $connection->fetchRow(
$connection->select()
->from($this->resource->getTableName($table))
->where('entity_id = ?', $id)
->limit(1)
);
return is_array($row) && $row !== [] ? $row : null;
}
/** @return array<int, array<string, mixed>> */
public function getLogs(string $type, array $record): array
{
if ($type === 'log') {
return [$record];
}
if (!isset(self::SYNC_TABLES[$type])) {
return [];
}
$connection = $this->resource->getConnection();
$select = $connection->select()
->from($this->resource->getTableName('esun_lingxing_sync_log'))
->where('entity_type = ?', $type)
->order('entity_id DESC');
$localId = (int)($record['entity_id'] ?? 0);
$requestId = trim((string)($record['request_id'] ?? ''));
if ($requestId !== '') {
$select->where(sprintf(
'(%s OR %s)',
$connection->quoteInto('local_entity_id = ?', $localId),
$connection->quoteInto('request_id = ?', $requestId)
));
} else {
$select->where('local_entity_id = ?', $localId);
}
return $connection->fetchAll($select);
}
}
@@ -0,0 +1,92 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Sync;
use Esun\LingxingErp\Model\Api\Endpoint;
use Magento\Framework\App\ResourceConnection;
class LogWriter
{
private const COMPACT_STATUSES = ['success', 'ignored'];
private const SUMMARY_SCALAR_KEYS = [
'code', 'message', 'request_id', 'store_count', 'shipment_id',
'pairs', 'mapped', 'unmapped', 'zeroed', 'preserved_without_erp_sku', 'total', 'count',
];
private const SENSITIVE_KEYS = [
'appsecret', 'app_secret', 'access_token', 'refresh_token', 'sign',
'receiver_name', 'receiver_company_name', 'address_line1', 'address_line2',
'address_line3', 'postal_code', 'postcode', 'receiver_mobile', 'buyer_email', 'buyer_name',
'phone', 'telephone', 'email', 'consignee', 'consignee_phone', 'consignee_address',
'consignee_full_address',
];
public function __construct(private readonly ResourceConnection $resource)
{
}
public function write(array $data): void
{
$data['api_path'] ??= Endpoint::forOperation((string)($data['operation'] ?? '')) ?: null;
$compactPayload = in_array((string)($data['status'] ?? ''), self::COMPACT_STATUSES, true);
foreach (['request_payload', 'response_payload'] as $field) {
if (!isset($data[$field])) {
continue;
}
if ($compactPayload) {
$data[$field] = $this->summarize($data[$field]);
}
if (is_array($data[$field])) {
$data[$field] = json_encode(
$this->sanitize($data[$field]),
JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR
);
}
}
$data['created_at'] = gmdate('Y-m-d H:i:s');
$this->resource->getConnection()->insert(
$this->resource->getTableName('esun_lingxing_sync_log'),
$data
);
}
private function summarize(mixed $payload): array
{
$sanitized = is_array($payload) ? $this->sanitize($payload) : $payload;
$encoded = json_encode(
$sanitized,
JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR
);
$summary = [
'_summary' => 'Success payload omitted by retention policy.',
'payload_sha256' => hash('sha256', $encoded),
'payload_bytes' => strlen($encoded),
];
if (!is_array($sanitized)) {
return $summary;
}
$summary['top_level_keys'] = array_values(array_map('strval', array_keys($sanitized)));
foreach ($sanitized as $key => $value) {
$normalized = strtolower((string)$key);
if (in_array($normalized, self::SUMMARY_SCALAR_KEYS, true) && is_scalar($value)) {
$summary[$key] = $value;
} elseif (is_array($value)) {
$summary[$key . '_count'] = count($value);
}
}
return $summary;
}
private function sanitize(array $data): array
{
foreach ($data as $key => $value) {
$normalized = strtolower((string)$key);
if (in_array($normalized, self::SENSITIVE_KEYS, true)) {
$data[$key] = '[REDACTED]';
} elseif (is_array($value)) {
$data[$key] = $this->sanitize($value);
}
}
return $data;
}
}
@@ -0,0 +1,146 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Sync;
use Magento\Framework\App\ResourceConnection;
use Magento\Sales\Api\Data\OrderInterface;
use Magento\Sales\Model\Order;
class OrderSyncRepository
{
private string $table;
public function __construct(private readonly ResourceConnection $resource)
{
$this->table = $resource->getTableName('esun_lingxing_order_sync');
}
public function enqueue(OrderInterface $order): void
{
$connection = $this->resource->getConnection();
$exists = $connection->fetchOne(
$connection->select()->from($this->table, ['entity_id'])->where('order_id = ?', (int)$order->getEntityId())
);
if ($exists) {
return;
}
$now = gmdate('Y-m-d H:i:s');
$connection->insert($this->table, [
'order_id' => (int)$order->getEntityId(),
'increment_id' => (string)$order->getIncrementId(),
'platform_order_no' => (string)$order->getIncrementId(),
'status' => 'pending',
'created_at' => $now,
'updated_at' => $now,
]);
}
public function getDue(int $limit): array
{
$connection = $this->resource->getConnection();
return $connection->fetchAll($connection->select()->from($this->table)
->where('status IN (?)', ['pending', 'retrying'])
->where('next_retry_at IS NULL OR next_retry_at <= ?', gmdate('Y-m-d H:i:s'))
->order('entity_id ASC')->limit($limit));
}
public function claim(int $entityId): bool
{
return $this->resource->getConnection()->update(
$this->table,
['status' => 'processing', 'last_attempt_at' => gmdate('Y-m-d H:i:s')],
['entity_id = ?' => $entityId, 'status IN (?)' => ['pending', 'retrying']]
) === 1;
}
public function markSuccess(int $entityId, string $globalOrderNo, string $requestId, string $payloadHash): void
{
$now = gmdate('Y-m-d H:i:s');
$this->resource->getConnection()->update($this->table, [
'global_order_no' => $globalOrderNo,
'status' => 'success',
'request_id' => $requestId ?: null,
'payload_hash' => $payloadHash,
'last_error_code' => null,
'last_error_message' => null,
'next_retry_at' => null,
'synced_at' => $now,
'updated_at' => $now,
], ['entity_id = ?' => $entityId]);
}
public function markCreationCanceled(int $entityId): void
{
$now = gmdate('Y-m-d H:i:s');
$this->resource->getConnection()->update($this->table, [
'status' => 'canceled',
'next_retry_at' => null,
'updated_at' => $now,
], ['entity_id = ?' => $entityId]);
}
public function markFailure(int $entityId, int $attemptCount, int $maxAttempts, string $code, string $message, string $requestId = ''): string
{
$attemptCount++;
$status = $attemptCount >= $maxAttempts ? 'failed' : 'retrying';
$delay = min(3600, 30 * (2 ** min(7, max(0, $attemptCount - 1))));
$this->resource->getConnection()->update($this->table, [
'status' => $status,
'attempt_count' => $attemptCount,
'next_retry_at' => $status === 'retrying' ? gmdate('Y-m-d H:i:s', time() + $delay) : null,
'last_error_code' => $code ?: null,
'last_error_message' => mb_substr($message, 0, 65535),
'request_id' => $requestId ?: null,
'updated_at' => gmdate('Y-m-d H:i:s'),
], ['entity_id = ?' => $entityId]);
return $status;
}
public function findByGlobalOrderNo(string $globalOrderNo): ?array
{
$connection = $this->resource->getConnection();
$row = $connection->fetchRow($connection->select()->from($this->table)
->where('global_order_no = ?', $globalOrderNo)->limit(1));
return is_array($row) ? $row : null;
}
public function findByIncrementId(string $incrementId): ?array
{
$connection = $this->resource->getConnection();
$row = $connection->fetchRow($connection->select()->from($this->table)
->where('increment_id = ?', $incrementId)->limit(1));
return is_array($row) ? $row : null;
}
/** @return string[] */
public function getTrackablePlatformOrderNos(): array
{
$connection = $this->resource->getConnection();
$salesOrderTable = $this->resource->getTableName('sales_order');
$select = $connection->select()
->from(['sync' => $this->table], ['platform_order_no'])
->joinInner(['sales_order' => $salesOrderTable], 'sales_order.entity_id = sync.order_id', [])
->where('sync.status = ?', 'success')
->where('sync.platform_order_no <> ?', '')
->where('sales_order.state NOT IN (?)', [
Order::STATE_COMPLETE,
Order::STATE_CLOSED,
Order::STATE_CANCELED,
])
->order('sync.entity_id ASC');
return array_values(array_unique(array_map('strval', $connection->fetchCol($select))));
}
public function retry(int $entityId): bool
{
return $this->resource->getConnection()->update($this->table, [
'status' => 'pending',
'attempt_count' => 0,
'next_retry_at' => null,
'last_error_code' => null,
'last_error_message' => null,
'updated_at' => gmdate('Y-m-d H:i:s'),
], ['entity_id = ?' => $entityId, 'status IN (?)' => ['failed', 'retrying']]) === 1;
}
}
@@ -0,0 +1,107 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Sync;
use Magento\Framework\App\ResourceConnection;
class ShipmentSyncRepository
{
private string $table;
public function __construct(private readonly ResourceConnection $resource)
{
$this->table = $resource->getTableName('esun_lingxing_shipment_sync');
}
public function enqueue(array $payload, string $requestId = ''): void
{
$connection = $this->resource->getConnection();
$externalKey = (string)$payload['external_key'];
$existing = $connection->fetchRow($connection->select()->from($this->table)
->where('external_key = ?', $externalKey)->limit(1));
$data = [
'global_order_no' => (string)($payload['global_order_no'] ?? ''),
'wo_id' => !empty($payload['wo_id']) ? (int)$payload['wo_id'] : null,
'wo_number' => (string)$payload['wo_number'],
'package_no' => (string)($payload['package_no'] ?? '') ?: null,
'tracking_no' => implode(',', array_values(array_filter(array_column($payload['tracks'] ?? [], 'number')))),
'request_id' => $requestId ?: null,
'payload_json' => (string)json_encode($payload, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES | JSON_THROW_ON_ERROR),
'updated_at' => gmdate('Y-m-d H:i:s'),
];
if (!$existing) {
$data += [
'external_key' => $externalKey,
'status' => 'pending',
'created_at' => gmdate('Y-m-d H:i:s'),
];
$connection->insert($this->table, $data);
return;
}
if ((string)$existing['status'] !== 'success') {
$connection->update($this->table, $data, ['entity_id = ?' => (int)$existing['entity_id']]);
}
}
public function getDue(int $limit): array
{
$connection = $this->resource->getConnection();
return $connection->fetchAll($connection->select()->from($this->table)
->where('status IN (?)', ['pending', 'retrying'])
->where('next_retry_at IS NULL OR next_retry_at <= ?', gmdate('Y-m-d H:i:s'))
->order('entity_id ASC')->limit($limit));
}
public function claim(int $entityId): bool
{
return $this->resource->getConnection()->update($this->table, [
'status' => 'processing',
'last_attempt_at' => gmdate('Y-m-d H:i:s'),
], ['entity_id = ?' => $entityId, 'status IN (?)' => ['pending', 'retrying']]) === 1;
}
public function markSuccess(int $entityId, int $orderId, string $incrementId, int $shipmentId): void
{
$now = gmdate('Y-m-d H:i:s');
$this->resource->getConnection()->update($this->table, [
'order_id' => $orderId,
'increment_id' => $incrementId,
'shipment_id' => $shipmentId,
'status' => 'success',
'last_error_code' => null,
'last_error_message' => null,
'next_retry_at' => null,
'synced_at' => $now,
'updated_at' => $now,
], ['entity_id = ?' => $entityId]);
}
public function markFailure(int $entityId, int $attemptCount, int $maxAttempts, string $code, string $message): string
{
$attemptCount++;
$status = $attemptCount >= $maxAttempts ? 'failed' : 'retrying';
$delay = min(3600, 30 * (2 ** min(7, max(0, $attemptCount - 1))));
$this->resource->getConnection()->update($this->table, [
'status' => $status,
'attempt_count' => $attemptCount,
'next_retry_at' => $status === 'retrying' ? gmdate('Y-m-d H:i:s', time() + $delay) : null,
'last_error_code' => $code ?: null,
'last_error_message' => mb_substr($message, 0, 65535),
'updated_at' => gmdate('Y-m-d H:i:s'),
], ['entity_id = ?' => $entityId]);
return $status;
}
public function retry(int $entityId): bool
{
return $this->resource->getConnection()->update($this->table, [
'status' => 'pending',
'attempt_count' => 0,
'next_retry_at' => null,
'last_error_code' => null,
'last_error_message' => null,
'updated_at' => gmdate('Y-m-d H:i:s'),
], ['entity_id = ?' => $entityId, 'status IN (?)' => ['failed', 'retrying']]) === 1;
}
}
@@ -0,0 +1,93 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Warehouse;
use Esun\LingxingErp\Model\Api\ApiException;
use Esun\LingxingErp\Model\Api\Client;
use Esun\LingxingErp\Model\Api\Endpoint;
use Esun\LingxingErp\Model\Sync\LogWriter;
class WarehouseFetcher
{
/**
* Lingxing API documentation:
* https://apidoc.lingxing.com/#/docs/Warehouse/WarehouseLists
*/
private const PAGE_SIZE = 1000;
private const WAREHOUSE_TYPE = 3;
public function __construct(
private readonly Client $client,
private readonly LogWriter $logWriter
) {
}
/** @return array<int, array<string, mixed>> */
public function fetchAll(): array
{
$warehouses = [];
$type = self::WAREHOUSE_TYPE;
$offset = 0;
do {
$request = [
'type' => $type,
'is_delete' => '0,1',
'offset' => $offset,
'length' => self::PAGE_SIZE,
];
$started = microtime(true);
$response = [];
try {
$response = $this->client->post(Endpoint::WAREHOUSE_LIST, $request);
$rows = $response['data'] ?? null;
if (!is_array($rows)) {
throw new \RuntimeException('Lingxing warehouse response is missing data.');
}
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'warehouse_sync',
'entity_type' => 'warehouse',
'external_id' => (string)$type,
'status' => 'success',
'attempt_number' => 1,
'request_id' => (string)($response['request_id'] ?? ''),
'request_payload' => $request,
'response_payload' => $response,
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
} catch (\Throwable $exception) {
$apiResponse = $exception instanceof ApiException ? $exception->getResponse() : $response;
$this->logWriter->write([
'direction' => 'pull',
'operation' => 'warehouse_sync',
'entity_type' => 'warehouse',
'external_id' => (string)$type,
'status' => 'failed',
'attempt_number' => 1,
'error_code' => $exception instanceof ApiException
? $exception->getErrorCode()
: (string)$exception->getCode(),
'error_message' => $exception->getMessage(),
'request_id' => (string)($apiResponse['request_id'] ?? ''),
'request_payload' => $request,
'response_payload' => $apiResponse,
'duration_ms' => (int)round((microtime(true) - $started) * 1000),
]);
throw $exception;
}
foreach ($rows as $row) {
if (!is_array($row) || (int)($row['wid'] ?? 0) <= 0) {
continue;
}
$row['type'] = (int)($row['type'] ?? $type);
$warehouses[(int)$row['wid']] = $row;
}
$received = count($rows);
$offset += $received;
$total = max(0, (int)($response['total'] ?? $offset));
} while ($received > 0 && $offset < $total);
return array_values($warehouses);
}
}
@@ -0,0 +1,159 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Warehouse;
use Magento\Framework\App\ResourceConnection;
class WarehouseRepository
{
public function __construct(private readonly ResourceConnection $resource)
{
}
/** @param array<string, mixed> $warehouse */
public function saveMetadata(array $warehouse): void
{
$now = gmdate('Y-m-d H:i:s');
$data = [
'wid' => (int)$warehouse['wid'],
'warehouse_name' => trim((string)($warehouse['name'] ?? '')),
'warehouse_type' => (int)($warehouse['type'] ?? 0),
'country_code' => trim((string)($warehouse['country_code'] ?? '')) ?: null,
'third_party_code' => trim((string)($warehouse['t_warehouse_code'] ?? '')) ?: null,
'third_party_name' => trim((string)($warehouse['t_warehouse_name'] ?? '')) ?: null,
'lingxing_status' => trim((string)($warehouse['t_status'] ?? '')) === ''
? 1
: (int)$warehouse['t_status'],
'is_deleted' => (int)($warehouse['is_delete'] ?? 0),
'last_synced_at' => $now,
'updated_at' => $now,
];
$this->resource->getConnection()->insertOnDuplicate(
$this->resource->getTableName('esun_lingxing_warehouse'),
$data,
array_keys(array_diff_key($data, ['wid' => true]))
);
}
public function assignSource(string $sourceCode, ?int $wid): void
{
$sourceCode = trim($sourceCode);
if ($sourceCode === '') {
throw new \InvalidArgumentException('Magento Source code is required.');
}
$connection = $this->resource->getConnection();
$table = $this->resource->getTableName('esun_lingxing_warehouse');
$connection->beginTransaction();
try {
$connection->update($table, ['source_code' => null], ['source_code = ?' => $sourceCode]);
if ($wid !== null) {
if ($wid <= 0) {
throw new \InvalidArgumentException('Lingxing warehouse ID must be positive.');
}
$updated = $connection->update(
$table,
['source_code' => $sourceCode],
['wid = ?' => $wid, 'warehouse_type = ?' => 3, 'is_deleted = ?' => 0]
);
if ($updated !== 1) {
throw new \RuntimeException(sprintf(
'Lingxing type 3 warehouse WID %d is not available. Synchronize warehouses first.',
$wid
));
}
}
$connection->commit();
} catch (\Throwable $exception) {
$connection->rollBack();
throw $exception;
}
}
public function getWidForSource(string $sourceCode): ?int
{
$connection = $this->resource->getConnection();
$value = $connection->fetchOne($connection->select()
->from($this->resource->getTableName('esun_lingxing_warehouse'), ['wid'])
->where('source_code = ?', $sourceCode)
->where('warehouse_type = ?', 3)
->limit(1));
return $value === false ? null : (int)$value;
}
/** @return array<int, array<string, mixed>> */
public function getInventoryTargets(): array
{
$connection = $this->resource->getConnection();
$warehouse = $this->resource->getTableName('esun_lingxing_warehouse');
$links = $this->resource->getTableName('inventory_source_stock_link');
return $connection->fetchAll($connection->select()
->distinct()
->from(['warehouse' => $warehouse])
->joinInner(['source_stock' => $links], 'source_stock.source_code = warehouse.source_code', [])
->where('warehouse.warehouse_type = ?', 3)
->where('warehouse.is_deleted = ?', 0)
->where('warehouse.lingxing_status = ?', 1)
->order('warehouse.wid ASC'));
}
/** @return int[] */
public function getWebsiteIdsForSource(string $sourceCode): array
{
$connection = $this->resource->getConnection();
$channelCondition = $connection->quoteInto(
'channel.stock_id = source_stock.stock_id AND channel.type = ?',
'website'
);
$select = $connection->select()
->distinct()
->from(['source_stock' => $this->resource->getTableName('inventory_source_stock_link')], [])
->joinInner(
['channel' => $this->resource->getTableName('inventory_stock_sales_channel')],
$channelCondition,
[]
)
->joinInner(
['website' => $this->resource->getTableName('store_website')],
'website.code = channel.code',
['website_id']
)
->where('source_stock.source_code = ?', $sourceCode)
->where('website.website_id > ?', 0);
return array_map('intval', $connection->fetchCol($select));
}
public function findSourceCodeByWid(int $wid): ?string
{
if ($wid <= 0) {
return null;
}
$connection = $this->resource->getConnection();
$value = $connection->fetchOne($connection->select()
->from($this->resource->getTableName('esun_lingxing_warehouse'), ['source_code'])
->where('wid = ?', $wid)
->where('is_deleted = ?', 0)
->limit(1));
return $value === false || trim((string)$value) === '' ? null : (string)$value;
}
/** @return string[] */
public function getExistingSourceItemSkus(string $sourceCode): array
{
$connection = $this->resource->getConnection();
return array_map('strval', $connection->fetchCol($connection->select()
->from($this->resource->getTableName('inventory_source_item'), ['sku'])
->where('source_code = ?', $sourceCode)));
}
public function markInventorySynchronized(int $wid): void
{
$now = gmdate('Y-m-d H:i:s');
$this->resource->getConnection()->update(
$this->resource->getTableName('esun_lingxing_warehouse'),
['last_inventory_synced_at' => $now, 'updated_at' => $now],
['wid = ?' => $wid]
);
}
}
@@ -0,0 +1,35 @@
<?php
declare(strict_types=1);
namespace Esun\LingxingErp\Model\Warehouse;
use Magento\Framework\Lock\LockManagerInterface;
class WarehouseSynchronizer
{
private const LOCK_NAME = 'esun_lingxing_warehouse_sync';
public function __construct(
private readonly WarehouseFetcher $fetcher,
private readonly WarehouseRepository $repository,
private readonly LockManagerInterface $lockManager
) {
}
/** @return array{warehouses:int} */
public function synchronize(): array
{
if (!$this->lockManager->lock(self::LOCK_NAME, 0)) {
throw new \RuntimeException('Warehouse synchronization is already running.');
}
try {
$warehouses = $this->fetcher->fetchAll();
foreach ($warehouses as $warehouse) {
$this->repository->saveMetadata($warehouse);
}
return ['warehouses' => count($warehouses)];
} finally {
$this->lockManager->unlock(self::LOCK_NAME);
}
}
}