create-react-admin-template 0.0.0-stage → 0.1.0

package/template/src/features/showcase/messages.ts

@@ -0,0 +1,192 @@
+import { fnDefineLocaleMessages } from '@/locale'
+
+/** 脚手架功能演示页面共用的中英文文案。 */
+export const objShowcaseMessages = fnDefineLocaleMessages({
+  'en-US': {
+    advancedTableDescription:
+      'The optional advanced table provides built-in querying, pagination, selection, editing, preferences, and toolbar actions.',
+    advancedTableTitle: 'Advanced AppTable',
+    advancedTableUnavailable:
+      'The advancedTable capability is not installed, or this is a production build without the demo entry.',
+    commonActions: 'Actions',
+    commonAdd: 'Add record',
+    commonAll: 'All statuses',
+    commonDelete: 'Delete',
+    commonEdit: 'Edit',
+    commonName: 'Name',
+    commonNext: 'Next',
+    commonOwner: 'Owner',
+    commonPrevious: 'Previous',
+    commonReset: 'Reset demo',
+    commonStatus: 'Status',
+    commonSubmit: 'Save record',
+    feedbackDialogContent:
+      'This dialog uses the project-owned overlay, focus management, and action conventions.',
+    feedbackDialogTitle: 'Confirm an operation',
+    feedbackConfirm: 'Confirm',
+    feedbackConfirmed: 'The demonstration operation was confirmed.',
+    feedbackDescription:
+      'Switch between page states, open a dialog, trigger a toast, and visit the standard error routes.',
+    feedbackEmptyDescription:
+      'The request succeeded, but the current filters returned no records.',
+    feedbackEmptyTitle: 'No matching records',
+    feedbackErrorDescription:
+      'The simulated request failed. Retry keeps the current page context.',
+    feedbackErrorTitle: 'Request failed',
+    feedbackLoadingDescription:
+      'The first request is loading and no cached content is available yet.',
+    feedbackLoadingTitle: 'Loading data',
+    feedbackOpenDialog: 'Open dialog',
+    feedbackErrorRoutes: 'Standard error pages',
+    feedbackShowEmpty: 'Empty state',
+    feedbackShowError: 'Error state',
+    feedbackShowLoading: 'Loading state',
+    feedbackShowToast: 'Show toast',
+    feedbackStateTitle: 'Switch the rendered page state',
+    feedbackTitle: 'Dialogs and page feedback',
+    feedbackToastContent: 'This is a global success toast.',
+    filesDescription:
+      'Select an image or PDF to exercise validation, upload progress, completion callbacks, and local preview cleanup.',
+    filesNoPreview: 'Select a supported file to display its preview here.',
+    filesPreviewTitle: 'File preview',
+    filesSelect: 'Select an image or PDF',
+    filesTitle: 'Upload and preview',
+    filesUploadDescription:
+      'Demo adapter only keeps the selected File in memory and does not send it to a server.',
+    filesUploadTitle: 'File upload',
+    formDepartment: 'Department',
+    formDepartmentFinance: 'Finance',
+    formDepartmentOperations: 'Operations',
+    formDepartmentTechnology: 'Technology',
+    formDescription:
+      'Use real field types, validation, conditional content, reset behavior, dirty tracking, and submit feedback.',
+    formEmail: 'Contact email',
+    formDirty: 'Unsaved changes',
+    formEditorTitle: 'Application configuration',
+    formName: 'Application name',
+    formNotes: 'Notes',
+    formNotSubmitted: 'Submit a valid form to inspect the resulting model.',
+    formPristine: 'No changes',
+    formQuota: 'User quota',
+    formStatus: 'Lifecycle status',
+    formSubmit: 'Validate and submit',
+    formSubmitted: 'Latest submitted model',
+    formTitle: 'PageForm interaction',
+    metadataDescription:
+      'The demo sources use the same catalog adapters, Query cache, typed hooks, value lookup, and display components as backend data.',
+    metadataEnumKeys: 'Enum keys',
+    metadataEnumTitle: 'Global enum catalog',
+    metadataLookup: 'Label-to-value lookup',
+    metadataParameterTitle: 'Typed global parameters',
+    metadataRefresh: 'Refresh catalogs',
+    metadataTitle: 'Enums and global parameters',
+    metadataValues: 'Complete values',
+    metadataVersion: 'Catalog version',
+    pageEyebrow: 'Scaffold live demo',
+    statusActive: 'Active',
+    statusDisabled: 'Disabled',
+    statusPending: 'Pending',
+    tableBulkActivate: 'Activate selected',
+    tableCoreDescription:
+      'A lightweight CRUD page composed from AppDataTable, AppPageForm, AppDialog, search, selection, and pagination.',
+    tableCoreTitle: 'Core CRUD page',
+    tableDescription:
+      'Operate the lightweight list and the optional advanced grid instead of reading a component inventory.',
+    tablePage: 'Page {current} of {total}',
+    tableSearchPlaceholder: 'Search name or owner',
+    tableSelected: '{count} selected',
+    tableTitle: 'Table scenarios',
+  },
+  'zh-CN': {
+    advancedTableDescription:
+      '可选高级表格直接提供查询、分页、选择、编辑、偏好和工具栏操作。',
+    advancedTableTitle: '高级 AppTable',
+    advancedTableUnavailable:
+      '当前没有安装 advancedTable 能力，或生产构建未开放开发演示入口。',
+    commonActions: '操作',
+    commonAdd: '新增记录',
+    commonAll: '全部状态',
+    commonDelete: '删除',
+    commonEdit: '编辑',
+    commonName: '名称',
+    commonNext: '下一页',
+    commonOwner: '负责人',
+    commonPrevious: '上一页',
+    commonReset: '重置演示',
+    commonStatus: '状态',
+    commonSubmit: '保存记录',
+    feedbackDialogContent:
+      '此弹窗实际使用项目源码内的遮罩层、焦点管理和统一操作区规范。',
+    feedbackDialogTitle: '确认执行操作',
+    feedbackConfirm: '确认执行',
+    feedbackConfirmed: '演示操作已确认。',
+    feedbackDescription:
+      '切换页面状态、打开弹窗、触发 Toast，并直接访问标准错误页面。',
+    feedbackEmptyDescription: '请求已经成功，但当前筛选条件没有匹配记录。',
+    feedbackEmptyTitle: '暂无匹配记录',
+    feedbackErrorDescription: '模拟请求失败；重试不会丢失当前页面上下文。',
+    feedbackErrorTitle: '请求失败',
+    feedbackLoadingDescription:
+      '首次请求正在加载，当前还没有可展示的缓存内容。',
+    feedbackLoadingTitle: '正在加载数据',
+    feedbackOpenDialog: '打开弹窗',
+    feedbackErrorRoutes: '标准错误页面',
+    feedbackShowEmpty: '空状态',
+    feedbackShowError: '错误状态',
+    feedbackShowLoading: '加载状态',
+    feedbackShowToast: '触发 Toast',
+    feedbackStateTitle: '切换实际渲染的页面状态',
+    feedbackTitle: '弹窗与页面反馈',
+    feedbackToastContent: '这是一条全局成功提示。',
+    filesDescription:
+      '选择图片或 PDF，实际体验文件校验、上传进度、成功回调和本地预览资源释放。',
+    filesNoPreview: '请选择支持的文件后在这里查看预览。',
+    filesPreviewTitle: '文件预览',
+    filesSelect: '选择图片或 PDF',
+    filesTitle: '上传与预览',
+    filesUploadDescription:
+      '演示适配器只在内存中保留所选 File，不会把文件发送到任何服务器。',
+    filesUploadTitle: '文件上传',
+    formDepartment: '所属部门',
+    formDepartmentFinance: '财务部',
+    formDepartmentOperations: '运营部',
+    formDepartmentTechnology: '技术部',
+    formDescription:
+      '实际体验字段类型、校验、条件内容、重置、脏状态跟踪和提交反馈。',
+    formEmail: '联系邮箱',
+    formDirty: '存在未保存修改',
+    formEditorTitle: '应用配置',
+    formName: '应用名称',
+    formNotes: '补充说明',
+    formNotSubmitted: '提交一份校验通过的表单后，这里会展示最终模型。',
+    formPristine: '尚未修改',
+    formQuota: '用户配额',
+    formStatus: '生命周期状态',
+    formSubmit: '校验并提交',
+    formSubmitted: '最近提交模型',
+    formTitle: 'PageForm 交互',
+    metadataDescription:
+      '演示数据源与后端数据使用相同的目录适配、Query 缓存、类型 Hook、值反查和展示组件。',
+    metadataEnumKeys: '枚举 Key',
+    metadataEnumTitle: '全局枚举目录',
+    metadataLookup: '文案反查值',
+    metadataParameterTitle: '类型安全全局参数',
+    metadataRefresh: '刷新目录',
+    metadataTitle: '枚举与全局参数',
+    metadataValues: '完整 Value 列表',
+    metadataVersion: '目录版本',
+    pageEyebrow: '脚手架功能实演',
+    statusActive: '启用',
+    statusDisabled: '停用',
+    statusPending: '待审核',
+    tableBulkActivate: '批量启用',
+    tableCoreDescription:
+      '由 AppDataTable、AppPageForm、AppDialog、搜索、选择和分页组合出的轻量 CRUD 页面。',
+    tableCoreTitle: '核心 CRUD 页面',
+    tableDescription: '直接操作轻量列表和可选高级网格，不再只展示组件名称。',
+    tablePage: '第 {current} / {total} 页',
+    tableSearchPlaceholder: '搜索名称或负责人',
+    tableSelected: '已选择 {count} 项',
+    tableTitle: '表格业务场景',
+  },
+})

