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

package/template/src/reporting/model.ts

@@ -0,0 +1,373 @@
+import {
+  fnSanitizeFileName,
+  type IFileTransferProgress,
+  type TFileTaskPollResult,
+  type TFileTaskStartResult,
+} from '@/files'
+import { ReportingError } from './errors'
+import type {
+  IReportGenerationRequest,
+  IReportOutput,
+  IReportOutputInput,
+  IReportTemplate,
+  IReportTemplateCatalog,
+  IReportTemplateCatalogInput,
+  IReportTemplateInput,
+  TReportGenerationPollResultInput,
+  TReportGenerationStartResultInput,
+  TReportOutputFormat,
+} from './types'
+
+/** 单次模板目录允许返回的最大模板数量。 */
+export const nMaxReportTemplates = 200
+
+const nMaxIdentifierLength = 200
+const nMaxTemplateNameLength = 300
+const nMaxTemplateDescriptionLength = 2_000
+const nMaxProgressMessageLength = 300
+
+const objMimeTypeByFormat: Readonly<Record<TReportOutputFormat, string>> = {
+  csv: 'text/csv',
+  docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  pdf: 'application/pdf',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+}
+
+function fnNormalizeRequiredText(
+  strValue: string,
+  strField: string,
+  nMaxLength = nMaxIdentifierLength,
+  strCode:
+    | 'INVALID_CATALOG'
+    | 'INVALID_OUTPUT'
+    | 'INVALID_REQUEST'
+    | 'INVALID_TASK' = 'INVALID_CATALOG'
+) {
+  const strNormalizedValue = typeof strValue === 'string' ? strValue.trim() : ''
+  if (!strNormalizedValue || strNormalizedValue.length > nMaxLength) {
+    throw new ReportingError(
+      strCode,
+      `报表字段 ${strField} 必须是长度不超过 ${nMaxLength} 的非空字符串。`
+    )
+  }
+  return strNormalizedValue
+}
+
+function fnNormalizeOptionalText(
+  strValue: string | undefined,
+  strField: string,
+  nMaxLength: number
+) {
+  return strValue === undefined
+    ? undefined
+    : fnNormalizeRequiredText(strValue, strField, nMaxLength, 'INVALID_CATALOG')
+}
+
+function fnIsReportOutputFormat(
+  strFormat: string
+): strFormat is TReportOutputFormat {
+  return (
+    strFormat === 'csv' ||
+    strFormat === 'docx' ||
+    strFormat === 'pdf' ||
+    strFormat === 'xlsx'
+  )
+}
+
+function fnIsNonEmptyStringArray(
+  arrValues: readonly string[] | undefined
+): arrValues is readonly string[] {
+  return (
+    Array.isArray(arrValues) &&
+    arrValues.length > 0 &&
+    arrValues.every((objValue) => typeof objValue === 'string')
+  )
+}
+
+/** 校验一个输出格式，拒绝可执行 HTML 等未声明类型。 */
+export function fnNormalizeReportOutputFormat(
+  strFormat: string,
+  strCode:
+    | 'INVALID_CATALOG'
+    | 'INVALID_OUTPUT'
+    | 'INVALID_REQUEST' = 'INVALID_REQUEST'
+): TReportOutputFormat {
+  if (!fnIsReportOutputFormat(strFormat)) {
+    throw new ReportingError(strCode, '报表输出格式不受支持。')
+  }
+  return strFormat
+}
+
+function fnNormalizeReportTemplate(
+  objInput: IReportTemplateInput
+): IReportTemplate {
+  if (!objInput || typeof objInput !== 'object') {
+    throw new ReportingError('INVALID_CATALOG', '模板目录包含无效模板。')
+  }
+  if (!fnIsNonEmptyStringArray(objInput.arrFormats)) {
+    throw new ReportingError(
+      'INVALID_CATALOG',
+      '每个报表模板必须声明至少一种输出格式。'
+    )
+  }
+  const arrFormats = objInput.arrFormats.map((strFormat) =>
+    fnNormalizeReportOutputFormat(strFormat, 'INVALID_CATALOG')
+  )
+  if (new Set(arrFormats).size !== arrFormats.length) {
+    throw new ReportingError('INVALID_CATALOG', '报表模板包含重复输出格式。')
+  }
+
+  return Object.freeze({
+    arrFormats: Object.freeze(arrFormats),
+    strDescription: fnNormalizeOptionalText(
+      objInput.strDescription,
+      'strDescription',
+      nMaxTemplateDescriptionLength
+    ),
+    strTemplateId: fnNormalizeRequiredText(
+      objInput.strTemplateId ?? '',
+      'strTemplateId'
+    ),
+    strTemplateName: fnNormalizeRequiredText(
+      objInput.strTemplateName ?? '',
+      'strTemplateName',
+      nMaxTemplateNameLength
+    ),
+    strTemplateVersion: fnNormalizeRequiredText(
+      objInput.strTemplateVersion ?? '',
+      'strTemplateVersion'
+    ),
+  })
+}
+
+/** 校验并冻结后端模板目录，拒绝重复 ID、未知格式和无界数据。 */
+export function fnNormalizeReportTemplateCatalog(
+  objInput: IReportTemplateCatalogInput
+): IReportTemplateCatalog {
+  if (
+    !objInput ||
+    typeof objInput !== 'object' ||
+    !Array.isArray(objInput.arrTemplates) ||
+    objInput.arrTemplates.length > nMaxReportTemplates
+  ) {
+    throw new ReportingError(
+      'INVALID_CATALOG',
+      `报表模板目录最多允许 ${nMaxReportTemplates} 项。`
+    )
+  }
+  const arrTemplates = objInput.arrTemplates.map(fnNormalizeReportTemplate)
+  if (
+    new Set(arrTemplates.map((objTemplate) => objTemplate.strTemplateId))
+      .size !== arrTemplates.length
+  ) {
+    throw new ReportingError('INVALID_CATALOG', '模板目录包含重复模板 ID。')
+  }
+
+  return Object.freeze({
+    arrTemplates: Object.freeze(arrTemplates),
+    strCatalogVersion: fnNormalizeRequiredText(
+      objInput.strCatalogVersion ?? '',
+      'strCatalogVersion'
+    ),
+  })
+}
+
+/** 校验报表生成请求的稳定模板身份和输出格式。 */
+export function fnNormalizeReportGenerationRequest<TParameters>(
+  objRequest: IReportGenerationRequest<TParameters>
+): IReportGenerationRequest<TParameters> {
+  if (!objRequest || typeof objRequest !== 'object') {
+    throw new ReportingError('INVALID_REQUEST', '报表生成请求无效。')
+  }
+  return Object.freeze({
+    objParameters: objRequest.objParameters,
+    strFormat: fnNormalizeReportOutputFormat(
+      objRequest.strFormat,
+      'INVALID_REQUEST'
+    ),
+    strTemplateId: fnNormalizeRequiredText(
+      objRequest.strTemplateId,
+      'strTemplateId',
+      nMaxIdentifierLength,
+      'INVALID_REQUEST'
+    ),
+    strTemplateVersion: fnNormalizeRequiredText(
+      objRequest.strTemplateVersion,
+      'strTemplateVersion',
+      nMaxIdentifierLength,
+      'INVALID_REQUEST'
+    ),
+  })
+}
+
+/** 校验报表结果的文件身份、格式、MIME 和安全文件名。 */
+export function fnNormalizeReportOutput(
+  objInput: IReportOutputInput,
+  strExpectedFormat?: TReportOutputFormat
+): IReportOutput {
+  if (!objInput || typeof objInput !== 'object') {
+    throw new ReportingError('INVALID_OUTPUT', '报表服务没有返回有效文件。')
+  }
+  const strFormat = fnNormalizeReportOutputFormat(
+    objInput.strFormat ?? '',
+    'INVALID_OUTPUT'
+  )
+  if (strExpectedFormat && strExpectedFormat !== strFormat) {
+    throw new ReportingError(
+      'INVALID_OUTPUT',
+      '报表服务返回的文件格式与请求不一致。'
+    )
+  }
+  const strMimeType = fnNormalizeRequiredText(
+    objInput.strMimeType ?? '',
+    'strMimeType',
+    nMaxIdentifierLength,
+    'INVALID_OUTPUT'
+  )
+  if (strMimeType !== objMimeTypeByFormat[strFormat]) {
+    throw new ReportingError(
+      'INVALID_OUTPUT',
+      '报表文件 MIME 与输出格式不一致。'
+    )
+  }
+  const strSanitizedFileName = fnSanitizeFileName(
+    fnNormalizeRequiredText(
+      objInput.strFileName ?? '',
+      'strFileName',
+      nMaxTemplateNameLength,
+      'INVALID_OUTPUT'
+    )
+  )
+  const strFileName = strSanitizedFileName
+    .toLowerCase()
+    .endsWith(`.${strFormat}`)
+    ? strSanitizedFileName
+    : `${strSanitizedFileName}.${strFormat}`
+
+  return Object.freeze({
+    strFileId: fnNormalizeRequiredText(
+      objInput.strFileId ?? '',
+      'strFileId',
+      nMaxIdentifierLength,
+      'INVALID_OUTPUT'
+    ),
+    strFileName,
+    strFormat,
+    strMimeType,
+    strReportId: fnNormalizeRequiredText(
+      objInput.strReportId ?? '',
+      'strReportId',
+      nMaxIdentifierLength,
+      'INVALID_OUTPUT'
+    ),
+  })
+}
+
+function fnNormalizeProgress(
+  objProgress: IFileTransferProgress | undefined
+): IFileTransferProgress | undefined {
+  if (objProgress === undefined) return undefined
+  if (!objProgress || typeof objProgress !== 'object') {
+    throw new ReportingError('INVALID_TASK', '报表任务返回了无效进度。')
+  }
+  const { nLoadedBytes, nPercent, nTotalBytes, strMessage } = objProgress
+  const bHasInvalidBytes = [nLoadedBytes, nTotalBytes].some(
+    (nValue) => nValue !== undefined && (!Number.isFinite(nValue) || nValue < 0)
+  )
+  if (
+    bHasInvalidBytes ||
+    (nPercent !== undefined &&
+      (!Number.isFinite(nPercent) || nPercent < 0 || nPercent > 100)) ||
+    (strMessage !== undefined &&
+      (typeof strMessage !== 'string' ||
+        strMessage.length > nMaxProgressMessageLength))
+  ) {
+    throw new ReportingError('INVALID_TASK', '报表任务返回了无效进度。')
+  }
+  return Object.freeze({ nLoadedBytes, nPercent, nTotalBytes, strMessage })
+}
+
+/** 将报表启动响应映射为统一文件任务结果。 */
+export function fnNormalizeReportGenerationStartResult(
+  objInput: TReportGenerationStartResultInput,
+  strExpectedFormat: TReportOutputFormat
+): TFileTaskStartResult<IReportOutput> {
+  if (!objInput || typeof objInput !== 'object') {
+    throw new ReportingError('INVALID_TASK', '报表服务返回了无效启动状态。')
+  }
+  if (objInput.strMode === 'completed') {
+    return {
+      objResult: fnNormalizeReportOutput(
+        objInput.objResult ?? {},
+        strExpectedFormat
+      ),
+      strMode: 'completed',
+    }
+  }
+  if (objInput.strMode === 'background') {
+    return {
+      strMode: 'background',
+      strTaskId: fnNormalizeRequiredText(
+        objInput.strTaskId ?? '',
+        'strTaskId',
+        nMaxIdentifierLength,
+        'INVALID_TASK'
+      ),
+    }
+  }
+  throw new ReportingError('INVALID_TASK', '报表服务返回了未知启动状态。')
+}
+
+/** 将报表轮询响应映射为统一文件任务结果。 */
+export function fnNormalizeReportGenerationPollResult(
+  objInput: TReportGenerationPollResultInput,
+  strExpectedFormat: TReportOutputFormat
+): TFileTaskPollResult<IReportOutput> {
+  if (!objInput || typeof objInput !== 'object') {
+    throw new ReportingError('INVALID_TASK', '报表服务返回了无效任务状态。')
+  }
+  if (objInput.strStatus === 'queued' || objInput.strStatus === 'running') {
+    return {
+      objProgress: fnNormalizeProgress(objInput.objProgress),
+      strStatus: objInput.strStatus,
+    }
+  }
+  if (objInput.strStatus === 'success') {
+    return {
+      objResult: fnNormalizeReportOutput(
+        objInput.objResult ?? {},
+        strExpectedFormat
+      ),
+      strStatus: 'success',
+    }
+  }
+  if (objInput.strStatus === 'error') {
+    const strSafeMessage =
+      objInput.strSafeMessage === undefined
+        ? '报表生成失败，请稍后重试。'
+        : fnNormalizeRequiredText(
+            objInput.strSafeMessage,
+            'strSafeMessage',
+            nMaxProgressMessageLength,
+            'INVALID_TASK'
+          )
+    const strReasonCode =
+      objInput.strReasonCode === undefined
+        ? undefined
+        : fnNormalizeRequiredText(
+            objInput.strReasonCode,
+            'strReasonCode',
+            nMaxIdentifierLength,
+            'INVALID_TASK'
+          )
+    return {
+      objError: new ReportingError(
+        'REPORT_FAILED',
+        strSafeMessage,
+        strReasonCode
+      ),
+      strStatus: 'error',
+    }
+  }
+  throw new ReportingError('INVALID_TASK', '报表服务返回了未知任务状态。')
+}

