优化

src/shared/api/AGENTS.md

@@ -0,0 +1,25 @@
+# Admin Shared API Instructions
+
+## 适用范围与入口
+
+- 本文件适用于 `src/shared/api/` 及其测试。业务模块只通过领域 `api/` 适配层调用这里的客户端，不在页面和组件直接创建 Axios 实例。
+- 国内 API 客户端为 `http.ts`；海外 API 客户端为 `overseasHttp.ts`。认证会话编排在 `../../core/auth/auth.ts`，不得在本目录复制登录状态。
+
+## 国内与海外请求
+
+- `http` 使用 `VITE_API_BASE_URL`，默认走国内代理；国内登录、刷新和退出仍由统一 Auth 处理。
+- `overseasHttp` 使用 `VITE_OVERSEAS_API_BASE_URL`，默认 `/overseas-api`；Vite 将该前缀改写为海外 Gateway 的 `/api`。代理上游由开发环境配置，不在源码或指引中记录真实地址。
+- 登录和刷新响应一次性返回国内 Token、`overseasAccessToken`、`overseasExpiresIn`；`core/auth/auth.ts` 必须原子替换两套访问凭据。不得恢复 Token 兑换端点或让业务模块单独刷新海外 Token。
+- 海外 Token 只由 `replaceOverseasAccessToken`、`clearOverseasAccessToken` 管理；业务模块不得读写缓存、LocalStorage 或手工拼装 `Authorization`。
+- 国内、海外 401 共用统一会话刷新编排。海外请求最多统一刷新一次并重放一次；刷新失败按会话失效处理，不循环重试或回退假数据。
+
+## 领域调用边界
+
+- 国内业务领域 API 使用 `http`；四期海外尾程、海外仓资源和海外本土业务使用 `overseasHttp`，不得经国内 Gateway 中转。
+- 页面只调用所属模块的 API 封装；模块 API 负责路径、DTO 和错误适配，不把 Axios 响应或区域选择泄漏到页面。
+- 跨区域 Token、Audience、JWKS 和服务通信公共契约读取 `../../../../../docs/跨区域认证与服务通信契约.md`。
+
+## 修改与验证
+
+- 修改客户端、拦截器、刷新、Token 生命周期或 Base URL 时，联查 `http.test.ts`、`overseasHttp.test.ts`、`core/auth/auth.test.ts`、Vite 代理、`.env.example` 和全部实际消费者。
+- 至少运行相关 API/Auth 测试和 `pnpm typecheck`；交付前按项目指引运行完整测试与构建。

src/shared/api/http.ts

@@ -61,6 +61,23 @@ export function registerAuthSessionExpiredHandler(handler: AuthSessionExpiredHan
   authSessionExpiredHandler = handler
 }
 