package/template/src/files/download.ts

@@ -0,0 +1,82 @@
+import { FileCapabilityError } from './errors'
+import { fnParseDownloadFileName } from './filename'
+import type {
+  IExternalFileDownloadOptions,
+  IFileMemoryDownloadOptions,
+  IFileTransferProgress,
+} from './types'
+
+const nDefaultMaxMemoryBytes = 100 * 1024 * 1024
+
+function fnIsErrorContentType(strContentType: string) {
+  const strNormalized = strContentType.toLowerCase()
+  return (
+    strNormalized.includes('application/json') ||
+    strNormalized.includes('application/problem+json') ||
+    strNormalized.includes('text/html')
+  )
+}
+
+/** 使用对象 URL 保存 Blob，并在当前事件循环结束后释放资源。 */
+export function fnSaveBlob(objBlob: Blob, strFileName: string) {
+  const strObjectUrl = URL.createObjectURL(objBlob)
+  const objAnchor = document.createElement('a')
+  objAnchor.href = strObjectUrl
+  objAnchor.download = strFileName
+  objAnchor.rel = 'noopener'
+  objAnchor.style.display = 'none'
+  document.body.append(objAnchor)
+  objAnchor.click()
+  objAnchor.remove()
+  window.setTimeout(() => URL.revokeObjectURL(strObjectUrl), 0)
+}
+
+/**
+ * 下载适合放入浏览器内存的文件。
+ *
+ * 大文件必须在请求前选择 `fnRunExternalFileDownload` 或异步导出任务，不能先
+ * 创建超大 Blob 再补救。
+ */
+export async function fnDownloadFile(
+  objOptions: IFileMemoryDownloadOptions,
+  objSignal: AbortSignal = new AbortController().signal,
+  fnOnProgress: (objProgress: IFileTransferProgress) => void = () => undefined
+) {
+  const objResponse = await objOptions.fnRequest({ objSignal, fnOnProgress })
+  const strContentType =
+    objResponse.strContentType || objResponse.objBlob.type || ''
+  const bIsAttachment = /(?:^|;)\s*attachment(?:;|$)/i.test(
+    objResponse.strContentDisposition ?? ''
+  )
+  if (fnIsErrorContentType(strContentType) && !bIsAttachment) {
+    throw new FileCapabilityError({
+      bRetriable: true,
+      strCode: 'DOWNLOAD_ERROR_CONTENT',
+      strMessage: '下载接口返回了错误内容，请稍后重试',
+    })
+  }
+
+  const nMaxBytes = objOptions.nMaxBytes ?? nDefaultMaxMemoryBytes
+  if (objResponse.objBlob.size > nMaxBytes) {
+    throw new FileCapabilityError({
+      strCode: 'DOWNLOAD_TOO_LARGE_FOR_MEMORY',
+      strMessage: '文件过大，请改用大文件下载或异步导出',
+    })
+  }
+
+  const strFileName = fnParseDownloadFileName(
+    objResponse.strContentDisposition,
+    objOptions.strFallbackFileName
+  )
+  fnSaveBlob(objResponse.objBlob, strFileName)
+  return strFileName
+}
+
+/** 执行不经过 Blob 内存缓存的大文件下载适配器。 */
+export async function fnRunExternalFileDownload(
+  objOptions: IExternalFileDownloadOptions,
+  objSignal: AbortSignal = new AbortController().signal,
+  fnOnProgress: (objProgress: IFileTransferProgress) => void = () => undefined
+) {
+  await objOptions.objAdapter.fnDownload({ objSignal, fnOnProgress })
+}

