优化

src/modules/finance/api/adapters.ts

@@ -2,6 +2,7 @@ import type {
   FinanceBillDetail,
   FinanceBillLine,
   FinanceBillStatus,
+  FinanceCustomerConfirmationStatus,
   FinanceBillSummary,
   FinanceReceiptRecord,
 } from '../contracts'
@@ -20,6 +21,10 @@ export interface FinanceBillWire {
   totalAmount: WireScalar
   receivedAmount: WireScalar
   outstandingAmount: WireScalar
+  version: number
+  customerConfirmationStatus: FinanceCustomerConfirmationStatus
+  customerConfirmedByName: string | null
+  customerConfirmedAt: string | null
 }
 
 export interface FinanceBillLineWire {
@@ -73,6 +78,10 @@ function mapBillSummary(bill: FinanceBillWire): FinanceBillSummary {
     issueDate: bill.billDate,
     dueDate: bill.dueDate,
     status: bill.status,
+    version: bill.version ?? 0,
+    customerConfirmationStatus: bill.customerConfirmationStatus ?? 'NOT_REQUIRED',
+    customerConfirmedByName: bill.customerConfirmedByName ?? null,
+    customerConfirmedAt: bill.customerConfirmedAt ?? null,
   }
 }
 

src/modules/finance/api/finance.ts

@@ -1,5 +1,5 @@
 import { apiRequest } from '@/api/http'
-import type { FinanceBillDetail, FinanceBillPage, FinanceBillQuery, FinanceReceiptRecord } from '../contracts'
+import type { FinanceBillDetail, FinanceBillPage, FinanceBillQuery, FinanceCustomerConfirmationResult, FinanceReceiptRecord } from '../contracts'
 import {
   mapFinanceBillDetail,
   mapFinanceBills,
@@ -54,3 +54,18 @@ export async function getMerchantFinanceReceipts(billId: string): Promise<Financ
   })
   return mapFinanceReceipts(response, billId)
 }