+export async function refreshAuthenticatedSession(): Promise<string> {
+  if (!authRefreshHandler) throw new Error('认证刷新处理器尚未初始化')
+  if (!activeRefresh) {
+    activeRefresh = authRefreshHandler()
+      .catch(async (refreshError) => {
+        try {
+          await authSessionExpiredHandler?.()
+        } catch {
+          // 会话已清理，跳转失败不应覆盖原始认证错误。
+        }
+        throw refreshError
+      })
+      .finally(() => { activeRefresh = null })
+  }
+  return activeRefresh
+}
+
 http.interceptors.request.use((config) => {
   const token = localStorage.getItem('cc-admin-token')
   const isAnonymousAuthEndpoint = typeof config.url === 'string'
@@ -82,19 +99,7 @@ http.interceptors.response.use(
 
     config._authRetry = true
     try {
-      if (!activeRefresh) {
-        activeRefresh = authRefreshHandler()
-          .catch(async (refreshError) => {
-            try {
-              await authSessionExpiredHandler?.()
-            } catch {
-              // 会话已清理，跳转失败不应覆盖原始认证错误。
-            }
-            throw refreshError
-          })
-          .finally(() => { activeRefresh = null })
-      }
-      const nextToken = await activeRefresh
+      const nextToken = await refreshAuthenticatedSession()
       config.headers.Authorization = `Bearer ${nextToken}`
       return http.request(config)
     } catch {

src/shared/api/overseasHttp.test.ts

@@ -0,0 +1,88 @@
+import axios, { type InternalAxiosRequestConfig } from 'axios'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { registerAuthRefreshHandler } from './http'
+import { clearOverseasAccessToken, overseasHttp, replaceOverseasAccessToken } from './overseasHttp'
+
+const originalOverseasAdapter = overseasHttp.defaults.adapter
+
+function success(config: InternalAxiosRequestConfig, data: unknown) {
+  return Promise.resolve({ status: 200, statusText: 'OK', headers: {}, config, data })
+}
+
+describe('overseas HTTP client', () => {
+  beforeEach(() => {
+    localStorage.setItem('cc-admin-token', 'domestic-token')
+    clearOverseasAccessToken()
+    registerAuthRefreshHandler(async () => 'domestic-token')
+  })
+
+  afterEach(() => {
+    overseasHttp.defaults.adapter = originalOverseasAdapter
+    localStorage.clear()
+    clearOverseasAccessToken()
+  })
+
+  it('uses the overseas token supplied by the login session for concurrent requests', async () => {
+    replaceOverseasAccessToken('overseas-token', 900)
+    const authorizations: unknown[] = []
+    overseasHttp.defaults.adapter = async (config) => {
+      authorizations.push(config.headers.Authorization)
+      return success(config, { code: '200', message: 'success', data: [] })
+    }
+
+    await Promise.all([
+      overseasHttp.get('/platform/v1/last-leg/orders'),
+      overseasHttp.get('/platform/v1/warehouse-admin'),
+    ])
+
+    expect(authorizations).toEqual(['Bearer overseas-token', 'Bearer overseas-token'])
+  })
+
+  it('refreshes the unified session once and replays once after an overseas 401', async () => {
+    replaceOverseasAccessToken('overseas-1', 900)
+    const refresh = vi.fn(async () => {
+      replaceOverseasAccessToken('overseas-2', 900)
+      return 'domestic-2'
+    })
+    registerAuthRefreshHandler(refresh)
+    let requests = 0
+    const authorizations: unknown[] = []
+    overseasHttp.defaults.adapter = async (config) => {
+      authorizations.push(config.headers.Authorization)
+      if (requests++ === 0) {
+        throw new axios.AxiosError('Unauthorized', 'ERR_BAD_REQUEST', config, undefined, {
+          status: 401,
+          statusText: 'Unauthorized',
+          headers: {},
+          config,
+          data: { code: 'A0401', message: '海外令牌失效' },
+        })
+      }
+      return success(config, { code: '200', message: 'success', data: [] })
+    }
+
+    await overseasHttp.get('/platform/v1/last-leg/orders')
+
+    expect(refresh).toHaveBeenCalledTimes(1)
+    expect(requests).toBe(2)
+    expect(authorizations).toEqual(['Bearer overseas-1', 'Bearer overseas-2'])
+  })
+
+  it('refreshes the unified session when no usable overseas token is present', async () => {
+    const refresh = vi.fn(async () => {
+      replaceOverseasAccessToken('overseas-refreshed', 900)
+      return 'domestic-refreshed'
+    })
+    registerAuthRefreshHandler(refresh)
+    let authorization: unknown
+    overseasHttp.defaults.adapter = async (config) => {
+      authorization = config.headers.Authorization
+      return success(config, { code: '200', message: 'success', data: [] })
+    }
+
+    await overseasHttp.get('/platform/v1/last-leg/orders')
+
+    expect(refresh).toHaveBeenCalledTimes(1)
+    expect(authorization).toBe('Bearer overseas-refreshed')
+  })
+})

src/shared/api/overseasHttp.ts

@@ -0,0 +1,77 @@
+import axios, { type InternalAxiosRequestConfig } from 'axios'
+import { parseApiJsonResponse } from '@chongchong/shared'
+import { refreshAuthenticatedSession } from './http'
+
+interface CachedOverseasToken {
+  accessToken: string
+  refreshAfter: number
+}
+
+type RetryableOverseasRequestConfig = InternalAxiosRequestConfig & { _overseasAuthRetry?: boolean }
+
+const TOKEN_REFRESH_SAFETY_WINDOW_MS = 30_000
+
+let cachedToken: CachedOverseasToken | null = null
+
+export const overseasHttp = axios.create({
+  baseURL: import.meta.env.VITE_OVERSEAS_API_BASE_URL || '/overseas-api',
+  timeout: 15_000,
+  transformResponse: [(data: unknown) => parseApiJsonResponse(data)],
+})
+
+function currentOverseasAccessToken() {
+  return cachedToken && cachedToken.refreshAfter > Date.now() ? cachedToken.accessToken : ''
+}
+
+async function requireOverseasAccessToken() {
+  const current = currentOverseasAccessToken()
+  if (current) return current
+  await refreshAuthenticatedSession()
+  const refreshed = currentOverseasAccessToken()
+  if (!refreshed) throw new Error('当前环境未签发海外访问令牌')
+  return refreshed
+}
+
+export function replaceOverseasAccessToken(accessToken: string | null, expiresIn: number) {
+  if (!accessToken && expiresIn === 0) {
+    cachedToken = null
+    return
+  }
+  if (!accessToken || !Number.isFinite(expiresIn) || expiresIn <= 0) {
+    throw new Error('海外访问令牌响应无效')
+  }
+  cachedToken = {
+    accessToken,
+    refreshAfter: Date.now() + Math.max(0, expiresIn * 1000 - TOKEN_REFRESH_SAFETY_WINDOW_MS),
+  }
+}
+
+export function clearOverseasAccessToken() {
+  cachedToken = null
+}
+
+overseasHttp.interceptors.request.use(async (config) => {
+  const accessToken = await requireOverseasAccessToken()
+  config.headers.Authorization = `Bearer ${accessToken}`
+  return config
+})
+
+overseasHttp.interceptors.response.use(
+  (response) => response.data,
+  async (error) => {
+    const config = error.config as RetryableOverseasRequestConfig | undefined
+    if (error.response?.status !== 401 || !config || config._overseasAuthRetry) {
+      return Promise.reject(error)
+    }
+    config._overseasAuthRetry = true
+    clearOverseasAccessToken()
+    try {
+      await refreshAuthenticatedSession()
+      const accessToken = await requireOverseasAccessToken()
+      config.headers.Authorization = `Bearer ${accessToken}`
+      return overseasHttp.request(config)
+    } catch {
+      return Promise.reject(error)
+    }
+  },
+)

src/shared/components/AGENTS.md

@@ -0,0 +1,33 @@
+# Admin Shared Components Instructions
+
+## 适用范围
+
+- 本文件适用于 `src/shared/components/` 及其直接测试。业务页面使用这些组件时，同时遵守 `../../../AGENTS.md` 和 `../../../../../docs/Admin-Client前端原型还原验收规则.md`。
+- 这里只放与具体业务无关、已被多个模块真实复用的后台组件；纯业务字段、状态和流程留在所属模块。
+
+## 标准列表组合
+
+- 标准列表使用 `ListPageLayout` 组织查询区和表格区，保持单一 `16px` 间距；不叠加页面级空白操作区或重复面板间距。
+- 查询与筛选使用 `QueryToolbar.vue`，通过 `fields`、`v-model`、`search`、`reset` 接入；查询即刷新当前结果，不另设独立刷新按钮。
+- 数据列表使用 `DataTable.vue`，通过 `columns`、命名插槽、`v-model:page`、`v-model:page-size` 和 `total` 接入，不重复拼装 `el-table` 与分页器。
+- “操作”列放在第一列，需要固定时固定在左侧。单行操作不超过 3 个时直接显示“图标 + 文案”；第 4 个起使用 `MoreHorizontal` 菜单，并优先直接保留详情、编辑、下载等高频操作。
+- 新增、导入、导出和批量操作放入 `DataTable` 的 `toolbar-actions`；不放入查询栏，不用 `toolbar-start` 重复列表标题、数量或说明，数量统一放在 `pagination-left`。
+- 路由标题和说明默认由 `AppLayout` 的 `page-heading` 根据路由元数据展示；标准列表正文不重复标题。只有明确关闭路由页头的详情页或工作台才自带独立页头。
+
+## 复用入口
+
+- XLSX 批量导入使用 `BatchImportDialog.vue`；页面只提供模板下载、导入调用和成功后刷新，不复制文件校验、上传状态、错误报告或弹窗 CSS。
+- 模态框和抽屉优先使用 `AppDialog.vue`、`AppDrawer.vue`；但独立页面、弹框或抽屉的选择必须服从对应原型，不因已有组件方便而替换承载方式。
+- 加载失败组合 `LoadErrorState.vue` 与 `ApiErrorMeta.vue`，保留重试和 `requestId`/`traceId`；状态与复制优先使用 `StatusBadge.vue`、`CopyButton.vue`。
+- 参考页面：查询和表格见 `../../modules/master-data/express-companies/pages/ExpressCompaniesView.vue`，批量导入见该页面与 `../../modules/master-data/counterparties/pages/PartnersView.vue`，抽屉见 `../../modules/downloads/pages/DownloadCenterView.vue`。
+
+## 图标、状态与可访问性
+
+- 原型已定义图标时复用原型资源；原型未定义时使用 Lucide：查看 `Eye`、编辑 `Pencil`、更多 `MoreHorizontal`、新增 `Plus`、删除 `Trash2`、启停 `Power`、刷新 `RefreshCw`、导入 `FileUp`、导出/下载 `Download`、返回 `ArrowLeft`、保存 `Save`、复制 `Copy`。
+- 危险操作保留明确文案、危险色、确认过程和成功/失败反馈，不只显示图标。
+- 组件按适用语义覆盖加载、空数据、错误、禁用和无权限状态；保留键盘操作、可见焦点、表单标签、图标按钮名称和颜色对比度，不只用颜色表达状态。
+
+## 修改与验证
+
+- 扩展公共组件前定向检查全部消费者；通用能力扩展公共组件，纯业务特例留在模块，不用页面级 CSS 覆盖破坏公共契约。
+- 至少运行组件测试、直接受影响页面测试和 `pnpm typecheck`；交付前按项目指引运行完整测试与构建。