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

package/template/src/auditLogs/query.ts

@@ -0,0 +1,113 @@
+import { queryOptions, type QueryClient } from '@tanstack/react-query'
+import {
+  fnCreateAppQueryKeys,
+  type IAppQueryScope,
+  type TAppQueryParameters,
+} from '@/api/query'
+import { fnNormalizeAuditLogFilter } from './model'
+import type { IAuditLogFilter, IAuditLogPage, IAuditLogSource } from './types'
+
+const strAuditLogFeatureKey = 'auditLogs'
+const strAuditLogResourceKey = 'entries'
+const nAuditLogListStaleTimeMs = 15_000
+const nAuditLogDetailStaleTimeMs = 30_000
+const nAuditLogGcTimeMs = 5 * 60_000
+
+function fnCreateAuditLogQueryParameters(
+  objFilter: ReturnType<typeof fnNormalizeAuditLogFilter>
+): TAppQueryParameters {
+  const objParameters: Record<string, boolean | number | string | null> = {
+    nPageSize: objFilter.nPageSize,
+  }
+  Object.entries(objFilter).forEach(([strKey, objValue]) => {
+    if (objValue !== undefined) objParameters[strKey] = objValue
+  })
+  return Object.freeze(objParameters)
+}
+
+/** 返回当前身份与筛选条件对应的精确审计列表 Key。 */
+export function fnAuditLogListQueryKey(
+  objScope: IAppQueryScope,
+  objFilter: IAuditLogFilter
+) {
+  const objNormalizedFilter = fnNormalizeAuditLogFilter(objFilter)
+  return fnCreateAppQueryKeys(strAuditLogFeatureKey, objScope).fnList(
+    strAuditLogResourceKey,
+    fnCreateAuditLogQueryParameters(objNormalizedFilter)
+  )
+}
+
+/** 返回当前身份与审计事实 ID 对应的精确详情 Key。 */
+export function fnAuditLogDetailQueryKey(
+  objScope: IAppQueryScope,
+  strAuditLogId: string
+) {
+  return fnCreateAppQueryKeys(strAuditLogFeatureKey, objScope).fnDetail(
+    strAuditLogResourceKey,
+    strAuditLogId
+  )
+}
+
+/** 创建当前身份作用域下的审计列表 Query 配置。 */
+export function fnAuditLogListQueryOptions(
+  objSource: IAuditLogSource,
+  objScope: IAppQueryScope,
+  objFilter: IAuditLogFilter
+) {
+  const objNormalizedFilter = fnNormalizeAuditLogFilter(objFilter)
+  return queryOptions({
+    gcTime: nAuditLogGcTimeMs,
+    queryFn: ({ signal: objSignal }) =>
+      objSource.fnList({
+        objFilter: objNormalizedFilter,
+        objScope,
+        objSignal,
+      }),
+    queryKey: fnAuditLogListQueryKey(objScope, objNormalizedFilter),
+    staleTime: nAuditLogListStaleTimeMs,
+  })
+}
+
+/** 创建当前身份作用域下的单个审计详情 Query 配置。 */
+export function fnAuditLogDetailQueryOptions(
+  objSource: IAuditLogSource,
+  objScope: IAppQueryScope,
+  strAuditLogId: string
+) {
+  return queryOptions({
+    gcTime: nAuditLogGcTimeMs,
+    queryFn: ({ signal: objSignal }) =>
+      objSource.fnGetDetail({ objScope, objSignal, strAuditLogId }),
+    queryKey: fnAuditLogDetailQueryKey(objScope, strAuditLogId),
+    staleTime: nAuditLogDetailStaleTimeMs,
+  })
+}
+
+/** 使当前身份作用域内的审计列表、详情或全部缓存失效。 */
+export function fnInvalidateAuditLogs(
+  objQueryClient: QueryClient,
+  objScope: IAppQueryScope,
+  strAuditLogId?: string
+) {
+  const objKeys = fnCreateAppQueryKeys(strAuditLogFeatureKey, objScope)
+  if (strAuditLogId) {
+    return objQueryClient.invalidateQueries({
+      exact: true,
+      queryKey: objKeys.fnDetail(strAuditLogResourceKey, strAuditLogId),
+    })
+  }
+  return objQueryClient.invalidateQueries({
+    queryKey: objKeys.fnResource(strAuditLogResourceKey),
+  })
+}
+
+/** 从 QueryClient 同步读取一个精确审计列表页。 */
+export function fnGetCachedAuditLogPage(
+  objQueryClient: QueryClient,
+  objScope: IAppQueryScope,
+  objFilter: IAuditLogFilter
+): IAuditLogPage | undefined {
+  return objQueryClient.getQueryData<IAuditLogPage>(
+    fnAuditLogListQueryKey(objScope, objFilter)
+  )
+}