package/template/src/files/errors.ts

@@ -0,0 +1,15 @@
+import { ApiError } from '@/api/ApiError'
+import type { IFileCapabilityErrorOptions } from './types'
+
+/** 文件上传、下载、预览与任务协调的标准错误。 */
+export class FileCapabilityError extends ApiError {
+  constructor(objOptions: IFileCapabilityErrorOptions) {
+    super({
+      bRetriable: objOptions.bRetriable ?? false,
+      strCode: objOptions.strCode,
+      strKind: 'client',
+      strMessage: objOptions.strMessage,
+    })
+    this.name = 'FileCapabilityError'
+  }
+}

package/template/src/files/filename.ts

@@ -0,0 +1,61 @@
+const nMaxFileNameLength = 180
+
+function fnDecodeExtendedFileName(strValue: string) {
+  const strEncoded = strValue.replace(/^UTF-8''/i, '')
+  try {
+    return decodeURIComponent(strEncoded)
+  } catch {
+    return strEncoded
+  }
+}
+
+/**
+ * 清理来自响应头或业务输入的文件名，移除路径、控制字符和平台保留结尾。
+ */
+export function fnSanitizeFileName(
+  strFileName: string,
+  strFallback = 'download'
+) {
+  const strBaseName = strFileName
+    .replaceAll('\\', '/')
+    .split('/')
+    .at(-1)
+    ?.split('')
+    .map((strCharacter) => {
+      const nCodePoint = strCharacter.codePointAt(0) ?? 0
+      return nCodePoint <= 31 || nCodePoint === 127 ? ' ' : strCharacter
+    })
+    .join('')
+    .replace(/[<>:"|?*]/g, '_')
+    .replace(/[. ]+$/g, '')
+    .trim()
+  if (!strBaseName || strBaseName === '.' || strBaseName === '..') {
+    return strFallback
+  }
+  return Array.from(strBaseName).slice(0, nMaxFileNameLength).join('')
+}
+
+/** 优先解析 RFC 5987 `filename*`，再回退到普通 `filename`。 */
+export function fnParseDownloadFileName(
+  strContentDisposition: string | undefined,
+  strFallback = 'download'
+) {
+  if (!strContentDisposition) return fnSanitizeFileName(strFallback)
+
+  const objExtendedMatch = /filename\*\s*=\s*([^;]+)/i.exec(
+    strContentDisposition
+  )
+  if (objExtendedMatch?.[1]) {
+    const strValue = objExtendedMatch[1].trim().replace(/^"|"$/g, '')
+    return fnSanitizeFileName(
+      fnDecodeExtendedFileName(strValue),
+      fnSanitizeFileName(strFallback)
+    )
+  }
+
+  const objBasicMatch = /filename\s*=\s*(?:"([^"]*)"|([^;]*))/i.exec(
+    strContentDisposition
+  )
+  const strValue = (objBasicMatch?.[1] ?? objBasicMatch?.[2])?.trim()
+  return fnSanitizeFileName(strValue ?? strFallback, strFallback)
+}

