feat: add third-party order logistics APIs

server-api/app/support/EnterpriseOrderService.php

@@ -169,6 +169,136 @@ class EnterpriseOrderService
         return $this->buildOrderProgress((int)$customer['id'], $ref, (string)$customer['customer_code']);
     }
 
+    public function submitShipping(array $customer, array $payload): array
+    {
+        $externalOrderNo = trim((string)($payload['external_order_no'] ?? ''));
+        $expressCompany = trim((string)($payload['express_company'] ?? ''));
+        $trackingNo = trim((string)($payload['tracking_no'] ?? ''));
+
+        if ($externalOrderNo === '') {
+            throw new \InvalidArgumentException('external_order_no 不能为空');
+        }
+        if ($expressCompany === '' || $trackingNo === '') {
+            throw new \InvalidArgumentException('快递公司和运单号不能为空');
+        }
+
+        $ref = Db::name('enterprise_customer_order_refs')
+            ->where('customer_id', (int)$customer['id'])
+            ->where('external_order_no', $externalOrderNo)
+            ->find();
+        if (!$ref) {
+            throw new \RuntimeException('订单不存在');
+        }
+
+        $order = Db::name('orders')->where('id', (int)$ref['order_id'])->find();
+        if (!$order) {
+            throw new \RuntimeException('订单不存在');
+        }
+        if ((string)$order['order_status'] !== 'pending_shipping') {
+            throw new \InvalidArgumentException('当前订单状态不支持提交运单');
+        }
+
+        $existing = Db::name('order_logistics')
+            ->where('order_id', (int)$order['id'])
+            ->where('logistics_type', 'send_to_center')
+            ->order('id', 'desc')
+            ->find();
+        $sameLogistics = $existing
+            && (string)$existing['express_company'] === $expressCompany
+            && (string)$existing['tracking_no'] === $trackingNo;
+        if ($sameLogistics) {
+            return [
+                'idempotent' => true,
+                'updated' => false,
+                'logistics' => $this->formatLogistics($existing),
+                'order' => $this->buildOrderProgress((int)$customer['id'], $ref, (string)$customer['customer_code']),
+            ];
+        }
+
+        $now = date('Y-m-d H:i:s');
+        $latestDesc = sprintf('客户已提交寄送运单：%s %s，等待鉴定中心签收。', $expressCompany, $trackingNo);
+        $updated = (bool)$existing;
+        $logisticsId = 0;
+        $resetLogisticsSync = false;
+
+        Db::startTrans();
+        try {
+            if ($existing) {
+                $logisticsId = (int)$existing['id'];
+                $resetLogisticsSync = true;
+                Db::name('order_logistics')->where('id', $logisticsId)->update([
+                    'logistics_type' => 'send_to_center',
+                    'express_company' => $expressCompany,
+                    'tracking_no' => $trackingNo,
+                    'tracking_status' => 'submitted',
+                    'latest_desc' => $latestDesc,
+                    'latest_time' => $now,
+                    'updated_at' => $now,
+                ]);
+                $nodeText = '已更新运单';
+                $nodeDesc = sprintf('客户更新了寄送运单：%s %s', $expressCompany, $trackingNo);
+            } else {
+                $logisticsId = (int)Db::name('order_logistics')->insertGetId([
+                    'order_id' => (int)$order['id'],
+                    'logistics_type' => 'send_to_center',
+                    'express_company' => $expressCompany,
+                    'tracking_no' => $trackingNo,
+                    'tracking_status' => 'submitted',
+                    'latest_desc' => $latestDesc,
+                    'latest_time' => $now,
+                    'created_at' => $now,
+                    'updated_at' => $now,
+                ]);
+                $nodeText = '已提交运单';
+                $nodeDesc = sprintf('客户已提交寄送运单：%s %s', $expressCompany, $trackingNo);
+            }
+
+            Db::name('order_logistics_nodes')->insert([
+                'logistics_id' => $logisticsId,
+                'node_time' => $now,
+                'node_desc' => $latestDesc,
+                'node_location' => '第三方',
+                'created_at' => $now,
+            ]);
+
+            Db::name('orders')->where('id', (int)$order['id'])->update([
+                'display_status' => '已提交运单',
+                'updated_at' => $now,
+            ]);
+
+            Db::name('order_timelines')->insert([
+                'order_id' => (int)$order['id'],
+                'node_code' => 'tracking_submitted',
+                'node_text' => $nodeText,
+                'node_desc' => $nodeDesc,
+                'operator_type' => 'system',
+                'operator_id' => null,
+                'occurred_at' => $now,
+                'created_at' => $now,
+            ]);
+
+            Db::commit();
+        } catch (\Throwable $e) {
+            Db::rollback();
+            throw $e;
+        }
+
+        $syncService = new OrderLogisticsSyncService();
+        if ($resetLogisticsSync) {
+            Db::name('order_logistics_syncs')->where('logistics_id', $logisticsId)->delete();
+        }
+        $syncService->subscribeAsync($logisticsId);
+
+        $logistics = Db::name('order_logistics')->where('id', $logisticsId)->find();
+
+        return [
+            'idempotent' => false,
+            'updated' => $updated,
+            'logistics' => $this->formatLogistics($logistics),
+            'order' => $this->buildOrderProgress((int)$customer['id'], $ref, (string)$customer['customer_code']),
+        ];
+    }
+
     public function buildOrderProgress(int $customerId, array $ref, string $customerCode = ''): array
     {
         $order = Db::name('orders')->where('id', (int)$ref['order_id'])->find();