package/template/src/auditLogs/react.ts

@@ -0,0 +1,36 @@
+import { useQuery } from '@tanstack/react-query'
+import { useAppQueryScope } from '@/api/query'
+import {
+  fnAuditLogDetailQueryOptions,
+  fnAuditLogListQueryOptions,
+} from './query'
+import type {
+  IUseAuditLogDetailOptions,
+  IUseAuditLogListOptions,
+} from './types'
+
+/** 查询当前身份有权查看的审计列表；远端错误与权限错误保持可观察。 */
+export function useAuditLogList({
+  bIsEnabled = true,
+  objFilter = {},
+  objSource,
+}: IUseAuditLogListOptions) {
+  const objScope = useAppQueryScope()
+  return useQuery({
+    ...fnAuditLogListQueryOptions(objSource, objScope, objFilter),
+    enabled: bIsEnabled,
+  })
+}
+
+/** 查询一个后端已授权且已脱敏的审计详情。 */
+export function useAuditLogDetail({
+  bIsEnabled = true,
+  objSource,
+  strAuditLogId,
+}: IUseAuditLogDetailOptions) {
+  const objScope = useAppQueryScope()
+  return useQuery({
+    ...fnAuditLogDetailQueryOptions(objSource, objScope, strAuditLogId),
+    enabled: bIsEnabled,
+  })
+}

package/template/src/auditLogs/source.ts

@@ -0,0 +1,51 @@
+import { AuditLogError } from './errors'
+import {
+  fnNormalizeAuditLogDetail,
+  fnNormalizeAuditLogFilter,
+  fnNormalizeAuditLogPage,
+} from './model'
+import type {
+  IAuditLogDetailRequestContext,
+  IAuditLogListRequestContext,
+  IAuditLogSource,
+  IAuditLogSourceRequests,
+} from './types'
+
+function fnNormalizeAuditLogId(strAuditLogId: string) {
+  const strNormalizedId = strAuditLogId.trim()
+  if (!strNormalizedId || strNormalizedId.length > 200) {
+    throw new AuditLogError(
+      'INVALID_DETAIL',
+      '审计事实 ID 必须是长度不超过 200 的非空字符串。'
+    )
+  }
+  return strNormalizedId
+}
+
+/** 将 Swagger 生成客户端请求适配为已校验的审计列表与详情数据源。 */
+export function fnCreateAuditLogSource(
+  objRequests: IAuditLogSourceRequests
+): IAuditLogSource {
+  return Object.freeze({
+    fnGetDetail: async (objContext: IAuditLogDetailRequestContext) => {
+      const strAuditLogId = fnNormalizeAuditLogId(objContext.strAuditLogId)
+      const objDetail = fnNormalizeAuditLogDetail(
+        await objRequests.fnGetDetail({ ...objContext, strAuditLogId })
+      )
+      if (objDetail.objEntry.strAuditLogId !== strAuditLogId) {
+        throw new AuditLogError(
+          'INVALID_DETAIL',
+          '审计详情返回的事实 ID 与请求不一致。'
+        )
+      }
+      return objDetail
+    },
+    fnList: async (objContext: IAuditLogListRequestContext) =>
+      fnNormalizeAuditLogPage(
+        await objRequests.fnList({
+          ...objContext,
+          objFilter: fnNormalizeAuditLogFilter(objContext.objFilter),
+        })
+      ),
+  })
+}