package/template/src/reporting/print.ts

@@ -0,0 +1,16 @@
+import { ReportingError } from './errors'
+
+/**
+ * 打印当前受控路由。
+ *
+ * 不接受 HTML 字符串或外部 URL，实际版式由 Feature 的 `@media print` 样式负责。
+ */
+export function fnPrintCurrentDocument() {
+  if (typeof window === 'undefined' || typeof window.print !== 'function') {
+    throw new ReportingError(
+      'PRINT_UNAVAILABLE',
+      '当前运行环境不支持浏览器打印。'
+    )
+  }
+  window.print()
+}

package/template/src/reporting/query.ts

@@ -0,0 +1,50 @@
+import { queryOptions, type QueryClient } from '@tanstack/react-query'
+import { fnCreateAppQueryKeys, type IAppQueryScope } from '@/api/query'
+import type { IReportTemplateCatalog, IReportTemplateSource } from './types'
+
+const strReportingFeatureKey = 'reporting'
+const strReportTemplateResourceKey = 'templates'
+const nReportTemplateStaleTimeMs = 5 * 60_000
+const nReportTemplateGcTimeMs = 30 * 60_000
+
+/** 返回当前身份作用域对应的模板目录 Query Key。 */
+export function fnReportTemplateQueryKey(objScope: IAppQueryScope) {
+  return fnCreateAppQueryKeys(strReportingFeatureKey, objScope).fnList(
+    strReportTemplateResourceKey
+  )
+}
+
+/** 创建当前身份作用域下的模板目录 Query 配置。 */
+export function fnReportTemplateQueryOptions(
+  objSource: IReportTemplateSource,
+  objScope: IAppQueryScope
+) {
+  return queryOptions({
+    gcTime: nReportTemplateGcTimeMs,
+    queryFn: ({ signal: objSignal }) =>
+      objSource.fnListTemplates({ objScope, objSignal }),
+    queryKey: fnReportTemplateQueryKey(objScope),
+    staleTime: nReportTemplateStaleTimeMs,
+  })
+}
+
+/** 使当前身份作用域下的模板目录失效。 */
+export function fnInvalidateReportTemplates(
+  objQueryClient: QueryClient,
+  objScope: IAppQueryScope
+) {
+  return objQueryClient.invalidateQueries({
+    exact: true,
+    queryKey: fnReportTemplateQueryKey(objScope),
+  })
+}
+
+/** 从 QueryClient 同步读取当前身份的模板目录。 */
+export function fnGetCachedReportTemplates(
+  objQueryClient: QueryClient,
+  objScope: IAppQueryScope
+): IReportTemplateCatalog | undefined {
+  return objQueryClient.getQueryData<IReportTemplateCatalog>(
+    fnReportTemplateQueryKey(objScope)
+  )
+}

