fix(delivery): version status commands and manage three document categories

src/modules/overseas-warehouse/api/customerVisits.test.ts

@@ -29,8 +29,8 @@ describe('customer visit API', () => {
 
   it('updates delivery status so selecting delivered can generate a visit', async () => {
     vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', data: { deliveryStatus: 'DELIVERED' } })
-    await updateDeliveryOrderStatus('DEL/1', '100', { status: 'DELIVERED', remark: '完成' })
-    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DEL%2F1/status', { status: 'DELIVERED', remark: '完成' }, { params: { customerId: '100' } })
+    await updateDeliveryOrderStatus('DEL/1', '100', { status: 'DELIVERED', expectedVersion: 7, remark: '完成' })
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DEL%2F1/status', { status: 'DELIVERED', expectedVersion: 7, remark: '完成' }, { params: { customerId: '100' } })
   })
 
   it('uploads and saves repeatable visit material', async () => {

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

@@ -107,7 +107,7 @@ export async function completeDeliveryOrder(deliveryNo: string, customerId: stri
   return unwrapApiResponse(response)
 }
 
-export async function updateDeliveryOrderStatus(deliveryNo: string, customerId: string, payload: { status: string; remark?: string }) {
+export async function updateDeliveryOrderStatus(deliveryNo: string, customerId: string, payload: { status: string; expectedVersion: number; remark?: string }) {
   const response = await overseasHttp.put<ApiEnvelope<{ visitId?: string | null; deliveryNo: string; deliveryStatus: string; visitStatus?: string | null; replayed: boolean }>, ApiEnvelope<{ visitId?: string | null; deliveryNo: string; deliveryStatus: string; visitStatus?: string | null; replayed: boolean }>>(
     `/platform/v1/last-leg/delivery-orders/${encodeURIComponent(deliveryNo)}/status`, payload,
     { params: { customerId } },

src/modules/overseas-warehouse/api/deliveryDocuments.test.ts

@@ -0,0 +1,28 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { deliveryDocumentCategories, getDeliveryDocuments, saveDeliveryDocuments, uploadDeliveryDocument, downloadDeliveryDocument } from './deliveryDocuments'
+vi.mock('@/shared/api/overseasHttp', () => ({ overseasHttp: { get: vi.fn(), post: vi.fn(), put: vi.fn() } }))
+describe('delivery document API', () => {
+  beforeEach(() => vi.clearAllMocks())
+  it('scopes reads and full three-category snapshots by customer and delivery number', async () => {
+    vi.mocked(overseasHttp.get).mockResolvedValue({ code: '200', data: {} })
+    vi.mocked(overseasHttp.put).mockResolvedValue({ code: '200', data: {} })
+    await getDeliveryDocuments('DL/1', '9007199254740993')
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DL%2F1/documents', { params: { customerId: '9007199254740993' } })
+    const body = { expectedVersion: 8, idempotencyKey: 'save-1', bolNo: null, documents: deliveryDocumentCategories.map(item => ({ category: item.category, fileIds: [] })) }
+    await saveDeliveryDocuments('DL/1', '9007199254740993', body)
+    expect(overseasHttp.put).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DL%2F1/documents', body, { params: { customerId: '9007199254740993' } })
+  })
+  it('uploads only the file and downloads through the authenticated category endpoint', async () => {
+    vi.mocked(overseasHttp.post).mockResolvedValue({ code: '200', data: { fileId: '9007199254740995' } })
+    const file = new File(['data'], 'proof.bin')
+    await uploadDeliveryDocument('DL/1', '100', 'RECEIPT', file)
+    const [url, body, config] = vi.mocked(overseasHttp.post).mock.calls[0]!
+    expect(url).toBe('/platform/v1/last-leg/delivery-orders/DL%2F1/documents/RECEIPT/files')
+    expect(Array.from((body as FormData).keys())).toEqual(['file'])
+    expect((body as FormData).get('file')).toBe(file)
+    expect(config).toEqual({ params: { customerId: '100' } })
+    await downloadDeliveryDocument('DL/1', '100', 'RECEIPT', '9007199254740995')
+    expect(overseasHttp.get).toHaveBeenCalledWith('/platform/v1/last-leg/delivery-orders/DL%2F1/documents/RECEIPT/files/9007199254740995/download', { params: { customerId: '100' }, responseType: 'blob' })
+  })
+})

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

@@ -0,0 +1,33 @@
+import { overseasHttp } from '@/shared/api/overseasHttp'
+import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+
+export const deliveryDocumentCategories = [
+  { category: 'LOADING_PHOTO', label: '装车照片' },
+  { category: 'BOL', label: 'BOL文件（含签名）' },
+  { category: 'RECEIPT', label: '签收文件（POD签收/快递签收）' },
+] as const
+export type DeliveryDocumentCategory = typeof deliveryDocumentCategories[number]['category']
+export interface DeliveryDocumentFile { fileId: string; fileName: string; contentType: string | null; sizeBytes: number; uploadedAt: string }
+export interface DeliveryDocumentCategorySummary { category: DeliveryDocumentCategory; status: 'UPLOADED' | 'MISSING'; fileCount: number }
+export interface DeliveryDocumentSummary { uploadedCategoryCount: number; totalCategoryCount: number; categories: DeliveryDocumentCategorySummary[] }
+export interface DeliveryDocuments extends DeliveryDocumentSummary {
+  deliveryNo: string; customerId: string; version: number; bolNo: string | null
+  categories: Array<DeliveryDocumentCategorySummary & { files: DeliveryDocumentFile[] }>
+  allowedActions: string[]; replayed: boolean
+}
+export interface SaveDeliveryDocuments { expectedVersion: number; idempotencyKey: string; bolNo: string | null; documents: Array<{ category: DeliveryDocumentCategory; fileIds: string[] }> }
+const path = (deliveryNo: string) => `/platform/v1/last-leg/delivery-orders/${encodeURIComponent(deliveryNo)}/documents`
+export async function getDeliveryDocuments(deliveryNo: string, customerId: string) {
+  return unwrapApiResponse(await overseasHttp.get<ApiEnvelope<DeliveryDocuments>, ApiEnvelope<DeliveryDocuments>>(path(deliveryNo), { params: { customerId } }))
+}
+export async function saveDeliveryDocuments(deliveryNo: string, customerId: string, body: SaveDeliveryDocuments) {
+  return unwrapApiResponse(await overseasHttp.put<ApiEnvelope<DeliveryDocuments>, ApiEnvelope<DeliveryDocuments>>(path(deliveryNo), body, { params: { customerId } }))
+}
+export async function uploadDeliveryDocument(deliveryNo: string, customerId: string, category: DeliveryDocumentCategory, file: File) {
+  const body = new FormData()
+  body.append('file', file)
+  return unwrapApiResponse(await overseasHttp.post<ApiEnvelope<DeliveryDocumentFile>, ApiEnvelope<DeliveryDocumentFile>>(`${path(deliveryNo)}/${category}/files`, body, { params: { customerId } }))
+}
+export async function downloadDeliveryDocument(deliveryNo: string, customerId: string, category: DeliveryDocumentCategory, fileId: string) {
+  return overseasHttp.get<Blob, Blob>(`${path(deliveryNo)}/${category}/files/${encodeURIComponent(fileId)}/download`, { params: { customerId }, responseType: 'blob' })
+}

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

@@ -2,6 +2,7 @@ import { overseasHttp } from '@/shared/api/overseasHttp'
 import { unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
 import { normalizeOverseasPage, type OverseasPagePayload } from './lastMileOrders'
 import type { ExceptionRelation } from './exceptionOrders'
+import type { DeliveryDocumentSummary } from './deliveryDocuments'
 
 export interface DeliveryOrderQuery {
   page: number
@@ -20,6 +21,10 @@ export interface DeliveryOrderQuery {
 }
 
 export interface DeliveryOrderRow {
+  version: number
+  allowedActions: string[]
+  bolNo?: string | null
+  documentSummary?: DeliveryDocumentSummary
   id: string
   customerId: string
   customerName?: string | null