package/template/src/auditLogs/types.ts

@@ -0,0 +1,357 @@
+import type {
+  IFileTaskContext,
+  IUseFileTaskResult,
+  TFileTaskPollResult,
+  TFileTaskStartResult,
+} from '@/files'
+import type { IAppQueryScope } from '@/api/query'
+
+/** 审计操作的权威执行结果。 */
+export type TAuditLogOutcome = 'denied' | 'failed' | 'succeeded'
+
+/** 审计操作者的稳定类别。 */
+export type TAuditLogActorType = 'service' | 'system' | 'user'
+
+/** 后端已处理的字段展示级别。 */
+export type TAuditLogDisplayMode = 'masked' | 'plain' | 'redacted'
+
+/** 审计导出的受支持格式。 */
+export type TAuditLogExportFormat = 'csv' | 'xlsx'
+
+/** 审计能力边界的稳定错误分类。 */
+export type TAuditLogErrorCode =
+  | 'INVALID_DETAIL'
+  | 'INVALID_ENTRY'
+  | 'INVALID_EXPORT_RESULT'
+  | 'INVALID_FILTER'
+  | 'INVALID_PAGE'
+
+/** 审计列表允许提交给后端的筛选条件。 */
+export interface IAuditLogFilter {
+  /** 精确操作者稳定 ID。 */
+  readonly strActorId?: string
+  /** 精确操作码，例如 `order.approve`。 */
+  readonly strAction?: string
+  /** 游标分页中由后端返回的不透明下一页游标。 */
+  readonly strCursor?: string
+  /** 查询结束 ISO 8601 时间，包含边界。 */
+  readonly strEndedAt?: string
+  /** 权威执行结果。 */
+  readonly strOutcome?: TAuditLogOutcome
+  /** API 请求关联 ID，用于从错误提示追溯审计事实。 */
+  readonly strRequestId?: string
+  /** 查询开始 ISO 8601 时间，包含边界。 */
+  readonly strStartedAt?: string
+  /** 精确业务对象稳定 ID。 */
+  readonly strTargetId?: string
+  /** 精确业务对象类型，例如 `order`。 */
+  readonly strTargetType?: string
+  /** 具备跨租户审计权限时由后端重新授权的目标租户 ID。 */
+  readonly strTenantId?: string
+  /** 具备跨空间审计权限时由后端重新授权的工作空间 ID。 */
+  readonly strWorkspaceId?: string
+  /** 单页条数，默认 50，最大 100。 */
+  readonly nPageSize?: number
+}
+
+/** 不包含分页游标和单页条数的审计导出筛选。 */
+export type TAuditLogExportFilter = Omit<
+  IAuditLogFilter,
+  'nPageSize' | 'strCursor'
+>
+
+/** Swagger Adapter 返回的审计列表单项原始数据。 */
+export interface IAuditLogEntryInput {
+  /** 操作者稳定 ID；系统匿名动作可以省略。 */
+  strActorId?: string
+  /** 后端已授权返回且可直接作为纯文本显示的操作者名称。 */
+  strActorLabel?: string
+  /** 操作者类别。 */
+  strActorType?: string
+  /** 跨系统稳定的操作码。 */
+  strAction?: string
+  /** 审计事实稳定唯一 ID。 */
+  strAuditLogId?: string
+  /** 后端已脱敏的来源 IP 展示值。 */
+  strMaskedIpAddress?: string
+  /** 审计事实发生的 ISO 8601 时间。 */
+  strOccurredAt?: string
+  /** 权威执行结果。 */
+  strOutcome?: string
+  /** API 请求关联 ID。 */
+  strRequestId?: string
+  /** 后端生成且可直接作为纯文本显示的安全摘要。 */
+  strSummary?: string
+  /** 业务对象稳定 ID。 */
+  strTargetId?: string
+  /** 后端已授权返回的业务对象展示名称。 */
+  strTargetLabel?: string
+  /** 业务对象类型。 */
+  strTargetType?: string
+  /** 该事实所属租户稳定 ID。 */
+  strTenantId?: string
+  /** 该事实所属工作空间稳定 ID。 */
+  strWorkspaceId?: string
+}
+
+/** 经过运行时校验、可供列表展示的审计事实摘要。 */
+export interface IAuditLogEntry {
+  /** 操作者稳定 ID；系统匿名动作可以省略。 */
+  readonly strActorId?: string
+  /** 后端已授权返回的操作者纯文本名称。 */
+  readonly strActorLabel?: string
+  /** 操作者类别。 */
+  readonly strActorType: TAuditLogActorType
+  /** 跨系统稳定的操作码。 */
+  readonly strAction: string
+  /** 审计事实稳定唯一 ID。 */
+  readonly strAuditLogId: string
+  /** 后端已脱敏的来源 IP 展示值。 */
+  readonly strMaskedIpAddress?: string
+  /** 审计事实发生的标准 ISO 8601 时间。 */
+  readonly strOccurredAt: string
+  /** 权威执行结果。 */
+  readonly strOutcome: TAuditLogOutcome
+  /** API 请求关联 ID。 */
+  readonly strRequestId?: string
+  /** 后端生成的安全纯文本摘要。 */
+  readonly strSummary: string
+  /** 业务对象稳定 ID。 */
+  readonly strTargetId?: string
+  /** 后端已授权返回的业务对象纯文本名称。 */
+  readonly strTargetLabel?: string
+  /** 业务对象类型。 */
+  readonly strTargetType?: string
+  /** 该事实所属租户稳定 ID。 */
+  readonly strTenantId?: string
+  /** 该事实所属工作空间稳定 ID。 */
+  readonly strWorkspaceId?: string
+}
+
+/** Swagger Adapter 返回的单个变更字段原始数据。 */
+export interface IAuditLogChangeInput {
+  /** 后端已脱敏的变更后展示值。 */
+  strAfterDisplayValue?: string
+  /** 后端已脱敏的变更前展示值。 */
+  strBeforeDisplayValue?: string
+  /** 字段展示级别。 */
+  strDisplayMode?: string
+  /** 稳定字段 Key。 */
+  strField?: string
+  /** 后端可直接作为纯文本显示的字段名称。 */
+  strFieldLabel?: string
+}
+
+/** 经过校验且仅包含后端安全展示值的审计变更字段。 */
+export interface IAuditLogChange {
+  /** 后端已脱敏的变更后展示值。 */
+  readonly strAfterDisplayValue?: string
+  /** 后端已脱敏的变更前展示值。 */
+  readonly strBeforeDisplayValue?: string
+  /** 字段展示级别；`plain` 仍必须由后端确认可见。 */
+  readonly strDisplayMode: TAuditLogDisplayMode
+  /** 稳定字段 Key。 */
+  readonly strField: string
+  /** 后端可直接作为纯文本显示的字段名称。 */
+  readonly strFieldLabel: string
+}
+
+/** Swagger Adapter 返回的审计安全上下文字段。 */
+export interface IAuditLogContextFieldInput {
+  /** 字段展示级别。 */
+  strDisplayMode?: string
+  /** 稳定上下文 Key。 */
+  strKey?: string
+  /** 后端可直接作为纯文本显示的字段名称。 */
+  strLabel?: string
+  /** 后端已脱敏且可直接作为纯文本显示的值。 */
+  strDisplayValue?: string
+}
+
+/** 审计详情中的受限安全上下文字段。 */
+export interface IAuditLogContextField {
+  /** 字段展示级别；不允许携带原始请求体或任意嵌套对象。 */
+  readonly strDisplayMode: TAuditLogDisplayMode
+  /** 后端已脱敏且可直接作为纯文本显示的值。 */
+  readonly strDisplayValue: string
+  /** 稳定上下文 Key。 */
+  readonly strKey: string
+  /** 后端可直接作为纯文本显示的字段名称。 */
+  readonly strLabel: string
+}
+
+/** Swagger Adapter 返回的审计详情原始数据。 */
+export interface IAuditLogDetailInput {
+  /** 已脱敏的字段变更集合。 */
+  arrChanges?: readonly IAuditLogChangeInput[]
+  /** 受限的安全上下文字段集合。 */
+  arrContextFields?: readonly IAuditLogContextFieldInput[]
+  /** 详情对应的列表摘要。 */
+  objEntry?: IAuditLogEntryInput
+}
+
+/** 审计详情，不包含原始请求体、凭据或任意 JSON。 */
+export interface IAuditLogDetail {
+  /** 已脱敏的字段变更集合，最多 100 项。 */
+  readonly arrChanges: readonly IAuditLogChange[]
+  /** 受限安全上下文字段集合，最多 50 项。 */
+  readonly arrContextFields: readonly IAuditLogContextField[]
+  /** 详情对应的权威审计摘要。 */
+  readonly objEntry: IAuditLogEntry
+}
+
+/** Swagger Adapter 返回的游标分页原始数据。 */
+export interface IAuditLogPageInput {
+  /** 当前页审计摘要。 */
+  arrEntries?: readonly IAuditLogEntryInput[]
+  /** 是否仍有更早的数据。 */
+  bHasMore?: boolean
+  /** 可选的后端估算或精确总数。 */
+  nTotal?: number
+  /** 下一页不透明游标；`bHasMore` 为真时必须存在。 */
+  strNextCursor?: string
+}
+
+/** 经过校验、按时间倒序排列的审计列表页。 */
+export interface IAuditLogPage {
+  /** 当前页审计摘要，最多 100 项。 */
+  readonly arrEntries: readonly IAuditLogEntry[]
+  /** 是否仍有更早的数据。 */
+  readonly bHasMore: boolean
+  /** 可选的后端估算或精确总数。 */
+  readonly nTotal?: number
+  /** 下一页不透明游标。 */
+  readonly strNextCursor?: string
+}
+
+/** 审计列表请求的安全运行时上下文。 */
+export interface IAuditLogListRequestContext {
+  /** 已标准化的筛选与游标。 */
+  readonly objFilter: Readonly<
+    Required<Pick<IAuditLogFilter, 'nPageSize'>> & IAuditLogFilter
+  >
+  /** 当前用户、会话、租户、工作空间和语言组成的缓存作用域。 */
+  readonly objScope: IAppQueryScope
+  /** Query 取消或替换请求时触发的信号。 */
+  readonly objSignal: AbortSignal
+}
+
+/** 审计详情请求的安全运行时上下文。 */
+export interface IAuditLogDetailRequestContext {
+  /** 当前用户、会话、租户、工作空间和语言组成的缓存作用域。 */
+  readonly objScope: IAppQueryScope
+  /** Query 取消或替换请求时触发的信号。 */
+  readonly objSignal: AbortSignal
+  /** 需要读取的审计事实稳定 ID。 */
+  readonly strAuditLogId: string
+}
+
+/** 由 Swagger 生成客户端实现的审计列表请求。 */
+export type TAuditLogListRequest = (
+  objContext: IAuditLogListRequestContext
+) => Promise<IAuditLogPageInput>
+
+/** 由 Swagger 生成客户端实现的审计详情请求。 */
+export type TAuditLogDetailRequest = (
+  objContext: IAuditLogDetailRequestContext
+) => Promise<IAuditLogDetailInput>
+
+/** 项目审计后端的列表与详情数据源。 */
+export interface IAuditLogSource {
+  /** 加载后端已授权、已脱敏的审计列表页。 */
+  readonly fnList: (
+    objContext: IAuditLogListRequestContext
+  ) => Promise<IAuditLogPage>
+  /** 加载后端已授权、已脱敏的单个审计详情。 */
+  readonly fnGetDetail: (
+    objContext: IAuditLogDetailRequestContext
+  ) => Promise<IAuditLogDetail>
+}
+
+/** 创建审计数据源时注入的 Swagger 请求。 */
+export interface IAuditLogSourceRequests {
+  /** 审计详情生成客户端请求。 */
+  readonly fnGetDetail: TAuditLogDetailRequest
+  /** 审计列表生成客户端请求。 */
+  readonly fnList: TAuditLogListRequest
+}
+
+/** 审计列表 React Hook 的公共参数。 */
+export interface IUseAuditLogListOptions {
+  /** 是否允许发起请求，默认启用。 */
+  readonly bIsEnabled?: boolean
+  /** 列表筛选与游标。 */
+  readonly objFilter?: IAuditLogFilter
+  /** 项目审计后端数据源。 */
+  readonly objSource: IAuditLogSource
+}
+
+/** 审计详情 React Hook 的公共参数。 */
+export interface IUseAuditLogDetailOptions {
+  /** 是否允许发起请求，默认启用。 */
+  readonly bIsEnabled?: boolean
+  /** 项目审计后端数据源。 */
+  readonly objSource: IAuditLogSource
+  /** 需要读取的审计事实稳定 ID。 */
+  readonly strAuditLogId: string
+}
+
+/** 审计导出请求。 */
+export interface IAuditLogExportRequest {
+  /** 不包含分页游标的完整导出筛选。 */
+  readonly objFilter?: TAuditLogExportFilter
+  /** 受支持的导出格式。 */
+  readonly strFormat: TAuditLogExportFormat
+}
+
+/** 后端完成审计导出后返回的文件身份，不包含任意外部 URL。 */
+export interface IAuditLogExportResult {
+  /** 本次导出事实的稳定 ID，用于后续审计和问题追踪。 */
+  readonly strExportId: string
+  /** 由受保护下载接口使用的稳定文件 ID。 */
+  readonly strFileId: string
+  /** 已清理、可作为下载回退值的文件名。 */
+  readonly strFileName: string
+}
+
+/** 启动审计导出的安全上下文。 */
+export interface IAuditLogExportStartContext extends IFileTaskContext {
+  /** 已标准化的格式与筛选。 */
+  readonly objRequest: IAuditLogExportRequest
+  /** 当前用户、会话、租户、工作空间和语言组成的作用域。 */
+  readonly objScope: IAppQueryScope
+}
+
+/** 轮询审计导出任务的安全上下文。 */
+export interface IAuditLogExportPollContext extends IFileTaskContext {
+  /** 当前用户、会话、租户、工作空间和语言组成的作用域。 */
+  readonly objScope: IAppQueryScope
+  /** 服务端任务稳定 ID。 */
+  readonly strTaskId: string
+}
+
+/** 项目使用 Swagger 生成客户端实现的审计导出数据源。 */
+export interface IAuditLogExportSource {
+  /** 启动同步或后台导出；服务端必须限制时间范围、行数和字段。 */
+  readonly fnStartExport: (
+    objContext: IAuditLogExportStartContext
+  ) => Promise<TFileTaskStartResult<IAuditLogExportResult>>
+  /** 查询后台导出任务；同步完成的项目可以省略。 */
+  readonly fnPollExport?: (
+    objContext: IAuditLogExportPollContext
+  ) => Promise<TFileTaskPollResult<IAuditLogExportResult>>
+}
+
+/** 审计导出 Hook 的公共参数。 */
+export interface IUseAuditLogExportOptions {
+  /** 后台任务轮询间隔，默认沿用文件任务策略。 */
+  readonly nPollIntervalMs?: number
+  /** 项目审计导出数据源。 */
+  readonly objSource: IAuditLogExportSource
+}
+
+/** 审计导出 Hook 的标准任务结果。 */
+export type TUseAuditLogExportResult = IUseFileTaskResult<
+  IAuditLogExportRequest,
+  IAuditLogExportResult
+>