package/template/src/reporting/react.ts

@@ -0,0 +1,17 @@
+import { useQuery } from '@tanstack/react-query'
+import { useAppQueryScope } from '@/api/query'
+import { fnReportTemplateQueryOptions } from './query'
+import type { IUseReportTemplatesOptions } from './types'
+
+/** 查询当前身份有权使用的报表模板目录。 */
+export function useReportTemplates({
+  bIsEnabled = true,
+  objSource,
+  strWorkspaceId,
+}: IUseReportTemplatesOptions) {
+  const objScope = useAppQueryScope({ strWorkspaceId })
+  return useQuery({
+    ...fnReportTemplateQueryOptions(objSource, objScope),
+    enabled: bIsEnabled,
+  })
+}

package/template/src/reporting/source.ts

@@ -0,0 +1,13 @@
+import { fnNormalizeReportTemplateCatalog } from './model'
+import type { IReportTemplateSource, TReportTemplateRequest } from './types'
+
+/** 使用 Swagger 生成客户端请求创建带运行时校验的模板目录数据源。 */
+export function fnCreateReportTemplateSource(
+  fnRequest: TReportTemplateRequest
+): IReportTemplateSource {
+  return {
+    async fnListTemplates(objContext) {
+      return fnNormalizeReportTemplateCatalog(await fnRequest(objContext))
+    },
+  }
+}