package/template/src/files/index.ts

@@ -0,0 +1,38 @@
+export {
+  fnDownloadFile,
+  fnRunExternalFileDownload,
+  fnSaveBlob,
+} from './download'
+export { FileCapabilityError } from './errors'
+export { fnParseDownloadFileName, fnSanitizeFileName } from './filename'
+export { useFileTask } from './useFileTask'
+export { useFileUpload } from './useFileUpload'
+export { fnCreateFileAccept, fnValidateFiles } from './validation'
+export type {
+  IExternalFileDownloadAdapter,
+  IExternalFileDownloadOptions,
+  IFileCapabilityErrorOptions,
+  IFileDownloadContext,
+  IFileDownloadResponse,
+  IFileMemoryDownloadOptions,
+  IFileTaskAdapter,
+  IFileTaskContext,
+  IFileTransferProgress,
+  IFileUploadContext,
+  IFileValidationIssue,
+  IFileValidationOptions,
+  IFileValidationResult,
+  IUseFileTaskOptions,
+  IUseFileTaskResult,
+  IUseFileUploadOptions,
+  IUseFileUploadResult,
+  TFileCapabilityErrorCode,
+  TFileDownloadRequest,
+  TExternalFileDownloadContext,
+  TFileTaskPollResult,
+  TFileTaskStartResult,
+  TFileTaskState,
+  TFileUploadRequest,
+  TFileUploadState,
+  TFileValidationIssueCode,
+} from './types'

