feat: add overseas return operations

src/api/return-packing.js

@@ -0,0 +1,47 @@
+import { overseasRequest } from './overseas.js'
+
+const BASE = '/pda/v1/last-leg/return-inventory'
+const encoded = (value) => encodeURIComponent(String(value || '').trim())
+const count = (value) => Number.isFinite(Number(value)) ? Math.max(0, Number(value)) : 0
+
+function normalizeItems(items) {
+	return Array.isArray(items) ? items.map((item) => ({
+		skuCode: String(item.skuCode || ''), productNameZh: String(item.productNameZh || ''),
+		quantity: count(item.quantity ?? item.availableQuantity)
+	})) : []
+}
+
+export function normalizePackingPreview(value = {}) {
+	return {
+		customerKey: value.customerId == null ? '' : String(value.customerId),
+		orders: Array.isArray(value.orders) ? value.orders.map((item) => ({
+			returnNo: String(item.returnNo || ''), customerReferenceNo: String(item.customerReferenceNo || ''), status: String(item.status || '')
+		})) : [],
+		skus: Array.isArray(value.skus) ? value.skus.map((item) => ({
+			skuCode: String(item.skuCode || ''), productNameZh: String(item.productNameZh || ''), availableQuantity: count(item.availableQuantity)
+		})) : []
+	}
+}
+
+export function normalizeReturnLabel(value = {}) {
+	return {
+		cartonMark: String(value.cartonMark || ''), sourceBatchNo: String(value.sourceBatchNo || ''),
+		sourceReturnNo: String(value.sourceReturnNo || ''), totalQuantity: count(value.totalQuantity),
+		length: count(value.length), width: count(value.width), height: count(value.height), weight: count(value.weight),
+		items: normalizeItems(value.items), generatedAt: value.generatedAt || null, printableHtml: String(value.printableHtml || '')
+	}
+}
+
+export async function findPackingOrders(returnNo = '') {
+	const query = String(returnNo || '').trim()
+	return normalizePackingPreview(await overseasRequest('GET', `${BASE}/packing/orders${query ? `?returnNo=${encoded(query)}` : ''}`))
+}
+
+export async function mergeReturnCartons(request) {
+	const value = await overseasRequest('POST', `${BASE}/cartons/merge`, request)
+	return { cartonMark: String(value?.cartonMark || ''), skuCode: String(value?.skuCode || ''), totalQuantity: count(value?.totalQuantity), label: normalizeReturnLabel(value?.label) }
+}
+
+export async function getReturnCartonLabel(cartonMark) {
+	return normalizeReturnLabel(await overseasRequest('GET', `${BASE}/cartons/${encoded(cartonMark)}/label`))
+}

src/api/return-receipt.js

@@ -0,0 +1,66 @@
+import { overseasRequest } from './overseas.js'
+
+const BASE = '/pda/v1/last-leg/return-receipts'
+
+function count(value) {
+	const result = Number(value || 0)
+	return Number.isFinite(result) ? Math.max(0, result) : 0
+}
+
+function normalizeItem(item = {}) {
+	return {
+		skuCode: String(item.skuCode || ''),
+		productNameZh: String(item.productNameZh || ''),
+		expectedQuantity: count(item.expectedQuantity),
+		receivedQuantity: count(item.receivedQuantity)
+	}
+}
+
+export function normalizeReturnReceiptStart(value = {}) {
+	return {
+		returnNo: String(value.returnNo || ''),
+		status: String(value.status || ''),
+		expectedItems: Array.isArray(value.expectedItems) ? value.expectedItems.map(normalizeItem) : []
+	}
+}
+
+export function normalizeReturnSkuCandidates(value = {}) {
+	return {
+		skuCode: String(value.skuCode || ''),
+		candidates: Array.isArray(value.candidates) ? value.candidates.map((item) => ({
+			returnNo: String(item.returnNo || ''),
+			customerReferenceNo: String(item.customerReferenceNo || ''),
+			status: String(item.status || ''),
+			skuExpectedQuantity: count(item.skuExpectedQuantity),
+			skuReceivedQuantity: count(item.skuReceivedQuantity),
+			orderExpectedQuantity: count(item.orderExpectedQuantity),
+			orderReceivedQuantity: count(item.orderReceivedQuantity)
+		})) : []
+	}
+}
+
+export function normalizeReturnReceiptResult(value = {}) {
+	return {
+		returnNo: String(value.returnNo || ''),
+		receiptNo: String(value.receiptNo || ''),
+		receiptBatchNo: String(value.receiptBatchNo || ''),
+		cartonMark: String(value.cartonMark || ''),
+		orderStatus: String(value.orderStatus || ''),
+		fullyMatched: Boolean(value.fullyMatched),
+		expectedQuantity: count(value.expectedQuantity),
+		receivedQuantity: count(value.receivedQuantity),
+		signedAt: value.signedAt || null
+	}
+}
+
+export async function startReturnReceipt(returnNo) {
+	return normalizeReturnReceiptStart(await overseasRequest('POST', `${BASE}/start`, { returnNo: String(returnNo || '').trim() }))
+}
+
+export async function findReturnSkuCandidates(skuCode) {
+	return normalizeReturnSkuCandidates(await overseasRequest('POST', `${BASE}/sku-candidates`, { skuCode: String(skuCode || '').trim() }))
+}
+
+export async function confirmReturnReceipt(request) {
+	return normalizeReturnReceiptResult(await overseasRequest('POST', `${BASE}/confirm`, request))
+}