+
+function confirmationIdempotencyKey(statementId: string) {
+  const randomPart = globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`
+  return `statement-confirm-${statementId}-${randomPart}`
+}
+
+export async function confirmMerchantFinanceStatement(statementId: string, expectedVersion: number,
+                                                       idempotencyKey = confirmationIdempotencyKey(statementId)) {
+  return apiRequest<FinanceCustomerConfirmationResult>({
+    method: 'POST',
+    url: `/client/finance/v1/statements/${encodeURIComponent(statementId)}/confirm`,
+    headers: { 'Idempotency-Key': idempotencyKey },
+    data: { expectedVersion },
+  })
+}

src/modules/finance/contracts.ts

@@ -1,6 +1,7 @@
 import type { PageResult } from '@/modules/first-leg/api/firstLeg'
 
 export type FinanceBillStatus = 'DRAFT' | 'ISSUED' | 'PARTIALLY_PAID' | 'PAID' | 'VOIDED'
+export type FinanceCustomerConfirmationStatus = 'NOT_REQUIRED' | 'PENDING_CONFIRMATION' | 'CONFIRMED'
 
 export interface FinanceBillQuery {
   keyword?: string
@@ -20,6 +21,19 @@ export interface FinanceBillSummary {
   issueDate: string | null
   dueDate: string | null
   status: FinanceBillStatus
+  version: number
+  customerConfirmationStatus: FinanceCustomerConfirmationStatus
+  customerConfirmedByName: string | null
+  customerConfirmedAt: string | null
+}
+
+export interface FinanceCustomerConfirmationResult {
+  statementId: string
+  confirmationStatus: 'CONFIRMED'
+  confirmedBy: string
+  confirmedByName: string
+  confirmedAt: string
+  version: number
 }
 
 export interface FinanceBillLine {

src/modules/finance/views/FinanceBillsView.test.mjs

@@ -20,7 +20,7 @@ async function importTypeScriptModule(url) {
 const financeAdapters = await importTypeScriptModule(new URL('../api/adapters.ts', import.meta.url))
 const permissionContracts = await importTypeScriptModule(new URL('../../tenant-management/contracts.ts', import.meta.url))
 
-test('activates the customer finance route with a read-only permission', () => {
+test('activates the customer finance route with its existing list and detail permission', () => {
   assert.match(routesSource, /path: 'finance\/bills'/)
   assert.match(routesSource, /FinanceBillsView\.vue/)
   assert.match(routesSource, /release: 'active'/)
@@ -28,13 +28,17 @@ test('activates the customer finance route with a read-only permission', () => {
   assert.doesNotMatch(routesSource, /finance\/payables|应付账单/)
 })
 
-test('uses client finance read APIs without browser-selected customer scope', () => {
+test('uses authenticated-scope finance APIs and confirms without browser-selected customer scope', () => {
   assert.match(apiSource, /method: 'GET'/)
   assert.match(apiSource, /\/client\/finance\/v1\/bills/)
   assert.match(apiSource, /\/client\/finance\/v1\/receipts/)
   assert.doesNotMatch(apiSource, /\/merchant\/v1\/finance/)
   assert.doesNotMatch(apiSource, /customerId|tenantId/)
-  assert.doesNotMatch(apiSource, /method: '(POST|PUT|PATCH|DELETE)'/)
+  assert.match(apiSource, /method: 'POST'/)
+  assert.match(apiSource, /\/client\/finance\/v1\/statements\/\$\{encodeURIComponent\(statementId\)\}\/confirm/)
+  assert.match(apiSource, /'Idempotency-Key'/)
+  assert.match(apiSource, /data: \{ expectedVersion \}/)
+  assert.doesNotMatch(apiSource, /method: '(PUT|PATCH|DELETE)'/)
   assert.doesNotMatch(apiSource, /params:\s*\{\s*billId/)
 })
 
@@ -65,6 +69,10 @@ test('does not expose draft or voided bills returned by the server', () => {
     totalAmount: '100.00',
     receivedAmount: '0.00',
     outstandingAmount: '100.00',
+    version: 1,
+    customerConfirmationStatus: 'PENDING_CONFIRMATION',
+    customerConfirmedByName: null,
+    customerConfirmedAt: null,
   })
   const visible = financeAdapters.mapFinanceBills([
     bill(1, 'DRAFT'),
@@ -82,6 +90,7 @@ test('maps nested bill detail and customer-safe receipt allocations', () => {
       id: 2, customerId: 10001, billNo: 'B-2', customerName: '测试客户', currency: 'CNY',
       billDate: '2026-08-11', dueDate: '2026-09-10', status: 'ISSUED', totalAmount: '100.00',
       receivedAmount: '40.00', outstandingAmount: '60.00',
+      version: 3, customerConfirmationStatus: 'PENDING_CONFIRMATION', customerConfirmedByName: null, customerConfirmedAt: null,
     },
     lines: [{ id: 21, sourceType: 'INBOUND_FEE', sourceId: 81, sourceVersion: 3, orderId: 31, inboundId: 41, feeItemCode: 'FREIGHT', feeItemName: '运费', amount: '100.00', currency: 'CNY' }],
   })
@@ -104,21 +113,21 @@ test('requires both finance statement authorities for the page permission', () =
   assert.equal(allowed(['merchant:finance:statement:list', 'merchant:finance:statement:view']), true)
 })
 
-test('keeps actions first and exposes list, balance, detail, receipt, empty and error states', () => {
+test('keeps actions first and exposes list, balance, detail, confirmation, receipt, empty and error states', () => {
   const actionIndex = viewSource.indexOf('label="操作"')
   const billNumberIndex = viewSource.indexOf('label="账单编号"')
   assert.ok(actionIndex >= 0 && actionIndex < billNumberIndex)
-  for (const expected of ['未收余额', '账单详情', '收款记录', '暂无账单', '暂无收款记录', 'state-panel--error']) {
+  for (const expected of ['未收余额', '账单详情', '确认账单', '客户确认信息', '收款记录', '暂无账单', '暂无收款记录', 'state-panel--error']) {
     assert.match(viewSource, new RegExp(expected))
   }
-  for (const forbidden of ['确认账单', '发起争议', '新增收款', '核销', '修改金额']) {
+  assert.match(viewSource, /auth\.hasPermission\('finance:bill:confirm'\)/)
+  for (const forbidden of ['发起争议', '新增收款', '核销', '修改金额']) {
     assert.doesNotMatch(viewSource, new RegExp(forbidden))
   }
 })
 
-test('catalogs customer finance as an assignable view-only role permission', () => {
+test('keeps the existing customer finance view permission mapping', () => {
   assert.match(permissionSource, /code: 'finance:bill:view'/)
-  assert.match(permissionSource, /不包含任何财务写操作/)
   assert.match(permissionSource, /merchant:finance:statement:list/)
   assert.match(permissionSource, /merchant:finance:statement:view/)
   assert.match(permissionSource, /FRONTEND_PERMISSIONS_REQUIRING_ALL_BACKEND_CODES/)

src/modules/finance/views/FinanceBillsView.vue

@@ -1,11 +1,14 @@
 <script setup lang="ts">
 import { computed, onMounted, reactive, ref } from 'vue'
 import { CircleDollarSign, Eye, RefreshCcw, Search } from '@lucide/vue'
+import { ElMessage, ElMessageBox } from 'element-plus'
 import { ApiError } from '@/api/http'
-import { getMerchantFinanceBill, getMerchantFinanceBills, getMerchantFinanceReceipts } from '../api/finance'
-import type { FinanceBillDetail, FinanceBillQuery, FinanceBillStatus, FinanceBillSummary } from '../contracts'
+import { useAuthStore } from '@/modules/auth/public'
+import { confirmMerchantFinanceStatement, getMerchantFinanceBill, getMerchantFinanceBills, getMerchantFinanceReceipts } from '../api/finance'
+import type { FinanceBillDetail, FinanceBillQuery, FinanceBillStatus, FinanceBillSummary, FinanceCustomerConfirmationStatus } from '../contracts'
 
 const loading = ref(false)
+const auth = useAuthStore()
 const detailLoading = ref(false)
 const errorMessage = ref('')
 const detailError = ref('')
@@ -13,6 +16,8 @@ const bills = ref<FinanceBillSummary[]>([])
 const detail = ref<FinanceBillDetail | null>(null)
 const selectedBillId = ref('')
 const detailVisible = ref(false)
+const confirming = ref(false)
+const confirmationKeys = new Map<string, string>()
 const page = ref(1)
 const pageSize = ref(20)
 const total = ref(0)
@@ -27,6 +32,7 @@ const statusOptions: Array<{ label: string; value: FinanceBillStatus }> = [
 ]
 
 const hasData = computed(() => bills.value.length > 0)
+const canConfirm = computed(() => auth.hasPermission('finance:bill:confirm'))
 
 function formatAmount(value: string | null | undefined) {
   if (!value) return '0.00'
@@ -39,6 +45,10 @@ function formatDate(value: string | null | undefined) {
   return value.slice(0, 10)
 }
 
+function formatDateTime(value: string | null | undefined) {
+  return value ? value.replace('T', ' ').replace(/Z$/, '').slice(0, 16) : '-'
+}
+
 function statusLabel(status: FinanceBillStatus) {
   return ({ DRAFT: '草稿', ISSUED: '已出账', PARTIALLY_PAID: '部分收款', PAID: '已收清', VOIDED: '作废' })[status] ?? status
 }
@@ -47,6 +57,14 @@ function statusType(status: FinanceBillStatus) {
   return ({ ISSUED: 'info', PARTIALLY_PAID: 'warning', PAID: 'success', VOIDED: 'danger', DRAFT: 'info' })[status] as 'info' | 'warning' | 'success' | 'danger'
 }
 
+function confirmationLabel(status: FinanceCustomerConfirmationStatus) {
+  return ({ NOT_REQUIRED: '无需确认', PENDING_CONFIRMATION: '待确认', CONFIRMED: '已确认' })[status]
+}
+
+function confirmationType(status: FinanceCustomerConfirmationStatus) {
+  return ({ NOT_REQUIRED: 'info', PENDING_CONFIRMATION: 'warning', CONFIRMED: 'success' })[status] as 'info' | 'warning' | 'success'
+}
+
 function messageOf(error: unknown) {
   return error instanceof ApiError ? error.message : '账单加载失败，请稍后重试'
 }
@@ -94,6 +112,37 @@ async function loadDetail(billId: string) {
   }
 }
 
+async function confirmStatement() {
+  if (!detail.value || detail.value.customerConfirmationStatus !== 'PENDING_CONFIRMATION') return
+  try {
+    await ElMessageBox.confirm(
+      `确认对账单 ${detail.value.billNo} 的金额与费用明细无误？确认后平台将记录当前登录成员和确认时间。`,
+      '确认客户对账单',
+      { type: 'warning', confirmButtonText: '确认无误', cancelButtonText: '取消' },
+    )
+  } catch {
+    return
+  }
+  confirming.value = true
+  const statementId = detail.value.id
+  let key = confirmationKeys.get(statementId)
+  if (!key) {
+    const randomPart = globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`
+    key = `statement-confirm-${statementId}-${randomPart}`
+    confirmationKeys.set(statementId, key)
+  }
+  try {
+    await confirmMerchantFinanceStatement(statementId, detail.value.version, key)
+    confirmationKeys.delete(statementId)
+    ElMessage.success('对账单已确认')
+    await Promise.all([loadDetail(statementId), loadBills(page.value)])
+  } catch (error) {
+    ElMessage.error(error instanceof ApiError ? error.message : '对账单确认失败，请重试')
+  } finally {
+    confirming.value = false
+  }
+}
+
 function resetFilters() {
   filters.keyword = ''
   filters.status = undefined
@@ -142,6 +191,7 @@ onMounted(() => { void loadBills(1) })
         <el-table-column label="已收" width="145" align="right"><template #default="{ row }">¥ {{ formatAmount(row.receivedAmount) }}</template></el-table-column>
         <el-table-column label="未收余额" width="145" align="right"><template #default="{ row }"><strong :class="{ 'amount-warning': row.outstandingAmount !== '0' }">¥ {{ formatAmount(row.outstandingAmount) }}</strong></template></el-table-column>
         <el-table-column label="状态" width="110"><template #default="{ row }"><el-tag :type="statusType(row.status)">{{ statusLabel(row.status) }}</el-tag></template></el-table-column>
+        <el-table-column label="客户确认" width="110"><template #default="{ row }"><el-tag :type="confirmationType(row.customerConfirmationStatus)">{{ confirmationLabel(row.customerConfirmationStatus) }}</el-tag></template></el-table-column>
         <template #empty><div class="table-empty"><CircleDollarSign :size="32" /><strong>暂无账单</strong><span>平台财务出账后，这里会显示本企业账单。</span></div></template>
       </el-table>
 
@@ -152,10 +202,11 @@ onMounted(() => { void loadBills(1) })
       <div v-loading="detailLoading" class="detail-content">
         <div v-if="detailError" class="state-panel state-panel--error" role="alert"><p>{{ detailError }}</p><el-button @click="loadDetail(selectedBillId)">重试</el-button></div>
         <template v-else-if="detail">
-          <div class="detail-heading"><div><h2>{{ detail.billNo }}</h2><p>出账 {{ formatDate(detail.issueDate) }} · 到期 {{ formatDate(detail.dueDate) }} · 未收 <strong class="amount-warning">¥ {{ formatAmount(detail.outstandingAmount) }}</strong></p></div><el-tag :type="statusType(detail.status)">{{ statusLabel(detail.status) }}</el-tag></div>
+          <div class="detail-heading"><div><h2>{{ detail.billNo }}</h2><p>出账 {{ formatDate(detail.issueDate) }} · 到期 {{ formatDate(detail.dueDate) }} · 未收 <strong class="amount-warning">¥ {{ formatAmount(detail.outstandingAmount) }}</strong></p></div><div class="detail-statuses"><el-tag :type="statusType(detail.status)">{{ statusLabel(detail.status) }}</el-tag><el-tag :type="confirmationType(detail.customerConfirmationStatus)">{{ confirmationLabel(detail.customerConfirmationStatus) }}</el-tag></div></div>
+          <section class="confirmation-panel" aria-label="客户确认信息"><div><strong>{{ confirmationLabel(detail.customerConfirmationStatus) }}</strong><p v-if="detail.customerConfirmationStatus === 'CONFIRMED'">{{ detail.customerConfirmedByName || '当前企业成员' }} · {{ formatDateTime(detail.customerConfirmedAt) }}</p><p v-else>请核对本期金额和费用明细，确认后将记录当前登录成员与确认时间。</p></div><el-button v-if="detail.customerConfirmationStatus === 'PENDING_CONFIRMATION' && canConfirm" type="primary" :loading="confirming" @click="confirmStatement">确认账单</el-button></section>
           <section class="detail-section"><h3>费用明细</h3><el-table :data="detail.lines" size="small"><el-table-column prop="feeName" label="费用项目" min-width="180" /><el-table-column label="金额" width="130" align="right"><template #default="{ row }">¥ {{ formatAmount(row.amount) }}</template></el-table-column></el-table></section>
           <section class="detail-section"><h3>收款记录</h3><el-table v-if="detail.receipts.length" :data="detail.receipts" size="small"><el-table-column prop="receivedAt" label="收款日期" width="110"><template #default="{ row }">{{ formatDate(row.receivedAt) }}</template></el-table-column><el-table-column prop="receiptNo" label="收款编号" min-width="130" /><el-table-column label="本次金额" width="130" align="right"><template #default="{ row }">¥ {{ formatAmount(row.allocatedAmount) }}</template></el-table-column><el-table-column prop="method" label="方式" min-width="100" /></el-table><div v-else class="sub-empty">暂无收款记录</div></section>
-          <p class="readonly-notice">账单金额和收款记录仅供查看。如有疑问，请线下联系平台财务。</p>
+          <p class="readonly-notice">如对账单内容有疑问，请先线下联系平台财务，核对无误后再确认。</p>
         </template>
       </div>
     </el-drawer>
@@ -171,6 +222,6 @@ onMounted(() => { void loadBills(1) })
 .state-panel { display: flex; min-height: 180px; align-items: center; justify-content: center; gap: 12px; flex-direction: column; color: var(--muted); text-align: center; }.state-panel p { margin: 0; }.state-panel--error { color: #b42318; background: #fff8f7; border: 1px solid #f5c2bd; border-radius: 6px; }
 .table-empty { display: flex; align-items: center; flex-direction: column; gap: 8px; padding: 42px 12px; color: var(--muted); }.table-empty strong { color: var(--navy); }.table-empty span { font-size: 12px; }
 .pagination-row { display: flex; align-items: center; justify-content: space-between; gap: 12px; padding-top: 14px; color: var(--muted); font-size: 12px; }
-.detail-content { min-height: 300px; }.detail-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: 16px; }.detail-heading h2 { margin: 0 0 5px; color: var(--navy); font-size: 18px; }.detail-heading p { margin: 0; color: var(--muted); font-size: 13px; }.detail-section { margin-top: 22px; }.detail-section h3 { margin: 0 0 10px; color: var(--navy); font-size: 14px; }.sub-empty { padding: 22px; color: var(--muted); font-size: 12px; text-align: center; background: #f7fafb; }.readonly-notice { margin: 22px 0 0; padding: 11px 12px; color: #45615d; background: #edf6f4; font-size: 12px; }
+.detail-content { min-height: 300px; }.detail-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: 16px; }.detail-heading h2 { margin: 0 0 5px; color: var(--navy); font-size: 18px; }.detail-heading p { margin: 0; color: var(--muted); font-size: 13px; }.detail-statuses { display: flex; align-items: center; gap: 8px; }.confirmation-panel { display: flex; align-items: center; justify-content: space-between; gap: 16px; margin-top: 18px; padding: 14px 16px; border: 1px solid #d7e9e4; border-radius: 8px; background: #f3f9f7; }.confirmation-panel strong { color: var(--navy); }.confirmation-panel p { margin: 4px 0 0; color: var(--muted); font-size: 12px; }.detail-section { margin-top: 22px; }.detail-section h3 { margin: 0 0 10px; color: var(--navy); font-size: 14px; }.sub-empty { padding: 22px; color: var(--muted); font-size: 12px; text-align: center; background: #f7fafb; }.readonly-notice { margin: 22px 0 0; padding: 11px 12px; color: #45615d; background: #edf6f4; font-size: 12px; }
 @media (max-width: 720px) { .keyword-input, .status-select { width: 100%; }.filter-bar > .el-button { flex: 1; }.content-card { padding: 12px; }.pagination-row { align-items: flex-start; flex-direction: column; }.finance-summary { align-items: flex-start; flex-direction: column; gap: 6px; } }
 </style>