feat(client): show actionable customs count on sidebar

src/components/ClientSidebarMenu.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-import { computed, ref, watch } from 'vue'
+import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
 import ClientSidebarMenuNode from '@/components/ClientSidebarMenuNode.vue'
 import {
   clientNavigation,
@@ -7,6 +7,7 @@ import {
   getNavigationParentKeys,
 } from '@/navigation/clientNavigation'
 import { useAuthStore } from '@/modules/auth/public'
+import { useCustomsPendingStore } from '@/modules/first-leg/public'
 
 const props = defineProps<{
   activePath: string
@@ -16,6 +17,28 @@ const emit = defineEmits<{
   navigate: [path: string]
 }>()
 const auth = useAuthStore()
+const customsPending = useCustomsPendingStore()
+const badges = computed(() => ({ 'first-leg-customs-documents': { count: customsPending.count, error: customsPending.error } }))
+watch(() => auth.isAuthenticated && auth.hasPermission('order:first-leg:customs-list') ? auth.user?.id ?? '' : '', scope => {
+  customsPending.setScope(scope)
+  if (scope) void customsPending.refresh()
+}, { immediate: true, flush: 'sync' })
+function refreshCustomsPending() {
+  if (document.visibilityState === 'visible') void customsPending.refresh()
+}
+let refreshTimer: ReturnType<typeof setInterval> | undefined
+onMounted(() => {
+  refreshTimer = setInterval(refreshCustomsPending, 60_000)
+  window.addEventListener('focus', refreshCustomsPending)
+  document.addEventListener('visibilitychange', refreshCustomsPending)
+})
+onBeforeUnmount(() => {
+  clearInterval(refreshTimer)
+  window.removeEventListener('focus', refreshCustomsPending)
+  document.removeEventListener('visibilitychange', refreshCustomsPending)
+  customsPending.setScope('')
+})
+
 const visibleNavigation = computed(() => filterNavigationByPermissions(clientNavigation, auth.permissionCodes))
 
 const activeParentKeys = computed(() => new Set(getNavigationParentKeys(visibleNavigation.value, props.activePath)))
@@ -47,6 +70,7 @@ function handleSelect(path: string) {
       v-for="node in visibleNavigation"
       :key="node.key"
       :node="node"
+      :badges="badges"
       :active-path="activePath"
       :opened-keys="openedKeys"
       :active-parent-keys="activeParentKeys"

src/components/ClientSidebarMenuNode.vue

@@ -8,6 +8,7 @@ const props = defineProps<{
   activePath: string
   openedKeys: ReadonlySet<string>
   activeParentKeys: ReadonlySet<string>
+  badges?: Readonly<Record<string, { count: number | null; error: string }>>
   level?: number
 }>()
 
@@ -16,6 +17,9 @@ const emit = defineEmits<{
   toggle: [key: string]
 }>()
 
+const badge = computed(() => props.badges?.[props.node.key])
+const badgeTitle = computed(() => badge.value?.error || `${badge.value?.count ?? 0} 个柜次待上传资料或确认回执`)
+
 const groupId = computed(() => `client-nav-group-${props.node.key}`)
 </script>
 
@@ -54,6 +58,7 @@ const groupId = computed(() => `client-nav-group-${props.node.key}`)
         v-for="child in node.children"
         :key="child.key"
         :node="child"
+        :badges="badges"
         :active-path="activePath"
         :opened-keys="openedKeys"
         :active-parent-keys="activeParentKeys"
@@ -78,6 +83,14 @@ const groupId = computed(() => `client-nav-group-${props.node.key}`)
         aria-hidden="true"
       />
       <span>{{ node.title }}</span>
+      <span v-if="badge?.error || (badge?.count != null && badge.count > 0)" class="client-nav-badge"
+        :title="badgeTitle" :aria-label="badgeTitle" role="status">
+        {{ badge?.error ? '!' : badge!.count! > 99 ? '99+' : badge?.count }}
+      </span>
     </RouterLink>
   </li>
 </template>
+
+<style scoped>
+.client-sidebar-link .client-nav-badge { display: inline-flex; flex: 0 0 auto; min-width: 23px; height: 23px; align-items: center; justify-content: center; margin-left: auto; padding: 0 5px; border: 2px solid #fff; border-radius: 999px; background: #ef4444; color: #fff; box-shadow: 0 3px 9px rgb(239 68 68 / 24%); font-size: 12px; font-weight: 700; line-height: 1; }
+</style>

src/modules/first-leg/api/customs.ts

@@ -283,3 +283,11 @@ export function merchantCustomsErrorMessage(error: unknown, fallback: string) {
 export function isMerchantCustomsUnavailable(error: unknown) {
   return error instanceof ApiError && (error.status === 404 || error.code === 'A0404')
 }
+
+
+export async function getMerchantCustomsPendingCount() {
+  const result = await apiRequest<{ pendingCount: string | number }>({ method: 'GET', url: '/merchant/v1/customs/pending-summary' })
+  const count = Number(result.pendingCount)
+  if (result.pendingCount == null || result.pendingCount === '' || !Number.isSafeInteger(count) || count < 0) throw new Error('报关待办数量返回不完整')
+  return count
+}

src/modules/first-leg/components/CustomsDocumentsDialog.test.mjs

@@ -10,7 +10,7 @@ function harness(t) {
   const code = ts.transpileModule(source + '\nexport { loadDetail, detail, clearanceResults, loading, errorMessage, selectedInboundIds, clearanceError, clearanceLoading, retryClearanceResults, close }', { compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 } }).outputText
   const props = vue.reactive({ modelValue: false, orderId: 'A', canEdit: true }), requests = [], clearances = [], updates = [], view = {}
   const unmounts = []
-  const dependencies = { vue: { ...vue, onBeforeUnmount: fn => unmounts.push(fn) }, 'element-plus': { ElMessage: {} }, '@/modules/first-leg/api/customs': {
+  const dependencies = { '../store/customsPending': { useCustomsPendingStore: () => ({ refresh: async () => {} }) }, vue: { ...vue, onBeforeUnmount: fn => unmounts.push(fn) }, 'element-plus': { ElMessage: {} }, '@/modules/first-leg/api/customs': {
     getMerchantCustomsForOrder: id => { const pending = deferred(); requests.push({ id, ...pending }); return pending.promise },
     getMerchantClearanceResults: id => { const pending = deferred(); clearances.push({ id, ...pending }); return pending.promise },
     merchantCustomsErrorMessage: error => error.message,

src/modules/first-leg/components/CustomsDocumentsDialog.vue

@@ -22,6 +22,9 @@ import {
   type MerchantClearanceResult,
 } from '@/modules/first-leg/api/customs'
 
+import { useCustomsPendingStore } from '../store/customsPending'
+
+const customsPending = useCustomsPendingStore()
 const props = defineProps<{
   modelValue: boolean
   orderId: string
@@ -104,6 +107,7 @@ async function retryClearanceResults() {
 
 async function loadDetail() {
   if (disposed || !props.modelValue || !props.orderId) return
+  void customsPending.refresh(true)
   const request = ++detailRequest
   resetClearanceResults()
   const orderId = props.orderId

src/modules/first-leg/public.ts

@@ -5,3 +5,4 @@ export { getMerchantWarehouses, type MerchantWarehouse } from './api/firstLeg'
 export { getFirstLegStatusLabel, getFirstLegStatusTone } from './utils/firstLegOrder'
 export { default as InboundCodeAssociationDialog } from './components/InboundCodeAssociationDialog.vue'
 export { default as FirstLegOrdersView } from './views/FirstLegOrdersView.vue'
+export { useCustomsPendingStore } from './store/customsPending'

src/modules/first-leg/store/customsPending.test.mjs

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { readFileSync } from 'node:fs'
+import ts from 'typescript'
+import * as vue from 'vue'
+import * as pinia from 'pinia'
+const source = readFileSync(new URL('./customsPending.ts', import.meta.url), 'utf8')
+const code = ts.transpileModule(source, { compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 } }).outputText
+function deferred() { let resolve, reject; const promise = new Promise((a,b) => { resolve=a; reject=b }); return { promise, resolve, reject } }
+function harness(t, read) {
+  const context=pinia.createPinia();pinia.setActivePinia(context);t.after(()=>pinia.disposePinia(context))
+  const deps={vue,pinia,'../api/customs':{getMerchantCustomsPendingCount:read}}, exports={}
+  new Function('require','exports',code)(id=>{assert.ok(id in deps,id);return deps[id]},exports)
+  return exports.useCustomsPendingStore()
+}
+test('does not request without a permitted identity; preserves counts while refreshing and accepts zero',async t=>{
+  const pending=deferred();let calls=0
+  const store=harness(t,()=>++calls===1?Promise.resolve(2):pending.promise)
+  await store.refresh();assert.equal(calls,0)
+  store.setScope('customer-a');await store.refresh();assert.equal(store.count,2)
+  const load=store.refresh();await store.refresh();assert.equal(calls,2);assert.equal(store.count,2)
+  pending.resolve(0);await load;assert.equal(store.count,0);assert.equal(store.loading,false)
+})
+test('logout, permission removal and account switches discard old in-flight responses',async t=>{
+  const pending=deferred();const store=harness(t,()=>pending.promise)
+  store.setScope('a');const load=store.refresh();store.setScope('')
+  pending.resolve(9);await load;assert.equal(store.count,null);assert.equal(store.error,'')
+  store.setScope('b');assert.equal(store.count,null)
+})
+test('successful mutation can force a newer refresh without being overwritten by an older query',async t=>{
+  const a=deferred(),b=deferred();let calls=0;const store=harness(t,()=>++calls===1?a.promise:b.promise)
+  store.setScope('a');const first=store.refresh();const second=store.refresh(true)
+  b.resolve(1);await second;a.resolve(2);await first;assert.equal(store.count,1)
+})
+test('failure is distinguishable from zero and retry restores authoritative count',async t=>{
+  let fail=true;const store=harness(t,()=>fail?Promise.reject(new Error('offline')):Promise.resolve(3))
+  store.setScope('a');await store.refresh();assert.equal(store.count,null);assert.notEqual(store.error,'')
+  fail=false;await store.refresh();assert.equal(store.count,3);assert.equal(store.error,'')
+})

src/modules/first-leg/store/customsPending.ts

@@ -0,0 +1,40 @@
+import { ref } from 'vue'
+import { defineStore } from 'pinia'
+import { getMerchantCustomsPendingCount } from '../api/customs'
+
+export const useCustomsPendingStore = defineStore('client-customs-pending', () => {
+  const count = ref<number | null>(null)
+  const loading = ref(false)
+  const error = ref('')
+  let scope = ''
+  let requestVersion = 0
+
+  function setScope(value: string) {
+    if (scope === value) return
+    scope = value
+    requestVersion++
+    count.value = null
+    error.value = ''
+    loading.value = false
+  }
+
+  async function refresh(force = false) {
+    if (!scope || (loading.value && !force)) return
+    const request = ++requestVersion
+    loading.value = true
+    try {
+      const result = await getMerchantCustomsPendingCount()
+      if (request !== requestVersion) return
+      count.value = result
+      error.value = ''
+    } catch {
+      if (request !== requestVersion) return
+      count.value = null
+      error.value = '报关待办数量加载失败，请进入报关资料刷新'
+    } finally {
+      if (request === requestVersion) loading.value = false
+    }
+  }
+
+  return { count, loading, error, setScope, refresh }
+})

src/modules/first-leg/views/CustomsDocumentsView.test.mjs

@@ -46,6 +46,7 @@ function harness(t, orders, getDetail = async id => detail(id)) {
     vue: { ...vue, onMounted() {} },
     '../utils/customsDocumentsReader': reader,
     '../api/customs': customsApi,
+    '../store/customsPending': { useCustomsPendingStore: () => ({ refresh: async () => {} }) },
   }))
   t.after(() => scope.stop())
   return { view, store, calls, pageCalls }

src/modules/first-leg/views/CustomsDocumentsView.vue

@@ -8,6 +8,9 @@ import { MERCHANT_CUSTOMS_STATUS_LABELS, type MerchantCustomsContainer } from '.
 import { readCustomsDocuments, type CustomsDocumentRow } from '../utils/customsDocumentsReader'
 import CustomsDocumentsDialog from '../components/CustomsDocumentsDialog.vue'
 
+import { useCustomsPendingStore } from '../store/customsPending'
+
+const customsPending = useCustomsPendingStore()
 const loading = ref(false)
 const errorMessage = ref('')
 const queryModel = ref<QueryModel>({ orderNo: '', inboundCode: '', containerNo: '', status: '' })
@@ -68,6 +71,7 @@ function statusType(detail: MerchantCustomsContainer) {
 }
 async function load() {
   if (loading.value) return
+  void customsPending.refresh(true)
   loading.value = true; errorMessage.value = ''
   try {
     const { records: loadedRecords, failedCount } = await readCustomsDocuments()