feat(fleet): complete exception processing and trip evidence interfaces

src/modules/overseas-warehouse/api/exceptionOrders.ts

@@ -10,6 +10,37 @@ export interface ExceptionOrderRow {
   deliveryOrderId?: string | null; deliveryNo?: string | null; outboundNo?: string | null
   skuCode?: string | null; packageCount?: number | null; returnDirection?: string | null; returnLogisticsNo?: string | null
   handlingAction?: string | null; handlerName?: string | null; exceptionAt: string; updatedAt: string
+  version?: number; allowedActions?: string[]; evidenceFileIds?: string[]; handlingResult?: string | null; completedAt?: string | null
+}
+
+export interface ExceptionReturnSource { outboundPalletItemId: string; inventoryPositionId: string; palletNo?: string | null; skuCode?: string | null; maxReturnPackages: number }
+export interface ExceptionDetail { order: ExceptionOrderRow; returnSources: ExceptionReturnSource[] }
+export interface ExceptionReceipt { outboundPalletItemId: string; inventoryPositionId: string; receivedPackages: number; targetPalletId: string; targetPalletNo: string; targetLocationId: string; targetLocationCode: string }
+export interface ExceptionCommand { expectedVersion: number; idempotencyKey: string; handlingAction?: string; reason?: string; handlingResult?: string; evidenceFileIds?: string[]; receipts?: ExceptionReceipt[] }
+export type ExceptionAction = 'start-processing' | 'complete' | 'cancel'
+export interface ExceptionCommandResult { exceptionNo: string; status: string; version: number; restoredPackages: number; replayed: boolean }
+const exceptionPath = (number: string) => `/platform/v1/last-leg/exception-orders/${encodeURIComponent(number)}`
+function safeInteger(value: unknown, label: string) {
+  if ((typeof value !== 'number' && typeof value !== 'string') || !/^\d+$/.test(String(value)) || !Number.isSafeInteger(Number(value))) throw new Error(`${label}无效，请重新加载`)
+  return Number(value)
+}
+export function normalizeExceptionDetail(value: ExceptionDetail): ExceptionDetail {
+  return { ...value, order: { ...value.order, version: safeInteger(value.order.version, '异常版本'), evidenceFileIds: value.order.evidenceFileIds?.map(String) },
+    returnSources: value.returnSources.map(row => ({ ...row, outboundPalletItemId: String(row.outboundPalletItemId), inventoryPositionId: String(row.inventoryPositionId), maxReturnPackages: safeInteger(row.maxReturnPackages, '剩余可收数量') })) }
+}
+export async function getExceptionDetail(customerId: string, exceptionNo: string) {
+  const response = await http.get<ApiEnvelope<ExceptionDetail>, ApiEnvelope<ExceptionDetail>>(exceptionPath(exceptionNo), { params: { customerId } })
+  return normalizeExceptionDetail(unwrapApiResponse(response))
+}
+export async function commandException(customerId: string, exceptionNo: string, action: ExceptionAction, payload: ExceptionCommand) {
+  const response = await http.post<ApiEnvelope<ExceptionCommandResult>, ApiEnvelope<ExceptionCommandResult>>(`${exceptionPath(exceptionNo)}/${action}`, payload, { params: { customerId } })
+  const result = unwrapApiResponse(response)
+  return { ...result, version: safeInteger(result.version, '操作版本'), restoredPackages: safeInteger(result.restoredPackages, '实际入账数量') }
+}
+export async function uploadExceptionEvidence(customerId: string, exceptionNo: string, file: File) {
+  const form = new FormData(); form.append('file', file)
+  const response = await http.post<ApiEnvelope<{ fileId: string; fileName: string }>, ApiEnvelope<{ fileId: string; fileName: string }>>(`${exceptionPath(exceptionNo)}/evidence`, form, { params: { customerId } })
+  return unwrapApiResponse(response)
 }
 export interface ExceptionRelation {
   lastMileOrderId?: string | null; lastMileOrderNo?: string | null; inboundOrderId?: string | null; inboundCode?: string | null