feat(admin): bind booking documents and truck containers

src/modules/ocean-bookings/api/platformOceanBookings.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { createOceanBooking, deleteOceanBookingDraft, listOceanBookingAgents, listOceanBookingLinkCandidates, listOceanBookings, listWarehouseLogisticsChannels, releaseOceanBooking, updateOceanBookingDraft } from './platformOceanBookings'
+import { createOceanBooking, deleteOceanBookingDraft, downloadOceanBookingDocument, downloadOceanBookingPrint, invalidateOceanBookingDocument, listOceanBookingAgents, listOceanBookingDocuments, listOceanBookingLinkCandidates, listOceanBookings, listWarehouseLogisticsChannels, referenceOceanBookingDocument, releaseOceanBooking, updateOceanBookingDraft, uploadOceanBookingDocument } from './platformOceanBookings'
 import { http } from '@/shared/api/http'
 
 const detailResponse = (version = 0, status = 'DRAFT') => ({
@@ -9,6 +9,7 @@ const detailResponse = (version = 0, status = 'DRAFT') => ({
   parties: [],
   containerRequirements: [{ id: 9007199254740994, oceanBookingId: 123, containerType: '40HC', containerKind: 'FCL', quantity: 2, capacityCbm: 76, maxWeightKg: 28000 }],
   containers: [{ containerBookingId: 9007199254740993, cabinetNo: 'CAB-1', containerNo: 'MSCU1234567', requirementId: 9007199254740994, allocationId: 9007199254740995, containerType: '40HC', containerKind: 'FCL', capacityCbm: 76, maxWeightKg: 28000, warehouseId: 9007199254740996, warehouseName: '义乌仓', channelCode: 'SEA', channelName: '海运', customerId: 456, customerName: '客户' }],
+  documents: [{ id: 9007199254740997, oceanBookingId: 123, fileId: 9007199254740998, documentType: 'BOOKING_CONFIRMATION', fileName: '订舱确认.pdf', fileHash: null, sizeBytes: '128', contentType: 'application/pdf', valid: true, uploadedBy: 7, uploadedByName: '平台', uploadedAt: '2026-08-31T10:00:00', invalidatedBy: null, invalidatedByName: null, invalidatedAt: null }],
   histories: [],
 })
 
@@ -48,6 +49,7 @@ describe('ocean bookings api', () => {
     expect(created.status).toBe('DRAFT')
     expect(created.containerRequirements[0]).toMatchObject({ id: '9007199254740994', requirementId: '9007199254740994', quantity: 2 })
     expect(created.containers[0]).toMatchObject({ containerBookingId: '9007199254740992', requirementId: '9007199254740994' })
+    expect(created.documents[0]).toMatchObject({ id: '9007199254740996', oceanBookingId: '123', fileId: '9007199254740998', sizeBytes: 128, uploadedBy: '7' })
   })
 
   it('uses draft update, delete and release contracts without legacy actions', async () => {
@@ -79,4 +81,45 @@ describe('ocean bookings api', () => {
     vi.spyOn(http, 'get').mockResolvedValue({ code: '200', message: 'ok', data: [] })
     await expect(listOceanBookingAgents('HEDE')).resolves.toEqual([])
   })
+
+  it('downloads both booking PDF documents from their dedicated public endpoints', async () => {
+    const get = vi.spyOn(http, 'get').mockResolvedValue(new Blob(['pdf'], { type: 'application/pdf' }))
+    await downloadOceanBookingPrint('123/456', 'SHIPPING_INSTRUCTION')
+    await downloadOceanBookingPrint('123/456', 'BILL_OF_LADING_CONFIRMATION')
+    expect(get).toHaveBeenNthCalledWith(1, '/platform/v1/ocean-bookings/123%2F456/prints/shipping-instruction', { responseType: 'blob' })
+    expect(get).toHaveBeenNthCalledWith(2, '/platform/v1/ocean-bookings/123%2F456/prints/bill-of-lading-confirmation', { responseType: 'blob' })
+  })
+
+  it('uses the booking-owned document list, upload, reference, invalidate and download contracts', async () => {
+    const rawDocument = { id: 9007199254740993n, oceanBookingId: 123, fileId: 9007199254740995n, documentType: 'BOOKING_CONFIRMATION', fileName: '订舱确认.pdf', fileHash: null, sizeBytes: '128', contentType: 'application/pdf', valid: true, uploadedBy: 7, uploadedByName: '平台', uploadedAt: '2026-08-31T10:00:00', invalidatedBy: null, invalidatedByName: null, invalidatedAt: null }
+    const get = vi.spyOn(http, 'get')
+      .mockResolvedValueOnce({ code: '200', data: [rawDocument] })
+      .mockResolvedValueOnce(new Blob(['pdf'], { type: 'application/pdf' }))
+    const post = vi.spyOn(http, 'post')
+      .mockResolvedValueOnce({ code: '200', data: { document: rawDocument, bookingVersion: '3' } })
+      .mockResolvedValueOnce({ code: '200', data: { document: rawDocument, bookingVersion: '4' } })
+    const remove = vi.spyOn(http, 'delete').mockResolvedValue({ code: '200', data: { documentId: 9007199254740993n, bookingVersion: '5' } })
+
+    await expect(listOceanBookingDocuments('123')).resolves.toMatchObject([{ id: '9007199254740993', oceanBookingId: '123', fileId: '9007199254740995', sizeBytes: 128, uploadedBy: '7' }])
+    await expect(referenceOceanBookingDocument('123', 2, '9007199254740995', 'BOOKING_CONFIRMATION')).resolves.toMatchObject({ bookingVersion: 3 })
+    const file = new File(['bill'], '提单.pdf', { type: 'application/pdf' })
+    await expect(uploadOceanBookingDocument('123', 3, 'BILL_OF_LADING', file)).resolves.toMatchObject({ bookingVersion: 4 })
+    const form = post.mock.calls[1]?.[1] as FormData
+    expect(form.get('expectedVersion')).toBe('3')
+    expect(form.get('documentType')).toBe('BILL_OF_LADING')
+    expect(form.get('file')).toBe(file)
+    await expect(invalidateOceanBookingDocument('123', '9007199254740993', 4)).resolves.toEqual({ documentId: '9007199254740993', bookingVersion: 5 })
+    await downloadOceanBookingDocument('123', '9007199254740993')
+
+    expect(get).toHaveBeenNthCalledWith(1, '/platform/v1/ocean-bookings/123/documents')
+    expect(post).toHaveBeenNthCalledWith(1, '/platform/v1/ocean-bookings/123/documents', { expectedVersion: 2, fileId: '9007199254740995', documentType: 'BOOKING_CONFIRMATION' }, { headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(post).toHaveBeenNthCalledWith(2, '/platform/v1/ocean-bookings/123/documents/upload', expect.any(FormData), { headers: { 'Content-Type': 'multipart/form-data', 'Idempotency-Key': expect.any(String) } })
+    expect(remove).toHaveBeenCalledWith('/platform/v1/ocean-bookings/123/documents/9007199254740993', { data: { expectedVersion: 4 }, headers: { 'Idempotency-Key': expect.any(String) } })
+    expect(get).toHaveBeenNthCalledWith(2, '/platform/v1/ocean-bookings/123/documents/9007199254740993/download', { responseType: 'blob' })
+  })
+
+  it('preserves request and trace ids when a PDF endpoint returns a JSON business envelope as a blob', async () => {
+    vi.spyOn(http, 'get').mockResolvedValueOnce(new Blob([JSON.stringify({ code: 'B0409', message: '订舱资料不完整', requestId: 'req-pdf', traceId: 'trace-pdf' })], { type: 'application/json' }))
+    await expect(downloadOceanBookingPrint('123', 'SHIPPING_INSTRUCTION')).rejects.toMatchObject({ code: 'B0409', message: '订舱资料不完整', requestId: 'req-pdf', traceId: 'trace-pdf' })
+  })
 })

src/modules/ocean-bookings/api/platformOceanBookings.ts

@@ -1,7 +1,9 @@
-import { http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
-import type { OceanBookingAgentOption, OceanBookingCarrierCode, OceanBookingDetail, OceanBookingLinkCandidatePage, OceanBookingLinkCandidateQuery, OceanBookingPage, OceanBookingQuery, OceanBookingResource, OceanBookingSaveRequest, OceanBookingStatus, OceanBookingReleaseRequest } from '../types'
+import axios from 'axios'
+import { ApiResponseError, http, unwrapApiResponse, type ApiEnvelope } from '@/shared/api/http'
+import type { OceanBookingAgentOption, OceanBookingCarrierCode, OceanBookingDetail, OceanBookingDocument, OceanBookingDocumentInvalidation, OceanBookingDocumentMutation, OceanBookingDocumentType, OceanBookingLinkCandidatePage, OceanBookingLinkCandidateQuery, OceanBookingPage, OceanBookingPrintType, OceanBookingQuery, OceanBookingResource, OceanBookingSaveRequest, OceanBookingStatus, OceanBookingReleaseRequest } from '../types'
 
 const basePath = '/platform/v1/ocean-bookings'
+const maxErrorEnvelopeBytes = 1024 * 1024
 
 export interface OceanLogisticsChannel {
   channelCode: string
@@ -51,6 +53,7 @@ function detail(raw: OceanBookingDetail): OceanBookingDetail {
       capacityCbm: Number(container.capacityCbm),
       maxWeightKg: Number(container.maxWeightKg),
     })),
+    documents: (raw.documents || []).map(document),
     histories,
     statusHistory: histories,
   }
@@ -87,7 +90,74 @@ export async function createOceanBooking(payload: OceanBookingSaveRequest) { con
 export async function updateOceanBookingDraft(id: string, payload: OceanBookingSaveRequest) { const response = await http.put<ApiEnvelope<OceanBookingDetail>, ApiEnvelope<OceanBookingDetail>>(`${basePath}/${encodeURIComponent(id)}`, payload, { headers: { 'Idempotency-Key': idempotencyKey() } }); return detail(unwrapApiResponse(response)) }
 export async function deleteOceanBookingDraft(id: string, expectedVersion: number) { await http.delete(`${basePath}/${encodeURIComponent(id)}`, { data: { expectedVersion }, headers: { 'Idempotency-Key': idempotencyKey() } }) }
 export async function releaseOceanBooking(id: string, request: OceanBookingReleaseRequest) { const response = await http.post<ApiEnvelope<OceanBookingDetail>, ApiEnvelope<OceanBookingDetail>>(`${basePath}/${encodeURIComponent(id)}/release`, request, { headers: { 'Idempotency-Key': idempotencyKey() } }); return detail(unwrapApiResponse(response)) }
-export async function printOceanBooking(id: string, type: 'SHIPPING_INSTRUCTION' | 'BILL_CONFIRMATION') { return http.get<Blob, Blob>(`${basePath}/${encodeURIComponent(id)}/print`, { params: { type }, responseType: 'blob' }) }
+const printPaths: Record<OceanBookingPrintType, string> = {
+  SHIPPING_INSTRUCTION: 'shipping-instruction',
+  BILL_OF_LADING_CONFIRMATION: 'bill-of-lading-confirmation',
+}
+function document(raw: OceanBookingDocument): OceanBookingDocument {
+  return {
+    ...raw,
+    id: String(raw.id),
+    oceanBookingId: String(raw.oceanBookingId),
+    fileId: String(raw.fileId),
+    sizeBytes: raw.sizeBytes == null ? null : Number(raw.sizeBytes),
+    uploadedBy: String(raw.uploadedBy),
+    invalidatedBy: raw.invalidatedBy == null ? null : String(raw.invalidatedBy),
+  }
+}
+export async function downloadOceanBookingPrint(id: string, type: OceanBookingPrintType) {
+  return requestBlob(`${basePath}/${encodeURIComponent(id)}/prints/${printPaths[type]}`)
+}
+async function parseBlobError(blob: Blob, status?: number) {
+  if (!blob.type.toLowerCase().includes('json')) return null
+  if (blob.size > maxErrorEnvelopeBytes) return new ApiResponseError('文件接口返回了超出限制的 JSON 响应', 'INVALID_FILE_RESPONSE', status)
+  try {
+    const payload = JSON.parse(await blob.text()) as Partial<ApiEnvelope<unknown>>
+    return new ApiResponseError(payload.code === '200' ? '文件接口未返回文件内容' : payload.message || '文件请求失败', payload.code === '200' ? 'INVALID_FILE_RESPONSE' : payload.code || (status ? `HTTP_${status}` : 'FILE_REQUEST_FAILED'), status, payload.data, payload.requestId, payload.traceId)
+  } catch {
+    return new ApiResponseError('文件接口返回了无法识别的 JSON 响应', 'INVALID_FILE_RESPONSE', status)
+  }
+}
+async function requestBlob(path: string) {
+  try {
+    const blob = await http.get<Blob, Blob>(path, { responseType: 'blob' })
+    const responseError = await parseBlobError(blob, 200)
+    if (responseError) throw responseError
+    return blob
+  } catch (error) {
+    if (axios.isAxiosError(error) && error.response?.data instanceof Blob) {
+      const responseError = await parseBlobError(error.response.data, error.response.status)
+      if (responseError) throw responseError
+    }
+    throw error
+  }
+}
+export async function listOceanBookingDocuments(id: string) {
+  const response = await http.get<ApiEnvelope<OceanBookingDocument[]>, ApiEnvelope<OceanBookingDocument[]>>(`${basePath}/${encodeURIComponent(id)}/documents`)
+  return (unwrapApiResponse(response) || []).map(document)
+}
+export async function referenceOceanBookingDocument(id: string, expectedVersion: number, fileId: string, documentType: OceanBookingDocumentType) {
+  const response = await http.post<ApiEnvelope<OceanBookingDocumentMutation>, ApiEnvelope<OceanBookingDocumentMutation>>(`${basePath}/${encodeURIComponent(id)}/documents`, { expectedVersion, fileId, documentType }, { headers: { 'Idempotency-Key': idempotencyKey() } })
+  const result = unwrapApiResponse(response)
+  return { document: document(result.document), bookingVersion: Number(result.bookingVersion) }
+}
+export async function uploadOceanBookingDocument(id: string, expectedVersion: number, documentType: OceanBookingDocumentType, file: File) {
+  const form = new FormData()
+  form.append('expectedVersion', String(expectedVersion))
+  form.append('documentType', documentType)
+  form.append('file', file)
+  const response = await http.post<ApiEnvelope<OceanBookingDocumentMutation>, ApiEnvelope<OceanBookingDocumentMutation>>(`${basePath}/${encodeURIComponent(id)}/documents/upload`, form, { headers: { 'Content-Type': 'multipart/form-data', 'Idempotency-Key': idempotencyKey() } })
+  const result = unwrapApiResponse(response)
+  return { document: document(result.document), bookingVersion: Number(result.bookingVersion) }
+}
+export async function invalidateOceanBookingDocument(id: string, documentId: string, expectedVersion: number) {
+  const response = await http.delete<ApiEnvelope<OceanBookingDocumentInvalidation>, ApiEnvelope<OceanBookingDocumentInvalidation>>(`${basePath}/${encodeURIComponent(id)}/documents/${encodeURIComponent(documentId)}`, { data: { expectedVersion }, headers: { 'Idempotency-Key': idempotencyKey() } })
+  const result = unwrapApiResponse(response)
+  return { documentId: String(result.documentId), bookingVersion: Number(result.bookingVersion) }
+}
+export async function downloadOceanBookingDocument(id: string, documentId: string) {
+  return requestBlob(`${basePath}/${encodeURIComponent(id)}/documents/${encodeURIComponent(documentId)}/download`)
+}
 export async function listWarehouseLogisticsChannels(warehouseId: string): Promise<OceanLogisticsChannel[]> {
   const response = await http.get<ApiEnvelope<OceanLogisticsChannel[]>, ApiEnvelope<OceanLogisticsChannel[]>>(`${basePath}/channels`, { params: { originWarehouseId: warehouseId } })
   return (unwrapApiResponse(response) || []).map((item) => ({ channelCode: String(item.channelCode), channelName: String(item.channelName) }))

src/modules/ocean-bookings/components/OceanBookingDocumentsPanel.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+
+const source = readFileSync(resolve(process.cwd(), 'src/modules/ocean-bookings/components/OceanBookingDocumentsPanel.vue'), 'utf8')
+
+describe('OceanBookingDocumentsPanel contract', () => {
+  it('owns the two confirmed document types under the booking', () => {
+    expect(source).toContain("value: 'BOOKING_CONFIRMATION', label: '订舱确认文件'")
+    expect(source).toContain("value: 'BILL_OF_LADING', label: '提单文件'")
+    expect(source).toContain('文件统一归属当前订舱')
+    expect(source).not.toContain('TRUCK_APPOINTMENT_ATTACHMENT')
+  })
+
+  it('supports upload, replacement, logical invalidation and download with version chaining', () => {
+    expect(source).toContain('uploadOceanBookingDocument(props.bookingId, props.bookingVersion, type, file)')
+    expect(source).toContain('invalidateOceanBookingDocument(props.bookingId, item.id, version)')
+    expect(source).toContain('version = invalidated.bookingVersion')
+    expect(source).toContain('确认替换')
+    expect(source).toContain('确认作废')
+    expect(source).toContain('downloadOceanBookingDocument')
+    expect(source).toContain('URL.createObjectURL(blob)')
+  })
+
+  it('makes released booking files permanently read-only and preserves traced errors', () => {
+    expect(source).toContain("props.bookingStatus === 'DRAFT' && props.canManage")
+    expect(source).toContain('已放舱 · 永久只读')
+    expect(source).toContain('manageReason')
+    expect(source).toContain('<ApiErrorMeta :details="error" />')
+    expect(source).toContain('订舱资料上传失败，请稍后重试')
+    expect(source).toContain('订舱资料下载失败，请稍后重试')
+  })
+})

src/modules/ocean-bookings/components/OceanBookingDocumentsPanel.vue

@@ -0,0 +1,127 @@
+<script setup lang="ts">
+import { computed, ref } from 'vue'
+import { Download, FileUp, Trash2 } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { downloadOceanBookingDocument, invalidateOceanBookingDocument, uploadOceanBookingDocument } from '../api/platformOceanBookings'
+import type { OceanBookingDocument, OceanBookingDocumentType, OceanBookingStatus } from '../types'
+
+const props = defineProps<{ bookingId: string; bookingVersion: number; bookingStatus: OceanBookingStatus; documents: OceanBookingDocument[]; canManage: boolean; manageReason?: string }>()
+const emit = defineEmits<{ updated: [documents: OceanBookingDocument[], bookingVersion: number] }>()
+const busyType = ref<OceanBookingDocumentType | ''>('')
+const busyDocumentId = ref('')
+const error = ref<ApiErrorDetails | null>(null)
+const types: Array<{ value: OceanBookingDocumentType; label: string; description: string }> = [
+  { value: 'BOOKING_CONFIRMATION', label: '订舱确认文件', description: '用于确认已订妥舱位及放舱前资料完整性' },
+  { value: 'BILL_OF_LADING', label: '提单文件', description: '用于提单号和拖车派车前资料校验' },
+]
+const editable = computed(() => props.bookingStatus === 'DRAFT' && props.canManage)
+const validDocuments = computed(() => props.documents.filter((item) => item.valid))
+const invalidDocuments = computed(() => props.documents.filter((item) => !item.valid))
+
+function documentsOfType(type: OceanBookingDocumentType) { return validDocuments.value.filter((item) => item.documentType === type) }
+function fileSize(value: number | null) {
+  if (value == null) return '大小未知'
+  if (value < 1024) return `${value} B`
+  if (value < 1024 * 1024) return `${(value / 1024).toFixed(1)} KB`
+  return `${(value / 1024 / 1024).toFixed(1)} MB`
+}
+function saveBlob(blob: Blob, name: string) {
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = name || '订舱资料'
+  anchor.click()
+  URL.revokeObjectURL(url)
+}
+async function download(item: OceanBookingDocument) {
+  busyDocumentId.value = item.id
+  error.value = null
+  try {
+    saveBlob(await downloadOceanBookingDocument(props.bookingId, item.id), item.fileName)
+  } catch (cause) {
+    error.value = getApiErrorDetails(cause, '订舱资料下载失败，请稍后重试')
+  } finally {
+    busyDocumentId.value = ''
+  }
+}
+async function invalidate(item: OceanBookingDocument, expectedVersion = props.bookingVersion) {
+  const result = await invalidateOceanBookingDocument(props.bookingId, item.id, expectedVersion)
+  const nextDocuments = props.documents.map((document) => document.id === item.id ? { ...document, valid: false, invalidatedAt: new Date().toISOString() } : document)
+  emit('updated', nextDocuments, result.bookingVersion)
+  return { documents: nextDocuments, version: result.bookingVersion }
+}
+async function remove(item: OceanBookingDocument) {
+  try {
+    await ElMessageBox.confirm(`确认作废“${item.fileName}”？文件历史仍会保留。`, '作废订舱资料', { confirmButtonText: '确认作废', cancelButtonText: '取消', type: 'warning' })
+  } catch (cause) {
+    if (cause === 'cancel' || cause === 'close') return
+    throw cause
+  }
+  busyDocumentId.value = item.id
+  error.value = null
+  try {
+    await invalidate(item)
+    ElMessage.success('订舱资料已作废')
+  } catch (cause) {
+    error.value = getApiErrorDetails(cause, '订舱资料作废失败，请稍后重试')
+  } finally {
+    busyDocumentId.value = ''
+  }
+}
+async function selectFile(event: Event, type: OceanBookingDocumentType) {
+  const input = event.target as HTMLInputElement
+  const file = input.files?.[0]
+  input.value = ''
+  if (!file || !editable.value) return
+  const previous = documentsOfType(type)
+  if (previous.length) {
+    try {
+      await ElMessageBox.confirm(`将上传“${file.name}”并作废当前 ${previous.length} 份同类型文件，是否继续？`, '替换订舱资料', { confirmButtonText: '确认替换', cancelButtonText: '取消', type: 'warning' })
+    } catch (cause) {
+      if (cause === 'cancel' || cause === 'close') return
+      throw cause
+    }
+  }
+  busyType.value = type
+  error.value = null
+  try {
+    const uploaded = await uploadOceanBookingDocument(props.bookingId, props.bookingVersion, type, file)
+    let documents = [...props.documents, uploaded.document]
+    let version = uploaded.bookingVersion
+    emit('updated', documents, version)
+    for (const item of previous) {
+      const invalidated = await invalidateOceanBookingDocument(props.bookingId, item.id, version)
+      version = invalidated.bookingVersion
+      documents = documents.map((document) => document.id === item.id ? { ...document, valid: false, invalidatedAt: new Date().toISOString() } : document)
+      emit('updated', documents, version)
+    }
+    ElMessage.success(previous.length ? '订舱资料已替换' : '订舱资料已上传')
+  } catch (cause) {
+    error.value = getApiErrorDetails(cause, '订舱资料上传失败，请稍后重试')
+  } finally {
+    busyType.value = ''
+  }
+}
+</script>
+
+<template>
+  <section class="surface-panel booking-documents" aria-label="订舱资料">
+    <div class="booking-documents__heading"><div><h2>订舱资料</h2><p>文件统一归属当前订舱；放舱要求至少一份有效的订舱确认文件或提单文件。</p></div><el-tag v-if="bookingStatus === 'RELEASED'" type="info">已放舱 · 永久只读</el-tag></div>
+    <el-alert v-if="bookingStatus === 'DRAFT' && !editable && manageReason" type="warning" :closable="false" show-icon :title="manageReason" />
+    <el-alert v-if="error" type="error" :closable="true" show-icon @close="error = null"><template #title>{{ error.message }}</template><ApiErrorMeta :details="error" /></el-alert>
+    <div class="booking-document-types">
+      <article v-for="type in types" :key="type.value" class="booking-document-card">
+        <div class="booking-document-card__heading"><div><h3>{{ type.label }}</h3><p>{{ type.description }}</p></div><label v-if="editable" class="booking-document-upload" :class="{ 'is-disabled': Boolean(busyType || busyDocumentId) }"><FileUp :size="15" /><span>{{ busyType === type.value ? '上传处理中' : (documentsOfType(type.value).length ? '替换文件' : '上传文件') }}</span><input type="file" accept=".pdf,.jpg,.jpeg,.png,application/pdf,image/jpeg,image/png" :disabled="Boolean(busyType || busyDocumentId)" @change="selectFile($event, type.value)" /></label></div>
+        <el-empty v-if="!documentsOfType(type.value).length" description="暂无有效文件" :image-size="48" />
+        <ul v-else class="booking-document-list"><li v-for="item in documentsOfType(type.value)" :key="item.id"><div><strong :title="item.fileName">{{ item.fileName }}</strong><small>{{ fileSize(item.sizeBytes) }} · {{ item.uploadedByName || item.uploadedBy }} · {{ item.uploadedAt }}</small></div><div class="booking-document-actions"><el-button size="small" plain :loading="busyDocumentId === item.id" @click="download(item)"><Download :size="14" />下载</el-button><el-button v-if="editable" size="small" type="danger" plain :loading="busyDocumentId === item.id" @click="remove(item)"><Trash2 :size="14" />作废</el-button></div></li></ul>
+      </article>
+    </div>
+    <details v-if="invalidDocuments.length" class="booking-document-history"><summary>查看已作废资料（{{ invalidDocuments.length }}）</summary><ul><li v-for="item in invalidDocuments" :key="item.id"><span>{{ item.fileName }}</span><small>{{ item.invalidatedByName || item.invalidatedBy || '系统' }} · {{ item.invalidatedAt || '—' }}</small></li></ul></details>
+  </section>
+</template>
+
+<style scoped>
+.booking-documents{padding:16px}.booking-documents__heading,.booking-document-card__heading,.booking-document-list li,.booking-document-actions{display:flex;align-items:center}.booking-documents__heading,.booking-document-card__heading,.booking-document-list li{justify-content:space-between;gap:16px}.booking-documents__heading{margin-bottom:14px}.booking-documents h2,.booking-document-card h3{margin:0}.booking-documents__heading h2{font-size:16px}.booking-documents__heading p,.booking-document-card__heading p{margin:4px 0 0;color:var(--cc-muted);font-size:12px}.booking-document-types{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:14px}.booking-document-card{min-width:0;padding:14px;border:1px solid var(--cc-border);border-radius:8px}.booking-document-card h3{font-size:14px}.booking-document-upload{display:flex;flex:0 0 auto;align-items:center;gap:6px;min-height:32px;padding:0 12px;border:1px solid var(--cc-primary);border-radius:6px;color:var(--cc-primary);font-size:12px;cursor:pointer}.booking-document-upload.is-disabled{cursor:not-allowed;opacity:.55}.booking-document-upload input{position:absolute;width:1px;height:1px;overflow:hidden;opacity:0}.booking-document-list,.booking-document-history ul{display:grid;gap:8px;margin:12px 0 0;padding:0;list-style:none}.booking-document-list li{min-width:0;padding:9px 10px;border-radius:6px;background:var(--el-fill-color-lighter)}.booking-document-list li>div:first-child{display:grid;min-width:0;gap:3px}.booking-document-list strong{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.booking-document-list small,.booking-document-history small{color:var(--cc-muted);font-size:11px}.booking-document-actions{flex:0 0 auto;gap:6px}.booking-document-actions :deep(.el-button){margin-left:0}.booking-document-history{margin-top:14px;color:var(--cc-muted);font-size:12px}.booking-document-history summary{cursor:pointer}.booking-document-history li{display:flex;justify-content:space-between;gap:12px;padding:7px 10px;border-bottom:1px solid var(--cc-border)}@media(max-width:900px){.booking-document-types{grid-template-columns:1fr}}@media(max-width:560px){.booking-documents__heading,.booking-document-card__heading,.booking-document-list li{align-items:flex-start;flex-direction:column}.booking-document-actions{width:100%}}
+</style>

src/modules/ocean-bookings/components/OceanBookingPrintDialog.test.ts

@@ -0,0 +1,57 @@
+import ElementPlus from 'element-plus'
+import { flushPromises, mount } from '@vue/test-utils'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import OceanBookingPrintDialog from './OceanBookingPrintDialog.vue'
+import { downloadOceanBookingPrint } from '../api/platformOceanBookings'
+import { ApiResponseError } from '@/shared/api/http'
+
+vi.mock('../api/platformOceanBookings', () => ({ downloadOceanBookingPrint: vi.fn() }))
+
+describe('OceanBookingPrintDialog', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    document.body.innerHTML = ''
+    vi.stubGlobal('URL', { createObjectURL: vi.fn(() => 'blob:booking-print'), revokeObjectURL: vi.fn() })
+  })
+
+  it('offers the two confirmed documents and previews the selected PDF', async () => {
+    vi.mocked(downloadOceanBookingPrint).mockResolvedValue(new Blob(['pdf'], { type: 'application/pdf' }))
+    const wrapper = mount(OceanBookingPrintDialog, {
+      props: { modelValue: true, bookingId: '123', bookingNo: 'OB-123', allowed: true },
+      global: { plugins: [ElementPlus] },
+      attachTo: document.body,
+    })
+    await flushPromises()
+
+    expect(document.body.textContent).toContain('出口货物托运单')
+    expect(document.body.textContent).toContain('提单确认件')
+    await wrapper.findAll('.booking-print-option')[0]!.trigger('click')
+    await flushPromises()
+    await Array.from(document.body.querySelectorAll('button')).find((button) => button.textContent?.includes('预览 PDF'))?.click()
+    await flushPromises()
+
+    expect(downloadOceanBookingPrint).toHaveBeenCalledWith('123', 'SHIPPING_INSTRUCTION')
+    expect(document.body.querySelector('iframe')?.getAttribute('src')).toBe('blob:booking-print')
+    wrapper.unmount()
+  })
+
+  it('shows permission and API errors without attempting a download', async () => {
+    const denied = mount(OceanBookingPrintDialog, { props: { modelValue: true, bookingId: '123', allowed: false }, global: { plugins: [ElementPlus] }, attachTo: document.body })
+    await flushPromises()
+    expect(document.body.textContent).toContain('暂无订舱单据打印权限')
+    expect(downloadOceanBookingPrint).not.toHaveBeenCalled()
+    denied.unmount()
+
+    vi.mocked(downloadOceanBookingPrint).mockRejectedValue(new ApiResponseError('缺少提单号', 'B0409', 200, undefined, 'req-print', 'trace-print'))
+    const failed = mount(OceanBookingPrintDialog, { props: { modelValue: true, bookingId: '123', allowed: true }, global: { plugins: [ElementPlus] }, attachTo: document.body })
+    await flushPromises()
+    await failed.findAll('.booking-print-option')[1]!.trigger('click')
+    await flushPromises()
+    await Array.from(document.body.querySelectorAll('button')).find((button) => button.textContent?.includes('预览 PDF'))?.click()
+    await flushPromises()
+    expect(document.body.textContent).toContain('缺少提单号')
+    expect(document.body.textContent).toContain('req-print')
+    expect(document.body.textContent).toContain('trace-print')
+    failed.unmount()
+  })
+})

src/modules/ocean-bookings/components/OceanBookingPrintDialog.vue

@@ -0,0 +1,108 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref, watch } from 'vue'
+import { Download, FileText } from '@lucide/vue'
+import AppDialog from '@/shared/components/AppDialog.vue'
+import ApiErrorMeta from '@/shared/components/ApiErrorMeta.vue'
+import LoadErrorState from '@/shared/components/LoadErrorState.vue'
+import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
+import { downloadOceanBookingPrint } from '../api/platformOceanBookings'
+import type { OceanBookingPrintType } from '../types'
+
+const props = defineProps<{ bookingId: string; bookingNo?: string | null; allowed: boolean }>()
+const open = defineModel<boolean>({ default: false })
+const selectedType = ref<OceanBookingPrintType | ''>('')
+const loading = ref(false)
+const previewUrl = ref('')
+const printBlob = ref<Blob | null>(null)
+const error = ref<ApiErrorDetails | null>(null)
+
+const options: Array<{ value: OceanBookingPrintType; label: string; description: string }> = [
+  { value: 'SHIPPING_INSTRUCTION', label: '出口货物托运单', description: 'Sea Freight Shipping Instructions · PDF' },
+  { value: 'BILL_OF_LADING_CONFIRMATION', label: '提单确认件', description: '提单内容确认及打印 · PDF' },
+]
+const selectedOption = computed(() => options.find((item) => item.value === selectedType.value) || null)
+const previewTitle = computed(() => `${selectedOption.value?.label || '打印单据'} · ${props.bookingNo || props.bookingId}`)
+
+function releasePreview() {
+  if (previewUrl.value) URL.revokeObjectURL(previewUrl.value)
+  previewUrl.value = ''
+  printBlob.value = null
+}
+function reset() {
+  releasePreview()
+  selectedType.value = ''
+  error.value = null
+  loading.value = false
+}
+async function preview() {
+  if (!props.allowed || !selectedType.value || loading.value) return
+  loading.value = true
+  error.value = null
+  releasePreview()
+  try {
+    const blob = await downloadOceanBookingPrint(props.bookingId, selectedType.value)
+    printBlob.value = blob
+    previewUrl.value = URL.createObjectURL(blob)
+  } catch (cause) {
+    error.value = getApiErrorDetails(cause, '打印单据加载失败，请稍后重试')
+  } finally {
+    loading.value = false
+  }
+}
+function backToSelection() {
+  releasePreview()
+  error.value = null
+}
+function download() {
+  if (!printBlob.value || !selectedOption.value) return
+  const url = URL.createObjectURL(printBlob.value)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = `${props.bookingNo || props.bookingId}-${selectedOption.value.label}.pdf`
+  anchor.click()
+  URL.revokeObjectURL(url)
+}
+
+watch(open, (value) => { if (!value) reset() })
+onBeforeUnmount(releasePreview)
+</script>
+
+<template>
+  <AppDialog
+    v-model="open"
+    :title="previewUrl ? previewTitle : '选择打印单据'"
+    width="min(1120px, calc(100vw - 48px))"
+    :loading="loading"
+    :show-confirm="false"
+    :cancel-text="previewUrl ? '关闭预览' : '取消'"
+    destroy-on-close
+  >
+    <el-alert v-if="!allowed" title="暂无订舱单据打印权限" type="warning" :closable="false" show-icon />
+    <template v-else-if="!previewUrl">
+      <p class="booking-print-current">当前订舱：<strong>{{ bookingNo || bookingId }}</strong></p>
+      <div class="booking-print-options" role="radiogroup" aria-label="打印单据类型">
+        <label v-for="item in options" :key="item.value" class="booking-print-option" :class="{ 'is-selected': selectedType === item.value }">
+          <el-radio v-model="selectedType" :value="item.value"><span class="sr-only">{{ item.label }}</span></el-radio>
+          <FileText :size="22" />
+          <span><strong>{{ item.label }}</strong><small>{{ item.description }}</small></span>
+        </label>
+      </div>
+      <LoadErrorState v-if="error" title="打印单据加载失败" :message="error.message" :show-retry="false"><template #details><ApiErrorMeta :details="error" /></template></LoadErrorState>
+    </template>
+    <div v-else class="booking-print-preview" :aria-label="previewTitle">
+      <iframe :src="previewUrl" :title="`${previewTitle} PDF 预览`" />
+    </div>
+    <template #footer="{ close }">
+      <div class="app-dialog__footer booking-print-footer">
+        <el-button v-if="previewUrl" :disabled="loading" @click="backToSelection">返回选择</el-button>
+        <el-button v-else :disabled="loading" @click="close">取消</el-button>
+        <el-button v-if="previewUrl" type="primary" :disabled="!printBlob" @click="download"><Download :size="16" />下载 PDF</el-button>
+        <el-button v-else type="primary" :loading="loading" :disabled="!allowed || !selectedType" @click="preview">预览 PDF</el-button>
+      </div>
+    </template>
+  </AppDialog>
+</template>
+
+<style scoped>
+.booking-print-current{margin:0 0 16px;color:var(--cc-muted);font-size:13px}.booking-print-current strong{color:var(--cc-text)}.booking-print-options{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.booking-print-option{display:grid;grid-template-columns:auto auto minmax(0,1fr);align-items:center;gap:12px;min-height:92px;padding:16px;border:1px solid var(--cc-border);border-radius:10px;background:#fff;cursor:pointer}.booking-print-option.is-selected{border-color:var(--cc-primary);background:var(--cc-primary-soft)}.booking-print-option span{display:grid;min-width:0;gap:4px}.booking-print-option strong{color:var(--cc-text);font-size:15px}.booking-print-option small{color:var(--cc-muted);font-size:12px}.booking-print-preview{min-height:0;overflow:hidden;border:1px solid var(--cc-border);border-radius:8px;background:#f3f5f8}.booking-print-preview iframe{display:block;width:100%;height:min(72vh,760px);border:0;background:#fff}.booking-print-footer{width:100%}.sr-only{position:absolute;width:1px;height:1px;padding:0;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}@media(max-width:720px){.booking-print-options{grid-template-columns:1fr}.booking-print-preview iframe{height:68vh}}
+</style>

src/modules/ocean-bookings/pages/OceanBookingDetailView.release.test.ts

@@ -54,7 +54,9 @@ function booking(status: OceanBookingStatus = 'DRAFT', version = 3, billOfLading
       { partyType: 'NOTIFY_PARTY', partyName: '通知人' },
     ],
     containerRequirements: [{ requirementId: '31', containerType: '40HC', containerKind: 'FCL', quantity: 2, remainingQuantity: 2, capacityCbm: 76, maxWeightKg: 28000 }],
-    containers: [], histories: [], statusHistory: [],
+    containers: [],
+    documents: [{ id: '41', oceanBookingId: '123', fileId: '51', documentType: 'BOOKING_CONFIRMATION', fileName: '订舱确认.pdf', fileHash: null, sizeBytes: 128, contentType: 'application/pdf', valid: true, uploadedBy: '7', uploadedByName: '平台', uploadedAt: '2026-08-31T10:00:00', invalidatedBy: null, invalidatedByName: null, invalidatedAt: null }],
+    histories: [], statusHistory: [],
   }
 }
 

src/modules/ocean-bookings/pages/OceanBookingDetailView.test.ts

@@ -70,6 +70,9 @@ describe('OceanBookingDetailView draft and release contract', () => {
     expect(source).toContain('const workflowBusy = computed(() => saving.value || actionSaving.value)')
     expect(source).toContain(':disabled="workflowBusy" @click="openReleaseDialog"')
     expect(source).not.toContain('releaseReason')
+    expect(source).toContain('放舱前请上传有效的订舱确认文件或提单文件')
+    expect(source).toContain('OceanBookingDocumentsPanel')
+    expect(source).toContain('@updated="updateDocuments"')
   })
 
   it('freezes the selected carrier standard code into the booking draft', () => {
@@ -105,6 +108,8 @@ describe('OceanBookingDetailView draft and release contract', () => {
     expect(source).toContain('LoadErrorState')
     expect(source).toContain('@media(max-width:720px)')
     expect(source).toContain('@media(max-width:420px)')
+    expect(source).toContain('OceanBookingPrintDialog')
+    expect(source).toContain('打印单据')
   })
 
   it('carries the existing read-only CarrierScheduleQuery on the booking detail page', () => {

src/modules/ocean-bookings/pages/OceanBookingDetailView.vue

@@ -2,7 +2,7 @@
 import { computed, onMounted, reactive, ref } from 'vue'
 import { ElMessage, ElMessageBox, type FormInstance, type FormRules } from 'element-plus'
 import { useRoute, useRouter } from 'vue-router'
-import { ArrowLeft, Plus, Save, Trash2 } from '@lucide/vue'
+import { ArrowLeft, Plus, Printer, Save, Trash2 } from '@lucide/vue'
 import { useAccessPreviewStore } from '@/core/access/accessPreview'
 import { useWorkspaceTabsStore } from '@/core/workspace-tabs/workspaceTabs'
 import { getApiErrorDetails, type ApiErrorDetails } from '@/shared/api/http'
@@ -34,6 +34,7 @@ import type {
   OceanBookingAgentOption,
   OceanBookingCarrierCode,
   OceanBookingDraftData,
+  OceanBookingDocument,
   OceanBookingParty,
   OceanBookingSaveRequest,
   OceanBookingStatus,
@@ -41,6 +42,8 @@ import type {
 import { oceanBookingStatusLabel } from '../status'
 import { containerRequirementError, createBlankContainerRequirement, selectContainerRequirementType } from '../containerRequirements'
 import { shouldClearBookingAgent } from '../bookingAgents'
+import OceanBookingPrintDialog from '../components/OceanBookingPrintDialog.vue'
+import OceanBookingDocumentsPanel from '../components/OceanBookingDocumentsPanel.vue'
 
 const partyTypes = [
   { value: 'SHIPPER', label: '发货人' },
@@ -103,8 +106,12 @@ const editable = computed(() => isNew.value || detail.value?.status === 'DRAFT')
 const canSave = computed(() => editable.value && access.can(isNew.value ? 'platform:firstleg:ocean-booking:create' : 'platform:firstleg:ocean-booking:edit'))
 const canDelete = computed(() => detail.value?.status === 'DRAFT' && access.can('platform:firstleg:ocean-booking:delete'))
 const canRelease = computed(() => detail.value?.status === 'DRAFT' && access.can('platform:firstleg:ocean-booking:release'))
+const canPrint = computed(() => detail.value?.status === 'RELEASED' && access.can('platform:firstleg:ocean-booking:list'))
+const canManageDocuments = computed(() => detail.value?.status === 'DRAFT' && Boolean(detail.value.customerId) && access.can('platform:firstleg:ocean-booking:edit'))
+const documentManageReason = computed(() => !access.can('platform:firstleg:ocean-booking:edit') ? '暂无订舱资料维护权限' : !detail.value?.customerId ? '请先选择客户并保存订舱草稿，再上传订舱资料' : '')
 const workflowBusy = computed(() => saving.value || actionSaving.value)
 const releaseDialogOpen = ref(false)
+const printOpen = ref(false)
 
 function statusLabel(status: OceanBookingStatus | string | null | undefined) {
   return oceanBookingStatusLabel(status)
@@ -303,8 +310,16 @@ function releaseValidationError() {
   if (missing) return `放舱前请填写${missing[1]}`
   if (form.data.estimatedArrivalAt! < form.data.estimatedSailingAt!) return '预计到港时间不能早于预计开船时间'
   if (form.data.parties.some((party) => !party.partyName.trim())) return '放舱前请填写发货人、收货人和通知人名称'
+  if (!detail.value?.documents.some((document) => document.valid && ['BOOKING_CONFIRMATION', 'BILL_OF_LADING'].includes(document.documentType))) return '放舱前请上传有效的订舱确认文件或提单文件'
   return containerRequirementError(form.data.containerRequirements)
 }
+function updateDocuments(documents: OceanBookingDocument[], bookingVersion: number) {
+  if (!detail.value) return
+  detail.value.documents = documents
+  detail.value.version = bookingVersion
+  detail.value.oceanBooking.version = bookingVersion
+  form.expectedVersion = bookingVersion
+}
 async function submitRelease() {
   if (!detail.value || workflowBusy.value) return
   actionSaving.value = true
@@ -366,6 +381,7 @@ onMounted(() => { void load(); void loadOptions() })
         <div class="section-title">
           <div><h2>订舱信息</h2><p v-if="detail?.status === 'DRAFT'">草稿可反复保存；放舱后资料同步至关联货柜并锁定。</p><p v-else-if="detail">已放舱资料只读。</p></div>
           <div class="actions">
+            <el-tooltip :content="canPrint ? '选择出口货物托运单或提单确认件' : detail?.status === 'DRAFT' ? '订舱放舱后方可打印' : '暂无订舱单据打印权限'" placement="top"><span><el-button v-if="detail" plain :disabled="!canPrint || workflowBusy" @click="printOpen = true"><Printer :size="16" />打印单据</el-button></span></el-tooltip>
             <el-button v-if="canDelete" type="danger" plain :loading="actionSaving" :disabled="workflowBusy" @click="removeDraft"><Trash2 :size="16" />删除草稿</el-button>
             <el-button v-if="canRelease" type="primary" plain :loading="actionSaving" :disabled="workflowBusy" @click="openReleaseDialog">放舱</el-button>
             <el-button v-if="canSave" type="primary" :loading="saving" :disabled="workflowBusy" @click="save"><Save :size="16" />保存草稿</el-button>
@@ -445,6 +461,8 @@ onMounted(() => { void load(); void loadOptions() })
         </div>
       </section>
 
+      <OceanBookingDocumentsPanel v-if="detail" :booking-id="detail.id" :booking-version="detail.version" :booking-status="detail.status" :documents="detail.documents" :can-manage="canManageDocuments" :manage-reason="documentManageReason" @updated="updateDocuments" />
+
       <div v-if="detail" class="surface-panel"><CarrierScheduleQueryPanel :ocean-booking-id="detail.id" /></div>
 
       <section v-if="detail" class="surface-panel history-panel">
@@ -453,6 +471,7 @@ onMounted(() => { void load(); void loadOptions() })
       </section>
       </template>
     </DetailPageLayout>
+    <OceanBookingPrintDialog v-if="detail" v-model="printOpen" :booking-id="detail.id" :booking-no="detail.bookingNo" :allowed="canPrint" />
 
     <AppDialog v-model="releaseDialogOpen" title="确认放舱" width="min(560px, 94vw)" :confirm-loading="actionSaving" :confirm-disabled="workflowBusy" confirm-text="确认放舱" cancel-text="取消" @confirm="submitRelease">
       <el-form label-position="top">

src/modules/ocean-bookings/pages/OceanBookingsView.test.ts

@@ -35,6 +35,9 @@ describe('OceanBookingsView', () => {
     expect(source).toContain('<Pencil v-if="row.status === \'DRAFT\'"')
     expect(source).toContain("row.status === 'DRAFT' ? '编辑' : '查看'")
     expect(source).not.toContain('MoreHorizontal')
+    expect(source).toContain('打印单据')
+    expect(source).toContain('OceanBookingPrintDialog')
+    expect(source).toContain("access.can('platform:firstleg:ocean-booking:list')")
   })
 
   it('uses only the frozen DRAFT and RELEASED status options', () => {

src/modules/ocean-bookings/pages/OceanBookingsView.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { computed, onActivated, onMounted, reactive, ref, watch } from 'vue'
 import { useRouter } from 'vue-router'
-import { Eye, Pencil, Plus } from '@lucide/vue'
+import { Eye, Pencil, Plus, Printer } from '@lucide/vue'
 import { useAccessPreviewStore } from '@/core/access/accessPreview'
 import QueryToolbar, { type QueryField, type QueryModel } from '@/shared/components/QueryToolbar.vue'
 import DataTable from '@/shared/components/DataTable.vue'
@@ -15,6 +15,7 @@ import { listPlatformTenants, type PlatformTenantResource } from '@/modules/iam'
 import { listOceanBookings, type OceanBookingResource } from '../api/platformOceanBookings'
 import type { OceanBookingQuery, OceanBookingStatus } from '../types'
 import { oceanBookingStatusLabel, oceanBookingStatusOptions } from '../status'
+import OceanBookingPrintDialog from '../components/OceanBookingPrintDialog.vue'
 
 const router = useRouter()
 const access = useAccessPreviewStore()
@@ -29,13 +30,16 @@ const customersLoading = ref(false)
 const query = reactive<QueryModel>({ customerId: '', keyword: '', status: '' })
 const activeCustomers = computed(() => customers.value.filter((customer) => customer.status === 'ACTIVE'))
 const canCreate = computed(() => access.can('platform:firstleg:ocean-booking:create'))
+const canPrint = computed(() => access.can('platform:firstleg:ocean-booking:list'))
+const printOpen = ref(false)
+const printBooking = ref<{ id: string; bookingNo?: string | null } | null>(null)
 const fields = computed<QueryField[]>(() => [
   { key: 'customerId', type: 'select', label: '客户', placeholder: '全部客户', width: 220, options: activeCustomers.value.map((customer) => ({ label: customer.tenantName, value: String(customer.id) })), props: { filterable: true, loading: customersLoading.value } },
   { key: 'keyword', type: 'input', label: '关键词', placeholder: '订舱号/提单号/船名/航次', width: 260 },
   { key: 'status', type: 'select', label: '状态', options: oceanBookingStatusOptions },
 ])
 const columns = [
-  { key: 'actions', label: '操作', fixed: 'left', width: 100, slotName: 'actions', hideable: false, movable: false },
+  { key: 'actions', label: '操作', fixed: 'left', width: 196, slotName: 'actions', hideable: false, movable: false },
   { prop: 'bookingNo', label: '订舱号', minWidth: 150 },
   { prop: 'customerName', label: '客户', minWidth: 160 },
   { prop: 'billOfLadingNo', label: '提单号', minWidth: 155, formatter: (row: OceanBookingResource) => row.billOfLadingNo || '—' },
@@ -57,6 +61,8 @@ async function loadCustomers() { customersLoading.value = true; try { const resu
 async function load() { loading.value = true; error.value = null; try { const keyword = String(query.keyword ?? '').trim(); const customerId = String(query.customerId ?? '').trim(); const status = String(query.status ?? '').trim(); const result = await listOceanBookings({ page: page.value, size: pageSize.value, customerId: customerId || undefined, keyword: keyword || undefined, status: (status || undefined) as OceanBookingStatus | undefined } satisfies OceanBookingQuery); rows.value = result.records; total.value = result.total } catch (e) { error.value = getApiErrorDetails(e) } finally { loading.value = false } }
 function open(id: string) { void router.push(`/ocean-bookings/${id}`) }
 function createBooking() { void router.push('/ocean-bookings/new') }
+function openPrint(row: Record<string, unknown>) { printBooking.value = { id: String(row.id), bookingNo: typeof row.bookingNo === 'string' ? row.bookingNo : null }; printOpen.value = true }
+function printHint(row: Record<string, unknown>) { return !canPrint.value ? '暂无订舱单据打印权限' : row.status !== 'RELEASED' ? '订舱放舱后方可打印' : '选择出口货物托运单或提单确认件' }
 function search() { if (page.value === 1) void load(); else page.value = 1 }
 watch([page, pageSize], () => void load()); onMounted(() => void loadCustomers())
 onActivated(() => void load())
@@ -69,7 +75,7 @@ onActivated(() => void load())
       <section v-if="!error" class="surface-panel table-panel">
       <DataTable v-model:page="page" v-model:page-size="pageSize" :data="rows" :columns="columns" :loading="loading" :total="total" stripe preference-key="ocean-bookings" aria-label="订舱列表" row-key="id" empty-text="暂无符合筛选条件的订舱">
         <template #toolbar-actions><el-button v-if="canCreate" type="primary" @click="createBooking"><Plus :size="16" />新增订舱</el-button></template>
-        <template #actions="{ row }"><div class="table-actions"><el-button size="small" type="primary" plain @click="open(row.id)"><Pencil v-if="row.status === 'DRAFT'" :size="15" /><Eye v-else :size="15" />{{ row.status === 'DRAFT' ? '编辑' : '查看' }}</el-button></div></template>
+        <template #actions="{ row }"><div class="table-actions"><el-button size="small" type="primary" plain @click="open(row.id)"><Pencil v-if="row.status === 'DRAFT'" :size="15" /><Eye v-else :size="15" />{{ row.status === 'DRAFT' ? '编辑' : '查看' }}</el-button><el-tooltip :content="printHint(row)" placement="top"><span><el-button size="small" plain :disabled="!canPrint || row.status !== 'RELEASED'" @click="openPrint(row)"><Printer :size="15" />打印单据</el-button></span></el-tooltip></div></template>
         <template #vessel="{ row }">{{ row.vesselName || '—' }}<span v-if="row.voyageNo"> / {{ row.voyageNo }}</span></template>
         <template #etd="{ row }">{{ formatDateTime(row.etd) }}</template>
         <template #eta="{ row }">{{ formatDateTime(row.eta) }}</template>
@@ -78,6 +84,7 @@ onActivated(() => void load())
       </DataTable>
       </section>
     </ListPageLayout>
+    <OceanBookingPrintDialog v-if="printBooking" v-model="printOpen" :booking-id="printBooking.id" :booking-no="printBooking.bookingNo" :allowed="canPrint" />
   </AdminPage>
 </template>
 <style scoped>.ocean-bookings-page{min-width:0}.table-actions{display:flex;align-items:center;flex-wrap:wrap;gap:6px}.table-actions :deep(.el-button){margin-left:0}@media(max-width:420px){.table-actions{flex-direction:column;align-items:stretch}.table-actions :deep(.el-button){width:100%;min-height:40px}}</style>

src/modules/ocean-bookings/types.ts

@@ -1,4 +1,26 @@
 export type OceanBookingStatus = 'DRAFT' | 'RELEASED'
+export type OceanBookingPrintType = 'SHIPPING_INSTRUCTION' | 'BILL_OF_LADING_CONFIRMATION'
+export type OceanBookingDocumentType = 'BOOKING_CONFIRMATION' | 'BILL_OF_LADING'
+
+export interface OceanBookingDocument {
+  id: string
+  oceanBookingId: string
+  fileId: string
+  documentType: OceanBookingDocumentType
+  fileName: string
+  fileHash: string | null
+  sizeBytes: number | null
+  contentType: string | null
+  valid: boolean
+  uploadedBy: string
+  uploadedByName: string | null
+  uploadedAt: string
+  invalidatedBy: string | null
+  invalidatedByName: string | null
+  invalidatedAt: string | null
+}
+export interface OceanBookingDocumentMutation { document: OceanBookingDocument; bookingVersion: number }
+export interface OceanBookingDocumentInvalidation { documentId: string; bookingVersion: number }
 export type OceanBookingContainerType = '20GP' | '40GP' | '40HC' | '40NR' | '45HC'
 export type OceanBookingCarrierCode = 'MATSON' | 'SML' | 'ZIM' | 'COSCO' | 'EMC' | 'HEDE' | 'OTHER'
 
@@ -56,7 +78,7 @@ export interface OceanBookingResource {
   etd: string | null; atd: string | null; eta: string | null; ata: string | null; containerSummary: string | null
   amount: string | null; currency: string | null
 }
-export interface OceanBookingDetail extends OceanBookingResource { oceanBooking: OceanBookingResource; parties: OceanBookingParty[]; containerRequirements: OceanBookingContainerRequirement[]; containers: OceanBookingAllocatedContainer[]; histories: OceanBookingStatusEvent[]; statusHistory: OceanBookingStatusEvent[] }
+export interface OceanBookingDetail extends OceanBookingResource { oceanBooking: OceanBookingResource; parties: OceanBookingParty[]; containerRequirements: OceanBookingContainerRequirement[]; containers: OceanBookingAllocatedContainer[]; documents: OceanBookingDocument[]; histories: OceanBookingStatusEvent[]; statusHistory: OceanBookingStatusEvent[] }
 export interface OceanBookingStatusEvent { id: string; fromStatus: OceanBookingStatus | null; toStatus: OceanBookingStatus; action: string; reason?: string | null; operatorName: string | null; occurredAt: string }
 export interface OceanBookingPage { records: OceanBookingResource[]; page: number; size: number; total: number; pages: number }
 export interface OceanBookingQuery { page: number; size: number; keyword?: string; status?: OceanBookingStatus; customerId?: string }