package/template/src/reporting/types.ts

@@ -0,0 +1,219 @@
+import type {
+  IFileTaskContext,
+  IFileTransferProgress,
+  IUseFileTaskResult,
+} from '@/files'
+import type { IAppQueryScope } from '@/api/query'
+
+/** 脚手架允许报表服务返回的文件格式。 */
+export type TReportOutputFormat = 'csv' | 'docx' | 'pdf' | 'xlsx'
+
+/** 报表、打印和模板边界的稳定错误码。 */
+export type TReportingErrorCode =
+  | 'INVALID_CATALOG'
+  | 'INVALID_OUTPUT'
+  | 'INVALID_REQUEST'
+  | 'INVALID_TASK'
+  | 'PRINT_UNAVAILABLE'
+  | 'REPORT_FAILED'
+
+/** Swagger Adapter 返回的单个报表模板原始元数据。 */
+export interface IReportTemplateInput {
+  /** 后端声明的输出格式；会在进入缓存前逐项校验。 */
+  arrFormats?: readonly string[]
+  /** 可直接作为纯文本展示的模板说明。 */
+  strDescription?: string
+  /** 后端授权返回的稳定模板 ID。 */
+  strTemplateId?: string
+  /** 可直接作为纯文本展示的模板名称。 */
+  strTemplateName?: string
+  /** 不可变模板版本；生成请求必须显式回传。 */
+  strTemplateVersion?: string
+}
+
+/** 经过校验、可供报表入口展示的模板元数据。 */
+export interface IReportTemplate {
+  /** 当前模板支持的输出格式，至少一项且不重复。 */
+  readonly arrFormats: readonly TReportOutputFormat[]
+  /** 后端授权返回的安全纯文本说明。 */
+  readonly strDescription?: string
+  /** 后端授权返回的稳定模板 ID。 */
+  readonly strTemplateId: string
+  /** 后端授权返回的安全纯文本名称。 */
+  readonly strTemplateName: string
+  /** 不可变模板版本。 */
+  readonly strTemplateVersion: string
+}
+
+/** Swagger Adapter 返回的模板目录原始数据。 */
+export interface IReportTemplateCatalogInput {
+  /** 当前用户有权使用的完整模板列表。 */
+  arrTemplates?: readonly IReportTemplateInput[]
+  /** 后端目录版本，用于诊断和主动失效。 */
+  strCatalogVersion?: string
+}
+
+/** 当前身份作用域下经过校验的模板目录。 */
+export interface IReportTemplateCatalog {
+  /** 当前用户有权使用的完整模板列表，最多 200 项。 */
+  readonly arrTemplates: readonly IReportTemplate[]
+  /** 后端目录版本。 */
+  readonly strCatalogVersion: string
+}
+
+/** 加载报表模板目录的安全请求上下文。 */
+export interface IReportTemplateRequestContext {
+  /** 当前用户、会话、租户、工作空间和语言组成的缓存作用域。 */
+  readonly objScope: IAppQueryScope
+  /** Query 取消、身份变化或路由卸载时触发的取消信号。 */
+  readonly objSignal: AbortSignal
+}
+
+/** 由 Swagger 生成客户端实现的模板目录请求。 */
+export type TReportTemplateRequest = (
+  objContext: IReportTemplateRequestContext
+) => Promise<IReportTemplateCatalogInput>
+
+/** 项目报表模板目录数据源。 */
+export interface IReportTemplateSource {
+  /** 加载后端已授权的模板目录并返回经过校验的结果。 */
+  readonly fnListTemplates: (
+    objContext: IReportTemplateRequestContext
+  ) => Promise<IReportTemplateCatalog>
+}
+
+/** 报表模板目录 Hook 的公共参数。 */
+export interface IUseReportTemplatesOptions {
+  /** 是否允许加载模板目录，默认启用。 */
+  readonly bIsEnabled?: boolean
+  /** 项目模板目录数据源。 */
+  readonly objSource: IReportTemplateSource
+  /** 跨工作空间报表 Feature 显式指定的工作空间 ID。 */
+  readonly strWorkspaceId?: string
+}
+
+/** 发起一次服务端报表生成所需的强类型输入。 */
+export interface IReportGenerationRequest<TParameters> {
+  /** 由具体 Swagger DTO 约束的模板参数，不由脚手架猜测字段。 */
+  readonly objParameters: TParameters
+  /** 期望生成的文件格式。 */
+  readonly strFormat: TReportOutputFormat
+  /** 当前选择的稳定模板 ID。 */
+  readonly strTemplateId: string
+  /** 目录返回的不可变模板版本。 */
+  readonly strTemplateVersion: string
+}
+
+/** Swagger Adapter 返回的报表文件原始身份。 */
+export interface IReportOutputInput {
+  /** 实际生成的文件格式。 */
+  strFormat?: string
+  /** 受保护下载接口使用的稳定文件 ID。 */
+  strFileId?: string
+  /** 后端建议的文件名；进入结果前会清理路径字符。 */
+  strFileName?: string
+  /** 与格式匹配的受支持 MIME。 */
+  strMimeType?: string
+  /** 本次报表生成的稳定结果 ID，用于审计和问题追踪。 */
+  strReportId?: string
+}
+
+/** 经过校验的报表文件身份，不包含 Blob 或任意外部 URL。 */
+export interface IReportOutput {
+  /** 实际生成且与请求一致的文件格式。 */
+  readonly strFormat: TReportOutputFormat
+  /** 受保护下载接口使用的稳定文件 ID。 */
+  readonly strFileId: string
+  /** 已清理的下载回退文件名。 */
+  readonly strFileName: string
+  /** 与文件格式严格匹配的 MIME。 */
+  readonly strMimeType: string
+  /** 本次报表生成的稳定结果 ID。 */
+  readonly strReportId: string
+}
+
+/** 报表服务启动生成后返回的原始状态。 */
+export type TReportGenerationStartResultInput =
+  | {
+      /** 请求内已经生成完成。 */
+      readonly strMode: 'completed'
+      /** 已生成文件的原始身份。 */
+      readonly objResult?: IReportOutputInput
+    }
+  | {
+      /** 服务端已创建后台任务。 */
+      readonly strMode: 'background'
+      /** 后端任务稳定 ID。 */
+      readonly strTaskId?: string
+    }
+
+/** 报表服务单次轮询返回的原始状态。 */
+export type TReportGenerationPollResultInput =
+  | {
+      /** 后台任务仍在排队或执行。 */
+      readonly strStatus: 'queued' | 'running'
+      /** 服务端最近一次安全进度。 */
+      readonly objProgress?: IFileTransferProgress
+    }
+  | {
+      /** 后台任务成功完成。 */
+      readonly strStatus: 'success'
+      /** 已生成文件的原始身份。 */
+      readonly objResult?: IReportOutputInput
+    }
+  | {
+      /** 后台任务以业务失败结束。 */
+      readonly strStatus: 'error'
+      /** 稳定、非敏感的后端原因码。 */
+      readonly strReasonCode?: string
+      /** 可直接展示的安全失败说明。 */
+      readonly strSafeMessage?: string
+    }
+
+/** 启动报表生成时交给项目 Adapter 的上下文。 */
+export interface IReportGenerationStartContext<
+  TParameters,
+> extends IFileTaskContext {
+  /** 经过校验的模板、版本、格式和强类型业务参数。 */
+  readonly objRequest: IReportGenerationRequest<TParameters>
+  /** 当前用户、会话、租户、工作空间和语言组成的作用域。 */
+  readonly objScope: IAppQueryScope
+}
+
+/** 轮询后台报表任务时交给项目 Adapter 的上下文。 */
+export interface IReportGenerationPollContext extends IFileTaskContext {
+  /** 当前用户、会话、租户、工作空间和语言组成的作用域。 */
+  readonly objScope: IAppQueryScope
+  /** 启动阶段请求的文件格式。 */
+  readonly strExpectedFormat: TReportOutputFormat
+  /** 后端任务稳定 ID。 */
+  readonly strTaskId: string
+}
+
+/** 项目使用 Swagger 生成客户端实现的报表生成数据源。 */
+export interface IReportGenerationSource<TParameters> {
+  /** 启动同步或后台报表生成。 */
+  readonly fnStartReport: (
+    objContext: IReportGenerationStartContext<TParameters>
+  ) => Promise<TReportGenerationStartResultInput>
+  /** 查询后台报表任务；只支持同步生成的项目可以省略。 */
+  readonly fnPollReport?: (
+    objContext: IReportGenerationPollContext
+  ) => Promise<TReportGenerationPollResultInput>
+}
+
+/** 服务端报表生成 Hook 的公共参数。 */
+export interface IUseReportGenerationOptions<TParameters> {
+  /** 后台任务轮询间隔，默认沿用文件任务策略。 */
+  readonly nPollIntervalMs?: number
+  /** 项目报表生成数据源。 */
+  readonly objSource: IReportGenerationSource<TParameters>
+  /** 跨工作空间报表 Feature 显式指定的工作空间 ID。 */
+  readonly strWorkspaceId?: string
+}
+
+/** 报表生成 Hook 的标准任务结果。 */
+export type TUseReportGenerationResult<TParameters> = IUseFileTaskResult<
+  IReportGenerationRequest<TParameters>,
+  IReportOutput
+>