package/template/src/files/types.ts

@@ -0,0 +1,299 @@
+/** 文件校验失败的稳定错误码。 */
+export type TFileValidationIssueCode =
+  | 'EMPTY_FILE'
+  | 'FILE_TOO_LARGE'
+  | 'FILE_TYPE_NOT_ALLOWED'
+  | 'TOO_MANY_FILES'
+
+/** 文件能力层抛出的稳定错误码。 */
+export type TFileCapabilityErrorCode =
+  | 'DOWNLOAD_ERROR_CONTENT'
+  | 'DOWNLOAD_TOO_LARGE_FOR_MEMORY'
+  | 'INVALID_PREVIEW_URL'
+  | 'TASK_POLLING_NOT_CONFIGURED'
+  | 'UNSUPPORTED_PREVIEW_TYPE'
+
+/** 单个文件校验问题；不得包含文件内容或服务端原始响应。 */
+export interface IFileValidationIssue {
+  /** 供界面分支和测试使用的稳定错误码。 */
+  strCode: TFileValidationIssueCode
+  /** 可直接展示给用户的安全说明。 */
+  strMessage: string
+  /** 发生问题的文件名；数量限制等集合问题可能不存在。 */
+  strFileName?: string
+}
+
+/** 浏览器选中文件后的体验校验规则，不能替代后端鉴权、扫描和内容校验。 */
+export interface IFileValidationOptions {
+  /** 允许的扩展名，建议包含点号，例如 `.pdf`；比较时忽略大小写。 */
+  arrAcceptedExtensions?: readonly string[]
+  /** 允许的 MIME，可使用 `image/*`；浏览器声明的 MIME 不能作为安全依据。 */
+  arrAcceptedMimeTypes?: readonly string[]
+  /** 是否允许零字节文件，默认不允许。 */
+  bAllowEmptyFile?: boolean
+  /** 单个文件最大字节数；省略表示不在浏览器侧限制。 */
+  nMaxBytes?: number
+  /** 一次最多选择的文件数量；省略表示不限制。 */
+  nMaxFiles?: number
+}
+
+/** 一次文件校验的完整结果。 */
+export interface IFileValidationResult {
+  /** 通过浏览器体验校验、可继续提交的文件。 */
+  arrAcceptedFiles: readonly File[]
+  /** 所有集合级和文件级问题。 */
+  arrIssues: readonly IFileValidationIssue[]
+}
+
+/** 上传、下载或后台任务的统一进度。 */
+export interface IFileTransferProgress {
+  /** 已处理字节数；后台任务没有字节概念时可省略。 */
+  nLoadedBytes?: number
+  /** 总字节数；服务端未提供时可省略。 */
+  nTotalBytes?: number
+  /** 0 至 100 的显示百分比；无法计算时可省略。 */
+  nPercent?: number
+  /** 业务适配器提供的安全阶段说明，例如“正在校验”。 */
+  strMessage?: string
+}
+
+/** 上传适配器接收的运行上下文。 */
+export interface IFileUploadContext {
+  /** 已通过浏览器体验校验的文件。 */
+  arrFiles: readonly File[]
+  /** 取消信号，必须透传给 Swagger 生成客户端的 Axios 配置。 */
+  objSignal: AbortSignal
+  /** 将 Axios 上传进度转换为统一进度后调用。 */
+  fnOnProgress: (objProgress: IFileTransferProgress) => void
+}
+
+/** 由业务层使用 Swagger 生成客户端实现的上传函数。 */
+export type TFileUploadRequest<TResult> = (
+  objContext: IFileUploadContext
+) => Promise<TResult>
+
+/** 上传钩子的配置。 */
+export interface IUseFileUploadOptions<TResult> {
+  /** 实际上传函数；文件能力层不会自行拼接地址或直接请求后端。 */
+  fnUpload: TFileUploadRequest<TResult>
+  /** 浏览器体验校验规则。 */
+  objValidation?: IFileValidationOptions
+}
+
+/** 上传过程的互斥状态。 */
+export type TFileUploadState<TResult> =
+  | {
+      /** 尚未选择或上传文件。 */
+      strStatus: 'idle'
+    }
+  | {
+      /** 上传请求正在执行。 */
+      strStatus: 'uploading'
+      /** 当前上传的文件。 */
+      arrFiles: readonly File[]
+      /** 最近一次上传进度。 */
+      objProgress: IFileTransferProgress
+    }
+  | {
+      /** 上传已经成功完成。 */
+      strStatus: 'success'
+      /** 已完成上传的文件。 */
+      arrFiles: readonly File[]
+      /** 业务上传适配器返回的结果。 */
+      objResult: TResult
+    }
+  | {
+      /** 浏览器体验校验或上传请求失败。 */
+      strStatus: 'error'
+      /** 本次尝试选择的文件。 */
+      arrFiles: readonly File[]
+      /** 浏览器体验校验问题；服务端失败时为空数组。 */
+      arrIssues: readonly IFileValidationIssue[]
+      /** 可安全展示或上报的标准错误。 */
+      objError: Error
+    }
+  | {
+      /** 用户取消了上传请求。 */
+      strStatus: 'canceled'
+      /** 被取消上传的文件。 */
+      arrFiles: readonly File[]
+    }
+
+/** 上传钩子返回的命令与单一状态快照。 */
+export interface IUseFileUploadResult<TResult> {
+  /** 取消当前上传；完成后调用没有副作用。 */
+  fnCancel: () => void
+  /** 使用最近一次文件重新上传；没有历史文件时保持空闲。 */
+  fnRetry: () => Promise<TResult | undefined>
+  /** 校验并上传指定文件；校验不通过时不会调用后端。 */
+  fnUpload: (arrFiles: readonly File[]) => Promise<TResult | undefined>
+  /** 当前互斥状态，避免多个布尔值组合出非法状态。 */
+  objState: TFileUploadState<TResult>
+}
+
+/** 下载适配器接收的运行上下文。 */
+export interface IFileDownloadContext {
+  /** 取消信号，必须透传给 Swagger 生成客户端。 */
+  objSignal: AbortSignal
+  /** 将 Axios 下载进度转换为统一进度后调用。 */
+  fnOnProgress: (objProgress: IFileTransferProgress) => void
+}
+
+/** 由生成客户端适配后的内存下载响应。 */
+export interface IFileDownloadResponse {
+  /** Axios 使用 `responseType: 'blob'` 返回的文件内容。 */
+  objBlob: Blob
+  /** 原始 Content-Disposition；仅用于受控文件名解析，不得直接写入 DOM。 */
+  strContentDisposition?: string
+  /** 原始 Content-Type；仅用于响应分类，不能作为内容安全证明。 */
+  strContentType?: string
+}
+
+/** 由业务层使用 Swagger 生成客户端实现的下载请求。 */
+export type TFileDownloadRequest = (
+  objContext: IFileDownloadContext
+) => Promise<IFileDownloadResponse>
+
+/** 适合中小文件的 Blob 内存下载配置。 */
+export interface IFileMemoryDownloadOptions {
+  /** 实际下载请求。 */
+  fnRequest: TFileDownloadRequest
+  /** Blob 允许占用的最大字节数，默认 100 MiB。 */
+  nMaxBytes?: number
+  /** 响应未提供合法文件名时使用的名称。 */
+  strFallbackFileName?: string
+}
+
+/** 大文件、签名 URL 或原生流式保存适配器的运行上下文。 */
+export type TExternalFileDownloadContext = IFileDownloadContext
+
+/** 大文件下载适配器；基础层不假定具体对象存储或浏览器流方案。 */
+export interface IExternalFileDownloadAdapter {
+  /** 启动外部下载，并负责目标 URL 信任校验、凭据策略和资源释放。 */
+  fnDownload: (objContext: TExternalFileDownloadContext) => Promise<void>
+}
+
+/** 外部下载执行配置。 */
+export interface IExternalFileDownloadOptions {
+  /** 业务或基础设施层提供的大文件下载适配器。 */
+  objAdapter: IExternalFileDownloadAdapter
+}
+
+/** 文件任务适配器接收的运行上下文。 */
+export interface IFileTaskContext {
+  /** 取消信号，必须透传给启动和轮询请求。 */
+  objSignal: AbortSignal
+  /** 同步转换或服务端任务进度回调。 */
+  fnOnProgress: (objProgress: IFileTransferProgress) => void
+}
+
+/** 文件任务启动后立即完成或进入后台队列。 */
+export type TFileTaskStartResult<TResult> =
+  | {
+      /** 请求内已经完成，无需轮询。 */
+      strMode: 'completed'
+      /** 同步任务结果。 */
+      objResult: TResult
+    }
+  | {
+      /** 服务端已创建后台任务。 */
+      strMode: 'background'
+      /** 服务端任务稳定标识。 */
+      strTaskId: string
+    }
+
+/** 后台文件任务单次轮询结果。 */
+export type TFileTaskPollResult<TResult> =
+  | {
+      /** 后台任务仍在排队或执行。 */
+      strStatus: 'queued' | 'running'
+      /** 服务端最近一次返回的任务进度。 */
+      objProgress?: IFileTransferProgress
+    }
+  | {
+      /** 后台任务成功完成。 */
+      strStatus: 'success'
+      /** 后台任务结果。 */
+      objResult: TResult
+    }
+  | {
+      /** 后台任务以业务失败结束。 */
+      strStatus: 'error'
+      /** 适配后的安全错误。 */
+      objError: Error
+    }
+
+/** 同步或异步导入导出任务的业务适配器。 */
+export interface IFileTaskAdapter<TInput, TResult> {
+  /** 启动任务；闭包中可使用生成客户端提交文件或导出条件。 */
+  fnStart: (
+    objInput: TInput,
+    objContext: IFileTaskContext
+  ) => Promise<TFileTaskStartResult<TResult>>
+  /** 查询后台任务；仅当 `fnStart` 返回 background 时需要。 */
+  fnPoll?: (
+    strTaskId: string,
+    objContext: IFileTaskContext
+  ) => Promise<TFileTaskPollResult<TResult>>
+}
+
+/** 文件任务钩子的配置。 */
+export interface IUseFileTaskOptions<TInput, TResult> {
+  /** 同步或异步任务适配器。 */
+  objAdapter: IFileTaskAdapter<TInput, TResult>
+  /** 后台任务轮询间隔，默认 1500ms，最小 250ms。 */
+  nPollIntervalMs?: number
+}
+
+/** 同步/异步文件任务的互斥状态。 */
+export type TFileTaskState<TResult> =
+  | {
+      /** 尚未启动任务。 */
+      strStatus: 'idle'
+    }
+  | {
+      /** 任务正在启动、排队或执行。 */
+      strStatus: 'starting' | 'queued' | 'running'
+      /** 最近一次任务进度。 */
+      objProgress: IFileTransferProgress
+      /** 后台任务标识；同步启动阶段不存在。 */
+      strTaskId?: string
+    }
+  | {
+      /** 同步或后台任务成功完成。 */
+      strStatus: 'success'
+      /** 文件任务结果。 */
+      objResult: TResult
+    }
+  | {
+      /** 启动、轮询或业务任务失败。 */
+      strStatus: 'error'
+      /** 可安全展示或上报的标准错误。 */
+      objError: Error
+    }
+  | {
+      /** 用户取消了任务。 */
+      strStatus: 'canceled'
+    }
+
+/** 文件任务钩子返回的命令与状态。 */
+export interface IUseFileTaskResult<TInput, TResult> {
+  /** 取消当前启动或轮询请求。 */
+  fnCancel: () => void
+  /** 使用最近一次输入重新开始任务。 */
+  fnRetry: () => Promise<TResult | undefined>
+  /** 启动同步或异步任务。 */
+  fnRun: (objInput: TInput) => Promise<TResult | undefined>
+  /** 当前互斥状态。 */
+  objState: TFileTaskState<TResult>
+}
+
+/** 构造文件能力错误的参数。 */
+export interface IFileCapabilityErrorOptions {
+  /** 稳定文件能力错误码。 */
+  strCode: TFileCapabilityErrorCode
+  /** 面向用户的安全错误说明。 */
+  strMessage: string
+  /** 用户是否可通过重试恢复。 */
+  bRetriable?: boolean
+}